Skip to main content
POST
Poll Agent Onboarding

Overview

No authentication is required for this endpoint. Call it with the device_code from /v1/agent/onboarding/start, waiting at least the returned interval seconds between calls. See the Agent onboarding API for the full flow.
This endpoint has two independent 429 responses: SLOW_DOWN when you poll faster than the per-device interval, and TOO_MANY_REQUESTS from the per-IP rate limit (600 requests per minute per IP, since a hosting platform’s shared egress address can carry many bots), which carries a Retry-After header instead of interval.

Body Parameters

string
required
The device_code returned by /v1/agent/onboarding/start.

Response

object
Current state of the flow.
string
One of pending, approved, expired.
number
Present when status is pending. Minimum seconds to wait before polling again.
number
Present when status is pending. Seconds remaining before the codes expire.
string
Present only when status is approved. A dedicated API key for the org, returned exactly once.
string
Present when status is approved. The org the key belongs to.
string | null
Present when status is approved. The number provisioned for this org, or null when the owner connected the bot without the Agent Phone Plan. Without the plan, calls go out from Bland’s shared pool of numbers and texting is not included.
object
Present when status is approved. The org’s Agent Phone Plan subscription. When the owner connected the bot on free credits instead, plan.status is none and every other plan field is null. The same object is returned by GET /billing/agent_phone (as data) and by GET /v1/me (as plan).
string | null
Internal plan identifier, agent_phone_basic. null when there is no plan.
string | null
Human-readable plan name, Agent Phone Plan. null when there is no plan.
string
Subscription status: active, or none when the org has no Agent Phone Plan.
string | null
The number provisioned for this org’s Agent Phone Plan. null when there is no plan.
number | null
Maximum concurrent calls, 1. null when there is no plan.
number | null
Maximum call length in minutes, 60. null when there is no plan.
array | null
Country codes calls, transfers, and SMS are allowed to, ["US", "CA"]. null when there is no plan.
string | null
ISO 8601 timestamp for the end of the current billing period. null when there is no plan.
string
Present when status is approved, if a client_name was given to /start.
null | array
null unless polling too fast.
An expired status covers both an expired code and a device_code that was never valid. The two aren’t distinguished, so don’t rely on this response to debug a mistyped code, start over with a new /start call instead.

Docs for agents: llms.txt