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

document_type
FieldTypeRequiredDescription
certificatestring—Certificate — Course, training or professional certificates
experience_letterstring—Experience letter — A letter from a past employer
educationstring—Education certificate — Degree certificates and marksheets
payslipstring—Payslip — Recent payslips, to confirm current salary
offer_letterstring—Offer letter — A current or previous offer letter
id_proofstring—ID proof — Government ID, where the role needs it
portfoliostring—Portfolio — Work samples, a portfolio or a case study
otherstring—Other document — Anything else the candidate wants to send

Request body (POST)

Send the file one of three ways
FieldTypeRequiredDescription
document_typestringYesOne of: certificate · experience_letter · education · payslip · offer_letter · id_proof · portfolio · other. A kind Talynce does not know is refused, not filed as "other".
filefileOne ofmultipart/form-data. The file's own name and type are used.
document_urlstringOne ofAn https link anyone can download the file from. Talynce fetches it; private addresses are refused.
(raw body)bytesOne ofThe file as the request body with a file Content-Type, and document_type in the query string.
file_namestringNoNeeded only with document_url or raw bytes when the link carries no name.
notestringNoShown beside the document.
job_iduuidNoThe job this document was sent for, when it answers one.
Sending a document three ways
# 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
A hosted file, as JSON
{
  "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"
}
The answer (201)
{
  "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"
  }
}
A link that could not be downloaded (422)
{
  "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_url must be https and public: a link to a private address, or one that answers an error, is refused with 422 and nothing is stored.
GET/api/v1/candidates/{id}/documents

List a candidate's documents, newest first.

POST/api/v1/candidates/{id}/documents

Add a document. Returns 201.

Example
{
  "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"
}
DELETE/api/v1/candidates/{id}/documents/{documentId}

Remove a document and the stored file.