Outreach

Headers

X-Api-Keyonb_live_<key_id>_<secret>required

Your issued Partner API key — see Authentication.

Request fields

phonestringrequired

E.164, for example +447700900321. Identifies the person within your account.

first_namestringrequired

1 to 100 characters, plain text.

last_namestring or nulloptional

Up to 100 characters.

emailstring or nulloptional

Up to 320 characters. The shape is checked; delivery is not.

external_refstring or nulloptional

Your own id for the person, up to 128 characters.

opt_inobjectrequired

The proof the person agreed to be contacted. All three fields inside it are required. It is stored once and never overwritten by a later call.

opt_in.sourcestringrequired

One of application_form, candidate_match, partner_attested, candidate_initiated.

opt_in.atstringrequired

ISO 8601 date and time with a zone, for example 2026-10-20T09:30:00Z. Not in the future and not older than 24 months.

opt_in.evidence_refstringrequired

1 to 512 characters. An opaque reference to your record of the consent (a form-submission id), never a link.

Status codes

2012xx

Prospect created.

2002xx

The person was already a prospect of yours. Their contact fields were refreshed; the stored opt-in was not changed.

4004xx

The body is too large (over 4096 characters), is not a JSON object, has a key this endpoint does not accept, or a field is refused. Read code: body_too_large, invalid_json, unknown_field, invalid_phone, invalid_first_name, invalid_last_name, invalid_email, invalid_external_ref, opt_in_required, invalid_opt_in_source, invalid_opt_in_at, opt_in_at_in_future or invalid_opt_in_evidence_ref.

The request body is too large.The request body must be a JSON object.The request body has a field this endpoint does not accept.phone must be an E.164 number such as +447700900123.first_name is required and must be a short plain name.last_name must be a short plain name.email must be a valid e-mail address.external_ref must be a short plain reference.opt_in is required, with source, at and evidence_ref.opt_in.source is not an accepted value.opt_in.at must be an ISO 8601 date and time, and recent enough to still count as consent.opt_in.at must not be in the future.opt_in.evidence_ref is required and must be a short plain reference, not a link.

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

Outreach is switched off for the deployment. The body is EMPTY.

4094xx

Refused. code is opted_out (your own account holds a STOP or opt-out for this number) or promoted (the person has already become a candidate). Neither clears on retry.

This person has opted out and cannot be contacted.This person has already moved on to onboarding.

4294xx

Per-key or per-account rate limit exceeded. Retry after the Retry-After header.

Too many requests — please try again shortly.

5035xx

A read or write failed, or the service is not ready. Retry shortly.

Temporarily unavailable. Try again shortly.

Headers

X-Api-Keyonb_live_<key_id>_<secret>required

Your issued Partner API key — see Authentication.

Status codes

2002xx

The prospect. The opt-in evidence reference and the candidate it became are not returned.

4014xx

Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.

4044xx

The outreach switch is off (an EMPTY body), or the prospect id is unknown, belongs to another account, or is not a valid id. The last three are one identical response, never a 403.

Not found

4294xx

Per-key or per-account rate limit exceeded. Retry after the Retry-After header.

Too many requests — please try again shortly.

5035xx

A read or write failed, or the service is not ready. Retry shortly.

Temporarily unavailable. Try again shortly.

Headers

X-Api-Keyonb_live_<key_id>_<secret>required

Your issued Partner API key — see Authentication.

Idempotency-Key<your own send id>required

Required, 1–255 characters. Use a new key for each message you want sent. Repeating a key after a delivered message returns that delivery; repeating it for a different request is a 409 idempotency_key_conflict.

Request fields

consultant_namestringrequired

The name the message is sent from. Plain text, up to 60 characters, no links.

role_titlestringrequired

The role the message mentions. Plain text, up to 60 characters, no links.

Status codes

2002xx

data.status is sent. message_id is our id for the message, or null if it cannot be found. Repeating the same Idempotency-Key after a delivery returns the same result.

2022xx

data.status is held. Nothing was sent. Retry later with a NEW Idempotency-Key.

4004xx

Read code: idempotency_key_required, body_too_large, invalid_json, unknown_field, invalid_consultant_name, invalid_role_title (not a string), or invalid_variables (a value is empty, too long, or not acceptable in a first message).

An Idempotency-Key header is required (max 255 characters).The request body is too large.The request body must be a JSON object.The request body has a field this endpoint does not accept.consultant_name is required and must be a short plain name.role_title is required and must be a short plain job title.consultant_name or role_title is not acceptable in a first message.

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.

4024xx

Your plan has ended (code: "no_subscription") or this month’s messages are used up (code: "over_message_quota"). Nothing was sent or written. Choose or upgrade a plan, or wait until the 1st. Replies inside an open chat are never refused for the message limit.

5035xx

We could not check your plan just now (code: "billing_unavailable"). Nothing was sent; retry shortly.

4044xx

The outreach switch is off (an EMPTY body), or the prospect id is unknown, belongs to another account, or is not a valid id. The last three are one identical response, never a 403.

Not found

4094xx

Not sent. Read code: not_sendable (this prospect cannot be messaged right now; one response for several causes, which are deliberately not told apart), opted_out, promoted, opt_in_missing, quiet_hours (try again later), undeliverable (the number cannot receive WhatsApp) or idempotency_key_conflict.

This prospect can't be messaged right now.This person has opted out and cannot be contacted.This person has already moved on to onboarding.This prospect has no opt-in record.Outside your sending hours. Try again later.This number can't receive WhatsApp messages.This Idempotency-Key was already used for a different request.

4294xx

A rate limit (retry after the Retry-After header), or a daily cap: recruiter_daily_cap (your own account’s) or platform_cap (the shared limit). Try again later.

Too many requests — please try again shortly.Your account has reached its daily first-message limit. Try again later.The daily sending limit has been reached. Try again later.

5035xx

The first-contact message is not available (template_unavailable), or a read or write failed (unavailable). Retry shortly.

The first-contact message is not available right now.Temporarily unavailable. Try again shortly.

Headers

X-Api-Keyonb_live_<key_id>_<secret>required

Your issued Partner API key — see Authentication.

Request fields

limitintegeroptional

25 if omitted, up to 100. Never clamped — an out-of-range value is a 400.

cursorstringoptional

Opaque. Pass back the previous page’s next_cursor verbatim; omit for the first page.

updated_sincestring (ISO-8601)optional

ISO-8601 timestamp with a timezone. Keeps messages whose updated_at is at or after it.

prospect_idstringoptional

Only this prospect’s messages. An id that is not yours returns an empty page.

Status codes

2002xx

A page of messages, newest change first. Keep going until next_cursor is null.

4004xx

An out-of-range or malformed query parameter, or a malformed cursor. prospect_id that is not a valid id is invalid_prospect_id.

Invalid query parameter: {param}Invalid or expired cursorprospect_id must be a valid prospect id.

4014xx

Missing, malformed, unknown, revoked or expired key. Every authentication failure looks the same — see Authentication.

4294xx

Per-key or per-account rate limit exceeded. Retry after the Retry-After header.

Too many requests — please try again shortly.

5035xx

A read or write failed, or the service is not ready. Retry shortly.

Temporarily unavailable. Try again shortly.

Headers

X-Api-Keyonb_live_<key_id>_<secret>required

Your issued Partner API key — see Authentication.

Idempotency-Key<your own send id>required

Required, 1–255 characters. Use a new key for each message you want sent. Repeating a key after a delivered message returns that delivery; repeating it for a different request is a 409 idempotency_key_conflict.

Request fields

bodystringrequired

The message text, 1 to 1000 characters. Line breaks are allowed. Links are not allowed, except to domains agreed with Onboardly in advance (and their subdomains): a body with any other web address is refused with invalid_body.

Status codes

2002xx

data.status is sent. message_id is our id for the message. Repeating the same Idempotency-Key with the same body returns the same result.

2022xx

data.status is held. Nothing was sent. Retry with a NEW Idempotency-Key.

4004xx

Read code: idempotency_key_required, body_too_large, invalid_json, unknown_field or invalid_body.

An Idempotency-Key header is required (max 255 characters).The request body is too large.The request body must be a JSON object.The request body has a field this endpoint does not accept.body is required and must be plain text within the reply length limit, with no {{ placeholders and no links (other than to domains agreed with Onboardly).

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.

4024xx

Your plan has ended (code: "no_subscription") or this month’s messages are used up (code: "over_message_quota"). Nothing was sent or written. Choose or upgrade a plan, or wait until the 1st. Replies inside an open chat are never refused for the message limit.

5035xx

We could not check your plan just now (code: "billing_unavailable"). Nothing was sent; retry shortly.

4044xx

The outreach switch is off (an EMPTY body), or the prospect id is unknown, belongs to another account, or is not a valid id. The last three are one identical response, never a 403.

Not found

4094xx

Not sent. Read code: session_window_closed (this person has not written in the last 24 hours), not_sendable (one response for several causes, deliberately not told apart), opted_out, promoted, opt_in_missing, undeliverable or idempotency_key_conflict.

This person's 24-hour reply window is closed, so a free-form message can't be sent.This prospect can't be messaged right now.This person has opted out and cannot be contacted.This person has already moved on to onboarding.This prospect has no opt-in record.This number can't receive WhatsApp messages.This Idempotency-Key was already used for a different request.

4294xx

A rate limit (retry after the Retry-After header), or reply_limit: you have already sent the most replies allowed to this person in the current 24-hour window.

Too many requests — please try again shortly.The reply limit for this person has been reached for the current 24-hour window.

5035xx

A read or write failed, or the service is not ready. Retry shortly.

Temporarily unavailable. Try again shortly.

Headers

X-Api-Keyonb_live_<key_id>_<secret>required

Your issued Partner API key — see Authentication.

Idempotency-Key<your own send id>required

Required, 1–255 characters. Use a new key for each message you want sent. Repeating a key after a delivered message returns that delivery; repeating it for a different request is a 409 idempotency_key_conflict.

Request fields

documentsstring[]optional

The documents to collect, exactly as on Create a candidate.

qualificationsobject[]optional

Qualification checks to record, exactly as on Create a candidate.

application_form_sectionsstring[]optional

Which parts of the application form are shown, exactly as on Create a candidate.

startbooleanoptional

Defaults to true: Onboardly sends the first WhatsApp message to the new candidate. Send false to create the candidate and start later with Start a candidate.

Status codes

2012xx

The candidate was created from the prospect. started is true when the first WhatsApp message went out. Repeating the same Idempotency-Key returns the same result with replayed: true.

4004xx

Read code: idempotency_key_required, body_too_large, invalid_json, unknown_field or invalid_promote_request. Name, number and e-mail cannot be sent: they come from the prospect.

An Idempotency-Key header is required (max 255 characters).The request body is too large.The request body must be a JSON object.The request body has a field this endpoint does not accept.The promotion request is not acceptable: check start, documents, qualifications and application_form_sections.

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

The outreach switch is off (an EMPTY body), or the prospect id is unknown, belongs to another account, or is not a valid id. The last three are one identical response, never a 403.

Not found

4094xx

Read code: already_promoted and candidate_exists (both carry candidate_id when known), opted_out, prospect_incomplete (add a last name and an e-mail to the prospect first), or not_sendable (one response for several causes, deliberately not told apart).

This person has already been promoted to a candidate.You already have a candidate with this number or e-mail.This person has opted out and cannot be contacted.This prospect needs a last name and an e-mail before it can become a candidate.This prospect can't be messaged right now.

4024xx

Your plan does not allow another candidate (the same refusal as Create a candidate).

4294xx

Per-key or per-account rate limit exceeded. Retry after the Retry-After header.

Too many requests — please try again shortly.

5035xx

A read or write failed, or the service is not ready. Retry shortly.

Temporarily unavailable. Try again shortly.