Onboardly
Get started

Retrieve a candidate

Read back everything you would see on the candidate’s dashboard detail page.

GET/api/v1/candidates/{id}#

Retrieve everything you would see on the candidate’s dashboard detail page.

Headers

X-Api-Keyonb_live_<key_id>_<secret>required
Your issued Partner API key — see Authentication.

Status codes

2002xx
The candidate’s current state.
4014xx
Missing, malformed, unknown or revoked key. Every authentication failure looks the same — see Authentication.
4044xx
Unknown, cross-tenant, or (a candidate id) sandbox-hidden. One outcome, never a 403.
Not found
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5035xx
A record this payload depends on could not be read right now. Never a confident empty/negative payload — retry shortly.
Some of this candidate’s records could not be read right now. Try again shortly.
  • status is the same presentational stage slug the dashboard header pill shows — awaiting_consent, consent_denied, in_progress, verified, flagged, or revoked — never the raw four-value database column.
  • content_url is set as soon as ANY submission exists for that slot, whatever its status (including a rejected one) — it is not a signal that the document was accepted.
  • cv.file_name is always null today — this repo’s CV writer stamps only the storage key, never the original filename. cv.size is the byte count actually stored, read from the same ledger content_url on a document resolves against.
  • compliance_pack.blockers here are bare names (["Right to Work"]); the pack endpoint’s own 409 carries richer { id, name, status } objects — see Retrieve the compliance pack.
  • Reference ids are not exposed here — store the id POST …/references returned you if you need to PATCH it later.
  • references[].template_id echoes back the recruiter-authored template pinned to that specific request via template_id on Add a reference / Update a reference, or null when none is pinned — see List reference templates.
cURL
curl \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "id": "3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70",
  "external_id": "ats-record-4471",
  "status": "in_progress",
  "consent": true,
  "candidate": {
    "name": "Jordan Ellis",
    "mobile_number": "+447700900321",
    "email": "jordan.ellis@example.com",
    "job_title": "Support Worker"
  },
  "documents": [
    {
      "name": "DBS",
      "status": "accepted",
      "submitted_at": "2026-08-20T10:15:00Z",
      "content_url": "https://rca-onboardly.com/api/v1/candidates/3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70/documents/8a21c4d6-0f3e-4b9a-8d1c-7e2f5a9b3c41/content"
    },
    {
      "name": "Right to Work",
      "status": "pending",
      "submitted_at": null,
      "content_url": null
    }
  ],
  "cv": {
    "file_name": "CV.pdf",
    "content_type": "application/pdf",
    "size": 482311,
    "content_url": "https://rca-onboardly.com/api/v1/candidates/3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70/cv"
  },
  "references": [
    {
      "organisation": "Acme Ltd",
      "role": "Support Worker",
      "status": "pending_send",
      "received_at": null,
      "reply_text": null,
      "template_id": "2c6b1e4a-7f3d-4a9e-8b5c-6d1f4a3e9c72",
      "reference_completeness": null
    }
  ],
  "reference_requirements": {
    "required": 1,
    "received": 0,
    "outstanding": 1
  },
  "compliance_pack": {
    "ready": false,
    "url": null,
    "blockers": [
      "Right to Work"
    ]
  },
  "chase": {
    "docs_attempts": 1,
    "docs_attempts_max": 3,
    "reference_attempts": 0,
    "reference_attempts_max": 3
  }
}

See The candidate object for the full field-by-field shape.

PreviousStart a candidateNextList candidates