Onboardly
Get started

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

Get an API key

Restart a candidate’s journey

Reset a candidate to a fresh start — clear their documents, CV and conversation, and ask for consent again.

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

Reset a candidate to a fresh start and re-send the consent request.

Headers

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

Request fields

confirmtruerequired
Must be the literal boolean true. Any other value, including omitting the field, is a 400.

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
Reset and restarted. outbound says whether the fresh consent request actually reached a transport.
4004xx
confirm was missing or not the literal true.
`confirm` must be the literal `true`
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, not this recruiter’s, sandbox-hidden, or the conversation belongs to a different recruiter/candidate.
Not found
4094xx
Cannot be restarted right now — see the notes below for every distinct cause this status covers.
This candidate has declined or withdrawn consent and cannot be restarted.A data request is open for this candidate. Restart is not available until it is closed.This conversation is paused or held by a recruiter and cannot be restarted automatically.Some of this candidate's WhatsApp files are held on a WhatsApp account that cannot be reached, so the restart stopped. Contact support.This restart was refused.
4294xx
Rate limited, OR this candidate was already restarted in the last hour — see the notes below; only the former has a Retry-After header.
Too many requests — please try again shortly.This candidate was restarted in the last hour.
5005xx
The service is temporarily unavailable, or a write could not be verified. Safe to retry.
This resource is temporarily unavailable. Try again shortly.
5035xx
WhatsApp sending is off right now, the engine’s conversation record could not be read, the candidate’s document list could not be verified, or the candidate’s WhatsApp files could not all be deleted. Safe to retry.
WhatsApp sending is switched off right now.This candidate's status could not be verified. Try again shortly.This candidate's document list could not be read, so the restart stopped before anything changed.This candidate's WhatsApp files could not all be deleted, so the restart stopped. Try again shortly.

This deletes uploaded documents, the CV and the conversation

Kept: message history, the activity log, the WhatsApp opt-in record, and any reference already answered by a referee. Deleted or reset: every uploaded document and the checklist status, the stored CV, and the conversation itself — reference requests still waiting on a reply are cancelled and fresh ones seeded; references already given are left exactly as they were. Consent is asked for again from scratch.

One restart per phone number per hour — a separate, durable limit

Independent of the rate-limit budget above and never lifted by a second key: at most one restart whose consent message actually sends, per WhatsApp number, every 1 hour — this also covers two candidate records that share one number. A second call inside that window is a 429 with the same status as a rate limit, but no Retry-After header.

  • Refused (409) for: a candidate who declined or withdrew consent, an open data request, a conversation currently paused or held by a recruiter (opted out, GDPR-paused, or handed to a human — one shared message for all three so this response cannot be used to learn which), or another consultant’s number.
  • outbound — sent, failed (transport rejected it), or refused (a check refused between the pre-flight and the send). All three still return 200.
  • outbound_signature — present only when outbound is not sent. Never a raw provider message or internal wording.
  • conversation_purge.status is always "purged" on a 200 — a restart that could not safely purge the conversation is refused before it reaches 200, never returned as a partial success.
  • The candidate’s WhatsApp files are deleted from our WhatsApp provider before anything else is cleared. If that cannot finish, the restart stops with nothing else changed: a 503 is safe to retry; a 409 about an unreachable WhatsApp account needs support first.
  • No Idempotency-Key support — this endpoint is addressed by the candidate id you already hold, and the durable one-per-hour cap above is what makes a retried call safe.
cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/restart" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm": true
}'
Request body
{
  "confirm": true
}
200 · Response
{
  "id": "3f9c1a2e-8b7d-4c1f-9a3e-2d5f8c1b4e70",
  "outbound": "sent",
  "conversation_purge": {
    "status": "purged"
  },
  "documents_cleared": true,
  "references_reseeded": 2,
  "cv_removed": true
}
PreviousApplication formNextApplication form links