Onboardly
Get started

Send a template

Send an approved WhatsApp template to a candidate, even outside the 24-hour messaging window.

POST/api/v1/candidates/{id}/messages/template#

Headers

X-Api-Keyonb_live_<key_id>_<secret>required
Your issued Partner API key — see Authentication.
Idempotency-Key<your own record id>required
Matches on the key alone, per account. 1–255 characters.

Request fields

template_keystringrequired
One of List templates’ partner_sendable keys — at launch, only "chase". Any other field on the body is ignored.

Status codes

2002xx
Sent, or replayed — see replayed in the notes below.
4004xx
Missing/over-long Idempotency-Key, or template_key is absent, unknown, or not partner_sendable.
An Idempotency-Key header is required (max 255 characters).A "template_key" string is required in the request body.That template key is not one this API can send. See List templates.
4014xx
Missing, malformed, unknown or revoked key. Every authentication failure looks the same — see Authentication.
4044xx
The capability is disabled, or the candidate is unknown, cross-tenant, or sandbox-hidden. One outcome, never a 403.
Not found
4094xx
Consent not granted, no acceptable recorded WhatsApp opt-in, missing opt-in evidence, outside this account’s messaging hours, the candidate cannot be messaged right now (opted out, processing paused, messaging disabled, account scheduled for deletion, taken over by a recruiter), not currently eligible for this template, the number is undeliverable, there is nothing outstanding to send about, the template is unavailable, the same Idempotency-Key was reused with a different template_key, or an earlier request with this exact key is still in flight.
That template key is not one this API can send. See List templates.This candidate has not granted consent yet, so a template cannot be sent.This candidate has no recorded WhatsApp opt-in, so a template cannot be sent.It is outside this account’s messaging hours for this candidate. Try again later.This candidate has opted out of messages.This candidate's data processing is paused — a message cannot be sent.Messaging is currently disabled for this candidate.This account is scheduled for deletion — a message cannot be sent.A recruiter has taken over this conversation — the bot is paused.This candidate is not currently waiting on anything this template can ask for.Messages to this number are not being delivered.There is nothing outstanding to send this template about.That template is not available to send right now.This candidate has already received a message recently — try again later.The messaging allowance for approved templates is used up for now — try again later.This message could not be sent. Try again shortly.This Idempotency-Key was already used for a different template_key today. Use a new Idempotency-Key per request.This request is still being processed. Try again shortly with the same Idempotency-Key.This candidate has no WhatsApp opt-in evidence on record. Pass opt_in_evidence_ref when creating or updating the candidate.
4294xx
Per-key/per-account rate limit, this candidate’s own daily cap (one partner template per recipient WhatsApp number per UTC day), or the platform-wide daily template budget.
Too many requests — please try again shortly.
5005xx
The service is temporarily unavailable.
This resource is temporarily unavailable. Try again shortly.
5025xx
Enqueued but did not classify as delivered.
This message could not be sent. Try again shortly.
5035xx
A read this response depends on could not complete — retry.
Some of this candidate’s records could not be read right now. Try again shortly.
  • The request carries no message content — every template variable is composed server-side from the candidate’s own record, so this endpoint cannot be used to send arbitrary text under an approved-template wrapper.
  • replayed: true means this exact Idempotency-Key already produced this send — the ORIGINAL outcome is returned verbatim and no second WhatsApp goes out. Unlike Send a message, this key never expires.
  • The returned message always shows author: "bot" on Retrieve messages — it is an engine-composed approved template, not human-typed text, even though a partner triggered it.
  • A candidate who has finished everything (complete) is not reachable through this endpoint, nor is one a recruiter is currently holding, one who has opted out, or one with an open data request — each returns its own 409 rather than a generic one.
  • Outside this account’s configured messaging hours the request is refused, never queued for later — retry once the window reopens.
  • A replay of an already-used Idempotency-Key reports the REAL current state of that original send: a still-in-flight original returns "still being processed", a non-delivered original returns the same non-2xx it originally did, and only a genuinely delivered original returns 200 with replayed: true.
  • If this candidate’s own WhatsApp opt-in source is recruiter_attested, opt_in_evidence_ref must already be set on the candidate — self-attestation alone is not accepted here.
cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/messages/template" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Idempotency-Key: <your own record id>" \
  -H "Content-Type: application/json" \
  -d '{
  "template_key": "chase"
}'
Request body
{
  "template_key": "chase"
}
200 · Response
{
  "message_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "template_key": "chase",
  "delivery_status": "sent",
  "sent_at": "2026-09-21T10:00:00.000Z",
  "replayed": false
}
PreviousSend a messageNextPause or resume the bot