Key takeaways
- Use the single endpoint for interactive uploads and bulk jobs for backlogs; bulk accepts up to 10 files per job and returns 202 with a job id.
- Send an Idempotency-Key with every bulk submission so a retry never creates a duplicate job.
- Verify the webhook signature, then fetch the job; treat the webhook as a prompt to look, not as the only source of truth.
Two endpoints, two jobs#
POST /extract-sds takes one PDF and returns the record in the same response. Use it where a person is waiting, for example an upload form in an EHS application. POST /extract-sds/bulk takes up to 10 files, returns 202 with a job id straight away, and processes them in the background. Use it for imports and backlogs. Poll GET /extract-sds/bulk/{jobId} for status and per-file results.
Make submissions idempotent#
Networks fail after the request leaves and before the response arrives. If your client retries a bulk submission, you do not want two jobs and two charges. Send an Idempotency-Key header with a value you generate, such as a hash of the batch. A repeated submission with the same key returns the existing job instead of creating another.
Use webhooks, but verify them#
Add an HTTPS callback_url to the bulk request and the API calls it when the job finishes. The request is signed. Check the signature with your signing secret before you trust the body, and reject requests that fail or carry an old timestamp. The signing secret is shown on the Keys tab of the dashboard. Callback URLs must be public HTTPS addresses; internal and metadata addresses are refused.
A webhook can still be missed if your endpoint is down. Make the handler fetch the job by id and treat that as the source of truth, and keep a slow poll as a backstop. The webhook section of the docs has verification code in several languages.
Handle partial failure per file#
A job can finish with some files failed. Each item has its own status, error_code and error_message. Failed files are not billed, so a retry of only those files costs nothing extra. Resubmit them in a new job with a new idempotency key.
Route by confidence#
Do not push every record straight into your system of record. A simple rule works well: accept records with no warnings and a high confidence_score, and queue the rest for a person. That puts human effort on the documents that need it, which is the point of automating extraction.
Respect rate limits#
Per-key limits are 60 single requests and 10 bulk submissions per minute. A 429 response carries a Retry-After header in seconds. Back off for that long. For large backfills, use bulk jobs rather than many parallel single requests. Limits are best effort; your prepaid balance is the real spending control.
Frequently asked questions
How long are bulk results kept?
Bulk job results are kept for 7 days so you can collect them, then deleted automatically.
What happens to the charge if a file fails?
Failed extractions are not billed. Bulk jobs reserve credit for each file up front and refund the failed ones.