Update a reference

Supply the referee’s email, or correct any referee detail, on an existing reference request.

PATCH/api/v1/references/{id}#

Supply the referee’s email (or correct any referee detail) on an existing reference request.

Headers

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

Request fields

referee_emailstringrequired: Required on every PATCH — this is a full replace, not a partial update (see the note below). The same bare-address rule as create-reference.
referee_namestringoptional: Omit to clear the field — see the note below.
referee_organisationstringoptional: Omit to clear the field.
referee_phonestringoptional: Omit to clear the field.
employment_start_datestringoptional: Omit to clear the field.
employment_end_datestringoptional: Omit to clear the field.
sendbooleanoptional: Defaults to true. Set false to suppress the automatic send on a first email capture.
template_idstring or nulloptional: A reference_templates.id from List reference templates to pin, null to unpin (falls back to the recruiter’s default), or omit to leave an existing pin untouched — the one field on this route that is NOT a full replace.

Status codes

2002xx: Reference updated. send is set only when this call triggered a send attempt.
4004xx: Missing/invalid email, a field over length, 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, 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 reference request, or not yours.
Reference request not found
4094xx: The request was cancelled (for example when the candidate’s journey was reset), so a first email cannot be added to it. Create a new reference request instead.
This reference request was cancelled, so it can’t be sent. Add a new reference instead.
4094xx: The call would change the email of a referee the candidate asked us not to contact until they have a job offer (their current employer). Nothing is written. A recruiter releases that hold from the dashboard first. The same address with only letter case or a +tag changed is not a change, so a PATCH that keeps the address and corrects the other fields goes through.
This referee is on hold until the candidate has an offer. Release the hold before changing their email.
4294xx: Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5005xx: The update could not be verified as written, the check for a contact hold on an email change could not be completed (nothing is written), or the service is temporarily unavailable.
Failed to update the reference requestThis resource is temporarily unavailable. Try again shortly.

This is a full REPLACE, not a partial update

Unlike PATCH /candidates/{id}, every field you omit is written as null (or cleared) — always send the complete referee record, not just the field that changed.

The FIRST call that supplies an email for a referee who had none triggers the send automatically (unless you pass send: false). A later correction to an already-emailed referee never re-sends.

While the candidate is being asked to agree on WhatsApp, that send is refused: the details are still saved, and send is { "error": "This referee will be emailed automatically once the candidate agrees on WhatsApp." }. A candidate who has never been messaged on WhatsApp is not held.

If the address you supply is one the candidate asked us not to contact until they have a job offer, the details are still saved but nothing is emailed: send is { "error": "The candidate asked us not to contact this referee until an offer is made. Release the hold to send.", "held": true }. Only a recruiter can release the hold, from the dashboard; this API has no field or endpoint that reads or releases one.

template_id is the one exception to the full-replace rule above — omit it and an existing pin is left alone, it is never cleared by omission the way the referee fields are.

cURL

curl -X PATCH \
  "https://rca-onboardly.com/api/v1/references/<reference id>" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "referee_email": "priya.shah@acme.example"
}'

Request body

{
  "referee_email": "priya.shah@acme.example"
}

200 · Response

{
  "reference": {
    "flagged_reason": null
  },
  "send": {
    "messageId": "a1b2c3d4-message-id"
  }
}

PreviousAdd a reference NextReference templates

PATCH /api/v1/references/{id}

cURL

curl -X PATCH \
  "https://rca-onboardly.com/api/v1/references/<reference id>" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "referee_email": "priya.shah@acme.example"
}'

Request body

{
  "referee_email": "priya.shah@acme.example"
}

200 · Response

{
  "reference": {
    "flagged_reason": null
  },
  "send": {
    "messageId": "a1b2c3d4-message-id"
  }
}