Onboardly
Get started

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

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 or revoked key. Every authentication failure looks the same — see Authentication.
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.
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. 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