# Bulk onboard UAE companies

Onboard up to 500 companies in one Connect request and review each result. Every company must meet the UAE prerequisites before you submit the batch.

## Step 1: Prepare the rows

Use the fields from [single-company onboarding](https://docs.complyance.io/api-reference/connect/companies/#create-a-uae-company). Give every company an unused source name/version pair. Replace the example TIN and contact email with authorized company details.

```json title="Save as companies.json"
{
  "countryCode": "AE",
  "platformEnvironment": "sandbox",
  "rows": [
    {
      "sourceName": "acme-dubai",
      "sourceVersion": "v1",
      "countryCode": "AE",
      "tin": "1234567890",
      "contactPersonEmail": "finance@example.com",
      "contactPersonName": "Alex Morgan",
      "branchName": "Dubai",
      "platformEnvironment": "sandbox"
    }
  ]
}
```

Add up to 500 rows. The outer and row environments must agree. `filename` is an optional batch label; the API does not require a file upload.

## Step 2: Submit the batch

```bash title="Onboard the prepared companies"
curl --request POST \
  'https://prod.gets.complyance.io/v3/connect/companies/onboarding-jobs' \
  --header "X-API-Key: ${COMPLYANCE_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data @companies.json
```

This endpoint waits for the job to finish and returns HTTP `200` with the completed job and row results. Save `data.id`, the job identifier, and `meta.requestId`.

Example result for the single row above:

```json title="Completed onboarding job — HTTP 200"
{
  "success": true,
  "data": {
    "id": "01JEXAMPLEBULKJOB",
    "workspaceId": "66b9e000c2d3e4f567890000",
    "countryCode": "AE",
    "status": "completed",
    "totalRows": 1,
    "processedRows": 1,
    "succeededRows": 1,
    "failedRows": 0,
    "createdAt": "2026-08-25T10:00:00.000Z",
    "updatedAt": "2026-08-25T10:00:02.000Z",
    "completedAt": "2026-08-25T10:00:02.000Z",
    "rows": [
      {
        "id": "01JEXAMPLEROW1",
        "jobId": "01JEXAMPLEBULKJOB",
        "rowIndex": 0,
        "status": "onboarded",
        "sourceName": "acme-dubai",
        "sourceVersion": "v1",
        "countryCode": "AE",
        "nextAction": "onboarded",
        "data": {
          "companyId": "66b9f0a1c2d3e4f567890123",
          "sourceId": "01JEXAMPLESOURCE1",
          "branchId": "66b9f0b2c2d3e4f567890456",
          "sourceName": "acme-dubai",
          "sourceVersion": "v1",
          "readyForInvoicing": true,
          "mappingReadiness": {
            "status": "READY",
            "templateId": "default-gets-WORKSPACE_ID"
          }
        }
      }
    ]
  },
  "meta": {
    "requestId": "01JEXAMPLEREQUEST",
    "timestamp": "2026-08-25T10:00:02.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}
```

## Step 3: Review every result

Check `data.status`, `processedRows`, `succeededRows` and `failedRows`. Then read every entry in `data.rows[]`.

For an `onboarded` row, save the identifiers in its `data` and check `readyForInvoicing`. For a failed row, use `errorCode`, `errorMessage` and `nextAction` to correct it. An HTTP `200` does not mean every company succeeded.

## Step 4: Recover failed rows

Retain successful rows. Correct and resubmit only rows that did not onboard, after checking for an existing company when the outcome is uncertain.

To retrieve a saved job, use `GET /v3/connect/companies/onboarding-jobs/{jobId}` with the same `X-API-Key`. The job’s `/rows` endpoint retrieves its row results and `/errors.csv` returns the error report.

## If something goes wrong

**A prerequisite fails:** complete the affected company’s authorization before retrying that row.

**The request times out:** [list existing companies](https://docs.complyance.io/partner-platform/isv/companies/list/) before sending the batch again. Do not duplicate the successful rows.

Next, [review mapping readiness](https://docs.complyance.io/partner-platform/isv/mappings-and-payloads/) for the new sources.

Source: https://docs.complyance.io/partner-platform/isv/companies/bulk-onboarding/