Onboardly
Get started

Application form

Mint a candidate-facing application-form link, and read back what a candidate submitted.

Mint-only — this pair never sends anything

The POST below mints and commits a fresh link; it never composes or enqueues a WhatsApp message. Deliver the URL to your candidate yourself.

POST/api/v1/candidates/{id}/application-form#

Mint a candidate-facing application-form link. This call never sends it.

Headers

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

Status codes

2002xx
Minted and committed. A repeat call ROTATES the token — the previous link stops resolving the moment this succeeds.
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
4094xx
This candidate has opted out — a link would only ever resolve as unavailable.
opted_out
4094xx
This candidate is not currently eligible for a fresh link — not yet consented, mid a data-subject request, taken over by a recruiter, or otherwise suppressed. No token is minted.
no_conversationmirror_not_ownednot_consentednot_collectingreal_seededlive_disabledrecruiter_deletion_scheduledprocessing_pausedbot_paused
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, the ownership read failed, the eligibility check itself could not run, or the token commit failed.

This endpoint sends nothing itself — but it enrols the candidate in the WhatsApp chase for the form

Deliver the returned url yourself — your own SMS, email, or ATS notification; this call never messages the candidate directly. It DOES mark the form outstanding: once the account-level application-form chase is switched on, a candidate who has not opened their link within their chase window will be reminded over WhatsApp, the same as any other outstanding document. A candidate ineligible for a fresh link (opted out, mid a data-subject request, not yet consented, …) is refused before that can happen — see the 409 rows below.

  • Before minting, this checks the SAME eligibility a recruiter’s own “Send application form” button checks — consent, conversation flow-state, and suppression (opt-out, data-subject-request pause, account status). A candidate this account has never messaged on WhatsApp skips that check outright — minting a web link needs no phone number.
  • expiresAt is 14 days out on a first mint, or 48 hours out if this candidate has already submitted once — a re-mint after submission gets the shorter correction window, never a fresh two-week credential for declarations already recorded. Repeated calls after a submission can only SHRINK that window further, never renew or extend it.
  • No request body — the candidate id in the path is everything this endpoint needs.
cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/application-form" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "url": "https://rca-onboardly.com/apply/9f2c1a4e7b3d8f5a6c2e1b9d4f7a3c8e5b1d9f2c1a4e7b3d8f5a6c2e1b9d4f7a",
  "expiresAt": "2026-09-28T10:14:02Z"
}
GET/api/v1/candidates/{id}/application-form#

Read back a candidate’s newest submitted application form.

Headers

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

Status codes

2002xx
application is the newest submission, or null when nothing has been submitted yet — both are a genuine checked answer, never an outage.
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 read this payload depends on could not be completed. Never a confident application: null — retry.
Some of this candidate’s records could not be read right now. Try again shortly.
  • Declarations always list all six, in the form’s own order. A declaration this candidate has no row for reads accepted: null, acceptedAt: null — an absence, never a refusal the candidate did not make.
  • submitted_ip and submitted_user_agent are never returned here. They DO surface elsewhere on this API — inside the compliance-pack audit block returned by GET /candidates/{id}/pack — where they exist for a regulator/DSR audit trail.
cURL
curl \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/application-form" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "application": {
    "submittedAt": "2026-09-10T09:02:14Z",
    "formVersion": "1",
    "personalDetails": [
      {
        "key": "fullName",
        "label": "Full name",
        "value": "Marcus Ade"
      },
      {
        "key": "dateOfBirth",
        "label": "Date of birth",
        "value": "1994-03-02"
      }
    ],
    "eligibility": [
      {
        "key": "rightToWorkStatus",
        "label": "Right to work status",
        "value": "British citizen"
      }
    ],
    "declarations": [
      {
        "key": "dbs_ongoing",
        "label": "DBS ongoing monitoring",
        "accepted": true,
        "acceptedAt": "2026-09-10T09:02:14Z"
      }
    ]
  }
}
PreviousPause or resume the botNextRestart a candidate’s journey