Onboardly
Get started

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).
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 or revoked key. Every authentication failure looks the same — see Authentication.
4044xx
Unknown reference request, or not yours.
Reference request 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 update could not be verified as 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.

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 referenceNextReference templates