Batching & company-number sets

The API supports two patterns for working with many companies at once.

Batch endpoints

Several endpoints take an array of company identifiers in a single request:

Endpoint	Body shape	When to use
`POST /v2/companies/batch`	Array of CRNs	Up to a few thousand companies — fetch details in one call.
`POST /v2/companies/check`	Array of CRNs	Check which exist; lightweight existence check.
`POST /v2/companies/by-website/batch`	Array of URLs	Resolve many websites at once.

These are the preferred path for “I have a list of N items, give me data for all of them” workflows.

Company-number sets — for very large lists

Above roughly 10,000 CRNs (and certainly above 50,000), packing them inline into every POST /v2/companies request becomes wasteful: each call re-sends the same big JSON array. Instead, upload the list once as a set, get a setId, and reference it from filter requests.

Upload a set

# Plaintext body, one CRN per line, UTF-8.
curl -X POST 'https://product-api.thedatacity.com/api/v2/company-number-sets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: text/plain' \
  --data-binary $'12345678\n87654321\n11223344\n'

Response:

{
  "setId": "set_abc123",
  "count": 3,
  "expiresAt": "2026-05-19T10:23:00Z"
}

Sets expire after roughly 24 hours. Call DELETE /v2/company-number-sets/{setId} to remove one early.

Use a set in filter requests

curl -X POST 'https://product-api.thedatacity.com/api/v2/companies' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
        "returnCount": 1000,
        "CompanyNumberSetId": "set_abc123",
        "AllowLargeAnalysis": true
      }'

When CompanyNumberSetId is set, omit CompanyNumbers — the API ignores it and the JSON stays small.

Gzip the upload

For very large bodies, gzip the request body:

gzip -c crns.txt | curl -X POST 'https://product-api.thedatacity.com/api/v2/company-number-sets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: text/plain' \
  -H 'Content-Encoding: gzip' \
  --data-binary @-

Error shapes

HTTP	Meaning
`400`	Malformed body (empty, non-UTF-8, bad CRNs).
`429`	`TooManyConcurrentSets` or `TooManyCompanyNumbers`.

See Errors for the wider envelope and Rate limits for the throttle behaviour.

Picking the right path

Workload	Best path
< 1000 companies, one-off	Inline `CompanyNumbers` array
1000–10k companies, repeated calls	Inline `CompanyNumbers` array
10k–50k companies	Either inline or set (set is cheaper if you re-use it)
> 50k companies	Upload a set, reference by `setId`

​Batch endpoints

​Company-number sets — for very large lists

​Upload a set

​Use a set in filter requests

​Gzip the upload

​Error shapes

​Picking the right path