Onboardly
Get started

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

Get an API key

Start a candidate

Send the WhatsApp opener for a candidate you created with `start: false` — the missing second step for checking field mapping before messaging anyone.

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

Begin the WhatsApp conversation for a candidate created with `start: false`.

Headers

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

Status codes

4024xx
Your plan has ended (code: "no_subscription") or this month’s messages are used up (code: "over_message_quota"). Nothing was sent or written. Choose or upgrade a plan, or wait until the 1st. Replies inside an open chat are never refused for the message limit.
5035xx
We could not check your plan just now (code: "billing_unavailable"). Nothing was sent; retry shortly.
2002xx
Attempted. outbound in the body says what actually happened — see the notes below.
4004xx
The candidate’s own phone number or opt-in details on file are invalid. Very rare — every candidate reachable through this API already passed this check at creation.
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, cross-tenant, or (a candidate id) sandbox-hidden. One outcome, never a 403.
Not found
4094xx
Cannot be started. Several distinct causes share this status — read the error string, and do not assume a retry clears it.
This candidate has already been started.This candidate has declined or withdrawn consent and cannot be started.This candidate cannot be started right now.This conversation is with a recruiter, so the candidate cannot be started.A data request is open for this candidate, so they cannot be started.This account is scheduled for deletion, so no new candidates can be started.
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5005xx
Internal error. Safe to retry — a 500 means the send was not attempted.
5035xx
The account is not ready to send WhatsApp right now, or the candidate’s data-request or account state could not be read (nothing is sent on an unknown). Retry; if it persists, contact support.
Starting a candidate requires the WhatsApp Transport setting to be 'twilio'. It is currently set to 'sim' — switch it in /chat → Settings, then retry.Starting this candidate is temporarily unavailable. Try again shortly.

One delivered opener per candidate — a second call is a 409, not a second message

Once a candidate’s opener has been handed to WhatsApp, calling this again returns 409 and sends nothing — with the same key or any other, immediately or a month later. The lock is held against the candidate rather than their phone number, so correcting a number with Update a profile does not release it. A send that FAILED can be retried: the lock covers a delivered opener, not an attempt — if the response was 200 with "outbound": "failed" or "refused", or a 503, the candidate is not locked.

A 409 does not mean nothing happened. If your client times out and retries, the first call may already have succeeded with only the response lost in transit — poll Retrieve a candidate’s status/consent fields before treating the call as failed.

  • outbound — sent (delivered to Twilio), failed (the transport rejected it), or refused (a suppression/ownership/budget check refused it between the pre-flight and the send). All three still return 200.
  • outboundSignature — present only when outbound is failed or refused. A normalised signature, never the provider’s raw message.
  • mirrored — whether the message was written into the candidate’s conversation thread, independent of outbound: false here does not mean the WhatsApp send failed, only that mirroring it did.
  • Rarely, an earlier call that died mid-send can leave a candidate’s opener lock held with nothing ever sent. That one needs a person — contact support, who can start the candidate from the dashboard.
cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/start" \
  -H "X-Api-Key: $ONB_KEY"
200 · Response
{
  "data": {
    "id": "3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70",
    "outbound": "sent",
    "mirrored": true
  },
  "error": null
}
PreviousCreate a candidateNextRetrieve a candidate