Phone Number Management
Search, purchase, and manage phone numbers via Twilio integration. Numbers are automatically debited from your account balance and can be assigned to SIP trunks for inbound/outbound calling.
Search Available Numbers
/api/v1/account/{accountId}/numbers/catalog?country=US&area_code=415&limit=10Search for available phone numbers by country, area code, or specific patterns using Twilio's inventory.
▶HTTP Headers
About This Endpoint
Query Twilio's real-time phone number inventory to discover available numbers matching your geographic, numeric, or capability requirements. Search by country code for international numbers, filter by area code or region for local presence, or specify numeric patterns to find vanity numbers. Each result includes detailed location information, voice/SMS/MMS capabilities, and transparent pricing data including setup fees and recurring monthly costs. The search returns immediately available numbers ready for instant purchase.
Search Capabilities
- Filter by country (ISO code), area code, region, or city for geographic targeting
- Pattern matching with "contains" parameter to find memorable or vanity numbers
- Results include voice/SMS/MMS capabilities and exact pricing before purchase
Common Use Cases
- Finding local numbers in specific cities to establish regional business presence
- Searching for toll-free numbers or vanity numbers with specific digit patterns
- Checking number availability and pricing before budgeting telecommunications costs
Query Parameters
| Parameter | Type | Description |
|---|---|---|
country | string | ISO country code (e.g., US, CA, GB) |
area_code | string | Area code to search (e.g., 415, 212) |
contains | string | Pattern to match in phone number |
limit | integer | Max results to return (default: 20) |
Response Example
{
"status": "success",
"data": {
"numbers": [
{
"phoneNumber": "+14155551234",
"friendlyName": "+1 (415) 555-1234",
"locality": "San Francisco",
"region": "CA",
"postalCode": "94102",
"country": "US",
"capabilities": {
"voice": true,
"sms": true,
"mms": false
},
"pricing": {
"setupFee": 0,
"monthlyFee": 100,
"currency": "USD"
}
},
{
"phoneNumber": "+14155559876",
"friendlyName": "+1 (415) 555-9876",
"locality": "San Francisco",
"region": "CA",
"postalCode": "94103",
"country": "US",
"capabilities": {
"voice": true,
"sms": true,
"mms": true
},
"pricing": {
"setupFee": 0,
"monthlyFee": 100,
"currency": "USD"
}
}
],
"totalFound": 47
}
}Purchase Number
/api/v1/account/{accountId}/numbers/purchasePurchase a phone number from the available inventory. The setup fee and first month's charges are automatically debited from your account balance.
▶HTTP Headers
Balance Requirement
Ensure your account has sufficient balance to cover setup fees and monthly charges before purchasing.
About This Endpoint
Instantly acquire a phone number from search results by purchasing it directly through Twilio integration. The purchase process automatically debits your account balance for setup fees and first month's recurring charges, provisions the number in Twilio's system, and optionally assigns it to a specified SIP trunk for immediate inbound call routing. The transaction is atomic—either the purchase completes fully with balance deduction and number provisioning, or it fails entirely with no charges.
Purchase Process
- Validates sufficient account balance before initiating purchase with Twilio
- Automatically debits setup fee + first month's charge from your balance
- Optionally assigns number to trunk ID for immediate inbound call configuration
Important Considerations
- Purchase fails if account balance insufficient—add funds via Balance API first
- Monthly billing cycle begins immediately from purchase timestamp
- Numbers become active within seconds and ready for inbound/outbound calls
{
"country": "US",
"numbers": [
"+14155550100"
],
"voice": true,
"sms": false,
"currency": "USD"
}Response Example
{
"status": "success",
"message": "Phone number purchased successfully",
"data": {
"id": "NUM_7a8b9c0d1e2f",
"phoneNumber": "+14155551234",
"friendlyName": "+1 (415) 555-1234",
"country": "US",
"region": "CA",
"locality": "San Francisco",
"status": "active",
"trunkId": "TRK_8f9e0a1b2c3d",
"capabilities": {
"voice": true,
"sms": true,
"mms": false
},
"pricing": {
"setupFee": 0,
"monthlyFee": 100,
"currency": "USD"
},
"purchasedAt": "2025-01-15T10:30:00.000Z",
"billingCycle": "monthly",
"nextBillingDate": "2025-02-15T00:00:00.000Z",
"transaction": {
"id": "TXN_9d8e7f6g5h4i",
"amount": 100,
"currency": "USD",
"description": "Phone number setup: +14155551234"
}
}
}List Purchased Numbers
/api/v1/account/{accountId}/numbersRetrieve all phone numbers owned by your account with their current status and assignment details.
▶HTTP Headers
About This Endpoint
Retrieve a comprehensive inventory of all phone numbers currently owned by your account, including assignment status, trunk associations, billing information, and capabilities. Each number entry shows whether it's assigned to a SIP trunk or unassigned, displays next billing date for renewal tracking, and includes monthly cost data. The response aggregates total monthly costs across all numbers, enabling accurate telecommunications expense forecasting and budget management for your organization.
Inventory Details
- Complete number portfolio with status, trunk assignments, and capabilities
- Billing information including monthly fees, next billing dates, and purchase timestamps
- Aggregate monthly cost calculation across all owned numbers for expense tracking
Common Use Cases
- Building number management dashboards showing all owned numbers and assignments
- Identifying unassigned numbers that can be allocated to new SIP trunks
- Calculating total monthly telecommunications costs for billing and budgeting
Response Example
{
"status": "success",
"data": {
"numbers": [
{
"id": "NUM_7a8b9c0d1e2f",
"phoneNumber": "+14155551234",
"friendlyName": "+1 (415) 555-1234",
"country": "US",
"status": "active",
"trunkId": "TRK_8f9e0a1b2c3d",
"trunkName": "Production SIP Trunk",
"capabilities": {
"voice": true,
"sms": true,
"mms": false
},
"monthlyFee": 100,
"currency": "USD",
"purchasedAt": "2025-01-15T10:30:00.000Z",
"nextBillingDate": "2025-02-15T00:00:00.000Z"
},
{
"id": "NUM_3c4d5e6f7g8h",
"phoneNumber": "+12125559876",
"friendlyName": "+1 (212) 555-9876",
"country": "US",
"status": "active",
"trunkId": null,
"trunkName": null,
"capabilities": {
"voice": true,
"sms": true,
"mms": true
},
"monthlyFee": 100,
"currency": "USD",
"purchasedAt": "2025-01-10T14:20:00.000Z",
"nextBillingDate": "2025-02-10T00:00:00.000Z"
}
],
"total": 2,
"monthlyCost": 200
}
}Release Number
/api/v1/account/{accountId}/numbers/{id}Release a phone number back to the provider. This action is permanent and stops all monthly billing.
▶HTTP Headers
Warning
Once released, the number cannot be recovered. All inbound calls to this number will fail immediately.
About This Endpoint
Permanently return a phone number to Twilio's inventory, immediately terminating all inbound routing and stopping future monthly billing charges. This irreversible operation releases the number from your ownership—it becomes available for other customers to purchase and cannot be recovered. If unused days remain in the current billing cycle, a prorated refund is automatically credited to your account balance based on the remaining time. Use this endpoint to reduce telecommunications costs by removing unused or unnecessary numbers.
Release Process
- Number immediately removed from Twilio and made available for other customers
- All inbound calls to released number fail immediately after release completes
- Prorated refund automatically calculated and credited for unused billing days
Important Warnings
- Released numbers cannot be recovered—another customer may purchase immediately
- Verify no critical services depend on the number before releasing
- Consider unassigning from trunk first to test service impact before release
Response Example
{
"status": "success",
"message": "Phone number released successfully",
"data": {
"id": "NUM_7a8b9c0d1e2f",
"phoneNumber": "+14155551234",
"releasedAt": "2025-01-20T11:00:00.000Z",
"finalBilling": {
"proratedRefund": 50,
"currency": "USD",
"description": "Prorated refund for 15 days remaining in billing cycle"
}
}
}