Switch API reference

Switch: suppliers

Suppliers and providers you buy from: accounts, trunks, admission and diagnostics.

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

BrowseSwitch: suppliers

List providers with their trunks

GET/api/v1/switch/providers

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

Every provider on your switch, each with its trunks (secrets redacted) and endpoint counts, plus trunks not yet assigned to a provider.

Response 200

FieldDescription

datarequired
object
accountsrequired
object[] · data.accounts
idrequired
string (uuid) · data.accounts[].id
namerequired
string · data.accounts[].name
accountCoderequired
string | null · data.accounts[].accountCode
legalNamerequired
string | null · data.accounts[].legalName
tradingNamerequired
string | null · data.accounts[].tradingName
providerTyperequired
string | null · data.accounts[].providerType
One of carrier, aggregator, mno, mvno, sip_provider
countryrequired
string | null · data.accounts[].country
servicesrequired
string[] | null · data.accounts[].services
portalEmailrequired
string | null · data.accounts[].portalEmail
currencyrequired
string · data.accounts[].currency
statusrequired
string · data.accounts[].status
One of draft, pending_approval, testing, active, suspended, terminated
statusNoterequired
string | null · data.accounts[].statusNote
statusChangedAtrequired
string (date-time) | null · data.accounts[].statusChangedAt
ISO-8601 timestamp (UTC)
routablerequired
boolean · data.accounts[].routable
Whether this provider admits new calls at all, given its status
contractStartrequired
string | null · data.accounts[].contractStart
YYYY-MM-DD
contractEndrequired
string | null · data.accounts[].contractEnd
autoRenewrequired
boolean · data.accounts[].autoRenew
rateNoticeDaysrequired
integer | null · data.accounts[].rateNoticeDays
disputeDaysrequired
integer | null · data.accounts[].disputeDays
billingModerequired
string · data.accounts[].billingMode
One of prepaid, postpaid
creditLimitrequired
string | null · data.accounts[].creditLimit
Decimal string with 2 decimal places, e.g. "5000.00"
balancerequired
money · data.accounts[].balance
USD as a decimal string with exactly 6 places, e.g. "0.012500".
paymentTermsDaysrequired
integer | null · data.accounts[].paymentTermsDays
invoiceCyclerequired
string | null · data.accounts[].invoiceCycle
createdAtrequired
string (date-time) · data.accounts[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.accounts[].updatedAt
ISO-8601 timestamp (UTC)
trunksrequired
object[] · data.accounts[].trunks
idrequired
string (uuid) · data.accounts[].trunks[].id
supplierIdrequired
string (uuid) | null · data.accounts[].trunks[].supplierId
The owning provider; null = ungrouped
labelrequired
string · data.accounts[].trunks[].label
sourcerequired
string · data.accounts[].trunks[].source
"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
statusrequired
string · data.accounts[].trunks[].status
One of active, disabled, draft, testing, draining, fault
sipHostrequired
string | null · data.accounts[].trunks[].sipHost
Null on a marketplace trunk: the seller address is never disclosed
sipPortrequired
integer | null · data.accounts[].trunks[].sipPort
transportrequired
string | null · data.accounts[].trunks[].transport
One of udp, tcp, tls
techPrefixrequired
string | null · data.accounts[].trunks[].techPrefix
sipAuthUsernamerequired
string | null · data.accounts[].trunks[].sipAuthUsername
sipAuthPasswordSetrequired
boolean · data.accounts[].trunks[].sipAuthPasswordSet
Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
smppPasswordSetrequired
boolean · data.accounts[].trunks[].smppPasswordSet
mediaModerequired
string · data.accounts[].trunks[].mediaMode
One of proxy, direct
defaultRatePerUnitrequired
money | null · data.accounts[].trunks[].defaultRatePerUnit
Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.accounts[].trunks[].billingIncrement
currencyrequired
string | null · data.accounts[].trunks[].currency
capacityrequired
integer | null · data.accounts[].trunks[].capacity
Max concurrent channels
maxCpsrequired
integer | null · data.accounts[].trunks[].maxCps
settlementModerequired
string · data.accounts[].trunks[].settlementMode
One of ap, prepaid
balancerequired
money · data.accounts[].trunks[].balance
Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
smsDeliveryMethodrequired
string | null · data.accounts[].trunks[].smsDeliveryMethod
One of http, smpp
reachablerequired
boolean | null · data.accounts[].trunks[].reachable
reachCheckedAtrequired
string (date-time) | null · data.accounts[].trunks[].reachCheckedAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.accounts[].trunks[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.accounts[].trunks[].updatedAt
ISO-8601 timestamp (UTC)
endpointCountrequired
integer · data.accounts[].trunks[].endpointCount
endpointsEnabledrequired
integer · data.accounts[].trunks[].endpointsEnabled
trunkCountrequired
integer · data.accounts[].trunkCount
activeTrunksrequired
integer · data.accounts[].activeTrunks
totalCapacityrequired
integer · data.accounts[].totalCapacity
ungroupedrequired
object[] · data.ungrouped
idrequired
string (uuid) · data.ungrouped[].id
supplierIdrequired
string (uuid) | null · data.ungrouped[].supplierId
The owning provider; null = ungrouped
labelrequired
string · data.ungrouped[].label
sourcerequired
string · data.ungrouped[].source
"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
statusrequired
string · data.ungrouped[].status
One of active, disabled, draft, testing, draining, fault
sipHostrequired
string | null · data.ungrouped[].sipHost
Null on a marketplace trunk: the seller address is never disclosed
sipPortrequired
integer | null · data.ungrouped[].sipPort
transportrequired
string | null · data.ungrouped[].transport
One of udp, tcp, tls
techPrefixrequired
string | null · data.ungrouped[].techPrefix
sipAuthUsernamerequired
string | null · data.ungrouped[].sipAuthUsername
sipAuthPasswordSetrequired
boolean · data.ungrouped[].sipAuthPasswordSet
Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
smppPasswordSetrequired
boolean · data.ungrouped[].smppPasswordSet
mediaModerequired
string · data.ungrouped[].mediaMode
One of proxy, direct
defaultRatePerUnitrequired
money | null · data.ungrouped[].defaultRatePerUnit
Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.ungrouped[].billingIncrement
currencyrequired
string | null · data.ungrouped[].currency
capacityrequired
integer | null · data.ungrouped[].capacity
Max concurrent channels
maxCpsrequired
integer | null · data.ungrouped[].maxCps
settlementModerequired
string · data.ungrouped[].settlementMode
One of ap, prepaid
balancerequired
money · data.ungrouped[].balance
Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
smsDeliveryMethodrequired
string | null · data.ungrouped[].smsDeliveryMethod
One of http, smpp
reachablerequired
boolean | null · data.ungrouped[].reachable
reachCheckedAtrequired
string (date-time) | null · data.ungrouped[].reachCheckedAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.ungrouped[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.ungrouped[].updatedAt
ISO-8601 timestamp (UTC)
endpointCountrequired
integer · data.ungrouped[].endpointCount
endpointsEnabledrequired
integer · data.ungrouped[].endpointsEnabled

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 provider

POST/api/v1/switch/providers

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

A provider is the carrier or company that owns one or more supplier trunks.

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

Request body (application/json)

FieldDescription

namerequired
string
max 160 chars
accountCode
string | null
max 40 chars
legalName
string | null
max 200 chars
tradingName
string | null
max 200 chars
providerType
string | null
One of carrier, aggregator, mno, mvno, sip_provider
registrationNumber
string | null
max 80 chars
taxId
string | null
max 80 chars
vatId
string | null
max 80 chars
address
string | null
max 600 chars
country
string | null
max 2 chars
accountManager
string | null
max 160 chars
tags
string[] | null
services
string[] | null
One of termination, origination, did, sms
portalEmail
string (email) | null
max 255 chars
notes
string | null
max 4000 chars
currency
string | null
max 3 chars
status
string
Accepted on create only; later changes go through POST /{id}/statusOne of draft, pending_approval, testing, active, suspended, terminated
contractStart
string | null
max 10 chars
contractEnd
string | null
max 10 chars
autoRenew
boolean
rateNoticeDays
number | string | null
disputeDays
number | string | null
billingMode
string | null
One of prepaid, postpaid
creditLimit
number | string | null
paymentTermsDays
number | string | null
invoiceCycle
string | null
One of weekly, biweekly, monthly
billingTimezone
string | null
max 64 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
accountCoderequired
string | null · data.accountCode
legalNamerequired
string | null · data.legalName
tradingNamerequired
string | null · data.tradingName
providerTyperequired
string | null · data.providerType
One of carrier, aggregator, mno, mvno, sip_provider
countryrequired
string | null · data.country
servicesrequired
string[] | null · data.services
portalEmailrequired
string | null · data.portalEmail
currencyrequired
string · data.currency
statusrequired
string · data.status
One of draft, pending_approval, testing, active, suspended, terminated
statusNoterequired
string | null · data.statusNote
statusChangedAtrequired
string (date-time) | null · data.statusChangedAt
ISO-8601 timestamp (UTC)
routablerequired
boolean · data.routable
Whether this provider admits new calls at all, given its status
contractStartrequired
string | null · data.contractStart
YYYY-MM-DD
contractEndrequired
string | null · data.contractEnd
autoRenewrequired
boolean · data.autoRenew
rateNoticeDaysrequired
integer | null · data.rateNoticeDays
disputeDaysrequired
integer | null · data.disputeDays
billingModerequired
string · data.billingMode
One of prepaid, postpaid
creditLimitrequired
string | null · data.creditLimit
Decimal string with 2 decimal places, e.g. "5000.00"
balancerequired
money · data.balance
USD as a decimal string with exactly 6 places, e.g. "0.012500".
paymentTermsDaysrequired
integer | null · data.paymentTermsDays
invoiceCyclerequired
string | null · data.invoiceCycle
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.
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/providers" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme"
}'

Run it here with a test key.

Get a provider with its trunks, endpoints and contacts

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

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
accountCoderequired
string | null · data.accountCode
legalNamerequired
string | null · data.legalName
tradingNamerequired
string | null · data.tradingName
providerTyperequired
string | null · data.providerType
One of carrier, aggregator, mno, mvno, sip_provider
countryrequired
string | null · data.country
servicesrequired
string[] | null · data.services
portalEmailrequired
string | null · data.portalEmail
currencyrequired
string · data.currency
statusrequired
string · data.status
One of draft, pending_approval, testing, active, suspended, terminated
statusNoterequired
string | null · data.statusNote
statusChangedAtrequired
string (date-time) | null · data.statusChangedAt
ISO-8601 timestamp (UTC)
routablerequired
boolean · data.routable
Whether this provider admits new calls at all, given its status
contractStartrequired
string | null · data.contractStart
YYYY-MM-DD
contractEndrequired
string | null · data.contractEnd
autoRenewrequired
boolean · data.autoRenew
rateNoticeDaysrequired
integer | null · data.rateNoticeDays
disputeDaysrequired
integer | null · data.disputeDays
billingModerequired
string · data.billingMode
One of prepaid, postpaid
creditLimitrequired
string | null · data.creditLimit
Decimal string with 2 decimal places, e.g. "5000.00"
balancerequired
money · data.balance
USD as a decimal string with exactly 6 places, e.g. "0.012500".
paymentTermsDaysrequired
integer | null · data.paymentTermsDays
invoiceCyclerequired
string | null · data.invoiceCycle
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
contactsrequired
object[] · data.contacts
idrequired
string (uuid) · data.contacts[].id
supplierIdrequired
string (uuid) · data.contacts[].supplierId
rolerequired
string · data.contacts[].role
One of noc, rates, billing, finance, fraud, account, emergency
namerequired
string | null · data.contacts[].name
emailrequired
string | null · data.contacts[].email
phonerequired
string | null · data.contacts[].phone
timezonerequired
string | null · data.contacts[].timezone
notifyrequired
boolean · data.contacts[].notify
notesrequired
string | null · data.contacts[].notes
createdAtrequired
string (date-time) · data.contacts[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.contacts[].updatedAt
ISO-8601 timestamp (UTC)
trunksrequired
object[] · data.trunks
idrequired
string (uuid) · data.trunks[].id
supplierIdrequired
string (uuid) | null · data.trunks[].supplierId
The owning provider; null = ungrouped
labelrequired
string · data.trunks[].label
sourcerequired
string · data.trunks[].source
"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
statusrequired
string · data.trunks[].status
One of active, disabled, draft, testing, draining, fault
sipHostrequired
string | null · data.trunks[].sipHost
Null on a marketplace trunk: the seller address is never disclosed
sipPortrequired
integer | null · data.trunks[].sipPort
transportrequired
string | null · data.trunks[].transport
One of udp, tcp, tls
techPrefixrequired
string | null · data.trunks[].techPrefix
sipAuthUsernamerequired
string | null · data.trunks[].sipAuthUsername
sipAuthPasswordSetrequired
boolean · data.trunks[].sipAuthPasswordSet
Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
smppPasswordSetrequired
boolean · data.trunks[].smppPasswordSet
mediaModerequired
string · data.trunks[].mediaMode
One of proxy, direct
defaultRatePerUnitrequired
money | null · data.trunks[].defaultRatePerUnit
Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.trunks[].billingIncrement
currencyrequired
string | null · data.trunks[].currency
capacityrequired
integer | null · data.trunks[].capacity
Max concurrent channels
maxCpsrequired
integer | null · data.trunks[].maxCps
settlementModerequired
string · data.trunks[].settlementMode
One of ap, prepaid
balancerequired
money · data.trunks[].balance
Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
smsDeliveryMethodrequired
string | null · data.trunks[].smsDeliveryMethod
One of http, smpp
reachablerequired
boolean | null · data.trunks[].reachable
reachCheckedAtrequired
string (date-time) | null · data.trunks[].reachCheckedAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.trunks[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.trunks[].updatedAt
ISO-8601 timestamp (UTC)
endpointsrequired
object[] · data.trunks[].endpoints
idrequired
string (uuid) · data.trunks[].endpoints[].id
vendorTrunkIdrequired
string (uuid) · data.trunks[].endpoints[].vendorTrunkId
rolerequired
string · data.trunks[].endpoints[].role
One of primary, backup
hostrequired
string | null · data.trunks[].endpoints[].host
Null on a marketplace trunk
portrequired
integer | null · data.trunks[].endpoints[].port
transportrequired
string · data.trunks[].endpoints[].transport
One of udp, tcp, tls
priorityrequired
integer · data.trunks[].endpoints[].priority
weightPctrequired
integer | null · data.trunks[].endpoints[].weightPct
enabledrequired
boolean · data.trunks[].endpoints[].enabled
optionsIntervalSecondsrequired
integer | null · data.trunks[].endpoints[].optionsIntervalSeconds
failureThresholdrequired
integer · data.trunks[].endpoints[].failureThreshold
recoveryThresholdrequired
integer · data.trunks[].endpoints[].recoveryThreshold
autoDisablerequired
boolean · data.trunks[].endpoints[].autoDisable
reachablerequired
boolean | null · data.trunks[].endpoints[].reachable
reachLatencyMsrequired
integer | null · data.trunks[].endpoints[].reachLatencyMs
reachCheckedAtrequired
string (date-time) | null · data.trunks[].endpoints[].reachCheckedAt
ISO-8601 timestamp (UTC)
healthDisabledAtrequired
string (date-time) | null · data.trunks[].endpoints[].healthDisabledAt
ISO-8601 timestamp (UTC)
healthrequired
object · data.trunks[].endpoints[].health
Derived health state (what routing believes), with its counters and thresholds
flap
object | null · data.trunks[].endpoints[].flap
createdAtrequired
string (date-time) · data.trunks[].endpoints[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.trunks[].endpoints[].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.

Update a provider

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

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

Partial update; status is changed through POST /{id}/status instead. Send X-If-Unchanged-Since: <updatedAt you loaded> to be refused with 409 STALE_WRITE if someone else saved in between.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

name
string
max 160 chars
accountCode
string | null
max 40 chars
legalName
string | null
max 200 chars
tradingName
string | null
max 200 chars
providerType
string | null
One of carrier, aggregator, mno, mvno, sip_provider
registrationNumber
string | null
max 80 chars
taxId
string | null
max 80 chars
vatId
string | null
max 80 chars
address
string | null
max 600 chars
country
string | null
max 2 chars
accountManager
string | null
max 160 chars
tags
string[] | null
services
string[] | null
One of termination, origination, did, sms
portalEmail
string (email) | null
max 255 chars
notes
string | null
max 4000 chars
currency
string | null
max 3 chars
status
string
Accepted on create only; later changes go through POST /{id}/statusOne of draft, pending_approval, testing, active, suspended, terminated
contractStart
string | null
max 10 chars
contractEnd
string | null
max 10 chars
autoRenew
boolean
rateNoticeDays
number | string | null
disputeDays
number | string | null
billingMode
string | null
One of prepaid, postpaid
creditLimit
number | string | null
paymentTermsDays
number | string | null
invoiceCycle
string | null
One of weekly, biweekly, monthly
billingTimezone
string | null
max 64 chars

Response 200

FieldDescription

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

Run it here with a test key.

Delete a provider

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

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

Its trunks are NOT deleted: they are detached (ungrouped) with their routing intact.

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true
detachedTrunksrequired
integer · data.detachedTrunks

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

Change a provider lifecycle status

POST/api/v1/switch/providers/{id}/status

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

Stops or resumes traffic on every trunk of the provider. The response says whether traffic changed and how many active trunks were affected.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

statusrequired
string
One of draft, pending_approval, testing, active, suspended, terminated
note
string | null
max 1000 chars

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
accountCoderequired
string | null · data.accountCode
legalNamerequired
string | null · data.legalName
tradingNamerequired
string | null · data.tradingName
providerTyperequired
string | null · data.providerType
One of carrier, aggregator, mno, mvno, sip_provider
countryrequired
string | null · data.country
servicesrequired
string[] | null · data.services
portalEmailrequired
string | null · data.portalEmail
currencyrequired
string · data.currency
statusrequired
string · data.status
One of draft, pending_approval, testing, active, suspended, terminated
statusNoterequired
string | null · data.statusNote
statusChangedAtrequired
string (date-time) | null · data.statusChangedAt
ISO-8601 timestamp (UTC)
routablerequired
boolean · data.routable
Whether this provider admits new calls at all, given its status
contractStartrequired
string | null · data.contractStart
YYYY-MM-DD
contractEndrequired
string | null · data.contractEnd
autoRenewrequired
boolean · data.autoRenew
rateNoticeDaysrequired
integer | null · data.rateNoticeDays
disputeDaysrequired
integer | null · data.disputeDays
billingModerequired
string · data.billingMode
One of prepaid, postpaid
creditLimitrequired
string | null · data.creditLimit
Decimal string with 2 decimal places, e.g. "5000.00"
balancerequired
money · data.balance
USD as a decimal string with exactly 6 places, e.g. "0.012500".
paymentTermsDaysrequired
integer | null · data.paymentTermsDays
invoiceCyclerequired
string | null · data.invoiceCycle
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
trafficChangerequired
string · data.trafficChange
One of none, resumed, stopped
affectedTrunksrequired
integer · data.affectedTrunks

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

Run it here with a test key.

List a provider contacts

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

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

Parameters

idrequired
path · string

Response 200

FieldDescription

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

Add a provider contact

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

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

One contact per role (NOC, rates, billing, finance, fraud, account, emergency).

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

rolerequired
string
One of noc, rates, billing, finance, fraud, account, emergency
name
string | null
max 160 chars
email
string | null
max 255 chars
phone
string | null
max 40 chars
timezone
string | null
max 64 chars
notify
boolean
notes
string | null
max 1000 chars

Response 201

FieldDescription

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

Run it here with a test key.

Update a provider contact

PATCH/api/v1/switch/providers/{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
contactIdrequired
path · string

Request body (application/json)

FieldDescription

role
string
One of noc, rates, billing, finance, fraud, account, emergency
name
string | null
max 160 chars
email
string | null
max 255 chars
phone
string | null
max 40 chars
timezone
string | null
max 64 chars
notify
boolean
notes
string | null
max 1000 chars

Response 200

FieldDescription

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

Run it here with a test key.

Delete a provider contact

DELETE/api/v1/switch/providers/{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
contactIdrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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

HTTP

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

Run it here with a test key.

List providers with their trunks

GET/api/v1/switch/supplier-accounts

Deprecated

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

Every provider on your switch, each with its trunks (secrets redacted) and endpoint counts, plus trunks not yet assigned to a provider. Deprecated alias of the same operation under /switch/providers.

Response 200

FieldDescription

datarequired
object
Same fields as SwitchProviderList, 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.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Create a provider

POST/api/v1/switch/supplier-accounts

Deprecated

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

A provider is the carrier or company that owns one or more supplier trunks. Deprecated alias of the same operation under /switch/providers.

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

Request body (application/json)

FieldDescription

namerequired
string
max 160 chars
accountCode
string | null
max 40 chars
legalName
string | null
max 200 chars
tradingName
string | null
max 200 chars
providerType
string | null
One of carrier, aggregator, mno, mvno, sip_provider
registrationNumber
string | null
max 80 chars
taxId
string | null
max 80 chars
vatId
string | null
max 80 chars
address
string | null
max 600 chars
country
string | null
max 2 chars
accountManager
string | null
max 160 chars
tags
string[] | null
services
string[] | null
One of termination, origination, did, sms
portalEmail
string (email) | null
max 255 chars
notes
string | null
max 4000 chars
currency
string | null
max 3 chars
status
string
Accepted on create only; later changes go through POST /{id}/statusOne of draft, pending_approval, testing, active, suspended, terminated
contractStart
string | null
max 10 chars
contractEnd
string | null
max 10 chars
autoRenew
boolean
rateNoticeDays
number | string | null
disputeDays
number | string | null
billingMode
string | null
One of prepaid, postpaid
creditLimit
number | string | null
paymentTermsDays
number | string | null
invoiceCycle
string | null
One of weekly, biweekly, monthly
billingTimezone
string | null
max 64 chars

Response 201

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/supplier-accounts" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme"
}'

Run it here with a test key.

Get a provider with its trunks, endpoints and contacts

GET/api/v1/switch/supplier-accounts/{id}

Deprecated

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

Deprecated alias of the same operation under /switch/providers.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
Same fields as SwitchProviderDetail, 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.

Update a provider

PATCH/api/v1/switch/supplier-accounts/{id}

Deprecated

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

Partial update; status is changed through POST /{id}/status instead. Send X-If-Unchanged-Since: <updatedAt you loaded> to be refused with 409 STALE_WRITE if someone else saved in between. Deprecated alias of the same operation under /switch/providers.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

name
string
max 160 chars
accountCode
string | null
max 40 chars
legalName
string | null
max 200 chars
tradingName
string | null
max 200 chars
providerType
string | null
One of carrier, aggregator, mno, mvno, sip_provider
registrationNumber
string | null
max 80 chars
taxId
string | null
max 80 chars
vatId
string | null
max 80 chars
address
string | null
max 600 chars
country
string | null
max 2 chars
accountManager
string | null
max 160 chars
tags
string[] | null
services
string[] | null
One of termination, origination, did, sms
portalEmail
string (email) | null
max 255 chars
notes
string | null
max 4000 chars
currency
string | null
max 3 chars
status
string
Accepted on create only; later changes go through POST /{id}/statusOne of draft, pending_approval, testing, active, suspended, terminated
contractStart
string | null
max 10 chars
contractEnd
string | null
max 10 chars
autoRenew
boolean
rateNoticeDays
number | string | null
disputeDays
number | string | null
billingMode
string | null
One of prepaid, postpaid
creditLimit
number | string | null
paymentTermsDays
number | string | null
invoiceCycle
string | null
One of weekly, biweekly, monthly
billingTimezone
string | null
max 64 chars

Response 200

FieldDescription

datarequired
object
Same fields as SwitchProvider, 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/supplier-accounts/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "accountCode": "<accountCode>"
}'

Run it here with a test key.

Delete a provider

DELETE/api/v1/switch/supplier-accounts/{id}

Deprecated

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

Its trunks are NOT deleted: they are detached (ungrouped) with their routing intact. Deprecated alias of the same operation under /switch/providers.

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true
detachedTrunksrequired
integer · data.detachedTrunks

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

Change a provider lifecycle status

POST/api/v1/switch/supplier-accounts/{id}/status

Deprecated

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

Stops or resumes traffic on every trunk of the provider. The response says whether traffic changed and how many active trunks were affected. Deprecated alias of the same operation under /switch/providers.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

statusrequired
string
One of draft, pending_approval, testing, active, suspended, terminated
note
string | null
max 1000 chars

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
accountCoderequired
string | null · data.accountCode
legalNamerequired
string | null · data.legalName
tradingNamerequired
string | null · data.tradingName
providerTyperequired
string | null · data.providerType
One of carrier, aggregator, mno, mvno, sip_provider
countryrequired
string | null · data.country
servicesrequired
string[] | null · data.services
portalEmailrequired
string | null · data.portalEmail
currencyrequired
string · data.currency
statusrequired
string · data.status
One of draft, pending_approval, testing, active, suspended, terminated
statusNoterequired
string | null · data.statusNote
statusChangedAtrequired
string (date-time) | null · data.statusChangedAt
ISO-8601 timestamp (UTC)
routablerequired
boolean · data.routable
Whether this provider admits new calls at all, given its status
contractStartrequired
string | null · data.contractStart
YYYY-MM-DD
contractEndrequired
string | null · data.contractEnd
autoRenewrequired
boolean · data.autoRenew
rateNoticeDaysrequired
integer | null · data.rateNoticeDays
disputeDaysrequired
integer | null · data.disputeDays
billingModerequired
string · data.billingMode
One of prepaid, postpaid
creditLimitrequired
string | null · data.creditLimit
Decimal string with 2 decimal places, e.g. "5000.00"
balancerequired
money · data.balance
USD as a decimal string with exactly 6 places, e.g. "0.012500".
paymentTermsDaysrequired
integer | null · data.paymentTermsDays
invoiceCyclerequired
string | null · data.invoiceCycle
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
trafficChangerequired
string · data.trafficChange
One of none, resumed, stopped
affectedTrunksrequired
integer · data.affectedTrunks

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

Run it here with a test key.

List a provider contacts

GET/api/v1/switch/supplier-accounts/{id}/contacts

Deprecated

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

Deprecated alias of the same operation under /switch/providers.

Parameters

idrequired
path · string

Response 200

FieldDescription

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

Add a provider contact

POST/api/v1/switch/supplier-accounts/{id}/contacts

Deprecated

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

One contact per role (NOC, rates, billing, finance, fraud, account, emergency). Deprecated alias of the same operation under /switch/providers.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

rolerequired
string
One of noc, rates, billing, finance, fraud, account, emergency
name
string | null
max 160 chars
email
string | null
max 255 chars
phone
string | null
max 40 chars
timezone
string | null
max 64 chars
notify
boolean
notes
string | null
max 1000 chars

Response 201

FieldDescription

datarequired
object
Same fields as SwitchProviderContact, 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/supplier-accounts/<id>/contacts" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "noc"
}'

Run it here with a test key.

Update a provider contact

PATCH/api/v1/switch/supplier-accounts/{id}/contacts/{contactId}

Deprecated

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

Deprecated alias of the same operation under /switch/providers.

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

Request body (application/json)

FieldDescription

role
string
One of noc, rates, billing, finance, fraud, account, emergency
name
string | null
max 160 chars
email
string | null
max 255 chars
phone
string | null
max 40 chars
timezone
string | null
max 64 chars
notify
boolean
notes
string | null
max 1000 chars

Response 200

FieldDescription

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

Run it here with a test key.

Delete a provider contact

DELETE/api/v1/switch/supplier-accounts/{id}/contacts/{contactId}

Deprecated

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

Deprecated alias of the same operation under /switch/providers.

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

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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

HTTP

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

Run it here with a test key.

Get call totals for a provider across its trunks

GET/api/v1/switch/providers/{id}/call-records

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

Calls, answer rate, minutes and cost over a window, overall and per trunk. cost and minutes are JSON numbers here (report figures, not ledger amounts).

Parameters

idrequired
path · string
from
query · string
ISO start of the window
to
query · string
ISO end of the window
limit
query · string
offset
query · string

Response 200

FieldDescription

datarequired
object
windowrequired
object · data.window
fromrequired
string · data.window.from
torequired
string · data.window.to
summaryrequired
object · data.summary
callsrequired
number · data.summary.calls
answeredrequired
number · data.summary.answered
asrrequired
number | null · data.summary.asr
minutesrequired
number · data.summary.minutes
costrequired
number · data.summary.cost
acdrequired
number | null · data.summary.acd
avgPddMsrequired
number | null · data.summary.avgPddMs
byTrunkrequired
object[] · data.byTrunk
trunkIdrequired
string (uuid) | null · data.byTrunk[].trunkId
labelrequired
string · data.byTrunk[].label
callsrequired
number · data.byTrunk[].calls
answeredrequired
number · data.byTrunk[].answered
asrrequired
number | null · data.byTrunk[].asr
minutesrequired
number · data.byTrunk[].minutes
costrequired
number · data.byTrunk[].cost

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 provider payables and unbilled cost

GET/api/v1/switch/providers/{id}/invoices

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

The provider billing terms, its payable documents, and cost carried since the last one that has not been raised yet (a JSON number).

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
currencyrequired
string · data.currency
billingModerequired
string · data.billingMode
creditLimitrequired
string | null · data.creditLimit
Decimal string with 2 decimal places, e.g. "5000.00"
paymentTermsDaysrequired
integer | null · data.paymentTermsDays
invoiceCyclerequired
string | null · data.invoiceCycle
invoicesrequired
object[] · data.invoices
unbilledrequired
object · data.unbilled
sincerequired
string | null · data.unbilled.since
callsrequired
number · data.unbilled.calls
minutesrequired
number · data.unbilled.minutes
costrequired
number · data.unbilled.cost

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 is wrong with a provider right now

GET/api/v1/switch/providers/{id}/alerts

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

Derived on every read, never stored: unroutable status, trunks in fault or draining, expiring credentials, expired trunks.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
alertsrequired
object[] · data.alerts
severityrequired
string · data.alerts[].severity
One of critical, warning, info
coderequired
string · data.alerts[].code
messagerequired
string · data.alerts[].message
trunkId
string (uuid) · data.alerts[].trunkId

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 the change history for a provider and its trunks

GET/api/v1/switch/providers/{id}/audit

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

Parameters

idrequired
path · string
limit
query · string
Max entries (default 100)

Response 200

FieldDescription

datarequired
object
entriesrequired
object[] · data.entries

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 billing disputes with a provider

GET/api/v1/switch/providers/{id}/disputes

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
supplierIdrequired
string (uuid) · data[].supplierId
periodStartrequired
string (date-time) | null · data[].periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data[].periodEnd
ISO-8601 timestamp (UTC)
ourAmountrequired
string | null · data[].ourAmount
Decimal string with 2 decimal places, e.g. "5000.00"
theirAmountrequired
string | null · data[].theirAmount
Decimal string with 2 decimal places, e.g. "5000.00"
currencyrequired
string · data[].currency
statusrequired
string · data[].status
One of open, submitted, accepted, rejected, settled, withdrawn
reasonrequired
string | null · data[].reason
resolutionrequired
string | null · data[].resolution
invoiceRefrequired
string | null · data[].invoiceRef
openedAtrequired
string (date-time) · data[].openedAt
ISO-8601 timestamp (UTC)
respondByrequired
string (date-time) | null · data[].respondBy
ISO-8601 timestamp (UTC)
closedAtrequired
string (date-time) | null · data[].closedAt
ISO-8601 timestamp (UTC)
daysLeft
integer | null · data[].daysLeft
Days left to respond (list only); negative = the window has passed
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.

Open a billing dispute with a provider

POST/api/v1/switch/providers/{id}/disputes

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

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

periodStart
string | null
max 40 chars
periodEnd
string | null
max 40 chars
ourAmount
number | string | null
theirAmount
number | string | null
currency
string | null
max 3 chars
reason
string | null
max 4000 chars
resolution
string | null
max 4000 chars
invoiceRef
string | null
max 120 chars
status
string
One of open, submitted, accepted, rejected, settled, withdrawn

Response 201

FieldDescription

datarequired
object
Same fields as SwitchProviderDispute, 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/providers/<id>/disputes" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "periodStart": "<periodStart>",
  "periodEnd": "<periodEnd>"
}'

Run it here with a test key.

Update a billing dispute

PATCH/api/v1/switch/providers/{id}/disputes/{disputeId}

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
disputeIdrequired
path · string

Request body (application/json)

FieldDescription

periodStart
string | null
max 40 chars
periodEnd
string | null
max 40 chars
ourAmount
number | string | null
theirAmount
number | string | null
currency
string | null
max 3 chars
reason
string | null
max 4000 chars
resolution
string | null
max 4000 chars
invoiceRef
string | null
max 120 chars
status
string
One of open, submitted, accepted, rejected, settled, withdrawn

Response 200

FieldDescription

datarequired
object
Same fields as SwitchProviderDispute, 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/providers/<id>/disputes/<disputeId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "periodStart": "<periodStart>",
  "periodEnd": "<periodEnd>"
}'

Run it here with a test key.

List SIP endpoints of a supplier trunk

GET/api/v1/switch/suppliers/{id}/endpoints

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

Primary and backup addresses with derived health and flap reports. A trunk with an address but no endpoint rows has its address adopted as endpoint 1 on first read.

Parameters

idrequired
path · string

Response 200

FieldDescription

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

Add a SIP endpoint to a supplier trunk

POST/api/v1/switch/suppliers/{id}/endpoints

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

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

role
string
One of primary, backup
hostrequired
string
max 255 chars
port
number | string | null
transport
string
One of udp, tcp, tls
priority
number | string
weightPct
number | string | null
enabled
boolean
optionsIntervalSeconds
number | string | null
failureThreshold
number | string
recoveryThreshold
number | string
autoDisable
boolean

Response 201

FieldDescription

datarequired
object
Same fields as SwitchTrunkEndpoint, 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/suppliers/<id>/endpoints" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "host": "203.0.113.10"
}'

Run it here with a test key.

Update a SIP endpoint

PATCH/api/v1/switch/suppliers/{id}/endpoints/{endpointId}

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
endpointIdrequired
path · string

Request body (application/json)

FieldDescription

role
string
One of primary, backup
host
string
max 255 chars
port
number | string | null
transport
string
One of udp, tcp, tls
priority
number | string
weightPct
number | string | null
enabled
boolean
optionsIntervalSeconds
number | string | null
failureThreshold
number | string
recoveryThreshold
number | string
autoDisable
boolean

Response 200

FieldDescription

datarequired
object
Same fields as SwitchTrunkEndpoint, 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/suppliers/<id>/endpoints/<endpointId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "primary",
  "host": "203.0.113.10"
}'

Run it here with a test key.

Remove a SIP endpoint

DELETE/api/v1/switch/suppliers/{id}/endpoints/{endpointId}

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

The last endpoint of a trunk cannot be removed: add its replacement first.

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

Parameters

idrequired
path · string
endpointIdrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X DELETE "https://packetexchange.io/api/v1/switch/suppliers/<id>/endpoints/<endpointId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Render the SBC gateway configuration for a supplier trunk

GET/api/v1/switch/suppliers/{id}/sbc-profile

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

Read-only. Names which settings are profile-level (and so need a deploy) rather than applied per call. Each read is recorded in the audit log.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
trunkIdrequired
string (uuid) · data.trunkId
trunkLabelrequired
string · data.trunkLabel
profileLevelrequired
object[] · data.profileLevel
endpointIdrequired
string (uuid) · data.profileLevel[].endpointId
hostrequired
string · data.profileLevel[].host
settingsrequired
string[] · data.profileLevel[].settings
xmlrequired
string · data.xml
Gateway configuration to place on the SBC
applyNoterequired
string · data.applyNote

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.

Render the SBC gateway configuration for a provider

GET/api/v1/switch/providers/{id}/sbc-profile

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

Read-only. One rendered profile per trunk; needsReload says whether any of it needs deploying. Each read is recorded in the audit log.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
supplierIdrequired
string (uuid) · data.supplierId
supplierNamerequired
string · data.supplierName
trunksrequired
object[] · data.trunks
Same fields as SwitchSbcProfile, shown earlier on this page.
needsReloadrequired
boolean · data.needsReload

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 health events for a supplier trunk

GET/api/v1/switch/suppliers/{id}/health-events

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

Probe results, up/down transitions, auto-disables, restores and degradations. Probe rows are kept 7 days, state changes 90 days. Page with before = the previous nextBefore.

Parameters

idrequired
path · string
endpointId
query · string (uuid)
days
query · integer
kinds
query · string
Comma-separated: probe, transition, auto_disable, restore, degraded
before
query · string
ISO cursor from nextBefore
limit
query · integer

Response 200

FieldDescription

datarequired
object
eventsrequired
object[] · data.events
windowDaysrequired
integer · data.windowDays
retentionrequired
object · data.retention
probeDaysrequired
integer · data.retention.probeDays
eventDaysrequired
integer · data.retention.eventDays
nextBeforerequired
string | null · data.nextBefore

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 the flap report for a supplier trunk

GET/api/v1/switch/suppliers/{id}/flap-report

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

Endpoints that changed state repeatedly in the window. Observe-only: nothing is disabled because of it.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
windowHoursrequired
number · data.windowHours
minTransitionsrequired
integer · data.minTransitions
endpointsrequired
object[] · data.endpoints
endpointIdrequired
string (uuid) | null · data.endpoints[].endpointId
hostrequired
string | null · data.endpoints[].host
transitionsrequired
integer · data.endpoints[].transitions
firstAtrequired
string (date-time) · data.endpoints[].firstAt
ISO-8601 timestamp (UTC)
lastAtrequired
string (date-time) · data.endpoints[].lastAt
ISO-8601 timestamp (UTC)
flappingrequired
boolean · data.endpoints[].flapping
flappingrequired
boolean · data.flapping

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.

Send a test call to a supplier trunk

POST/api/v1/switch/suppliers/{id}/test-call

Access: API key. Scoped keys need switch:manage.
Rate limit: 6 requests per minute
Real traffic: Places a real test call or sends a real test SMS over the trunk.

A real INVITE from every media worker, on demand. Never touches health counters or state. Address details are withheld for a marketplace trunk. Audited.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

endpointId
string (uuid) | null

Response 200

FieldDescription

datarequired
object
ranAtrequired
string (date-time) · data.ranAt
ISO-8601 timestamp (UTC)
hostrequired
string | null · data.host
portrequired
integer | null · data.port
techPrefixrequired
string | null · data.techPrefix
verdictrequired
string · data.verdict
latencyMsrequired
integer · data.latencyMs
diagnosticsrequired
object · data.diagnostics
endpointHidden
boolean · data.endpointHidden

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/suppliers/<id>/test-call" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "endpointId": "<endpointId>"
}'

Run it here with a test key.

Move a supplier trunk to another provider

POST/api/v1/switch/suppliers/{id}/assign-account

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

Pass supplierId: null to ungroup the 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

Request body (application/json)

FieldDescription

supplierIdrequired
string (uuid) | null

Response 200

FieldDescription

datarequired
object
A supplier (vendor) trunk. Carries every spec section-4 policy field accepted on create/update; secrets are replaced by *Set booleans.
idrequired
string (uuid) · data.id
supplierIdrequired
string (uuid) | null · data.supplierId
The owning provider; null = ungrouped
labelrequired
string · data.label
sourcerequired
string · data.source
"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
statusrequired
string · data.status
One of active, disabled, draft, testing, draining, fault
sipHostrequired
string | null · data.sipHost
Null on a marketplace trunk: the seller address is never disclosed
sipPortrequired
integer | null · data.sipPort
transportrequired
string | null · data.transport
One of udp, tcp, tls
techPrefixrequired
string | null · data.techPrefix
sipAuthUsernamerequired
string | null · data.sipAuthUsername
sipAuthPasswordSetrequired
boolean · data.sipAuthPasswordSet
Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
smppPasswordSetrequired
boolean · data.smppPasswordSet
mediaModerequired
string · data.mediaMode
One of proxy, direct
defaultRatePerUnitrequired
money | null · data.defaultRatePerUnit
Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.billingIncrement
currencyrequired
string | null · data.currency
capacityrequired
integer | null · data.capacity
Max concurrent channels
maxCpsrequired
integer | null · data.maxCps
settlementModerequired
string · data.settlementMode
One of ap, prepaid
balancerequired
money · data.balance
Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
smsDeliveryMethodrequired
string | null · data.smsDeliveryMethod
One of http, smpp
reachablerequired
boolean | null · data.reachable
reachCheckedAtrequired
string (date-time) | null · data.reachCheckedAt
ISO-8601 timestamp (UTC)
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/suppliers/<id>/assign-account" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "supplierId": "<supplierId>"
}'

Run it here with a test key.

List supplier trunks

GET/api/v1/switch/suppliers

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

Every vendor trunk on your switch, newest first. SIP and SMPP secrets are replaced by *Set booleans.

Response 200

FieldDescription

datarequired
object[]
Same fields as SwitchSupplierTrunk, 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.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Create a supplier trunk

POST/api/v1/switch/suppliers

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

A trunk needs at least one reachable endpoint: a SIP host, an HTTPS SMS delivery URL, or an SMPP host.

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
supplierId
string (uuid) | null
sipHost
string | null
max 255 chars
sipPort
integer | null
1 to 65535
transport
string | null
One of udp, tcp, tls
techPrefix
string | null
max 24 chars
sipAuthUsername
string | null
max 128 chars
sipAuthPassword
string | null
max 128 chars
supportedCodecs
string[] | null
defaultRatePerUnit
number | null
min 0
mediaMode
string
One of proxy, direct
billingIncrement
string | null
max 10 chars
currency
string | null
max 3 chars
capacity
integer | null
min 0
maxCps
integer | null
min 0
status
string
One of active, disabled, draft, testing, draining, fault
settlementMode
string
One of ap, prepaid
balance
number | null
min 0
portalEmail
string (email) | null
max 255 chars
smsDeliveryUrl
string (uri) | null
max 500 chars
smsDeliveryMethod
string | null
One of http, smpp
smppHost
string | null
max 255 chars
smppPort
integer | null
1 to 65535
smppSystemId
string | null
smppPassword
string | null
max 64 chars
smppBindType
string | null
One of transceiver, transmitter
smppSystemType
string | null
max 13 chars
smppTps
integer | null
1 to 1000
code
string | null
max 40 chars
description
string | null
max 2000 chars
product
string | null
max 32 chars
direction
string
One of termination, origination, bidirectional
testMode
boolean
activationDate
string | null
max 10 chars
expirationDate
string | null
max 10 chars
tags
string[] | null
notes
string | null
max 4000 chars
credentialExpiresAt
string | null
max 40 chars
credentialRotatedAt
string | null
max 40 chars
allowedSourceNetworks
string[] | null
requestRateLimit
integer | null
0 to 100000
sipRegister
boolean
sipRealm
string | null
max 255 chars
incomingTechPrefix
string | null
max 24 chars
techPrefixMode
string
One of add, remove, replace
techPrefixSeparator
string | null
max 4 chars
cliRewrite
any | null
dnisRewrite
any | null
cliPolicy
string
One of passthrough, replace, remove, pool
cliPoolId
string (uuid) | null
anonymousPolicy
string
One of passthrough, reject, substitute
e164Normalise
boolean
defaultCountryCode
string | null
max 6 chars
minDnisLength
integer | null
0 to 32
maxDnisLength
integer | null
0 to 32
paiPolicy
string
One of omit, passthrough, generate
rpidPolicy
string
One of omit, passthrough, generate
diversionPolicy
string
One of omit, passthrough, generate
historyInfoPolicy
string
One of omit, passthrough, generate
lrnPolicy
string
One of none, passthrough, strip
packetizationMs
integer | null
10 to 120
codecMode
string
One of transparent, transcode
forcedCodec
string | null
max 24 chars
srtpMode
string
One of disabled, optional, required
dtmfMode
string
One of rfc2833, info, inband, auto
t38Mode
string
One of disabled, passthrough, relay
comfortNoise
boolean
silenceSuppression
boolean
symmetricRtp
boolean
inviteTimeoutSeconds
integer | null
1 to 600
pddTimeoutSeconds
integer | null
1 to 600
ringTimeoutSeconds
integer | null
1 to 600
sessionExpiresSeconds
integer | null
90 to 86400
minSeSeconds
integer | null
90 to 86400
prackMode
string
One of disabled, supported, required
allowReinvite
boolean
allowUpdate
boolean
allowRefer
boolean
earlyMediaPolicy
string
One of passthrough, generate_ringback, suppress
recordRoute
boolean
customHeaders
object | null
q850Map
object | null
cpsBurst
integer | null
0 to 10000
queueLimit
integer | null
0 to 100000
maxChannelsPerDestination
integer | null
0 to 100000
maxCpsPerDestination
integer | null
0 to 10000
minCallSeconds
integer | null
0 to 86400
maxCallSeconds
integer | null
0 to 86400
dailyMinutesCap
integer | null
min 0
dailySpendCap
number | string | null
monthlySpendCap
number | string | null
rampupChannels
integer | null
0 to 100000
rampupDays
integer | null
0 to 365
allowedPrefixes
string[] | null
blockedPrefixes
string[] | null
allowedCountries
string[] | null
blockedCountries
string[] | null
allowMobile
boolean
allowFixed
boolean
allowSatellite
boolean
allowPremium
boolean
allowTollfree
boolean
allowEmergency
boolean
jurisdictionPolicy
string
One of any, interstate, intrastate, local
schedule
object[] | null
daysrequired
integer[] · schedule[].days
fromrequired
string · schedule[].from
max 5 chars
torequired
string · schedule[].to
max 5 chars
tzrequired
string · schedule[].tz
max 64 chars
maintenanceWindows
object[] | null
fromrequired
string · maintenanceWindows[].from
max 40 chars
torequired
string · maintenanceWindows[].to
max 40 chars
note
string · maintenanceWindows[].note
max 200 chars
routingEnabled
boolean
lcrEligible
boolean
qualityEligible
boolean
popRegion
string | null
max 40 chars
allowedCustomerGroups
string[] | null
allowedProducts
string[] | null
minMarginPct
number | string | null
minMarginAbs
number | string | null
maxBuyRate
number | string | null
overflowTrunkId
string (uuid) | null
retryableSipCodes
integer[] | null
terminalSipCodes
integer[] | null
retryPolicy
string
One of same_endpoint, next_endpoint, next_trunk
maxAttemptsPerCall
integer | null
1 to 10
qosThresholds
object | null
asrMin
number · qosThresholds.asrMin
0 to 100
acdMin
number · qosThresholds.acdMin
0 to 86400
nerMin
number · qosThresholds.nerMin
0 to 100
pddMaxMs
integer · qosThresholds.pddMaxMs
0 to 600000
mosMin
number · qosThresholds.mosMin
1 to 5
shortCallMaxPct
number · qosThresholds.shortCallMaxPct
0 to 100
minCalls
integer · qosThresholds.minCalls
1 to 1000000
windowMinutes
integer · qosThresholds.windowMinutes
5 to 10080
action
string · qosThresholds.action
One of alert, demote, reduce_cps, block_destination, disable_trunk
mode
string · qosThresholds.mode
One of observe, enforce
fraudControls
object | null
shortCallSeconds
integer · fraudControls.shortCallSeconds
1 to 3600
longCallSeconds
integer · fraudControls.longCallSeconds
1 to 86400
duplicateDetect
boolean · fraudControls.duplicateDetect
spikeMultiple
number · fraudControls.spikeMultiple
1.1 to 1000
spendVelocityPerHour
number · fraudControls.spendVelocityPerHour
0 to 1000000
highCostRate
number · fraudControls.highCostRate
0 to 10000
action
string · fraudControls.action
One of alert, demote, reduce_cps, block_destination, disable_trunk
mode
string · fraudControls.mode
One of observe, enforce

Response 201

FieldDescription

datarequired
object
A supplier (vendor) trunk. Carries every spec section-4 policy field accepted on create/update; secrets are replaced by *Set booleans.Same fields as SwitchSupplierTrunk, shown earlier on this page.

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/suppliers" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Acme"
}'

Run it here with a test key.

Get live metrics for active supplier trunks

GET/api/v1/switch/suppliers/live

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

Concurrent channels, peak CPS, reachability and the last hour of answer rate and post-dial delay per active trunk. Meant to be polled.

Response 200

FieldDescription

datarequired
object
trunksrequired
object[] · data.trunks
idrequired
string (uuid) · data.trunks[].id
labelrequired
string · data.trunks[].label
capacityrequired
integer | null · data.trunks[].capacity
maxCpsrequired
integer | null · data.trunks[].maxCps
reachablerequired
boolean | null · data.trunks[].reachable
healthrequired
object · data.trunks[].health
Derived health state (what routing believes), with its counters and thresholds
asrrequired
number | null · data.trunks[].asr
Last-hour answer rate %, null when idle
asrSessionsrequired
integer · data.trunks[].asrSessions
pddP95Msrequired
integer | null · data.trunks[].pddP95Ms
lastSipCoderequired
integer | null · data.trunks[].lastSipCode
lastCauserequired
string | null · data.trunks[].lastCause
liveChannelsrequired
integer · data.trunks[].liveChannels
cpsrequired
integer · data.trunks[].cps
capacityPctrequired
integer | null · data.trunks[].capacityPct
flappingrequired
boolean · data.trunks[].flapping
totalChannelsrequired
integer · data.totalChannels
peakCpsrequired
integer · data.peakCps
cpsAttemptsrequired
integer · data.cpsAttempts

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.

Show where a supplier trunk sits in routing

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

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

The route groups that reference it and at what priority, and any customer trunk wired straight to it. unrouted is true when no traffic can reach it.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
groupsrequired
object[] · data.groups
directrequired
object[] · data.direct
unroutedrequired
boolean · data.unrouted

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.

Promote a marketplace purchase to a supplier trunk

POST/api/v1/switch/suppliers/promote

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

Turns a route you bought on the marketplace into a trunk your switch can route to. Idempotent per route: promoting again returns the existing trunk. The seller address stays hidden.

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

routeIdrequired
string (uuid)

Response 201

FieldDescription

datarequired
object
A supplier (vendor) trunk. Carries every spec section-4 policy field accepted on create/update; secrets are replaced by *Set booleans.Same fields as SwitchSupplierTrunk, shown earlier on this page.

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/suppliers/promote" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "routeId": "<routeId>"
}'

Run it here with a test key.

Reveal a supplier trunk SIP credentials

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

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

The one audited way to read a stored SIP password back. Refused (403) for a trunk promoted from the marketplace, whose login belongs to the seller.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
sipAuthUsernamerequired
string | null · data.sipAuthUsername
sipAuthPasswordrequired
string | null · data.sipAuthPassword

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 supplier trunk overview and today figures

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

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

Trunk settings plus KPIs: today cost, minutes and calls, last-hour answer rate, ACD, PDD and MOS, live channels, CPS and outstanding payables. KPI money is a JSON number.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
supplierrequired
object · data.supplier
kpisrequired
object · data.kpis

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 quality by destination for a supplier trunk

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

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

Parameters

idrequired
path · string
window
query · integer
Window in hours (default 24)

Response 200

FieldDescription

datarequired
object
windowHoursrequired
number · data.windowHours
windowrequired
object · data.window
kpisrequired
object · data.kpis
destinationsrequired
object[] · data.destinations
thresholdsrequired
object · data.thresholds
excludedMetricsrequired
any[] · data.excludedMetrics
minJudgeableSessionsrequired
number · data.minJudgeableSessions
freshnessrequired
object · 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.

List quality and fraud protection events for a supplier trunk

GET/api/v1/switch/suppliers/{id}/protection-events

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

What the protection sweep saw on this trunk and what it did (enforced) or would have done (observe mode).

Parameters

idrequired
path · string
limit
query · integer

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
vendorTrunkIdrequired
string (uuid) · data[].vendorTrunkId
moderequired
string · data[].mode
actionrequired
string · data[].action
enforcedrequired
boolean · data[].enforced
reasonrequired
string · data[].reason
breachesrequired
string[] | null · data[].breaches
measured
any · data[].measured
windowMinutesrequired
integer · data[].windowMinutes
callsrequired
integer · data[].calls
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

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

Get a supplier trunk

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

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

Includes its inbound IP ACLs, a loopback warning when its address is also one of your customers, and the derived health state.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
A supplier (vendor) trunk. Carries every spec section-4 policy field accepted on create/update; secrets are replaced by *Set booleans.
idrequired
string (uuid) · data.id
supplierIdrequired
string (uuid) | null · data.supplierId
The owning provider; null = ungrouped
labelrequired
string · data.label
sourcerequired
string · data.source
"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
statusrequired
string · data.status
One of active, disabled, draft, testing, draining, fault
sipHostrequired
string | null · data.sipHost
Null on a marketplace trunk: the seller address is never disclosed
sipPortrequired
integer | null · data.sipPort
transportrequired
string | null · data.transport
One of udp, tcp, tls
techPrefixrequired
string | null · data.techPrefix
sipAuthUsernamerequired
string | null · data.sipAuthUsername
sipAuthPasswordSetrequired
boolean · data.sipAuthPasswordSet
Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
smppPasswordSetrequired
boolean · data.smppPasswordSet
mediaModerequired
string · data.mediaMode
One of proxy, direct
defaultRatePerUnitrequired
money | null · data.defaultRatePerUnit
Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.billingIncrement
currencyrequired
string | null · data.currency
capacityrequired
integer | null · data.capacity
Max concurrent channels
maxCpsrequired
integer | null · data.maxCps
settlementModerequired
string · data.settlementMode
One of ap, prepaid
balancerequired
money · data.balance
Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
smsDeliveryMethodrequired
string | null · data.smsDeliveryMethod
One of http, smpp
reachablerequired
boolean | null · data.reachable
reachCheckedAtrequired
string (date-time) | null · data.reachCheckedAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
ipAclsrequired
object[] · data.ipAcls
idrequired
string (uuid) · data.ipAcls[].id
entityTyperequired
string · data.ipAcls[].entityType
One of customer, trunk
entityIdrequired
string (uuid) · data.ipAcls[].entityId
cidrrequired
string · data.ipAcls[].cidr
descriptionrequired
string | null · data.ipAcls[].description
createdAtrequired
string (date-time) · data.ipAcls[].createdAt
ISO-8601 timestamp (UTC)
hairpinrequired
object | null · data.hairpin
Warning when this address is also one of your own customers (loopback)
healthrequired
object · data.health
Derived health state (what routing believes), with its counters and thresholds

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 supplier trunk

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

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

Partial update. When trunk change approval is on, the change is queued for review instead and the response carries pendingChange. Send X-If-Unchanged-Since: <updatedAt you loaded> to be refused with 409 STALE_WRITE if someone else saved in between.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

label
string
max 160 chars
supplierId
string (uuid) | null
sipHost
string | null
max 255 chars
sipPort
integer | null
1 to 65535
transport
string | null
One of udp, tcp, tls
techPrefix
string | null
max 24 chars
sipAuthUsername
string | null
max 128 chars
sipAuthPassword
string | null
max 128 chars
supportedCodecs
string[] | null
defaultRatePerUnit
number | null
min 0
mediaMode
string
One of proxy, direct
billingIncrement
string | null
max 10 chars
currency
string | null
max 3 chars
capacity
integer | null
min 0
maxCps
integer | null
min 0
status
string
One of active, disabled, draft, testing, draining, fault
settlementMode
string
One of ap, prepaid
balance
number | null
min 0
portalEmail
string (email) | null
max 255 chars
smsDeliveryUrl
string (uri) | null
max 500 chars
smsDeliveryMethod
string | null
One of http, smpp
smppHost
string | null
max 255 chars
smppPort
integer | null
1 to 65535
smppSystemId
string | null
smppPassword
string | null
max 64 chars
smppBindType
string | null
One of transceiver, transmitter
smppSystemType
string | null
max 13 chars
smppTps
integer | null
1 to 1000
code
string | null
max 40 chars
description
string | null
max 2000 chars
product
string | null
max 32 chars
direction
string
One of termination, origination, bidirectional
testMode
boolean
activationDate
string | null
max 10 chars
expirationDate
string | null
max 10 chars
tags
string[] | null
notes
string | null
max 4000 chars
credentialExpiresAt
string | null
max 40 chars
credentialRotatedAt
string | null
max 40 chars
allowedSourceNetworks
string[] | null
requestRateLimit
integer | null
0 to 100000
sipRegister
boolean
sipRealm
string | null
max 255 chars
incomingTechPrefix
string | null
max 24 chars
techPrefixMode
string
One of add, remove, replace
techPrefixSeparator
string | null
max 4 chars
cliRewrite
any | null
dnisRewrite
any | null
cliPolicy
string
One of passthrough, replace, remove, pool
cliPoolId
string (uuid) | null
anonymousPolicy
string
One of passthrough, reject, substitute
e164Normalise
boolean
defaultCountryCode
string | null
max 6 chars
minDnisLength
integer | null
0 to 32
maxDnisLength
integer | null
0 to 32
paiPolicy
string
One of omit, passthrough, generate
rpidPolicy
string
One of omit, passthrough, generate
diversionPolicy
string
One of omit, passthrough, generate
historyInfoPolicy
string
One of omit, passthrough, generate
lrnPolicy
string
One of none, passthrough, strip
packetizationMs
integer | null
10 to 120
codecMode
string
One of transparent, transcode
forcedCodec
string | null
max 24 chars
srtpMode
string
One of disabled, optional, required
dtmfMode
string
One of rfc2833, info, inband, auto
t38Mode
string
One of disabled, passthrough, relay
comfortNoise
boolean
silenceSuppression
boolean
symmetricRtp
boolean
inviteTimeoutSeconds
integer | null
1 to 600
pddTimeoutSeconds
integer | null
1 to 600
ringTimeoutSeconds
integer | null
1 to 600
sessionExpiresSeconds
integer | null
90 to 86400
minSeSeconds
integer | null
90 to 86400
prackMode
string
One of disabled, supported, required
allowReinvite
boolean
allowUpdate
boolean
allowRefer
boolean
earlyMediaPolicy
string
One of passthrough, generate_ringback, suppress
recordRoute
boolean
customHeaders
object | null
q850Map
object | null
cpsBurst
integer | null
0 to 10000
queueLimit
integer | null
0 to 100000
maxChannelsPerDestination
integer | null
0 to 100000
maxCpsPerDestination
integer | null
0 to 10000
minCallSeconds
integer | null
0 to 86400
maxCallSeconds
integer | null
0 to 86400
dailyMinutesCap
integer | null
min 0
dailySpendCap
number | string | null
monthlySpendCap
number | string | null
rampupChannels
integer | null
0 to 100000
rampupDays
integer | null
0 to 365
allowedPrefixes
string[] | null
blockedPrefixes
string[] | null
allowedCountries
string[] | null
blockedCountries
string[] | null
allowMobile
boolean
allowFixed
boolean
allowSatellite
boolean
allowPremium
boolean
allowTollfree
boolean
allowEmergency
boolean
jurisdictionPolicy
string
One of any, interstate, intrastate, local
schedule
object[] | null
daysrequired
integer[] · schedule[].days
fromrequired
string · schedule[].from
max 5 chars
torequired
string · schedule[].to
max 5 chars
tzrequired
string · schedule[].tz
max 64 chars
maintenanceWindows
object[] | null
fromrequired
string · maintenanceWindows[].from
max 40 chars
torequired
string · maintenanceWindows[].to
max 40 chars
note
string · maintenanceWindows[].note
max 200 chars
routingEnabled
boolean
lcrEligible
boolean
qualityEligible
boolean
popRegion
string | null
max 40 chars
allowedCustomerGroups
string[] | null
allowedProducts
string[] | null
minMarginPct
number | string | null
minMarginAbs
number | string | null
maxBuyRate
number | string | null
overflowTrunkId
string (uuid) | null
retryableSipCodes
integer[] | null
terminalSipCodes
integer[] | null
retryPolicy
string
One of same_endpoint, next_endpoint, next_trunk
maxAttemptsPerCall
integer | null
1 to 10
qosThresholds
object | null
asrMin
number · qosThresholds.asrMin
0 to 100
acdMin
number · qosThresholds.acdMin
0 to 86400
nerMin
number · qosThresholds.nerMin
0 to 100
pddMaxMs
integer · qosThresholds.pddMaxMs
0 to 600000
mosMin
number · qosThresholds.mosMin
1 to 5
shortCallMaxPct
number · qosThresholds.shortCallMaxPct
0 to 100
minCalls
integer · qosThresholds.minCalls
1 to 1000000
windowMinutes
integer · qosThresholds.windowMinutes
5 to 10080
action
string · qosThresholds.action
One of alert, demote, reduce_cps, block_destination, disable_trunk
mode
string · qosThresholds.mode
One of observe, enforce
fraudControls
object | null
shortCallSeconds
integer · fraudControls.shortCallSeconds
1 to 3600
longCallSeconds
integer · fraudControls.longCallSeconds
1 to 86400
duplicateDetect
boolean · fraudControls.duplicateDetect
spikeMultiple
number · fraudControls.spikeMultiple
1.1 to 1000
spendVelocityPerHour
number · fraudControls.spendVelocityPerHour
0 to 1000000
highCostRate
number · fraudControls.highCostRate
0 to 10000
action
string · fraudControls.action
One of alert, demote, reduce_cps, block_destination, disable_trunk
mode
string · fraudControls.mode
One of observe, enforce

Response 200

FieldDescription

datarequired
object
A supplier (vendor) trunk. Carries every spec section-4 policy field accepted on create/update; secrets are replaced by *Set booleans.
idrequired
string (uuid) · data.id
supplierIdrequired
string (uuid) | null · data.supplierId
The owning provider; null = ungrouped
labelrequired
string · data.label
sourcerequired
string · data.source
"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
statusrequired
string · data.status
One of active, disabled, draft, testing, draining, fault
sipHostrequired
string | null · data.sipHost
Null on a marketplace trunk: the seller address is never disclosed
sipPortrequired
integer | null · data.sipPort
transportrequired
string | null · data.transport
One of udp, tcp, tls
techPrefixrequired
string | null · data.techPrefix
sipAuthUsernamerequired
string | null · data.sipAuthUsername
sipAuthPasswordSetrequired
boolean · data.sipAuthPasswordSet
Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
smppPasswordSetrequired
boolean · data.smppPasswordSet
mediaModerequired
string · data.mediaMode
One of proxy, direct
defaultRatePerUnitrequired
money | null · data.defaultRatePerUnit
Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data.billingIncrement
currencyrequired
string | null · data.currency
capacityrequired
integer | null · data.capacity
Max concurrent channels
maxCpsrequired
integer | null · data.maxCps
settlementModerequired
string · data.settlementMode
One of ap, prepaid
balancerequired
money · data.balance
Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
smsDeliveryMethodrequired
string | null · data.smsDeliveryMethod
One of http, smpp
reachablerequired
boolean | null · data.reachable
reachCheckedAtrequired
string (date-time) | null · data.reachCheckedAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
pendingChange
object · data.pendingChange
idrequired
string (uuid) · data.pendingChange.id
fieldsrequired
string[] · data.pendingChange.fields
statusrequired
string · data.pendingChange.status

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

Run it here with a test key.

Delete a supplier trunk

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

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

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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

Get the production readiness checklist for a supplier trunk

GET/api/v1/switch/suppliers/{id}/readiness

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

A pure read: it reports and never blocks. Bundle carriage trunks come back exempt with no checks.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
trunkIdrequired
string (uuid) · data.trunkId
exemptrequired
boolean · data.exempt
exemptReasonrequired
string | null · data.exemptReason
staterequired
string · data.state
One of ready, not_ready, exempt
checksrequired
object[] · data.checks
idrequired
string · data.checks[].id
specrequired
string · data.checks[].spec
titlerequired
string · data.checks[].title
statusrequired
string · data.checks[].status
pass, warn or fail
evidencerequired
string · data.checks[].evidence
fixrequired
string · data.checks[].fix
One of supplier, contacts, endpoints, configuration, cost_deck, diagnostics, settings, routing
failingrequired
integer · data.failing
warningrequired
integer · data.warning
grandfatheredrequired
boolean · data.grandfathered
blockingEnabledrequired
boolean · data.blockingEnabled

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 configuration versions of a supplier trunk

GET/api/v1/switch/suppliers/{id}/config-history

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

Parameters

idrequired
path · string
limit
query · integer

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
versionrequired
integer · data[].version
sourcerequired
string · data[].source
Which door the change came through, e.g. update, approval, api
changedFieldsrequired
string[] · data[].changedFields
diffrequired
object | null · data[].diff
noterequired
string | null · data[].note
checksumrequired
string | null · data[].checksum
changeRequestIdrequired
string (uuid) | null · data[].changeRequestId
actorUserIdrequired
string (uuid) | null · data[].actorUserId
actorEmail
string | null · data[].actorEmail
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

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

Get one configuration version of a supplier trunk

GET/api/v1/switch/suppliers/{id}/config-history/{versionId}

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

The full snapshot as of that version, plus the previous version snapshot for comparison.

Parameters

idrequired
path · string
versionIdrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
versionrequired
integer · data.version
sourcerequired
string · data.source
Which door the change came through, e.g. update, approval, api
changedFieldsrequired
string[] · data.changedFields
diffrequired
object | null · data.diff
noterequired
string | null · data.note
checksumrequired
string | null · data.checksum
changeRequestIdrequired
string (uuid) | null · data.changeRequestId
actorUserIdrequired
string (uuid) | null · data.actorUserId
actorEmail
string | null · data.actorEmail
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
snapshotrequired
object · data.snapshot
previousrequired
object | null · data.previous
idrequired
string (uuid) · data.previous.id
versionrequired
integer · data.previous.version
snapshotrequired
object · data.previous.snapshot
createdAtrequired
string (date-time) · data.previous.createdAt
ISO-8601 timestamp (UTC)

Errors

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

Test a supplier trunk SMS delivery

POST/api/v1/switch/suppliers/{id}/test-sms

Access: API key. Scoped keys need switch:manage.
Rate limit: 20 requests per minute
Real traffic: Places a real test call or sends a real test SMS over the trunk.

SMPP performs a real bind with the stored credentials and sends nothing; HTTP can only be checked for a well-formed https URL.

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
passrequired
boolean · data.pass
viarequired
string · data.via
One of http, smpp
checksrequired
object[] · data.checks
labelrequired
string · data.checks[].label
valuerequired
string · data.checks[].value
okrequired
boolean · data.checks[].ok
messagerequired
string · data.message

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

Test unsaved SMS delivery details

POST/api/v1/switch/suppliers/test-sms

Access: API key. Scoped keys need switch:manage.
Rate limit: 20 requests per minute
Real traffic: Places a real test call or sends a real test SMS over the trunk.

For the create form. SMPP performs a real bind and sends nothing; HTTP can only be checked for a well-formed https URL. The password is used for this one handshake and never stored.

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

smsDeliveryMethod
string | null
One of http, smpp
smsDeliveryUrl
string | null
max 500 chars
smppHost
string | null
max 255 chars
smppPort
integer | null
1 to 65535
smppSystemId
string | null
Short account code the supplier issued (max 16 chars). An email address is rejected.max 16 chars
smppPassword
string | null
max 64 chars
smppBindType
string | null
One of transceiver, transmitter
smppSystemType
string | null
max 13 chars
smppTps
integer | null
1 to 1000

Response 200

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/suppliers/test-sms" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "smsDeliveryMethod": "http",
  "smsDeliveryUrl": "<smsDeliveryUrl>"
}'

Run it here with a test key.

Email a supplier portal sign-in link

POST/api/v1/switch/suppliers/{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 link to the trunk portalEmail. When no portal email is 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

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 the cost deck in force on a supplier trunk

GET/api/v1/switch/suppliers/{id}/rates

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

Active rows only; scheduled and archived rows have their own endpoints. Search matches a prefix start.

Parameters

idrequired
path · string
search
query · string
Digits; matches prefixes starting with them
limit
query · string
1-1000, default 100
offset
query · string

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string (uuid) · data.rows[].id
vendorTrunkIdrequired
string (uuid) · data.rows[].vendorTrunkId
prefixrequired
string · data.rows[].prefix
originPrefixrequired
string · data.rows[].originPrefix
Caller-origin prefix; "" = any origin
ratePerUnitrequired
money · data.rows[].ratePerUnit
Cost per minute USD as a decimal string with exactly 6 places, e.g. "0.012500".
destinationNamerequired
string | null · data.rows[].destinationName
billingIncrementrequired
string | null · data.rows[].billingIncrement
e.g. "6/6"; null inherits the trunk default
statusrequired
string · data.rows[].status
effectiveFromrequired
string (date-time) | null · data.rows[].effectiveFrom
ISO-8601 timestamp (UTC)
totalrequired
integer · data.total
limitrequired
integer · data.limit
offsetrequired
integer · data.offset

Errors

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

Set the cost for one prefix on a supplier trunk

POST/api/v1/switch/suppliers/{id}/rates

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

Creates or replaces the active rate for the prefix (and origin), effective now.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

prefixrequired
string
max 24 chars
raterequired
number
Cost per minute, USDmin 0
origin
string
max 24 chars
billingIncrement
string
max 10 chars

Response 201

FieldDescription

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

Run it here with a test key.

Set costs for many prefixes on a supplier trunk

POST/api/v1/switch/suppliers/{id}/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

Request body (application/json)

FieldDescription

rowsrequired
object[]
prefixrequired
string · rows[].prefix
max 24 chars
raterequired
number · rows[].rate
Cost per minute, USDmin 0
origin
string · rows[].origin
max 24 chars
billingIncrement
string · rows[].billingIncrement
max 10 chars

Response 200

FieldDescription

datarequired
object
appliedrequired
integer · data.applied

Response 202

FieldDescription

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

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
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/suppliers/<id>/rates/bulk" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "prefix": "44",
      "rate": 1
    }
  ]
}'

Run it here with a test key.

Delete one cost row from a supplier trunk

DELETE/api/v1/switch/suppliers/{id}/rates/{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
rateIdrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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

Clear the cost deck of a supplier trunk

POST/api/v1/switch/suppliers/{id}/rates/clear

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

The deck is archived, not destroyed: restore it with POST /{id}/rates/restore.

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
integer · data.deleted
archivedrequired
integer · data.archived
recoverablerequired
boolean · data.recoverable
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

List archived cost decks of a supplier trunk

GET/api/v1/switch/suppliers/{id}/rates/archived

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object[]
revisionIdrequired
string (uuid) | null · data[].revisionId
archivedAtrequired
string (date-time) · data[].archivedAt
ISO-8601 timestamp (UTC)
rowsrequired
integer · data[].rows
labelrequired
string · data[].label

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.

Restore an archived cost deck

POST/api/v1/switch/suppliers/{id}/rates/restore

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

Restores the newest archive unless revisionId names one. Each row returns to the status it was archived from.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

revisionId
string (uuid)

Response 200

FieldDescription

datarequired
object
restoredrequired
integer · data.restored
skippedrequired
integer · data.skipped
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/suppliers/<id>/rates/restore" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "revisionId": "<revisionId>"
}'

Run it here with a test key.

List scheduled cost changes on a supplier trunk

GET/api/v1/switch/suppliers/{id}/rates/scheduled

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object[]
Same fields as SwitchTrunkRate, 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 cost change for one prefix

POST/api/v1/switch/suppliers/{id}/rates/schedule

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

A date in the past or now applies the rate immediately 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

Request body (application/json)

FieldDescription

prefixrequired
string
max 24 chars
raterequired
number
Cost per minute, USDmin 0
origin
string
max 24 chars
billingIncrement
string
max 10 chars
effectiveFromrequired
string (date-time)

Response 201

FieldDescription

datarequired
object
Same fields as SwitchTrunkRate, 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/suppliers/<id>/rates/schedule" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prefix": "44",
  "rate": 1,
  "effectiveFrom": "2026-10-01T09:00:00Z"
}'

Run it here with a test key.

Cancel a scheduled cost change

DELETE/api/v1/switch/suppliers/{id}/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
rateIdrequired
path · string

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/suppliers/<id>/rates/scheduled/<rateId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Review queued cost changes before they take effect

GET/api/v1/switch/suppliers/{id}/rates/pending-review

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

Every queued change with the price billed today, the price that takes over and when, and the effect on the last 30 days of traffic. Rates are 6-decimal strings; monthlyDelta and netMonthlyDelta are JSON numbers. At most 500 rows.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string · data.rows[].id
kindrequired
string · data.rows[].kind
One of deck, row, removed
prefixrequired
string · data.rows[].prefix
destinationrequired
string | null · data.rows[].destination
currentRaterequired
money | null · data.rows[].currentRate
US dollars as a decimal string with exactly 6 decimal places, e.g. "0.012500". Do money arithmetic with a decimal type, not floating point. USD as a decimal string with exactly 6 places, e.g. "0.012500".
newRaterequired
string | null · data.rows[].newRate
deltaPctrequired
number | null · data.rows[].deltaPct
effectiveFromrequired
string (date-time) · data.rows[].effectiveFrom
ISO-8601 timestamp (UTC)
minutes30drequired
number · data.rows[].minutes30d
calls30drequired
integer · data.rows[].calls30d
monthlyDeltarequired
number | null · data.rows[].monthlyDelta
totalRowsrequired
integer · data.totalRows
decksrequired
object[] · data.decks
impactTruncatedrequired
boolean · data.impactTruncated
summaryrequired
object · data.summary

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.