Onboardly
Get started

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

Get an API key

Candidate Match questions

Fetch, preview and publish the questions of your Candidate Match quiz, with no dashboard screen.

Keep the draft in your own system

Onboardly keeps no draft. Fetch the live quiz, edit it in your system, preview the change, then publish it. Preview and publish need a key held by an owner or admin of an organisation that is enabled for question management; every other organisation gets the same 404 as when Candidate Match is switched off.

Read the quiz#

GET/api/v1/match/questions#

Fetch the Candidate Match quiz that is live now for your organisation.

Headers

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

Status codes

2002xx
The live quiz. If nothing has ever been published for your account, this is the built-in quiz as version 1.
4014xx
Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.
4044xx
Candidate Match is switched off (an EMPTY body), or your account is not enabled for question management (not_found). These two cannot be told apart by status, on purpose.
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
The read or write could not be completed. Nothing was changed; retry.
This resource is temporarily unavailable. Try again shortly.
5035xx
Your account’s team details could not be read right now. Nothing was changed; retry.
Some of this candidate’s records could not be read right now. Try again shortly.

questions is in screen order: core questions first, then your own, in the order you gave them. The candidate’s contact-details screen is not part of the list and cannot be changed. version_id is the id to quote in Fetch a quiz version; core_version is the same string as quiz_version in the profiles feed.

Re-fetch whenever version_no differs from the one you hold, and before every edit: Onboardly publishes a new version itself when the locked core questions change, keeping your questions and rewording as they were.

cURL
curl \
  "https://rca-onboardly.com/api/v1/match/questions" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "version_id": "c91a47be-2d38-4e05-b6f2-0a7d3e5c1b84",
  "version_no": 2,
  "core_version": "2026-10-13",
  "published_at": "2026-10-14T10:30:00Z",
  "questions": [
    {
      "key": "discipline",
      "scope": "core",
      "type": "single",
      "question": "What’s your main discipline?",
      "helper": "Tap one. You can add more later.",
      "required": true,
      "options": [
        {
          "value": "electrical",
          "label": "Electrical"
        },
        {
          "value": "mechanical_cooling",
          "label": "Mechanical & cooling"
        }
      ]
    },
    {
      "key": "based_in",
      "scope": "core",
      "type": "text",
      "question": "Where are you based now?",
      "helper": null,
      "required": true,
      "options": []
    },
    {
      "key": "x_clearance_level",
      "scope": "custom",
      "type": "single",
      "question": "What security clearance do you hold?",
      "helper": "Pick the highest.",
      "required": false,
      "options": [
        {
          "value": "none",
          "label": "None"
        },
        {
          "value": "sc",
          "label": "SC"
        }
      ]
    }
  ]
}
GET/api/v1/match/questions/versions/{id}#

Fetch the exact quiz an older profile was answered against.

Headers

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

Status codes

2002xx
That version, in the same shape as Fetch the live quiz.
4014xx
Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.
4044xx
Candidate Match is switched off (an EMPTY body), your account is not enabled for question management, or the id is not UUID-shaped, does not exist or belongs to someone else. One outcome, never distinguishable.
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
The read or write could not be completed. Nothing was changed; retry.
This resource is temporarily unavailable. Try again shortly.
5035xx
Your account’s team details could not be read right now. Nothing was changed; retry.
Some of this candidate’s records could not be read right now. Try again shortly.

A version is never edited or deleted, so this returns the quiz exactly as it was, for as long as a profile refers to it. id is a version_id from Fetch the live quiz or a publish response.

cURL
curl \
  "https://rca-onboardly.com/api/v1/match/questions/versions/<candidate id>" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "version_id": "c91a47be-2d38-4e05-b6f2-0a7d3e5c1b84",
  "version_no": 2,
  "core_version": "2026-10-13",
  "published_at": "2026-10-14T10:30:00Z",
  "questions": [
    {
      "key": "discipline",
      "scope": "core",
      "type": "single",
      "question": "What’s your main discipline?",
      "helper": "Tap one. You can add more later.",
      "required": true,
      "options": [
        {
          "value": "electrical",
          "label": "Electrical"
        },
        {
          "value": "mechanical_cooling",
          "label": "Mechanical & cooling"
        }
      ]
    },
    {
      "key": "based_in",
      "scope": "core",
      "type": "text",
      "question": "Where are you based now?",
      "helper": null,
      "required": true,
      "options": []
    },
    {
      "key": "x_clearance_level",
      "scope": "custom",
      "type": "single",
      "question": "What security clearance do you hold?",
      "helper": "Pick the highest.",
      "required": false,
      "options": [
        {
          "value": "none",
          "label": "None"
        },
        {
          "value": "sc",
          "label": "SC"
        }
      ]
    }
  ]
}

Change the quiz#

POST/api/v1/match/questions/preview#

Check a proposed quiz change and get a preview link. Never changes the live quiz.

Headers

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

Request fields

custom_questionsarrayrequired
Your own questions, in screen order: up to 8. [] means none. Send the complete desired set on every call; it replaces what is live and is not a patch.
core_overridesobjectoptional
Reworded text for core questions, keyed by core key; only question, helper and sub_label can change. {} or omitted means no rewording.

Status codes

2002xx
The proposal was checked. ok says whether it can be published; a failed validation is ok: false with errors, not an HTTP error.
4004xx
The body is not JSON, is over 20000 characters, or is not the right shape at the top level.
invalid_jsonbody_too_largeinvalid_body
4014xx
Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.
4034xx
The key’s user is not an owner or admin of your organisation, or the key was created Read only (code: "key_read_only"). Checked before the body.
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
Candidate Match is switched off (an EMPTY body), or your account is not enabled for question management (not_found). These two cannot be told apart by status, on purpose.
not_found
4294xx
Rate limit exceeded, or your organisation already holds the most unexpired previews (too_many_previews); wait for some to expire. Retry after the Retry-After header when it is present.
Too many requests — please try again shortly.too_many_previews
5005xx
The read or write could not be completed. Nothing was changed; retry.
This resource is temporarily unavailable. Try again shortly.
5035xx
Your account’s team details could not be read right now. Nothing was changed; retry.
Some of this candidate’s records could not be read right now. Try again shortly.

preview_url is the public quiz page of your most recently created, non-revoked quiz link with ?preview=<id>, valid for 24 hours (preview_expires_at). It shows the quiz with your proposal applied; a banner says "Preview" and the page cannot submit, so no profile is created.

If your key has no live quiz link, preview_url is null and warnings gains an entry with code no_active_link: the preview is still stored and quiz is still returned. Mint a link with POST /api/v1/match/links and preview again.

errors[] and warnings[] entries are { path, code, message }. path points into your request, code is stable and safe to branch on, message is for people. A warning does not make ok false, but publishing with warnings needs acknowledge_sensitive: true.

Only an owner or admin key of an enabled organisation can preview. Any other organisation gets the same 404 as every other question endpoint.

cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/match/questions/preview" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_questions": [
    {
      "key": "x_clearance_level",
      "type": "single",
      "question": "What security clearance do you hold?",
      "helper": "Pick the highest.",
      "required": false,
      "options": [
        {
          "value": "none",
          "label": "None"
        },
        {
          "value": "sc",
          "label": "SC"
        }
      ]
    }
  ],
  "core_overrides": {
    "dc_years": {
      "question": "How many years have you worked in data centres?"
    }
  }
}'
Request body
{
  "custom_questions": [
    {
      "key": "x_clearance_level",
      "type": "single",
      "question": "What security clearance do you hold?",
      "helper": "Pick the highest.",
      "required": false,
      "options": [
        {
          "value": "none",
          "label": "None"
        },
        {
          "value": "sc",
          "label": "SC"
        }
      ]
    }
  ],
  "core_overrides": {
    "dc_years": {
      "question": "How many years have you worked in data centres?"
    }
  }
}
200 · A proposal that passes
{
  "ok": true,
  "errors": [],
  "warnings": [],
  "quiz": {
    "version_id": null,
    "version_no": null,
    "core_version": "2026-10-13",
    "questions": [
      {
        "key": "discipline",
        "scope": "core",
        "type": "single",
        "question": "What’s your main discipline?",
        "helper": "Tap one. You can add more later.",
        "required": true,
        "options": [
          {
            "value": "electrical",
            "label": "Electrical"
          },
          {
            "value": "mechanical_cooling",
            "label": "Mechanical & cooling"
          }
        ]
      },
      {
        "key": "based_in",
        "scope": "core",
        "type": "text",
        "question": "Where are you based now?",
        "helper": null,
        "required": true,
        "options": []
      },
      {
        "key": "x_clearance_level",
        "scope": "custom",
        "type": "single",
        "question": "What security clearance do you hold?",
        "helper": "Pick the highest.",
        "required": false,
        "options": [
          {
            "value": "none",
            "label": "None"
          },
          {
            "value": "sc",
            "label": "SC"
          }
        ]
      }
    ]
  },
  "preview_url": "https://rca-onboardly.com/match/m4k7pqr2?preview=5d2e8a10-77c3-4f6b-9b0e-1c4a8f3e6d92",
  "preview_expires_at": "2026-10-15T09:12:00Z"
}
200 · A proposal that fails validation
{
  "ok": false,
  "errors": [
    {
      "path": "custom_questions[0].key",
      "code": "invalid_key",
      "message": "Keys must start with x_ and use lower-case letters, digits and underscores."
    }
  ],
  "warnings": [],
  "quiz": null,
  "preview_url": null,
  "preview_expires_at": null
}
POST/api/v1/match/questions/publish#

Publish a proposed quiz change as a new version. Live on every quiz link at once.

Headers

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

Request fields

custom_questionsarrayrequired
As for preview.
core_overridesobjectoptional
As for preview.
expected_version_nointegerrequired
The version_no you last fetched. If another publish got in first the call is refused with 409 and nothing changes.
acknowledge_sensitivebooleanoptional
Must be true if the same proposal produced warnings in preview.

Status codes

2002xx
Published. The response is the new live quiz.
4004xx
Malformed body, or the proposal failed validation. For a validation failure error is the first error code and data.errors lists them all.
invalid_jsonbody_too_largeinvalid_body
4014xx
Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.
4034xx
The key’s user is not an owner or admin of your organisation, or the key was created Read only (code: "key_read_only"). Checked before the body.
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
Candidate Match is switched off (an EMPTY body), or your account is not enabled for question management (not_found). These two cannot be told apart by status, on purpose.
not_found
4094xx
expected_version_no is no longer the live version (version_conflict; data.current_version_no says what it is now), or the proposal is identical to the live quiz (unchanged). Nothing was published.
version_conflictunchanged
4224xx
Sensitive wording: a blocked phrase, never publishable as worded, or a warned phrase without acknowledge_sensitive: true. data.errors and data.warnings say where.
sensitive_wording_blockedsensitive_ack_required
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5005xx
The read or write could not be completed. Nothing was changed; retry.
This resource is temporarily unavailable. Try again shortly.
5035xx
Your account’s team details could not be read right now. Nothing was changed; retry.
Some of this candidate’s records could not be read right now. Try again shortly.

The checks preview ran are run again, so publish does not depend on a prior preview. A failed publish, whatever the status, leaves the live quiz exactly as it was.

400 is a request that is wrong by the rules of the format (shape, limits, characters, key reuse); 422 is a well-formed request refused for its content (sensitive wording). Preview reports both as entries in errors[]; only publish turns them into HTTP statuses.

Every publish creates a new version and is live on every quiz link at once; you do not re-mint links. A candidate part-way through can finish on the version they saw for 60 minutes after it is replaced.

cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/match/questions/publish" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_questions": [
    {
      "key": "x_clearance_level",
      "type": "single",
      "question": "What security clearance do you hold?",
      "helper": "Pick the highest.",
      "required": false,
      "options": [
        {
          "value": "none",
          "label": "None"
        },
        {
          "value": "sc",
          "label": "SC"
        }
      ]
    }
  ],
  "core_overrides": {
    "dc_years": {
      "question": "How many years have you worked in data centres?"
    }
  },
  "expected_version_no": 1
}'
Request body
{
  "custom_questions": [
    {
      "key": "x_clearance_level",
      "type": "single",
      "question": "What security clearance do you hold?",
      "helper": "Pick the highest.",
      "required": false,
      "options": [
        {
          "value": "none",
          "label": "None"
        },
        {
          "value": "sc",
          "label": "SC"
        }
      ]
    }
  ],
  "core_overrides": {
    "dc_years": {
      "question": "How many years have you worked in data centres?"
    }
  },
  "expected_version_no": 1
}
200 · Response
{
  "version_id": "c91a47be-2d38-4e05-b6f2-0a7d3e5c1b84",
  "version_no": 2,
  "core_version": "2026-10-13",
  "published_at": "2026-10-14T10:30:00Z",
  "questions": [
    {
      "key": "discipline",
      "scope": "core",
      "type": "single",
      "question": "What’s your main discipline?",
      "helper": "Tap one. You can add more later.",
      "required": true,
      "options": [
        {
          "value": "electrical",
          "label": "Electrical"
        },
        {
          "value": "mechanical_cooling",
          "label": "Mechanical & cooling"
        }
      ]
    },
    {
      "key": "based_in",
      "scope": "core",
      "type": "text",
      "question": "Where are you based now?",
      "helper": null,
      "required": true,
      "options": []
    },
    {
      "key": "x_clearance_level",
      "scope": "custom",
      "type": "single",
      "question": "What security clearance do you hold?",
      "helper": "Pick the highest.",
      "required": false,
      "options": [
        {
          "value": "none",
          "label": "None"
        },
        {
          "value": "sc",
          "label": "SC"
        }
      ]
    }
  ]
}
PreviousCandidate MatchNextQualifications