Onboardly
Get started

Partner API Create candidates, collect documents and references, retrieve the compliance pack.

Get an API key

Add documents

Add one or more document requests to a candidate’s checklist after creation.

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

Add one or more document requests to a candidate’s checklist.

Headers

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

Request fields

documents(string | { name, customInstructions? })[]required
1–50 entries. name up to 200 characters, any value accepted. customInstructions up to 2000 characters.

Status codes

2002xx
The names not already on the checklist were added; added lists only the new ones.
4004xx
Malformed body, too many entries, or a name/instructions field over its length cap.
Invalid request bodyNo document names suppliedA single request can add at most 50 documents
4014xx
Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.
4034xx
The key’s user has the viewer team role, or their account could not be read just then (retry) — or the key was created Read only (code: "key_read_only", refused before anything else). Checked before the body or any id — see Authentication.
Your team role doesn't allow this. Ask your team's admin or owner.This API key is read-only. Create a full-access key to make changes.
4044xx
Unknown, cross-tenant, or (a candidate id) sandbox-hidden. One outcome, never a 403.
Not found
4094xx
Every requested name is already on this candidate’s checklist.
Every requested document is already on this checklist
4294xx
Per-key or per-account rate limit exceeded. Retry after the Retry-After header.
Too many requests — please try again shortly.
5005xx
The insert could not be verified as written, or the service is temporarily unavailable.
Failed to add documentThis resource is temporarily unavailable. Try again shortly.
  • Any name is accepted — see Document names for how the bot asks about a name outside its nine-entry catalogue.
  • The 409 fires only when EVERY requested name duplicates an existing (or another requested) entry — a request mixing one new and one duplicate name succeeds and adds the new one.
  • If the candidate’s WhatsApp conversation has already started, the added document is now asked for on that same conversation — it no longer only shows up in the checklist rows this endpoint returns.
cURL
curl -X POST \
  "https://rca-onboardly.com/api/v1/candidates/<candidate id>/documents" \
  -H "X-Api-Key: $ONB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "documents": [
    "Training Certificate",
    {
      "name": "Proof of Address",
      "customInstructions": "Dated within the last 3 months"
    }
  ]
}'
Request body
{
  "documents": [
    "Training Certificate",
    {
      "name": "Proof of Address",
      "customInstructions": "Dated within the last 3 months"
    }
  ]
}
200 · Response
{
  "added": [
    "Training Certificate",
    "Proof of Address"
  ]
}

See Document names for how a name outside the nine-entry catalogue is handled.

PreviousUpdate outreach settingsNextRetrieve messages