API reference

Rate sheets

Upload and manage per-prefix rate decks on routes you sell.

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

BrowseRate sheets

List rate-sheet imports for a route

GET/api/v1/routes/{id}/rate-sheets

Access: API key. Scoped keys need routes: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)	-
`routeId`requireddata[].routeId	string (uuid)	-
`filename`requireddata[].filename	string	-
`fileType`requireddata[].fileType	string	-
`status`requireddata[].status	string	-
`rowCount`requireddata[].rowCount	integer \| null	-
`columnMapping`data[].columnMapping	any	-
`previewRows`data[].previewRows	any	-
`warnings`data[].warnings	any	-
`currency`requireddata[].currency	string \| null	-
`fxRate`requireddata[].fxRate	string \| null	-
`errorMessage`requireddata[].errorMessage	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`appliedAt`requireddata[].appliedAt	string (date-time) \| null	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 rate sheet to a route

POST/api/v1/routes/{id}/rate-sheets

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

Multipart upload (field file, CSV or Excel). Creates an import to preview, diff and apply; nothing is priced until you apply it.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (multipart/form-data)

Field	Type	Description
`file`required	string	CSV or Excel rate sheet (binary)

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`routeId`requireddata.routeId	string (uuid)	-
`filename`requireddata.filename	string	-
`fileType`requireddata.fileType	string	-
`status`requireddata.status	string	-
`rowCount`requireddata.rowCount	integer \| null	-
`columnMapping`data.columnMapping	any	-
`previewRows`data.previewRows	any	-
`warnings`data.warnings	any	-
`currency`requireddata.currency	string \| null	-
`fxRate`requireddata.fxRate	string \| null	-
`errorMessage`requireddata.errorMessage	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`appliedAt`requireddata.appliedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`rawSample`data.rawSample	any	-
`summary`data.summary	any	-
`confidence`data.confidence	any	-

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/routes/<id>/rate-sheets" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -F "file=@rates.csv"

Run it here with a test key.

Upload and apply a rate sheet in one step

POST/api/v1/routes/{id}/rate-sheets/quick

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

Applies straight away when the sheet reads unambiguously; otherwise returns outcome: "review" with the reasons.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (multipart/form-data)

Field	Type	Description
`file`required	string	CSV or Excel rate sheet (binary)

Response 200

Field	Type	Description
`data`required	object	-
`outcome`requireddata.outcome	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/routes/<id>/rate-sheets/quick" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -F "file=@rates.csv"

Run it here with a test key.

Get a rate-sheet import

GET/api/v1/routes/{id}/rate-sheets/{importId}

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

Parameters

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

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`routeId`requireddata.routeId	string (uuid)	-
`filename`requireddata.filename	string	-
`fileType`requireddata.fileType	string	-
`status`requireddata.status	string	-
`rowCount`requireddata.rowCount	integer \| null	-
`columnMapping`data.columnMapping	any	-
`previewRows`data.previewRows	any	-
`warnings`data.warnings	any	-
`currency`requireddata.currency	string \| null	-
`fxRate`requireddata.fxRate	string \| null	-
`errorMessage`requireddata.errorMessage	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`appliedAt`requireddata.appliedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`rawSample`data.rawSample	any	-

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.

Preview a rate-sheet import

POST/api/v1/routes/{id}/rate-sheets/{importId}/preview

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

Parameters

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

Request body (application/json)

Field	Type	Description
`fxRate`	number	Multiply source rates by this to convert to USDmin 0
`mapping`	any	Column mapping override
`overrides`	object	-
`defaultIncrement`	string \| null	-
`increaseEffectiveAt`	string \| string (date-time) \| null	When the sheet's increases take effect: "now", an ISO instant, or omitted for the default notice period (diff and apply only)

Response 200

Field	Type	Description
`data`required	object	Parsed rows as they would be priced

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/routes/<id>/rate-sheets/<importId>/preview" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fxRate": 1,
  "mapping": "<mapping>"
}'

Run it here with a test key.

Compare a rate-sheet import with the live deck

POST/api/v1/routes/{id}/rate-sheets/{importId}/diff

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

Parameters

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

Request body (application/json)

Field	Type	Description
`fxRate`	number	Multiply source rates by this to convert to USDmin 0
`mapping`	any	Column mapping override
`overrides`	object	-
`defaultIncrement`	string \| null	-
`increaseEffectiveAt`	string \| string (date-time) \| null	When the sheet's increases take effect: "now", an ISO instant, or omitted for the default notice period (diff and apply only)

Response 200

Field	Type	Description
`data`required	object	Added, changed and removed rows

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/routes/<id>/rate-sheets/<importId>/diff" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fxRate": 1,
  "mapping": "<mapping>"
}'

Run it here with a test key.

Apply a rate-sheet import

POST/api/v1/routes/{id}/rate-sheets/{importId}/apply

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

Rate increases put list-rate buyers on hold until they accept the new rate.

Parameters

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

Request body (application/json)

Field	Type	Description
`fxRate`	number	Multiply source rates by this to convert to USDmin 0
`mapping`	any	Column mapping override
`overrides`	object	-
`defaultIncrement`	string \| null	-
`increaseEffectiveAt`	string \| string (date-time) \| null	When the sheet's increases take effect: "now", an ISO instant, or omitted for the default notice period (diff and apply only)

Response 200

Field	Type	Description
`data`required	object	-
`applied`requireddata.applied	integer	-
`added`requireddata.added	integer	-
`changed`requireddata.changed	integer	-
`removed`requireddata.removed	integer	-
`droppedBlocked`requireddata.droppedBlocked	integer	-
`diff`data.diff	any	-

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/routes/<id>/rate-sheets/<importId>/apply" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fxRate": 1,
  "mapping": "<mapping>"
}'

Run it here with a test key.

Roll a route back to an earlier rate-sheet import

POST/api/v1/routes/{id}/rate-sheets/{importId}/rollback

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

Parameters

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

Response 200

Field	Type	Description
`data`required	object	-
`applied`requireddata.applied	integer	-
`added`requireddata.added	integer	-
`changed`requireddata.changed	integer	-
`removed`requireddata.removed	integer	-
`droppedBlocked`requireddata.droppedBlocked	integer	-
`diff`data.diff	any	-

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/routes/<id>/rate-sheets/<importId>/rollback" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Reapply a rate-sheet import with new settings

POST/api/v1/routes/{id}/rate-sheets/{importId}/reapply

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

Parameters

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

Request body (application/json)

Field	Type	Description
`fxRate`	number	Multiply source rates by this to convert to USDmin 0
`mapping`	any	Column mapping override
`overrides`	object	-
`defaultIncrement`	string \| null	-
`increaseEffectiveAt`	string \| string (date-time) \| null	When the sheet's increases take effect: "now", an ISO instant, or omitted for the default notice period (diff and apply only)

Response 200

Field	Type	Description
`data`required	object	-
`applied`requireddata.applied	integer	-
`added`requireddata.added	integer	-
`changed`requireddata.changed	integer	-
`removed`requireddata.removed	integer	-
`droppedBlocked`requireddata.droppedBlocked	integer	-
`diff`data.diff	any	-

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/routes/<id>/rate-sheets/<importId>/reapply" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fxRate": 1,
  "mapping": "<mapping>"
}'

Run it here with a test key.

Publish an A-Z deck as per-country listings

POST/api/v1/routes/{id}/publish-by-country

Access: API key. Scoped keys need routes:write.
Rate limit: 6 requests per minute

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`perCarrier`	boolean	-

Response 200

Field	Type	Description
`data`required	object	The listings created

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/routes/<id>/publish-by-country" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "perCarrier": true
}'

Run it here with a test key.

Collapse per-country listings back into one deck

POST/api/v1/routes/{id}/collapse-bundle

Access: API key. Scoped keys need routes:write.
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	-
`removed`requireddata.removed	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.

List the per-country listings of a deck

GET/api/v1/routes/{id}/children

Access: API key. Scoped keys need routes: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[]	-

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 per-destination rates on a route

GET/api/v1/routes/{id}/rates

Access: Key optional. A key or token personalises the answer.
Rate limit: 100 requests per second (the default)

Public for public routes. Buyers see cleaned destination names and no upstream operator labels.

Parameters

Name	In	Type	Description
`id`required	path	string	-
`search`	query	string	-
`limit`	query	integer	-
`offset`	query	integer	-

Response 200

Field	Type	Description
`rates`required	object[]	-
`id`requiredrates[].id	string (uuid)	-
`routeId`requiredrates[].routeId	string (uuid)	-
`destinationName`requiredrates[].destinationName	string	-
`operator`requiredrates[].operator	string \| null	-
`prefix`requiredrates[].prefix	string	-
`ratePerUnit`requiredrates[].ratePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requiredrates[].billingIncrement	string \| null	-
`minDuration`requiredrates[].minDuration	integer \| null	-
`effectiveDate`requiredrates[].effectiveDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`status`requiredrates[].status	string	-
`mccMnc`rates[].mccMnc	string \| null	SMS sheets priced by network code: the network the row price came from ("214" = whole country)
`operatorRates`rates[].operatorRates	object[] \| null	SMS sheets priced by network: the price per destination network (charged per network when `networkPriced` is true). A message is charged its network's rate (networks not listed pay the All Operators rate when there is one); `ratePerUnit` is the price for other or unknown networks. The network is determined from the number's range (ported numbers may be priced at the network the range belongs to)
`mccMnc`requiredrates[].operatorRates[].mccMnc	string	"214-07" for one network; "214" for All Operators
`operator`requiredrates[].operatorRates[].operator	string \| null	-
`rate`requiredrates[].operatorRates[].rate	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`networkPriced`rates[].networkPriced	boolean	True when each SMS on this row is charged its destination network's rate from `operatorRates`; `ratePerUnit` then applies to other or unknown networks
`total`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.
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.

Add a rate to your route's deck

POST/api/v1/routes/{id}/rates

Access: API key. Scoped keys need routes: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
`destinationName`required	string	-max 255 chars
`operator`	string \| null	-max 120 chars
`prefix`required	string	-max 24 chars
`ratePerUnit`required	string	-
`billingIncrement`	string	-max 10 chars
`minDuration`	integer	-min 0

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`routeId`requireddata.routeId	string (uuid)	-
`destinationName`requireddata.destinationName	string	-
`operator`requireddata.operator	string \| null	-
`prefix`requireddata.prefix	string	-
`ratePerUnit`requireddata.ratePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.billingIncrement	string \| null	-
`minDuration`requireddata.minDuration	integer \| null	-
`effectiveDate`requireddata.effectiveDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`status`requireddata.status	string	-
`mccMnc`data.mccMnc	string \| null	SMS sheets priced by network code: the network the row price came from ("214" = whole country)
`operatorRates`data.operatorRates	object[] \| null	SMS sheets priced by network: the price per destination network (charged per network when `networkPriced` is true). A message is charged its network's rate (networks not listed pay the All Operators rate when there is one); `ratePerUnit` is the price for other or unknown networks. The network is determined from the number's range (ported numbers may be priced at the network the range belongs to)
`mccMnc`requireddata.operatorRates[].mccMnc	string	"214-07" for one network; "214" for All Operators
`operator`requireddata.operatorRates[].operator	string \| null	-
`rate`requireddata.operatorRates[].rate	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`networkPriced`data.networkPriced	boolean	True when each SMS on this row is charged its destination network's rate from `operatorRates`; `ratePerUnit` then applies to other or unknown networks
`updated`requireddata.updated	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/routes/<id>/rates" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "destinationName": "<destinationName>",
  "prefix": "44",
  "ratePerUnit": "<ratePerUnit>"
}'

Run it here with a test key.

Export a route's rates as CSV

GET/api/v1/routes/{id}/rates/export

Access: Key optional. A key or token personalises the answer.
Rate limit: 100 requests per second (the default)

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200 (text/csv)

The deck as CSV (attachment).

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.

Add many rates to your route's deck

POST/api/v1/routes/{id}/rates/bulk

Access: API key. Scoped keys need routes: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
`rows`required	object[]	-
`destinationName`rows[].destinationName	string	-max 255 chars
`operator`rows[].operator	string \| null	-max 120 chars
`prefix`requiredrows[].prefix	string	-max 24 chars
`ratePerUnit`requiredrows[].ratePerUnit	string	-max 32 chars
`billingIncrement`rows[].billingIncrement	string	-max 10 chars
`minDuration`rows[].minDuration	integer	-min 0

Response 201

Field	Type	Description
`data`required	object	-
`added`requireddata.added	integer	-
`updated`requireddata.updated	integer	-
`skipped`requireddata.skipped	integer	-
`skippedRows`requireddata.skippedRows	object[]	-

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/routes/<id>/rates/bulk" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "prefix": "44",
      "ratePerUnit": "<ratePerUnit>"
    }
  ]
}'

Run it here with a test key.

Edit or block one rate in your deck

PATCH/api/v1/routes/{id}/rates/{rateId}

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

Parameters

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

Request body (application/json)

Field	Type	Description
`destinationName`	string	-max 255 chars
`ratePerUnit`	string	-
`billingIncrement`	string \| null	-max 10 chars
`minDuration`	integer \| null	-min 0
`blocked`	boolean	-

Response 200

Field	Type	Description
`data`required	object	Same fields as RouteRate, 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/routes/<id>/rates/<rateId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "destinationName": "<destinationName>",
  "ratePerUnit": "<ratePerUnit>"
}'

Run it here with a test key.

Delete one rate from your deck

DELETE/api/v1/routes/{id}/rates/{rateId}

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

Parameters

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

Response 200

Field	Type	Description
`data`required	object	-
`message`requireddata.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.
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 scheduled rate changes on your route

GET/api/v1/routes/{id}/rate-changes

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

With how many buyers are held by each change and how many already accepted it.

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	-
`status`requireddata[].status	string	-
`effectiveDate`requireddata[].effectiveDate	string (date-time)	ISO-8601 timestamp (UTC)
`increases`requireddata[].increases	integer	-
`decreases`requireddata[].decreases	integer	-
`added`requireddata[].added	integer	-
`removed`requireddata[].removed	integer	-
`largestIncreasePct`requireddata[].largestIncreasePct	number \| null	-
`sampleOldRate`requireddata[].sampleOldRate	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".
`sampleNewRate`requireddata[].sampleNewRate	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".
`flatOldPrice`requireddata[].flatOldPrice	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".
`flatNewPrice`requireddata[].flatNewPrice	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".
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`notifiedAt`requireddata[].notifiedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`promotedAt`requireddata[].promotedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`cancelledAt`requireddata[].cancelledAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`heldPurchases`requireddata[].heldPurchases	integer \| null	-
`acceptedPurchases`requireddata[].acceptedPurchases	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.

Schedule a price change on a one-price route

POST/api/v1/routes/{id}/rate-changes/flat

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

An increase takes effect after the notice period when list-rate buyers are bound; buyers are notified and can accept in advance. Replaces any change already scheduled.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`newPrice`required	string	-
`effectiveDate`	string (date-time) \| null	Omit for the default notice period

Response 201

Field	Type	Description
`data`required	object	-
`scheduled`requireddata.scheduled	boolean	False when the change applied immediately
`changeId`requireddata.changeId	string (uuid)	-
`effectiveDate`requireddata.effectiveDate	string (date-time)	ISO-8601 timestamp (UTC)
`boundBuyers`requireddata.boundBuyers	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/routes/<id>/rate-changes/flat" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "newPrice": "<newPrice>"
}'

Run it here with a test key.

Withdraw a scheduled rate change

POST/api/v1/routes/{id}/rate-changes/{changeId}/cancel

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

Parameters

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

Response 200

Field	Type	Description
`data`required	object	-
`cancelled`requireddata.cancelled	boolean	-One of `true`

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/routes/<id>/rate-changes/<changeId>/cancel" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.