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: it selects the tenant the request acts on. Omit with tenant keys.

Request

Path parameters

idstringrequired

The resource's UUID.

Responses

200
successbooleanrequired

true on every 2xx

dataobjectoptional

The result

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

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

400The request is invalid. `details` lists each field that failed
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 3 child properties
codeenumrequired

A parameter or body field broke a rule

Allowed values:"VALIDATION_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

detailsobject[]optional

One entry per field that failed

Show 2 item properties
fieldstringrequired

The offending field

messagestringrequired

The rule it broke

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

401Missing or invalid credentials
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

No valid credentials

Allowed values:"UNAUTHORIZED"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

403The credentials are valid but may not use this route
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

The credentials may not use this route

Allowed values:"FORBIDDEN"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

404Not found, or outside the caller's scope
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An id names nothing the caller can see

Allowed values:"RESOURCE_NOT_FOUND"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested

500An unexpected server error
successbooleanrequired

false on every error

errorobjectoptional

What went wrong: a stable `code` to branch on and a human-readable `message`

Show 2 child properties
codeenumrequired

An unexpected server failure

Allowed values:"INTERNAL_SERVER_ERROR"
messagestringrequired

Human-readable explanation. Do not parse it; branch on `code`

metadataobjectoptional

Request metadata

Show 3 child properties
timestampstringrequired

When the server answered, ISO 8601 UTC

versionstringrequired

API version

pathstringoptional

The URL that was requested