Numbers API
Search available phone numbers in 60+ countries, purchase instantly, configure routing for SMS and voice, and release numbers you no longer need.
Base path: /v1/numbers
Search Available Numbers
GET /v1/numbers/available
Search the Orbit inventory for phone numbers matching your criteria.
ISO 3166-1 alpha-2 country code (e.g., US, GB, TR)
Number type: local, toll_free, mobile, short_code
Comma-separated capabilities filter: sms, voice, mms, whatsapp
Filter by area code (e.g., 415 for San Francisco)
Pattern match — search for numbers containing specific digits (e.g., 555)
Number of results to return (max 100)
curl "https://orbit-api.devotel.io/api/v1/numbers/available?country=US&type=local&capabilities=sms,voice&area_code=415&limit=5" \
-H "X-API-Key: dv_live_sk_your_key_here"
{
"data": [
{
"number": "+14155550100",
"country": "US",
"type": "local",
"region": "California",
"capabilities": ["sms", "voice", "mms"],
"monthly_cost": "1.50",
"currency": "USD"
},
{
"number": "+14155550101",
"country": "US",
"type": "local",
"region": "California",
"capabilities": ["sms", "voice", "mms"],
"monthly_cost": "1.50",
"currency": "USD"
}
],
"meta": {
"request_id": "req_num_001",
"timestamp": "2026-03-08T12:00:00Z"
}
}
Purchase a Number
POST /v1/numbers
Purchase an available number and add it to your account. The number is billed monthly starting immediately.
The phone number to purchase in E.164 format (from the search results)
A human-readable label for this number (e.g., Main Support Line)
URL to receive inbound SMS webhooks for this number
URL to receive inbound voice call webhooks for this number
AI agent ID to automatically handle inbound calls or messages on this number
curl -X POST https://orbit-api.devotel.io/api/v1/numbers \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"number": "+14155550100",
"friendly_name": "Main Support Line",
"sms_webhook_url": "https://yourapp.com/webhooks/sms",
"voice_webhook_url": "https://yourapp.com/webhooks/voice"
}'
{
"data": {
"id": "num_abc123",
"number": "+14155550100",
"country": "US",
"type": "local",
"friendly_name": "Main Support Line",
"capabilities": ["sms", "voice", "mms"],
"status": "active",
"sms_webhook_url": "https://yourapp.com/webhooks/sms",
"voice_webhook_url": "https://yourapp.com/webhooks/voice",
"monthly_cost": "1.50",
"currency": "USD",
"created_at": "2026-03-08T12:00:00Z"
},
"meta": {
"request_id": "req_num_002",
"timestamp": "2026-03-08T12:00:00Z"
}
}
List Your Numbers
GET /v1/numbers
Retrieve all phone numbers on your account with cursor-based pagination.
Cursor for pagination (returned in previous response)
Number of results per page (max 100)
Filter by capability: sms, voice, mms, whatsapp
curl "https://orbit-api.devotel.io/api/v1/numbers?limit=10" \
-H "X-API-Key: dv_live_sk_your_key_here"
{
"data": [
{
"id": "num_abc123",
"number": "+14155550100",
"country": "US",
"type": "local",
"friendly_name": "Main Support Line",
"capabilities": ["sms", "voice", "mms"],
"status": "active",
"monthly_cost": "1.50",
"currency": "USD",
"created_at": "2026-03-08T12:00:00Z"
}
],
"meta": {
"request_id": "req_num_003",
"timestamp": "2026-03-08T12:00:00Z",
"pagination": {
"cursor": "cur_num_abc",
"has_more": false,
"total": 1
}
}
}
Get Number Details
GET /v1/numbers/{id}
Retrieve the full configuration and status of a specific number.
Number ID (e.g., num_abc123)
curl https://orbit-api.devotel.io/api/v1/numbers/num_abc123 \
-H "X-API-Key: dv_live_sk_your_key_here"
{
"data": {
"id": "num_abc123",
"number": "+14155550100",
"country": "US",
"type": "local",
"friendly_name": "Main Support Line",
"capabilities": ["sms", "voice", "mms"],
"status": "active",
"sms_webhook_url": "https://yourapp.com/webhooks/sms",
"voice_webhook_url": "https://yourapp.com/webhooks/voice",
"agent_id": null,
"monthly_cost": "1.50",
"currency": "USD",
"created_at": "2026-03-08T12:00:00Z"
},
"meta": {
"request_id": "req_num_004",
"timestamp": "2026-03-08T12:00:00Z"
}
}
PATCH /v1/numbers/{id}
Update routing configuration for a number — set webhook URLs, assign an AI agent, or change the friendly name.
URL for inbound SMS webhooks
URL for inbound voice call webhooks
AI agent ID for automatic call/message handling, or null to remove
curl -X PATCH https://orbit-api.devotel.io/api/v1/numbers/num_abc123 \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agt_support_bot",
"voice_webhook_url": "https://yourapp.com/webhooks/voice-v2"
}'
{
"data": {
"id": "num_abc123",
"number": "+14155550100",
"friendly_name": "Main Support Line",
"agent_id": "agt_support_bot",
"voice_webhook_url": "https://yourapp.com/webhooks/voice-v2",
"status": "active",
"updated_at": "2026-03-08T12:10:00Z"
},
"meta": {
"request_id": "req_num_005",
"timestamp": "2026-03-08T12:10:00Z"
}
}
Release a Number
DELETE /v1/numbers/{id}
Release a number from your account. The number is immediately removed from your inventory and billing stops at the end of the current billing cycle.
This action is irreversible. The number may be reassigned to another customer and cannot be guaranteed for repurchase.
curl -X DELETE https://orbit-api.devotel.io/api/v1/numbers/num_abc123 \
-H "X-API-Key: dv_live_sk_your_key_here"
204 No Content
Port a Number
POST /v1/numbers/port
Submit a request to port existing numbers from another carrier to Orbit.
Array of phone numbers in E.164 format to port
Name of the current carrier
Name of the authorized person on the current carrier account
Account number with the current carrier
Account PIN or passcode if required by the carrier
curl -X POST https://orbit-api.devotel.io/api/v1/numbers/port \
-H "X-API-Key: dv_live_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"numbers": ["+14155551234", "+14155551235"],
"current_carrier": "Acme Telecom",
"authorization_name": "John Doe",
"account_number": "ACC-12345"
}'
{
"data": {
"id": "port_abc123",
"numbers": ["+14155551234", "+14155551235"],
"status": "pending",
"estimated_completion": "2026-03-22T00:00:00Z",
"created_at": "2026-03-08T12:00:00Z"
},
"meta": {
"request_id": "req_port_001",
"timestamp": "2026-03-08T12:00:00Z"
}
}
Porting typically takes 7–14 business days depending on the country and carrier.
You will receive a number.ported webhook event when the port is complete.
Number Types
| Type | Description | Availability |
|---|
local | Geographic number tied to a city or region | 60+ countries |
toll_free | Free for callers, costs billed to you | US, CA, UK, AU |
mobile | Mobile number for SMS and voice | 40+ countries |
short_code | 5-6 digit number for high-volume SMS | US, CA, UK |
Number Capabilities
| Capability | Description |
|---|
sms | Send and receive SMS messages |
voice | Make and receive voice calls |
mms | Send and receive MMS (images, media) |
whatsapp | Register as a WhatsApp Business number |
Examples
Node.js
const orbit = new Devotel({ apiKey: 'dv_live_sk_xxxx' })
const available = await orbit.numbers.search({
country: 'US',
type: 'local',
capabilities: ['sms', 'voice'],
areaCode: '415',
})
const purchased = await orbit.numbers.purchase({
number: available.data[0].number,
friendlyName: 'Support Line',
})
Python
orbit = OrbitClient(api_key="dv_live_sk_xxxx")
available = orbit.numbers.search(
country="US",
type="local",
capabilities=["sms", "voice"],
area_code="415",
)
purchased = orbit.numbers.purchase(
number=available.data[0].number,
friendly_name="Support Line",
)
