Switch API reference

Switch: rating

Rate decks, sell decks and sell rates: what you pay and what you charge.

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

BrowseSwitch: rating

Analyse the cost and configured margin of a destination

GET/api/v1/switch/cost-analysis

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

Resolves the route a call from this customer trunk would take (the same resolver the switch uses), prices every eligible supplier with its own increment and deck, and estimates margin on a call of seconds length. Read-only: no call record, balance or capacity is touched. This is an estimate; see /margin/realised for what was actually earned.

Parameters

Name	In	Type	Description
`destination`required	query	string	-
`origin`	query	string	-
`customerId`	query	string (uuid)	-
`customerTrunkId`	query	string (uuid)	-
`seconds`	query	integer	Reference call length for the margin estimate

Response 200

Field	Type	Description
`data`required	object	-
`at`requireddata.at	string (date-time)	ISO-8601 timestamp (UTC)
`input`requireddata.input	object	The destination, routed number, origin, customer, trunk and reference call length used
`basis`requireddata.basis	object	-
`resolved`requireddata.basis.resolved	boolean	-
`detail`requireddata.basis.detail	string	-
`routingKind`requireddata.basis.routingKind	string	-One of `fixed`, `group`, `dialplan`, `none`
`routingName`requireddata.basis.routingName	string \| null	-
`selectionMode`requireddata.basis.selectionMode	string \| null	-
`maxAttempts`requireddata.basis.maxAttempts	integer \| null	-
`sell`requireddata.sell	object	-
`outcome`requireddata.sell.outcome	object \| null	A price, or the reason there is none. Only kind = rated carries a rate.
`kind`requireddata.sell.outcome.kind	string	-One of `rated`, `no_matching_rate`, `not_yet_effective`, `expired`, `forbidden`, `rating_failed`, `not_billable`
`rate`data.sell.outcome.rate	number	Present when kind = rated. May legitimately be 0.
`matchedPrefix`data.sell.outcome.matchedPrefix	string	-
`deckVersion`data.sell.outcome.deckVersion	integer \| null	-
`source`data.sell.outcome.source	string	-
`destination`data.sell.outcome.destination	string	-
`effectiveFrom`data.sell.outcome.effectiveFrom	string	-
`expiredAt`data.sell.outcome.expiredAt	string	-
`reason`data.sell.outcome.reason	string	Why it is forbidden or failed
`billingRate`requireddata.sell.billingRate	number \| null	USD as a JSON number (engine output, up to 6 decimal places)
`matchedPrefix`requireddata.sell.matchedPrefix	string \| null	-
`billingIncrement`requireddata.sell.billingIncrement	string	-
`suppliers`requireddata.suppliers	object[]	-
`vendorTrunkId`requireddata.suppliers[].vendorTrunkId	string (uuid) \| null	-
`label`requireddata.suppliers[].label	string	-
`kind`requireddata.suppliers[].kind	string	-One of `supplier trunk`, `marketplace route`
`chainOrdinal`requireddata.suppliers[].chainOrdinal	integer \| null	Attempt position in the failover chain; null if past the attempt ceiling
`outcome`requireddata.suppliers[].outcome	object \| null	A price, or the reason there is none. Only kind = rated carries a rate.Same fields as SwitchRatingOutcome, shown earlier on this page.
`billingRate`requireddata.suppliers[].billingRate	number \| null	USD as a JSON number (engine output, up to 6 decimal places)
`source`requireddata.suppliers[].source	string	-One of `supplier deck`, `trunk default`, `marketplace listing`, `unpriced`
`matchedPrefix`requireddata.suppliers[].matchedPrefix	string \| null	-
`deckId`requireddata.suppliers[].deckId	string (uuid) \| null	-
`deckVersion`requireddata.suppliers[].deckVersion	integer \| null	-
`billingIncrement`requireddata.suppliers[].billingIncrement	string	-
`excluded`requireddata.suppliers[].excluded	object \| null	-
`stage`requireddata.suppliers[].excluded.stage	string	-
`reason`requireddata.suppliers[].excluded.reason	string	-
`detail`requireddata.suppliers[].excluded.detail	string	-
`selected`requireddata.selected	object \| null	-
`vendorTrunkId`requireddata.selected.vendorTrunkId	string (uuid) \| null	-
`label`requireddata.selected.label	string	-
`kind`requireddata.selected.kind	string	-One of `supplier trunk`, `marketplace route`
`chainOrdinal`requireddata.selected.chainOrdinal	integer \| null	Attempt position in the failover chain; null if past the attempt ceiling
`outcome`requireddata.selected.outcome	object \| null	A price, or the reason there is none. Only kind = rated carries a rate.Same fields as SwitchRatingOutcome, shown earlier on this page.
`billingRate`requireddata.selected.billingRate	number \| null	USD as a JSON number (engine output, up to 6 decimal places)
`source`requireddata.selected.source	string	-One of `supplier deck`, `trunk default`, `marketplace listing`, `unpriced`
`matchedPrefix`requireddata.selected.matchedPrefix	string \| null	-
`deckId`requireddata.selected.deckId	string (uuid) \| null	-
`deckVersion`requireddata.selected.deckVersion	integer \| null	-
`billingIncrement`requireddata.selected.billingIncrement	string	-
`excluded`requireddata.selected.excluded	object \| null	-
`stage`requireddata.selected.excluded.stage	string	-
`reason`requireddata.selected.excluded.reason	string	-
`detail`requireddata.selected.excluded.detail	string	-
`configuredMargin`requireddata.configuredMargin	object	-
`kind`requireddata.configuredMargin.kind	string	-One of `configured_estimate`
`perMinute`requireddata.configuredMargin.perMinute	number \| null	USD as a JSON number (engine output, up to 6 decimal places)
`perMinutePct`requireddata.configuredMargin.perMinutePct	number \| null	-
`referenceCall`requireddata.configuredMargin.referenceCall	object \| null	Revenue, cost and margin of a call of the reference length, increment-aware (JSON numbers)
`range`requireddata.configuredMargin.range	object \| null	-
`explain`requireddata.configuredMargin.explain	object[]	-
`label`requireddata.configuredMargin.explain[].label	string	-
`value`requireddata.configuredMargin.explain[].value	string	-
`note`data.configuredMargin.explain[].note	string	-
`source`data.configuredMargin.explain[].source	string	-
`traceId`requireddata.traceId	string (uuid)	The route trace this analysis ran on
`verdict`requireddata.verdict	object	-
`sideEffects`requireddata.sideEffects	object	-
`createdCdr`requireddata.sideEffects.createdCdr	boolean	-One of `false`
`movedBalance`requireddata.sideEffects.movedBalance	boolean	-One of `false`
`consumedCapacity`requireddata.sideEffects.consumedCapacity	boolean	-One of `false`

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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List the suppliers that can carry a customer's traffic

GET/api/v1/switch/cost-analysis/suppliers

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

Destination-independent: which supplier trunks the customer's routing makes eligible, and whether each can be priced. Name a customer or a customer trunk. When a customer has several trunks with different routing, ambiguous says so.

Parameters

Name	In	Type	Description
`customerId`	query	string (uuid)	-
`customerTrunkId`	query	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`suppliers`requireddata.suppliers	object[]	-
`vendorTrunkId`requireddata.suppliers[].vendorTrunkId	string (uuid)	-
`label`requireddata.suppliers[].label	string	-
`status`requireddata.suppliers[].status	string	-
`via`requireddata.suppliers[].via	object[]	-
`source`requireddata.suppliers[].via[].source	string	-One of `fixed target`, `route group`, `failover group`, `dialplan rule`
`groupId`requireddata.suppliers[].via[].groupId	string (uuid) \| null	-
`groupName`requireddata.suppliers[].via[].groupName	string \| null	-
`prefix`requireddata.suppliers[].via[].prefix	string \| null	-
`priority`requireddata.suppliers[].via[].priority	integer \| null	-
`defaultRatePerUnit`requireddata.suppliers[].defaultRatePerUnit	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".
`activeRateRows`requireddata.suppliers[].activeRateRows	integer	-
`unpriced`requireddata.suppliers[].unpriced	boolean	True when the trunk has no rates and no default: calls to it cannot be costed
`billingIncrement`requireddata.suppliers[].billingIncrement	string	-
`routing`requireddata.routing	object	-
`kind`requireddata.routing.kind	string	-One of `fixed`, `group`, `dialplan`, `none`
`name`requireddata.routing.name	string \| null	-
`selectionMode`requireddata.routing.selectionMode	string \| null	-
`maxAttempts`requireddata.routing.maxAttempts	integer \| null	-
`trunkIds`requireddata.routing.trunkIds	string (uuid)[]	-
`ambiguous`requireddata.ambiguous	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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get realised margin over a period

GET/api/v1/switch/margin/realised

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

What customers were actually charged minus what suppliers actually cost, including the estimated cost of answered attempts that did not win. All amounts are JSON numbers in USD. exposure lists what makes the figure less reliable (for example sessions billed with no supplier cost).

Parameters

Name	In	Type	Description
`from`	query	string	ISO timestamp; default 24 hours before `to`
`to`	query	string	ISO timestamp; default now
`customerId`	query	string (uuid)	-
`customerTrunkId`	query	string (uuid)	-
`supplierTrunkId`	query	string (uuid)	-
`kind`	query	string	voice (default) or all, which includes SMSOne of voice, all

Response 200

Field	Type	Description
`data`required	object	-
`kind`requireddata.kind	string	-One of `realised_actual`
`window`requireddata.window	object	-
`from`requireddata.window.from	string	-
`to`requireddata.window.to	string	-
`label`requireddata.window.label	string	-
`basis`requireddata.basis	object	-
`answer`requireddata.answer	object	-
`revenue`requireddata.revenue	object	-
`customerCharges`requireddata.revenue.customerCharges	number	USD as a JSON number (engine output, up to 6 decimal places)
`platformFee`requireddata.revenue.platformFee	number	USD as a JSON number (engine output, up to 6 decimal places)
`feeCertainty`requireddata.revenue.feeCertainty	string	-One of `exact`, `upper_bound`
`operatorRevenue`requireddata.revenue.operatorRevenue	number	USD as a JSON number (engine output, up to 6 decimal places)
`cost`requireddata.cost	object	-
`booked`requireddata.cost.booked	number	USD as a JSON number (engine output, up to 6 decimal places)
`unbookedAttemptCost`requireddata.cost.unbookedAttemptCost	number	USD as a JSON number (engine output, up to 6 decimal places)
`unbookedAttempts`requireddata.cost.unbookedAttempts	integer	-
`total`requireddata.cost.total	number	USD as a JSON number (engine output, up to 6 decimal places)
`gross`requireddata.gross	number	USD as a JSON number (engine output, up to 6 decimal places)
`grossPct`requireddata.grossPct	number \| null	-
`exposure`requireddata.exposure	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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List per-call realised margin

GET/api/v1/switch/margin/realised/sessions

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

One row per session with its charge and every supplier attempt beneath it. Paged (limit up to 200).

Parameters

Name	In	Type	Description
`from`	query	string	ISO timestamp; default 24 hours before `to`
`to`	query	string	ISO timestamp; default now
`customerId`	query	string (uuid)	-
`customerTrunkId`	query	string (uuid)	-
`supplierTrunkId`	query	string (uuid)	-
`kind`	query	string	voice (default) or all, which includes SMSOne of voice, all
`negativeOnly`	query	boolean	Only sessions that lost money
`failoverOnly`	query	boolean	Only sessions that needed more than one attempt
`limit`	query	integer	-
`offset`	query	integer	-

Response 200

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`sessionKey`requireddata.rows[].sessionKey	string	-
`callUuid`requireddata.rows[].callUuid	string \| null	-
`at`requireddata.rows[].at	string (date-time)	ISO-8601 timestamp (UTC)
`destination`requireddata.rows[].destination	string \| null	-
`destinationName`requireddata.rows[].destinationName	string \| null	-
`customerTrunkId`requireddata.rows[].customerTrunkId	string (uuid) \| null	-
`status`requireddata.rows[].status	string \| null	-
`durationSeconds`requireddata.rows[].durationSeconds	integer	-
`billedSeconds`requireddata.rows[].billedSeconds	integer \| null	-
`billingIncrement`requireddata.rows[].billingIncrement	string \| null	-
`sellRate`requireddata.rows[].sellRate	number \| null	USD as a JSON number (engine output, up to 6 decimal places)
`charge`requireddata.rows[].charge	number	USD as a JSON number (engine output, up to 6 decimal places)
`bookedCost`requireddata.rows[].bookedCost	number	USD as a JSON number (engine output, up to 6 decimal places)
`attempts`requireddata.rows[].attempts	object[]	-
`ordinal`requireddata.rows[].attempts[].ordinal	integer	-
`supplier`requireddata.rows[].attempts[].supplier	string \| null	-
`vendorTrunkId`requireddata.rows[].attempts[].vendorTrunkId	string (uuid) \| null	-
`outcome`requireddata.rows[].attempts[].outcome	string	-
`sipStatus`requireddata.rows[].attempts[].sipStatus	integer \| null	-
`won`requireddata.rows[].attempts[].won	boolean	-
`answeredSeconds`requireddata.rows[].attempts[].answeredSeconds	integer \| null	-
`buyRate`requireddata.rows[].attempts[].buyRate	number \| null	USD as a JSON number (engine output, up to 6 decimal places)
`costBasis`requireddata.rows[].attempts[].costBasis	string	-One of `booked`, `derived`, `none`
`derivedCost`requireddata.rows[].attempts[].derivedCost	number \| null	USD as a JSON number (engine output, up to 6 decimal places)
`attemptCost`requireddata.rows[].attemptCost	number	USD as a JSON number (engine output, up to 6 decimal places)
`margin`requireddata.rows[].margin	number	USD as a JSON number (engine output, up to 6 decimal places)
`flags`requireddata.rows[].flags	string[]	-
`total`requireddata.total	integer	-
`limit`requireddata.limit	integer	-
`offset`requireddata.offset	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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get the realised margin of one call

GET/api/v1/switch/margin/realised/sessions/{callUuid}

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

Parameters

Name	In	Type	Description
`callUuid`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchSessionMargin, 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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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 supplier rate decks

GET/api/v1/switch/rate-decks

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

Newest first, up to 500, with row counts and the supplier trunks each deck prices.

Parameters

Name	In	Type	Description
`supplierId`	query	string (uuid)	Only decks from this provider
`trunkId`	query	string (uuid)	Only decks that price this supplier trunk
`status`	query	string	-One of draft, uploaded, invalid, validated, pending_approval, scheduled, active, expired, rolled_back

Response 200

Field	Type	Description
`data`required	object	-
`decks`requireddata.decks	object[]	-
`id`requireddata.decks[].id	string (uuid)	-
`supplierId`requireddata.decks[].supplierId	string (uuid) \| null	The provider who sent it; null for a deck recorded before its provider was
`name`requireddata.decks[].name	string	-
`currency`requireddata.decks[].currency	string	-max 3 chars
`version`requireddata.decks[].version	integer	-
`status`requireddata.decks[].status	string	-One of `draft`, `uploaded`, `invalid`, `validated`, `pending_approval`, `scheduled`, `active`, `expired`, `rolled_back`
`effectiveFrom`requireddata.decks[].effectiveFrom	string (date-time) \| null	ISO-8601 timestamp (UTC)
`expiresAt`requireddata.decks[].expiresAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`source`requireddata.decks[].source	string \| null	-One of `portal`, `csv`, `api`, `email`, `sftp`
`sourceRef`requireddata.decks[].sourceRef	string \| null	-
`approvedAt`requireddata.decks[].approvedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`validation`requireddata.decks[].validation	object \| null	The last validation result; null before the deck is validated
`checkedAt`requireddata.decks[].validation.checkedAt	string	-
`rows`requireddata.decks[].validation.rows	integer	-
`destinations`requireddata.decks[].validation.destinations	integer	-
`errors`requireddata.decks[].validation.errors	object[]	-
`warnings`requireddata.decks[].validation.warnings	object[]	-
`maxIncreasePct`data.decks[].validation.maxIncreasePct	number	-
`supersedesId`requireddata.decks[].supersedesId	string (uuid) \| null	-
`rolledBackAt`requireddata.decks[].rolledBackAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`notes`requireddata.decks[].notes	string \| null	-
`createdAt`requireddata.decks[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.decks[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`rowCount`requireddata.decks[].rowCount	integer	-
`trunks`requireddata.decks[].trunks	object[]	Supplier trunks the deck prices
`id`requireddata.decks[].trunks[].id	string (uuid)	-
`label`requireddata.decks[].trunks[].label	string	-
`mutable`requireddata.decks[].mutable	boolean	Whether rows can still be edited

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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.

Create a supplier rate deck

POST/api/v1/switch/rate-decks

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

Creates a draft deck (version 1, or the next version of an existing name for that provider). Load rows with PUT /rate-decks/{id}/rows.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

Field	Type	Description
`supplierId`	string (uuid) \| null	-
`name`required	string	-max 160 chars
`currency`	string	-max 3 chars
`source`	string \| null	-One of `portal`, `csv`, `api`, `email`, `sftp`
`sourceRef`	string \| null	-max 500 chars
`effectiveFrom`	string \| null	-max 40 chars
`expiresAt`	string \| null	-max 40 chars
`trunkIds`	string (uuid)[]	-
`notes`	string \| null	-max 4000 chars

Response 201

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/rate-decks" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme"
}'

Run it here with a test key.

Get a supplier rate deck

GET/api/v1/switch/rate-decks/{id}

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

The deck, its trunks and row count. Rows themselves are read from the supplier trunk rates.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, 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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Delete a rate deck

DELETE/api/v1/switch/rate-decks/{id}

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

Deletes the deck and its rows. An active deck must be rolled back first.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

List every version of a rate deck

GET/api/v1/switch/rate-decks/{id}/history

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

All versions sharing this deck's name and provider, newest first.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`name`requireddata.name	string	-
`versions`requireddata.versions	object[]	-
`id`requireddata.versions[].id	string (uuid)	-
`supplierId`requireddata.versions[].supplierId	string (uuid) \| null	The provider who sent it; null for a deck recorded before its provider was
`name`requireddata.versions[].name	string	-
`currency`requireddata.versions[].currency	string	-max 3 chars
`version`requireddata.versions[].version	integer	-
`status`requireddata.versions[].status	string	-One of `draft`, `uploaded`, `invalid`, `validated`, `pending_approval`, `scheduled`, `active`, `expired`, `rolled_back`
`effectiveFrom`requireddata.versions[].effectiveFrom	string (date-time) \| null	ISO-8601 timestamp (UTC)
`expiresAt`requireddata.versions[].expiresAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`source`requireddata.versions[].source	string \| null	-One of `portal`, `csv`, `api`, `email`, `sftp`
`sourceRef`requireddata.versions[].sourceRef	string \| null	-
`approvedAt`requireddata.versions[].approvedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`validation`requireddata.versions[].validation	object \| null	The last validation result; null before the deck is validated
`checkedAt`requireddata.versions[].validation.checkedAt	string	-
`rows`requireddata.versions[].validation.rows	integer	-
`destinations`requireddata.versions[].validation.destinations	integer	-
`errors`requireddata.versions[].validation.errors	object[]	-
`warnings`requireddata.versions[].validation.warnings	object[]	-
`maxIncreasePct`data.versions[].validation.maxIncreasePct	number	-
`supersedesId`requireddata.versions[].supersedesId	string (uuid) \| null	-
`rolledBackAt`requireddata.versions[].rolledBackAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`notes`requireddata.versions[].notes	string \| null	-
`createdAt`requireddata.versions[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.versions[].updatedAt	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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.

Compare a rate deck with the prices in force

GET/api/v1/switch/rate-decks/{id}/diff

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

Per supplier trunk the deck covers, what activating it would change against the rows pricing calls now. Writes nothing.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`deckId`requireddata.deckId	string (uuid)	-
`name`requireddata.name	string	-
`version`requireddata.version	integer	-
`status`requireddata.status	string	-One of `draft`, `uploaded`, `invalid`, `validated`, `pending_approval`, `scheduled`, `active`, `expired`, `rolled_back`
`effectiveFrom`requireddata.effectiveFrom	string (date-time) \| null	ISO-8601 timestamp (UTC)
`trunks`requireddata.trunks	object[]	-
`trunkId`requireddata.trunks[].trunkId	string (uuid)	-
`label`requireddata.trunks[].label	string	-
`diff`requireddata.trunks[].diff	object	What a change does to live pricing, with the biggest movers
`removalMode`requireddata.trunks[].diff.removalMode	string	-One of `merge`, `replace`
`changeMode`requireddata.trunks[].diff.changeMode	string	-One of `amendment`, `full_replacement`
`live`requireddata.trunks[].diff.live	integer	Prefixes priced on the live deck now
`incoming`requireddata.trunks[].diff.incoming	integer	Prefixes the new rows price
`added`requireddata.trunks[].diff.added	integer	-
`changed`requireddata.trunks[].diff.changed	integer	-
`rateChanged`requireddata.trunks[].diff.rateChanged	integer	-
`incrementOnly`requireddata.trunks[].diff.incrementOnly	integer	Changed rows where only the billing increment moved
`unchanged`requireddata.trunks[].diff.unchanged	integer	-
`removed`requireddata.trunks[].diff.removed	integer	Live prefixes the new rows do not mention
`originScoped`requireddata.trunks[].originScoped	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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.

Set which supplier trunks a rate deck prices

PUT/api/v1/switch/rate-decks/{id}/trunks

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

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`trunkIds`required	string (uuid)[]	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

HTTP

curl -X PUT "https://packetexchange.io/api/v1/switch/rate-decks/<id>/trunks" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "trunkIds": [
    "<trunkId>"
  ]
}'

Run it here with a test key.

Replace the rows of a draft rate deck

PUT/api/v1/switch/rate-decks/{id}/rows

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

Up to 200,000 rows, replacing whatever the deck held. Rows are stored pending and price nothing until the deck is activated. Validation runs straight after, and the validated deck is returned. Rows can only be changed while the deck is draft, uploaded, invalid or validated (mutable: true); an active deck is changed by opening a new version.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`rows`required	object[]	-
`prefix`requiredrows[].prefix	string	-max 24 chars
`rate`requiredrows[].rate	number \| string	Price per minute; a number or a decimal string. Blank is refused, 0 is a real price.
`origin`rows[].origin	string	Caller-origin prefix; omit for any originmax 24 chars
`destinationName`rows[].destinationName	string \| null	-max 96 chars
`country`rows[].country	string \| null	-max 64 chars
`mcc`rows[].mcc	string \| null	-max 8 chars
`mnc`rows[].mnc	string \| null	-max 8 chars
`jurisdiction`rows[].jurisdiction	string \| null	-max 16 chars
`connectionFee`rows[].connectionFee	number \| string \| null	-
`minChargedSeconds`rows[].minChargedSeconds	integer \| null	-min 0
`billingIncrement`rows[].billingIncrement	string \| null	-max 10 chars
`effectiveFrom`rows[].effectiveFrom	string \| null	-max 40 chars
`endDate`rows[].endDate	string \| null	-max 40 chars

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

HTTP

curl -X PUT "https://packetexchange.io/api/v1/switch/rate-decks/<id>/rows" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "prefix": "44",
      "rate": 1
    }
  ]
}'

Run it here with a test key.

Open a new draft version of a rate deck

POST/api/v1/switch/rate-decks/{id}/versions

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

Copies this deck's rows and trunks into version n+1 as a draft, so an active deck can be repriced without editing it in place.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 201

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

Validate a rate deck

POST/api/v1/switch/rate-decks/{id}/validate

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

Checks the rows (missing prices, duplicate prefixes, increases) and stores the result on the deck. A deck with errors becomes invalid and cannot be activated.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

Submit a rate deck for approval

POST/api/v1/switch/rate-decks/{id}/submit

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

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

Approve a rate deck, now or from a future date

POST/api/v1/switch/rate-decks/{id}/approve

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

With no effectiveFrom (or a past one) the deck is activated immediately. A future effectiveFrom schedules it and emits the cost_rate.scheduled webhook.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`effectiveFrom`	string \| null	-max 40 chars

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/rate-decks/<id>/approve" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "effectiveFrom": "<effectiveFrom>"
}'

Run it here with a test key.

Activate a rate deck

POST/api/v1/switch/rate-decks/{id}/activate

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

Makes the deck's rows price calls on its trunks from now on and supersedes the deck they replace. Exactly one deck is active per trunk.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

Roll back an active rate deck

POST/api/v1/switch/rate-decks/{id}/rollback

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

Withdraws the deck and restores the one it superseded (named in restoredDeckId). Emits the cost_rate.rolled_back webhook.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`supplierId`requireddata.supplierId	string (uuid) \| null	The provider who sent it; null for a deck recorded before its provider was
`name`requireddata.name	string	-
`currency`requireddata.currency	string	-max 3 chars
`version`requireddata.version	integer	-
`status`requireddata.status	string	-One of `draft`, `uploaded`, `invalid`, `validated`, `pending_approval`, `scheduled`, `active`, `expired`, `rolled_back`
`effectiveFrom`requireddata.effectiveFrom	string (date-time) \| null	ISO-8601 timestamp (UTC)
`expiresAt`requireddata.expiresAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`source`requireddata.source	string \| null	-One of `portal`, `csv`, `api`, `email`, `sftp`
`sourceRef`requireddata.sourceRef	string \| null	-
`approvedAt`requireddata.approvedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`validation`requireddata.validation	object \| null	The last validation result; null before the deck is validated
`checkedAt`requireddata.validation.checkedAt	string	-
`rows`requireddata.validation.rows	integer	-
`destinations`requireddata.validation.destinations	integer	-
`errors`requireddata.validation.errors	object[]	-
`warnings`requireddata.validation.warnings	object[]	-
`maxIncreasePct`data.validation.maxIncreasePct	number	-
`supersedesId`requireddata.supersedesId	string (uuid) \| null	-
`rolledBackAt`requireddata.rolledBackAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`notes`requireddata.notes	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`rowCount`requireddata.rowCount	integer	-
`trunks`requireddata.trunks	object[]	Supplier trunks the deck prices
`id`requireddata.trunks[].id	string (uuid)	-
`label`requireddata.trunks[].label	string	-
`mutable`requireddata.mutable	boolean	Whether rows can still be edited
`restoredDeckId`requireddata.restoredDeckId	string (uuid) \| null	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.
AlsoSTALE_WRITE

Show what a blank rating or limit field inherits

GET/api/v1/switch/inherited-defaults

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

Your operator defaults, the platform fallbacks, and the inheritance chain for each field in plain words.

Response 200

Field	Type	Description
`data`required	object	-
`operator`requireddata.operator	object	-
`markupPct`requireddata.operator.markupPct	number \| null	-
`dailySpendCap`requireddata.operator.dailySpendCap	number \| null	USD, a JSON number
`maxConcurrentCalls`requireddata.operator.maxConcurrentCalls	number \| null	-
`billingIncrement`requireddata.operator.billingIncrement	string \| null	-
`platform`requireddata.platform	object	-
`billingIncrement`requireddata.platform.billingIncrement	string	-One of `1/1`
`maxConcurrentCalls`requireddata.platform.maxConcurrentCalls	enum \| null	-One of `null`
`maxCps`requireddata.platform.maxCps	enum \| null	-One of `null`
`chains`requireddata.chains	object	Field name -> how a blank resolves

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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List sell decks

GET/api/v1/switch/sell-decks

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

Every version of every sell deck, with how many customers and trunks each one reaches.

Parameters

Name	In	Type	Description
`status`	query	string	-One of draft, active, superseded, archived

Response 200

Field	Type	Description
`data`required	object	-
`decks`requireddata.decks	object[]	-
`id`requireddata.decks[].id	string (uuid)	-
`name`requireddata.decks[].name	string	-
`version`requireddata.decks[].version	integer	-
`status`requireddata.decks[].status	string	-One of `draft`, `active`, `superseded`, `archived`
`currency`requireddata.decks[].currency	string	-max 3 chars
`isSystemDefault`requireddata.decks[].isSystemDefault	boolean	-
`defaultRatePerUnit`requireddata.decks[].defaultRatePerUnit	number \| null	Catch-all price for destinations the deck does not list (a JSON number)
`charging`requireddata.decks[].charging	object	-
`minimumDurationSeconds`requireddata.decks[].charging.minimumDurationSeconds	integer \| null	-
`firstIntervalSeconds`requireddata.decks[].charging.firstIntervalSeconds	integer \| null	-
`subsequentIntervalSeconds`requireddata.decks[].charging.subsequentIntervalSeconds	integer \| null	-
`setupFee`requireddata.decks[].charging.setupFee	number \| null	Per-call setup fee (a JSON number)
`graceSeconds`requireddata.decks[].charging.graceSeconds	integer \| null	-
`rounding`requireddata.decks[].charging.rounding	string \| null	-One of `up`, `nearest`, `down`
`effectiveFrom`requireddata.decks[].effectiveFrom	string (date-time) \| null	ISO-8601 timestamp (UTC)
`notes`requireddata.decks[].notes	string \| null	-
`updatedAt`requireddata.decks[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`activeRates`requireddata.decks[].activeRates	integer	Rows in the deck
`customersOnIt`requireddata.decks[].customersOnIt	integer	Customers whose default deck this is
`trunksNamingIt`requireddata.decks[].trunksNamingIt	integer	Trunks that name this deck directly

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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.

Create a sell deck

POST/api/v1/switch/sell-decks

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

Creates a draft (version 1, or the next version of an existing name). Load prices, then publish.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

Field	Type	Description
`name`required	string	-max 160 chars
`currency`	string	-max 3 chars
`defaultRatePerUnit`	number \| string \| null	Catch-all price; null or "" clears it
`minimumDurationSeconds`	integer \| null	-0 to 3600
`firstIntervalSeconds`	integer \| null	Set together with subsequentIntervalSeconds, or neither1 to 3600
`subsequentIntervalSeconds`	integer \| null	-1 to 3600
`setupFee`	number \| string \| null	-
`graceSeconds`	integer \| null	-0 to 120
`rounding`	string \| null	-One of `up`, `nearest`, `down`
`notes`	string \| null	-
`effectiveFrom`	string \| null	ISO timestamp

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`version`requireddata.version	integer	-
`status`requireddata.status	string	-One of `draft`, `active`, `superseded`, `archived`
`currency`requireddata.currency	string	-max 3 chars
`isSystemDefault`requireddata.isSystemDefault	boolean	-
`defaultRatePerUnit`requireddata.defaultRatePerUnit	number \| null	Catch-all price for destinations the deck does not list (a JSON number)
`charging`requireddata.charging	object	-
`minimumDurationSeconds`requireddata.charging.minimumDurationSeconds	integer \| null	-
`firstIntervalSeconds`requireddata.charging.firstIntervalSeconds	integer \| null	-
`subsequentIntervalSeconds`requireddata.charging.subsequentIntervalSeconds	integer \| null	-
`setupFee`requireddata.charging.setupFee	number \| null	Per-call setup fee (a JSON number)
`graceSeconds`requireddata.charging.graceSeconds	integer \| null	-
`rounding`requireddata.charging.rounding	string \| null	-One of `up`, `nearest`, `down`

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/sell-decks" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme"
}'

Run it here with a test key.

Get a sell deck with its reach and versions

GET/api/v1/switch/sell-decks/{deckId}

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

Parameters

Name	In	Type	Description
`deckId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`version`requireddata.version	integer	-
`status`requireddata.status	string	-One of `draft`, `active`, `superseded`, `archived`
`currency`requireddata.currency	string	-max 3 chars
`isSystemDefault`requireddata.isSystemDefault	boolean	-
`defaultRatePerUnit`requireddata.defaultRatePerUnit	number \| null	Catch-all price for destinations the deck does not list (a JSON number)
`charging`requireddata.charging	object	-
`minimumDurationSeconds`requireddata.charging.minimumDurationSeconds	integer \| null	-
`firstIntervalSeconds`requireddata.charging.firstIntervalSeconds	integer \| null	-
`subsequentIntervalSeconds`requireddata.charging.subsequentIntervalSeconds	integer \| null	-
`setupFee`requireddata.charging.setupFee	number \| null	Per-call setup fee (a JSON number)
`graceSeconds`requireddata.charging.graceSeconds	integer \| null	-
`rounding`requireddata.charging.rounding	string \| null	-One of `up`, `nearest`, `down`
`effectiveFrom`requireddata.effectiveFrom	string (date-time) \| null	ISO-8601 timestamp (UTC)
`notes`requireddata.notes	string \| null	-
`supersedesId`requireddata.supersedesId	string (uuid) \| null	-
`approvedAt`requireddata.approvedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`activeRates`requireddata.activeRates	integer	-
`customersDefaultingToIt`requireddata.customersDefaultingToIt	object[]	-
`id`requireddata.customersDefaultingToIt[].id	string (uuid)	-
`label`requireddata.customersDefaultingToIt[].label	string \| null	-
`trunksNamingIt`requireddata.trunksNamingIt	object[]	-
`id`requireddata.trunksNamingIt[].id	string (uuid)	-
`label`requireddata.trunksNamingIt[].label	string \| null	-
`subAccountId`requireddata.trunksNamingIt[].subAccountId	string (uuid)	-
`versions`requireddata.versions	object[]	-
`id`requireddata.versions[].id	string (uuid)	-
`version`requireddata.versions[].version	integer	-
`status`requireddata.versions[].status	string	-One of `draft`, `active`, `superseded`, `archived`
`effectiveFrom`requireddata.versions[].effectiveFrom	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.versions[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Update a sell deck's name, notes or charging profile

PATCH/api/v1/switch/sell-decks/{deckId}

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

Superseded and archived decks cannot change. Changing the charging profile of an ACTIVE deck reprices every trunk on it from the next call, and is logged as a warning.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`deckId`required	path	string	-

Request body (application/json)

Field	Type	Description
`name`	string	-max 160 chars
`currency`	string	-max 3 chars
`defaultRatePerUnit`	number \| string \| null	Catch-all price; null or "" clears it
`minimumDurationSeconds`	integer \| null	-0 to 3600
`firstIntervalSeconds`	integer \| null	Set together with subsequentIntervalSeconds, or neither1 to 3600
`subsequentIntervalSeconds`	integer \| null	-1 to 3600
`setupFee`	number \| string \| null	-
`graceSeconds`	integer \| null	-0 to 120
`rounding`	string \| null	-One of `up`, `nearest`, `down`
`notes`	string \| null	-
`effectiveFrom`	string \| null	ISO timestamp

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchSellDeck, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/sell-decks/<deckId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "currency": "USD"
}'

Run it here with a test key.

List the prices in a sell deck

GET/api/v1/switch/sell-decks/{deckId}/rates

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

Parameters

Name	In	Type	Description
`deckId`required	path	string	-
`search`	query	string	Prefix search (digits)
`limit`	query	integer	Default 100, max 1000
`offset`	query	integer	-

Response 200

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string (uuid)	-
`deckId`requireddata.rows[].deckId	string (uuid)	-
`prefix`requireddata.rows[].prefix	string	-
`originPrefix`requireddata.rows[].originPrefix	string	"" = any origin
`ratePerUnit`requireddata.rows[].ratePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.rows[].billingIncrement	string \| null	null = inherit the trunk or customer default
`destinationName`requireddata.rows[].destinationName	string \| null	-
`createdAt`requireddata.rows[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.rows[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`total`requireddata.total	integer	-
`limit`requireddata.limit	integer	-
`offset`requireddata.offset	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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Replace the prices in a draft sell deck

POST/api/v1/switch/sell-decks/{deckId}/rates

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

Up to 200,000 rows, replacing whatever the draft held (last row wins per prefix and origin). Published decks are never overwritten; open a new version instead.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`deckId`required	path	string	-

Request body (application/json)

Field	Type	Description
`rows`required	object[]	-
`prefix`requiredrows[].prefix	string	-max 24 chars
`rate`requiredrows[].rate	number \| string	A blank is refused; 0 is a real price
`origin`rows[].origin	string \| null	-max 24 chars
`billingIncrement`rows[].billingIncrement	string \| null	"first/subsequent", e.g. 60/60; anything else is stored as inherit

Response 200

Field	Type	Description
`data`required	object	-
`loaded`requireddata.loaded	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/sell-decks/<deckId>/rates" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "prefix": "44",
      "rate": 1
    }
  ]
}'

Run it here with a test key.

Open a new draft version of a sell deck

POST/api/v1/switch/sell-decks/{deckId}/versions

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

Copies the deck's charging profile and prices into version n+1 as a draft. Publishing it is what moves prices.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`deckId`required	path	string	-

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`version`requireddata.version	integer	-
`status`requireddata.status	string	-One of `draft`, `active`, `superseded`, `archived`
`currency`requireddata.currency	string	-max 3 chars
`isSystemDefault`requireddata.isSystemDefault	boolean	-
`defaultRatePerUnit`requireddata.defaultRatePerUnit	number \| null	Catch-all price for destinations the deck does not list (a JSON number)
`charging`requireddata.charging	object	-
`minimumDurationSeconds`requireddata.charging.minimumDurationSeconds	integer \| null	-
`firstIntervalSeconds`requireddata.charging.firstIntervalSeconds	integer \| null	-
`subsequentIntervalSeconds`requireddata.charging.subsequentIntervalSeconds	integer \| null	-
`setupFee`requireddata.charging.setupFee	number \| null	Per-call setup fee (a JSON number)
`graceSeconds`requireddata.charging.graceSeconds	integer \| null	-
`rounding`requireddata.charging.rounding	string \| null	-One of `up`, `nearest`, `down`
`copiedRates`requireddata.copiedRates	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.

Publish a sell deck (preview first, then confirm)

POST/api/v1/switch/sell-decks/{deckId}/publish

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

Without confirm: true this only reports whose prices would change and writes nothing. With it, the deck becomes active, the previous version is superseded, and its prices are written onto every trunk that resolves to it, from the next call onward.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`deckId`required	path	string	-

Request body (application/json)

Field	Type	Description
`confirm`	boolean	-

Response 200

Field	Type	Description
`data`required	object	-
`published`data.published	boolean	-One of `true`
`wouldChange`data.wouldChange	object	-
`rates`requireddata.wouldChange.rates	integer	-
`trunks`requireddata.wouldChange.trunks	integer	-
`message`requireddata.wouldChange.message	string	-
`trunks`data.trunks	integer	-
`rowsWritten`data.rowsWritten	integer	-
`rowsSuperseded`data.rowsSuperseded	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/sell-decks/<deckId>/publish" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm": true
}'

Run it here with a test key.

Set or clear the system default sell deck

POST/api/v1/switch/sell-decks/system-default

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

The deck used by trunks set to "system default". Only an active deck qualifies; send deckId: null to clear it.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

Field	Type	Description
`deckId`	string (uuid) \| null	-

Response 200

Field	Type	Description
`data`required	object	-
`systemDefaultDeckId`requireddata.systemDefaultDeckId	string (uuid) \| null	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/sell-decks/system-default" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "deckId": "<deckId>"
}'

Run it here with a test key.

Look up the buy and sell price for a destination

GET/api/v1/switch/rate-lookup

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

Read-only. The buy side needs a supplier trunkId; the sell side is resolved for the customer or customer trunk named (or your own sell rates). Each side is a rating outcome, so "no matching rate" is distinguishable from a price of 0. margin is present only when both sides are rated.

Parameters

Name	In	Type	Description
`destination`required	query	string	-
`trunkId`	query	string (uuid)	Supplier trunk for the buy side
`customerId`	query	string (uuid)	-
`customerTrunkId`	query	string (uuid)	-
`origin`	query	string	Caller number, for origin-based rates

Response 200

Field	Type	Description
`data`required	object	-
`destination`requireddata.destination	string	-
`origin`requireddata.origin	string \| null	-
`buy`requireddata.buy	object \| null	null when no trunkId was givenSame fields as SwitchRatingOutcome, shown earlier on this page.
`sell`requireddata.sell	object	A price, or the reason there is none. Only kind = rated carries a rate.Same fields as SwitchRatingOutcome, shown earlier on this page.
`margin`requireddata.margin	number \| null	sell minus buy per minute, a JSON number; null unless both are rated
`at`requireddata.at	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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

List your operator sell rates

GET/api/v1/switch/sell-rates

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

The operator-wide A-Z sell rates, by prefix.

Parameters

Name	In	Type	Description
`search`	query	string	Prefix search (digits)
`limit`	query	integer	Default 100, max 1000
`offset`	query	integer	-

Response 200

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string (uuid)	-
`prefix`requireddata.rows[].prefix	string	-
`originPrefix`requireddata.rows[].originPrefix	string	"" = any origin
`ratePerUnit`requireddata.rows[].ratePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.rows[].billingIncrement	string \| null	null = inherit the trunk default
`createdAt`requireddata.rows[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.rows[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`total`requireddata.total	integer	-
`limit`requireddata.limit	integer	-
`offset`requireddata.offset	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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Add or update one operator sell rate

POST/api/v1/switch/sell-rates

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

Upserts by prefix and origin. Emits the sell_rate.changed webhook.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

Field	Type	Description
`prefix`required	string	-max 24 chars
`rate`required	number	Price per minute, as a JSON numbermin 0
`origin`	string	-max 24 chars
`billingIncrement`	string	e.g. 60/60 or 1/1; omit to inherit the trunk defaultmax 10 chars

Response 201

Field	Type	Description
`data`required	object	Same fields as SwitchSellRate, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/sell-rates" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prefix": "44",
  "rate": 1
}'

Run it here with a test key.

Add or update operator sell rates in bulk

POST/api/v1/switch/sell-rates/bulk

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

Up to 50,000 rows in one transaction; the last row wins per prefix and origin. Emits one sell_rate.changed webhook.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

Field	Type	Description
`rows`required	object[]	-
`prefix`requiredrows[].prefix	string	-max 24 chars
`rate`requiredrows[].rate	number	Price per minute, as a JSON numbermin 0
`origin`rows[].origin	string	-max 24 chars
`billingIncrement`rows[].billingIncrement	string	e.g. 60/60 or 1/1; omit to inherit the trunk defaultmax 10 chars

Response 200

Field	Type	Description
`data`required	object	-
`applied`requireddata.applied	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/sell-rates/bulk" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "prefix": "44",
      "rate": 1
    }
  ]
}'

Run it here with a test key.

Delete an operator sell rate

DELETE/api/v1/switch/sell-rates/{id}

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

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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.

Clear operator sell rates

POST/api/v1/switch/sell-rates/clear

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

Deletes the listed prefixes, or EVERY operator sell rate when prefixes is omitted.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (application/json)

Field	Type	Description
`prefixes`	string[]	-

Response 200

Field	Type	Description
`data`required	object	-
`deleted`requireddata.deleted	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/sell-rates/clear" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prefixes": [
    "<prefixe>"
  ]
}'

Run it here with a test key.

Read a rate sheet and propose a column mapping

POST/api/v1/switch/rate-decks/parse

Access: API key. Scoped keys need switch:manage.
Rate limit: 10 requests per minute

Step 1 of the guided import into any switch deck (your own sell deck, a supplier trunk or a customer trunk). Returns the detected columns, a sample and warnings. Writes nothing.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (multipart/form-data)

Field	Type	Description
`targetKind`required	string	-One of `operator`, `supplier`, `customer`
`targetId`	string (uuid)	-
`targetTrunkId`	string (uuid)	-
`defaultIncrement`	string	-
`changeMode`	string	-One of `amendment`, `full_replacement`
`effectiveFrom`	string (date-time)	-
`timezone`	string	-max 64 chars
`fxRate`	string	Units of USD per 1 unit of the sheet currency; required to apply a non-USD sheet
`replace`	string	Legacy form of changeMode=full_replacementOne of `true`, `false`
`mapping`	string	The confirmed column mapping from the parse step, as JSON text
`file`required	string	The rate sheet (CSV or XLSX), sent LAST

Response 200

Field	Type	Description
`data`required	object	-
`targetLabel`requireddata.targetLabel	string	-
`mapping`requireddata.mapping	object	Detected column mapping; send it back (as JSON) on diff and apply
`rawSample`requireddata.rawSample	any[][]	The first 8 raw rows
`previewRows`requireddata.previewRows	object[]	Up to 50 parsed rows
`rowCount`requireddata.rowCount	integer	-
`warnings`requireddata.warnings	object[]	-
`currency`requireddata.currency	string	-
`summary`requireddata.summary	object	-
`overLimit`requireddata.overLimit	boolean	-
`maxRows`requireddata.maxRows	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/rate-decks/parse" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -F "targetKind=..." \
  -F "targetId=..." \
  -F "targetTrunkId=..." \
  -F "defaultIncrement=..." \
  -F "changeMode=..." \
  -F "effectiveFrom=..." \
  -F "timezone=..." \
  -F "fxRate=..." \
  -F "replace=..." \
  -F "mapping=..." \
  -F "file=@rates.csv"

Run it here with a test key.

Preview what a rate sheet would change

POST/api/v1/switch/rate-decks/diff

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

Dry run: compares the sheet with the target deck's live rows and reports added, changed and removed prefixes. changeMode decides whether omitted prefixes stop pricing. Writes nothing.

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (multipart/form-data)

Field	Type	Description
`targetKind`required	string	-One of `operator`, `supplier`, `customer`
`targetId`	string (uuid)	-
`targetTrunkId`	string (uuid)	-
`defaultIncrement`	string	-
`changeMode`	string	-One of `amendment`, `full_replacement`
`effectiveFrom`	string (date-time)	-
`timezone`	string	-max 64 chars
`fxRate`	string	Units of USD per 1 unit of the sheet currency; required to apply a non-USD sheet
`replace`	string	Legacy form of changeMode=full_replacementOne of `true`, `false`
`mapping`	string	The confirmed column mapping from the parse step, as JSON text
`file`required	string	The rate sheet (CSV or XLSX), sent LAST

Response 200

Field	Type	Description
`data`required	object	-
`targetLabel`requireddata.targetLabel	string	-
`rowCount`data.rowCount	integer	-
`currency`requireddata.currency	string	-
`warnings`requireddata.warnings	object[]	-
`diff`data.diff	object	What a change does to live pricing, with the biggest moversSame fields as SwitchRateDeckDiff, shown earlier on this page.
`applied`data.applied	integer	Rows written (apply) or queued (scheduled apply)
`replaced`data.replaced	boolean	-
`scheduled`data.scheduled	boolean	Present when a future effectiveFrom queued the sheetOne of `true`
`effectiveFrom`data.effectiveFrom	string	-
`originScoped`data.originScoped	integer	Origin-scoped live rows a sheet cannot express, counted not changed
`overLimit`data.overLimit	boolean	-
`maxRows`data.maxRows	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/rate-decks/diff" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -F "targetKind=..." \
  -F "targetId=..." \
  -F "targetTrunkId=..." \
  -F "defaultIncrement=..." \
  -F "changeMode=..." \
  -F "effectiveFrom=..." \
  -F "timezone=..." \
  -F "fxRate=..." \
  -F "replace=..." \
  -F "mapping=..." \
  -F "file=@rates.csv"

Run it here with a test key.

Apply a rate sheet to a switch deck

POST/api/v1/switch/rate-decks/apply

Access: API key. Scoped keys need switch:manage.
Rate limit: 20 requests per minute

Writes the sheet in one transaction and reports what landed. A non-USD sheet needs fxRate. For supplier decks a future effectiveFrom queues the change for that moment instead (the result then has scheduled: true).

Test keys: refused with 403 TEST_KEY_NOT_ALLOWED. The Switch has no test mode, so a change always applies to your live configuration. Test keys can still read Switch data.

Request body (multipart/form-data)

Field	Type	Description
`targetKind`required	string	-One of `operator`, `supplier`, `customer`
`targetId`	string (uuid)	-
`targetTrunkId`	string (uuid)	-
`defaultIncrement`	string	-
`changeMode`	string	-One of `amendment`, `full_replacement`
`effectiveFrom`	string (date-time)	-
`timezone`	string	-max 64 chars
`fxRate`	string	Units of USD per 1 unit of the sheet currency; required to apply a non-USD sheet
`replace`	string	Legacy form of changeMode=full_replacementOne of `true`, `false`
`mapping`	string	The confirmed column mapping from the parse step, as JSON text
`file`required	string	The rate sheet (CSV or XLSX), sent LAST

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchDeckSheetResult, shown earlier on this page.

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.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.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
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/switch/rate-decks/apply" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -F "targetKind=..." \
  -F "targetId=..." \
  -F "targetTrunkId=..." \
  -F "defaultIncrement=..." \
  -F "changeMode=..." \
  -F "effectiveFrom=..." \
  -F "timezone=..." \
  -F "fxRate=..." \
  -F "replace=..." \
  -F "mapping=..." \
  -F "file=@rates.csv"

Run it here with a test key.