Onboardly
Get started

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

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 or revoked key. Every authentication failure looks the same — see Authentication.
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.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, or the candidate’s document list could not be verified.
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 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.
  • 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