Skip to main content

CvDeepMatchSubmitRequest

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

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_idstringrequired

Client-supplied job identifier. Charset [A-Za-z0-9._-], 1–28 chars. Used as the deterministic key into the AWS Step Functions input contract.

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

Example: eng-backend-2026
job_descriptionstringrequired

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.

configstringrequired

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).

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_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\"]"
}