latestOpenAPI 3.1.0MIT2026-08-226224149.1 KB

613ceff68dc7

Bulk create records

Submit up to 1,000 records for asynchronous processing. Returns immediately with a bulk request ID. Each record is validated and inserted independently, so some records can succeed while others fail. Use the GET /bulk_requests/{id} endpoint to poll for results.

post/records/bulk

Headers

Idempotency-Keystring

Optional idempotency key. If a bulk request with this key already exists for your environment, the existing request is returned instead of creating a new one.

Request body

on_conflict'skip' | 'error'

How to handle records whose external_id already exists in the target stream. skip (default) silently skips duplicates and counts them in skipped_items. error surfaces duplicates as per-row failures. Only applies to records with external_id set.

Response

Bulk request accepted for processing

idinteger

Unique identifier for the bulk request

status'pending' | 'processing' | 'completed' | 'failed' | 'cancelled'

Current processing status

total_itemsinteger

Number of records submitted

processed_itemsinteger

Number of records processed so far

successful_itemsinteger

Number of records successfully created

failed_itemsinteger

Number of records that failed

skipped_itemsinteger

Number of records skipped due to on_conflict: skip matching an existing external_id

urlstring

Polling URL to check progress (e.g. /v1/bulk_requests/123)