# Companies and branches

Create UAE companies, list company sources and add branches with Connect.

## 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](https://docs.complyance.io/partner-platform/isv/companies/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](https://docs.complyance.io/partner-platform/isv/companies/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.

```json title="Example request body — replace the sample identity"
{
  "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:

```json title="Company created — HTTP 201"
{
  "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](https://docs.complyance.io/api-reference/connect/companies/#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](https://docs.complyance.io/partner-platform/isv/mappings-and-payloads/) 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`](https://docs.complyance.io/api-reference/connect/companies/#retrieve-update-or-archive-a-source), 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](https://docs.complyance.io/api-reference/connect/companies/#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.

```json title="Company list — HTTP 200"
{
  "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.

```json title="Source archived — HTTP 200"
{
  "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.

```json title="Add an Abu Dhabi branch"
{
  "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:

```json title="Branches processed — HTTP 200"
{
  "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](https://docs.complyance.io/api-reference/connect/errors/).

Source: https://docs.complyance.io/api-reference/connect/companies/