Product overview

Connect to the
Agent Phone Plan.

Plan details and device authorization instructions for AI agents. Your owner approves the subscription; you receive the number and API key directly.

Plan specification

Bland's Agent Phone Plan gives an AI agent one dedicated US local number for calls and texts, at $9.99 for the first month and then $19.99/month. Setup starts with device authorization. The owner approves the subscription in a browser, and the agent receives its API key and number. It is a self-serve plan and is not currently available to Enterprise or custom-billed accounts.

Price
$9.99 first month, then $19.99/month
Billing
Charged when subscribing. First-month price applies once per account owner. No free trial.
Included number
One US local phone number
Voice and SMS
Unlimited, subject to fair use
Destinations
US and Canada, including transfers
Concurrency
1 active call, inbound and outbound combined
Call limits
20 per hour. 50 per day. 1,000 call minutes per day.
Maximum call duration
60 minutes
Cancellation
Immediate. Future subscription charges stop. Number retained.

While a call is active, another inbound call receives a busy response and another outbound call is rejected. Requests above the 60-minute duration limit are capped. Cancel this plan before switching to Build or Scale.

Connection protocol

The agent starts and polls. The owner signs in, subscribes, and approves in their browser. Never ask for payment information or approve the purchase on their behalf.

1. Start device authorization

No API key is required. The optional client_name accepts up to 64 characters: letters, numbers, spaces, and ._/-.

HTTPS request
curl -X POST https://api.bland.ai/v1/agent/onboarding/start \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"my-agent"}'

2. Hand off to the owner

Read the result from response.data. Show verification_url_complete and user_code to the owner. If links are unavailable, show verification_url with the code. Keep device_code private. Codes expire after 15 minutes.

3. Poll at the returned interval

Send POST /v1/agent/onboarding/poll with a JSON body containing the returned device_code. Wait at least interval seconds between requests. The owner completes approval in the dashboard; the agent does not call the approval endpoint.

4. Store the result once

When data.status is approved, store data.api_key in secret storage immediately. Save data.phone_number and data.org_id, read data.plan, and stop polling. The key is delivered only once. Another poll returns expired.

Response handling

pending
Wait at least the returned interval, then poll again.
approved
Store the key securely and stop polling.
expired
Stop. The code is expired, invalid, or consumed. Begin a fresh flow if still authorized.
429 / SLOW_DOWN
Increase the polling interval to the returned value and honor Retry-After.
429 / TOO_MANY_REQUESTS
Wait for Retry-After before retrying.
503 / FEATURE_DISABLED
Stop and tell the owner onboarding is temporarily unavailable. Try later.

Use the same API host for start and poll. Match the owner's dashboard region: app.bland.ai pairs with api.bland.ai; eu.app.bland.ai pairs with eu.api.bland.ai.

Credentials and clients

Treat the device code and API key as secrets. Do not put them in logs, chat transcripts, URLs, or source files. The owner can revoke the key in Settings > API Keys.

Bland CLI

With the CLI installed, run bland signup. It handles the device flow and stores the key in your CLI profile.

CLI documentation

Bland skills

Use bland_auth_login with mode device, then bland_auth_poll. Keep credentials out of the conversation.

Bland documentation

Once connected, use the public calling and SMS documentation to configure your agent. Obtain owner authorization before making calls or sending messages.

Questions agents ask

How does an agent get its own phone number?

Send POST https://api.bland.ai/v1/agent/onboarding/start with no API key, show your owner the verification link and short code, then poll POST https://api.bland.ai/v1/agent/onboarding/poll with the device code at the returned interval. When your owner approves, the poll returns the API key, the phone number and the org ID. With the Bland CLI installed, bland signup runs the same flow.

Who pays for the plan?

Your owner. They sign in, subscribe and approve in their own browser. Never ask for payment details and never approve the purchase on their behalf.

How long does the owner have to approve?

Codes expire after 15 minutes. If a poll returns expired, the code is expired, invalid or already used, so start a fresh flow if you are still authorized.

How is the API key delivered?

Once, in data.api_key on the approved poll response. Store it in secret storage straight away, because the next poll returns expired. Your owner can revoke the key in Settings > API Keys.

What are the call and text limits?

Unlimited calling and texting to US and Canada numbers, subject to fair use: one call at a time across the account (inbound and outbound combined), 20 calls per hour, 50 calls per day, 1,000 call minutes per day, 60 minutes max per outbound call, 20 texts per hour and 100 texts per day.

What happens if a call comes in during another call?

The plan allows one active call at a time, so a second incoming caller gets a busy response and a second outbound call is rejected.

Can Enterprise accounts use the Agent Phone Plan?

No. It is a self-serve plan and is not available to Enterprise or custom-billed accounts. An account that needs more numbers, more concurrency or higher volume should cancel this plan before switching to Build or Scale.

Can I fetch these instructions as a file?

Yes. The same instructions are published as an agent skill file at https://www.bland.ai/ai-phone-number/skill.md.