Ingestion Semantics

Both Resume imports and Job Match candidate uploads share one ingestion pipeline. Understanding it explains the validation errors and the dedup behavior you'll see.

File vs URL

Every document can be supplied two ways:

• Multipart file — send the bytes directly as a file (or files) part. The part must carry a correct Content-Type; an empty type is rejected with 415.
• URL — send a URL and Talentino fetches it server-side.

You can mix files and URLs freely in the bulk and Job Match endpoints.

Validation limits

These mirror the in-app upload flow exactly:

• Size: max 5 MB per document. Oversized documents return 413. The cap is enforced on the actual streamed bytes — a lying Content-Length won't get past it.
• Type: the allowlist is pdf, doc, docx, png, jpeg, jpg. Anything else returns 415. (Images are allowed because the in-app resume dropzone allows them.)

URL fetching & SSRF protection

Server-side URL fetches are guarded:

• Only http/https URLs; embedded credentials are rejected.
• The host is resolved and every resulting address is checked — private, loopback, link-local, and metadata ranges are blocked (e.g. 127.0.0.1, 10.0.0.0/8, 169.254.169.254, IPv6 ::1/fc00::/7, IPv4-mapped forms, and decimal/hex-obfuscated literals).
• Redirects are followed up to a limit, and every hop is re-validated before it's fetched.
• A 30-second timeout applies.
• A fetch failure (DNS, timeout, blocked address, bad response) surfaces as 502.

Deduplication

Talentino computes a SHA-256 content hash of each document:

• Within a single request (bulk / Job Match), an identical document is accepted once; later copies in the same batch are reported as in-batch duplicates.
• Across requests, a previously-seen document returns 409 — but this cross-request dedup runs on production stages only. On dev/testing stages duplicates pass through.

Straight-through processing

For Resume imports, the Import Activity drives what happens next:

• No import_activity_id supplied → Talentino auto-creates a validated disk Import Activity. Because it's already validated, the pipeline's deep-processing phase runs immediately — there's no awaiting_validation pause.
• import_activity_id supplied → the Resume is linked to that Import Activity (which must belong to your Business Unit, else 404). The processing machine is triggered without changing the activity's status; an awaiting_validation activity will shallow-process the new Resume and pause again, preserving in-app semantics.

Credits

Ingestion verifies credits up front. If your Business Unit lacks enough credits for the requested work, the request is rejected with 402 before any document is processed.

Billable Action Types are process_resume, process_job_requirements, score_resume, and request_info — the billable act of requesting additional information from a candidate by email (1 credit). See the Credit API for how services reserve and settle credits.

Partial success (bulk & Job Match)

The batch endpoints don't fail the whole request when one document is bad:

• Each item gets an entry with status: "accepted" (carrying its resume_id) or status: "failed" (carrying an error message), returned in input order.
• A summary reports { total, accepted, failed }.
• HTTP status is 201 when at least one item is accepted, or 422 when all items failed.

See the reference for the exact item shape.