API reference

Voice and SMS

Place single calls and send single SMS over the routes you bought, and read their history.

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

BrowseVoice and SMS

List your API call history

GET/api/v1/comms/calls

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Ledger entries for calls placed through POST /comms/calls, newest first.

Parameters

Name	In	Type	Description
`type`	query	string	Accepted but not applied: each endpoint already fixes its own typeOne of api_call, api_sms, smpp_sms, dialer_campaign
`from`	query	string (date-time)	Only rows created at or after this instant
`to`	query	string (date-time)	Only rows created before this instant
`cursor`	query	string (uuid)	The `nextCursor` from the previous page
`limit`	query	integer	-Default 25

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`userId`requireddata[].userId	string (uuid)	-
`type`requireddata[].type	string	Ledger entry type, e.g. charge
`amount`requireddata[].amount	money	Signed: a charge is negative USD as a decimal string with exactly 6 places, e.g. "0.012500".
`balanceAfter`requireddata[].balanceAfter	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`reference`requireddata[].reference	string \| null	Human-readable description of the call or message
`relatedEntityType`requireddata[].relatedEntityType	string \| null	api_call for calls; api_sms or smpp_sms for messages
`relatedEntityId`requireddata[].relatedEntityId	string (uuid) \| null	The callId or messageId
`callId`requireddata[].callId	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`nextCursor`required	string \| null	Pass as `cursor` to fetch the next page; null on the last page.
`hasMore`required	boolean	True when another page exists.

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.

Place a single outbound call

POST/api/v1/comms/calls

Access: API key. Scoped keys need voice:send.
Rate limit: 10 requests per second
Safe retries: Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Real traffic: Places a real call or sends a real message, billed to your balance. A test key simulates it against test credit.

Dials to over a route you purchased (or one Smart Routing selects). By default the request BLOCKS until the call ends - answer and hangup, no answer, or maxDuration - then returns the outcome and what it cost (200); set a client timeout above maxDuration. With async: true it returns at once with 202 and status: ringing; follow the call on GET /comms/calls/{id} or with the call.ringing, call.answered, call.gathered and call.completed webhooks. Validation, routing and balance errors are still returned straight away in both modes. actions make the answered call speak (say, in en, es, fr, de, pt or hi), play an MP3 (play), collect keypad digits (gather), wait (pause) or end (hangup), in order; audio is prepared before dialling, so a bad URL costs nothing. Billed per the route increment at the route price plus the platform fee, after the call completes; there is no charge for spoken text. A test key simulates the call against test credit and runs no actions.

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
`to`required	string	Destination number (E.164)
`from`required	string	Caller ID to present (E.164)
`routeId`	string (uuid)	A route you purchased. Omit to let Smart Routing pick one
`strategy`	string	Smart Routing strategy used when routeId is omittedOne of `cheapest`, `best_quality`, `balanced`
`maxDuration`	integer	Hang up after this many seconds10 to 3600, default 300
`async`	boolean	Return at once (202, status ringing) instead of waiting for the call to end. Follow the call on GET /comms/calls/{id} or with the call.* webhooks
`actions`	object[]	What the call does once answered, in order: say, play, gather, pause, hangup. At most 10 actions, 1,500 characters of spoken text, 3 play URLs and 5 gathers. The call ends when the actions finish
`say`actions[].say	string	Text spoken by our text-to-speech voicemax 500 chars
`language`actions[].language	string	Overrides the call default for this actionOne of `en`, `es`, `fr`, `de`, `pt`, `hi`
`play`actions[].play	string (uri)	HTTPS URL of an MP3 file, at most 2 MB. We download it once before dialling (public addresses only, no redirects) and play our copymax 2048 chars
`gather`actions[].gather	object	-
`digits`actions[].gather.digits	integer	Most keys to collect1 to 20, default 1
`timeout`actions[].gather.timeout	integer	Seconds to wait for the first key1 to 30, default 5
`finishOnKey`actions[].gather.finishOnKey	string	Key that ends input early; empty for nonedefault "#"One of `#`, `*`,
`tries`actions[].gather.tries	integer	Prompt and wait again this many times in total when nothing is pressed1 to 3, default 1
`say`actions[].gather.say	string	Prompt spoken while listening; a key press interrupts itmax 500 chars
`play`actions[].gather.play	string (uri)	Prompt played while listening (instead of say)max 2048 chars
`language`actions[].gather.language	string	-One of `en`, `es`, `fr`, `de`, `pt`, `hi`
`pause`actions[].pause	integer	Seconds of silence1 to 10
`hangup`actions[].hangup	boolean	-One of `true`
`language`	string	Default language for say actions (default en)One of `en`, `es`, `fr`, `de`, `pt`, `hi`

Response 200

Field	Type	Description
`data`required	object	-
`callId`data.callId	string (uuid)	Use with GET /comms/calls/{id}; the same id appears on the call.* webhooks
`to`data.to	string	-
`from`data.from	string	-
`status`data.status	string	The call has been handed to the network and is being dialledOne of `ringing`
`sipResponseCode`data.sipResponseCode	integer \| null	-
`hangupCause`data.hangupCause	string \| null	-
`durationSeconds`data.durationSeconds	integer	-
`billableSeconds`data.billableSeconds	integer	Duration rounded up to the route billing increment
`cost`data.cost	money	What this call cost you, platform fee included USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`data.billingIncrement	string	The route billing increment, e.g. "6/6" or "60/60"
`startedAt`data.startedAt	string (date-time)	ISO-8601 timestamp (UTC)
`completedAt`data.completedAt	string (date-time)	ISO-8601 timestamp (UTC)
`simulated`data.simulated	boolean	Present and true for test-key calls: nothing was dialled
`routeId`data.routeId	string (uuid) \| null	Present on calls placed over a failover chain (Smart Routing calls with automatic failover, and Switch sub-account calls): the route that carried the call, or the last one tried
`attempts`data.attempts	object[]	Present when the call was tried on more than one route: each route tried, in order. Only the one that connected is billed; a wrong number (404/484), a busy or declined call and no answer are never retried
`routeId`requireddata.attempts[].routeId	string (uuid)	-
`sipResponseCode`requireddata.attempts[].sipResponseCode	integer \| null	-
`status`requireddata.attempts[].status	string	-
`hangupCause`requireddata.attempts[].hangupCause	string \| null	-
`mode`data.mode	string	-One of `async`
`actions`data.actions	integer	How many call actions will run on answer
`statusUrl`data.statusUrl	string	Path of GET /comms/calls/{id} for this call

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/comms/calls" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+447700900123",
  "from": "+447700900123"
}'

Run it here with a test key.

Get one call: live status, cost and gathered digits

GET/api/v1/comms/calls/{id}

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

Works for any call placed through POST /comms/calls, while it runs and after it ends: status, timestamps, duration, cost, the hangup cause in plain words, and the digits collected by gather actions. A reseller sub-account key sees only its own calls. Unknown ids answer 404.

Parameters

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

Response 200

Field	Type	Description
`data`required	object	-
`callId`requireddata.callId	string (uuid)	-
`status`requireddata.status	string	queued, ringing and answered are live states; completed (answered, then ended), no_answer, busy and failed are finalOne of `queued`, `ringing`, `answered`, `completed`, `no_answer`, `busy`, `failed`
`mode`requireddata.mode	string	-One of `sync`, `async`
`to`requireddata.to	string	-
`from`requireddata.from	string	-
`simulated`requireddata.simulated	boolean	True for test-key calls: nothing was dialled
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`ringingAt`requireddata.ringingAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`answeredAt`requireddata.answeredAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`endedAt`requireddata.endedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`durationSeconds`requireddata.durationSeconds	integer \| null	-
`billableSeconds`requireddata.billableSeconds	integer \| null	Duration rounded up to the route billing increment
`cost`requireddata.cost	money \| null	What the call cost you, platform fee included. Null until it ends USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.billingIncrement	string \| null	-
`sipResponseCode`requireddata.sipResponseCode	integer \| null	-
`hangupCause`requireddata.hangupCause	string \| null	The switch cause code, e.g. NORMAL_CLEARING or USER_BUSY
`hangupReason`requireddata.hangupReason	string \| null	Why the call ended, in plain words. Null while it is live
`error`requireddata.error	string \| null	Why the call could not be placed, when it failed before reaching the network
`actions`requireddata.actions	any[] \| null	The call actions as you sent them
`gathered`requireddata.gathered	object[] \| null	Keypad input from gather actions, filled in when the call ends
`index`requireddata.gathered[].index	integer	Which gather action (0 for the first)
`digits`requireddata.gathered[].digits	string \| null	The keys pressed, without the finish key
`status`requireddata.gathered[].status	string	no_input: nothing was pressed, or the call ended before this stepOne of `received`, `no_input`
`routeId`data.routeId	string (uuid) \| null	Present when the call was placed over a failover chain: the route that carried it, or the last one tried
`attempts`data.attempts	object[]	Present when the call was tried on more than one route: every attempt in order. Only the attempt that connected is billed
`attempt`requireddata.attempts[].attempt	integer	1 for the first route tried
`routeId`requireddata.attempts[].routeId	string (uuid) \| null	-
`status`requireddata.attempts[].status	string	answered, failed, busy or no_answer
`sipResponseCode`requireddata.attempts[].sipResponseCode	integer \| null	-
`hangupCause`requireddata.attempts[].hangupCause	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.
AlsoNOT_FOUND

List your SMS history

GET/api/v1/comms/sms

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Ledger entries for messages sent over the API and SMPP, newest first.

Parameters

Name	In	Type	Description
`type`	query	string	Accepted but not applied: each endpoint already fixes its own typeOne of api_call, api_sms, smpp_sms, dialer_campaign
`from`	query	string (date-time)	Only rows created at or after this instant
`to`	query	string (date-time)	Only rows created before this instant
`cursor`	query	string (uuid)	The `nextCursor` from the previous page
`limit`	query	integer	-Default 25

Response 200

Field	Type	Description
`data`required	object[]	Same fields as CommsHistoryEntry, shown earlier on this page.
`nextCursor`required	string \| null	Pass as `cursor` to fetch the next page; null on the last page.
`hasMore`required	boolean	True when another page exists.

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.

Send a single SMS

POST/api/v1/comms/sms

Access: API key. Scoped keys need sms:send.
Rate limit: 10 requests per second
Safe retries: Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Real traffic: Places a real call or sends a real message, billed to your balance. A test key simulates it against test credit.

Forwards the message to the route seller and returns straight away with a message id. status is the send-time outcome (accepted, sent or failed). The final outcome comes later from the carrier's delivery receipt, when the route returns one: read it with GET /comms/sms/{messageId} or subscribe to the sms.delivered and sms.failed webhooks. A message that fails on its receipt is refunded. Billed per segment at the route price plus the platform fee. A test key simulates the send against test credit.

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
`to`required	string	Destination number (E.164)
`from`required	string	Sender ID: a number or an alphanumeric sender (letters, digits, spaces and . + _ -)max 30 chars
`routeId`	string (uuid)	A route you purchased. Omit to let Smart Routing pick one
`strategy`	string	Smart Routing strategy used when routeId is omittedOne of `cheapest`, `best_quality`, `balanced`
`message`required	string	Message body. Long messages are sent as concatenated segmentsmax 1600 chars

Response 200

Field	Type	Description
`data`required	object	-
`messageId`requireddata.messageId	string	Use with GET /comms/sms/{messageId}
`to`requireddata.to	string	-
`from`requireddata.from	string	-
`status`requireddata.status	string	Send-time outcome when we forwarded the message, not a handset delivery receiptOne of `sent`, `delivered`, `failed`, `pending`, `accepted`
`segments`requireddata.segments	integer	Billed segments (160 GSM-7 / 70 UCS-2 characters each, fewer when concatenated)
`cost`requireddata.cost	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`submittedAt`requireddata.submittedAt	string (date-time)	ISO-8601 timestamp (UTC)
`simulated`data.simulated	boolean	Present and true for test-key messages: nothing was sent
`network`data.network	object \| null	Present when the route prices SMS to this country per destination network. The network is determined from the number's range (ported numbers may be priced at the network the range belongs to)
`mccMnc`requireddata.network.mccMnc	string \| null	Mobile network code (MCC-MNC) the message was priced as, e.g. "234-10"
`operator`requireddata.network.operator	string \| null	Network name from public number-range data
`source`requireddata.network.source	string	range = number-range data; hlr = a live network lookup; none = not determinedOne of `range`, `hlr`, `none`
`rateBasis`requireddata.network.rateBasis	string	network = that network's own rate; all_operators = the route's rate for networks it does not list separately; country = the route's price for other or unknown networksOne of `network`, `all_operators`, `country`

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/comms/sms" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+447700900123",
  "from": "+447700900123",
  "message": "Hello from Acme"
}'

Run it here with a test key.

Get the delivery status and timeline of a sent SMS

GET/api/v1/comms/sms/{messageId}

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

Returns the message's current status and its timeline: queued (charged), sent (the route accepted the hand-off), then delivered or failed, each with a timestamp, and an errorCode on failure.

Where delivered comes from. Only from a carrier delivery receipt. Receipts come back on SMPP routes whose supplier returns them, and on HTTP routes whose seller posts them back to us. A route that returns none leaves its messages at sent with awaitingReceipt: true; routeReturnsReceipts tells you whether the route has returned any in the last 30 days, so you know whether to wait. A receipt that reports the message undelivered, expired or rejected marks it failed and refunds it.

Covers messages sent with POST /comms/sms and POST /comms/sms/bulk. An unknown id answers 200 with status not_found rather than 404.

Parameters

Name	In	Type	Description
`messageId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`messageId`requireddata.messageId	string	-
`status`requireddata.status	string	Current state: sent, accepted (test key), delivered or failed; not_found when the id is not on your account. delivered only ever comes from a carrier receipt
`to`data.to	string \| null	-
`from`data.from	string \| null	-
`segments`data.segments	integer \| null	-
`errorCode`data.errorCode	string \| null	Set when status is failed: SELLER_REJECTED (the route refused the hand-off), NO_ENDPOINT, UNDELIVERABLE, EXPIRED or REJECTED (from the carrier receipt)
`timeline`data.timeline	object[]	Every state the message has been in, oldest first
`status`requireddata.timeline[].status	string	queued = charged and waiting to be handed off; sent = the route accepted it; accepted = simulated on a test key; delivered / failed = finalOne of `queued`, `sent`, `accepted`, `delivered`, `failed`
`at`requireddata.timeline[].at	string (date-time)	ISO-8601 timestamp (UTC)
`source`requireddata.timeline[].source	string	Where we learned it: our ledger, the hand-off to the route, the carrier's delivery receipt, or a test-key simulationOne of `platform`, `submit`, `carrier_receipt`, `simulated`
`errorCode`data.timeline[].errorCode	string \| null	On failed: SELLER_REJECTED, NO_ENDPOINT, UNDELIVERABLE, EXPIRED or REJECTED
`carrierStatus`data.timeline[].carrierStatus	string \| null	The carrier receipt's own status value, e.g. DELIVRD or UNDELIV
`carrierError`data.timeline[].carrierError	string \| null	The carrier receipt's own error value, when it sent one
`awaitingReceipt`data.awaitingReceipt	boolean	True while the message is sent and no carrier receipt has arrived. It stays true for good on a route that returns no receipts
`routeReturnsReceipts`data.routeReturnsReceipts	boolean \| null	Whether the route that carried this message has returned at least one carrier receipt in the last 30 days. null for test-key messages
`dlrSupported`data.dlrSupported	boolean	True: the platform collects carrier delivery receipts. Whether one arrives for this message depends on the route (routeReturnsReceipts)
`simulated`data.simulated	boolean	Present and true for test-key messages: nothing was sent
`cost`data.cost	money	The ledger amount of the charge (negative) USD as a decimal string with exactly 6 places, e.g. "0.012500".
`reference`data.reference	string \| null	-
`sentAt`data.sentAt	string (date-time)	When the message was charged
`message`data.message	string	Explanation, present when status is not_found

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 up to 1,000 SMS in one request

POST/api/v1/comms/sms/bulk

Access: API key. Scoped keys need sms:send.
Rate limit: 100 requests per second (the default)
Real traffic: Places a real call or sends a real message, billed to your balance. A test key simulates it against test credit.

Sends each message in order over one route and returns a result per recipient. Each message is billed exactly as POST /comms/sms bills it: a reseller sub-account API key pays the sub-account's retail rate, a test key simulates. Stops at the first insufficient-balance refusal (account or sub-account) and marks the rest skipped. Not idempotent: retrying resends every message.

Request body (application/json)

Field	Type	Description
`routeId`required	string (uuid)	The purchased SMS route every message is sent over
`from`required	string	Sender ID for every messagemax 30 chars
`messages`required	object[]	-
`to`requiredmessages[].to	string	-max 30 chars
`message`requiredmessages[].message	string	-max 1600 chars

Response 200

Field	Type	Description
`data`required	object	-
`total`requireddata.total	integer	-
`sent`requireddata.sent	integer	-
`failed`requireddata.failed	integer	Failed plus skipped
`totalCost`requireddata.totalCost	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`results`requireddata.results	object[]	-
`to`requireddata.results[].to	string	-
`status`requireddata.results[].status	string	The send status, or failed / skipped
`messageId`data.results[].messageId	string	-
`from`data.results[].from	string	-
`segments`data.results[].segments	integer	-
`cost`data.results[].cost	money	US dollars as a decimal string with exactly 6 decimal places, e.g. "0.012500". Do money arithmetic with a decimal type, not floating point. USD as a decimal string with exactly 6 places, e.g. "0.012500".
`submittedAt`data.results[].submittedAt	string (date-time)	ISO-8601 timestamp (UTC)
`error`data.results[].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/comms/sms/bulk" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "routeId": "<routeId>",
  "from": "+447700900123",
  "messages": [
    {
      "to": "+447700900123",
      "message": "Hello from Acme"
    }
  ]
}'

Run it here with a test key.