Candidate documents
Certificates, experience letters, portfolios and anything else a candidate sends you. A document added here appears under Documents on that candidate in Talynce, filed under the kind you sent it as, and marked as having come through the API.
A resume is not a document: send it with resume_url on the candidate, or to POST /candidates/{id}/resume, so it is read and its details filled in. Documents are stored and shown, never parsed.
A job can ask applicants for these kinds itself — tick them under Application settings when you create or edit the job, and the upload boxes appear on the job's public page and on the link its emails carry. Files sent that way arrive in the same place.
Kinds of document
| Field | Type | Required | Description |
|---|---|---|---|
| certificate | string | — | Certificate — Course, training or professional certificates |
| experience_letter | string | — | Experience letter — A letter from a past employer |
| education | string | — | Education certificate — Degree certificates and marksheets |
| payslip | string | — | Payslip — Recent payslips, to confirm current salary |
| offer_letter | string | — | Offer letter — A current or previous offer letter |
| id_proof | string | — | ID proof — Government ID, where the role needs it |
| portfolio | string | — | Portfolio — Work samples, a portfolio or a case study |
| other | string | — | Other document — Anything else the candidate wants to send |
Request body (POST)
| Field | Type | Required | Description |
|---|---|---|---|
| document_type | string | Yes | One of: certificate · experience_letter · education · payslip · offer_letter · id_proof · portfolio · other. A kind Talynce does not know is refused, not filed as "other". |
| file | file | One of | multipart/form-data. The file's own name and type are used. |
| document_url | string | One of | An https link anyone can download the file from. Talynce fetches it; private addresses are refused. |
| (raw body) | bytes | One of | The file as the request body with a file Content-Type, and document_type in the query string. |
| file_name | string | No | Needed only with document_url or raw bytes when the link carries no name. |
| note | string | No | Shown beside the document. |
| job_id | uuid | No | The job this document was sent for, when it answers one. |
# A file you already have: multipart, with the kind as a field
curl -X POST https://talynce.com/api/v1/candidates/{id}/documents \
-H "Authorization: Bearer <API_KEY>" \
-F "document_type=certificate" \
-F "note=AWS Solutions Architect" \
-F "file=@/path/to/aws-certificate.pdf"
# A file you host: send the link, Talynce downloads it
curl -X POST https://talynce.com/api/v1/candidates/{id}/documents \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{"document_type":"portfolio","document_url":"https://files.example.com/jane/portfolio.pdf"}'
# Raw bytes, with the kind and the name in the query string
curl -X POST "https://talynce.com/api/v1/candidates/{id}/documents?document_type=payslip&file_name=oct-payslip.pdf" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/pdf" \
--data-binary @oct-payslip.pdf{
"document_type": "experience_letter",
"document_url": "https://files.example.com/candidates/jane/relieving-letter.pdf",
"file_name": "relieving-letter.pdf",
"note": "Relieving letter from Acme Corp"
}{
"data": {
"id": "7c2d4b1e-5f3a-4c8d-9e1b-2a6f8d0c4b11",
"candidate_id": "550e8400-e29b-41d4-a716-446655440000",
"document_type": "experience_letter",
"document_type_label": "Experience letter",
"file_name": "relieving-letter.pdf",
"file_size_bytes": 184320,
"mime_type": "application/pdf",
"source": "api",
"job_id": null,
"note": "Relieving letter from Acme Corp",
"created_at": "2026-11-19T11:04:22.118Z"
}
}{
"error": {
"code": "document_unavailable",
"message": "document_url answered HTTP 403; it must be a link anyone can download the file from",
"details": { "reason": "http_error", "http_status": 403 }
}
}Limits
- PDF, Word (.doc/.docx) and images (PNG/JPG). Anything else is refused with 422.
- 10 MB a file, and 20 documents a candidate. The 21st is refused with 422.
- A
document_urlmust be https and public: a link to a private address, or one that answers an error, is refused with 422 and nothing is stored.
/api/v1/candidates/{id}/documentsList a candidate's documents, newest first.
/api/v1/candidates/{id}/documentsAdd a document. Returns 201.
{
"document_type": "experience_letter",
"document_url": "https://files.example.com/candidates/jane/relieving-letter.pdf",
"file_name": "relieving-letter.pdf",
"note": "Relieving letter from Acme Corp"
}/api/v1/candidates/{id}/documents/{documentId}Remove a document and the stored file.