> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedatacity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batching & company-number sets

> Send many companies in one request. For very large lists, upload a set once and reference it by ID.

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

```bash theme={null}
# 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:

```json theme={null}
{
  "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

```bash theme={null}
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:

```bash theme={null}
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](/api-reference/guides/errors) for the wider envelope and [Rate limits](/api-reference/guides/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`                     |

<Snippet file="need-help.mdx" />