List onboarded companies

Retrieve the companies available to the workspace resolved from the caller's API key. Use this endpoint to obtain the company identifier required by the branch and document-count APIs.

Endpoint

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

This is a read-only endpoint. Results are scoped to the authenticated workspace and returned with pagination metadata.

Headers

Header	Required	Description
`X-API-Key`	Yes	Authenticates the caller and resolves its workspace and permissions.
`Accept`	No	Use `application/json`.

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

Query parameters

Parameter	Type	Required	Validation and meaning
`page`	integer	No	Page number starting at `1`. Defaults to `1`.
`limit`	integer	No	Companies per page from `1` to `100`. Defaults to `10`.
`countryCode`	string	No	Filter by country code, such as `AE`.
`sourceVersion`	string	No	Filter by source version.
`status`	string	No	`active` or `inactive`.
`search`	string	No	Case-insensitive search across company and source identity fields.

Request example

curl --get 'https://prod.gets.complyance.io/v3/connect/companies' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --data-urlencode 'countryCode=AE' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=100'

Success response

Status: 200 OK

{
  "success": true,
  "data": [
    {
      "companyId": "66b9f0a1c2d3e4f567890123",
      "sourceName": "accounting-platform",
      "sourceVersion": "2.1",
      "legalName": "Example UAE Entity",
      "legalIdentifier": null,
      "countryCode": "AE",
      "status": "active",
      "onboardingStatus": "onboarded",
      "peppolId": "0235:1234567890",
      "sourceId": "01JABCDEF1234567890SOURCE",
      "branchId": "66b9f0a1c2d3e4f567890456",
      "branchName": "Main",
      "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"
    }
  }
}

Each item in data represents one branch and its source configuration. A company with multiple branches therefore appears in multiple items with the same companyId and different branch-level fields.

Response fields

Field	Type	Description
`companyId`	string	Opaque company identifier. Repeated for each branch belonging to the company.
`sourceName`	string	Name of the source configured for the branch.
`sourceVersion`	string	Version of the branch source.
`legalName`	string	Registered company name.
`legalIdentifier`	string or null	Legal identifier when available.
`countryCode`	string	Company country code.
`status`	string	Company status, such as `active` or `inactive`.
`onboardingStatus`	string	Company onboarding status.
`peppolId`	string or null	Peppol participant ID associated with the company, when available.
`sourceId`	string	Identifier of the source configured for this branch.
`branchId`	string	Internal branch identifier.
`branchName`	string	Branch display name.
`tin`	string or null	Company tax identification number, when available.
`vatTrn`	string or null	Company VAT tax registration number, when available.
`mappingReadiness`	object	Mapping state for this branch. A ready mapping includes `templateId`; an incomplete mapping includes an action-required `code`.
`readyForInvoicing`	boolean	Whether this branch is ready to submit invoices.
`createdAt`	string	Company creation time in ISO 8601 format.
`updatedAt`	string	Company update time in ISO 8601 format.

Use `companyId`

The same opaque company identifier is returned as companyId by company onboarding, branch creation, and document-count endpoints.

For the example response:

data[0].companyId = 66b9f0a1c2d3e4f567890123

Use this value in endpoints such as:

POST /v3/connect/companies/66b9f0a1c2d3e4f567890123/branches/bulk
GET /v3/connect/invoices/counts?countryCode=AE&companyId=66b9f0a1c2d3e4f567890123

Treat the identifier as an opaque string. Do not derive it from the TIN, source ID, branch ID, Peppol participant ID, or workspace ID.

Pagination

Pagination is applied to companies before their branches are expanded into data. Use meta.pagination.total to determine the number of matching companies, hasMore to determine whether another page exists, and increment page until all pages have been retrieved. Because every branch becomes a separate item, data.length can be greater than meta.pagination.limit. The maximum supported limit is 100.

An empty result is successful:

{
  "success": true,
  "data": [],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 0,
      "totalPages": 0,
      "hasMore": false
    }
  }
}

Errors

Errors use the standard Connect API v3 error envelope.

HTTP status	Condition
`400`	A query parameter is malformed or outside its allowed range.
`401`	The API key is missing or invalid.
`403`	The caller cannot access Connect APIs for the resolved workspace.
`429`	The workspace exceeded its request limit. Honor `Retry-After`.
`500` / `503`	A required service is unavailable. Retain `meta.requestId` for support.

Next step: Use a returned data[].companyId when adding branches or retrieving document counts.