Onboardly
Get started

Pause or resume the bot

Pause the bot for a human (recruiter take-over), or hand a paused conversation back to the bot.

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

Pause the bot for a candidate (recruiter take-over), or hand a paused conversation back to the bot.

Headers

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

Request fields

action"pause" | "resume"required
Any other value 400s.

Status codes

2002xx
Dispatched — see the notes below for what notified/bot_paused mean.
4004xx
Missing/invalid action.
action must be "pause" or "resume"
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
pause: consent not granted, or already paused. resume: not currently paused, in a state that cannot be resumed automatically, or its automated-resume budget is exhausted — see the notes below.
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5005xx
The service is temporarily unavailable, or the write itself failed.
This resource is temporarily unavailable. Try again shortly.
5025xx
pause: the engine pause drive dispatched but did not land. resume: forwarded from the resume seam.
5035xx
The engine’s own conversation mirror could not be read.
  • notified (pause only) — whether the candidate was actually told a recruiter is taking over. false means the pause itself still succeeded, but the candidate was not messaged (no phone on file, or no approved template for a stale session window).
  • bot_paused (pause only) — whether the underlying conversation engine actually holds bot replies now. false (with a 200) means the recruiter-visible state still flipped, but there was no live conversation to pause yet.
  • resume’s 200 already implies the bot is un-paused — it carries no bot_paused field.
  • A 200 resume also releases the recruiter hold on the candidate record, so the candidate is eligible for scheduled reminders and for Restart again. A candidate resumed before this behaviour existed may still be held — call resume once more; it returns 200 and releases the hold.
  • There is no stage field on either action — the response never surfaces the underlying conversation state name, so a 409 cannot be read to learn anything about the candidate beyond "cannot resume automatically right now".
cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/bot" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "pause"
}'
Request body
{
  "action": "pause"
}
200 · Response
{
  "action": "pause",
  "notified": true,
  "bot_paused": true
}
PreviousSend a templateNextApplication form