Skip to main content

Phone numbers

Numbers your org owns are what agents dial from, and what inbound calls land on.

Buying a number​

Searching Twilio's live inventory and purchasing a number both require a real payment method on file, so both happen through the dashboard, not via API key — the purchase flow collects a Stripe payment method client-side and needs a real logged-in billing contact, not a headless script.

Once a number is purchased, everything else about it is available through the API.

Managing numbers you own​

# List your org's numbers
curl https://convostack.ai/api/phone-numbers \
  -H "Authorization: Bearer cak_live_..."

# One number in detail
curl https://convostack.ai/api/phone-numbers/{id} \
  -H "Authorization: Bearer cak_live_..."

# Assign an agent to a number (inbound calls to it will reach that agent)
curl -X PATCH https://convostack.ai/api/phone-numbers/{id}/assigned-agent \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"}'

# Unassign — pass null
curl -X PATCH https://convostack.ai/api/phone-numbers/{id}/assigned-agent \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agentId": null}'

# Rename
curl -X PATCH https://convostack.ai/api/phone-numbers/{id}/friendly-name \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"friendlyName": "Main support line"}'

# Release — cancels billing for the number and returns it to Twilio
curl -X POST https://convostack.ai/api/phone-numbers/{id}/release \
  -H "Authorization: Bearer cak_live_..."

Releasing is not reversible — the number goes back into the general Twilio pool and you'd have to search for and purchase it again (if it's even still available) to get it back.

Using a number as caller ID​

Pass a number's id as fromPhoneNumberId when placing a call or creating a campaign. If you own the number, the call goes out with it as caller ID; omit it to use the platform default.