Onboardly
Get started

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

Get an API key

Add a reference

Create a reference request for a candidate’s referee. This call never sends an email by itself.

POST/api/v1/candidates/{id}/references#

Create a reference request for a candidate’s referee.

Headers

X-Api-Keyonb_live_<key_id>_<secret>required
Your issued Partner API key — see Authentication.
Idempotency-Key<your own retry id>optional
Optional. Send it and a retry of the same request replays the first outcome instead of repeating the write. 1–255 characters. Per account, per route, per candidate.

Request fields

referee_emailstringunless `ask_candidate_fields` includes `referee_email`
A bare address: no display name or angle brackets, none of <>",;()[]\: or whitespace, no trailing dot, and a final domain label shaped like a top-level domain (letters, or an xn-- label) — any real TLD, e.g. .ai or .ltd. Anything else is a 400.
referee_namestringoptional
Up to 200 characters.
referee_organisationstringoptional
Up to 200 characters.
ref_typestringoptional
professional (default) or character.
employment_start_datestringoptional
Free-form; normalised server-side.
employment_end_datestringoptional
Free-form; normalised server-side.
ask_candidate_fieldsstring[]optional
Subset of referee_name, referee_organisation, employment_dates, referee_email — defers those fields to the candidate over WhatsApp instead of you supplying them now.
template_idstringoptional
A reference_templates.id from List reference templates, to pin a recruiter-authored template to this specific request. Omit to use the recruiter’s default template (or the built-in copy if they have none) — see How reference emails are sent.

Status codes

2012xx
Reference request created. With an Idempotency-Key already used for this candidate, this is the ORIGINAL answer again with replayed: true inside data — nothing is created a second time.
4004xx
No referee email (and it was not deferred to the candidate), an invalid email, a field over length, an invalid ref_type/ask_candidate_fields, a malformed/unknown/another account’s template_id, or an Idempotency-Key over the length limit.
Referee email is requiredInvalid referee email addressReferee details must be at most 200 charactersInvalid template_idThe Idempotency-Key header must be at most 255 characters.
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
Unknown candidate, or not yours.
Candidate not found
4094xx
Another request with this Idempotency-Key is still in flight. Nothing was created; retry shortly with the same key.
A request with this Idempotency-Key is already in progress.
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5005xx
The insert could not be verified as written, or the service is temporarily unavailable.
Failed to create the reference requestThis resource is temporarily unavailable. Try again shortly.

This call does NOT send the referee email — see How reference emails are sent for what does.

cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/references" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Idempotency-Key: <your own retry id>" \
  -H "Content-Type: application/json" \
  -d '{
  "referee_organisation": "Acme Ltd",
  "referee_name": "Priya Shah",
  "ask_candidate_fields": [
    "referee_email"
  ]
}'
Request body
{
  "referee_organisation": "Acme Ltd",
  "referee_name": "Priya Shah",
  "ask_candidate_fields": [
    "referee_email"
  ]
}
201 · Response
{
  "id": "8f21a9c0-4d3b-4e7a-9c2f-1b6d8e5a7f30",
  "status": "pending_send"
}

See How reference emails are sent for what actually triggers the send.

PreviousDocument namesNextUpdate a reference