Skip to main content

​
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: /api/v1/numbers

​
Search Available Numbers

GET /api/v1/numbers/available Search the Orbit inventory for phone numbers matching your criteria.
​
country
string
required
ISO 3166-1 alpha-2 country code (e.g., US, GB, TR)
​
type
string
Number type: local, toll_free, mobile, short_code
​
capabilities
string
Comma-separated capabilities filter: sms, voice, mms, whatsapp
​
area_code
string
Filter by area code (e.g., 415 for San Francisco)
​
contains
string
Pattern match — search for numbers containing specific digits (e.g., 555)
​
limit
integer
default:"100"
Number of results to return (max 500)
curl "https://api.orbit.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 /api/v1/numbers/purchase Purchase an available number and add it to your account. The number is billed monthly starting immediately.
​
phone_number
string
required
The phone number to purchase in E.164 format (from the search results)
​
country_code
string
default:"US"
ISO 3166-1 alpha-2 country code for the number (2 letters)
​
capabilities
string[]
Capabilities to provision on the number — any of sms, voice, whatsapp, rcs
​
compliance_profile_id
string
ID of an approved compliance profile to attach before the carrier order. For regulated countries, attaching a profile that covers the target country lets the number activate immediately instead of entering a regulatory hold.
​
id
string
Provider-issued inventory row id returned by GET /api/v1/numbers/available. Forward it for placeholder (carrier-allocated) numbers; omit it to purchase by phone_number alone.
Purchase only acquires the number. Set its label and inbound webhook routing afterward with the Configure a Number endpoint.
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/purchase \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550100",
    "country_code": "US",
    "capabilities": ["sms", "voice"]
  }'

{
  "data": {
    "id": "num_abc123",
    "number": "+14155550100",
    "country": "US",
    "type": "local",
    "capabilities": ["sms", "voice", "mms"],
    "status": "active",
    "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 /api/v1/numbers Retrieve all phone numbers on your account with cursor-based pagination.
​
cursor
string
Cursor for pagination (returned in previous response)
​
limit
integer
default:"25"
Number of results per page (max 200)
​
country
string
Filter by country code
​
capabilities
string
Filter by capability: sms, voice, mms, whatsapp
curl "https://api.orbit.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",
      "label": "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 /api/v1/numbers/{id} Retrieve the full configuration and status of a specific number.
​
id
string
required
Number ID (e.g., num_abc123)
curl https://api.orbit.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",
    "label": "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"
  }
}

​
Configure a Number

PUT /api/v1/numbers/{id} Update the configuration for a number — change its label, status, capabilities, forwarding, webhook delivery, compliance profile, or tags. All body fields are optional; only the keys you send are updated. The request body is validated strictly, so unknown keys are rejected with 422.
To configure inbound AI-agent routing (which agent answers calls/messages on this number), use PUT /api/v1/numbers/{phoneNumber}/routing instead — agent assignment is not part of this endpoint.
​
id
string
required
Number ID
​
label
string
Human-friendly label for the number (max 100 characters)
​
status
string
Number status — one of active or inactive
​
capabilities
string[]
Enabled capabilities, any of sms, mms, voice, fax. Toggling depends on carrier support (for example fax/T.38 is fixed at provisioning time); unsupported toggles return 422.
​
forwarding_number
string
E.164 number to forward inbound voice calls to. Send "" to clear.
​
webhook_url
string | null
Single webhook URL for inbound event delivery (SMS and voice). Send "" or null to detach.
​
sms_forwarding
string
E.164 number to forward inbound SMS to. Send "" to clear.
​
compliance_profile_id
string | null
Per-number compliance profile to attach. Send "" or null to detach.
​
tags
string[]
Up to 10 lowercase-slug tags (^[a-z0-9][a-z0-9_-]{0,63}$). Sent as the full resolved tag set; an empty array clears all tags.
​
channel_config
object
Provider-specific channel configuration overrides.
curl -X PUT https://api.orbit.devotel.io/api/v1/numbers/num_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Main Support Line",
    "status": "active",
    "webhook_url": "https://yourapp.com/webhooks/inbound-v2",
    "forwarding_number": "+14155550111",
    "tags": ["support", "us-west"]
  }'

{
  "data": {
    "id": "num_abc123",
    "number": "+14155550100",
    "label": "Main Support Line",
    "capabilities": ["sms", "voice", "mms"],
    "status": "active",
    "webhook_url": "https://yourapp.com/webhooks/inbound-v2",
    "forwarding_number": "+14155550111",
    "tags": ["support", "us-west"],
    "updated_at": "2026-03-08T12:10:00Z"
  },
  "meta": {
    "request_id": "req_num_005",
    "timestamp": "2026-03-08T12:10:00Z"
  }
}

​
Release a Number

DELETE /api/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.
​
id
string
required
Number ID to release
curl -X DELETE https://api.orbit.devotel.io/api/v1/numbers/num_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"
Response: 204 No Content

​
Port a Number

POST /api/v1/numbers/porting Submit a request to port existing numbers from another carrier to Orbit.
​
numbers
string[]
required
Array of phone numbers in E.164 format to port
​
current_carrier
string
required
Name of the current carrier
​
authorization_name
string
required
Name of the authorized person on the current carrier account
​
account_number
string
Account number with the current carrier
​
pin
string
Account PIN or passcode if required by the carrier
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -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

TypeDescriptionAvailability
localGeographic number tied to a city or region60+ countries
toll_freeFree for callers, costs billed to youUS, CA, UK, AU
mobileMobile number for SMS and voice40+ countries
short_code5-6 digit number for high-volume SMSUS, CA, UK

​
Number Capabilities

CapabilityDescription
smsSend and receive SMS messages
voiceMake and receive voice calls
mmsSend and receive MMS (images, media)
whatsappRegister 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({
  phoneNumber: available.data[0].number,
  countryCode: 'US',
  capabilities: ['sms', 'voice'],
})
A first-party Python SDK is on the roadmap but not yet shipped. Call the REST endpoints above with requests / httpx / any HTTP client.