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.

Request fields

referee_emailstringunless `ask_candidate_fields` includes `referee_email`: A syntactically valid address.
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.
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, or a malformed/unknown/another account’s template_id.
Referee email is requiredInvalid referee email addressReferee details must be at most 200 charactersInvalid template_id
4014xx: Missing, malformed, unknown or revoked key. Every authentication failure looks the same — see Authentication.
4044xx: Unknown candidate, or not yours.
Candidate 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 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 "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 names NextUpdate a reference

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

cURL

curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/references" \
  -H "X-Api-Key: $ONB_KEY" \
  -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"
}