Quickstart

Create a candidate, poll for the outcome, and download the compliance pack — end to end.

This walkthrough takes one candidate from creation to a downloaded compliance pack, without sending a real WhatsApp message until step 5 — when you choose to.

1
Get an API key
In the Onboardly dashboard, go to /settings/integrations → API keys (inbound) → Create key. Copy the value from the one-time reveal panel — it is never shown again. You may hold up to 5 active keys at once.
Export it once, use it in every sample below
```
export ONB_KEY="onb_live_…"
```

Create a candidate without sending anything

Create with start: false — this seeds the candidate and their document checklist without messaging them.

Shell

curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Idempotency-Key: ats-record-4471" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jordan","last_name":"Ellis","email":"jordan.ellis@example.com","mobile_number":"+447700900321","opt_in":true,"opt_in_source":"ats_import","opt_in_at":"2026-09-01T09:00:00Z","start":false}'

Expect: 201, documentsSeeded/referencesSeeded reflect what you sent, outbound is ABSENT. The candidate now shows in your dashboard, awaiting consent.

3
Replay is safe
Send the exact same request again (same Idempotency-Key) — nothing new is created.
Expect: 200 { "data": { "id": "…", "replayed": true }, "error": null }.
4
Read the candidate back
GET /candidates/{id} using the id from step 2.
Expect: external_id echoes ats-record-4471; documents are all pending; compliance_pack.ready is false.
5
Send the real opener (optional, needs a handset you control)
Create a SECOND candidate — a new record, a new Idempotency-Key — with start: true and a phone number that is not already on your account.
Expect: 201 with "outbound": "sent". WhatsApp is only ever sent on the literal true.
6
Make corrections as they come in
Use PATCH /candidates/{id} for a profile fix, POST /candidates/{id}/documents to add a checklist item you forgot, or PATCH /candidates/{id}/outreach to change how hard this one candidate is chased.
7
Poll for completion
Every 15–30 minutes, GET /candidates/{id} and check compliance_pack.ready (and reference_requirements.outstanding === 0 if references matter to you).
8
Fetch the evidence
Follow each accepted document’s content_url, then download the pack.
Shell
```
curl "https://rca-onboardly.com/api/v1/candidates/{id}/pack" -H "X-Api-Key: $ONB_KEY" -H "Accept: application/zip" -o compliance-pack.zip
```
Expect: 409 with meta.blockers until every required document is accepted — keep polling rather than retrying blindly.

PreviousOverview NextAuthentication