Onboardly
Get started

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

Get an API key

Send a survey question

Mint (or reuse) a candidate’s survey placement and send the next question over WhatsApp.

POST/api/v1/candidates/{id}/churnguard/send#

Mint (or reuse) this candidate’s survey placement and open its next scheduled check-in session over WhatsApp.

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.
2012xx
A check-in opener (intro, or the fixed first-week message) was sent.
2002xx
Already sent this round, or the send itself was refused (data.delivery: "failed", data.refusal names the reason).
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.
4034xx
Your account’s plan does not include ChurnGuard.
ChurnGuard is not included in your plan.
4044xx
Unknown, cross-tenant, or (a candidate id) sandbox-hidden. One outcome, never a 403.
Not found
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
4094xx
A refusal reason from a closed, published vocabulary — e.g. session_in_progress (a session is already out and awaiting a reply — never force-closed by a repeat call), template_unprovisioned (the WhatsApp session window is stale and no approved template exists yet), engine_active, placement_not_eligible, no_question_set, phone_changed (the candidate’s phone number changed after check-ins started — end check-ins, then send again to use the new number). Branch on the exact string.
5035xx
The compliance-conversation read failed — retry.
mirror_unreadable
5005xx
The send itself, or an internal read/write, failed — retry.
This resource is temporarily unavailable. Try again shortly.round_unavailablecandidate_unreadableplacement_unreadablesettings_unreadablerounds_unreadableclose_failedoutbox_unreadable

This sends a real WhatsApp message

Calling this endpoint messages the candidate. It is idempotent per round — a repeat call once an opener has already gone out returns already_sent, never a duplicate send. It never sends one of your own questions directly — those follow automatically once the worker accepts a round.

cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/churnguard/send" \
  -H "X-Api-Key: $ONB_KEY"
201 · Sent
{
  "delivery": "sent",
  "roundNo": 1,
  "placementId": "7c4e2a1b-6f9d-4b3e-8a2c-1d5e9f4a3b60"
}
200 · Already sent this round
{
  "delivery": "already_sent",
  "roundNo": 1
}
PreviousQuestion setsNextRetrieve survey results