API reference

Phone numbers

The DID Store: search, buy, route and release phone numbers; SMS and softphone lines on them.

52 operationsBase URL https://packetexchange.io/api/v1Postman collection

BrowsePhone numbers

Browse the number catalogue

GET/api/v1/dids/catalog

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Number groups by country, city and type, with the price of each SKU. While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Parameters

countryId
query · string
From GET .../catalog/countries
typeId
query · string
From GET .../catalog/types
search
query · string
Text match over country, city, area prefix and type; digits also match the start of the full dialling prefix ("4420" finds London). Spans the whole catalogue once it is indexed, otherwise the fetched page
page
query · integer
sort
query · string
Order by the cheapest monthly price, setup price or location. Omitted: the catalogue orderOne of monthly_asc, monthly_desc, setup_asc, location_asc
maxMonthly
query · number
Only groups whose cheapest monthly price is at most this, in USD

Response 200

FieldDescription

groupsrequired
object[]
groupIdrequired
string · groups[].groupId
Pass to POST /dids/buy with a skuId
countryrequired
string · groups[].country
countryIdrequired
string · groups[].countryId
Catalogue country id (filter value), not an ISO code
countryPrefixrequired
string · groups[].countryPrefix
cityrequired
string | null · groups[].city
areaPrefixrequired
string | null · groups[].areaPrefix
typeIdrequired
string | null · groups[].typeId
typeNamerequired
string | null · groups[].typeName
Local, National, Mobile, Toll-free...
skusrequired
object[] · groups[].skus
skuIdrequired
string · groups[].skus[].skuId
Pass to POST /dids/buy
channelsrequired
integer · groups[].skus[].channels
Concurrent call channels included
setupPricerequired
number · groups[].skus[].setupPrice
One-off price in USD (display number, not a money string)
monthlyPricerequired
number · groups[].skus[].monthlyPrice
Monthly price in USD (display number, not a money string)
totalrequired
integer | null
pagerequired
integer

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List countries with numbers for sale

GET/api/v1/dids/catalog/countries

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Response 200

FieldDescription

datarequired
object[]
countryIdrequired
string · data[].countryId
countryrequired
string · data[].country
countryPrefixrequired
string · data[].countryPrefix

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List number types for sale

GET/api/v1/dids/catalog/types

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Response 200

FieldDescription

datarequired
object[]
idrequired
string · data[].id
namerequired
string · data[].name

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Buy a phone number

POST/api/v1/dids/buy

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)
Safe retries: Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Moves money: Buys a phone number, charged to your balance.

Charges the setup price plus the first month to your balance (or the named sub-account's) and orders the number. It starts pending; number is null until provisioning completes. Requires a verified identity where KYC is enforced.

Parameters

X-Idempotency-Key
header · string
Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

FieldDescription

skuIdrequired
string
max 64 chars
groupIdrequired
string
max 64 chars
countryId
string
max 64 chars
country
string
max 120 chars
city
string | null
max 120 chars
areaPrefix
string | null
max 16 chars
didType
string | null
max 40 chars
subAccountId
string (uuid)
Buy the number for one of your sub-accounts: its balance pays and the number is theirs

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
numberrequired
string | null · data.number
null while the number is still being provisioned
countryrequired
string | null · data.country
countryCoderequired
string | null · data.countryCode
ISO-3166-1 alpha-2 country codemax 2 chars
cityrequired
string | null · data.city
areaPrefixrequired
string | null · data.areaPrefix
didTyperequired
string | null · data.didType
channelsIncludedrequired
integer · data.channelsIncluded
statusrequired
string · data.status
suspended = a monthly renewal failed; the number is held for graceDays before releaseOne of pending, active, suspended, released, failed
pointModerequired
string · data.pointMode
One of unrouted, sip, forward
pointsTorequired
string | null · data.pointsTo
Primary destination: host[:port] for sip, E.164 for forward
pointsToBackuprequired
string | null · data.pointsToBackup
autoRenewrequired
boolean · data.autoRenew
setupPricerequired
money · data.setupPrice
USD as a decimal string with exactly 6 places, e.g. "0.012500".
monthlyPricerequired
money · data.monthlyPrice
USD as a decimal string with exactly 6 places, e.g. "0.012500".
orderedAtrequired
string (date-time) | null · data.orderedAt
ISO-8601 timestamp (UTC)
activatedAtrequired
string (date-time) | null · data.activatedAt
ISO-8601 timestamp (UTC)
nextRenewalAtrequired
string (date-time) | null · data.nextRenewalAt
ISO-8601 timestamp (UTC)
suspendedAtrequired
string (date-time) | null · data.suspendedAt
ISO-8601 timestamp (UTC)
releasedAtrequired
string (date-time) | null · data.releasedAt
ISO-8601 timestamp (UTC)
endpointReachablerequired
boolean | null · data.endpointReachable
null = not checked yet
endpointCauserequired
string | null · data.endpointCause
endpointCheckedAtrequired
string (date-time) | null · data.endpointCheckedAt
ISO-8601 timestamp (UTC)
aiAgentIdrequired
string (uuid) | null · data.aiAgentId
The AI voice agent answering inbound calls to this number, or null (PUT /dids/{id}/ai-agent)
graceDaysrequired
integer · data.graceDays
Days an unpaid (suspended) number is held before release

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoKYC_REQUIRED

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/buy" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "skuId": "<skuId>",
  "groupId": "<groupId>"
}'

Run it here with a test key.

List your phone numbers

GET/api/v1/dids/mine

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Response 200

FieldDescription

datarequired
object[]
Same fields as Did, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your request to list numbers on the marketplace

GET/api/v1/dids/listing-request

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Your latest request, plus a profile prefill for the form. Works while the number store is off.

Response 200

FieldDescription

datarequired
object
ownedActiveDidsrequired
integer · data.ownedActiveDids
requestrequired
object | null · data.request
Your latest request, or null
idrequired
string (uuid) · data.request.id
statusrequired
string · data.request.status
selectedDidsrequired
object[] | null · data.request.selectedDids
idrequired
string (uuid) · data.request.selectedDids[].id
numberrequired
string | null · data.request.selectedDids[].number
countryrequired
string | null · data.request.selectedDids[].country
didTyperequired
string | null · data.request.selectedDids[].didType
didCountrequired
integer | null · data.request.didCount
submittedAtrequired
string (date-time) · data.request.submittedAt
ISO-8601 timestamp (UTC)
reviewedAtrequired
string (date-time) | null · data.request.reviewedAt
ISO-8601 timestamp (UTC)
prefillrequired
object · data.prefill
companyNamerequired
string · data.prefill.companyName
contactNamerequired
string · data.prefill.contactName
contactEmailrequired
string · data.prefill.contactEmail
contactPhonerequired
string · data.prefill.contactPhone

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Ask to list your numbers on the marketplace

POST/api/v1/dids/listing-request

Access: API key. Scoped keys need numbers:write.
Rate limit: 5 requests per 10 minutes

Our team reviews the request and lists the numbers by hand. One open request at a time (409 CONFLICT otherwise). A validation failure here answers 400 with error.field naming the first bad field instead of a details array.

Request body (application/json)

FieldDescription

companyName
string | null
max 255 chars
contactNamerequired
string
max 255 chars
contactEmail
string (email) | null
max 255 chars
contactPhone
string | null
max 40 chars
selectedDidIds
string (uuid)[]
Numbers from your portfolio to list
didCount
integer | null
countries
string | null
max 255 chars
numberTypes
string | null
max 255 chars
monthlyVolume
string | null
max 255 chars
targetPrice
string | null
max 2000 chars
notes
string | null
max 4000 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
statusrequired
string · data.status
submittedAtrequired
string (date-time) · data.submittedAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/listing-request" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contactName": "<contactName>"
}'

Run it here with a test key.

List your numbers usable as outbound caller IDs

GET/api/v1/dids/cli-eligible

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Active, provisioned numbers you own.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
clirequired
string · data[].cli
Digits only
numberrequired
string · data[].number
countryrequired
string | null · data[].country
countryCoderequired
string | null · data[].countryCode
cityrequired
string | null · data[].city
didTyperequired
string | null · data[].didType
channelsrequired
integer · data[].channels
labelrequired
string | null · data[].label

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Add your numbers to a dialer caller-ID set

POST/api/v1/dids/to-cli-set

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Adds the chosen (or all) active numbers so they rotate as caller IDs on voice campaigns.

Request body (application/json)

FieldDescription

setIdrequired
string (uuid)
One of your dialer caller-ID sets
didIds
string (uuid)[] | string
Omit or "all" for every active number

Response 201

FieldDescription

datarequired
object
insertedrequired
integer · data.inserted
skippedrequired
integer · data.skipped
rejectsrequired
object[] · data.rejects
valuerequired
string · data.rejects[].value
reasonrequired
string · data.rejects[].reason

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/to-cli-set" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "setId": "<setId>"
}'

Run it here with a test key.

Get one of your phone numbers

GET/api/v1/dids/{id}

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
Same fields as Did, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get a number's call flow

GET/api/v1/dids/{id}/routing

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Ring strategy and ordered destinations. Hosted line passwords are never included.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
strategyrequired
string · data.strategy
One of failover, simultaneous
timeoutSecrequired
integer · data.timeoutSec
endpointsrequired
object[] · data.endpoints
idrequired
string (uuid) · data.endpoints[].id
kindrequired
string · data.endpoints[].kind
One of sip, forward, hosted
targetrequired
string | null · data.endpoints[].target
sipUsernamerequired
string | null · data.endpoints[].sipUsername
Hosted lines only; the password is never listed
labelrequired
string | null · data.endpoints[].label
priorityrequired
integer · data.endpoints[].priority
enabledrequired
boolean · data.endpoints[].enabled

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Replace a number's call flow

PUT/api/v1/dids/{id}/routing

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Full replace: an endpoint sent with an id is kept or updated, one without an id is created, and any existing endpoint you leave out is deleted (hosted lines included - send them back by id to keep them).

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

strategy
string
One of failover, simultaneous
timeoutSec
integer
5 to 600
endpointsrequired
object[]
id
string (uuid) · endpoints[].id
Send an existing id to keep or update it; omit to create
kindrequired
string · endpoints[].kind
One of sip, forward, hosted
target
string | null · endpoints[].target
Required for sip and forward; ignored for hostedmax 255 chars
label
string | null · endpoints[].label
max 120 chars
priority
integer · endpoints[].priority
1 to 999
enabled
boolean · endpoints[].enabled

Response 200

FieldDescription

datarequired
object
Same fields as DidCallFlow, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/dids/<id>/routing" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "endpoints": [
    {
      "kind": "sip"
    }
  ]
}'

Run it here with a test key.

Point a number at one destination (and an optional backup)

PATCH/api/v1/dids/{id}/routing

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

The simple form of call routing: a primary and an optional failover backup. Hosted softphone lines and any extra destinations are left alone. Use PUT for the full call flow.

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

moderequired
string
One of sip, forward
targetrequired
string
host[:port] for sip, E.164 for forwardmax 255 chars
backupMode
string | null
Defaults to modeOne of sip, forward
backupTarget
string | null
null or "" clears the backup; omit to keep itmax 255 chars

Response 200

FieldDescription

datarequired
object
Same fields as Did, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PATCH "https://packetexchange.io/api/v1/dids/<id>/routing" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "sip",
  "target": "<target>"
}'

Run it here with a test key.

List a number's softphone lines

GET/api/v1/dids/{id}/sip-lines

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Passwords are not included; use reveal.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
sipUsernamerequired
string · data[].sipUsername
labelrequired
string | null · data[].label
priorityrequired
integer · data[].priority
enabledrequired
boolean · data[].enabled
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Create a softphone line on a number

POST/api/v1/dids/{id}/sip-lines

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Returns the full login, password included, once.

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

label
string | null
max 120 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
sipUsernamerequired
string · data.sipUsername
sipPasswordrequired
string · data.sipPassword
Shown only here and on an explicit reveal
serverrequired
string · data.server
portrequired
string · data.port

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/<id>/sip-lines" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Acme"
}'

Run it here with a test key.

Reveal a softphone line's login

POST/api/v1/dids/{id}/sip-lines/{lineId}/reveal

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
lineIdrequired
path · string

Response 200

FieldDescription

datarequired
object
Same fields as DidSipLineLogin, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Delete a softphone line

DELETE/api/v1/dids/{id}/sip-lines/{lineId}

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
lineIdrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string · data.id
deletedrequired
boolean · data.deleted

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Turn monthly auto-renew on or off

PATCH/api/v1/dids/{id}/auto-renew

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

With auto-renew off, the number is released at its next renewal date instead of being charged.

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

enabledrequired
boolean

Response 200

FieldDescription

datarequired
object
Same fields as Did, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PATCH "https://packetexchange.io/api/v1/dids/<id>/auto-renew" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true
}'

Run it here with a test key.

List inbound calls to a number

GET/api/v1/dids/{id}/cdrs

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Recent inbound calls, newest first, with a calls and minutes total.

Parameters

idrequired
path · string
limit
query · integer
Newest first; default 200

Response 200

FieldDescription

datarequired
object
callsrequired
object[] · data.calls
idrequired
string (uuid) · data.calls[].id
fromNumberrequired
string | null · data.calls[].fromNumber
toNumberrequired
string | null · data.calls[].toNumber
durationSecrequired
integer · data.calls[].durationSec
statusrequired
string | null · data.calls[].status
startedAtrequired
string (date-time) · data.calls[].startedAt
ISO-8601 timestamp (UTC)
summaryrequired
object · data.summary
callsrequired
integer · data.summary.calls
minutesrequired
number · data.summary.minutes

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

See which AI voice agent answers a number

GET/api/v1/dids/{id}/ai-agent

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Returns the agent pointed at this number (or null), whether inbound AI answering is switched on for the platform, and the per-minute AI voice rate.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
didIdrequired
string (uuid) · data.didId
agentIdrequired
string (uuid) | null · data.agentId
agentNamerequired
string | null · data.agentName
agentEnabledrequired
boolean | null · data.agentEnabled
A disabled agent does not answer; the number rings its call flow
liverequired
boolean · data.live
Whether inbound AI answering is switched on for the platform right now
ratePerMinrequired
string · data.ratePerMin
AI voice rate in USD per minute, billed per second

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Point a number at an AI voice agent

PUT/api/v1/dids/{id}/ai-agent

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Send { "agentId": "<your agent id>" } and inbound calls to the number are answered by that agent instead of ringing the number's call flow; send { "agentId": null } to go back to the call flow, which is kept untouched meanwhile. Billed per second at the AI voice per-minute rate to the number's owner, on top of the number's monthly price. Each call is capped at the agent's maximum call length and at what your balance covers; when the agent is disabled or your balance covers less than 30 seconds, the number rings its call flow as usual. The agent must belong to your account.

Parameters

idrequired
path · string (uuid)

Request body (application/json)

FieldDescription

agentIdrequired
string (uuid) | null
One of your AI agents (GET /ai-agents), or null to clear

Response 200

FieldDescription

datarequired
object
Same fields as DidAiAgent, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/dids/<id>/ai-agent" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "<agentId>"
}'

Run it here with a test key.

Get a number's voicemail, recording, IVR and schedule settings

GET/api/v1/dids/{id}/features

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

A number with nothing configured rings its call flow as normal.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
voicemailrequired
object · data.voicemail
enabledrequired
boolean · data.voicemail.enabled
moderequired
string · data.voicemail.mode
One of on_no_answer, always
greetingAssetIdrequired
string (uuid) | null · data.voicemail.greetingAssetId
hasGreetingrequired
boolean · data.voicemail.hasGreeting
transcriberequired
boolean · data.voicemail.transcribe
recordingrequired
object · data.recording
enabledrequired
boolean · data.recording.enabled
announcerequired
boolean · data.recording.announce
retentionDaysrequired
integer · data.recording.retentionDays
ivrrequired
object · data.ivr
enabledrequired
boolean · data.ivr.enabled
greetingAssetIdrequired
string (uuid) | null · data.ivr.greetingAssetId
hasGreetingrequired
boolean · data.ivr.hasGreeting
timeoutSecrequired
integer · data.ivr.timeoutSec
maxRetriesrequired
integer · data.ivr.maxRetries
optionsrequired
object[] · data.ivr.options
idrequired
string (uuid) · data.ivr.options[].id
digitrequired
string · data.ivr.options[].digit
actionrequired
string · data.ivr.options[].action
One of endpoint, voicemail, hangup
endpointIdrequired
string (uuid) | null · data.ivr.options[].endpointId
labelrequired
string | null · data.ivr.options[].label
schedulerequired
object · data.schedule
enabledrequired
boolean · data.schedule.enabled
timezonerequired
string · data.schedule.timezone
schedulerequired
object | null · data.schedule.schedule
sunrequired
object[] · data.schedule.schedule.sun
openrequired
string · data.schedule.schedule.sun[].open
HH:MMmax 5 chars
closerequired
string · data.schedule.schedule.sun[].close
HH:MMmax 5 chars
monrequired
object[] · data.schedule.schedule.mon
openrequired
string · data.schedule.schedule.mon[].open
HH:MMmax 5 chars
closerequired
string · data.schedule.schedule.mon[].close
HH:MMmax 5 chars
tuerequired
object[] · data.schedule.schedule.tue
openrequired
string · data.schedule.schedule.tue[].open
HH:MMmax 5 chars
closerequired
string · data.schedule.schedule.tue[].close
HH:MMmax 5 chars
wedrequired
object[] · data.schedule.schedule.wed
openrequired
string · data.schedule.schedule.wed[].open
HH:MMmax 5 chars
closerequired
string · data.schedule.schedule.wed[].close
HH:MMmax 5 chars
thurequired
object[] · data.schedule.schedule.thu
openrequired
string · data.schedule.schedule.thu[].open
HH:MMmax 5 chars
closerequired
string · data.schedule.schedule.thu[].close
HH:MMmax 5 chars
frirequired
object[] · data.schedule.schedule.fri
openrequired
string · data.schedule.schedule.fri[].open
HH:MMmax 5 chars
closerequired
string · data.schedule.schedule.fri[].close
HH:MMmax 5 chars
satrequired
object[] · data.schedule.schedule.sat
openrequired
string · data.schedule.schedule.sat[].open
HH:MMmax 5 chars
closerequired
string · data.schedule.schedule.sat[].close
HH:MMmax 5 chars
holidaysrequired
object[] | null · data.schedule.holidays
daterequired
string · data.schedule.holidays[].date
YYYY-MM-DDmax 10 chars
name
string · data.schedule.holidays[].name
max 120 chars
outsideHoursActionrequired
string · data.schedule.outsideHoursAction
One of voicemail, endpoints, hangup
closedEndpointsrequired
object[] · data.schedule.closedEndpoints
idrequired
string (uuid) · data.schedule.closedEndpoints[].id
kindrequired
string · data.schedule.closedEndpoints[].kind
One of sip, forward
targetrequired
string · data.schedule.closedEndpoints[].target
labelrequired
string | null · data.schedule.closedEndpoints[].label
priorityrequired
integer · data.schedule.closedEndpoints[].priority
enabledrequired
boolean · data.schedule.closedEndpoints[].enabled
openNowrequired
boolean | null · data.schedule.openNow
assetsrequired
object[] · data.assets
idrequired
string (uuid) · data.assets[].id
kindrequired
string · data.assets[].kind
One of voicemail_greeting, ivr_greeting
namerequired
string | null · data.assets[].name
mimerequired
string · data.assets[].mime
createdAtrequired
string (date-time) · data.assets[].createdAt
ISO-8601 timestamp (UTC)
mediaLiverequired
boolean · data.mediaLive
Whether voicemail and recording capture is live on the platform

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Configure voicemail on a number

PUT/api/v1/dids/{id}/features/voicemail

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

enabled
boolean
mode
string
One of on_no_answer, always
greetingAssetId
string (uuid) | null
transcribe
boolean

Response 200

FieldDescription

datarequired
object
Same fields as DidFeatures, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/dids/<id>/features/voicemail" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "mode": "on_no_answer"
}'

Run it here with a test key.

Configure call recording on a number

PUT/api/v1/dids/{id}/features/recording

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

enabled
boolean
announce
boolean
retentionDays
integer
0 to 3650

Response 200

FieldDescription

datarequired
object
Same fields as DidFeatures, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/dids/<id>/features/recording" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "announce": true
}'

Run it here with a test key.

Configure the IVR menu on a number

PUT/api/v1/dids/{id}/features/ivr

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

enabled
boolean
greetingAssetId
string (uuid) | null
timeoutSec
integer
1 to 30
maxRetries
integer
1 to 5
options
object[]
Replaces the whole menu when sent
digitrequired
string · options[].digit
0-9, * or #max 1 chars
actionrequired
string · options[].action
One of endpoint, voicemail, hangup
endpointId
string (uuid) | null · options[].endpointId
label
string | null · options[].label
max 120 chars

Response 200

FieldDescription

datarequired
object
Same fields as DidFeatures, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/dids/<id>/features/ivr" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "greetingAssetId": "<greetingAssetId>"
}'

Run it here with a test key.

Configure business-hours routing on a number

PUT/api/v1/dids/{id}/features/schedule

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

enabled
boolean
timezone
string
IANA zone, e.g. Europe/Londonmax 64 chars
schedule
object
sunrequired
object[] · schedule.sun
openrequired
string · schedule.sun[].open
HH:MMmax 5 chars
closerequired
string · schedule.sun[].close
HH:MMmax 5 chars
monrequired
object[] · schedule.mon
openrequired
string · schedule.mon[].open
HH:MMmax 5 chars
closerequired
string · schedule.mon[].close
HH:MMmax 5 chars
tuerequired
object[] · schedule.tue
openrequired
string · schedule.tue[].open
HH:MMmax 5 chars
closerequired
string · schedule.tue[].close
HH:MMmax 5 chars
wedrequired
object[] · schedule.wed
openrequired
string · schedule.wed[].open
HH:MMmax 5 chars
closerequired
string · schedule.wed[].close
HH:MMmax 5 chars
thurequired
object[] · schedule.thu
openrequired
string · schedule.thu[].open
HH:MMmax 5 chars
closerequired
string · schedule.thu[].close
HH:MMmax 5 chars
frirequired
object[] · schedule.fri
openrequired
string · schedule.fri[].open
HH:MMmax 5 chars
closerequired
string · schedule.fri[].close
HH:MMmax 5 chars
satrequired
object[] · schedule.sat
openrequired
string · schedule.sat[].open
HH:MMmax 5 chars
closerequired
string · schedule.sat[].close
HH:MMmax 5 chars
holidays
object[]
daterequired
string · holidays[].date
YYYY-MM-DDmax 10 chars
name
string · holidays[].name
max 120 chars
outsideHoursAction
string
One of voicemail, endpoints, hangup
closedEndpoints
object[]
kindrequired
string · closedEndpoints[].kind
One of sip, forward
targetrequired
string · closedEndpoints[].target
max 255 chars
label
string | null · closedEndpoints[].label
max 120 chars
priority
integer · closedEndpoints[].priority
1 to 999
enabled
boolean · closedEndpoints[].enabled

Response 200

FieldDescription

datarequired
object
Same fields as DidFeatures, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/dids/<id>/features/schedule" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "timezone": "<timezone>"
}'

Run it here with a test key.

List a number's uploaded greetings

GET/api/v1/dids/{id}/greetings

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
kindrequired
string · data[].kind
One of voicemail_greeting, ivr_greeting
namerequired
string | null · data[].name
mimerequired
string · data[].mime
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Upload a voicemail or IVR greeting

POST/api/v1/dids/{id}/greetings

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

WAV or MP3, up to 8 MB. Send multipart with a file part (and kind as a field or query parameter), or JSON with contentBase64.

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

kindrequired
string
One of voicemail_greeting, ivr_greeting
name
string | null
max 120 chars
contentBase64
string
WAV or MP3, base64, up to 8 MB. Or send multipart with a file part

Response 201

FieldDescription

datarequired
object
Same fields as DidGreeting, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/<id>/greetings" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "voicemail_greeting"
}'

Run it here with a test key.

Download a greeting's audio

GET/api/v1/dids/{id}/greetings/{assetId}/audio

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
assetIdrequired
path · string

Response 200 (audio/*)

The greeting audio bytes (WAV or MP3; the Content-Type says which).

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Delete a greeting

DELETE/api/v1/dids/{id}/greetings/{assetId}

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
assetIdrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string · data.id
deletedrequired
boolean · data.deleted

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List call recordings on a number

GET/api/v1/dids/{id}/recordings

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
limit
query · integer
Newest first; default 200

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
kindrequired
string · data[].kind
One of call, voicemail
fromNumberrequired
string | null · data[].fromNumber
toNumberrequired
string | null · data[].toNumber
durationSecrequired
integer · data[].durationSec
mimerequired
string | null · data[].mime
byteSizerequired
integer · data[].byteSize
heardrequired
boolean · data[].heard
transcriptrequired
string | null · data[].transcript
hasAudiorequired
boolean · data[].hasAudio
expiresAtrequired
string (date-time) | null · data[].expiresAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Download a call recording

GET/api/v1/dids/{id}/recordings/{recId}/audio

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
recIdrequired
path · string

Response 200 (audio/*)

The recording audio bytes (WAV or MP3; the Content-Type says which).

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Delete a call recording

DELETE/api/v1/dids/{id}/recordings/{recId}

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
recIdrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string · data.id
deletedrequired
boolean · data.deleted

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List voicemails on a number

GET/api/v1/dids/{id}/voicemails

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
limit
query · integer
Newest first; default 200

Response 200

FieldDescription

datarequired
object[]
Same fields as DidRecording, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Download a voicemail

GET/api/v1/dids/{id}/voicemails/{recId}/audio

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
recIdrequired
path · string

Response 200 (audio/*)

The voicemail audio bytes (WAV or MP3; the Content-Type says which).

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Mark a voicemail heard or unheard

POST/api/v1/dids/{id}/voicemails/{recId}/heard

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
recIdrequired
path · string

Request body (application/json)

FieldDescription

heard
boolean
Default true

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
heardrequired
boolean · data.heard

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/<id>/voicemails/<recId>/heard" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "heard": true
}'

Run it here with a test key.

Delete a voicemail

DELETE/api/v1/dids/{id}/voicemails/{recId}

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string
recIdrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string · data.id
deletedrequired
boolean · data.deleted

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Release a phone number

POST/api/v1/dids/{id}/release

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Cancels the number and stops its monthly charge. Irreversible: the number goes back to the carrier.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
Same fields as Did, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get a number's SMS settings

GET/api/v1/dids/{id}/sms-settings

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

While SMS on numbers is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
smsEnabledrequired
boolean · data.smsEnabled
forwardWebhookUrlrequired
string | null · data.forwardWebhookUrl
https URL each inbound SMS is forwarded to
notifyEmailrequired
string | null · data.notifyEmail

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Update a number's SMS settings

PUT/api/v1/dids/{id}/sms-settings

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

smsEnabled
boolean
forwardWebhookUrl
string | null
https only; null or "" clears itmax 2048 chars
notifyEmail
string | null
null or "" clears itmax 255 chars

Response 200

FieldDescription

datarequired
object
Same fields as DidSmsSettings, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/dids/<id>/sms-settings" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "smsEnabled": true,
  "forwardWebhookUrl": "<forwardWebhookUrl>"
}'

Run it here with a test key.

List SMS conversations on a number

GET/api/v1/dids/{id}/messages/conversations

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

One row per other party, newest activity first, with unread counts.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object[]
peerrequired
string · data[].peer
lastBodyrequired
string · data[].lastBody
lastDirectionrequired
string · data[].lastDirection
One of in, out
lastStatusrequired
string · data[].lastStatus
One of received, queued, sent, delivered, failed
lastAtrequired
string (date-time) · data[].lastAt
ISO-8601 timestamp (UTC)
unreadrequired
integer · data[].unread
totalrequired
integer · data[].total

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List SMS messages on a number

GET/api/v1/dids/{id}/messages

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Newest first. Page older with before set to the previous nextBefore.

Parameters

idrequired
path · string
peer
query · string
One conversation; omit for the number's whole log
before
query · string
ISO timestamp: page older than this (use nextBefore)
limit
query · integer
Default 50

Response 200

FieldDescription

messagesrequired
object[]
idrequired
string (uuid) · messages[].id
directionrequired
string · messages[].direction
One of in, out
fromrequired
string · messages[].from
torequired
string · messages[].to
peerrequired
string · messages[].peer
The other party, digits only; the conversation key
bodyrequired
string · messages[].body
segmentsrequired
integer · messages[].segments
statusrequired
string · messages[].status
One of received, queued, sent, delivered, failed
errorrequired
string | null · messages[].error
providerMessageIdrequired
string | null · messages[].providerMessageId
Upstream carrier message id
readAtrequired
string (date-time) | null · messages[].readAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · messages[].createdAt
ISO-8601 timestamp (UTC)
nextBeforerequired
string | null

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Send an SMS from one of your numbers

POST/api/v1/dids/{id}/messages

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)
Safe retries: Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Real traffic: Sends a real SMS from your number, billed to your balance.

Charges per segment, then hands the message to the carrier. A hard send failure refunds the charge and marks the message failed.

Parameters

idrequired
path · string
X-Idempotency-Key
header · string
Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

FieldDescription

torequired
string
max 32 chars
bodyrequired
string
max 1600 chars
idempotencyKey
string | null
A retry with the same key returns the original messagemax 80 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
directionrequired
string · data.direction
One of in, out
fromrequired
string · data.from
torequired
string · data.to
peerrequired
string · data.peer
The other party, digits only; the conversation key
bodyrequired
string · data.body
segmentsrequired
integer · data.segments
statusrequired
string · data.status
One of received, queued, sent, delivered, failed
errorrequired
string | null · data.error
providerMessageIdrequired
string | null · data.providerMessageId
Upstream carrier message id
readAtrequired
string (date-time) | null · data.readAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
costrequired
money · data.cost
What you were charged; 0.000000 when failed and refunded USD as a decimal string with exactly 6 places, e.g. "0.012500".

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/<id>/messages" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+447700900123",
  "body": "Hello from Acme"
}'

Run it here with a test key.

Mark an SMS conversation read

POST/api/v1/dids/{id}/messages/read

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

peerrequired
string
max 32 chars

Response 200

FieldDescription

datarequired
object
updatedrequired
integer · data.updated

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/<id>/messages/read" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "peer": "<peer>"
}'

Run it here with a test key.

Search the catalogue by digit pattern or vanity run

GET/api/v1/dids/search

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Scans catalogue pages for groups whose dialing prefix matches. While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Parameters

pattern
query · string
Digits to match against the dialing prefix (country + area)
match
query · string
Default containsOne of contains, starts_with, ends_with, exact
vanity
query · string
Only prefixes with repeating or sequential runsOne of true, false, 1, 0, yes, no, on, off
countryId
query · string
typeId
query · string
text
query · string
Text over country, city and type name
limit
query · integer
Default 50

Response 200

FieldDescription

datarequired
object
hitsrequired
object[] · data.hits
groupIdrequired
string · data.hits[].groupId
Pass to POST /dids/buy with a skuId
countryrequired
string · data.hits[].country
countryIdrequired
string · data.hits[].countryId
Catalogue country id (filter value), not an ISO code
countryPrefixrequired
string · data.hits[].countryPrefix
cityrequired
string | null · data.hits[].city
areaPrefixrequired
string | null · data.hits[].areaPrefix
typeIdrequired
string | null · data.hits[].typeId
typeNamerequired
string | null · data.hits[].typeName
Local, National, Mobile, Toll-free...
skusrequired
object[] · data.hits[].skus
Same fields as DidCatalogSku, shown earlier on this page.
dialingPrefixrequired
string · data.hits[].dialingPrefix
Country prefix plus area prefix
vanityrequired
boolean · data.hits[].vanity
scannedPagesrequired
integer · data.scannedPages
truncatedrequired
boolean · data.truncated
True when the scan budget ran out before the end of the catalogue
hits
object[]
groupIdrequired
string · hits[].groupId
Pass to POST /dids/buy with a skuId
countryrequired
string · hits[].country
countryIdrequired
string · hits[].countryId
Catalogue country id (filter value), not an ISO code
countryPrefixrequired
string · hits[].countryPrefix
cityrequired
string | null · hits[].city
areaPrefixrequired
string | null · hits[].areaPrefix
typeIdrequired
string | null · hits[].typeId
typeNamerequired
string | null · hits[].typeName
Local, National, Mobile, Toll-free...
skusrequired
object[] · hits[].skus
Same fields as DidCatalogSku, shown earlier on this page.
dialingPrefixrequired
string · hits[].dialingPrefix
Country prefix plus area prefix
vanityrequired
boolean · hits[].vanity
scannedPages
integer
truncated
boolean
True when the scan budget ran out before the end of the catalogue

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Buy several phone numbers in one request

POST/api/v1/dids/bulk-buy

Access: API key. Scoped keys need numbers:write.
Rate limit: 100 requests per second (the default)
Safe retries: Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Moves money: Buys a phone number, charged to your balance.

Buys each item in order and reports a result per item. Stops buying once your balance runs out and marks the rest skipped.

Parameters

X-Idempotency-Key
header · string
Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

FieldDescription

itemsrequired
object[]
skuIdrequired
string · items[].skuId
max 64 chars
groupIdrequired
string · items[].groupId
max 64 chars
countryId
string · items[].countryId
max 64 chars
country
string · items[].country
max 120 chars
city
string | null · items[].city
max 120 chars
areaPrefix
string | null · items[].areaPrefix
max 16 chars
didType
string | null · items[].didType
max 40 chars

Response 201

FieldDescription

datarequired
object
requestedrequired
integer · data.requested
succeededrequired
integer · data.succeeded
failedrequired
integer · data.failed
skippedrequired
integer · data.skipped
itemsrequired
object[] · data.items
indexrequired
integer · data.items[].index
Position in the submitted array
skuIdrequired
string · data.items[].skuId
groupIdrequired
string · data.items[].groupId
statusrequired
string · data.items[].status
One of ok, failed, skipped
did
object · data.items[].did
Present when status is okSame fields as Did, shown earlier on this page.
error
string · data.items[].error

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X POST "https://packetexchange.io/api/v1/dids/bulk-buy" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "skuId": "<skuId>",
      "groupId": "<groupId>"
    }
  ]
}'

Run it here with a test key.

Get a spend and usage overview across your numbers

GET/api/v1/dids/analytics/overview

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Response 200

FieldDescription

datarequired
object
countsrequired
object · data.counts
totalrequired
integer · data.counts.total
activerequired
integer · data.counts.active
pendingrequired
integer · data.counts.pending
suspendedrequired
integer · data.counts.suspended
releasedrequired
integer · data.counts.released
failedrequired
integer · data.counts.failed
monthlyRecurringrequired
number · data.monthlyRecurring
Sum of monthly prices on active numbers, USD display number
lifetimeSpendrequired
number · data.lifetimeSpend
Net charged across all your numbers, USD display number
usagerequired
object · data.usage
callsrequired
integer · data.usage.calls
callMinutesrequired
number · data.usage.callMinutes
smsrequired
integer · data.usage.sms
voicemailsrequired
integer · data.usage.voicemails
voicemailMinutesrequired
number · data.usage.voicemailMinutes

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get spend and usage analytics for a number

GET/api/v1/dids/{id}/analytics

Access: API key. Scoped keys need numbers:read.
Rate limit: 100 requests per second (the default)

Totals and a month-by-month series. Spend figures are USD display numbers.

Parameters

idrequired
path · string
months
query · integer
Trailing months in the series

Response 200

FieldDescription

datarequired
object
numberrequired
string | null · data.number
statusrequired
string · data.status
pricerequired
object · data.price
setuprequired
money · data.price.setup
USD as a decimal string with exactly 6 places, e.g. "0.012500".
monthlyrequired
money · data.price.monthly
USD as a decimal string with exactly 6 places, e.g. "0.012500".
spendrequired
object · data.spend
USD as display numbers
grossrequired
number · data.spend.gross
refundedrequired
number · data.spend.refunded
netrequired
number · data.spend.net
setuprequired
number · data.spend.setup
recurringrequired
number · data.spend.recurring
usagerequired
object · data.usage
callsrequired
integer · data.usage.calls
callMinutesrequired
number · data.usage.callMinutes
smsrequired
integer · data.usage.sms
voicemailsrequired
integer · data.usage.voicemails
voicemailMinutesrequired
number · data.usage.voicemailMinutes
windowrequired
object · data.window
monthsrequired
integer · data.window.months
fromrequired
string · data.window.from
seriesrequired
object[] · data.series
callsrequired
integer · data.series[].calls
callMinutesrequired
number · data.series[].callMinutes
smsrequired
integer · data.series[].sms
voicemailsrequired
integer · data.series[].voicemails
voicemailMinutesrequired
number · data.series[].voicemailMinutes
periodrequired
string · data.series[].period
YYYY-MM
spendrequired
number · data.series[].spend
USD, display number

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Browse the public number catalogue

GET/api/v1/public/numbers/catalog

Access: Public. No key needed.
Rate limit: 30 requests per minute

No account needed: prices only, for pre-signup browsing. While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Parameters

countryId
query · string
From GET .../catalog/countries
typeId
query · string
From GET .../catalog/types
search
query · string
Text match over country, city, area prefix and type; digits also match the start of the full dialling prefix ("4420" finds London). Spans the whole catalogue once it is indexed, otherwise the fetched page
page
query · integer
sort
query · string
Order by the cheapest monthly price, setup price or location. Omitted: the catalogue orderOne of monthly_asc, monthly_desc, setup_asc, location_asc
maxMonthly
query · number
Only groups whose cheapest monthly price is at most this, in USD

Response 200

FieldDescription

groupsrequired
object[]
Same fields as DidCatalogGroup, shown earlier on this page.
totalrequired
integer | null
pagerequired
integer

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Number catalogue market summary

GET/api/v1/public/numbers/catalog/summary

Access: Public. No key needed.
Rate limit: 15 requests per minute

No account needed. The store's live figures: how many countries and number groups are for sale, and the cheapest monthly price by number type and by country. Prices only. Indexed in the background and refreshed about every 20 minutes. While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Response 200

FieldDescription

datarequired
object
ready
boolean · data.ready
The catalogue is being indexed (the first minute after a restart); ask again shortlyOne of false
complete
boolean · data.complete
false when the catalogue was larger than the indexing budget, so the figures are a lower bound
asOf
string (date-time) · data.asOf
When the catalogue was last indexed
groups
integer · data.groups
Buyable number groups (a city, area or national pool you order a number from)
countries
integer · data.countries
fromMonthly
number | null · data.fromMonthly
Cheapest monthly price in the catalogue, USD
types
object[] · data.types
Most groups first
typeIdrequired
string · data.types[].typeId
typeNamerequired
string · data.types[].typeName
Local, National, Mobile, Toll-free...
groupsrequired
integer · data.types[].groups
Number groups of this type
countriesrequired
integer · data.types[].countries
Countries with at least one group of this type
fromMonthlyrequired
number | null · data.types[].fromMonthly
Cheapest monthly price of this type, USD
fromSetuprequired
number | null · data.types[].fromSetup
Cheapest one-off setup price of this type, USD
countryList
object[] · data.countryList
Alphabetical
countryIdrequired
string · data.countryList[].countryId
Catalogue country id (filter value)
countryrequired
string · data.countryList[].country
countryPrefixrequired
string · data.countryList[].countryPrefix
groupsrequired
integer · data.countryList[].groups
fromMonthlyrequired
number | null · data.countryList[].fromMonthly
Cheapest monthly price in this country, USD
typeIdsrequired
string[] · data.countryList[].typeIds
Number types sold in this country

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List countries in the public number catalogue

GET/api/v1/public/numbers/catalog/countries

Access: Public. No key needed.
Rate limit: 15 requests per minute

While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Response 200

FieldDescription

datarequired
object[]
Same fields as DidCatalogCountry, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List number types in the public number catalogue

GET/api/v1/public/numbers/catalog/types

Access: Public. No key needed.
Rate limit: 15 requests per minute

While the number store is switched off this answers 200 with data: { disabled: true, comingSoon: true, message }.

Response 200

FieldDescription

datarequired
object[]
Same fields as DidCatalogType, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.