Agent Onboarding
Poll Agent Onboarding
Poll for the result of a device-authorization flow started with /v1/agent/onboarding/start. No API key required.
POST
Poll Agent Onboarding
Overview
No authentication is required for this endpoint. Call it with thedevice_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