API reference

Phone numbers

A PhoneNumber represents a DID assigned to your account. You point its voice_url at your own answer-URL handler so inbound calls reach your app, and you set the caller-ID rotation strategy that gives outbound calls local presence. DID-pool assignment and caller-ID rotation (round-robin, sticky and area-code match) are real, shipped capabilities. The public REST surface is in developer preview, so the fields and payloads below are illustrative and may change before GA.

Base URL https://api.telvox.dev

Authentication Authorization: Bearer $TELVOX_API_KEY

Provisioning today

Numbers are provisioned with the TelVox team today, not bought via the API. This resource covers the numbers already assigned to your account. Self-serve number search and purchase are on the roadmap — see roadmap endpoints below.

Properties

A PhoneNumber resource has the following properties.

Property	Type	Description
sid	string	Unique identifier for the assigned number, prefixed PN.
phone_number	string	The number in E.164 format, e.g. +14155550100.
friendly_name	string	A human-readable label for the number.
number_type	enum	local or toll-free.
capabilities	object	Which channels the number supports, e.g. { voice: true }. TelVox numbers are voice-capable.
voice_url	string<uri>	The answer-URL document TelVox requests when this number receives an inbound call.
voice_method	enum	HTTP method used to request voice_url. GET or POST; defaults to POST.
status_callback	string<uri>	URL TelVox requests as inbound calls to this number change state.
caller_id_strategy	enum	Outbound caller-ID rotation for this number's pool: round-robin, sticky or area-code-match.
date_assigned	string<date-time>	ISO 8601 timestamp for when the number was assigned to your account.

List assigned numbers

GET/v1/phone-numbers

Return a paginated list of the numbers assigned to your account.

Query parameter	Type	Description
phone_number	string	Filter by a full or partial number (digits to match).
number_type	enum	Filter to local or toll-free numbers.
friendly_name	string	Filter to numbers matching an exact friendly name.
page_size	integer	Number of results per page. Defaults to 50; cursor returned in the response.

GET/v1/phone-numbers

illustrative

curl -G https://api.telvox.dev/v1/phone-numbers \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  --data-urlencode "number_type=local" \
  --data-urlencode "page_size=25"

200 ok

200 — response

illustrative

{
  "phone_numbers": [
    {
      "sid": "PN6b2e9a1c4d7f480ab3e1c6d9f0a2b5c8",
      "phone_number": "+14155550100",
      "friendly_name": "support-inbound-sf",
      "number_type": "local",
      "capabilities": { "voice": true },
      "voice_url": "https://your.app/voice/answer",
      "voice_method": "POST",
      "status_callback": "https://your.app/voice/status",
      "caller_id_strategy": "area-code-match",
      "date_assigned": "2026-05-30T11:02:44Z"
    }
  ],
  "meta": {
    "page_size": 25,
    "next_cursor": null
  }
}

Fetch a number

GET/v1/phone-numbers/{sid}

Retrieve a single assigned number by its SID.

GET/v1/phone-numbers/{sid}

illustrative

curl https://api.telvox.dev/v1/phone-numbers/PN6b2e9a1c4d7f480ab3e1c6d9f0a2b5c8 \
  -H "Authorization: Bearer $TELVOX_API_KEY"

200 ok

200 — response

illustrative

{
  "sid": "PN6b2e9a1c4d7f480ab3e1c6d9f0a2b5c8",
  "phone_number": "+14155550100",
  "friendly_name": "support-inbound-sf",
  "number_type": "local",
  "capabilities": { "voice": true },
  "voice_url": "https://your.app/voice/answer",
  "voice_method": "POST",
  "status_callback": "https://your.app/voice/status",
  "caller_id_strategy": "area-code-match",
  "date_assigned": "2026-05-30T11:02:44Z"
}

Update a number

POST/v1/phone-numbers/{sid}

Point a number at a new answer URL, change its status callback, or change its outbound caller-ID rotation strategy.

Body parameter	Type	Description
friendly_name	string	Rename the number.
voice_url	string<uri>	Set the answer-URL document for inbound calls to this number.
voice_method	enum	Set the HTTP method used to request voice_url. GET or POST.
status_callback	string<uri>	Set the URL TelVox requests as inbound calls change state.
caller_id_strategy	enum	Set the outbound caller-ID rotation strategy: round-robin, sticky or area-code-match.

POST/v1/phone-numbers/{sid}

illustrative

curl -X POST https://api.telvox.dev/v1/phone-numbers/PN6b2e9a1c4d7f480ab3e1c6d9f0a2b5c8 \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -d voice_url="https://your.app/voice/answer" \
  -d caller_id_strategy="round-robin"

200 ok

Roadmap — search & purchase

Roadmap — not yet available

Self-serve number search and purchase are planned for a future release. Today, numbers are provisioned with the TelVox team. The endpoints below are shown to convey the intended shape only — they are not callable in the developer preview.

GET/v1/available-phone-numbers

Roadmap: search for purchasable numbers by country, type and area code. Not available in the developer preview.

GET/v1/available-phone-numbers

illustrative

# roadmap — search is not available in the developer preview
curl -G https://api.telvox.dev/v1/available-phone-numbers \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  --data-urlencode "country=US" \
  --data-urlencode "type=local" \
  --data-urlencode "area_code=415"

roadmap — not callable

roadmap — illustrative response shape

illustrative

{
  "available_phone_numbers": [
    {
      "phone_number": "+14155550133",
      "number_type": "local",
      "region": "CA",
      "locality": "San Francisco",
      "capabilities": { "voice": true }
    }
  ]
}

POST/v1/phone-numbers

Roadmap: purchase and assign a number found via search. Not available in the developer preview; today the team provisions numbers with you.

POST/v1/phone-numbers

illustrative

# roadmap — purchase is not available in the developer preview
curl -X POST https://api.telvox.dev/v1/phone-numbers \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -d phone_number="+14155550133" \
  -d voice_url="https://your.app/voice/answer"

roadmap — not callable