Companies and branches

Authentication

Use https://prod.gets.complyance.io with X-API-Key. JSON requests require Content-Type: application/json.

Create a UAE company

http

POST /v3/connect/companies

Complete the UAE prerequisites first.

Body field	Type	Required	Description
`sourceName`	string	Yes	Non-empty source name, unique together with its version in the workspace
`sourceVersion`	string	Yes	Non-empty source version
`countryCode`	string	Yes	`AE`
`tin`	string	Yes	UAE tax identification number; exactly 10 digits
`contactPersonEmail`	string	Yes	The email the company’s authorization for its accredited service provider (ASP), the provider that exchanges its e-invoices, was registered with; see UAE prerequisites
`contactPersonName`	string	No	Contact’s name
`contactPersonMobile`	string	No	Digits with an optional leading `+`; no spaces
`branchName`	string	Yes	Name of the first branch
`platformEnvironment`	string	Yes	`sandbox`, `simulation` or `production`

Unknown fields are rejected. Do not send company, source, branch or Peppol identifiers; successful onboarding returns them.

Example request body — replace the sample identityjson

{
  "sourceName": "acme-dubai",
  "sourceVersion": "v1",
  "countryCode": "AE",
  "tin": "1234567890",
  "contactPersonEmail": "finance@example.com",
  "contactPersonName": "Alex Morgan",
  "branchName": "Dubai",
  "platformEnvironment": "sandbox"
}

Response

HTTP 201 returns success: true, data and meta.

Example response with sample company details:

Company created — HTTP 201json

{
  "success": true,
  "data": {
    "companyId": "66b9f0a1c2d3e4f567890123",
    "sourceId": "01JABCDEF1234567890SOURCE",
    "branchId": "66b9f0b2c2d3e4f567890456",
    "peppolParticipantId": "0235:1234567890",
    "legalName": "Acme Trading LLC",
    "tin": "1234567890",
    "vatTrn": "123456789000003",
    "sourceName": "acme-dubai",
    "sourceVersion": "v1",
    "countryCode": "AE",
    "branchName": "Dubai",
    "contactPersonName": "Alex Morgan",
    "contactPersonEmail": "finance@example.com",
    "platformEnvironment": "sandbox",
    "userGivenBranchId": "acme-dubai",
    "readyForInvoicing": false,
    "mappingReadiness": {
      "status": "ACTION_REQUIRED",
      "code": "CONNECT_MAPPING_NOT_CONFIGURED"
    },
    "createdAt": "2026-08-01T12:00:00.000Z",
    "updatedAt": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-01T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}

Data field	Meaning
`companyId`, `sourceId`, `branchId`	Created company, source and first branch identifiers
`userGivenBranchId`	Buyer-owned branch reference to share with suppliers
`peppolParticipantId`	Company’s Peppol network identifier: `0235:` followed by the TIN. List companies returns the same value as `peppolId`.
`legalName`, `legalNameArabic`, `tin`, `vatTrn`	Registered company details
`sourceName`, `sourceVersion`, `countryCode`, `branchName`	Created source and branch details
`contactPersonName`, `contactPersonEmail`, `contactPersonMobile`	Contact details; optional inputs may be absent
`platformEnvironment`	Onboarding environment
`readyForInvoicing`	Whether this source is ready for invoice submission
`mappingReadiness`	`status` is `READY`, with the `templateId` in use, or `ACTION_REQUIRED`, with a `code` that says what to fix
`createdAt`, `updatedAt`	Timestamps

meta contains requestId, timestamp and workspaceId. Preserve the request identifier for support.

readyForInvoicing is true only when mappingReadiness.status is READY. A new company usually starts with ACTION_REQUIRED: CONNECT_MAPPING_INELIGIBLE until the default mapping’s test cases pass, or CONNECT_MAPPING_NOT_CONFIGURED when the workspace has no default mapping to assign: resolve mapping readiness before submitting.

List companies

http

GET /v3/connect/companies

Query	Default	Description
`page`	`1`	Page number, at least 1
`limit`	`10`	Companies per page, 1–100
`countryCode`	None	Country filter
`sourceVersion`	None	Exact source version
`status`	None	`active` or `inactive`
`search`	None	Search company sources

HTTP 200 returns data[] and pagination metadata. Results are ordered by most recently updated first; meta.sort says so. Use the returned companyId where requested.

Item field	Always returned	Description
`companyId`	Yes	The company’s identifier
`sourceName`, `sourceVersion`	Yes	The source this item describes
`legalName`	Yes	The company’s registered name
`legalIdentifier`	Yes	An identifier you can store for the company with `PATCH`, such as a licence number; `null` when none is set
`countryCode`	Yes	The company’s country
`status`	Yes	`active` or `inactive`
`onboardingStatus`	Yes	`onboarded`, or `draft` for a UAE company whose onboarding has not finished
`createdAt`, `updatedAt`	Yes	Timestamps
`peppolId`	No	The company’s Peppol ID, `0235:` followed by the TIN; the same value as `peppolParticipantId` when the company was created
`sourceId`, `branchId`, `branchName`	No	The branch this item describes
`tin`, `vatTrn`	No	The company’s TIN and VAT registration number (TRN)
`mappingReadiness`, `readyForInvoicing`	No	Whether the branch’s source can take invoices, as in the create response

The fields marked No appear for an onboarded UAE company.

A UAE company with several branches appears once per branch, so a page can hold more items than limit. meta.pagination.total counts companies, not items.

Company list — HTTP 200json

{
  "success": true,
  "data": [
    {
      "companyId": "66b9f0a1c2d3e4f567890123",
      "sourceName": "acme-dubai",
      "sourceVersion": "v1",
      "legalName": "Acme Trading LLC",
      "legalIdentifier": null,
      "countryCode": "AE",
      "status": "active",
      "onboardingStatus": "onboarded",
      "peppolId": "0235:1234567890",
      "sourceId": "01JABCDEF1234567890SOURCE",
      "branchId": "66b9f0a1c2d3e4f567890456",
      "branchName": "Dubai",
      "tin": "1234567890",
      "vatTrn": "123456789000003",
      "mappingReadiness": {
        "status": "READY",
        "templateId": "default-gets-66b9e000c2d3e4f567890000"
      },
      "readyForInvoicing": true,
      "createdAt": "2026-08-01T12:00:00.000Z",
      "updatedAt": "2026-08-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-01T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000",
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1,
      "hasMore": false
    },
    "filters": {
      "countryCode": "AE"
    },
    "sort": {
      "field": "updatedAt",
      "order": "desc"
    }
  }
}

Retrieve, update or archive a source

http

GET /v3/connect/companies/{sourceName}?sourceVersion=v1
PATCH /v3/connect/companies/{sourceName}?sourceVersion=v1
DELETE /v3/connect/companies/{sourceName}?sourceVersion=v1

URL-encode sourceName. Supply sourceVersion to identify the version explicitly.

GET retrieves one source. PATCH accepts optional sourceVersion, legalName, legalIdentifier, countryCode, status (active or inactive) and metadata (a JSON object). Send only fields you intend to change. Changing a source’s details is not a substitute for completing country onboarding.

DELETE archives the source rather than erasing its document history: its status becomes inactive and any scheduled credit allowance is cancelled. Check the source and version before archiving.

Source archived — HTTP 200json

{
  "success": true,
  "data": {
    "archived": true,
    "companyId": "66b9f0a1c2d3e4f567890123",
    "sourceName": "acme-dubai"
  },
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-01T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}

Add branches

http

POST /v3/connect/companies/{companyId}/branches

companyId is the 24-character identifier returned when the company was created or listed. The company must already be onboarded in the UAE. Each branch needs a non-empty branchName, sourceName and sourceVersion; unknown fields are rejected.

Add an Abu Dhabi branchjson

{
  "branchName": "Abu Dhabi",
  "sourceName": "acme-abu-dhabi",
  "sourceVersion": "v1"
}

HTTP 201 returns companyId, branchId, branchName, userGivenBranchId, sourceId, sourceName, sourceVersion, platformEnvironment, readyForInvoicing and optional mappingReadiness. The branch uses the company’s environment.

For 1–100 branches, use POST /v3/connect/companies/{companyId}/branches/bulk with a branches array of the same objects. It returns HTTP 200 once every branch has been processed, even when some failed:

Branches processed — HTTP 200json

{
  "success": true,
  "data": {
    "companyId": "66b9f0a1c2d3e4f567890123",
    "processed": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "branchName": "Abu Dhabi",
        "sourceName": "acme-abu-dhabi",
        "sourceVersion": "v1",
        "success": true,
        "data": { "branchId": "66b9f0c3c2d3e4f567890789", "userGivenBranchId": "acme-abu-dhabi" }
      },
      {
        "branchName": "Sharjah",
        "sourceName": "acme-sharjah",
        "sourceVersion": "v1",
        "success": false,
        "error": {
          "code": "CONNECT_SOURCE_ALREADY_EXISTS",
          "message": "Source 'acme-sharjah' (version v1) already exists in this workspace.",
          "retryable": false
        }
      }
    ]
  },
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-01T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}

A successful item’s data has the same fields as a single branch; it is shortened here. Inspect every item: a failed branch does not undo successful branches.

Errors

Condition	Action
`ASP_LINKAGE_NOT_FOUND`	Check that `tin` and `contactPersonEmail` match the company’s ASP authorization for this environment
`PEPPOL_PARTICIPANT_UNAVAILABLE`	Check that the ASP authorization registered the company with this `tin` in this `platformEnvironment`; if it did, email support@complyance.io with the request identifier
`CONNECT_COMPANY_ALREADY_EXISTS`	Recover the existing company instead of creating another
`CONNECT_SOURCE_ALREADY_EXISTS`	Use an unused source name/version for the new branch
`ONBOARDING_TIMEOUT`	List companies before retrying; creation may have completed

See error envelopes and recovery.