Bulk Operations

Batch sizing

The bulk endpoints accept an array of records under a data key. There's no fixed cap on the number of records per request: the practical ceiling is the request body size, so very large payloads are rejected. Because batches are atomic (see below), the real question when picking a batch size is blast radius, not a maximum:

Batches are atomic: one bad record fails the entire batch, so a single duplicate email takes down every other record in the same request. The larger the batch, the more work a single bad record rolls back.

Import order

Always import in this order so foreign keys resolve:

1. Companies: no dependencies
2. People: can reference company_id
3. Deals: can reference company_id
4. Associations: link people to deals
5. Transcripts: link to meetings and people

Rate limiting

The API allows 3,000 requests per minute, per workspace, per endpoint. Bulk endpoints help you stay under it: one request with many records counts as a single request. We recommend:

• A short delay between batches to smooth out bursts
• Back off on 429 responses, honoring the Retry-After header

See rate limits for the response headers and a backoff example.

Common errors