Onboard a UAE company

Create and synchronously onboard one UAE company in the workspace resolved from the caller's API key.

Endpoint

POST https://prod.gets.complyance.io/v3/connect/companies

A 201 Created response means the required synchronous onboarding work completed. There is no public onboarding-status endpoint, polling URL, or status lifecycle for this POST.

Before you call the endpoint

Complete the approved ASP/TIN authorization for the company's TIN in the same environment you will call. Follow the UAE onboarding prerequisite guide and wait for the confirmed readiness signal.

Complyance manages the associated Peppol participant. Do not create or send peppolParticipantId yourself. A missing or unavailable prerequisite returns 409 ASP_LINKAGE_NOT_FOUND or 409 PEPPOL_PARTICIPANT_UNAVAILABLE.

Headers

The API key resolves the workspace. Do not send workspaceId in the body.

Request body

The request contains company and source information only.

Unknown fields return 400. Send only the company and source fields listed above.

System-generated identifiers are rejected

Do not send companyId, sourceId, branchId, userGivenBranchId, peppolParticipantId, an internal onboarding identifier, or workspaceId. Supplying a system-managed identifier returns 400.

Request example

All company, contact, tax, and identifier values in the request and response examples are illustrative.

curl --request POST 'https://prod.gets.complyance.io/v3/connect/companies' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "sourceName": "accounting-platform",
    "sourceVersion": "2.1",
    "countryCode": "AE",
    "tin": "1234567890",
    "contactPersonEmail": "onboarding@example.com",
    "contactPersonName": "Amina Hassan",
    "branchName": "Main",
    "platformEnvironment": "sandbox"
  }'

Retries

Do not send concurrent create requests for the same company. Before retrying after a timeout or an uncertain dependency failure, use the Company List API to confirm whether the company was created. Retain meta.requestId for support.

Success response

Status: 201 Created

{
  "success": true,
  "data": {
    "companyId": "66b9f0a1c2d3e4f567890123",
    "sourceId": "01JABCDEF1234567890SOURCE",
    "branchId": "66b9f0b2c2d3e4f567890456",
    "peppolParticipantId": "0235:1234567890",
    "legalName": "Example UAE Entity",
    "legalNameArabic": "شركة الإمارات التجريبية",
    "tin": "1234567890",
    "vatTrn": "123456789000003",
    "sourceName": "accounting-platform",
    "sourceVersion": "2.1",
    "countryCode": "AE",
    "branchName": "Main",
    "contactPersonName": "Amina Hassan",
    "contactPersonEmail": "onboarding@example.com",
    "platformEnvironment": "sandbox",
    "readyForInvoicing": true,
    "mappingReadiness": {
      "status": "READY",
      "templateId": "default-gets-66b9e000c2d3e4f567890000"
    },
    "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"
  }
}

Response fields

Treat companyId, sourceId, branchId, and peppolParticipantId as opaque, system-generated values.

Invoicing readiness

readyForInvoicing reports whether invoice submission can start for the onboarded Source. For new ISV workspaces, automatic assignment is enabled by default and a successful assignment returns mappingReadiness.status: "READY".

When action is required, readyForInvoicing is false and the response returns one of:

See Default mapping and payload before retrying or manually changing assignments.

Duplicate behavior

A new request returns 409 CONNECT_COMPANY_ALREADY_EXISTS when the workspace already has the effective sourceName and sourceVersion or the same tin. The POST does not silently attach a new source alias to an existing company.

Recover the existing companyId from the stored onboarding response or the Company List API. Do not create another logical request for an existing company.

Error response

Onboarding errors contain error.code, error.message, and error.retryable. error.details is optional. meta.workspaceId appears only after safe workspace resolution.

{
  "success": false,
  "error": {
    "code": "STABLE_PUBLIC_CODE",
    "message": "Human-readable public message.",
    "details": null,
    "retryable": false
  },
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-15T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}

The exact public codes for other onboarding 400, 401, 403, and 429 conditions must be verified against the deployed gateway. See Errors and troubleshooting for remediation guidance.

Submit an invoice next

Use the exact sourceName:sourceVersion returned above with the complete payload and Unify V2. Follow the ISV UAE quickstart.

Use companyId for reporting

curl --get 'https://prod.gets.complyance.io/v3/connect/invoices/counts' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Environment: sandbox' \
  --header 'Accept: application/json' \
  --data-urlencode 'countryCode=AE' \
  --data-urlencode 'companyId=66b9f0a1c2d3e4f567890123'

Related pages

• UAE onboarding prerequisites
• ISV UAE quickstart
• Bulk onboard UAE companies
• Default mapping and payload
• List onboarded companies
• Get document counts
• Errors and troubleshooting

Next step: Download the payload and submit a sandbox invoice.