Skip to content
OnCoreDocs
WhatsApp

GEThttps://core-api.heysadie.ai/whatsapp/onboarding-sessions/{id}

id success data status failureReason blame userMessage retryAfterHours verificationCallOverdue metadata timestamp version path error code message details field

Get onboarding session

Fetch the current onboarding status. State machine: `pending → authorized → verifying → [tier_pending] → completed → live`, with terminal `failed` / `name_rejected` / `abandoned`. A `pending` session past its 15-minute TTL is reported as `abandoned`; a session stranded past its TTL self-heals to `failed` — with `failureReason: "stalled"` if it crashed in `authorized` (no verification call placed), or `failureReason: "otp_call_timeout"` if it was stuck in `verifying` (the call was placed but never completed). `failureReason` is populated on failure states. While a session is `verifying`, if the verification call was placed more than ~5 minutes ago (but has not yet timed out), the response also carries `verificationCallOverdue: true` — a soft signal to prompt the customer to resend or cancel before the terminal `otp_call_timeout`. When `failureReason` is `otp_request_limit`, the response also carries `retryAfterHours` — the same cooldown a webhook subscriber receives in `data.retryAfterHours`. Onboarding progress is also pushed via the reseller webhooks — see the create-session docs for the signed webhook contract.

Try it in the API Explorer

Example request

Terminal
curl "https://core-api.heysadie.ai/whatsapp/onboarding-sessions/ONBOARDING_SESSION_ID" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Authentication

Authenticate with an API key in the Authorization header using the ApiKey scheme — see Authentication for how keys work and where to get them.

Authorizationstringrequired

API key in the ApiKey scheme: ApiKey YOUR_API_KEY. Tenant keys authorize their own tenant; organization keys can act on any tenant in the organization.

X-Tenant-Idstring (uuid)optional

Required when authenticating with an organization key — selects the tenant the request acts on. Omit with tenant keys.

Request

Path parameters

idstringrequired

The resource's UUID.

Responses

200
successbooleanrequired
dataobjectoptional
Show 6 child properties
statusstringrequired

pending → authorized → verifying → [tier_pending] → completed → live | failed | name_rejected | abandoned

failureReasonstringoptional

Present on terminal failure states.

blamestringoptional

Present on terminal failure states. `customer` = the account owner must act (e.g. restricted WABA, rejected name, revoked token) — the reseller resolves it with their customer; `system` = Sadie/Meta-side — hand to Sadie.

userMessagestringoptional

Present on terminal failure states. Human-readable, end-user-facing message safe to show the customer (Meta's own text for account-side problems, or Sadie's curated copy).

retryAfterHoursnumberoptional

Present when `failureReason` is `otp_request_limit`: hours to wait before retrying (Meta's registration lockout window). Parity with the `data.retryAfterHours` a webhook subscriber already receives.

verificationCallOverduebooleanoptional

Present (and `true`) only while `status` is `verifying` and the last verification call was placed more than ~5 minutes ago but the session has not yet timed out. A soft, derived signal (no state change) that a reseller UI should prompt the customer to Resend or Cancel. Absent otherwise.

metadataobjectoptional
Show 3 child properties
timestampstringrequired
versionstringrequired
pathstringoptional
400
successbooleanrequired
errorobjectoptional
Show 3 child properties
codeenumrequired
Allowed values:"VALIDATION_ERROR"
messagestringrequired
detailsobject[]optional
Show 2 item properties
fieldstringrequired
messagestringrequired
metadataobjectoptional
Show 3 child properties
timestampstringrequired
versionstringrequired
pathstringoptional
401
successbooleanrequired
errorobjectoptional
Show 2 child properties
codeenumrequired
Allowed values:"UNAUTHORIZED"
messagestringrequired
metadataobjectoptional
Show 3 child properties
timestampstringrequired
versionstringrequired
pathstringoptional
403
successbooleanrequired
errorobjectoptional
Show 2 child properties
codeenumrequired
Allowed values:"FORBIDDEN"
messagestringrequired
metadataobjectoptional
Show 3 child properties
timestampstringrequired
versionstringrequired
pathstringoptional
404
successbooleanrequired
errorobjectoptional
Show 2 child properties
codeenumrequired
Allowed values:"RESOURCE_NOT_FOUND"
messagestringrequired
metadataobjectoptional
Show 3 child properties
timestampstringrequired
versionstringrequired
pathstringoptional
500
successbooleanrequired
errorobjectoptional
Show 2 child properties
codeenumrequired
Allowed values:"INTERNAL_SERVER_ERROR"
messagestringrequired
metadataobjectoptional
Show 3 child properties
timestampstringrequired
versionstringrequired
pathstringoptional