Skip to main content

Submit CV + job description for asynchronous matching

POST 
/api/v1/cvdeepmatch/submit

Submits a CV (PDF) plus a job description and a requirements configuration. Returns 202 Accepted with an id. Poll GET /api/v1/cvdeepmatch/{id} for the current status, or wait for the webhook callback to fire.

Saved-job references​

Instead of sending job_description + config inline, you can reference a job saved in the Jobs catalog:

  • At least one of position_id / job_id is required. position_id is your own key; job_id is the platform id (jobs.id). When both are sent they must resolve to the same saved job (400 INVALID_INPUT otherwise); job_id wins for resolution.
  • job_description and config are both-or-neither. Send both to run with inline content (exactly as before), or neither to run with the referenced job's stored content. Sending exactly one returns 400 INVALID_INPUT — partial updates go through PATCH /api/v1/jobs/{jobId}, never the run endpoint.
  • A reference that resolves to no saved job for your client returns 400 JOB_NOT_FOUND.
  • saveJob: true saves the inline job_description + config to the catalog before running: an existing job under the reference is updated, otherwise a new one is created under position_id. A job_id alone can only update an existing job — it never creates one (400 INVALID_INPUT: use position_id to create).
  • Responses on the poll/list endpoints expose the run's job_id attribution (null for pure inline runs).

File requirements​

  • Format: PDF only at launch (application/pdf MIME + .pdf extension). DOCX returns INVALID_INPUT.
  • Magic-byte check: the uploaded bytes must start with a valid PDF header (%PDF-). Files that pass the extension/MIME gate but fail the magic-byte check return INVALID_FILE_CONTENT.
  • Max size: 5 MB.

Webhook URL requirements​

  • Must use https:// (plain HTTP returns INSECURE_WEBHOOK_URL).
  • Must NOT resolve to a private, loopback, or link-local address (returns PRIVATE_WEBHOOK_URL). The DNS resolution is re-checked immediately before each delivery attempt to defend against DNS-rebinding.

Idempotency​

Pass an idempotency_key to make the submit safe to retry. If the same key arrives within 24 h the existing id is returned with HTTP 200 and idempotent_replay: true instead of a fresh 202.

Required permission​

Client's permissions[] must contain cvdeepmatch. Without it the request returns 403 MISSING_PERMISSION.

Credits​

Each successful match deducts credits when the run completes. At submission time the available balance is checked — submits from clients with insufficient credits are rejected with 402 INSUFFICIENT_CREDITS.

Request​

Responses​

Idempotency replay — the supplied idempotency_key was seen within the last 24 h. The returned id is the original one; no new match is started.