Add multiple UAE branches

Add between 1 and 100 branches to one existing UAE company with a single request. Each branch receives its own source and reuses the onboarded company's verified identity and platform environment.

Endpoint

POST https://prod.gets.complyance.io/v3/connect/companies/{companyId}/branches/bulk

Use the 24-character data.companyId returned by POST /v3/connect/companies. The company must be active, belong to the workspace resolved from the API key, and use country code AE.

Headers

Header	Required	Description
`X-API-Key`	Yes	Authenticates the caller and resolves the workspace that owns the company.
`Content-Type`	Yes	`application/json`

Request body

Field	Type	Required	Validation and meaning
`branches`	array	Yes	Between 1 and 100 branch objects.
`branches[].branchName`	string	Yes	Non-empty branch display name.
`branches[].sourceName`	string	Yes	Non-empty source alias. The source name and version must be unique within the workspace.
`branches[].sourceVersion`	string	Yes	Non-empty source version.

Unknown top-level or branch fields return 400 CONNECT_VALIDATION_ERROR.

Request example

curl --request POST 'https://prod.gets.complyance.io/v3/connect/companies/66b9f0a1c2d3e4f567890123/branches/bulk' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "branches": [
      {
        "branchName": "Dubai Branch",
        "sourceName": "accounting-platform-dubai",
        "sourceVersion": "2.1"
      },
      {
        "branchName": "Abu Dhabi Branch",
        "sourceName": "accounting-platform-abu-dhabi",
        "sourceVersion": "2.1"
      },
      {
        "branchName": "Sharjah Branch",
        "sourceName": "accounting-platform-sharjah",
        "sourceVersion": "2.1"
      },
      {
        "branchName": "Ajman Branch",
        "sourceName": "accounting-platform-ajman",
        "sourceVersion": "2.1"
      },
      {
        "branchName": "Al Ain Branch",
        "sourceName": "accounting-platform-al-ain",
        "sourceVersion": "2.1"
      }
    ]
  }'

Success response

An accepted batch returns 200 OK. Every request item has a corresponding entry in data.results.

{
  "success": true,
  "data": {
    "companyId": "66b9f0a1c2d3e4f567890123",
    "processed": 2,
    "succeeded": 2,
    "failed": 0,
    "results": [
      {
        "branchName": "Dubai Branch",
        "sourceName": "accounting-platform-dubai",
        "sourceVersion": "2.1",
        "success": true,
        "data": {
          "companyId": "66b9f0a1c2d3e4f567890123",
          "branchId": "66b9f0b2c2d3e4f567890456",
          "branchName": "Dubai Branch",
          "sourceId": "01JABCDEF1234567890SOURCE",
          "sourceName": "accounting-platform-dubai",
          "sourceVersion": "2.1",
          "platformEnvironment": "sandbox",
          "readyForInvoicing": true
        }
      },
      {
        "branchName": "Abu Dhabi Branch",
        "sourceName": "accounting-platform-abu-dhabi",
        "sourceVersion": "2.1",
        "success": true,
        "data": {
          "companyId": "66b9f0a1c2d3e4f567890123",
          "branchId": "66b9f0b2c2d3e4f567890789",
          "branchName": "Abu Dhabi Branch",
          "sourceId": "01JABCDEF1234567890SECOND",
          "sourceName": "accounting-platform-abu-dhabi",
          "sourceVersion": "2.1",
          "platformEnvironment": "sandbox",
          "readyForInvoicing": true
        }
      }
    ]
  },
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-17T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}

Response fields

Field	Type	Description
`data.companyId`	string	Company that received every branch.
`data.processed`	number	Total branch items processed.
`data.succeeded`	number	Items that created a branch.
`data.failed`	number	Items that returned an item-level error.
`data.results`	array	One result for every request item, in request order.
`data.results[].success`	boolean	Whether that branch was created.
`data.results[].data`	object	Created branch and source details when `success` is `true`.
`data.results[].error`	object	Public error code, message, and retryability when `success` is `false`.

data.results[].data.mappingReadiness may also be returned when mapping readiness information is available.

Partial success

Branches are processed independently. A failure does not roll back successful branches, and an accepted mixed-result batch still returns 200 OK.

{
  "success": true,
  "data": {
    "companyId": "66b9f0a1c2d3e4f567890123",
    "processed": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "branchName": "Dubai Branch",
        "sourceName": "accounting-platform-dubai",
        "sourceVersion": "2.1",
        "success": true,
        "data": {
          "companyId": "66b9f0a1c2d3e4f567890123",
          "branchId": "66b9f0b2c2d3e4f567890456",
          "branchName": "Dubai Branch",
          "sourceId": "01JABCDEF1234567890SOURCE",
          "sourceName": "accounting-platform-dubai",
          "sourceVersion": "2.1",
          "platformEnvironment": "sandbox",
          "readyForInvoicing": true
        }
      },
      {
        "branchName": "Duplicate Branch",
        "sourceName": "existing-source",
        "sourceVersion": "2.1",
        "success": false,
        "error": {
          "code": "CONNECT_SOURCE_ALREADY_EXISTS",
          "message": "The branch source already exists.",
          "retryable": false
        }
      }
    ]
  },
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-17T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}

Inspect data.failed and every data.results[] entry before treating the batch as fully successful. Retry only failed branches after correcting their errors and confirming that they were not created.

Request-level errors

Request-level failures use the standard Connect API v3 error envelope and do not process any branches.

HTTP status	Code or condition	Description
`400`	`CONNECT_VALIDATION_ERROR`	The company ID or body is malformed, the array is outside the 1–100 limit, or an unknown field was supplied.
`400`	`CONNECT_UNSUPPORTED_COUNTRY`	The target company is not a UAE company.
`401`	Authentication failure	The API key is missing or invalid.
`403`	Access denied	The key cannot use the workspace or operation.
`404`	`CONNECT_COMPANY_NOT_FOUND`	No active company with that ID exists in the API key's workspace.
`429`	Rate limit	The workspace exceeded its request limit. Honor `Retry-After`.
`500`–`504`	Service or dependency failure	A required service failed or timed out. Use `error.retryable` and retain `meta.requestId`.

{
  "success": false,
  "error": {
    "code": "CONNECT_COMPANY_NOT_FOUND",
    "message": "Company not found.",
    "retryable": false
  },
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-17T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}

Next step: Retrieve document counts for the company.