Switch API reference

Switch: customers

Customers you sell to: accounts, balances, credit, contacts and lifecycle.

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

BrowseSwitch: customers

Get a Switch customer routing assignment

GET/api/v1/switch/customers/{id}/routing

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

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
subAccountIdrequired
string (uuid) · data.subAccountId
customerTrunkId
string (uuid) | null · data.customerTrunkId
dialplanIdrequired
string (uuid) | null · data.dialplanId
routePlanIdrequired
string (uuid) | null · data.routePlanId
failoverRoutePlanIdrequired
string (uuid) | null · data.failoverRoutePlanId
strategyOverriderequired
string | null · data.strategyOverride
directRouteIdrequired
string (uuid) | null · data.directRouteId
directVendorTrunkIdrequired
string (uuid) | null · data.directVendorTrunkId

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.

Assign routing to a Switch customer

POST/api/v1/switch/customers/{id}/routing

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

Sets the dialplan, route group, failover group, strategy or a direct supplier on the customer's first trunk. Use the per-trunk routing endpoint for a specific trunk. Send X-If-Unchanged-Since: <updatedAt you loaded> to have the save refused with 409 STALE_WRITE if someone changed the record since.

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 (uuid)

Request body (application/json)

FieldDescription

dialplanId
string (uuid) | null
routePlanId
string (uuid) | null
failoverRoutePlanId
string (uuid) | null
strategyOverride
string | null
One of cheapest, best_quality, balanced
directRouteId
string (uuid) | null
directVendorTrunkId
string (uuid) | null

Response 200

FieldDescription

datarequired
object
Same fields as SwitchCustomerRoutingAssignment, 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/customers/<id>/routing" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dialplanId": "<dialplanId>",
  "routePlanId": "<routePlanId>"
}'

Run it here with a test key.

List a Switch customer trunks with traffic

GET/api/v1/switch/customers/{id}/trunks

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

Each trunk with its authentication readiness, identification, addresses, routing, inherited limits and traffic over the chosen period.

Parameters

idrequired
path · string (uuid)
scope
query · string
Default operational (excludes archived)One of operational, archived, all
periodHours
query · integer
Window for the traffic figures; unrecognised values fall back to 24

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
subAccountIdrequired
string (uuid) · data[].subAccountId
The customer this trunk belongs to
labelrequired
string · data[].label
statusrequired
string · data[].status
One of active, disabled, archived
authMode
string · data[].authMode
One of ip, credentials, ip_and_credentials, registration, certificate
sipUsernamerequired
string | null · data[].sipUsername
sipPasswordSetrequired
boolean · data[].sipPasswordSet
maxConcurrentCallsrequired
integer | null · data[].maxConcurrentCalls
Null inherits the customer ceiling
maxCpsrequired
integer | null · data[].maxCps
markupPctrequired
string | null · data[].markupPct
billingIncrementrequired
string | null · data[].billingIncrement
techPrefixrequired
string | null · data[].techPrefix
mediaMode
string · data[].mediaMode
One of proxy, direct
cliRewriterequired
object | null · data[].cliRewrite
allowedPrefixesrequired
string[] | null · data[].allowedPrefixes
allowedCountriesrequired
string[] | null · data[].allowedCountries
blockedCountriesrequired
string[] | null · data[].blockedCountries
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data[].updatedAt
ISO-8601 timestamp (UTC)
authenticationrequired
object · data[].authentication
moderequired
string · data[].authentication.mode
One of ip, credentials, ip_and_credentials, registration, certificate
titlerequired
string · data[].authentication.title
summaryrequired
string · data[].authentication.summary
sendsrequired
string[] · data[].authentication.sends
checksrequired
string[] · data[].authentication.checks
gapsrequired
string[] · data[].authentication.gaps
Empty when the trunk is configured for its declared mode
enforcedrequired
boolean · data[].authentication.enforced
identificationrequired
object · data[].identification
namedByrequired
string[] · data[].identification.namedBy
uniquerequired
boolean · data[].identification.unique
noterequired
string | null · data[].identification.note
allowedIpsrequired
string[] · data[].allowedIps
allowedAddressesrequired
object[] · data[].allowedAddresses
idrequired
string (uuid) · data[].allowedAddresses[].id
cidrrequired
string · data[].allowedAddresses[].cidr
routingrequired
object | null · data[].routing
inheritedrequired
object · data[].inherited
fromrequired
string · data[].inherited.from
One of customer
maxConcurrentCallsrequired
integer | null · data[].inherited.maxConcurrentCalls
maxCpsrequired
integer | null · data[].inherited.maxCps
billingIncrementrequired
string | null · data[].inherited.billingIncrement
last24hrequired
object · data[].last24h
callsrequired
integer · data[].last24h.calls
minutesrequired
number · data[].last24h.minutes
revenuerequired
number · data[].last24h.revenue
US dollars as a JSON number (computed figure)
period
any · data[].period
The window the traffic figures cover
trafficrequired
object · data[].traffic
callsrequired
integer · data[].traffic.calls
answeredrequired
integer · data[].traffic.answered
minutesrequired
number · data[].traffic.minutes
revenuerequired
number · data[].traffic.revenue
US dollars as a JSON number (computed figure)
marginrequired
number · data[].traffic.margin
US dollars as a JSON number (computed figure)
asrrequired
number | null · data[].traffic.asr
pddMsrequired
number | null · data[].traffic.pddMs
refusedrequired
object · data[].refused
forbiddenrequired
integer · data[].refused.forbidden
capacityrequired
integer · data[].refused.capacity
capacityChannelsrequired
integer · data[].refused.capacityChannels
capacityCpsrequired
integer · data[].refused.capacityCps

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.

Add a trunk to a Switch customer

POST/api/v1/switch/customers/{id}/trunks

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

If sipPassword is set it is echoed back ONCE in the response.

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 (uuid)

Request body (application/json)

FieldDescription

label
string
max 120 chars
authMode
string
What the customer must present; the service refuses a mode the trunk is not configured forOne of ip, credentials, ip_and_credentials, registration, certificate
sipUsername
string | null
max 64 chars
sipPassword
string | null
max 64 chars
maxConcurrentCalls
integer | null
0 to 100000
maxCps
integer | null
0 to 10000
markupPct
number | null
0 to 10000
billingIncrement
string | null
max 10 chars
blockedPrefixes
string | null
max 8000 chars
status
string
One of active, disabled
mediaMode
string
One of proxy, direct
techPrefix
string | null
max 24 chars
cliRewrite
object | null
mode
string · cliRewrite.mode
One of pattern
value
string · cliRewrite.value
max 24 chars
strip
integer · cliRewrite.strip
0 to 15
add
string · cliRewrite.add
max 12 chars
match
string · cliRewrite.match
max 200 chars
replace
string · cliRewrite.replace
max 200 chars
allowedPrefixes
string[] | null
allowedCountries
string[] | null
blockedCountries
string[] | null
maxCallDurationSeconds
integer | null
1 to 21600
requireCli
boolean
allowedClis
string[] | null
marginProtectionMode
string
One of off, monitor, enforce
minMarginPct
number | null
0 to 99.999
minMarginAbs
number | null
0 to 1000
maxLossPerMinute
number | null
0 to 1000
dailyLossLimit
number | null
Warns only; never blocks0 to 10000000
dailyLossLimitPct
number | null
0 to 100000

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
subAccountIdrequired
string (uuid) · data.subAccountId
The customer this trunk belongs to
labelrequired
string · data.label
statusrequired
string · data.status
One of active, disabled, archived
authMode
string · data.authMode
One of ip, credentials, ip_and_credentials, registration, certificate
sipUsernamerequired
string | null · data.sipUsername
maxConcurrentCallsrequired
integer | null · data.maxConcurrentCalls
Null inherits the customer ceiling
maxCpsrequired
integer | null · data.maxCps
markupPctrequired
string | null · data.markupPct
billingIncrementrequired
string | null · data.billingIncrement
techPrefixrequired
string | null · data.techPrefix
mediaMode
string · data.mediaMode
One of proxy, direct
cliRewriterequired
object | null · data.cliRewrite
allowedPrefixesrequired
string[] | null · data.allowedPrefixes
allowedCountriesrequired
string[] | null · data.allowedCountries
blockedCountriesrequired
string[] | null · data.blockedCountries
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
sipPasswordrequired
string | null · data.sipPassword

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/customers/<id>/trunks" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Acme",
  "authMode": "ip"
}'

Run it here with a test key.

List your Switch customers with live and 24-hour figures

GET/api/v1/switch/customers

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

Every customer with trunk health, live calls, 24-hour traffic, credit used, primary contact and problem flags.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
labelrequired
string · data[].label
sourcerequired
string · data[].source
One of marketplace, external
statusrequired
string · data[].status
One of draft, active, suspended, closed
externalRefrequired
string | null · data[].externalRef
balancerequired
money · data[].balance
USD as a decimal string with exactly 6 places, e.g. "0.012500".
creditLimitrequired
string · data[].creditLimit
USD decimal string as stored (2 decimal places), e.g. "5000.00"
currencyrequired
string | null · data[].currency
sipUsernamerequired
string | null · data[].sipUsername
portalEmailrequired
string | null · data[].portalEmail
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
trunkCountrequired
integer · data[].trunkCount
Trunks excluding archived ones
trunksUprequired
integer · data[].trunksUp
trunksDownrequired
integer · data[].trunksDown
liveCallsrequired
integer · data[].liveCalls
calls24hrequired
integer · data[].calls24h
answered24hrequired
integer · data[].answered24h
asr24hrequired
number | null · data[].asr24h
Percent; null when no calls ran (not 0)
revenue24hrequired
number · data[].revenue24h
US dollars as a JSON number (computed figure)
margin24hrequired
number · data[].margin24h
US dollars as a JSON number (computed figure)
marginPct24hrequired
number | null · data[].marginPct24h
pddMs24hrequired
number | null · data[].pddMs24h
creditUsedPctrequired
number | null · data[].creditUsedPct
contactrequired
object | null · data[].contact
namerequired
string · data[].contact.name
emailrequired
string | null · data[].contact.email
phonerequired
string | null · data[].contact.phone
attentionrequired
object | null · data[].attention
Open operational issues. Null means the check could not run, not that nothing is wrong.
highestrequired
string | null · data[].attention.highest
openrequired
integer · data[].attention.open
unacknowledgedrequired
integer · data[].attention.unacknowledged
refsrequired
string[] · data[].attention.refs
setuprequired
object · data[].setup
trunksrequired
integer · data[].setup.trunks
enabledrequired
integer · data[].setup.enabled
identifiedrequired
integer · data[].setup.identified
routedrequired
integer · data[].setup.routed
unroutedrequired
integer · data[].setup.unrouted
refused24hrequired
object · data[].refused24h
forbiddenrequired
integer · data[].refused24h.forbidden
capacityrequired
integer · data[].refused24h.capacity
flagsrequired
string[] · data[].flags
Filterable problem and state flags, e.g. "problem:no_traffic"

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
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 Switch customer

POST/api/v1/switch/customers

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

Creates the customer, a "Default" trunk carrying the same credentials and limits, an empty routing row, and the customer's first API key. The SIP password and API key are returned ONCE in this response.

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

labelrequired
string
max 160 chars
source
string
One of marketplace, external
status
string
One of draft, active
externalRef
string | null
max 255 chars
creditLimit
number | null
min 0
markupPct
number | null
0 to 100000
billingIncrement
string | null
max 10 chars
currency
string | null
max 3 chars
minMarginPct
number | null
0 to 100000
marginFloorAction
string | null
One of block, alert
dailySpendCap
number | null
min 0
maxConcurrentCalls
integer | null
min 0
maxCps
integer | null
min 0
blockedPrefixes
string[]
portalEmail
string (email) | null
max 255 chars
taxCountry
string | null
max 2 chars
taxId
string | null
max 64 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
labelrequired
string · data.label
sourcerequired
string · data.source
One of marketplace, external
statusrequired
string · data.status
One of draft, active, suspended, closed
externalRefrequired
string | null · data.externalRef
balancerequired
money · data.balance
Prepaid wallet balance (negative = owed), 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
creditLimitrequired
string · data.creditLimit
USD decimal string as stored (2 decimal places), e.g. "5000.00"
currencyrequired
string | null · data.currency
markupPctrequired
string | null · data.markupPct
Default markup over cost, percent as a decimal string
billingIncrementrequired
string | null · data.billingIncrement
e.g. "60/60" or "6/6"
minMarginPctrequired
string | null · data.minMarginPct
marginFloorActionrequired
string | null · data.marginFloorAction
One of block, alert
dailySpendCaprequired
string | null · data.dailySpendCap
USD decimal string as stored (2 decimal places), e.g. "5000.00"
maxConcurrentCallsrequired
integer | null · data.maxConcurrentCalls
maxCpsrequired
integer | null · data.maxCps
blockedPrefixesrequired
string[] | null · data.blockedPrefixes
sipUsernamerequired
string | null · data.sipUsername
portalEmailrequired
string | null · data.portalEmail
taxCountryrequired
string | null · data.taxCountry
taxIdrequired
string | null · data.taxId
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
sipPasswordrequired
string · data.sipPassword
The inbound SIP password in plain text. Returned ONCE, here.
defaultTrunkIdrequired
string (uuid) · data.defaultTrunkId
The "Default" trunk created with every customer
apiKeyrequired
string · data.apiKey
The customer's first API key. Returned ONCE, here.
apiKeyPrefixrequired
string · data.apiKeyPrefix

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

Run it here with a test key.

Get a Switch customer command-centre overview

GET/api/v1/switch/customers/{id}/overview

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

KPIs, live traffic, quality, activity, setup state and data freshness in one read.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
customerrequired
object · data.customer
idrequired
string (uuid) · data.customer.id
labelrequired
string · data.customer.label
statusrequired
string · data.customer.status
One of draft, active, suspended, closed
sourcerequired
string · data.customer.source
kpisrequired
object · data.kpis
Balance owed, wallet, credit used and today's traffic figures (numbers)
commercialrequired
object · data.commercial
activityrequired
object[] · data.activity
topDestinationsTodayrequired
object[] · data.topDestinationsToday
health
any · data.health
setup
any · data.setup
reconciliation
any · data.reconciliation
freshness
any · data.freshness

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.

Get a Switch customer

GET/api/v1/switch/customers/{id}

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

Includes customer-level IP allow-list entries in ipAcls. The SIP password is never returned here; see the credentials endpoint.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
labelrequired
string · data.label
sourcerequired
string · data.source
One of marketplace, external
statusrequired
string · data.status
One of draft, active, suspended, closed
externalRefrequired
string | null · data.externalRef
balancerequired
money · data.balance
Prepaid wallet balance (negative = owed), 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
creditLimitrequired
string · data.creditLimit
USD decimal string as stored (2 decimal places), e.g. "5000.00"
currencyrequired
string | null · data.currency
markupPctrequired
string | null · data.markupPct
Default markup over cost, percent as a decimal string
billingIncrementrequired
string | null · data.billingIncrement
e.g. "60/60" or "6/6"
minMarginPctrequired
string | null · data.minMarginPct
marginFloorActionrequired
string | null · data.marginFloorAction
One of block, alert
dailySpendCaprequired
string | null · data.dailySpendCap
USD decimal string as stored (2 decimal places), e.g. "5000.00"
maxConcurrentCallsrequired
integer | null · data.maxConcurrentCalls
maxCpsrequired
integer | null · data.maxCps
blockedPrefixesrequired
string[] | null · data.blockedPrefixes
sipUsernamerequired
string | null · data.sipUsername
sipPasswordSetrequired
boolean · data.sipPasswordSet
Whether an inbound SIP password is set. The value itself is only ever returned by the audited credentials endpoint.
portalEmailrequired
string | null · data.portalEmail
taxCountryrequired
string | null · data.taxCountry
taxIdrequired
string | null · data.taxId
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
ipAclsrequired
object[] · data.ipAcls

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 Switch customer

PATCH/api/v1/switch/customers/{id}

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

Any field from create, all optional. A status change is applied as the matching lifecycle action, with the same guards and history entry as POST /lifecycle. Send X-If-Unchanged-Since: <updatedAt you loaded> to have the save refused with 409 STALE_WRITE if someone changed the record since.

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 (uuid)

Request body (application/json)

FieldDescription

label
string
max 160 chars
source
string
One of marketplace, external
status
string
One of draft, active, suspended, closed
externalRef
string | null
max 255 chars
creditLimit
number | null
min 0
markupPct
number | null
0 to 100000
billingIncrement
string | null
max 10 chars
currency
string | null
max 3 chars
minMarginPct
number | null
0 to 100000
marginFloorAction
string | null
One of block, alert
dailySpendCap
number | null
min 0
maxConcurrentCalls
integer | null
min 0
maxCps
integer | null
min 0
blockedPrefixes
string[]
portalEmail
string (email) | null
max 255 chars
taxCountry
string | null
max 2 chars
taxId
string | null
max 64 chars
statusReason
string | null
max 2000 chars

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
labelrequired
string · data.label
sourcerequired
string · data.source
One of marketplace, external
statusrequired
string · data.status
One of draft, active, suspended, closed
externalRefrequired
string | null · data.externalRef
balancerequired
money · data.balance
Prepaid wallet balance (negative = owed), 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
creditLimitrequired
string · data.creditLimit
USD decimal string as stored (2 decimal places), e.g. "5000.00"
currencyrequired
string | null · data.currency
markupPctrequired
string | null · data.markupPct
Default markup over cost, percent as a decimal string
billingIncrementrequired
string | null · data.billingIncrement
e.g. "60/60" or "6/6"
minMarginPctrequired
string | null · data.minMarginPct
marginFloorActionrequired
string | null · data.marginFloorAction
One of block, alert
dailySpendCaprequired
string | null · data.dailySpendCap
USD decimal string as stored (2 decimal places), e.g. "5000.00"
maxConcurrentCallsrequired
integer | null · data.maxConcurrentCalls
maxCpsrequired
integer | null · data.maxCps
blockedPrefixesrequired
string[] | null · data.blockedPrefixes
sipUsernamerequired
string | null · data.sipUsername
sipPasswordSetrequired
boolean · data.sipPasswordSet
Whether an inbound SIP password is set. The value itself is only ever returned by the audited credentials endpoint.
portalEmailrequired
string | null · data.portalEmail
taxCountryrequired
string | null · data.taxCountry
taxIdrequired
string | null · data.taxId
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)

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 PATCH "https://packetexchange.io/api/v1/switch/customers/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Acme",
  "source": "marketplace"
}'

Run it here with a test key.

Delete a draft Switch customer

DELETE/api/v1/switch/customers/{id}

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

Only for a customer that never carried traffic or held financial records. Offboard a real customer with the close lifecycle action 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

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true
idrequired
string (uuid) · data.id
labelrequired
string · data.label

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

Get a Switch customer lifecycle state and financial position

GET/api/v1/switch/customers/{id}/lifecycle

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

Which lifecycle actions are available now, live calls, trunk counts, recent history and the money position a close or suspend would leave.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
customerrequired
object · data.customer
idrequired
string (uuid) · data.customer.id
labelrequired
string · data.customer.label
statusrequired
string · data.customer.status
One of draft, active, suspended, closed
sourcerequired
string · data.customer.source
createdAtrequired
string (date-time) · data.customer.createdAt
ISO-8601 timestamp (UTC)
availablerequired
string[] · data.available
Actions allowed from the current stateOne of activate, suspend, reactivate, close, reopen
liveCallsrequired
integer · data.liveCalls
trunksrequired
object · data.trunks
totalrequired
integer · data.trunks.total
activerequired
integer · data.trunks.active
historyrequired
object[] · data.history
idrequired
string · data.history[].id
atrequired
string (date-time) · data.history[].at
ISO-8601 timestamp (UTC)
actionrequired
string · data.history[].action
fromrequired
string | null · data.history[].from
torequired
string | null · data.history[].to
reasonrequired
string | null · data.history[].reason
actorrequired
string | null · data.history[].actor
Email of whoever did it
detailrequired
object · data.history[].detail
financialsrequired
object · data.financials
currencyrequired
string · data.financials.currency
prepaidBalancerequired
number · data.financials.prepaidBalance
US dollars as a JSON number (computed figure)
invoicesOutstandingrequired
number · data.financials.invoicesOutstanding
US dollars as a JSON number (computed figure)
invoicesOverduerequired
number · data.financials.invoicesOverdue
US dollars as a JSON number (computed figure)
creditNotesOpenrequired
number · data.financials.creditNotesOpen
US dollars as a JSON number (computed figure)
unbilledUsagerequired
number · data.financials.unbilledUsage
US dollars as a JSON number (computed figure)
creditLimitrequired
number · data.financials.creditLimit
US dollars as a JSON number (computed figure)
openInvoiceCountrequired
integer · data.financials.openInvoiceCount
paidInvoiceCountrequired
integer · data.financials.paidInvoiceCount
paymentCountrequired
integer · data.financials.paymentCount
hasOpenPositionrequired
boolean · data.financials.hasOpenPosition
canDeleterequired
boolean · data.canDelete
deleteBlockersrequired
string[] · data.deleteBlockers

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.

Activate, suspend, reactivate, close or reopen a Switch customer

POST/api/v1/switch/customers/{id}/lifecycle

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

The one write path for a customer's state. Live calls keep talking unless disconnectLiveCalls is true. Send X-If-Unchanged-Since: <updatedAt you loaded> to have the save refused with 409 STALE_WRITE if someone changed the record since.

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 (uuid)

Request body (application/json)

FieldDescription

actionrequired
string
One of activate, suspend, reactivate, close, reopen
reason
string | null
max 2000 chars
disconnectLiveCalls
boolean

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
labelrequired
string · data.label
statusrequired
string · data.status
One of draft, active, suspended, closed
previousStatusrequired
string · data.previousStatus
One of draft, active, suspended, closed
actionrequired
string · data.action
liveCallsAtChangerequired
integer · data.liveCallsAtChange
disconnectedLiveCallsrequired
boolean · data.disconnectedLiveCalls
disconnectIncomplete
boolean · data.disconnectIncomplete
apiKeysRevoked
integer · data.apiKeysRevoked
financialsUnchangedrequired
boolean · data.financialsUnchanged
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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/customers/<id>/lifecycle" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "activate"
}'

Run it here with a test key.

List a Switch customer lifecycle history

GET/api/v1/switch/customers/{id}/history

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

Parameters

idrequired
path · string (uuid)
limit
query · integer
Default 50

Response 200

FieldDescription

datarequired
object[]
Same fields as SwitchCustomerLifecycleEntry, 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.

Rotate a Switch customer inbound SIP password

POST/api/v1/switch/customers/{id}/sip-password

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

Generates a new password and returns it ONCE. The old password stops working immediately.

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 (uuid)

Response 200

FieldDescription

datarequired
object
sipUsernamerequired
string | null · data.sipUsername
sipPasswordrequired
string | null · data.sipPassword

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

Reveal a Switch customer inbound SIP credentials

GET/api/v1/switch/customers/{id}/credentials

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

Returns the current username and password without changing them. Every reveal is recorded in the audit log.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
Same fields as SwitchCustomerSipCredentials, 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 what needs attention on a Switch customer

GET/api/v1/switch/customers/{id}/attention

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

A compact projection of the customer's open operational issues: quality, margin, credit and setup problems.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object[]
kindrequired
string · data[].kind
One of quality, commercial, credit, config, setup
titlerequired
string · data[].title
detailrequired
string · data[].detail
atrequired
string · data[].at
actionablerequired
boolean · data[].actionable

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 operational issues on a Switch customer

GET/api/v1/switch/customers/{id}/issues

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

The full issue records behind the attention feed, with trigger, recovery rule, evidence and ownership.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object[]
refrequired
string · data[].ref
Issue reference, e.g. OPS-1042
detectorrequired
string · data[].detector
severityrequired
string · data[].severity
statusrequired
string · data[].status
titlerequired
string · data[].title
summaryrequired
string · data[].summary
triggerrequired
string · data[].trigger
recoveryrequired
string · data[].recovery
sampleSizerequired
number · data[].sampleSize
evidencerequired
object[] · data[].evidence
labelrequired
string · data[].evidence[].label
valuerequired
string · data[].evidence[].value
firstDetectedAtrequired
string · data[].firstDetectedAt
lastDetectedAtrequired
string · data[].lastDetectedAt
acknowledgedAtrequired
string | null · data[].acknowledgedAt
resolvedAtrequired
string | null · data[].resolvedAt

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 a Switch customer contacts

GET/api/v1/switch/customers/{id}/contacts

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

Ordered by role, then priority. A contact is a person to reach, never a login.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
subAccountIdrequired
string (uuid) · data[].subAccountId
namerequired
string · data[].name
rolerequired
string · data[].role
One of technical, noc, billing, escalation, commercial
emailrequired
string | null · data[].email
phonerequired
string | null · data[].phone
priorityrequired
integer · data[].priority
1 = try first within this role
isPrimaryrequired
boolean · data[].isPrimary
preferredMethodrequired
string · data[].preferredMethod
One of email, phone, either
availabilityrequired
string | null · data[].availability
One of 24x7, business_hours, on_call
timezonerequired
string | null · data[].timezone
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)

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.

Add a Switch customer contact

POST/api/v1/switch/customers/{id}/contacts

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 (uuid)

Request body (application/json)

FieldDescription

namerequired
string
max 200 chars
rolerequired
string
One of technical, noc, billing, escalation, commercial
email
string (email) | null
max 255 chars
phone
string | null
max 48 chars
priority
integer
1 to 99
isPrimary
boolean
preferredMethod
string
One of email, phone, either
availability
string | null
One of 24x7, business_hours, on_call
timezone
string | null
max 64 chars
notes
string | null
max 2000 chars

Response 201

FieldDescription

datarequired
object
Same fields as SwitchCustomerContact, 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/customers/<id>/contacts" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "role": "technical"
}'

Run it here with a test key.

Update a Switch customer contact

PATCH/api/v1/switch/customers/{id}/contacts/{contactId}

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 (uuid)
contactIdrequired
path · string (uuid)

Request body (application/json)

FieldDescription

name
string
max 200 chars
role
string
One of technical, noc, billing, escalation, commercial
email
string (email) | null
max 255 chars
phone
string | null
max 48 chars
priority
integer
1 to 99
isPrimary
boolean
preferredMethod
string
One of email, phone, either
availability
string | null
One of 24x7, business_hours, on_call
timezone
string | null
max 64 chars
notes
string | null
max 2000 chars

Response 200

FieldDescription

datarequired
object
Same fields as SwitchCustomerContact, 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 PATCH "https://packetexchange.io/api/v1/switch/customers/<id>/contacts/<contactId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "role": "technical"
}'

Run it here with a test key.

Delete a Switch customer contact

DELETE/api/v1/switch/customers/{id}/contacts/{contactId}

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 (uuid)
contactIdrequired
path · string (uuid)

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

HTTP

curl -X DELETE "https://packetexchange.io/api/v1/switch/customers/<id>/contacts/<contactId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

List internal notes on a Switch customer

GET/api/v1/switch/customers/{id}/notes

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

Operator-private notes with the author name. Never visible to the customer.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
subAccountIdrequired
string (uuid) · data[].subAccountId
bodyrequired
string · data[].body
typerequired
string · data[].type
One of general, technical, billing, warning
pinnedrequired
boolean · data[].pinned
followUpAtrequired
string (date-time) | null · data[].followUpAt
ISO-8601 timestamp (UTC)
createdByrequired
string (uuid) | null · data[].createdBy
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data[].updatedAt
ISO-8601 timestamp (UTC)
authorNamerequired
string | null · data[].authorName

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.

Add an internal note to a Switch customer

POST/api/v1/switch/customers/{id}/notes

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 (uuid)

Request body (application/json)

FieldDescription

bodyrequired
string
max 4000 chars
type
string
One of general, technical, billing, warning
pinned
boolean
followUpAt
string (date-time) | null

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
subAccountIdrequired
string (uuid) · data.subAccountId
bodyrequired
string · data.body
typerequired
string · data.type
One of general, technical, billing, warning
pinnedrequired
boolean · data.pinned
followUpAtrequired
string (date-time) | null · data.followUpAt
ISO-8601 timestamp (UTC)
createdByrequired
string (uuid) | null · data.createdBy
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)

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/customers/<id>/notes" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Hello from Acme"
}'

Run it here with a test key.

Edit, pin or flag a Switch customer note

PATCH/api/v1/switch/customers/{id}/notes/{noteId}

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

The author and creation time never change.

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 (uuid)
noteIdrequired
path · string (uuid)

Request body (application/json)

FieldDescription

body
string
max 4000 chars
type
string
One of general, technical, billing, warning
pinned
boolean
followUpAt
string (date-time) | null

Response 200

FieldDescription

datarequired
object
Same fields as SwitchCustomerNote, 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 PATCH "https://packetexchange.io/api/v1/switch/customers/<id>/notes/<noteId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Hello from Acme",
  "type": "general"
}'

Run it here with a test key.

Delete a Switch customer note

DELETE/api/v1/switch/customers/{id}/notes/{noteId}

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 (uuid)
noteIdrequired
path · string (uuid)

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

Get per-destination quality for a Switch customer

GET/api/v1/switch/customers/{id}/quality

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

ASR, NER and PDD per destination over a window, with verdicts. The KPI row and the table are both computed from the same filtered set.

Parameters

idrequired
path · string (uuid)
window
query · integer
Hours: 1, 24 or 168. Default 24
from
query · string
Explicit window start (ISO-8601); overrides window
to
query · string
Explicit window end (ISO-8601)

Response 200

FieldDescription

datarequired
object
windowHoursrequired
number · data.windowHours
windowrequired
object · data.window
fromrequired
string (date-time) · data.window.from
ISO-8601 timestamp (UTC)
torequired
string (date-time) · data.window.to
ISO-8601 timestamp (UTC)
labelrequired
string · data.window.label
destinationDigitsrequired
integer · data.destinationDigits
kpisrequired
object · data.kpis
callsrequired
integer · data.kpis.calls
answeredrequired
integer · data.kpis.answered
asrrequired
number | null · data.kpis.asr
nerrequired
number | null · data.kpis.ner
destinationsrequired
object[] · data.destinations
prefixrequired
string · data.destinations[].prefix
callsrequired
integer · data.destinations[].calls
answeredrequired
integer · data.destinations[].answered
asrrequired
number | null · data.destinations[].asr
nerrequired
number | null · data.destinations[].ner
healthrequired
string · data.destinations[].health
thresholds
any · data.thresholds
minJudgeableSessionsrequired
integer · data.minJudgeableSessions
supportsrequired
string[] · data.supports
Call Records filter ids this view honours
unsupportedrequired
any[] · data.unsupported
Filters you sent that this view could not apply

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.

Drill into one destination for a Switch customer

GET/api/v1/switch/customers/{id}/quality/destination

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

Which customer trunks sent it, which supplier trunks carried it, which route groups send it there, and how far the sessions got. Uses the same window and filters as the quality table.

Parameters

idrequired
path · string (uuid)
window
query · integer
Hours: 1, 24 or 168. Default 24
from
query · string
Explicit window start (ISO-8601); overrides window
to
query · string
Explicit window end (ISO-8601)
prefixrequired
query · string
The destination prefix to open

Response 200

FieldDescription

datarequired
object
windowHoursrequired
number · data.windowHours
windowrequired
object · data.window
fromrequired
string (date-time) · data.window.from
ISO-8601 timestamp (UTC)
torequired
string (date-time) · data.window.to
ISO-8601 timestamp (UTC)
labelrequired
string · data.window.label
destinationDigitsrequired
integer · data.destinationDigits

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.

HTTP

curl "https://packetexchange.io/api/v1/switch/customers/<id>/quality/destination?prefix=44" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Get a Switch customer receivables summary

GET/api/v1/switch/customers/{id}/billing-summary

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

What is owed, unbilled and unrated, payments recorded and ageing. Credit headroom is a separate endpoint (credit-position).

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
balanceOwedrequired
number · data.balanceOwed
Open invoices less open credit notes
grossBalanceOwedrequired
number · data.grossBalanceOwed
US dollars as a JSON number (computed figure)
creditNotesOpenrequired
number · data.creditNotesOpen
US dollars as a JSON number (computed figure)
paymentsRecordedrequired
number · data.paymentsRecorded
US dollars as a JSON number (computed figure)
creditLimitrequired
number · data.creditLimit
US dollars as a JSON number (computed figure)
unbilledRatedrequired
number · data.unbilledRated
US dollars as a JSON number (computed figure)
unbilledSinceLastInvoicerequired
number · data.unbilledSinceLastInvoice
US dollars as a JSON number (computed figure)
unratedUsagerequired
object · data.unratedUsage
callsrequired
integer · data.unratedUsage.calls
minutesrequired
number | null · data.unratedUsage.minutes
noterequired
string · data.unratedUsage.note
overdueIsSubsetOfOpenInvoicesrequired
boolean · data.overdueIsSubsetOfOpenInvoices
One of true
disputedrequired
enum | null · data.disputed
Customer-side disputes are not recorded, so always nullOne of null
avgDaysToPayrequired
number | null · data.avgDaysToPay
lastInvoicePeriodEndrequired
string (date-time) | null · data.lastInvoicePeriodEnd
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
agingrequired
object · data.aging
currentrequired
number · data.aging.current
US dollars as a JSON number (computed figure)
d1_30required
number · data.aging.d1_30
US dollars as a JSON number (computed figure)
d31_60required
number · data.aging.d31_60
US dollars as a JSON number (computed figure)
d61_90required
number · data.aging.d61_90
US dollars as a JSON number (computed figure)
d90_plusrequired
number · data.aging.d90_plus
US dollars as a JSON number (computed figure)

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.

Get a Switch customer credit position

GET/api/v1/switch/customers/{id}/credit-position

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

Credit limit, exposure, funds reserved by live calls, available credit and whether the next call would be admitted. Read-only; it reports the admission arithmetic without performing it.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
customerIdrequired
string (uuid) · data.customerId
labelrequired
string · data.label
currencyrequired
string · data.currency
moderequired
string · data.mode
prepaid or postpaid, derived from the credit limit
creditLimitrequired
object · data.creditLimit
valuerequired
number · data.creditLimit.value
US dollars as a JSON number (computed figure)
ambiguousrequired
string | null · data.creditLimit.ambiguous
exposurerequired
number · data.exposure
US dollars as a JSON number (computed figure)
balancerequired
number · data.balance
US dollars as a JSON number (computed figure)
reservationsrequired
object · data.reservations
amountrequired
number · data.reservations.amount
US dollars as a JSON number (computed figure)
callsrequired
integer · data.reservations.calls
enforcedrequired
boolean · data.reservations.enforced
basisrequired
string · data.reservations.basis
availableCreditrequired
number · data.availableCredit
US dollars as a JSON number (computed figure)
availableAfterReservationsrequired
number · data.availableAfterReservations
US dollars as a JSON number (computed figure)
admitsNextCallrequired
boolean · data.admitsNextCall
usedPctrequired
number | null · data.usedPct
overCommittedrequired
boolean · data.overCommitted

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.

Preview how a payment would be allocated to invoices

GET/api/v1/switch/customers/{id}/payments/preview

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

Parameters

idrequired
path · string (uuid)
amount
query · number
USD amount to preview

Response 200

FieldDescription

datarequired
object
billingModerequired
string · data.billingMode
currencyrequired
string · data.currency
wouldAllocaterequired
object[] · data.wouldAllocate
invoiceIdrequired
string (uuid) · data.wouldAllocate[].invoiceId
invoiceNumberrequired
string · data.wouldAllocate[].invoiceNumber
appliedrequired
number · data.wouldAllocate[].applied
US dollars as a JSON number (computed figure)
clearsInvoicerequired
boolean · data.wouldAllocate[].clearsInvoice
wouldLeaveUnappliedrequired
number · data.wouldLeaveUnapplied
US dollars as a JSON number (computed figure)

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.

Record a payment received from a Switch customer

POST/api/v1/switch/customers/{id}/payments

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Safe retries: Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Moves money: Records or reverses a payment on a Switch customer ledger.

Records money the customer already paid you (nothing is collected). It credits the wallet and pays open invoices oldest-due first in one transaction; anything left is held unapplied.

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 (uuid)
X-Idempotency-Key
header · string
Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

FieldDescription

amountrequired
number
USDmin 0
reference
string | null
Bank or remittance reference, for matching latermax 160 chars
method
string | null
max 32 chars
paidAt
string | null
When the money was received (ISO-8601); default now

Response 201

FieldDescription

datarequired
object
kindrequired
string · data.kind
One of payment
transactionIdrequired
string (uuid) · data.transactionId
amountrequired
number · data.amount
US dollars as a JSON number (computed figure)
currencyrequired
string · data.currency
postedAtrequired
string (date-time) · data.postedAt
ISO-8601 timestamp (UTC)
externalReferencerequired
string | null · data.externalReference
methodrequired
string | null · data.method
operatorLabelrequired
string | null · data.operatorLabel
billingModerequired
string · data.billingMode
allocationsrequired
object[] · data.allocations
Oldest-due invoices first
invoiceIdrequired
string (uuid) · data.allocations[].invoiceId
invoiceNumberrequired
string · data.allocations[].invoiceNumber
appliedrequired
number · data.allocations[].applied
US dollars as a JSON number (computed figure)
outstandingAfterrequired
number · data.allocations[].outstandingAfter
US dollars as a JSON number (computed figure)
statusrequired
string · data.allocations[].status
unappliedrequired
number · data.unapplied
Left on account after paying every open invoice
positionAfterrequired
object · data.positionAfter

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/customers/<id>/payments" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 1
}'

Run it here with a test key.

Reverse a recorded Switch customer payment

POST/api/v1/switch/customers/{id}/payments/{transactionId}/reverse

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Records or reverses a payment on a Switch customer ledger.

A posted payment is never edited or deleted. This posts a linked reversal and unwinds its invoice allocations; both entries stay on the record.

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 (uuid)
transactionIdrequired
path · string (uuid)

Request body (application/json)

FieldDescription

reasonrequired
string
max 500 chars

Response 201

FieldDescription

datarequired
object
kindrequired
string · data.kind
One of reversal
reversesTransactionIdrequired
string (uuid) · data.reversesTransactionId
transactionIdrequired
string (uuid) · data.transactionId
amountrequired
number · data.amount
US dollars as a JSON number (computed figure)
currencyrequired
string · data.currency
reasonrequired
string · data.reason
unwoundrequired
object[] · data.unwound
positionAfterrequired
object · data.positionAfter

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/customers/<id>/payments/<transactionId>/reverse" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Example"
}'

Run it here with a test key.

Preview an invoice for a Switch customer unbilled period

POST/api/v1/switch/customers/{id}/invoice-preview

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

The period runs from the last invoice's end (or the customer's creation) to now. Issues nothing; returns a reviewToken for generate-invoice.

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 (uuid)

Request body (application/json)

FieldDescription

notes
string | null
max 2000 chars
includeBroughtForward
boolean
applyCredits
boolean
excludeUnrated
object | null
Issue despite unrated usage in the period, with the reason recorded on the invoice
reasonrequired
string · excludeUnrated.reason
max 2000 chars

Response 200

FieldDescription

datarequired
object
customerrequired
object · data.customer
idrequired
string (uuid) · data.customer.id
labelrequired
string · data.customer.label
legalNamerequired
string · data.customer.legalName
currencyrequired
string · data.customer.currency
periodrequired
object · data.period
dueDaterequired
string · data.dueDate
paymentTermsDaysrequired
integer · data.paymentTermsDays
currencyrequired
string · data.currency
usagerequired
object · data.usage
unratedrequired
object · data.unrated
Usage that has no price yet; blocks issue unless excluded
reviewTokenrequired
string · data.reviewToken
Pass to generate-invoice to issue exactly what was reviewed
reviewDigestrequired
string · data.reviewDigest

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/customers/<id>/invoice-preview" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "notes": "Example",
  "includeBroughtForward": true
}'

Run it here with a test key.

Issue the reviewed invoice for a Switch customer

POST/api/v1/switch/customers/{id}/generate-invoice

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

Requires the reviewToken from invoice-preview; refused with 409 INVOICE_REVIEW_STALE if the data changed since, or INVOICE_UNRATED_USAGE if unrated usage remains and was not excluded.

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 (uuid)

Request body (application/json)

FieldDescription

notes
string | null
max 2000 chars
includeBroughtForward
boolean
applyCredits
boolean
excludeUnrated
object | null
Issue despite unrated usage in the period, with the reason recorded on the invoice
reasonrequired
string · excludeUnrated.reason
max 2000 chars
reviewTokenrequired
string
max 120 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
invoiceNumberrequired
string · data.invoiceNumber
customerIdrequired
string (uuid) · data.customerId
statusrequired
string · data.status
subtotalrequired
money · data.subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
currencyrequired
string · data.currency
periodStartrequired
string (date-time) · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) · data.periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) | null · data.issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.dueDate
ISO-8601 timestamp (UTC)
linesrequired
object[] · data.lines
reviewDigestrequired
string | null · data.reviewDigest

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.
AlsoINVOICE_REVIEW_STALE, INVOICE_UNRATED_USAGE, STALE_WRITE

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/customers/<id>/generate-invoice" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reviewToken": "<reviewToken>"
}'

Run it here with a test key.

Get a Switch customer billing profile

GET/api/v1/switch/customers/{id}/billing-profile

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

profile is what was entered (null if none); resolved is what an invoice issued now would freeze, including fallbacks.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
profilerequired
object | null · data.profile
idrequired
string (uuid) · data.profile.id
legalNamerequired
string · data.profile.legalName
versionrequired
integer · data.profile.version
Bumped on every save; frozen onto invoices issued afterwards
updatedAtrequired
string (date-time) · data.profile.updatedAt
ISO-8601 timestamp (UTC)
resolvedrequired
object · data.resolved
sourcerequired
string · data.resolved.source
One of profile, fallback
profileIdrequired
string (uuid) | null · data.resolved.profileId
profileVersionrequired
integer | null · data.resolved.profileVersion
customerrequired
object · data.resolved.customer
billingAddressrequired
object | null · data.resolved.billingAddress
issuerrequired
object · data.resolved.issuer
termsrequired
object · data.resolved.terms
currencyrequired
string · data.resolved.terms.currency
billingCyclerequired
string | null · data.resolved.terms.billingCycle
billingTimezonerequired
string · data.resolved.terms.billingTimezone
paymentTermsDaysrequired
integer · data.resolved.terms.paymentTermsDays
purchaseOrderRefrequired
string | null · data.resolved.terms.purchaseOrderRef
paymentInstructionsrequired
string | null · data.resolved.terms.paymentInstructions
recipients
any · data.resolved.recipients

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.

Save a Switch customer billing profile

PUT/api/v1/switch/customers/{id}/billing-profile

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

The customer's legal and billing identity. Frozen onto invoices issued afterwards; never changes an invoice already issued. Send X-If-Unchanged-Since: <updatedAt you loaded> to have the save refused with 409 STALE_WRITE if someone changed the record since.

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 (uuid)

Request body (application/json)

FieldDescription

legalName
string
max 200 chars
tradingName
string | null
max 200 chars
registrationNumber
string | null
max 64 chars
addressLine1
string | null
max 200 chars
addressLine2
string | null
max 200 chars
city
string | null
max 120 chars
region
string | null
max 120 chars
postcode
string | null
max 32 chars
country
string | null
max 2 chars
billingAddressLine1
string | null
max 200 chars
billingAddressLine2
string | null
max 200 chars
billingCity
string | null
max 120 chars
billingRegion
string | null
max 120 chars
billingPostcode
string | null
max 32 chars
billingCountry
string | null
max 2 chars
taxCountry
string | null
max 2 chars
taxId
string | null
max 64 chars
taxTreatment
string | null
One of standard, reverse_charge, zero_rated, exempt
invoiceCurrency
string
max 3 chars
billingCycle
string | null
One of weekly, biweekly, monthly, manual
billingTimezone
string
max 64 chars
paymentTermsDays
integer | null
0 to 365
purchaseOrderRef
string | null
max 64 chars
invoiceRecipients
string (email)[]

Response 200

FieldDescription

datarequired
object
Same fields as SwitchCustomerBillingProfile, 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/customers/<id>/billing-profile" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "legalName": "<legalName>",
  "tradingName": "<tradingName>"
}'

Run it here with a test key.

Get a Switch customer default sell deck and each trunk's deck

GET/api/v1/switch/customers/{id}/sell-deck

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

An unknown customer answers 404 NOT_FOUND.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
customerIdrequired
string (uuid) · data.customerId
customerLabelrequired
string · data.customerLabel
defaultDeckrequired
object | null · data.defaultDeck
idrequired
string (uuid) · data.defaultDeck.id
namerequired
string · data.defaultDeck.name
versionrequired
integer · data.defaultDeck.version
statusrequired
string · data.defaultDeck.status
currencyrequired
string · data.defaultDeck.currency
isSystemDefaultrequired
boolean · data.defaultDeck.isSystemDefault
defaultRatePerUnitrequired
number | null · data.defaultDeck.defaultRatePerUnit
USD per minute for destinations the deck does not list; null = refuse them
chargingrequired
object · data.defaultDeck.charging
systemDefaultrequired
object | null · data.systemDefault
Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.
trunksrequired
object[] · data.trunks
effectiverequired
object · data.trunks[].effective
deckrequired
object | null · data.trunks[].effective.deck
Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.
moderequired
string · data.trunks[].effective.mode
choicerequired
string · data.trunks[].effective.choice
Which rule won: the trunk, the customer default or the system default
bypassesCustomerDefaultrequired
boolean · data.trunks[].effective.bypassesCustomerDefault
customerDefaultrequired
object | null · data.trunks[].effective.customerDefault
Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.
systemDefaultrequired
object | null · data.trunks[].effective.systemDefault
Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.
liveRowCountrequired
integer · data.trunks[].effective.liveRowCount
explanationrequired
string · data.trunks[].effective.explanation
problemrequired
string | null · data.trunks[].effective.problem
trunksDisagreerequired
boolean · data.trunksDisagree

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 a Switch customer default sell deck

PUT/api/v1/switch/customers/{id}/sell-deck

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

Without confirm: true nothing changes: the response lists the trunks whose prices would change. With it, the deck is assigned and trunks that follow the customer default reprice from the next call.

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 (uuid)

Request body (application/json)

FieldDescription

deckId
string (uuid) | null
null clears the default
confirm
boolean
reason
string

Response 200

FieldDescription

datarequired
object
changed
boolean · data.changed
One of true
wouldChange
object · data.wouldChange
trunksrequired
string[] · data.wouldChange.trunks
messagerequired
string · data.wouldChange.message
trunks
integer · data.trunks

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/customers/<id>/sell-deck" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "deckId": "<deckId>",
  "confirm": true
}'

Run it here with a test key.

Email a Switch customer a portal sign-in link

POST/api/v1/switch/customers/{id}/portal-invite

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Sends email: Sends an email to a third party.

Sends a magic sign-in link to the customer's portal email. With no portal email set it answers 400 VALIDATION_ERROR.

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 (uuid)

Response 200

FieldDescription

datarequired
object
sentrequired
boolean · data.sent
One of true
torequired
string · data.to

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 a Switch customer sell rates with buy cost and margin

GET/api/v1/switch/customers/{id}/sell-rates

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

Parameters

idrequired
path · string (uuid)
search
query · string
Prefix or destination text
limit
query · integer
offset
query · integer
view
query · string
Default currentOne of current, scheduled, discontinued, expiring, all
origin
query · string
One of any, origin_only, destination_only
increment
query · string
One of any, custom, inherited
cost
query · string
One of any, missing
margin
query · string
One of any, thin, negative

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string (uuid) · data.rows[].id
subAccountIdrequired
string (uuid) · data.rows[].subAccountId
customerTrunkIdrequired
string (uuid) | null · data.rows[].customerTrunkId
prefixrequired
string · data.rows[].prefix
originPrefixrequired
string · data.rows[].originPrefix
"" = any origin
ratePerUnitrequired
money · data.rows[].ratePerUnit
Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.rows[].billingIncrement
statusrequired
string · data.rows[].status
active, pending (scheduled) or discontinued
effectiveFromrequired
string (date-time) · data.rows[].effectiveFrom
ISO-8601 timestamp (UTC)
endDaterequired
string (date-time) | null · data.rows[].endDate
ISO-8601 timestamp (UTC)
buyCostrequired
number | null · data.rows[].buyCost
Best eligible buy cost per minute (USD number); null = no supplier prices it
marginPctrequired
number | null · data.rows[].marginPct
thinrequired
boolean · data.rows[].thin
negativerequired
boolean · data.rows[].negative
costSupplierrequired
string | null · data.rows[].costSupplier
costSourcerequired
string · data.rows[].costSource
costMatchedPrefixrequired
string | null · data.rows[].costMatchedPrefix
costNoterequired
string | null · data.rows[].costNote
totalrequired
integer · data.total
totalIsPageScopedrequired
boolean · data.totalIsPageScoped
True when a cost or margin filter narrowed the page, so total counts this page only
limitrequired
integer · data.limit
offsetrequired
integer · data.offset
viewrequired
string · data.view
summaryrequired
object · data.summary
prefixesrequired
integer · data.summary.prefixes
blendedMarginPctrequired
number | null · data.summary.blendedMarginPct
thinCountrequired
integer · data.summary.thinCount
negativeCountrequired
integer · data.summary.negativeCount
defaultRateCostCountrequired
integer · data.summary.defaultRateCostCount
unpricedCountrequired
integer · data.summary.unpricedCount
basis
any · data.basis

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.

Add or replace one Switch customer sell rate

POST/api/v1/switch/customers/{id}/sell-rates

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

Takes effect now on the customer's default trunk. Use the per-trunk rate endpoints to price a specific 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 (uuid)

Request body (application/json)

FieldDescription

prefixrequired
string
max 24 chars
raterequired
number
USD per minutemin 0
origin
string
max 24 chars
billingIncrement
string
max 10 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
subAccountIdrequired
string (uuid) · data.subAccountId
customerTrunkIdrequired
string (uuid) | null · data.customerTrunkId
prefixrequired
string · data.prefix
originPrefixrequired
string · data.originPrefix
"" = any origin
ratePerUnitrequired
money · data.ratePerUnit
Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.billingIncrement
statusrequired
string · data.status
active, pending (scheduled) or discontinued
effectiveFromrequired
string (date-time) · data.effectiveFrom
ISO-8601 timestamp (UTC)
endDaterequired
string (date-time) | null · data.endDate
ISO-8601 timestamp (UTC)

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/customers/<id>/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.

Count a Switch customer sell rates by view

GET/api/v1/switch/customers/{id}/sell-rates/counts

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

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
currentrequired
integer · data.current
scheduledrequired
integer · data.scheduled
expiringrequired
integer · data.expiring
discontinuedrequired
integer · data.discontinued
allrequired
integer · data.all

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 upcoming sell-rate starts and ends for a Switch customer

GET/api/v1/switch/customers/{id}/sell-rates/upcoming

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

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
subAccountIdrequired
string (uuid) · data[].subAccountId
customerTrunkIdrequired
string (uuid) | null · data[].customerTrunkId
prefixrequired
string · data[].prefix
originPrefixrequired
string · data[].originPrefix
"" = any origin
ratePerUnitrequired
money · data[].ratePerUnit
Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data[].billingIncrement
statusrequired
string · data[].status
active, pending (scheduled) or discontinued
effectiveFromrequired
string (date-time) · data[].effectiveFrom
ISO-8601 timestamp (UTC)
endDaterequired
string (date-time) | null · data[].endDate
ISO-8601 timestamp (UTC)
kindrequired
string · data[].kind
One of starts, ends
atrequired
string (date-time) | null · 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.
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.

Get a Switch customer rate-change notice period and what is queued

GET/api/v1/switch/customers/{id}/sell-rates/notice

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

The notice period you give this customer before a sell-rate increase takes effect, how many sell-rate changes are queued behind it, and who a notice email would go to by default (commercial contacts, then billing contacts, then the portal email; at most 5). Needs the rates.view permission. An unknown customer, or one that is not yours, answers 404.

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
rateNoticeDaysrequired
integer · data.rateNoticeDays
Days of notice before a sell-rate increase takes effect; 0 = none
queuedrequired
integer · data.queued
Sell-rate changes queued and not yet in effect
increasesrequired
integer · data.increases
How many of the queued changes are increases
nextEffectiveFromrequired
string (date-time) | null · data.nextEffectiveFrom
When the soonest queued change takes effect
defaultRecipientsrequired
string[] · data.defaultRecipients
Who a notice goes to when you do not name recipients

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 a Switch customer rate-change notice period

PUT/api/v1/switch/customers/{id}/sell-rates/notice

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

With a notice period, a rise on any of this customer's prices (hand edit, bulk paste, sheet import, markup, sell-deck publish or assignment) is queued and takes effect that many days out, at the next 00:00 UTC; decreases and new destinations still apply at once. 0 = every change applies immediately. The new period applies to rises written from now on; changes already queued keep their dates. Needs the rates.publish permission; the change is audited. Send X-If-Unchanged-Since: <updatedAt you loaded> to have the save refused with 409 STALE_WRITE if someone changed the record since.

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 (uuid)

Request body (application/json)

FieldDescription

rateNoticeDaysrequired
integer
Whole days of notice before an increase takes effect; 0 = none0 to 365

Response 200

FieldDescription

datarequired
object
rateNoticeDaysrequired
integer · data.rateNoticeDays
0 to 365

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/customers/<id>/sell-rates/notice" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rateNoticeDays": 1
}'

Run it here with a test key.

List a Switch customer queued sell-rate changes

GET/api/v1/switch/customers/{id}/sell-rates/notice/changes

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

Every sell-rate change queued for this customer and not yet in effect, with the rate in force today beside it. Soonest first, then by prefix; at most 50,000 rows. The same rows as the CSV the customer receives.

Parameters

idrequired
path · string (uuid)
trunkId
query · string (uuid)
Only this trunk's changes

Response 200

FieldDescription

datarequired
object[]
trunkrequired
string · data[].trunk
The customer trunk's label ("" when it has none)
prefixrequired
string · data[].prefix
originrequired
string · data[].origin
Origin prefix for origin-based pricing; "" when the rate applies from any origin
currentRaterequired
money | null · data[].currentRate
The rate in force today; null for a new destination USD as a decimal string with exactly 6 places, e.g. "0.012500".
newRaterequired
money · data[].newRate
USD as a decimal string with exactly 6 places, e.g. "0.012500".
changePctrequired
number | null · data[].changePct
Percentage move, 2 decimals; null for a new destination
currentIncrementrequired
string | null · data[].currentIncrement
newIncrementrequired
string | null · data[].newIncrement
effectiveFromrequired
string (date-time) · data[].effectiveFrom
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.

Download a Switch customer queued sell-rate changes as CSV

GET/api/v1/switch/customers/{id}/sell-rates/notice/changes.csv

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

The list from GET /switch/customers/{id}/sell-rates/notice/changes as the CSV the customer receives, for you to check or forward.

Parameters

idrequired
path · string (uuid)
trunkId
query · string (uuid)
Only this trunk's changes

Response 200 (text/csv)

An attachment named rate-changes-<customer id>.csv. Columns: trunk, prefix, origin, current_rate, new_rate, change_pct, current_increment, new_increment, effective_from_utc. current_rate is empty for a new destination.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
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.

HTTP

curl "https://packetexchange.io/api/v1/switch/customers/<id>/sell-rates/notice/changes.csv" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Email a Switch customer a rate-change notice

POST/api/v1/switch/customers/{id}/sell-rates/notice/send

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Sends email: Sends an email to a third party.

Emails the customer every queued change with its effective date: a table of the first 100 in the message and the full list (up to 5,000 rows) as CSV in the text part. The email is white-label: it is sent under your brand, replies go to your own support address, and it does not mention PacketExchange. Recipients are to when given (up to 10), otherwise the default recipients from GET .../sell-rates/notice. Answers 400 VALIDATION_ERROR when there are no queued changes, when trunkId is not one of this customer's trunks, or when there is no one to send to. A recipient the mail service refused is listed in failed, not raised as an error. Needs the rates.publish permission; the send is audited. Send X-If-Unchanged-Since: <updatedAt you loaded> to have the save refused with 409 STALE_WRITE if someone changed the record since.

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 (uuid)

Request body (application/json)

FieldDescription

trunkId
string (uuid) | null
Only this trunk's changes; omit for every trunk of the customer
to
string (email)[]
Recipients; omit to use the default recipients
message
string
A note of your own, added under the introductionmax 2000 chars

Response 200

FieldDescription

datarequired
object
sentrequired
string[] · data.sent
Addresses the notice was accepted for
failedrequired
string[] · data.failed
Addresses the mail service refused
rowsrequired
integer · data.rows
Changes in the notice
increasesrequired
integer · data.increases
decreasesrequired
integer · data.decreases
addedrequired
integer · data.added
New destinations (no rate today)
firstEffectiveFromrequired
string (date-time) · data.firstEffectiveFrom
The earliest effective date in the notice

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/customers/<id>/sell-rates/notice/send" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "trunkId": "<trunkId>",
  "to": [
    "you@example.com"
  ]
}'

Run it here with a test key.

Preview discontinuing a Switch customer whole sell deck

POST/api/v1/switch/customers/{id}/sell-rates/discontinue-all/preview

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

Omit the effective fields to act now. Send either effectiveFrom (an instant with an offset) or effectiveLocal plus timezone; a bare date is refused because midnight differs by country.

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 (uuid)

Request body (application/json)

FieldDescription

effectiveFrom
string
An instant with offset, e.g. "2026-10-01T00:00:00Z". A bare date is refused.max 40 chars
effectiveLocal
string
A wall-clock time, e.g. "2026-10-01T00:00"; requires timezonemax 30 chars
timezone
string | null
IANA zone, e.g. Europe/London; always recordedmax 64 chars

Response 200

FieldDescription

datarequired
object
customerLabelrequired
string · data.customerLabel
activeRatesrequired
integer · data.activeRates
scheduledRatesrequired
integer · data.scheduledRates
alreadyDiscontinuedrequired
integer · data.alreadyDiscontinued
endDaterequired
string (date-time) · data.endDate
ISO-8601 timestamp (UTC)
immediaterequired
boolean · data.immediate
timezonerequired
string | null · data.timezone
effectOnNewCallsrequired
string · data.effectOnNewCalls
minutes30drequired
number · data.minutes30d
calls30drequired
integer · data.calls30d
revenue30drequired
number · data.revenue30d
US dollars as a JSON number (computed figure)
impactTruncatedrequired
boolean · data.impactTruncated
samplerequired
object[] · data.sample
prefixrequired
string · data.sample[].prefix
originPrefixrequired
string · data.sample[].originPrefix
ratePerUnitrequired
money · data.sample[].ratePerUnit
USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.sample[].billingIncrement

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/customers/<id>/sell-rates/discontinue-all/preview" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "effectiveFrom": "<effectiveFrom>",
  "effectiveLocal": "<effectiveLocal>"
}'

Run it here with a test key.

Discontinue a Switch customer whole sell deck

POST/api/v1/switch/customers/{id}/sell-rates/discontinue-all

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

Closes every rate's period at the effective moment; nothing is deleted and priced calls keep their rate. New calls fall back to your operator deck, then markup over cost. Omit the effective fields to act now. Send either effectiveFrom (an instant with an offset) or effectiveLocal plus timezone; a bare date is refused because midnight differs by country.

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 (uuid)

Request body (application/json)

FieldDescription

effectiveFrom
string
An instant with offset, e.g. "2026-10-01T00:00:00Z". A bare date is refused.max 40 chars
effectiveLocal
string
A wall-clock time, e.g. "2026-10-01T00:00"; requires timezonemax 30 chars
timezone
string | null
IANA zone, e.g. Europe/London; always recordedmax 64 chars
includeScheduled
boolean

Response 200

FieldDescription

datarequired
object
endDaterequired
string (date-time) · data.endDate
ISO-8601 timestamp (UTC)
effective
any · data.effective
The moment described in words and in the recorded zone
revisionId
string (uuid) | null · data.revisionId
discontinuedrequired
integer · data.discontinued
deletedrequired
integer · data.deleted
Deprecated alias of discontinued; nothing is deleted
scheduledLeftrequired
integer · data.scheduledLeft

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/customers/<id>/sell-rates/discontinue-all" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "effectiveFrom": "<effectiveFrom>",
  "effectiveLocal": "<effectiveLocal>"
}'

Run it here with a test key.

Discontinue one Switch customer sell rate

POST/api/v1/switch/customers/{id}/sell-rates/{rateId}/discontinue

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

Omit the effective fields to act now. Send either effectiveFrom (an instant with an offset) or effectiveLocal plus timezone; a bare date is refused because midnight differs by country.

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 (uuid)
rateIdrequired
path · string (uuid)

Request body (application/json)

FieldDescription

effectiveFrom
string
An instant with offset, e.g. "2026-10-01T00:00:00Z". A bare date is refused.max 40 chars
effectiveLocal
string
A wall-clock time, e.g. "2026-10-01T00:00"; requires timezonemax 30 chars
timezone
string | null
IANA zone, e.g. Europe/London; always recordedmax 64 chars

Response 200

FieldDescription

datarequired
object
endDaterequired
string (date-time) · data.endDate
ISO-8601 timestamp (UTC)
effective
any · data.effective
The moment described in words and in the recorded zone
revisionId
string (uuid) | null · data.revisionId
discontinuedrequired
boolean · data.discontinued
One of true
deletedrequired
boolean · data.deleted
Deprecated alias; the rate is discontinued, not deletedOne of true
immediaterequired
boolean · data.immediate

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/customers/<id>/sell-rates/<rateId>/discontinue" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "effectiveFrom": "<effectiveFrom>",
  "effectiveLocal": "<effectiveLocal>"
}'

Run it here with a test key.

List sell-rate discontinuation events for a Switch customer

GET/api/v1/switch/customers/{id}/sell-rates/discontinuations

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

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object[]
revisionIdrequired
string (uuid) | null · data[].revisionId
discontinuedAtrequired
string (date-time) · data[].discontinuedAt
ISO-8601 timestamp (UTC)
rowsrequired
integer · data[].rows
labelrequired
string · data[].label
effective
any | null · data[].effective
timezonerequired
string | null · data[].timezone
changeModerequired
string | null · data[].changeMode

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.

HTTP

curl "https://packetexchange.io/api/v1/switch/customers/<id>/sell-rates/discontinuations" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Reprice a Switch customer deck as a markup over buy cost

POST/api/v1/switch/customers/{id}/sell-rates/apply-markup

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 (uuid)

Request body (application/json)

FieldDescription

markupPctrequired
number
min -100
prefixes
string[]
Only these prefixes; omit for the whole deck

Response 200

FieldDescription

datarequired
object
updatedrequired
integer · data.updated
skippedrequired
integer · data.skipped
basis
any · data.basis
revisionIdrequired
string (uuid) | null · data.revisionId

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/customers/<id>/sell-rates/apply-markup" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "markupPct": 1
}'

Run it here with a test key.

Export a Switch customer sell rates as CSV

GET/api/v1/switch/customers/{id}/sell-rates.csv

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

Takes the same filters as the list, with buy cost and margin columns.

Parameters

idrequired
path · string (uuid)
search
query · string
Prefix or destination text
view
query · string
Default currentOne of current, scheduled, discontinued, expiring, all
origin
query · string
One of any, origin_only, destination_only
increment
query · string
One of any, custom, inherited
cost
query · string
One of any, missing
margin
query · string
One of any, thin, negative

Response 200 (text/csv)

The filtered sell deck as a CSV attachment.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
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.

Add or replace many Switch customer sell rates

POST/api/v1/switch/customers/{id}/sell-rates/bulk

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 (uuid)

Request body (application/json)

FieldDescription

rowsrequired
object[]
prefixrequired
string · rows[].prefix
max 24 chars
raterequired
number · rows[].rate
min 0
origin
string · rows[].origin
max 24 chars
billingIncrement
string · rows[].billingIncrement
max 10 chars

Response 200

FieldDescription

datarequired
object
appliedrequired
integer · data.applied
revisionIdrequired
string (uuid) | null · data.revisionId

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/customers/<id>/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.

Discontinue one Switch customer sell rate now

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

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

Kept for existing clients: the rate is discontinued immediately, not deleted.

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 (uuid)
rateIdrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
endDaterequired
string (date-time) · data.endDate
ISO-8601 timestamp (UTC)
effective
any · data.effective
The moment described in words and in the recorded zone
revisionId
string (uuid) | null · data.revisionId
discontinuedrequired
boolean · data.discontinued
One of true
deletedrequired
boolean · data.deleted
Deprecated alias; the rate is discontinued, not deletedOne of true
immediaterequired
boolean · data.immediate

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 DELETE "https://packetexchange.io/api/v1/switch/customers/<id>/sell-rates/<rateId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Discontinue every Switch customer sell rate now

POST/api/v1/switch/customers/{id}/sell-rates/clear

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 (uuid)

Response 200

FieldDescription

datarequired
object
endDaterequired
string (date-time) · data.endDate
ISO-8601 timestamp (UTC)
effective
any · data.effective
The moment described in words and in the recorded zone
revisionId
string (uuid) | null · data.revisionId
discontinuedrequired
integer · data.discontinued
deletedrequired
integer · data.deleted
Deprecated alias of discontinued; nothing is deleted
scheduledLeftrequired
integer · data.scheduledLeft

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 scheduled (future-dated) sell rates for a Switch customer

GET/api/v1/switch/customers/{id}/sell-rates/scheduled

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

Parameters

idrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object[]
Same fields as SwitchCustomerSellRate, 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.

Schedule a future Switch customer sell-rate change

POST/api/v1/switch/customers/{id}/sell-rates/schedule

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

The rate becomes active at the effective moment. Omit the effective fields to act now. Send either effectiveFrom (an instant with an offset) or effectiveLocal plus timezone; a bare date is refused because midnight differs by country.

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 (uuid)

Request body (application/json)

FieldDescription

effectiveFrom
string
An instant with offset, e.g. "2026-10-01T00:00:00Z". A bare date is refused.max 40 chars
effectiveLocal
string
A wall-clock time, e.g. "2026-10-01T00:00"; requires timezonemax 30 chars
timezone
string | null
IANA zone, e.g. Europe/London; always recordedmax 64 chars
prefixrequired
string
max 24 chars
raterequired
number
USD per minutemin 0
origin
string
max 24 chars
billingIncrement
string
max 10 chars

Response 201

FieldDescription

datarequired
object
Same fields as SwitchCustomerSellRate, 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/customers/<id>/sell-rates/schedule" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prefix": "44",
  "rate": 1
}'

Run it here with a test key.

Cancel a scheduled Switch customer sell rate

DELETE/api/v1/switch/customers/{id}/sell-rates/scheduled/{rateId}

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 (uuid)
rateIdrequired
path · string (uuid)

Response 200

FieldDescription

datarequired
object
cancelledrequired
boolean · data.cancelled
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

HTTP

curl -X DELETE "https://packetexchange.io/api/v1/switch/customers/<id>/sell-rates/scheduled/<rateId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Set a Switch customer billing cycle and payment terms

POST/api/v1/switch/customers/{id}/billing-settings

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 (uuid)

Request body (application/json)

FieldDescription

billingCycle
string | null
One of weekly, biweekly, monthly, manual
paymentTermsDays
integer | null
0 to 365

Response 200

FieldDescription

datarequired
object
customerIdrequired
string (uuid) · data.customerId
billingCyclerequired
string | null · data.billingCycle
paymentTermsDaysrequired
integer | null · data.paymentTermsDays
nextInvoiceAtrequired
string (date-time) | null · data.nextInvoiceAt
ISO-8601 timestamp (UTC)

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/customers/<id>/billing-settings" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "billingCycle": "weekly",
  "paymentTermsDays": 1
}'

Run it here with a test key.