API reference

Onboarding

The guided first-call flow for new accounts.

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

Get everything the first-call guide needs

GET/api/v1/first-call/state

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

Balance, verification, active purchases (with where to send traffic and the billing increment), the five most recent calls and the account connectivity brief. If the brief cannot be read, brief is null and briefError says why; no fallback address is ever guessed.

Response 200

Field	Type	Description
`data`required	object	-
`balance`requireddata.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`balanceNumeric`requireddata.balanceNumeric	number	-
`emailVerified`requireddata.emailVerified	boolean	-
`accountStatus`requireddata.accountStatus	string \| null	-
`activePurchases`requireddata.activePurchases	object[]	-
`purchaseId`requireddata.activePurchases[].purchaseId	string (uuid)	-
`routeId`requireddata.activePurchases[].routeId	string (uuid)	-
`routeName`requireddata.activePurchases[].routeName	string \| null	The listing name as a buyer reads it: generated by the platform, never the seller's text, and ending in the listing reference (e.g. "Niger Mobile · Ref 7K2Q", "A-Z Voice · Premium · Full CLI · Ref 3MX9"). Your own listings keep the name you gave them.
`countryCode`requireddata.activePurchases[].countryCode	string \| null	-
`prefixes`requireddata.activePurchases[].prefixes	string \| null	Comma-joined prefixes
`type`requireddata.activePurchases[].type	string	-
`status`requireddata.activePurchases[].status	string	-
`billingIncrement`requireddata.activePurchases[].billingIncrement	string \| null	e.g. "60/60"
`sipUsername`requireddata.activePurchases[].sipUsername	string \| null	-
`hasSipPassword`requireddata.activePurchases[].hasSipPassword	boolean	-
`sendTo`requireddata.activePurchases[].sendTo	string \| null	Our address to send this traffic to, from the live brief
`sendToPort`requireddata.activePurchases[].sendToPort	integer \| null	-
`recentCalls`requireddata.recentCalls	object[]	-
`id`requireddata.recentCalls[].id	string (uuid)	-
`createdAt`requireddata.recentCalls[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`direction`requireddata.recentCalls[].direction	string	-
`kind`requireddata.recentCalls[].kind	string	-
`toNumber`requireddata.recentCalls[].toNumber	string \| null	-
`fromNumber`requireddata.recentCalls[].fromNumber	string \| null	-
`status`requireddata.recentCalls[].status	string \| null	-
`sipCode`requireddata.recentCalls[].sipCode	integer \| null	-
`hangupCause`requireddata.recentCalls[].hangupCause	string \| null	-
`durationSeconds`requireddata.recentCalls[].durationSeconds	integer \| null	-
`billedSeconds`requireddata.recentCalls[].billedSeconds	integer \| null	Seconds the charge was computed from, after increment rounding
`buyerCost`requireddata.recentCalls[].buyerCost	money \| null	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".
`ratePerUnit`requireddata.recentCalls[].ratePerUnit	money \| null	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".
`isTest`requireddata.recentCalls[].isTest	boolean	-
`hasAnyCall`requireddata.hasAnyCall	boolean	-
`brief`requireddata.brief	object \| null	The account connectivity brief: authorised source addresses, purchased routes and where to send them
`briefError`requireddata.briefError	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.

Check first-call progress

GET/api/v1/first-call/status

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

Three cheap yes/no checks for a progress badge: any call made, any active purchase, a positive balance.

Response 200

Field	Type	Description
`data`required	object	-
`hasAnyCall`requireddata.hasAnyCall	boolean	-
`hasActivePurchase`requireddata.hasActivePurchase	boolean	-
`hasBalance`requireddata.hasBalance	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.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Activate your own switch address

POST/api/v1/first-call/switch-address

Access: API key. Scoped keys need account:write.
Rate limit: 10 requests per minute

Moves the account onto its own ingress address. Call without confirm to preview what changes; send confirm: true to apply.

Request body (application/json)

Field	Type	Description
`confirm`	boolean	-

Response 200

Field	Type	Description
`data`required	object	What was (or would be) changed

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/first-call/switch-address" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm": true
}'

Run it here with a test key.

Check whether a call to a destination would be accepted

POST/api/v1/first-call/readiness

Access: API key. Scoped keys need account:read.
Rate limit: 20 requests per minute

Dry-runs inbound admission for a destination against each way your traffic can be recognised (source address or SIP credentials). Places no call and moves no money. When refused, rejection explains why and whose move it is.

Request body (application/json)

Field	Type	Description
`destination`required	string	Destination number in international formatmax 24 chars

Response 200

Field	Type	Description
`data`required	object	-
`checkable`requireddata.checkable	boolean	-
`accepted`requireddata.accepted	boolean	-
`identityChecked`requireddata.identityChecked	string \| null	-
`identitiesTried`requireddata.identitiesTried	string[]	-
`rejection`requireddata.rejection	object \| null	-
`code`requireddata.rejection.code	integer	Stable PacketExchange cause code (not the SIP code)
`blockedBy`requireddata.rejection.blockedBy	string	Whose move it is to unblock the call
`reason`requireddata.rejection.reason	string	-
`remedy`requireddata.rejection.remedy	string	-
`sipCode`requireddata.rejection.sipCode	integer	-
`note`requireddata.note	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.
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/first-call/readiness" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "destination": "+447700900123"
}'

Run it here with a test key.