Onboardly
Get started

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

Get an API key

Candidate Match

Mint public quiz links for a website button and pull each completed Candidate Match quiz, page by page.

Links in, profiles out

Mint a link, put it on your website, and pull the profiles of everyone who completes the quiz through it. Nothing is pushed to you and nothing is sent to the candidate by these endpoints. Candidate Match can be switched off for a deployment, in which case every endpoint here answers an empty 404.

Quiz links#

Profiles#

GET/api/v1/match/profiles#

Pull completed Candidate Match quizzes, keyset-paginated.

Headers

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

Request fields

limitintegeroptional
25 if omitted, up to 100. Never clamped — an out-of-range value is a 400.
cursorstringoptional
Opaque. Pass back the previous page’s next_cursor verbatim; omit for the first page.
updated_sincestring (ISO-8601)optional
ISO-8601 timestamp with a timezone (2026-10-13T00:00:00Z). Keeps profiles whose updated_at is at or after it; a retake updates updated_at. Anything else is a 400.
contact_opt_inboolean (`true` or `false`)optional
true returns only candidates who ticked "contact me about roles"; false only those who did not; omit for both. Applied before pagination. Any other value is a 400.

Status codes

2002xx
A page of profiles, newest first — may hold zero rows. Keep going until next_cursor is null.
4004xx
An out-of-range or malformed query parameter, or a malformed/tampered cursor.
Invalid query parameter: {param}Invalid or expired cursor
4014xx
Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5035xx
The read itself failed. Never a confident empty page — retry.
Some of this candidate’s records could not be read right now. Try again shortly.

Each profile carries the contact fields (first_name, mobile in international format, email, linkedin, contact_opt_in, contact_opt_in_at), every quiz answer under its field key (single-choice and number answers as a value, multi-choice answers as an array), and the computed badges, profile_strength (0 to 100) and profile_level. quiz_version says which version of the quiz the candidate answered. question_version_id names the question version they saw (null for a profile taken before question versions, or when that version is not one of this account’s), and custom_answers holds their answers to your own questions as { "x_key": value } ({} when there are none). Only this account’s profiles are returned.

Important: contact_opt_in: false means the candidate declined contact about roles; their mobile, email and linkedin are returned as null. Every other field, including first_name, is still returned. A quiz answer that is missing or was skipped reads as null (or [] for a multi-choice field).

Pagination is keyset on (created_at, id) descending: each page’s next_cursor points at the last row it returned, so every profile appears exactly once per walk. Iterate until next_cursor is null, not until a page is empty.

While Candidate Match is switched off for the deployment, every Candidate Match endpoint answers 404 with an EMPTY body (not the JSON envelope; an unknown path returns an HTML page instead), before the API key is checked.

cURL
curl \
  "https://rca-onboardly.com/api/v1/match/profiles" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "profiles": [
    {
      "id": "7e1d9a52-3b64-4f08-8c27-5a0e6b9d4c13",
      "link_id": "0b9c3f1e-7d52-4c1a-9a43-2f6e8d1b5a70",
      "first_name": "Jordan",
      "mobile": "+447700900321",
      "email": "jordan.ellis@example.com",
      "linkedin": null,
      "contact_opt_in": true,
      "contact_opt_in_at": "2026-10-13T09:05:41Z",
      "discipline": "electrical",
      "dc_years": "5_to_10",
      "related_sector": [
        "power_grid"
      ],
      "largest_project_mw": "50_100mw",
      "client_type": "hyperscaler",
      "liquid_cooling": "some_exposure",
      "tickets": [
        "ap_hv",
        "18th_edition"
      ],
      "regions": [
        "uk",
        "europe"
      ],
      "relocate": "yes_right_role",
      "rotation": "maybe",
      "based_in": "Manchester, UK",
      "currency": "GBP",
      "target_base": 85000,
      "notice": "2_months",
      "perm_contract": "permanent",
      "badges": [
        "hv_authorised"
      ],
      "profile_strength": 82,
      "profile_level": "standout",
      "quiz_version": "2026-10-13",
      "question_version_id": "c91a47be-2d38-4e05-b6f2-0a7d3e5c1b84",
      "custom_answers": {
        "x_clearance_level": "sc"
      },
      "created_at": "2026-10-13T09:05:41Z",
      "updated_at": "2026-10-13T09:05:41Z"
    }
  ],
  "next_cursor": null
}

Deletions and erasure#

GET/api/v1/match/profiles/deletions#

Poll which Candidate Match profiles were deleted, so you can delete your copies.

Headers

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

Request fields

limitintegeroptional
25 if omitted, up to 100. Never clamped — an out-of-range value is a 400.
cursorstringoptional
Opaque. Pass back the previous page’s next_cursor verbatim; omit for the first page.
sincestring (ISO-8601)optional
ISO-8601 timestamp with a timezone (2026-10-13T00:00:00Z). Keeps entries whose deleted_at is at or after it. Anything else is a 400.

Status codes

2002xx
A page of deletions, newest first — may hold zero rows. Keep going until next_cursor is null.
4004xx
An out-of-range or malformed query parameter, or a malformed/tampered cursor.
Invalid query parameter: {param}Invalid or expired cursor
4014xx
Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5035xx
The read itself failed. Never a confident empty page — retry.
Some of this candidate’s records could not be read right now. Try again shortly.

Each entry says that the profile with this profile_id no longer exists on Onboardly and why: retention (kept past the retention period), erasure_request (you called the erase endpoint) or subject_erasure (the person asked to be erased). When you see one, delete your own copy of that profile. Entries carry no personal data and only cover this account’s profiles. Not every deletion has an entry: deleting the whole Onboardly account removes the profiles and their entries together, because your integration key goes with the account.

Poll it on a schedule and remember the deleted_at of the newest entry you handled: send it as since next time. Pagination is keyset on (deleted_at, id) descending, so every entry appears exactly once per walk; iterate until next_cursor is null.

In a rare race a respondent can retake the quiz in the same instant their profile is deleted, so an entry can name a profile that a retake has just refreshed. If a profile you hold reappears in the profiles list after its entry, keep the newer copy.

Unlike the other Candidate Match endpoints, this one stays available when Candidate Match is switched off for the deployment: profiles already collected still age out and can still be erased, so you can always read the deletions and erase a respondent. It still needs a valid API key.

cURL
curl \
  "https://rca-onboardly.com/api/v1/match/profiles/deletions" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "deletions": [
    {
      "profile_id": "7e1d9a52-3b64-4f08-8c27-5a0e6b9d4c13",
      "reason": "erasure_request",
      "deleted_at": "2026-10-14T08:30:00Z"
    },
    {
      "profile_id": "3c5a8e10-92d4-4b7f-a1e6-0d4f7b2c9e58",
      "reason": "retention",
      "deleted_at": "2026-10-13T08:00:00Z"
    }
  ],
  "next_cursor": null
}
DELETE/api/v1/match/profiles/{id}#

Erase one Candidate Match respondent on request.

Headers

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

Status codes

2002xx
Erased for good. The profile appears in the deletion feed with reason erasure_request.
4014xx
Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.
4034xx
The key’s user has the viewer team role, or their account could not be read just then (retry) — or the key was created Read only (code: "key_read_only", refused before anything else). Checked before the body or any id — see Authentication.
Your team role doesn't allow this. Ask your team's admin or owner.This API key is read-only. Create a full-access key to make changes.
4044xx
An id that is not UUID-shaped, one this account does not own, or one that does not exist — one outcome, never distinguishable, and a malformed id is refused before the rate limit is spent.
not_found
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5005xx
No service client, or the deletion could not be committed. Nothing is deleted without its entry in the deletion feed; retry.
This resource is temporarily unavailable. Try again shortly.erase_failed

Use this when a respondent asks you to erase their data and you have confirmed it is theirs. It cannot be undone. Delete your own copy as well.

Unlike the other Candidate Match endpoints, this one stays available when Candidate Match is switched off for the deployment: profiles already collected still age out and can still be erased, so you can always read the deletions and erase a respondent. It still needs a valid API key.

cURL
curl -X DELETE \
  "https://rca-onboardly.com/api/v1/match/profiles/<candidate id>" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "erased": true
}
PreviousApplication form linksNextCandidate Match questions