Onboardly
Get started

Partner API Create candidates, collect documents and references, retrieve the compliance pack.

Get an API key

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, revoked or expired 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.
  • documents[].pages is present ONLY on a document the candidate sent as several pages (two or more); a single-file document has no pages key. It lists the pages that can be opened, in page order, each with its page_number and its own content_url — see Retrieve a document page. The page the document’s own content_url serves is the one its submission was recorded against — not necessarily page 1 — so content_url behaves exactly as before. A page that cannot be opened right now is left out and the numbering keeps its gap, so a missing number means “not available”, never “renumbered”.
  • documents[].pages_unavailable is true ONLY on a document whose pages the platform could not locate: its file may be one page of a multi-page document whose other pages could not be reached. It is absent on every other document (a single-file document has neither key), and pages is absent on a document that carries it. Do not read the missing pages as “one file”. The document’s own content_url still serves the file its submission was recorded against. The marker is a stable data condition on that one document, not a failed read: a 503 on this endpoint means only that a record could not be read right now, so retry it.
  • When a candidate sends several pages of one document, each page is listed under that document’s pages, not under List unmatched attachments. Files already listed there stay listed.
  • 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
    },
    {
      "name": "Proof of Address",
      "status": "accepted",
      "submitted_at": "2026-08-20T10:17:00Z",
      "content_url": "https://rca-onboardly.com/api/v1/candidates/3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70/documents/2d9f7c35-6b1a-4e48-9a7d-5c3e8f1a2b64/content",
      "pages": [
        {
          "page_number": 1,
          "content_url": "https://rca-onboardly.com/api/v1/candidates/3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70/documents/2d9f7c35-6b1a-4e48-9a7d-5c3e8f1a2b64/pages/6a1c8e27-3f4b-4d95-8e2a-9b7c0d5f1e38/content"
        },
        {
          "page_number": 2,
          "content_url": "https://rca-onboardly.com/api/v1/candidates/3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70/documents/2d9f7c35-6b1a-4e48-9a7d-5c3e8f1a2b64/pages/9e4b2a61-7c3d-4f18-b5a9-1d6e8c3f7a52/content"
        }
      ]
    },
    {
      "name": "Training Certificate",
      "status": "accepted",
      "submitted_at": "2026-08-20T10:19:00Z",
      "content_url": "https://rca-onboardly.com/api/v1/candidates/3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70/documents/5b8e3d17-2a6c-4f90-b4d1-7c9a1e6f3d85/content",
      "pages_unavailable": true
    }
  ],
  "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