Get a candidate
Fetch one candidate in the curated v1 shape. Scope: candidates:read.
GET
/api/v1/candidates/{id}
🔒 API keyFetches a single candidate. Scope: candidates:read. A candidate the key cannot see returns 404 (no existence leak).
Path parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The candidate id. |
Example request
curl https://app.talent-ray.com/api/v1/candidates/cand_1 \
-H "Authorization: Bearer tr_YOUR_KEY"Response
200 OK
{
"id": "cand_1",
"fullName": "Jane Doe",
"email": "[email protected]",
"phone": "+905551112233",
"status": "Active",
"createdAt": "2026-06-01T10:00:00Z",
"updatedAt": "2026-06-02T08:00:00Z",
"roles": [
{ "roleId": "role_eng_be", "roleName": "Senior Backend Engineer", "organizationId": "org_acme", "status": "In Pipeline", "overallFitScore": 82, "approved": false }
]
}Status codes
| Status | Meaning |
|---|---|
200 | Success. |
401 | No valid API key. |
403 | insufficient_scope — the key lacks candidates:read. |
404 | Not found, or not visible to the key. |
429 | Rate limit exceeded. |