Skip to main content

CvDeepMatchSubmitRequest

multipart/form-data body for POST /api/v1/cvdeepmatch/submit.

Beyond cv_file, two cross-field rules apply (EPIC-035 saved-job references):

  • at least one of position_id / job_id is required;
  • job_description and config are both-or-neither — both for an inline run, neither for a run that loads the referenced saved job's stored content. Exactly one returns 400 INVALID_INPUT.
cv_filebinaryrequired

PDF file (≤ 5 MB). The uploaded bytes must begin with a valid PDF magic header (%PDF-). Anything else returns INVALID_FILE_CONTENT.

position_idstring

Client-supplied job identifier. Charset [A-Za-z0-9._-], 1–28 chars. Used as the deterministic key into the matching pipeline's input contract, and — when it names a job saved in the Jobs catalog — as the saved-job reference. Optional when job_id is sent (at least one of the two is required).

Possible values: non-empty and <= 28 characters, Value must match regular expression ^[A-Za-z0-9._-]{1,28}$

Example: eng-backend-2026
job_idstring

Optional saved-job reference by the platform-assigned job id (jobs.id). An alternative to position_id — at least one of the two is required; when both are sent they must resolve to the same saved job, and job_id wins for resolution. An unresolvable reference (no inline content) returns 400 JOB_NOT_FOUND.

Possible values: <= 64 characters

Example: 6f0d5c2e-1b7a-4c3d-9e8f-2a1b3c4d5e6f
saveJobboolean

When true, saves the inline job_description + config to the Jobs catalog before running — updating the referenced job if it exists, else creating one under position_id (a job_id alone never creates). The save is validated with the strict save-time contract; on failure the submit returns 400 INVALID_INPUT with per-field detail, nothing is saved, and no run is started. Multipart string forms "true"/"1"/"false"/"0" are accepted; anything else is 400 INVALID_INPUT.

Default value: false
job_descriptionstring

Free-form text or a JSON-encoded JD body. Strings that parse as JSON objects are treated as the JD object verbatim; anything else is forwarded as text. Optional when a saved-job reference supplies the content — but always paired with config (both-or-neither).

configstring

JSON-encoded configuration object. Must contain requirements.workExperience and requirements.skills — the two keys the downstream matching pipeline requires. See the CvDeepMatchRequirements schema below for the full shape. See the Position config reference guide for a full, field-by-field explanation of the requirements config (the 1–5 importance scale, where each requirement belongs, education ON/OFF, and cardinality limits). Optional when a saved-job reference supplies the content — but always paired with job_description (both-or-neither).

webhook_urluri

Optional. HTTPS callback URL for result delivery. Omit it to use the API in poll-only mode — no callback is attempted and you retrieve the result via GET /api/v1/cvdeepmatch/{id} (see the async polling guide). When provided, it must be https:// and must NOT resolve to a private / loopback / link-local address; the DNS resolution is re-checked before each delivery attempt (DNS-rebinding defense).

Example: https://example.com/cvdeepmatch/callback
idempotency_keystring

Optional. If the same key is supplied within a 24 h window the existing id is returned (HTTP 200, idempotent_replay: true) instead of starting a new match.

Possible values: non-empty and <= 128 characters, Value must match regular expression ^[A-Za-z0-9._-]{1,128}$

metadatastring

Optional JSON object (stringified) of {key:value} correlation data attached to the run — for example your own candidate or customer identifiers. String keys to string/number/boolean values (≤ 50 keys, key ≤ 40 chars, value ≤ 500 chars, total ≤ 8 KB). Echoed back on every poll response and filterable. Invalid metadata returns 400 INVALID_INPUT.

Example: {"candidate_id":"c_887","customer":"acme"}
tagsstring

Optional JSON array of strings (stringified) attached to the run for your own correlation/filtering. Up to 20 distinct tags, each 1–40 chars (trimmed; duplicates removed). Echoed back on every poll response. Invalid tags return 400 INVALID_INPUT.

Example: ["batch-3","eu-region"]
CvDeepMatchSubmitRequest
{
  "cv_file": "string",
  "position_id": "eng-backend-2026",
  "job_id": "6f0d5c2e-1b7a-4c3d-9e8f-2a1b3c4d5e6f",
  "saveJob": false,
  "job_description": "string",
  "config": "string",
  "webhook_url": "https://example.com/cvdeepmatch/callback",
  "idempotency_key": "string",
  "metadata": "{\"candidate_id\":\"c_887\",\"customer\":\"acme\"}",
  "tags": "[\"batch-3\",\"eu-region\"]"
}