Manage Phone Numbers

Bolna Phone Numbers

Buy, list, and manage dedicated DIDs through Bolna. US numbers come from Twilio; Indian numbers from Plivo (Karnataka, Maharashtra) or Vobiz (Karnataka, Gujarat, NCR). Flat $5/month rental per number, billed from the wallet.

For numbers you bring on your own SIP trunk (Twilio Elastic, Plivo Zentrunk, Telnyx, etc.), see setup-sip-trunk.

Endpoints

Auth: Authorization: Bearer $BOLNA_API_KEY.

What you can do with a Bolna-hosted number

List your numbers

curl https://api.bolna.ai/phone-numbers/all \
  -H "Authorization: Bearer $BOLNA_API_KEY"

Important fields on each response item:

Search before buying

# US numbers in the 718 area code
curl "https://api.bolna.ai/phone-numbers/search?country=US&pattern=718" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

# India - Plivo - Karnataka (80)
curl "https://api.bolna.ai/phone-numbers/search?country=IN&provider=plivo&region=80" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

# India - Vobiz - NCR (11)
curl "https://api.bolna.ai/phone-numbers/search?country=IN&provider=vobiz&region=11" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

Region codes

US numbers don't have a region filter — use pattern (area code prefix) instead.

Buy

curl -X POST https://api.bolna.ai/phone-numbers/buy \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "phone_number": "+17182718146",
    "provider": "twilio"
  }'

For India:

curl -X POST https://api.bolna.ai/phone-numbers/buy \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "IN",
    "phone_number": "+918012345678",
    "provider": "plivo"
  }'

Response includes the new id — save it for inbound mapping.

After purchase — wire to an inbound agent

curl -X POST https://api.bolna.ai/inbound/setup \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'$AGENT_ID'",
    "phone_number_id": "'$PHONE_NUMBER_ID'"
  }'

(Full detail in setup-inbound/SKILL.md.)

Pricing

• $5/month per number, charged to your wallet on renewal_at.
• Call charges are separate — per-minute telephony costs (Twilio/Plivo/Vobiz) plus Bolna's platform fee.
• The wallet runs the show — if it's low, POST /call will land in balance-low. Check with GET /user/me.

India: 140 / 160-series numbers

These are not ordinary numbers. Selling commercial calls in India requires:

Plan 2-4 weeks to go live. Full process in ../references/india-compliance.md.

You cannot buy 140/160 numbers through /phone-numbers/buy without completing compliance first — the carrier rejects the allocation. Surface this prerequisite up front when a user asks for Indian regulated numbers.

Delete

curl -X DELETE "https://api.bolna.ai/phone-numbers/$PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

Deletion:

• Stops inbound routing immediately (if mapped).
• Stops the $5/month rent at next renewal.
• Cannot be undone — you'd need to buy a new number.

Always confirm with the user before deleting, especially if the number is mapped to an active inbound agent (agent_id non-null in the list response).

Bolna-hosted vs your own provider

For each, the setup-inbound flow is the same once a phone_number_id exists.

Going deeper

See also

• setup-inbound — map a purchased number to an agent.
• make-call — use a number as from_phone_number for outbound.
• setup-sip-trunk — for BYOT trunks (different lifecycle, separate endpoints).
• add-provider — to connect your own Twilio/Plivo/Vobiz/Exotel and use their numbers.