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

destinationrequired
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

FieldDescription

datarequired
object
atrequired
string (date-time) · data.at
ISO-8601 timestamp (UTC)
inputrequired
object · data.input
The destination, routed number, origin, customer, trunk and reference call length used
basisrequired
object · data.basis
resolvedrequired
boolean · data.basis.resolved
detailrequired
string · data.basis.detail
routingKindrequired
string · data.basis.routingKind
One of fixed, group, dialplan, none
routingNamerequired
string | null · data.basis.routingName
selectionModerequired
string | null · data.basis.selectionMode
maxAttemptsrequired
integer | null · data.basis.maxAttempts
sellrequired
object · data.sell
outcomerequired
object | null · data.sell.outcome
A price, or the reason there is none. Only kind = rated carries a rate.
kindrequired
string · data.sell.outcome.kind
One of rated, no_matching_rate, not_yet_effective, expired, forbidden, rating_failed, not_billable
rate
number · data.sell.outcome.rate
Present when kind = rated. May legitimately be 0.
matchedPrefix
string · data.sell.outcome.matchedPrefix
deckVersion
integer | null · data.sell.outcome.deckVersion
source
string · data.sell.outcome.source
destination
string · data.sell.outcome.destination
effectiveFrom
string · data.sell.outcome.effectiveFrom
expiredAt
string · data.sell.outcome.expiredAt
reason
string · data.sell.outcome.reason
Why it is forbidden or failed
billingRaterequired
number | null · data.sell.billingRate
USD as a JSON number (engine output, up to 6 decimal places)
matchedPrefixrequired
string | null · data.sell.matchedPrefix
billingIncrementrequired
string · data.sell.billingIncrement
suppliersrequired
object[] · data.suppliers
vendorTrunkIdrequired
string (uuid) | null · data.suppliers[].vendorTrunkId
labelrequired
string · data.suppliers[].label
kindrequired
string · data.suppliers[].kind
One of supplier trunk, marketplace route
chainOrdinalrequired
integer | null · data.suppliers[].chainOrdinal
Attempt position in the failover chain; null if past the attempt ceiling
outcomerequired
object | null · data.suppliers[].outcome
A price, or the reason there is none. Only kind = rated carries a rate.Same fields as SwitchRatingOutcome, shown earlier on this page.
billingRaterequired
number | null · data.suppliers[].billingRate
USD as a JSON number (engine output, up to 6 decimal places)
sourcerequired
string · data.suppliers[].source
One of supplier deck, trunk default, marketplace listing, unpriced
matchedPrefixrequired
string | null · data.suppliers[].matchedPrefix
deckIdrequired
string (uuid) | null · data.suppliers[].deckId
deckVersionrequired
integer | null · data.suppliers[].deckVersion
billingIncrementrequired
string · data.suppliers[].billingIncrement
excludedrequired
object | null · data.suppliers[].excluded
stagerequired
string · data.suppliers[].excluded.stage
reasonrequired
string · data.suppliers[].excluded.reason
detailrequired
string · data.suppliers[].excluded.detail
selectedrequired
object | null · data.selected
vendorTrunkIdrequired
string (uuid) | null · data.selected.vendorTrunkId
labelrequired
string · data.selected.label
kindrequired
string · data.selected.kind
One of supplier trunk, marketplace route
chainOrdinalrequired
integer | null · data.selected.chainOrdinal
Attempt position in the failover chain; null if past the attempt ceiling
outcomerequired
object | null · data.selected.outcome
A price, or the reason there is none. Only kind = rated carries a rate.Same fields as SwitchRatingOutcome, shown earlier on this page.
billingRaterequired
number | null · data.selected.billingRate
USD as a JSON number (engine output, up to 6 decimal places)
sourcerequired
string · data.selected.source
One of supplier deck, trunk default, marketplace listing, unpriced
matchedPrefixrequired
string | null · data.selected.matchedPrefix
deckIdrequired
string (uuid) | null · data.selected.deckId
deckVersionrequired
integer | null · data.selected.deckVersion
billingIncrementrequired
string · data.selected.billingIncrement
excludedrequired
object | null · data.selected.excluded
stagerequired
string · data.selected.excluded.stage
reasonrequired
string · data.selected.excluded.reason
detailrequired
string · data.selected.excluded.detail
configuredMarginrequired
object · data.configuredMargin
kindrequired
string · data.configuredMargin.kind
One of configured_estimate
perMinuterequired
number | null · data.configuredMargin.perMinute
USD as a JSON number (engine output, up to 6 decimal places)
perMinutePctrequired
number | null · data.configuredMargin.perMinutePct
referenceCallrequired
object | null · data.configuredMargin.referenceCall
Revenue, cost and margin of a call of the reference length, increment-aware (JSON numbers)
rangerequired
object | null · data.configuredMargin.range
explainrequired
object[] · data.configuredMargin.explain
labelrequired
string · data.configuredMargin.explain[].label
valuerequired
string · data.configuredMargin.explain[].value
note
string · data.configuredMargin.explain[].note
source
string · data.configuredMargin.explain[].source
traceIdrequired
string (uuid) · data.traceId
The route trace this analysis ran on
verdictrequired
object · data.verdict
sideEffectsrequired
object · data.sideEffects
createdCdrrequired
boolean · data.sideEffects.createdCdr
One of false
movedBalancerequired
boolean · data.sideEffects.movedBalance
One of false
consumedCapacityrequired
boolean · data.sideEffects.consumedCapacity
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

customerId
query · string (uuid)
customerTrunkId
query · string (uuid)

Response 200

FieldDescription

datarequired
object
suppliersrequired
object[] · data.suppliers
vendorTrunkIdrequired
string (uuid) · data.suppliers[].vendorTrunkId
labelrequired
string · data.suppliers[].label
statusrequired
string · data.suppliers[].status
viarequired
object[] · data.suppliers[].via
sourcerequired
string · data.suppliers[].via[].source
One of fixed target, route group, failover group, dialplan rule
groupIdrequired
string (uuid) | null · data.suppliers[].via[].groupId
groupNamerequired
string | null · data.suppliers[].via[].groupName
prefixrequired
string | null · data.suppliers[].via[].prefix
priorityrequired
integer | null · data.suppliers[].via[].priority
defaultRatePerUnitrequired
money | null · data.suppliers[].defaultRatePerUnit
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".
activeRateRowsrequired
integer · data.suppliers[].activeRateRows
unpricedrequired
boolean · data.suppliers[].unpriced
True when the trunk has no rates and no default: calls to it cannot be costed
billingIncrementrequired
string · data.suppliers[].billingIncrement
routingrequired
object · data.routing
kindrequired
string · data.routing.kind
One of fixed, group, dialplan, none
namerequired
string | null · data.routing.name
selectionModerequired
string | null · data.routing.selectionMode
maxAttemptsrequired
integer | null · data.routing.maxAttempts
trunkIdsrequired
string (uuid)[] · data.routing.trunkIds
ambiguousrequired
string | null · data.ambiguous

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

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

FieldDescription

datarequired
object
kindrequired
string · data.kind
One of realised_actual
windowrequired
object · data.window
fromrequired
string · data.window.from
torequired
string · data.window.to
labelrequired
string · data.window.label
basisrequired
object · data.basis
answerrequired
object · data.answer
revenuerequired
object · data.revenue
customerChargesrequired
number · data.revenue.customerCharges
USD as a JSON number (engine output, up to 6 decimal places)
platformFeerequired
number · data.revenue.platformFee
USD as a JSON number (engine output, up to 6 decimal places)
feeCertaintyrequired
string · data.revenue.feeCertainty
One of exact, upper_bound
operatorRevenuerequired
number · data.revenue.operatorRevenue
USD as a JSON number (engine output, up to 6 decimal places)
costrequired
object · data.cost
bookedrequired
number · data.cost.booked
USD as a JSON number (engine output, up to 6 decimal places)
unbookedAttemptCostrequired
number · data.cost.unbookedAttemptCost
USD as a JSON number (engine output, up to 6 decimal places)
unbookedAttemptsrequired
integer · data.cost.unbookedAttempts
totalrequired
number · data.cost.total
USD as a JSON number (engine output, up to 6 decimal places)
grossrequired
number · data.gross
USD as a JSON number (engine output, up to 6 decimal places)
grossPctrequired
number | null · data.grossPct
exposurerequired
object · data.exposure

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

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

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
sessionKeyrequired
string · data.rows[].sessionKey
callUuidrequired
string | null · data.rows[].callUuid
atrequired
string (date-time) · data.rows[].at
ISO-8601 timestamp (UTC)
destinationrequired
string | null · data.rows[].destination
destinationNamerequired
string | null · data.rows[].destinationName
customerTrunkIdrequired
string (uuid) | null · data.rows[].customerTrunkId
statusrequired
string | null · data.rows[].status
durationSecondsrequired
integer · data.rows[].durationSeconds
billedSecondsrequired
integer | null · data.rows[].billedSeconds
billingIncrementrequired
string | null · data.rows[].billingIncrement
sellRaterequired
number | null · data.rows[].sellRate
USD as a JSON number (engine output, up to 6 decimal places)
chargerequired
number · data.rows[].charge
USD as a JSON number (engine output, up to 6 decimal places)
bookedCostrequired
number · data.rows[].bookedCost
USD as a JSON number (engine output, up to 6 decimal places)
attemptsrequired
object[] · data.rows[].attempts
ordinalrequired
integer · data.rows[].attempts[].ordinal
supplierrequired
string | null · data.rows[].attempts[].supplier
vendorTrunkIdrequired
string (uuid) | null · data.rows[].attempts[].vendorTrunkId
outcomerequired
string · data.rows[].attempts[].outcome
sipStatusrequired
integer | null · data.rows[].attempts[].sipStatus
wonrequired
boolean · data.rows[].attempts[].won
answeredSecondsrequired
integer | null · data.rows[].attempts[].answeredSeconds
buyRaterequired
number | null · data.rows[].attempts[].buyRate
USD as a JSON number (engine output, up to 6 decimal places)
costBasisrequired
string · data.rows[].attempts[].costBasis
One of booked, derived, none
derivedCostrequired
number | null · data.rows[].attempts[].derivedCost
USD as a JSON number (engine output, up to 6 decimal places)
attemptCostrequired
number · data.rows[].attemptCost
USD as a JSON number (engine output, up to 6 decimal places)
marginrequired
number · data.rows[].margin
USD as a JSON number (engine output, up to 6 decimal places)
flagsrequired
string[] · data.rows[].flags
totalrequired
integer · data.total
limitrequired
integer · data.limit
offsetrequired
integer · data.offset

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

callUuidrequired
path · string

Response 200

FieldDescription

datarequired
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

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

FieldDescription

datarequired
object
decksrequired
object[] · data.decks
idrequired
string (uuid) · data.decks[].id
supplierIdrequired
string (uuid) | null · data.decks[].supplierId
The provider who sent it; null for a deck recorded before its provider was
namerequired
string · data.decks[].name
currencyrequired
string · data.decks[].currency
max 3 chars
versionrequired
integer · data.decks[].version
statusrequired
string · data.decks[].status
One of draft, uploaded, invalid, validated, pending_approval, scheduled, active, expired, rolled_back
effectiveFromrequired
string (date-time) | null · data.decks[].effectiveFrom
ISO-8601 timestamp (UTC)
expiresAtrequired
string (date-time) | null · data.decks[].expiresAt
ISO-8601 timestamp (UTC)
sourcerequired
string | null · data.decks[].source
One of portal, csv, api, email, sftp
sourceRefrequired
string | null · data.decks[].sourceRef
approvedAtrequired
string (date-time) | null · data.decks[].approvedAt
ISO-8601 timestamp (UTC)
validationrequired
object | null · data.decks[].validation
The last validation result; null before the deck is validated
checkedAtrequired
string · data.decks[].validation.checkedAt
rowsrequired
integer · data.decks[].validation.rows
destinationsrequired
integer · data.decks[].validation.destinations
errorsrequired
object[] · data.decks[].validation.errors
warningsrequired
object[] · data.decks[].validation.warnings
maxIncreasePct
number · data.decks[].validation.maxIncreasePct
supersedesIdrequired
string (uuid) | null · data.decks[].supersedesId
rolledBackAtrequired
string (date-time) | null · data.decks[].rolledBackAt
ISO-8601 timestamp (UTC)
notesrequired
string | null · data.decks[].notes
createdAtrequired
string (date-time) · data.decks[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.decks[].updatedAt
ISO-8601 timestamp (UTC)
rowCountrequired
integer · data.decks[].rowCount
trunksrequired
object[] · data.decks[].trunks
Supplier trunks the deck prices
idrequired
string (uuid) · data.decks[].trunks[].id
labelrequired
string · data.decks[].trunks[].label
mutablerequired
boolean · data.decks[].mutable
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)

FieldDescription

supplierId
string (uuid) | null
namerequired
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

FieldDescription

datarequired
object
Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Response 200

FieldDescription

datarequired
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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
namerequired
string · data.name
versionsrequired
object[] · data.versions
idrequired
string (uuid) · data.versions[].id
supplierIdrequired
string (uuid) | null · data.versions[].supplierId
The provider who sent it; null for a deck recorded before its provider was
namerequired
string · data.versions[].name
currencyrequired
string · data.versions[].currency
max 3 chars
versionrequired
integer · data.versions[].version
statusrequired
string · data.versions[].status
One of draft, uploaded, invalid, validated, pending_approval, scheduled, active, expired, rolled_back
effectiveFromrequired
string (date-time) | null · data.versions[].effectiveFrom
ISO-8601 timestamp (UTC)
expiresAtrequired
string (date-time) | null · data.versions[].expiresAt
ISO-8601 timestamp (UTC)
sourcerequired
string | null · data.versions[].source
One of portal, csv, api, email, sftp
sourceRefrequired
string | null · data.versions[].sourceRef
approvedAtrequired
string (date-time) | null · data.versions[].approvedAt
ISO-8601 timestamp (UTC)
validationrequired
object | null · data.versions[].validation
The last validation result; null before the deck is validated
checkedAtrequired
string · data.versions[].validation.checkedAt
rowsrequired
integer · data.versions[].validation.rows
destinationsrequired
integer · data.versions[].validation.destinations
errorsrequired
object[] · data.versions[].validation.errors
warningsrequired
object[] · data.versions[].validation.warnings
maxIncreasePct
number · data.versions[].validation.maxIncreasePct
supersedesIdrequired
string (uuid) | null · data.versions[].supersedesId
rolledBackAtrequired
string (date-time) | null · data.versions[].rolledBackAt
ISO-8601 timestamp (UTC)
notesrequired
string | null · data.versions[].notes
createdAtrequired
string (date-time) · data.versions[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.versions[].updatedAt
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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deckIdrequired
string (uuid) · data.deckId
namerequired
string · data.name
versionrequired
integer · data.version
statusrequired
string · data.status
One of draft, uploaded, invalid, validated, pending_approval, scheduled, active, expired, rolled_back
effectiveFromrequired
string (date-time) | null · data.effectiveFrom
ISO-8601 timestamp (UTC)
trunksrequired
object[] · data.trunks
trunkIdrequired
string (uuid) · data.trunks[].trunkId
labelrequired
string · data.trunks[].label
diffrequired
object · data.trunks[].diff
What a change does to live pricing, with the biggest movers
removalModerequired
string · data.trunks[].diff.removalMode
One of merge, replace
changeModerequired
string · data.trunks[].diff.changeMode
One of amendment, full_replacement
liverequired
integer · data.trunks[].diff.live
Prefixes priced on the live deck now
incomingrequired
integer · data.trunks[].diff.incoming
Prefixes the new rows price
addedrequired
integer · data.trunks[].diff.added
changedrequired
integer · data.trunks[].diff.changed
rateChangedrequired
integer · data.trunks[].diff.rateChanged
incrementOnlyrequired
integer · data.trunks[].diff.incrementOnly
Changed rows where only the billing increment moved
unchangedrequired
integer · data.trunks[].diff.unchanged
removedrequired
integer · data.trunks[].diff.removed
Live prefixes the new rows do not mention
originScopedrequired
integer · data.trunks[].originScoped

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

idrequired
path · string

Request body (application/json)

FieldDescription

trunkIdsrequired
string (uuid)[]

Response 200

FieldDescription

datarequired
object
Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Request body (application/json)

FieldDescription

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

Response 200

FieldDescription

datarequired
object
Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Response 201

FieldDescription

datarequired
object
Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Request body (application/json)

FieldDescription

effectiveFrom
string | null
max 40 chars

Response 200

FieldDescription

datarequired
object
Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
Same fields as SwitchRateDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
supplierIdrequired
string (uuid) | null · data.supplierId
The provider who sent it; null for a deck recorded before its provider was
namerequired
string · data.name
currencyrequired
string · data.currency
max 3 chars
versionrequired
integer · data.version
statusrequired
string · data.status
One of draft, uploaded, invalid, validated, pending_approval, scheduled, active, expired, rolled_back
effectiveFromrequired
string (date-time) | null · data.effectiveFrom
ISO-8601 timestamp (UTC)
expiresAtrequired
string (date-time) | null · data.expiresAt
ISO-8601 timestamp (UTC)
sourcerequired
string | null · data.source
One of portal, csv, api, email, sftp
sourceRefrequired
string | null · data.sourceRef
approvedAtrequired
string (date-time) | null · data.approvedAt
ISO-8601 timestamp (UTC)
validationrequired
object | null · data.validation
The last validation result; null before the deck is validated
checkedAtrequired
string · data.validation.checkedAt
rowsrequired
integer · data.validation.rows
destinationsrequired
integer · data.validation.destinations
errorsrequired
object[] · data.validation.errors
warningsrequired
object[] · data.validation.warnings
maxIncreasePct
number · data.validation.maxIncreasePct
supersedesIdrequired
string (uuid) | null · data.supersedesId
rolledBackAtrequired
string (date-time) | null · data.rolledBackAt
ISO-8601 timestamp (UTC)
notesrequired
string | null · data.notes
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
rowCountrequired
integer · data.rowCount
trunksrequired
object[] · data.trunks
Supplier trunks the deck prices
idrequired
string (uuid) · data.trunks[].id
labelrequired
string · data.trunks[].label
mutablerequired
boolean · data.mutable
Whether rows can still be edited
restoredDeckIdrequired
string (uuid) | null · data.restoredDeckId

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

FieldDescription

datarequired
object
operatorrequired
object · data.operator
markupPctrequired
number | null · data.operator.markupPct
dailySpendCaprequired
number | null · data.operator.dailySpendCap
USD, a JSON number
maxConcurrentCallsrequired
number | null · data.operator.maxConcurrentCalls
billingIncrementrequired
string | null · data.operator.billingIncrement
platformrequired
object · data.platform
billingIncrementrequired
string · data.platform.billingIncrement
One of 1/1
maxConcurrentCallsrequired
enum | null · data.platform.maxConcurrentCalls
One of null
maxCpsrequired
enum | null · data.platform.maxCps
One of null
chainsrequired
object · data.chains
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

status
query · string
One of draft, active, superseded, archived

Response 200

FieldDescription

datarequired
object
decksrequired
object[] · data.decks
idrequired
string (uuid) · data.decks[].id
namerequired
string · data.decks[].name
versionrequired
integer · data.decks[].version
statusrequired
string · data.decks[].status
One of draft, active, superseded, archived
currencyrequired
string · data.decks[].currency
max 3 chars
isSystemDefaultrequired
boolean · data.decks[].isSystemDefault
defaultRatePerUnitrequired
number | null · data.decks[].defaultRatePerUnit
Catch-all price for destinations the deck does not list (a JSON number)
chargingrequired
object · data.decks[].charging
minimumDurationSecondsrequired
integer | null · data.decks[].charging.minimumDurationSeconds
firstIntervalSecondsrequired
integer | null · data.decks[].charging.firstIntervalSeconds
subsequentIntervalSecondsrequired
integer | null · data.decks[].charging.subsequentIntervalSeconds
setupFeerequired
number | null · data.decks[].charging.setupFee
Per-call setup fee (a JSON number)
graceSecondsrequired
integer | null · data.decks[].charging.graceSeconds
roundingrequired
string | null · data.decks[].charging.rounding
One of up, nearest, down
effectiveFromrequired
string (date-time) | null · data.decks[].effectiveFrom
ISO-8601 timestamp (UTC)
notesrequired
string | null · data.decks[].notes
updatedAtrequired
string (date-time) · data.decks[].updatedAt
ISO-8601 timestamp (UTC)
activeRatesrequired
integer · data.decks[].activeRates
Rows in the deck
customersOnItrequired
integer · data.decks[].customersOnIt
Customers whose default deck this is
trunksNamingItrequired
integer · data.decks[].trunksNamingIt
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)

FieldDescription

namerequired
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

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
versionrequired
integer · data.version
statusrequired
string · data.status
One of draft, active, superseded, archived
currencyrequired
string · data.currency
max 3 chars
isSystemDefaultrequired
boolean · data.isSystemDefault
defaultRatePerUnitrequired
number | null · data.defaultRatePerUnit
Catch-all price for destinations the deck does not list (a JSON number)
chargingrequired
object · data.charging
minimumDurationSecondsrequired
integer | null · data.charging.minimumDurationSeconds
firstIntervalSecondsrequired
integer | null · data.charging.firstIntervalSeconds
subsequentIntervalSecondsrequired
integer | null · data.charging.subsequentIntervalSeconds
setupFeerequired
number | null · data.charging.setupFee
Per-call setup fee (a JSON number)
graceSecondsrequired
integer | null · data.charging.graceSeconds
roundingrequired
string | null · data.charging.rounding
One of up, nearest, down

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

deckIdrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
versionrequired
integer · data.version
statusrequired
string · data.status
One of draft, active, superseded, archived
currencyrequired
string · data.currency
max 3 chars
isSystemDefaultrequired
boolean · data.isSystemDefault
defaultRatePerUnitrequired
number | null · data.defaultRatePerUnit
Catch-all price for destinations the deck does not list (a JSON number)
chargingrequired
object · data.charging
minimumDurationSecondsrequired
integer | null · data.charging.minimumDurationSeconds
firstIntervalSecondsrequired
integer | null · data.charging.firstIntervalSeconds
subsequentIntervalSecondsrequired
integer | null · data.charging.subsequentIntervalSeconds
setupFeerequired
number | null · data.charging.setupFee
Per-call setup fee (a JSON number)
graceSecondsrequired
integer | null · data.charging.graceSeconds
roundingrequired
string | null · data.charging.rounding
One of up, nearest, down
effectiveFromrequired
string (date-time) | null · data.effectiveFrom
ISO-8601 timestamp (UTC)
notesrequired
string | null · data.notes
supersedesIdrequired
string (uuid) | null · data.supersedesId
approvedAtrequired
string (date-time) | null · data.approvedAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
activeRatesrequired
integer · data.activeRates
customersDefaultingToItrequired
object[] · data.customersDefaultingToIt
idrequired
string (uuid) · data.customersDefaultingToIt[].id
labelrequired
string | null · data.customersDefaultingToIt[].label
trunksNamingItrequired
object[] · data.trunksNamingIt
idrequired
string (uuid) · data.trunksNamingIt[].id
labelrequired
string | null · data.trunksNamingIt[].label
subAccountIdrequired
string (uuid) · data.trunksNamingIt[].subAccountId
versionsrequired
object[] · data.versions
idrequired
string (uuid) · data.versions[].id
versionrequired
integer · data.versions[].version
statusrequired
string · data.versions[].status
One of draft, active, superseded, archived
effectiveFromrequired
string (date-time) | null · data.versions[].effectiveFrom
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.versions[].createdAt
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

deckIdrequired
path · string

Request body (application/json)

FieldDescription

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

FieldDescription

datarequired
object
Same fields as SwitchSellDeck, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

deckIdrequired
path · string
search
query · string
Prefix search (digits)
limit
query · integer
Default 100, max 1000
offset
query · integer

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string (uuid) · data.rows[].id
deckIdrequired
string (uuid) · data.rows[].deckId
prefixrequired
string · data.rows[].prefix
originPrefixrequired
string · data.rows[].originPrefix
"" = any origin
ratePerUnitrequired
money · data.rows[].ratePerUnit
USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.rows[].billingIncrement
null = inherit the trunk or customer default
destinationNamerequired
string | null · data.rows[].destinationName
createdAtrequired
string (date-time) · data.rows[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.rows[].updatedAt
ISO-8601 timestamp (UTC)
totalrequired
integer · data.total
limitrequired
integer · data.limit
offsetrequired
integer · data.offset

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

deckIdrequired
path · string

Request body (application/json)

FieldDescription

rowsrequired
object[]
prefixrequired
string · rows[].prefix
max 24 chars
raterequired
number | string · rows[].rate
A blank is refused; 0 is a real price
origin
string | null · rows[].origin
max 24 chars
billingIncrement
string | null · rows[].billingIncrement
"first/subsequent", e.g. 60/60; anything else is stored as inherit

Response 200

FieldDescription

datarequired
object
loadedrequired
integer · data.loaded

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

deckIdrequired
path · string

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
versionrequired
integer · data.version
statusrequired
string · data.status
One of draft, active, superseded, archived
currencyrequired
string · data.currency
max 3 chars
isSystemDefaultrequired
boolean · data.isSystemDefault
defaultRatePerUnitrequired
number | null · data.defaultRatePerUnit
Catch-all price for destinations the deck does not list (a JSON number)
chargingrequired
object · data.charging
minimumDurationSecondsrequired
integer | null · data.charging.minimumDurationSeconds
firstIntervalSecondsrequired
integer | null · data.charging.firstIntervalSeconds
subsequentIntervalSecondsrequired
integer | null · data.charging.subsequentIntervalSeconds
setupFeerequired
number | null · data.charging.setupFee
Per-call setup fee (a JSON number)
graceSecondsrequired
integer | null · data.charging.graceSeconds
roundingrequired
string | null · data.charging.rounding
One of up, nearest, down
copiedRatesrequired
integer · data.copiedRates

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

deckIdrequired
path · string

Request body (application/json)

FieldDescription

confirm
boolean

Response 200

FieldDescription

datarequired
object
published
boolean · data.published
One of true
wouldChange
object · data.wouldChange
ratesrequired
integer · data.wouldChange.rates
trunksrequired
integer · data.wouldChange.trunks
messagerequired
string · data.wouldChange.message
trunks
integer · data.trunks
rowsWritten
integer · data.rowsWritten
rowsSuperseded
integer · data.rowsSuperseded

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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)

FieldDescription

deckId
string (uuid) | null

Response 200

FieldDescription

datarequired
object
systemDefaultDeckIdrequired
string (uuid) | null · data.systemDefaultDeckId

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

destinationrequired
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

FieldDescription

datarequired
object
destinationrequired
string · data.destination
originrequired
string | null · data.origin
buyrequired
object | null · data.buy
null when no trunkId was givenSame fields as SwitchRatingOutcome, shown earlier on this page.
sellrequired
object · data.sell
A price, or the reason there is none. Only kind = rated carries a rate.Same fields as SwitchRatingOutcome, shown earlier on this page.
marginrequired
number | null · data.margin
sell minus buy per minute, a JSON number; null unless both are rated
atrequired
string (date-time) · data.at
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

search
query · string
Prefix search (digits)
limit
query · integer
Default 100, max 1000
offset
query · integer

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string (uuid) · data.rows[].id
prefixrequired
string · data.rows[].prefix
originPrefixrequired
string · data.rows[].originPrefix
"" = any origin
ratePerUnitrequired
money · data.rows[].ratePerUnit
USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.rows[].billingIncrement
null = inherit the trunk default
createdAtrequired
string (date-time) · data.rows[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.rows[].updatedAt
ISO-8601 timestamp (UTC)
totalrequired
integer · data.total
limitrequired
integer · data.limit
offsetrequired
integer · data.offset

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)

FieldDescription

prefixrequired
string
max 24 chars
raterequired
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

FieldDescription

datarequired
object
Same fields as SwitchSellRate, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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)

FieldDescription

rowsrequired
object[]
prefixrequired
string · rows[].prefix
max 24 chars
raterequired
number · rows[].rate
Price per minute, as a JSON numbermin 0
origin
string · rows[].origin
max 24 chars
billingIncrement
string · rows[].billingIncrement
e.g. 60/60 or 1/1; omit to inherit the trunk defaultmax 10 chars

Response 200

FieldDescription

datarequired
object
appliedrequired
integer · data.applied

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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)

FieldDescription

prefixes
string[]

Response 200

FieldDescription

datarequired
object
deletedrequired
integer · data.deleted

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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)

FieldDescription

targetKindrequired
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
filerequired
string
The rate sheet (CSV or XLSX), sent LAST

Response 200

FieldDescription

datarequired
object
targetLabelrequired
string · data.targetLabel
mappingrequired
object · data.mapping
Detected column mapping; send it back (as JSON) on diff and apply
rawSamplerequired
any[][] · data.rawSample
The first 8 raw rows
previewRowsrequired
object[] · data.previewRows
Up to 50 parsed rows
rowCountrequired
integer · data.rowCount
warningsrequired
object[] · data.warnings
currencyrequired
string · data.currency
summaryrequired
object · data.summary
overLimitrequired
boolean · data.overLimit
maxRowsrequired
integer · data.maxRows

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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)

FieldDescription

targetKindrequired
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
filerequired
string
The rate sheet (CSV or XLSX), sent LAST

Response 200

FieldDescription

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

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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)

FieldDescription

targetKindrequired
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
filerequired
string
The rate sheet (CSV or XLSX), sent LAST

Response 200

FieldDescription

datarequired
object
Same fields as SwitchDeckSheetResult, shown earlier on this page.

Response 202

FieldDescription

datarequired
object
approvalRequired
boolean · data.approvalRequired
One of true
approvalRequestId
string (uuid) | null · data.approvalRequestId
permission
string · data.permission
expiresAt
string (date-time) · data.expiresAt
message
string · data.message

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.