Onboardly Partner API
Push a candidate into Onboardly from your ATS and read back their compliance outcome.
The Onboardly Partner API lets your ATS push a candidate into Onboardly and read back the result. Onboardly runs the WhatsApp conversation on your behalf — collecting consent, asking for documents one at a time, checking them with OCR, requesting references by email and chasing outstanding ones — so your integration only needs to create the candidate, poll for the outcome, and download the finished compliance pack.
Your ATS Onboardly Partner API Candidate | | | |-- POST /candidates ------->| | | |-- WhatsApp opener (start) --->| | |<-- consent, documents, ------| | | one at a time, OCR-checked | | |<-- referee reply (email) -----| |-- GET /candidates/{id} -->| | |<-- status, documents, -----| | | references, pack.ready | | |-- GET /candidates/{id}/pack ->| | |<-- compliance pack (PDF/ZIP) --| |System of record#
Your ATS stays the system of record for your own candidate id. Send it as the Idempotency-Key header when you create a candidate, and every subsequent GET echoes it back as external_id — so you never need a lookup table mapping your ids to ours.
Base URL and format#
Every request is made against https://rca-onboardly.com/api/v1. Send and expect application/json (two endpoints — Retrieve document content and Retrieve the compliance pack — return raw bytes instead). Every JSON response is wrapped in the same envelope: { "data": ..., "error": ... } — exactly one of the two is non-null. A small number of error responses add a third meta key alongside error (over-quota and the compliance-pack 409) carrying machine-readable detail beyond the message string.
Every endpoint this API exposes
| Method | Path | What it does |
|---|---|---|
| POST | /api/v1/candidates | Create a candidate from your ATS record, optionally sending the WhatsApp opener. |
| POST | /api/v1/candidates/{id}/start | Begin the WhatsApp conversation for a candidate created with start: false. |
| GET | /api/v1/candidates/{id} | Retrieve everything you would see on the candidate’s dashboard detail page. |
| GET | /api/v1/candidates | Discover which candidates exist, keyset-paginated, without already holding an id. |
| PATCH | /api/v1/candidates/{id} | Correct a candidate’s name, email, phone, role, or notes. |
| PATCH | /api/v1/candidates/{id}/outreach | Override this candidate’s document- and reference-chase behaviour. |
| POST | /api/v1/candidates/{id}/documents | Add one or more document requests to a candidate’s checklist. |
| GET | /api/v1/candidates/{id}/messages | Read a candidate’s WhatsApp conversation history, newest first, plus a bot-health summary. |
| POST | /api/v1/candidates/{id}/messages | Send a free-text WhatsApp message to a candidate, on the recruiter’s behalf. |
| POST | /api/v1/candidates/{id}/messages/template | Send an approved WhatsApp template to a candidate, even outside the 24-hour messaging window. |
| POST | /api/v1/candidates/{id}/bot | Pause the bot for a candidate (recruiter take-over), or hand a paused conversation back to the bot. |
| GET | /api/v1/templates | List the approved WhatsApp templates this platform can send outside the 24-hour messaging window. |
| POST | /api/v1/candidates/{id}/application-form | Mint a candidate-facing application-form link. This call never sends it. |
| GET | /api/v1/candidates/{id}/application-form | Read back a candidate’s newest submitted application form. |
| GET | /api/v1/application-form/link | Read the account’s one stable public application-form link, if one has been published. |
| POST | /api/v1/application-form/link | Mint the account’s one stable public application-form link, or return the one that already exists. |
| GET | /api/v1/application-form/links | List every campaign application-form link this account has minted. |
| POST | /api/v1/application-form/links | Mint a fresh campaign application-form link with its own document checklist. |
| DELETE | /api/v1/application-form/links | Revoke one campaign application-form link. |
| GET | /api/v1/candidates/{id}/documents/{docId}/content | Download the bytes of a document’s latest submission. |
| GET | /api/v1/candidates/{id}/cv | Download the bytes of a candidate’s uploaded CV. |
| POST | /api/v1/candidates/{id}/references | Create a reference request for a candidate’s referee. |
| PATCH | /api/v1/references/{id} | Supply the referee’s email (or correct any referee detail) on an existing reference request. |
| GET | /api/v1/reference-templates | List your own reference templates, so you can pick a template_id to pin on Add a reference / Update a reference. |
| GET | /api/v1/candidates/{id}/pack | Download the candidate’s compliance pack once every required document is accepted. |
| GET | /api/v1/settings/assistant | Read the name the WhatsApp assistant currently introduces itself with. |
| PATCH | /api/v1/settings/assistant | Set or clear the assistant’s display name. |
| GET | /api/v1/settings/quiet-hours | Read the account’s quiet-hours window — the hours outbound chase and template sends are suppressed. |
| PATCH | /api/v1/settings/quiet-hours | Set any subset of the quiet-hours window. |
| GET | /api/v1/churnguard/question-sets | List your own candidate-survey question sets, to choose a question_set_id for the prefs endpoint below. |
| GET | /api/v1/candidates/{id}/churnguard | Read back a candidate’s ChurnGuard survey — every question asked so far, and its typed answer. |
| GET | /api/v1/candidates/{id}/churnguard/prefs | Read a candidate’s pinned question set and auto-send override. |
| PATCH | /api/v1/candidates/{id}/churnguard/prefs | Pin a question set for this candidate, and/or override whether their survey sends automatically. |
| POST | /api/v1/candidates/{id}/churnguard/send | Mint (or reuse) this candidate’s survey placement and send the next question over WhatsApp. |
| GET | /api/v1/churnguard/settings | Read your account’s default for whether a candidate’s survey sends automatically once their compliance process completes. |
| POST | /api/v1/candidates/{id}/restart | Reset a candidate to a fresh start and re-send the consent request. |
What this API does not do#
- No webhooks. Poll
GET /candidates/{id}for the current state — there is nothing to subscribe to yet. - No delete. A candidate created here is permanent from this API’s side; deletion is a dashboard/GDPR operation.
- No resend of the WhatsApp opener from this API —
startonly ever fires once, at creation. - No read-only keys. Every issued key can create candidates and trigger real WhatsApp sends.
Versioning#
v1 (the /api/v1 prefix) is stable. New, additive fields may appear on any response without a version bump — ignore keys you do not recognise rather than rejecting them. content_url and compliance_pack.url are always absolute URLs; follow them with the same X-Api-Key header you already hold.