Onboardly
Get started

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

Get an API key

Application form links

Publish the account’s one stable public application-form link, or mint per-campaign links that each carry their own document checklist.

Two different kinds of link, six endpoints

The account link is ONE per account, published once and dropped into your careers page — POST is an idempotent ensure, never a rotation. A campaign link is minted as many times as you like, each with its own documents checklist, and can be revoked independently.

The account link#

Campaign links#

Client brands#

GET/api/v1/application-form/brands#

List the client brands this account holds, to choose a `brand_id` for a campaign link.

Headers

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

Status codes

2002xx
Every brand this account owns, most recent first; archived brands are not listed.
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 list — retry.
Some of this candidate’s records could not be read right now. Try again shortly.

logo_url is an absolute URL, or null for a brand without a logo. An archived brand cannot be put on a new link (brand_archived). Create a brand with Create a client brand.

cURL
curl \
  "https://rca-onboardly.com/api/v1/application-form/brands" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
[
  {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "client_name": "Northgate Care",
    "agency_name": "Example Recruitment",
    "logo_url": "https://rca-onboardly.com/api/email-assets/3f2b8c1e-5d4a-4b7e-9a10-2c6d8e0f1a23.png",
    "primary_colour": "#1D254C",
    "accent_colour": "#26AA9E",
    "created_at": "2026-10-20T09:00:00Z",
    "archived_at": null
  }
]
POST/api/v1/application-form/brands#

Create a client brand (names, optional logo and colours) on your account, to put on campaign links.

Headers

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

Request fields

client_namestringrequired
The client the form is branded for, 1 to 80 characters. Shown to candidates and written into the consent sentence they tick, so it can never be changed afterwards. A client_name equal to your account company name makes an agency-only brand: candidates see your company once, with a one-party consent sentence.
agency_namestringoptional
Not accepted: sending this field at all (even empty) is 400 agency_name_not_settable. The agency in the consent sentence is always your account’s company name from Settings, because the first WhatsApp message a candidate gets names that company. If the account has none, create is 400 agency_name_required with a message to set it first. A brand keeps the agency name it was created with; if the company is renamed, brands made under the old name stop showing their client branding, so create a new one.
primary_colourstringoptional
#RRGGBB. Used for buttons and links, so it must have a contrast ratio of at least 4.5 against white; otherwise primary_colour_low_contrast comes back with measured_ratio, minimum and a suggested_primary that passes.
accent_colourstringoptional
#RRGGBB. The header stripe only; never contrast-checked.
logofileoptional
PNG, JPEG or SVG. Omit for a name-only brand.
logo_rights_confirmedstringrequired
Must be exactly true. It stands for: “We have the client’s permission to use its name and logo on our application forms, and will archive this brand when that permission ends.”

Status codes

2012xx
Brand created. Use its id as brand_id on a campaign link.
4004xx
A field failed validation, an agency_name was sent, or the body is not multipart.
invalid_multipartagency_name_not_settableclient_name_requiredclient_name_too_longagency_name_requiredagency_name_too_longinvalid_colourprimary_colour_low_contrastlogo_rights_not_confirmed
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.
4094xx
The account already holds the most active brands it may (archived ones do not count).
brand_limit_reached
4134xx
The upload is over the size cap (2 MB for PNG and JPEG, 512 KB for SVG). Refused before the body is parsed.
logo_too_large
4154xx
The logo is not a PNG, JPEG or SVG, an SVG contains something refused (script, external reference, entity), or the file cannot be decoded.
unsupported_logounsafe_svgundecodable_logo
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 a write failed. Nothing is left behind.
server_error
5035xx
Logo storage is not available right now. Retry.
storage_unavailable

The body is multipart/form-data, not JSON. The logo is stored as a PNG; an SVG is rasterised and never served as SVG. A brand is always created on the account that owns the API key; a recruiter_id field in the body is ignored.

cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/application-form/brands" \
  -H "X-Api-Key: $ONB_KEY"
201 · Response
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "client_name": "Northgate Care",
  "agency_name": "Example Recruitment",
  "logo_url": "https://rca-onboardly.com/api/email-assets/3f2b8c1e-5d4a-4b7e-9a10-2c6d8e0f1a23.png",
  "primary_colour": "#1D254C",
  "accent_colour": "#26AA9E",
  "created_at": "2026-10-20T09:00:00Z",
  "archived_at": null
}
PATCH/api/v1/application-form/brands/{id}#

Change a client brand’s logo and/or colours. The names never change.

Headers

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

Request fields

logofileoptional
A replacement PNG, JPEG or SVG. Needs logo_rights_confirmed. Once the new logo is in place the old file is deleted (unless another of your brands still uses it). Logo changes are limited to 10 per brand per hour (429).
logo_rights_confirmedstringoptional
Must be exactly true when a logo is sent. It stands for: “We have the client’s permission to use its name and logo on our application forms, and will archive this brand when that permission ends.”
primary_colourstringoptional
#RRGGBB, contrast-checked as on create. Send the field empty to clear it; leave it out to keep the stored value.
accent_colourstringoptional
#RRGGBB. Send the field empty to clear it; leave it out to keep the stored value.

Status codes

2002xx
Updated. The brand as it now stands.
4004xx
The body names a name field (names cannot change; create a new brand), carries nothing to change, is not multipart, a colour or the rights confirmation failed validation, or the brand is archived.
brand_names_immutablenothing_to_updatebrand_archivedinvalid_multipartinvalid_colourprimary_colour_low_contrastlogo_rights_not_confirmed
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 (refused before the rate limit), does not exist or belongs to another account — one outcome, never distinguishable.
brand_not_found
4094xx
Another logo change for this brand landed between this request reading the brand and writing it. Nothing changed; read the brand again and retry.
logo_changed_concurrently
4134xx
The upload is over the size cap (2 MB for PNG and JPEG, 512 KB for SVG). Refused before the body is parsed.
logo_too_large
4154xx
The logo is not a PNG, JPEG or SVG, an SVG contains something refused (script, external reference, entity), or the file cannot be decoded.
unsupported_logounsafe_svgundecodable_logo
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 write failed.
server_error
5035xx
Logo storage is not available right now. Retry.
storage_unavailable

The body is multipart/form-data, not JSON. The logo is stored as a PNG; an SVG is rasterised and never served as SVG. A brand is always created on the account that owns the API key; a recruiter_id field in the body is ignored.

Links already minted with this brand pick up the new logo and colours at once. Candidates who already submitted keep the names they ticked.

cURL
curl -X PATCH \
  "https://rca-onboardly.com/api/v1/application-form/brands/<candidate id>" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "client_name": "Northgate Care",
  "agency_name": "Example Recruitment",
  "logo_url": "https://rca-onboardly.com/api/email-assets/3f2b8c1e-5d4a-4b7e-9a10-2c6d8e0f1a23.png",
  "primary_colour": "#1D254C",
  "accent_colour": "#26AA9E",
  "created_at": "2026-10-20T09:00:00Z",
  "archived_at": null
}
DELETE/api/v1/application-form/brands/{id}#

Archive a client brand. It leaves the list and cannot go on a new link.

Headers

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

Status codes

2002xx
Archived (or already archived: the call is idempotent). The brand is kept, never deleted.
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 (refused before the rate limit), does not exist or belongs to another account — one outcome, never distinguishable.
brand_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 write failed.
server_error

Links already minted with the brand keep working, but from now on they open the form with Onboardly branding for new applicants. An applicant who already started under the brand keeps seeing it. Archiving also hides the brand from the list and stops it being chosen for new links.

cURL
curl -X DELETE \
  "https://rca-onboardly.com/api/v1/application-form/brands/<candidate id>" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "archived": true
}
PreviousRestart a candidate’s journeyNextCandidate Match