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

Name	In	Type	Description
`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

Field	Type	Description
`groups`required	object[]	-
`groupId`requiredgroups[].groupId	string	Pass to POST /dids/buy with a skuId
`country`requiredgroups[].country	string	-
`countryId`requiredgroups[].countryId	string	Catalogue country id (filter value), not an ISO code
`countryPrefix`requiredgroups[].countryPrefix	string	-
`city`requiredgroups[].city	string \| null	-
`areaPrefix`requiredgroups[].areaPrefix	string \| null	-
`typeId`requiredgroups[].typeId	string \| null	-
`typeName`requiredgroups[].typeName	string \| null	Local, National, Mobile, Toll-free...
`skus`requiredgroups[].skus	object[]	-
`skuId`requiredgroups[].skus[].skuId	string	Pass to POST /dids/buy
`channels`requiredgroups[].skus[].channels	integer	Concurrent call channels included
`setupPrice`requiredgroups[].skus[].setupPrice	number	One-off price in USD (display number, not a money string)
`monthlyPrice`requiredgroups[].skus[].monthlyPrice	number	Monthly price in USD (display number, not a money string)
`total`required	integer \| null	-
`page`required	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

Field	Type	Description
`data`required	object[]	-
`countryId`requireddata[].countryId	string	-
`country`requireddata[].country	string	-
`countryPrefix`requireddata[].countryPrefix	string	-

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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string	-
`name`requireddata[].name	string	-

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

Name	In	Type	Description
`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)

Field	Type	Description
`skuId`required	string	-max 64 chars
`groupId`required	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

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`number`requireddata.number	string \| null	null while the number is still being provisioned
`country`requireddata.country	string \| null	-
`countryCode`requireddata.countryCode	string \| null	ISO-3166-1 alpha-2 country codemax 2 chars
`city`requireddata.city	string \| null	-
`areaPrefix`requireddata.areaPrefix	string \| null	-
`didType`requireddata.didType	string \| null	-
`channelsIncluded`requireddata.channelsIncluded	integer	-
`status`requireddata.status	string	suspended = a monthly renewal failed; the number is held for `graceDays` before releaseOne of `pending`, `active`, `suspended`, `released`, `failed`
`pointMode`requireddata.pointMode	string	-One of `unrouted`, `sip`, `forward`
`pointsTo`requireddata.pointsTo	string \| null	Primary destination: host[:port] for sip, E.164 for forward
`pointsToBackup`requireddata.pointsToBackup	string \| null	-
`autoRenew`requireddata.autoRenew	boolean	-
`setupPrice`requireddata.setupPrice	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`monthlyPrice`requireddata.monthlyPrice	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`orderedAt`requireddata.orderedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`activatedAt`requireddata.activatedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`nextRenewalAt`requireddata.nextRenewalAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`suspendedAt`requireddata.suspendedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`releasedAt`requireddata.releasedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`endpointReachable`requireddata.endpointReachable	boolean \| null	null = not checked yet
`endpointCause`requireddata.endpointCause	string \| null	-
`endpointCheckedAt`requireddata.endpointCheckedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`aiAgentId`requireddata.aiAgentId	string (uuid) \| null	The AI voice agent answering inbound calls to this number, or null (PUT /dids/{id}/ai-agent)
`graceDays`requireddata.graceDays	integer	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

Field	Type	Description
`data`required	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

Field	Type	Description
`data`required	object	-
`ownedActiveDids`requireddata.ownedActiveDids	integer	-
`request`requireddata.request	object \| null	Your latest request, or null
`id`requireddata.request.id	string (uuid)	-
`status`requireddata.request.status	string	-
`selectedDids`requireddata.request.selectedDids	object[] \| null	-
`id`requireddata.request.selectedDids[].id	string (uuid)	-
`number`requireddata.request.selectedDids[].number	string \| null	-
`country`requireddata.request.selectedDids[].country	string \| null	-
`didType`requireddata.request.selectedDids[].didType	string \| null	-
`didCount`requireddata.request.didCount	integer \| null	-
`submittedAt`requireddata.request.submittedAt	string (date-time)	ISO-8601 timestamp (UTC)
`reviewedAt`requireddata.request.reviewedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`prefill`requireddata.prefill	object	-
`companyName`requireddata.prefill.companyName	string	-
`contactName`requireddata.prefill.contactName	string	-
`contactEmail`requireddata.prefill.contactEmail	string	-
`contactPhone`requireddata.prefill.contactPhone	string	-

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)

Field	Type	Description
`companyName`	string \| null	-max 255 chars
`contactName`required	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

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`status`requireddata.status	string	-
`submittedAt`requireddata.submittedAt	string (date-time)	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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`cli`requireddata[].cli	string	Digits only
`number`requireddata[].number	string	-
`country`requireddata[].country	string \| null	-
`countryCode`requireddata[].countryCode	string \| null	-
`city`requireddata[].city	string \| null	-
`didType`requireddata[].didType	string \| null	-
`channels`requireddata[].channels	integer	-
`label`requireddata[].label	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.
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)

Field	Type	Description
`setId`required	string (uuid)	One of your dialer caller-ID sets
`didIds`	string (uuid)[] \| string	Omit or "all" for every active number

Response 201

Field	Type	Description
`data`required	object	-
`inserted`requireddata.inserted	integer	-
`skipped`requireddata.skipped	integer	-
`rejects`requireddata.rejects	object[]	-
`value`requireddata.rejects[].value	string	-
`reason`requireddata.rejects[].reason	string	-

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`strategy`requireddata.strategy	string	-One of `failover`, `simultaneous`
`timeoutSec`requireddata.timeoutSec	integer	-
`endpoints`requireddata.endpoints	object[]	-
`id`requireddata.endpoints[].id	string (uuid)	-
`kind`requireddata.endpoints[].kind	string	-One of `sip`, `forward`, `hosted`
`target`requireddata.endpoints[].target	string \| null	-
`sipUsername`requireddata.endpoints[].sipUsername	string \| null	Hosted lines only; the password is never listed
`label`requireddata.endpoints[].label	string \| null	-
`priority`requireddata.endpoints[].priority	integer	-
`enabled`requireddata.endpoints[].enabled	boolean	-

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`mode`required	string	-One of `sip`, `forward`
`target`required	string	host[:port] for sip, E.164 for forwardmax 255 chars
`backupMode`	string \| null	Defaults to `mode`One of `sip`, `forward`
`backupTarget`	string \| null	null or "" clears the backup; omit to keep itmax 255 chars

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`sipUsername`requireddata[].sipUsername	string	-
`label`requireddata[].label	string \| null	-
`priority`requireddata[].priority	integer	-
`enabled`requireddata[].enabled	boolean	-
`createdAt`requireddata[].createdAt	string (date-time)	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`label`	string \| null	-max 120 chars

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`sipUsername`requireddata.sipUsername	string	-
`sipPassword`requireddata.sipPassword	string	Shown only here and on an explicit reveal
`server`requireddata.server	string	-
`port`requireddata.port	string	-

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

Name	In	Type	Description
`id`required	path	string	-
`lineId`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-
`lineId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string	-
`deleted`requireddata.deleted	boolean	-

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`enabled`required	boolean	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-
`limit`	query	integer	Newest first; default 200

Response 200

Field	Type	Description
`data`required	object	-
`calls`requireddata.calls	object[]	-
`id`requireddata.calls[].id	string (uuid)	-
`fromNumber`requireddata.calls[].fromNumber	string \| null	-
`toNumber`requireddata.calls[].toNumber	string \| null	-
`durationSec`requireddata.calls[].durationSec	integer	-
`status`requireddata.calls[].status	string \| null	-
`startedAt`requireddata.calls[].startedAt	string (date-time)	ISO-8601 timestamp (UTC)
`summary`requireddata.summary	object	-
`calls`requireddata.summary.calls	integer	-
`minutes`requireddata.summary.minutes	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.

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

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`didId`requireddata.didId	string (uuid)	-
`agentId`requireddata.agentId	string (uuid) \| null	-
`agentName`requireddata.agentName	string \| null	-
`agentEnabled`requireddata.agentEnabled	boolean \| null	A disabled agent does not answer; the number rings its call flow
`live`requireddata.live	boolean	Whether inbound AI answering is switched on for the platform right now
`ratePerMin`requireddata.ratePerMin	string	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

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`agentId`required	string (uuid) \| null	One of your AI agents (GET /ai-agents), or null to clear

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`voicemail`requireddata.voicemail	object	-
`enabled`requireddata.voicemail.enabled	boolean	-
`mode`requireddata.voicemail.mode	string	-One of `on_no_answer`, `always`
`greetingAssetId`requireddata.voicemail.greetingAssetId	string (uuid) \| null	-
`hasGreeting`requireddata.voicemail.hasGreeting	boolean	-
`transcribe`requireddata.voicemail.transcribe	boolean	-
`recording`requireddata.recording	object	-
`enabled`requireddata.recording.enabled	boolean	-
`announce`requireddata.recording.announce	boolean	-
`retentionDays`requireddata.recording.retentionDays	integer	-
`ivr`requireddata.ivr	object	-
`enabled`requireddata.ivr.enabled	boolean	-
`greetingAssetId`requireddata.ivr.greetingAssetId	string (uuid) \| null	-
`hasGreeting`requireddata.ivr.hasGreeting	boolean	-
`timeoutSec`requireddata.ivr.timeoutSec	integer	-
`maxRetries`requireddata.ivr.maxRetries	integer	-
`options`requireddata.ivr.options	object[]	-
`id`requireddata.ivr.options[].id	string (uuid)	-
`digit`requireddata.ivr.options[].digit	string	-
`action`requireddata.ivr.options[].action	string	-One of `endpoint`, `voicemail`, `hangup`
`endpointId`requireddata.ivr.options[].endpointId	string (uuid) \| null	-
`label`requireddata.ivr.options[].label	string \| null	-
`schedule`requireddata.schedule	object	-
`enabled`requireddata.schedule.enabled	boolean	-
`timezone`requireddata.schedule.timezone	string	-
`schedule`requireddata.schedule.schedule	object \| null	-
`sun`requireddata.schedule.schedule.sun	object[]	-
`open`requireddata.schedule.schedule.sun[].open	string	HH:MMmax 5 chars
`close`requireddata.schedule.schedule.sun[].close	string	HH:MMmax 5 chars
`mon`requireddata.schedule.schedule.mon	object[]	-
`open`requireddata.schedule.schedule.mon[].open	string	HH:MMmax 5 chars
`close`requireddata.schedule.schedule.mon[].close	string	HH:MMmax 5 chars
`tue`requireddata.schedule.schedule.tue	object[]	-
`open`requireddata.schedule.schedule.tue[].open	string	HH:MMmax 5 chars
`close`requireddata.schedule.schedule.tue[].close	string	HH:MMmax 5 chars
`wed`requireddata.schedule.schedule.wed	object[]	-
`open`requireddata.schedule.schedule.wed[].open	string	HH:MMmax 5 chars
`close`requireddata.schedule.schedule.wed[].close	string	HH:MMmax 5 chars
`thu`requireddata.schedule.schedule.thu	object[]	-
`open`requireddata.schedule.schedule.thu[].open	string	HH:MMmax 5 chars
`close`requireddata.schedule.schedule.thu[].close	string	HH:MMmax 5 chars
`fri`requireddata.schedule.schedule.fri	object[]	-
`open`requireddata.schedule.schedule.fri[].open	string	HH:MMmax 5 chars
`close`requireddata.schedule.schedule.fri[].close	string	HH:MMmax 5 chars
`sat`requireddata.schedule.schedule.sat	object[]	-
`open`requireddata.schedule.schedule.sat[].open	string	HH:MMmax 5 chars
`close`requireddata.schedule.schedule.sat[].close	string	HH:MMmax 5 chars
`holidays`requireddata.schedule.holidays	object[] \| null	-
`date`requireddata.schedule.holidays[].date	string	YYYY-MM-DDmax 10 chars
`name`data.schedule.holidays[].name	string	-max 120 chars
`outsideHoursAction`requireddata.schedule.outsideHoursAction	string	-One of `voicemail`, `endpoints`, `hangup`
`closedEndpoints`requireddata.schedule.closedEndpoints	object[]	-
`id`requireddata.schedule.closedEndpoints[].id	string (uuid)	-
`kind`requireddata.schedule.closedEndpoints[].kind	string	-One of `sip`, `forward`
`target`requireddata.schedule.closedEndpoints[].target	string	-
`label`requireddata.schedule.closedEndpoints[].label	string \| null	-
`priority`requireddata.schedule.closedEndpoints[].priority	integer	-
`enabled`requireddata.schedule.closedEndpoints[].enabled	boolean	-
`openNow`requireddata.schedule.openNow	boolean \| null	-
`assets`requireddata.assets	object[]	-
`id`requireddata.assets[].id	string (uuid)	-
`kind`requireddata.assets[].kind	string	-One of `voicemail_greeting`, `ivr_greeting`
`name`requireddata.assets[].name	string \| null	-
`mime`requireddata.assets[].mime	string	-
`createdAt`requireddata.assets[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`mediaLive`requireddata.mediaLive	boolean	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`enabled`	boolean	-
`mode`	string	-One of `on_no_answer`, `always`
`greetingAssetId`	string (uuid) \| null	-
`transcribe`	boolean	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`enabled`	boolean	-
`announce`	boolean	-
`retentionDays`	integer	-0 to 3650

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`enabled`	boolean	-
`timezone`	string	IANA zone, e.g. Europe/Londonmax 64 chars
`schedule`	object	-
`sun`requiredschedule.sun	object[]	-
`open`requiredschedule.sun[].open	string	HH:MMmax 5 chars
`close`requiredschedule.sun[].close	string	HH:MMmax 5 chars
`mon`requiredschedule.mon	object[]	-
`open`requiredschedule.mon[].open	string	HH:MMmax 5 chars
`close`requiredschedule.mon[].close	string	HH:MMmax 5 chars
`tue`requiredschedule.tue	object[]	-
`open`requiredschedule.tue[].open	string	HH:MMmax 5 chars
`close`requiredschedule.tue[].close	string	HH:MMmax 5 chars
`wed`requiredschedule.wed	object[]	-
`open`requiredschedule.wed[].open	string	HH:MMmax 5 chars
`close`requiredschedule.wed[].close	string	HH:MMmax 5 chars
`thu`requiredschedule.thu	object[]	-
`open`requiredschedule.thu[].open	string	HH:MMmax 5 chars
`close`requiredschedule.thu[].close	string	HH:MMmax 5 chars
`fri`requiredschedule.fri	object[]	-
`open`requiredschedule.fri[].open	string	HH:MMmax 5 chars
`close`requiredschedule.fri[].close	string	HH:MMmax 5 chars
`sat`requiredschedule.sat	object[]	-
`open`requiredschedule.sat[].open	string	HH:MMmax 5 chars
`close`requiredschedule.sat[].close	string	HH:MMmax 5 chars
`holidays`	object[]	-
`date`requiredholidays[].date	string	YYYY-MM-DDmax 10 chars
`name`holidays[].name	string	-max 120 chars
`outsideHoursAction`	string	-One of `voicemail`, `endpoints`, `hangup`
`closedEndpoints`	object[]	-
`kind`requiredclosedEndpoints[].kind	string	-One of `sip`, `forward`
`target`requiredclosedEndpoints[].target	string	-max 255 chars
`label`closedEndpoints[].label	string \| null	-max 120 chars
`priority`closedEndpoints[].priority	integer	-1 to 999
`enabled`closedEndpoints[].enabled	boolean	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`kind`requireddata[].kind	string	-One of `voicemail_greeting`, `ivr_greeting`
`name`requireddata[].name	string \| null	-
`mime`requireddata[].mime	string	-
`createdAt`requireddata[].createdAt	string (date-time)	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`kind`required	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

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-
`assetId`required	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

Name	In	Type	Description
`id`required	path	string	-
`assetId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string	-
`deleted`requireddata.deleted	boolean	-

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

Name	In	Type	Description
`id`required	path	string	-
`limit`	query	integer	Newest first; default 200

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`kind`requireddata[].kind	string	-One of `call`, `voicemail`
`fromNumber`requireddata[].fromNumber	string \| null	-
`toNumber`requireddata[].toNumber	string \| null	-
`durationSec`requireddata[].durationSec	integer	-
`mime`requireddata[].mime	string \| null	-
`byteSize`requireddata[].byteSize	integer	-
`heard`requireddata[].heard	boolean	-
`transcript`requireddata[].transcript	string \| null	-
`hasAudio`requireddata[].hasAudio	boolean	-
`expiresAt`requireddata[].expiresAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata[].createdAt	string (date-time)	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

Name	In	Type	Description
`id`required	path	string	-
`recId`required	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

Name	In	Type	Description
`id`required	path	string	-
`recId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string	-
`deleted`requireddata.deleted	boolean	-

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

Name	In	Type	Description
`id`required	path	string	-
`limit`	query	integer	Newest first; default 200

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-
`recId`required	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

Name	In	Type	Description
`id`required	path	string	-
`recId`required	path	string	-

Request body (application/json)

Field	Type	Description
`heard`	boolean	Default true

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`heard`requireddata.heard	boolean	-

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

Name	In	Type	Description
`id`required	path	string	-
`recId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string	-
`deleted`requireddata.deleted	boolean	-

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`smsEnabled`requireddata.smsEnabled	boolean	-
`forwardWebhookUrl`requireddata.forwardWebhookUrl	string \| null	https URL each inbound SMS is forwarded to
`notifyEmail`requireddata.notifyEmail	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.

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`smsEnabled`	boolean	-
`forwardWebhookUrl`	string \| null	https only; null or "" clears itmax 2048 chars
`notifyEmail`	string \| null	null or "" clears itmax 255 chars

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object[]	-
`peer`requireddata[].peer	string	-
`lastBody`requireddata[].lastBody	string	-
`lastDirection`requireddata[].lastDirection	string	-One of `in`, `out`
`lastStatus`requireddata[].lastStatus	string	-One of `received`, `queued`, `sent`, `delivered`, `failed`
`lastAt`requireddata[].lastAt	string (date-time)	ISO-8601 timestamp (UTC)
`unread`requireddata[].unread	integer	-
`total`requireddata[].total	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.
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

Name	In	Type	Description
`id`required	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

Field	Type	Description
`messages`required	object[]	-
`id`requiredmessages[].id	string (uuid)	-
`direction`requiredmessages[].direction	string	-One of `in`, `out`
`from`requiredmessages[].from	string	-
`to`requiredmessages[].to	string	-
`peer`requiredmessages[].peer	string	The other party, digits only; the conversation key
`body`requiredmessages[].body	string	-
`segments`requiredmessages[].segments	integer	-
`status`requiredmessages[].status	string	-One of `received`, `queued`, `sent`, `delivered`, `failed`
`error`requiredmessages[].error	string \| null	-
`providerMessageId`requiredmessages[].providerMessageId	string \| null	Upstream carrier message id
`readAt`requiredmessages[].readAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requiredmessages[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`nextBefore`required	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

Name	In	Type	Description
`id`required	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)

Field	Type	Description
`to`required	string	-max 32 chars
`body`required	string	-max 1600 chars
`idempotencyKey`	string \| null	A retry with the same key returns the original messagemax 80 chars

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`direction`requireddata.direction	string	-One of `in`, `out`
`from`requireddata.from	string	-
`to`requireddata.to	string	-
`peer`requireddata.peer	string	The other party, digits only; the conversation key
`body`requireddata.body	string	-
`segments`requireddata.segments	integer	-
`status`requireddata.status	string	-One of `received`, `queued`, `sent`, `delivered`, `failed`
`error`requireddata.error	string \| null	-
`providerMessageId`requireddata.providerMessageId	string \| null	Upstream carrier message id
`readAt`requireddata.readAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`cost`requireddata.cost	money	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`peer`required	string	-max 32 chars

Response 200

Field	Type	Description
`data`required	object	-
`updated`requireddata.updated	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.
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

Name	In	Type	Description
`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

Field	Type	Description
`data`required	object	-
`hits`requireddata.hits	object[]	-
`groupId`requireddata.hits[].groupId	string	Pass to POST /dids/buy with a skuId
`country`requireddata.hits[].country	string	-
`countryId`requireddata.hits[].countryId	string	Catalogue country id (filter value), not an ISO code
`countryPrefix`requireddata.hits[].countryPrefix	string	-
`city`requireddata.hits[].city	string \| null	-
`areaPrefix`requireddata.hits[].areaPrefix	string \| null	-
`typeId`requireddata.hits[].typeId	string \| null	-
`typeName`requireddata.hits[].typeName	string \| null	Local, National, Mobile, Toll-free...
`skus`requireddata.hits[].skus	object[]	Same fields as DidCatalogSku, shown earlier on this page.
`dialingPrefix`requireddata.hits[].dialingPrefix	string	Country prefix plus area prefix
`vanity`requireddata.hits[].vanity	boolean	-
`scannedPages`requireddata.scannedPages	integer	-
`truncated`requireddata.truncated	boolean	True when the scan budget ran out before the end of the catalogue
`hits`	object[]	-
`groupId`requiredhits[].groupId	string	Pass to POST /dids/buy with a skuId
`country`requiredhits[].country	string	-
`countryId`requiredhits[].countryId	string	Catalogue country id (filter value), not an ISO code
`countryPrefix`requiredhits[].countryPrefix	string	-
`city`requiredhits[].city	string \| null	-
`areaPrefix`requiredhits[].areaPrefix	string \| null	-
`typeId`requiredhits[].typeId	string \| null	-
`typeName`requiredhits[].typeName	string \| null	Local, National, Mobile, Toll-free...
`skus`requiredhits[].skus	object[]	Same fields as DidCatalogSku, shown earlier on this page.
`dialingPrefix`requiredhits[].dialingPrefix	string	Country prefix plus area prefix
`vanity`requiredhits[].vanity	boolean	-
`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

Name	In	Type	Description
`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)

Field	Type	Description
`items`required	object[]	-
`skuId`requireditems[].skuId	string	-max 64 chars
`groupId`requireditems[].groupId	string	-max 64 chars
`countryId`items[].countryId	string	-max 64 chars
`country`items[].country	string	-max 120 chars
`city`items[].city	string \| null	-max 120 chars
`areaPrefix`items[].areaPrefix	string \| null	-max 16 chars
`didType`items[].didType	string \| null	-max 40 chars

Response 201

Field	Type	Description
`data`required	object	-
`requested`requireddata.requested	integer	-
`succeeded`requireddata.succeeded	integer	-
`failed`requireddata.failed	integer	-
`skipped`requireddata.skipped	integer	-
`items`requireddata.items	object[]	-
`index`requireddata.items[].index	integer	Position in the submitted array
`skuId`requireddata.items[].skuId	string	-
`groupId`requireddata.items[].groupId	string	-
`status`requireddata.items[].status	string	-One of `ok`, `failed`, `skipped`
`did`data.items[].did	object	Present when status is okSame fields as Did, shown earlier on this page.
`error`data.items[].error	string	-

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

Field	Type	Description
`data`required	object	-
`counts`requireddata.counts	object	-
`total`requireddata.counts.total	integer	-
`active`requireddata.counts.active	integer	-
`pending`requireddata.counts.pending	integer	-
`suspended`requireddata.counts.suspended	integer	-
`released`requireddata.counts.released	integer	-
`failed`requireddata.counts.failed	integer	-
`monthlyRecurring`requireddata.monthlyRecurring	number	Sum of monthly prices on active numbers, USD display number
`lifetimeSpend`requireddata.lifetimeSpend	number	Net charged across all your numbers, USD display number
`usage`requireddata.usage	object	-
`calls`requireddata.usage.calls	integer	-
`callMinutes`requireddata.usage.callMinutes	number	-
`sms`requireddata.usage.sms	integer	-
`voicemails`requireddata.usage.voicemails	integer	-
`voicemailMinutes`requireddata.usage.voicemailMinutes	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.
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

Name	In	Type	Description
`id`required	path	string	-
`months`	query	integer	Trailing months in the series

Response 200

Field	Type	Description
`data`required	object	-
`number`requireddata.number	string \| null	-
`status`requireddata.status	string	-
`price`requireddata.price	object	-
`setup`requireddata.price.setup	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`monthly`requireddata.price.monthly	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`spend`requireddata.spend	object	USD as display numbers
`gross`requireddata.spend.gross	number	-
`refunded`requireddata.spend.refunded	number	-
`net`requireddata.spend.net	number	-
`setup`requireddata.spend.setup	number	-
`recurring`requireddata.spend.recurring	number	-
`usage`requireddata.usage	object	-
`calls`requireddata.usage.calls	integer	-
`callMinutes`requireddata.usage.callMinutes	number	-
`sms`requireddata.usage.sms	integer	-
`voicemails`requireddata.usage.voicemails	integer	-
`voicemailMinutes`requireddata.usage.voicemailMinutes	number	-
`window`requireddata.window	object	-
`months`requireddata.window.months	integer	-
`from`requireddata.window.from	string	-
`series`requireddata.series	object[]	-
`calls`requireddata.series[].calls	integer	-
`callMinutes`requireddata.series[].callMinutes	number	-
`sms`requireddata.series[].sms	integer	-
`voicemails`requireddata.series[].voicemails	integer	-
`voicemailMinutes`requireddata.series[].voicemailMinutes	number	-
`period`requireddata.series[].period	string	YYYY-MM
`spend`requireddata.series[].spend	number	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

Name	In	Type	Description
`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

Field	Type	Description
`groups`required	object[]	Same fields as DidCatalogGroup, shown earlier on this page.
`total`required	integer \| null	-
`page`required	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

Field	Type	Description
`data`required	object	-
`ready`data.ready	boolean	The catalogue is being indexed (the first minute after a restart); ask again shortlyOne of `false`
`complete`data.complete	boolean	false when the catalogue was larger than the indexing budget, so the figures are a lower bound
`asOf`data.asOf	string (date-time)	When the catalogue was last indexed
`groups`data.groups	integer	Buyable number groups (a city, area or national pool you order a number from)
`countries`data.countries	integer	-
`fromMonthly`data.fromMonthly	number \| null	Cheapest monthly price in the catalogue, USD
`types`data.types	object[]	Most groups first
`typeId`requireddata.types[].typeId	string	-
`typeName`requireddata.types[].typeName	string	Local, National, Mobile, Toll-free...
`groups`requireddata.types[].groups	integer	Number groups of this type
`countries`requireddata.types[].countries	integer	Countries with at least one group of this type
`fromMonthly`requireddata.types[].fromMonthly	number \| null	Cheapest monthly price of this type, USD
`fromSetup`requireddata.types[].fromSetup	number \| null	Cheapest one-off setup price of this type, USD
`countryList`data.countryList	object[]	Alphabetical
`countryId`requireddata.countryList[].countryId	string	Catalogue country id (filter value)
`country`requireddata.countryList[].country	string	-
`countryPrefix`requireddata.countryList[].countryPrefix	string	-
`groups`requireddata.countryList[].groups	integer	-
`fromMonthly`requireddata.countryList[].fromMonthly	number \| null	Cheapest monthly price in this country, USD
`typeIds`requireddata.countryList[].typeIds	string[]	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

Field	Type	Description
`data`required	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

Field	Type	Description
`data`required	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.