API / Async & webhooks
Async & webhooks
Hand off a CV and receive the full result — markdown plus the 24-field candidate object — on your webhook. Best for bulk or fire-and-forget flows.
POST/v1/jobs
Submit a job 202
Send multipart/form-data. The response returns immediately with
instant_fields; the full result is delivered later.
| Field | Type | Notes | |
|---|---|---|---|
file | file | required | Same formats as /v1/parse. Max 20 MB, 60 pages. |
callback_url | string | required | Public HTTPS URL. Private/internal addresses are rejected. |
An accepted job is durable — it is queued before the 202 is
returned, so it is never lost.
Webhook delivery
When the job finishes, the full result is POSTed to your
callback_url:
{ "job_id": "...", "status": "done",
"markdown": "...", "candidate_data": { ... } }
- Delivery is at-least-once — deduplicate on
job_id. - Each request carries
X-Parse-Signature, an HMAC-SHA256 of the body — verify it. - Failed deliveries are retried with backoff.
- On failure, the payload is
{ "status": "failed", "error": "..." }.
Poll instead
If you'd rather pull the result:
GET/v1/jobs/{job_id}
GET/v1/jobs/{job_id}/result
Status moves pending → processing → done (or failed).
The result stays available for 7 days even if your webhook endpoint was down.