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.
How a candidate moves through the API
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/application-form/brands | List the client brands this account holds, to choose a brand_id for a campaign link. |
| POST | /api/v1/application-form/brands | Create a client brand (names, optional logo and colours) on your account, to put on campaign links. |
| PATCH | /api/v1/application-form/brands/{id} | Change a client brand’s logo and/or colours. The names never change. |
| DELETE | /api/v1/application-form/brands/{id} | Archive a client brand. It leaves the list and cannot go on a new link. |
| GET | /api/v1/match/links | List every Candidate Match quiz link this account has minted. |
| POST | /api/v1/match/links | Mint a public Candidate Match quiz link to put on a website button. |
| DELETE | /api/v1/match/links/{id} | Revoke one Candidate Match quiz link. |
| GET | /api/v1/match/profiles | Pull completed Candidate Match quizzes, keyset-paginated. |
| GET | /api/v1/match/profiles/deletions | Poll which Candidate Match profiles were deleted, so you can delete your copies. |
| DELETE | /api/v1/match/profiles/{id} | Erase one Candidate Match respondent on request. |
| GET | /api/v1/match/questions | Fetch the Candidate Match quiz that is live now for your organisation. |
| GET | /api/v1/match/questions/versions/{id} | Fetch the exact quiz an older profile was answered against. |
| POST | /api/v1/match/questions/preview | Check a proposed quiz change and get a preview link. Never changes the live quiz. |
| POST | /api/v1/match/questions/publish | Publish a proposed quiz change as a new version. Live on every quiz link at once. |
| GET | /api/v1/candidates/{id}/documents/{docId}/content | Download the bytes of a document’s latest submission. |
| GET | /api/v1/candidates/{id}/documents/{docId}/pages/{pageId}/content | Download the bytes of one page of a multi-page document. |
| GET | /api/v1/candidates/{id}/cv | Download the bytes of a candidate’s uploaded CV. |
| GET | /api/v1/candidates/{id}/attachments | List the files a candidate sent that the bot kept but could not match to a document, newest first. |
| GET | /api/v1/candidates/{id}/attachments/{attachmentId}/content | Download the bytes of one unmatched attachment. |
| 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, auto-send override, and schedule start date. |
| PATCH | /api/v1/candidates/{id}/churnguard/prefs | Pin a question set for this candidate, override whether their survey sends automatically, and/or set the job start date check-ins are scheduled from. |
| POST | /api/v1/candidates/{id}/churnguard/send | Mint (or reuse) this candidate’s survey placement and open its next scheduled check-in session over WhatsApp. |
| GET | /api/v1/churnguard/settings | Read your account’s defaults for whether a candidate’s survey sends automatically once their compliance process completes, and how often scheduled check-ins repeat. |
| POST | /api/v1/candidates/{id}/restart | Reset a candidate to a fresh start and re-send the consent request. |
| POST | /api/v1/candidates/{id}/qualifications | Hand over the qualifications a candidate claims, so Onboardly can collect evidence and check each one. |
| GET | /api/v1/candidates/{id}/qualifications | Read every qualification of one candidate with its current state. |
| GET | /api/v1/qualifications | Poll the results of every qualification across your candidates, oldest change first. |
| POST | /api/v1/outreach/prospects | Add a person who has agreed to be contacted, or refresh their contact details, so you can send them a first message. |
| GET | /api/v1/outreach/prospects/{id} | Read one outreach prospect of yours, including whether they have opted out or become a candidate. |
| POST | /api/v1/outreach/prospects/{id}/send | Send the approved first-contact WhatsApp message to an opted-in prospect. |
| GET | /api/v1/outreach/messages | Poll the messages to and from your prospects, newest change first. |
| POST | /api/v1/outreach/prospects/{id}/messages | Send a free-form WhatsApp reply to a prospect, only while their 24-hour reply window is open. |
| POST | /api/v1/outreach/prospects/{id}/promote | Turn a prospect into a normal Onboardly candidate (consent, documents, checks) without re-entering their details. |
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.