API reference

Purchases

Buy access to marketplace routes and manage what you bought.

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

BrowsePurchases

List your route purchases

GET/api/v1/purchases

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

Parameters

Name	In	Type	Description
`status`	query	string	-One of active, paused, cancelled
`cursor`	query	string (uuid)	-
`limit`	query	integer	-Default 25

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`buyerId`requireddata[].buyerId	string (uuid)	Your account id
`routeId`requireddata[].routeId	string (uuid)	-
`status`requireddata[].status	string	-One of `active`, `paused`, `cancelled`, `pending_review`
`sipUsername`requireddata[].sipUsername	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`cancelledAt`requireddata[].cancelledAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`agreedPrice`requireddata[].agreedPrice	money \| null	Negotiated price (from an accepted offer) that overrides the list price USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldOldRate`requireddata[].heldOldRate	money \| null	Set while the purchase is paused by a seller rate increase: the rate you were paying USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldNewRate`requireddata[].heldNewRate	money \| null	The increased rate waiting for your acceptance USD as a decimal string with exactly 6 places, e.g. "0.012500".
`routingPriority`requireddata[].routingPriority	integer \| null	Your routing position (1 = first); null = unranked
`sipPassword`requireddata[].sipPassword	string \| null	Your own SIP password, for your connection card
`heldDeckVersion`requireddata[].heldDeckVersion	string \| null	Deck fingerprint to pass as deckVersion when accepting a deck increase
`route`requireddata[].route	object	-
`type`requireddata[].route.type	string	-One of `voice`, `sms`
`country`requireddata[].route.country	string	-
`prefix`requireddata[].route.prefix	string[]	-
`countryCode`requireddata[].route.countryCode	string	-
`destinationName`requireddata[].route.destinationName	string	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.
`pricePerUnit`requireddata[].route.pricePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata[].route.billingIncrement	string \| null	-
`jingleSipIp`requireddata[].route.jingleSipIp	enum \| null	Always null: the seller endpoint is never disclosedOne of `null`
`capacity`requireddata[].route.capacity	integer	-
`expectedAsr`requireddata[].route.expectedAsr	string \| null	-
`expectedAcd`requireddata[].route.expectedAcd	string \| null	-
`dialerCompatible`requireddata[].route.dialerCompatible	boolean	-
`rateCount`requireddata[].route.rateCount	integer	-
`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.

Buy access to a marketplace route

POST/api/v1/purchases

Access: API key. Scoped keys need purchases:write.
Rate limit: 100 requests per second (the default)
Moves money: Buys access to a marketplace route.

No upfront cost: usage is billed per minute or message from your balance. Requires a LIVE API key: a test key is refused with 400.

Request body (application/json)

Field	Type	Description
`routeId`required	string (uuid)	-

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`buyerId`requireddata.buyerId	string (uuid)	Your account id
`routeId`requireddata.routeId	string (uuid)	-
`status`requireddata.status	string	-One of `active`, `paused`, `cancelled`, `pending_review`
`sipUsername`requireddata.sipUsername	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`cancelledAt`requireddata.cancelledAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`agreedPrice`requireddata.agreedPrice	money \| null	Negotiated price (from an accepted offer) that overrides the list price USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldOldRate`requireddata.heldOldRate	money \| null	Set while the purchase is paused by a seller rate increase: the rate you were paying USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldNewRate`requireddata.heldNewRate	money \| null	The increased rate waiting for your acceptance USD as a decimal string with exactly 6 places, e.g. "0.012500".
`routingPriority`requireddata.routingPriority	integer \| null	Your routing position (1 = first); null = unranked
`requiresUsCompliance`requireddata.requiresUsCompliance	boolean	A US voice route that needs STIR/SHAKEN review before traffic flows
`reviewedAt`requireddata.reviewedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`reviewNote`requireddata.reviewNote	string \| null	The compliance reviewer's note to you, if any
`sipPasswordSet`requireddata.sipPasswordSet	boolean	Whether a SIP password exists. The value is not returned here: it is shown once at purchase, on your purchased-routes list and on Interconnections.
`smppSystemId`requireddata.smppSystemId	string \| null	-
`offerId`requireddata.offerId	string (uuid) \| null	The accepted offer that set agreedPrice
`route`requireddata.route	object \| null	-
`id`requireddata.route.id	string (uuid)	-
`type`requireddata.route.type	string	-One of `voice`, `sms`
`country`requireddata.route.country	string	-
`destinationName`requireddata.route.destinationName	string	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.
`listingRef`requireddata.route.listingRef	string	Anonymous short reference of the listing (4 characters, e.g. "7K2Q"): stable for the life of the listing, unique enough to tell two same-named listings apart, and derived from the listing alone (it says nothing about the seller). Absent on your own listings.
`pricePerUnit`requireddata.route.pricePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.route.billingIncrement	string \| null	-
`jingleSipIp`requireddata.route.jingleSipIp	enum \| null	-One of `null`
`sipPublicIp`requireddata.sipPublicIp	string	Where to send your SIP traffic
`sipPassword`requireddata.sipPassword	string \| null	Plaintext SIP password, returned once here
`pendingCompliance`requireddata.pendingCompliance	boolean	True when US STIR/SHAKEN compliance review must finish before traffic flows

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/purchases" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "routeId": "<routeId>"
}'

Run it here with a test key.

Get your voice routing order

GET/api/v1/purchases/routing-order

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

Your SIP credentials and whitelisted IPs identify your ACCOUNT, not a route, so every active voice purchase can carry any call it covers. When several cover a number equally well (same prefix length), your routing order decides, then the cheaper rate, then the older purchase. This lists every voice purchase that can hold a position (active, paused or pending review): ranked ones first by position, then unranked ones oldest first. Destination names are cleaned of seller details. rateSheet routes are priced by an A-Z deck, so they can overlap any destination.

Response 200

Field	Type	Description
`data`required	object[]	-
`purchaseId`requireddata[].purchaseId	string (uuid)	-
`routeId`requireddata[].routeId	string (uuid)	-
`status`requireddata[].status	string	-One of `active`, `paused`, `cancelled`, `pending_review`
`routingPriority`requireddata[].routingPriority	integer \| null	Your position (1 = first); null = unranked
`createdAt`requireddata[].createdAt	string (date-time)	When you bought it (the tie-break among unranked routes)
`destinationName`requireddata[].destinationName	string	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.
`country`requireddata[].country	string	-
`countryCode`requireddata[].countryCode	string	-
`prefix`requireddata[].prefix	string[]	-
`rateSheet`requireddata[].rateSheet	boolean	Priced by an A-Z rate sheet, so it can overlap any destination

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.

Replace your voice routing order

PUT/api/v1/purchases/routing-order

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

purchaseIds[0] becomes position 1, the next 2, and so on; every other voice purchase of yours is cleared to unranked. Atomic: a reorder never leaves two routes half-swapped. An empty list clears the whole order (back to cheapest, then oldest). A repeated id is 400 VALIDATION_ERROR; an id that is not one of your rankable voice purchases is 404 and nothing changes.

Request body (application/json)

Field	Type	Description
`purchaseIds`required	string (uuid)[]	Your voice purchases in the order to try them; an empty list clears the order

Response 200

Field	Type	Description
`data`required	object	-
`order`requireddata.order	object[]	-
`purchaseId`requireddata.order[].purchaseId	string (uuid)	-
`routingPriority`requireddata.order[].routingPriority	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.
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/purchases/routing-order" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "purchaseIds": [
    "<purchaseId>"
  ]
}'

Run it here with a test key.

See your first-choice and backup routes per destination

GET/api/v1/purchases/failover

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

For each prefix your active voice routes list: the route tried first and the backups behind it, in the order a call would use them. When automatic failover is on (enabled: true), a call that a route refuses before it is answered (for example SIP 403, 480, 5xx or no response) is tried straight away on the next route, up to maxAttempts routes, and only the route that connects is billed. A wrong number, a busy or declined call and an unanswered call are never retried. Over a SIP trunk only server errors and congestion (5xx) move a call on; apiOnly marks backups SIP trunk calls never use. singleRoute: true marks a destination with no backup. A-Z rate sheets are listed separately because they have no single prefix. Names are cleaned of seller details. Read-only.

Response 200

Field	Type	Description
`data`required	object	-
`enabled`requireddata.enabled	boolean	Whether automatic failover is switched on
`maxAttempts`requireddata.maxAttempts	integer	The most routes tried for one call, the first included
`destinations`requireddata.destinations	object[]	-
`prefix`requireddata.destinations[].prefix	string	"+" and the listed prefix
`country`requireddata.destinations[].country	string	-
`routes`requireddata.destinations[].routes	object[]	-
`purchaseId`requireddata.destinations[].routes[].purchaseId	string (uuid)	-
`routeId`requireddata.destinations[].routes[].routeId	string (uuid)	-
`destinationName`requireddata.destinations[].routes[].destinationName	string	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.
`position`requireddata.destinations[].routes[].position	integer	1 is tried first
`role`requireddata.destinations[].routes[].role	string	not_tried: beyond maxAttempts, so never reached by one callOne of `first`, `backup`, `not_tried`
`apiOnly`requireddata.destinations[].routes[].apiOnly	boolean	true for a backup that calls over your SIP trunk never use (it needs SIP credentials, call screening or a reshaped number, or the first choice does); Voice API calls still fail over to it
`singleRoute`requireddata.destinations[].singleRoute	boolean	True when only one of your routes covers this prefix: no backup
`rateSheets`requireddata.rateSheets	object[]	-
`purchaseId`requireddata.rateSheets[].purchaseId	string (uuid)	-
`routeId`requireddata.rateSheets[].routeId	string (uuid)	-
`destinationName`requireddata.rateSheets[].destinationName	string	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.

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.

See which of your routes would carry a number

GET/api/v1/purchases/route-for

Access: API key. Scoped keys need routes:read.
Rate limit: 60 requests per minute

Runs the same ranking the live SIP path uses, for your account and with the same number normalisation, so the answer is what a real call would do. Lists every route of yours that covers the number, in order, with the step of the rule that put each one behind the one above. Also reports the two refusals that sit in front of routing: an embargoed destination and an empty balance; when refused is set, no route carries the call. Read-only.

Parameters

Name	In	Type	Description
`to`required	query	string	The number to check, international format

Response 200

Field	Type	Description
`data`required	object	-
`number`requireddata.number	string	The number as checked, "+" and digits
`carriedBy`requireddata.carriedBy	object \| null	The route that would carry it (candidates[0]); null when none covers it
`position`requireddata.carriedBy.position	integer	1 = the route that would carry the call
`carries`requireddata.carriedBy.carries	boolean	-
`purchaseId`requireddata.carriedBy.purchaseId	string (uuid) \| null	null for one of your own listings
`routeId`requireddata.carriedBy.routeId	string (uuid)	-
`ownRoute`requireddata.carriedBy.ownRoute	boolean	True when this is a route you sell yourself
`destinationName`requireddata.carriedBy.destinationName	string	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.
`country`requireddata.carriedBy.country	string	-
`matchedPrefix`requireddata.carriedBy.matchedPrefix	string \| null	-
`matchedDigits`requireddata.carriedBy.matchedDigits	integer	Length of the matching prefix
`routingPriority`requireddata.carriedBy.routingPriority	integer \| null	-
`rate`requireddata.carriedBy.rate	money \| null	What you are billed per minute for this number on this route USD as a decimal string with exactly 6 places, e.g. "0.012500".
`rateSheet`requireddata.carriedBy.rateSheet	boolean	The route is priced by an A-Z rate sheet
`purchasedAt`requireddata.carriedBy.purchasedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`behindBecause`requireddata.carriedBy.behindBecause	string \| null	For every route after the first: why the route above it winsOne of `prefix`, `routing_order`, `rate`, `age`, `route_id`
`reason`requireddata.reason	string	Why that route wins, in words
`decidedBy`requireddata.decidedBy	string \| null	The step that decided between the first two routes; null with fewer than twoOne of `prefix`, `routing_order`, `rate`, `age`, `route_id`
`candidates`requireddata.candidates	object[]	Same fields as RouteForCandidate, shown earlier on this page.
`refused`requireddata.refused	object \| null	-
`reason`requireddata.refused.reason	string	-One of `embargoed`, `no_balance`
`message`requireddata.refused.message	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.

Set a purchase's routing position

PATCH/api/v1/purchases/{id}/routing-priority

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

Sets (priority: n) or clears (priority: null) one voice purchase's position in your routing order; 1 is tried first. Positions do not have to be contiguous, and two purchases may share one (then rate, then age decides). Voice purchases only, and not a cancelled one (400 VALIDATION_ERROR). To reorder several at once use PUT /purchases/routing-order.

Parameters

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

Request body (application/json)

Field	Type	Description
`priority`required	integer \| null	1 = tried first; null clears the position1 to 9999

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`routingPriority`requireddata.routingPriority	integer \| 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.
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/purchases/<id>/routing-priority" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "priority": 1
}'

Run it here with a test key.

Clear a purchase's routing position

DELETE/api/v1/purchases/{id}/routing-priority

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

The purchase goes back to unranked: after every ranked route, cheapest then oldest.

Parameters

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

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`routingPriority`requireddata.routingPriority	integer \| 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.
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 purchase

GET/api/v1/purchases/{id}

Access: API key. Full-access keys only; not reachable by scoped keys.
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)	-
`buyerId`requireddata.buyerId	string (uuid)	Your account id
`routeId`requireddata.routeId	string (uuid)	-
`status`requireddata.status	string	-One of `active`, `paused`, `cancelled`, `pending_review`
`sipUsername`requireddata.sipUsername	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`cancelledAt`requireddata.cancelledAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`agreedPrice`requireddata.agreedPrice	money \| null	Negotiated price (from an accepted offer) that overrides the list price USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldOldRate`requireddata.heldOldRate	money \| null	Set while the purchase is paused by a seller rate increase: the rate you were paying USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldNewRate`requireddata.heldNewRate	money \| null	The increased rate waiting for your acceptance USD as a decimal string with exactly 6 places, e.g. "0.012500".
`routingPriority`requireddata.routingPriority	integer \| null	Your routing position (1 = first); null = unranked
`requiresUsCompliance`requireddata.requiresUsCompliance	boolean	A US voice route that needs STIR/SHAKEN review before traffic flows
`reviewedAt`requireddata.reviewedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`reviewNote`requireddata.reviewNote	string \| null	The compliance reviewer's note to you, if any
`sipPasswordSet`requireddata.sipPasswordSet	boolean	Whether a SIP password exists. The value is not returned here: it is shown once at purchase, on your purchased-routes list and on Interconnections.
`smppSystemId`requireddata.smppSystemId	string \| null	-
`offerId`requireddata.offerId	string (uuid) \| null	The accepted offer that set agreedPrice
`route`requireddata.route	object \| null	-
`id`requireddata.route.id	string (uuid)	-
`type`requireddata.route.type	string	-One of `voice`, `sms`
`country`requireddata.route.country	string	-
`destinationName`requireddata.route.destinationName	string	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.
`listingRef`requireddata.route.listingRef	string	Anonymous short reference of the listing (4 characters, e.g. "7K2Q"): stable for the life of the listing, unique enough to tell two same-named listings apart, and derived from the listing alone (it says nothing about the seller). Absent on your own listings.
`pricePerUnit`requireddata.route.pricePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.route.billingIncrement	string \| null	-
`jingleSipIp`requireddata.route.jingleSipIp	enum \| null	-One of `null`
`sipPublicIp`requireddata.sipPublicIp	string	Where to send your SIP traffic

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.

Pause or resume a purchase

PATCH/api/v1/purchases/{id}

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`status`required	string	-One of `active`, `paused`

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`buyerId`requireddata.buyerId	string (uuid)	Your account id
`routeId`requireddata.routeId	string (uuid)	-
`status`requireddata.status	string	-One of `active`, `paused`, `cancelled`, `pending_review`
`sipUsername`requireddata.sipUsername	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`cancelledAt`requireddata.cancelledAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`agreedPrice`requireddata.agreedPrice	money \| null	Negotiated price (from an accepted offer) that overrides the list price USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldOldRate`requireddata.heldOldRate	money \| null	Set while the purchase is paused by a seller rate increase: the rate you were paying USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldNewRate`requireddata.heldNewRate	money \| null	The increased rate waiting for your acceptance USD as a decimal string with exactly 6 places, e.g. "0.012500".
`routingPriority`requireddata.routingPriority	integer \| null	Your routing position (1 = first); null = unranked
`requiresUsCompliance`requireddata.requiresUsCompliance	boolean	A US voice route that needs STIR/SHAKEN review before traffic flows
`reviewedAt`requireddata.reviewedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`reviewNote`requireddata.reviewNote	string \| null	The compliance reviewer's note to you, if any
`sipPasswordSet`requireddata.sipPasswordSet	boolean	Whether a SIP password exists. The value is not returned here: it is shown once at purchase, on your purchased-routes list and on Interconnections.
`smppSystemId`requireddata.smppSystemId	string \| null	-
`offerId`requireddata.offerId	string (uuid) \| null	The accepted offer that set agreedPrice

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/purchases/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'

Run it here with a test key.

Cancel a purchase

DELETE/api/v1/purchases/{id}

Access: API key. Full-access keys only; not reachable by scoped keys.
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 PurchaseRow, 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 call counts, ASR and spend for a purchase

GET/api/v1/purchases/{id}/usage

Access: API key. Full-access keys only; not reachable by scoped keys.
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	-
`calls24h`requireddata.calls24h	integer	-
`calls7d`requireddata.calls7d	integer	-
`calls30d`requireddata.calls30d	integer	-
`totalCalls`requireddata.totalCalls	integer	-
`lastActivityAt`requireddata.lastActivityAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`spend30d`data.spend30d	money	Absent when nothing was spent USD as a decimal string with exactly 6 places, e.g. "0.012500".
`measuredAsr`data.measuredAsr	number	-
`measuredAsrSessions`data.measuredAsrSessions	integer	-
`measuredAsrPopulation`data.measuredAsrPopulation	string	-
`measuredAsrWindow`data.measuredAsrWindow	string	-
`measuredAcd`data.measuredAcd	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.

Accept a seller's rate increase

POST/api/v1/purchases/{id}/accept-rate

Access: API key. Scoped keys need purchases:write.
Rate limit: 100 requests per second (the default)
Moves money: Accepts a higher rate on a route you buy.

A purchase paused by a price rise resumes at the new rate. Pass the rate (or deck version) you reviewed so a further change is not accepted by mistake.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`acceptedRate`	string \| number	The new rate you are agreeing to, as shown to you (guards against a further change in between)
`deckVersion`	string	For A-Z decks: the heldDeckVersion you reviewed
`changeId`	string (uuid)	Accept a SCHEDULED change in advance (id from upcoming-rate-changes). Nothing resumes or bills now.

Response 200

Field	Type	Description
`data`required	object	-
`id`data.id	string (uuid)	-
`buyerId`data.buyerId	string (uuid)	Your account id
`routeId`data.routeId	string (uuid)	-
`status`data.status	string	-One of `active`, `paused`, `cancelled`, `pending_review`
`sipUsername`data.sipUsername	string \| null	-
`createdAt`data.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`cancelledAt`data.cancelledAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`agreedPrice`data.agreedPrice	money \| null	Negotiated price (from an accepted offer) that overrides the list price USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldOldRate`data.heldOldRate	money \| null	Set while the purchase is paused by a seller rate increase: the rate you were paying USD as a decimal string with exactly 6 places, e.g. "0.012500".
`heldNewRate`data.heldNewRate	money \| null	The increased rate waiting for your acceptance USD as a decimal string with exactly 6 places, e.g. "0.012500".
`routingPriority`data.routingPriority	integer \| null	Your routing position (1 = first); null = unranked
`requiresUsCompliance`data.requiresUsCompliance	boolean	A US voice route that needs STIR/SHAKEN review before traffic flows
`reviewedAt`data.reviewedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`reviewNote`data.reviewNote	string \| null	The compliance reviewer's note to you, if any
`sipPasswordSet`data.sipPasswordSet	boolean	Whether a SIP password exists. The value is not returned here: it is shown once at purchase, on your purchased-routes list and on Interconnections.
`smppSystemId`data.smppSystemId	string \| null	-
`offerId`data.offerId	string (uuid) \| null	The accepted offer that set agreedPrice
`accepted`data.accepted	boolean	-One of `true`
`changeId`data.changeId	string (uuid)	-
`purchaseId`data.purchaseId	string (uuid)	-
`effectiveDate`data.effectiveDate	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.
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/purchases/<id>/accept-rate" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "acceptedRate": "<acceptedRate>",
  "deckVersion": "<deckVersion>"
}'

Run it here with a test key.

List scheduled rate changes on a route you bought

GET/api/v1/purchases/{id}/upcoming-rate-changes

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

Rate changes the seller has scheduled on a route you bought and that are not yet in effect, soonest first: the effective date, the old and new rate per destination (biggest increases first, at most 200 rows per change; totalRows is the full count), and whether you have already accepted each one. For a per-country listing of an A-Z deck, only that listing's destinations are shown. Accept a change in advance with POST /purchases/{id}/accept-rate and changeId: at the effective date an accepted purchase keeps running instead of being paused for re-consent. affectsYou is false when you do not pay the list rate (an accepted offer or a private price), so a change will not pause you. Destination names are cleaned of seller details.

Parameters

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

Response 200

Field	Type	Description
`data`required	object	-
`purchaseId`requireddata.purchaseId	string (uuid)	-
`affectsYou`requireddata.affectsYou	boolean	True when you pay the list rate, so this change would pause you until accepted
`changes`requireddata.changes	object[]	-
`changeId`requireddata.changes[].changeId	string (uuid)	Pass as changeId to POST /purchases/{id}/accept-rate
`kind`requireddata.changes[].kind	string	flat = the route's single price changes; deck = rate-sheet rows changeOne of `flat`, `deck`
`effectiveDate`requireddata.changes[].effectiveDate	string (date-time)	ISO-8601 timestamp (UTC)
`increases`requireddata.changes[].increases	integer	-
`decreases`requireddata.changes[].decreases	integer	-
`added`requireddata.changes[].added	integer	-
`removed`requireddata.changes[].removed	integer	-
`largestIncreasePct`requireddata.changes[].largestIncreasePct	number \| null	-
`accepted`requireddata.changes[].accepted	boolean	-
`acceptedAt`requireddata.changes[].acceptedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`rows`requireddata.changes[].rows	object[]	-
`destination`requireddata.changes[].rows[].destination	string \| null	-
`prefix`requireddata.changes[].rows[].prefix	string \| null	-
`oldRate`requireddata.changes[].rows[].oldRate	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".
`newRate`requireddata.changes[].rows[].newRate	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".
`oldIncrement`requireddata.changes[].rows[].oldIncrement	string \| null	-
`newIncrement`requireddata.changes[].rows[].newIncrement	string \| null	-
`deltaPct`requireddata.changes[].rows[].deltaPct	number \| null	-
`removed`requireddata.changes[].rows[].removed	boolean	-
`totalRows`requireddata.changes[].totalRows	integer	Rows in the change for this listing (rows is capped at 200)

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.