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

Field	Type	Description
`data`required	object	-
`accounts`requireddata.accounts	object[]	-
`id`requireddata.accounts[].id	string (uuid)	-
`name`requireddata.accounts[].name	string	-
`accountCode`requireddata.accounts[].accountCode	string \| null	-
`legalName`requireddata.accounts[].legalName	string \| null	-
`tradingName`requireddata.accounts[].tradingName	string \| null	-
`providerType`requireddata.accounts[].providerType	string \| null	-One of `carrier`, `aggregator`, `mno`, `mvno`, `sip_provider`
`country`requireddata.accounts[].country	string \| null	-
`services`requireddata.accounts[].services	string[] \| null	-
`portalEmail`requireddata.accounts[].portalEmail	string \| null	-
`currency`requireddata.accounts[].currency	string	-
`status`requireddata.accounts[].status	string	-One of `draft`, `pending_approval`, `testing`, `active`, `suspended`, `terminated`
`statusNote`requireddata.accounts[].statusNote	string \| null	-
`statusChangedAt`requireddata.accounts[].statusChangedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`routable`requireddata.accounts[].routable	boolean	Whether this provider admits new calls at all, given its status
`contractStart`requireddata.accounts[].contractStart	string \| null	YYYY-MM-DD
`contractEnd`requireddata.accounts[].contractEnd	string \| null	-
`autoRenew`requireddata.accounts[].autoRenew	boolean	-
`rateNoticeDays`requireddata.accounts[].rateNoticeDays	integer \| null	-
`disputeDays`requireddata.accounts[].disputeDays	integer \| null	-
`billingMode`requireddata.accounts[].billingMode	string	-One of `prepaid`, `postpaid`
`creditLimit`requireddata.accounts[].creditLimit	string \| null	Decimal string with 2 decimal places, e.g. "5000.00"
`balance`requireddata.accounts[].balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`paymentTermsDays`requireddata.accounts[].paymentTermsDays	integer \| null	-
`invoiceCycle`requireddata.accounts[].invoiceCycle	string \| null	-
`createdAt`requireddata.accounts[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.accounts[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`trunks`requireddata.accounts[].trunks	object[]	-
`id`requireddata.accounts[].trunks[].id	string (uuid)	-
`supplierId`requireddata.accounts[].trunks[].supplierId	string (uuid) \| null	The owning provider; null = ungrouped
`label`requireddata.accounts[].trunks[].label	string	-
`source`requireddata.accounts[].trunks[].source	string	"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
`status`requireddata.accounts[].trunks[].status	string	-One of `active`, `disabled`, `draft`, `testing`, `draining`, `fault`
`sipHost`requireddata.accounts[].trunks[].sipHost	string \| null	Null on a marketplace trunk: the seller address is never disclosed
`sipPort`requireddata.accounts[].trunks[].sipPort	integer \| null	-
`transport`requireddata.accounts[].trunks[].transport	string \| null	-One of `udp`, `tcp`, `tls`
`techPrefix`requireddata.accounts[].trunks[].techPrefix	string \| null	-
`sipAuthUsername`requireddata.accounts[].trunks[].sipAuthUsername	string \| null	-
`sipAuthPasswordSet`requireddata.accounts[].trunks[].sipAuthPasswordSet	boolean	Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
`smppPasswordSet`requireddata.accounts[].trunks[].smppPasswordSet	boolean	-
`mediaMode`requireddata.accounts[].trunks[].mediaMode	string	-One of `proxy`, `direct`
`defaultRatePerUnit`requireddata.accounts[].trunks[].defaultRatePerUnit	money \| null	Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.accounts[].trunks[].billingIncrement	string \| null	-
`currency`requireddata.accounts[].trunks[].currency	string \| null	-
`capacity`requireddata.accounts[].trunks[].capacity	integer \| null	Max concurrent channels
`maxCps`requireddata.accounts[].trunks[].maxCps	integer \| null	-
`settlementMode`requireddata.accounts[].trunks[].settlementMode	string	-One of `ap`, `prepaid`
`balance`requireddata.accounts[].trunks[].balance	money	Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
`smsDeliveryMethod`requireddata.accounts[].trunks[].smsDeliveryMethod	string \| null	-One of `http`, `smpp`
`reachable`requireddata.accounts[].trunks[].reachable	boolean \| null	-
`reachCheckedAt`requireddata.accounts[].trunks[].reachCheckedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.accounts[].trunks[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.accounts[].trunks[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`endpointCount`requireddata.accounts[].trunks[].endpointCount	integer	-
`endpointsEnabled`requireddata.accounts[].trunks[].endpointsEnabled	integer	-
`trunkCount`requireddata.accounts[].trunkCount	integer	-
`activeTrunks`requireddata.accounts[].activeTrunks	integer	-
`totalCapacity`requireddata.accounts[].totalCapacity	integer	-
`ungrouped`requireddata.ungrouped	object[]	-
`id`requireddata.ungrouped[].id	string (uuid)	-
`supplierId`requireddata.ungrouped[].supplierId	string (uuid) \| null	The owning provider; null = ungrouped
`label`requireddata.ungrouped[].label	string	-
`source`requireddata.ungrouped[].source	string	"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
`status`requireddata.ungrouped[].status	string	-One of `active`, `disabled`, `draft`, `testing`, `draining`, `fault`
`sipHost`requireddata.ungrouped[].sipHost	string \| null	Null on a marketplace trunk: the seller address is never disclosed
`sipPort`requireddata.ungrouped[].sipPort	integer \| null	-
`transport`requireddata.ungrouped[].transport	string \| null	-One of `udp`, `tcp`, `tls`
`techPrefix`requireddata.ungrouped[].techPrefix	string \| null	-
`sipAuthUsername`requireddata.ungrouped[].sipAuthUsername	string \| null	-
`sipAuthPasswordSet`requireddata.ungrouped[].sipAuthPasswordSet	boolean	Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
`smppPasswordSet`requireddata.ungrouped[].smppPasswordSet	boolean	-
`mediaMode`requireddata.ungrouped[].mediaMode	string	-One of `proxy`, `direct`
`defaultRatePerUnit`requireddata.ungrouped[].defaultRatePerUnit	money \| null	Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.ungrouped[].billingIncrement	string \| null	-
`currency`requireddata.ungrouped[].currency	string \| null	-
`capacity`requireddata.ungrouped[].capacity	integer \| null	Max concurrent channels
`maxCps`requireddata.ungrouped[].maxCps	integer \| null	-
`settlementMode`requireddata.ungrouped[].settlementMode	string	-One of `ap`, `prepaid`
`balance`requireddata.ungrouped[].balance	money	Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
`smsDeliveryMethod`requireddata.ungrouped[].smsDeliveryMethod	string \| null	-One of `http`, `smpp`
`reachable`requireddata.ungrouped[].reachable	boolean \| null	-
`reachCheckedAt`requireddata.ungrouped[].reachCheckedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.ungrouped[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.ungrouped[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`endpointCount`requireddata.ungrouped[].endpointCount	integer	-
`endpointsEnabled`requireddata.ungrouped[].endpointsEnabled	integer	-

Errors

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

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)

Field	Type	Description
`name`required	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

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`accountCode`requireddata.accountCode	string \| null	-
`legalName`requireddata.legalName	string \| null	-
`tradingName`requireddata.tradingName	string \| null	-
`providerType`requireddata.providerType	string \| null	-One of `carrier`, `aggregator`, `mno`, `mvno`, `sip_provider`
`country`requireddata.country	string \| null	-
`services`requireddata.services	string[] \| null	-
`portalEmail`requireddata.portalEmail	string \| null	-
`currency`requireddata.currency	string	-
`status`requireddata.status	string	-One of `draft`, `pending_approval`, `testing`, `active`, `suspended`, `terminated`
`statusNote`requireddata.statusNote	string \| null	-
`statusChangedAt`requireddata.statusChangedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`routable`requireddata.routable	boolean	Whether this provider admits new calls at all, given its status
`contractStart`requireddata.contractStart	string \| null	YYYY-MM-DD
`contractEnd`requireddata.contractEnd	string \| null	-
`autoRenew`requireddata.autoRenew	boolean	-
`rateNoticeDays`requireddata.rateNoticeDays	integer \| null	-
`disputeDays`requireddata.disputeDays	integer \| null	-
`billingMode`requireddata.billingMode	string	-One of `prepaid`, `postpaid`
`creditLimit`requireddata.creditLimit	string \| null	Decimal string with 2 decimal places, e.g. "5000.00"
`balance`requireddata.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`paymentTermsDays`requireddata.paymentTermsDays	integer \| null	-
`invoiceCycle`requireddata.invoiceCycle	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`accountCode`requireddata.accountCode	string \| null	-
`legalName`requireddata.legalName	string \| null	-
`tradingName`requireddata.tradingName	string \| null	-
`providerType`requireddata.providerType	string \| null	-One of `carrier`, `aggregator`, `mno`, `mvno`, `sip_provider`
`country`requireddata.country	string \| null	-
`services`requireddata.services	string[] \| null	-
`portalEmail`requireddata.portalEmail	string \| null	-
`currency`requireddata.currency	string	-
`status`requireddata.status	string	-One of `draft`, `pending_approval`, `testing`, `active`, `suspended`, `terminated`
`statusNote`requireddata.statusNote	string \| null	-
`statusChangedAt`requireddata.statusChangedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`routable`requireddata.routable	boolean	Whether this provider admits new calls at all, given its status
`contractStart`requireddata.contractStart	string \| null	YYYY-MM-DD
`contractEnd`requireddata.contractEnd	string \| null	-
`autoRenew`requireddata.autoRenew	boolean	-
`rateNoticeDays`requireddata.rateNoticeDays	integer \| null	-
`disputeDays`requireddata.disputeDays	integer \| null	-
`billingMode`requireddata.billingMode	string	-One of `prepaid`, `postpaid`
`creditLimit`requireddata.creditLimit	string \| null	Decimal string with 2 decimal places, e.g. "5000.00"
`balance`requireddata.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`paymentTermsDays`requireddata.paymentTermsDays	integer \| null	-
`invoiceCycle`requireddata.invoiceCycle	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`contacts`requireddata.contacts	object[]	-
`id`requireddata.contacts[].id	string (uuid)	-
`supplierId`requireddata.contacts[].supplierId	string (uuid)	-
`role`requireddata.contacts[].role	string	-One of `noc`, `rates`, `billing`, `finance`, `fraud`, `account`, `emergency`
`name`requireddata.contacts[].name	string \| null	-
`email`requireddata.contacts[].email	string \| null	-
`phone`requireddata.contacts[].phone	string \| null	-
`timezone`requireddata.contacts[].timezone	string \| null	-
`notify`requireddata.contacts[].notify	boolean	-
`notes`requireddata.contacts[].notes	string \| null	-
`createdAt`requireddata.contacts[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.contacts[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`trunks`requireddata.trunks	object[]	-
`id`requireddata.trunks[].id	string (uuid)	-
`supplierId`requireddata.trunks[].supplierId	string (uuid) \| null	The owning provider; null = ungrouped
`label`requireddata.trunks[].label	string	-
`source`requireddata.trunks[].source	string	"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
`status`requireddata.trunks[].status	string	-One of `active`, `disabled`, `draft`, `testing`, `draining`, `fault`
`sipHost`requireddata.trunks[].sipHost	string \| null	Null on a marketplace trunk: the seller address is never disclosed
`sipPort`requireddata.trunks[].sipPort	integer \| null	-
`transport`requireddata.trunks[].transport	string \| null	-One of `udp`, `tcp`, `tls`
`techPrefix`requireddata.trunks[].techPrefix	string \| null	-
`sipAuthUsername`requireddata.trunks[].sipAuthUsername	string \| null	-
`sipAuthPasswordSet`requireddata.trunks[].sipAuthPasswordSet	boolean	Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
`smppPasswordSet`requireddata.trunks[].smppPasswordSet	boolean	-
`mediaMode`requireddata.trunks[].mediaMode	string	-One of `proxy`, `direct`
`defaultRatePerUnit`requireddata.trunks[].defaultRatePerUnit	money \| null	Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.trunks[].billingIncrement	string \| null	-
`currency`requireddata.trunks[].currency	string \| null	-
`capacity`requireddata.trunks[].capacity	integer \| null	Max concurrent channels
`maxCps`requireddata.trunks[].maxCps	integer \| null	-
`settlementMode`requireddata.trunks[].settlementMode	string	-One of `ap`, `prepaid`
`balance`requireddata.trunks[].balance	money	Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
`smsDeliveryMethod`requireddata.trunks[].smsDeliveryMethod	string \| null	-One of `http`, `smpp`
`reachable`requireddata.trunks[].reachable	boolean \| null	-
`reachCheckedAt`requireddata.trunks[].reachCheckedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.trunks[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.trunks[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`endpoints`requireddata.trunks[].endpoints	object[]	-
`id`requireddata.trunks[].endpoints[].id	string (uuid)	-
`vendorTrunkId`requireddata.trunks[].endpoints[].vendorTrunkId	string (uuid)	-
`role`requireddata.trunks[].endpoints[].role	string	-One of `primary`, `backup`
`host`requireddata.trunks[].endpoints[].host	string \| null	Null on a marketplace trunk
`port`requireddata.trunks[].endpoints[].port	integer \| null	-
`transport`requireddata.trunks[].endpoints[].transport	string	-One of `udp`, `tcp`, `tls`
`priority`requireddata.trunks[].endpoints[].priority	integer	-
`weightPct`requireddata.trunks[].endpoints[].weightPct	integer \| null	-
`enabled`requireddata.trunks[].endpoints[].enabled	boolean	-
`optionsIntervalSeconds`requireddata.trunks[].endpoints[].optionsIntervalSeconds	integer \| null	-
`failureThreshold`requireddata.trunks[].endpoints[].failureThreshold	integer	-
`recoveryThreshold`requireddata.trunks[].endpoints[].recoveryThreshold	integer	-
`autoDisable`requireddata.trunks[].endpoints[].autoDisable	boolean	-
`reachable`requireddata.trunks[].endpoints[].reachable	boolean \| null	-
`reachLatencyMs`requireddata.trunks[].endpoints[].reachLatencyMs	integer \| null	-
`reachCheckedAt`requireddata.trunks[].endpoints[].reachCheckedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`healthDisabledAt`requireddata.trunks[].endpoints[].healthDisabledAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`health`requireddata.trunks[].endpoints[].health	object	Derived health state (what routing believes), with its counters and thresholds
`flap`data.trunks[].endpoints[].flap	object \| null	-
`createdAt`requireddata.trunks[].endpoints[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.trunks[].endpoints[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X 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

Name	In	Type	Description
`id`required	path	string	-

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`status`required	string	-One of `draft`, `pending_approval`, `testing`, `active`, `suspended`, `terminated`
`note`	string \| null	-max 1000 chars

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`accountCode`requireddata.accountCode	string \| null	-
`legalName`requireddata.legalName	string \| null	-
`tradingName`requireddata.tradingName	string \| null	-
`providerType`requireddata.providerType	string \| null	-One of `carrier`, `aggregator`, `mno`, `mvno`, `sip_provider`
`country`requireddata.country	string \| null	-
`services`requireddata.services	string[] \| null	-
`portalEmail`requireddata.portalEmail	string \| null	-
`currency`requireddata.currency	string	-
`status`requireddata.status	string	-One of `draft`, `pending_approval`, `testing`, `active`, `suspended`, `terminated`
`statusNote`requireddata.statusNote	string \| null	-
`statusChangedAt`requireddata.statusChangedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`routable`requireddata.routable	boolean	Whether this provider admits new calls at all, given its status
`contractStart`requireddata.contractStart	string \| null	YYYY-MM-DD
`contractEnd`requireddata.contractEnd	string \| null	-
`autoRenew`requireddata.autoRenew	boolean	-
`rateNoticeDays`requireddata.rateNoticeDays	integer \| null	-
`disputeDays`requireddata.disputeDays	integer \| null	-
`billingMode`requireddata.billingMode	string	-One of `prepaid`, `postpaid`
`creditLimit`requireddata.creditLimit	string \| null	Decimal string with 2 decimal places, e.g. "5000.00"
`balance`requireddata.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`paymentTermsDays`requireddata.paymentTermsDays	integer \| null	-
`invoiceCycle`requireddata.invoiceCycle	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`trafficChange`requireddata.trafficChange	string	-One of `none`, `resumed`, `stopped`
`affectedTrunks`requireddata.affectedTrunks	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`role`required	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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

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

Request body (application/json)

Field	Type	Description
`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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X 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

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

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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

Field	Type	Description
`data`required	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)

Field	Type	Description
`name`required	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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X 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

Name	In	Type	Description
`id`required	path	string	-

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`status`required	string	-One of `draft`, `pending_approval`, `testing`, `active`, `suspended`, `terminated`
`note`	string \| null	-max 1000 chars

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`accountCode`requireddata.accountCode	string \| null	-
`legalName`requireddata.legalName	string \| null	-
`tradingName`requireddata.tradingName	string \| null	-
`providerType`requireddata.providerType	string \| null	-One of `carrier`, `aggregator`, `mno`, `mvno`, `sip_provider`
`country`requireddata.country	string \| null	-
`services`requireddata.services	string[] \| null	-
`portalEmail`requireddata.portalEmail	string \| null	-
`currency`requireddata.currency	string	-
`status`requireddata.status	string	-One of `draft`, `pending_approval`, `testing`, `active`, `suspended`, `terminated`
`statusNote`requireddata.statusNote	string \| null	-
`statusChangedAt`requireddata.statusChangedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`routable`requireddata.routable	boolean	Whether this provider admits new calls at all, given its status
`contractStart`requireddata.contractStart	string \| null	YYYY-MM-DD
`contractEnd`requireddata.contractEnd	string \| null	-
`autoRenew`requireddata.autoRenew	boolean	-
`rateNoticeDays`requireddata.rateNoticeDays	integer \| null	-
`disputeDays`requireddata.disputeDays	integer \| null	-
`billingMode`requireddata.billingMode	string	-One of `prepaid`, `postpaid`
`creditLimit`requireddata.creditLimit	string \| null	Decimal string with 2 decimal places, e.g. "5000.00"
`balance`requireddata.balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`paymentTermsDays`requireddata.paymentTermsDays	integer \| null	-
`invoiceCycle`requireddata.invoiceCycle	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`trafficChange`requireddata.trafficChange	string	-One of `none`, `resumed`, `stopped`
`affectedTrunks`requireddata.affectedTrunks	integer	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`role`required	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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

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

Request body (application/json)

Field	Type	Description
`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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X 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

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

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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

Name	In	Type	Description
`id`required	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

Field	Type	Description
`data`required	object	-
`window`requireddata.window	object	-
`from`requireddata.window.from	string	-
`to`requireddata.window.to	string	-
`summary`requireddata.summary	object	-
`calls`requireddata.summary.calls	number	-
`answered`requireddata.summary.answered	number	-
`asr`requireddata.summary.asr	number \| null	-
`minutes`requireddata.summary.minutes	number	-
`cost`requireddata.summary.cost	number	-
`acd`requireddata.summary.acd	number \| null	-
`avgPddMs`requireddata.summary.avgPddMs	number \| null	-
`byTrunk`requireddata.byTrunk	object[]	-
`trunkId`requireddata.byTrunk[].trunkId	string (uuid) \| null	-
`label`requireddata.byTrunk[].label	string	-
`calls`requireddata.byTrunk[].calls	number	-
`answered`requireddata.byTrunk[].answered	number	-
`asr`requireddata.byTrunk[].asr	number \| null	-
`minutes`requireddata.byTrunk[].minutes	number	-
`cost`requireddata.byTrunk[].cost	number	-

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`currency`requireddata.currency	string	-
`billingMode`requireddata.billingMode	string	-
`creditLimit`requireddata.creditLimit	string \| null	Decimal string with 2 decimal places, e.g. "5000.00"
`paymentTermsDays`requireddata.paymentTermsDays	integer \| null	-
`invoiceCycle`requireddata.invoiceCycle	string \| null	-
`invoices`requireddata.invoices	object[]	-
`unbilled`requireddata.unbilled	object	-
`since`requireddata.unbilled.since	string \| null	-
`calls`requireddata.unbilled.calls	number	-
`minutes`requireddata.unbilled.minutes	number	-
`cost`requireddata.unbilled.cost	number	-

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`alerts`requireddata.alerts	object[]	-
`severity`requireddata.alerts[].severity	string	-One of `critical`, `warning`, `info`
`code`requireddata.alerts[].code	string	-
`message`requireddata.alerts[].message	string	-
`trunkId`data.alerts[].trunkId	string (uuid)	-

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

Name	In	Type	Description
`id`required	path	string	-
`limit`	query	string	Max entries (default 100)

Response 200

Field	Type	Description
`data`required	object	-
`entries`requireddata.entries	object[]	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`supplierId`requireddata[].supplierId	string (uuid)	-
`periodStart`requireddata[].periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata[].periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`ourAmount`requireddata[].ourAmount	string \| null	Decimal string with 2 decimal places, e.g. "5000.00"
`theirAmount`requireddata[].theirAmount	string \| null	Decimal string with 2 decimal places, e.g. "5000.00"
`currency`requireddata[].currency	string	-
`status`requireddata[].status	string	-One of `open`, `submitted`, `accepted`, `rejected`, `settled`, `withdrawn`
`reason`requireddata[].reason	string \| null	-
`resolution`requireddata[].resolution	string \| null	-
`invoiceRef`requireddata[].invoiceRef	string \| null	-
`openedAt`requireddata[].openedAt	string (date-time)	ISO-8601 timestamp (UTC)
`respondBy`requireddata[].respondBy	string (date-time) \| null	ISO-8601 timestamp (UTC)
`closedAt`requireddata[].closedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`daysLeft`data[].daysLeft	integer \| null	Days left to respond (list only); negative = the window has passed
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

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

Request body (application/json)

Field	Type	Description
`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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X 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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`role`	string	-One of `primary`, `backup`
`host`required	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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

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

Request body (application/json)

Field	Type	Description
`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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X 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

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

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`trunkId`requireddata.trunkId	string (uuid)	-
`trunkLabel`requireddata.trunkLabel	string	-
`profileLevel`requireddata.profileLevel	object[]	-
`endpointId`requireddata.profileLevel[].endpointId	string (uuid)	-
`host`requireddata.profileLevel[].host	string	-
`settings`requireddata.profileLevel[].settings	string[]	-
`xml`requireddata.xml	string	Gateway configuration to place on the SBC
`applyNote`requireddata.applyNote	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`supplierId`requireddata.supplierId	string (uuid)	-
`supplierName`requireddata.supplierName	string	-
`trunks`requireddata.trunks	object[]	Same fields as SwitchSbcProfile, shown earlier on this page.
`needsReload`requireddata.needsReload	boolean	-

Errors

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

Name	In	Type	Description
`id`required	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

Field	Type	Description
`data`required	object	-
`events`requireddata.events	object[]	-
`windowDays`requireddata.windowDays	integer	-
`retention`requireddata.retention	object	-
`probeDays`requireddata.retention.probeDays	integer	-
`eventDays`requireddata.retention.eventDays	integer	-
`nextBefore`requireddata.nextBefore	string \| null	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`windowHours`requireddata.windowHours	number	-
`minTransitions`requireddata.minTransitions	integer	-
`endpoints`requireddata.endpoints	object[]	-
`endpointId`requireddata.endpoints[].endpointId	string (uuid) \| null	-
`host`requireddata.endpoints[].host	string \| null	-
`transitions`requireddata.endpoints[].transitions	integer	-
`firstAt`requireddata.endpoints[].firstAt	string (date-time)	ISO-8601 timestamp (UTC)
`lastAt`requireddata.endpoints[].lastAt	string (date-time)	ISO-8601 timestamp (UTC)
`flapping`requireddata.endpoints[].flapping	boolean	-
`flapping`requireddata.flapping	boolean	-

Errors

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	object	-
`ranAt`requireddata.ranAt	string (date-time)	ISO-8601 timestamp (UTC)
`host`requireddata.host	string \| null	-
`port`requireddata.port	integer \| null	-
`techPrefix`requireddata.techPrefix	string \| null	-
`verdict`requireddata.verdict	string	-
`latencyMs`requireddata.latencyMs	integer	-
`diagnostics`requireddata.diagnostics	object	-
`endpointHidden`data.endpointHidden	boolean	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	object	A supplier (vendor) trunk. Carries every spec section-4 policy field accepted on create/update; secrets are replaced by *Set booleans.
`id`requireddata.id	string (uuid)	-
`supplierId`requireddata.supplierId	string (uuid) \| null	The owning provider; null = ungrouped
`label`requireddata.label	string	-
`source`requireddata.source	string	"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
`status`requireddata.status	string	-One of `active`, `disabled`, `draft`, `testing`, `draining`, `fault`
`sipHost`requireddata.sipHost	string \| null	Null on a marketplace trunk: the seller address is never disclosed
`sipPort`requireddata.sipPort	integer \| null	-
`transport`requireddata.transport	string \| null	-One of `udp`, `tcp`, `tls`
`techPrefix`requireddata.techPrefix	string \| null	-
`sipAuthUsername`requireddata.sipAuthUsername	string \| null	-
`sipAuthPasswordSet`requireddata.sipAuthPasswordSet	boolean	Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
`smppPasswordSet`requireddata.smppPasswordSet	boolean	-
`mediaMode`requireddata.mediaMode	string	-One of `proxy`, `direct`
`defaultRatePerUnit`requireddata.defaultRatePerUnit	money \| null	Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.billingIncrement	string \| null	-
`currency`requireddata.currency	string \| null	-
`capacity`requireddata.capacity	integer \| null	Max concurrent channels
`maxCps`requireddata.maxCps	integer \| null	-
`settlementMode`requireddata.settlementMode	string	-One of `ap`, `prepaid`
`balance`requireddata.balance	money	Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
`smsDeliveryMethod`requireddata.smsDeliveryMethod	string \| null	-One of `http`, `smpp`
`reachable`requireddata.reachable	boolean \| null	-
`reachCheckedAt`requireddata.reachCheckedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Field	Type	Description
`data`required	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)

Field	Type	Description
`label`required	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	-
`days`requiredschedule[].days	integer[]	-
`from`requiredschedule[].from	string	-max 5 chars
`to`requiredschedule[].to	string	-max 5 chars
`tz`requiredschedule[].tz	string	-max 64 chars
`maintenanceWindows`	object[] \| null	-
`from`requiredmaintenanceWindows[].from	string	-max 40 chars
`to`requiredmaintenanceWindows[].to	string	-max 40 chars
`note`maintenanceWindows[].note	string	-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`qosThresholds.asrMin	number	-0 to 100
`acdMin`qosThresholds.acdMin	number	-0 to 86400
`nerMin`qosThresholds.nerMin	number	-0 to 100
`pddMaxMs`qosThresholds.pddMaxMs	integer	-0 to 600000
`mosMin`qosThresholds.mosMin	number	-1 to 5
`shortCallMaxPct`qosThresholds.shortCallMaxPct	number	-0 to 100
`minCalls`qosThresholds.minCalls	integer	-1 to 1000000
`windowMinutes`qosThresholds.windowMinutes	integer	-5 to 10080
`action`qosThresholds.action	string	-One of `alert`, `demote`, `reduce_cps`, `block_destination`, `disable_trunk`
`mode`qosThresholds.mode	string	-One of `observe`, `enforce`
`fraudControls`	object \| null	-
`shortCallSeconds`fraudControls.shortCallSeconds	integer	-1 to 3600
`longCallSeconds`fraudControls.longCallSeconds	integer	-1 to 86400
`duplicateDetect`fraudControls.duplicateDetect	boolean	-
`spikeMultiple`fraudControls.spikeMultiple	number	-1.1 to 1000
`spendVelocityPerHour`fraudControls.spendVelocityPerHour	number	-0 to 1000000
`highCostRate`fraudControls.highCostRate	number	-0 to 10000
`action`fraudControls.action	string	-One of `alert`, `demote`, `reduce_cps`, `block_destination`, `disable_trunk`
`mode`fraudControls.mode	string	-One of `observe`, `enforce`

Response 201

Field	Type	Description
`data`required	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

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Field	Type	Description
`data`required	object	-
`trunks`requireddata.trunks	object[]	-
`id`requireddata.trunks[].id	string (uuid)	-
`label`requireddata.trunks[].label	string	-
`capacity`requireddata.trunks[].capacity	integer \| null	-
`maxCps`requireddata.trunks[].maxCps	integer \| null	-
`reachable`requireddata.trunks[].reachable	boolean \| null	-
`health`requireddata.trunks[].health	object	Derived health state (what routing believes), with its counters and thresholds
`asr`requireddata.trunks[].asr	number \| null	Last-hour answer rate %, null when idle
`asrSessions`requireddata.trunks[].asrSessions	integer	-
`pddP95Ms`requireddata.trunks[].pddP95Ms	integer \| null	-
`lastSipCode`requireddata.trunks[].lastSipCode	integer \| null	-
`lastCause`requireddata.trunks[].lastCause	string \| null	-
`liveChannels`requireddata.trunks[].liveChannels	integer	-
`cps`requireddata.trunks[].cps	integer	-
`capacityPct`requireddata.trunks[].capacityPct	integer \| null	-
`flapping`requireddata.trunks[].flapping	boolean	-
`totalChannels`requireddata.totalChannels	integer	-
`peakCps`requireddata.peakCps	integer	-
`cpsAttempts`requireddata.cpsAttempts	integer	-

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`groups`requireddata.groups	object[]	-
`direct`requireddata.direct	object[]	-
`unrouted`requireddata.unrouted	boolean	-

Errors

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

Field	Type	Description
`routeId`required	string (uuid)	-

Response 201

Field	Type	Description
`data`required	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

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`sipAuthUsername`requireddata.sipAuthUsername	string \| null	-
`sipAuthPassword`requireddata.sipAuthPassword	string \| null	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`supplier`requireddata.supplier	object	-
`kpis`requireddata.kpis	object	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
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

Name	In	Type	Description
`id`required	path	string	-
`window`	query	integer	Window in hours (default 24)

Response 200

Field	Type	Description
`data`required	object	-
`windowHours`requireddata.windowHours	number	-
`window`requireddata.window	object	-
`kpis`requireddata.kpis	object	-
`destinations`requireddata.destinations	object[]	-
`thresholds`requireddata.thresholds	object	-
`excludedMetrics`requireddata.excludedMetrics	any[]	-
`minJudgeableSessions`requireddata.minJudgeableSessions	number	-
`freshness`requireddata.freshness	object	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
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

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

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`vendorTrunkId`requireddata[].vendorTrunkId	string (uuid)	-
`mode`requireddata[].mode	string	-
`action`requireddata[].action	string	-
`enforced`requireddata[].enforced	boolean	-
`reason`requireddata[].reason	string	-
`breaches`requireddata[].breaches	string[] \| null	-
`measured`data[].measured	any	-
`windowMinutes`requireddata[].windowMinutes	integer	-
`calls`requireddata[].calls	integer	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	A supplier (vendor) trunk. Carries every spec section-4 policy field accepted on create/update; secrets are replaced by *Set booleans.
`id`requireddata.id	string (uuid)	-
`supplierId`requireddata.supplierId	string (uuid) \| null	The owning provider; null = ungrouped
`label`requireddata.label	string	-
`source`requireddata.source	string	"external" for a carrier you entered; "marketplace" for a trunk promoted from a marketplace purchase
`status`requireddata.status	string	-One of `active`, `disabled`, `draft`, `testing`, `draining`, `fault`
`sipHost`requireddata.sipHost	string \| null	Null on a marketplace trunk: the seller address is never disclosed
`sipPort`requireddata.sipPort	integer \| null	-
`transport`requireddata.transport	string \| null	-One of `udp`, `tcp`, `tls`
`techPrefix`requireddata.techPrefix	string \| null	-
`sipAuthUsername`requireddata.sipAuthUsername	string \| null	-
`sipAuthPasswordSet`requireddata.sipAuthPasswordSet	boolean	Whether a SIP password is stored. The value is only readable via GET /switch/suppliers/{id}/credentials
`smppPasswordSet`requireddata.smppPasswordSet	boolean	-
`mediaMode`requireddata.mediaMode	string	-One of `proxy`, `direct`
`defaultRatePerUnit`requireddata.defaultRatePerUnit	money \| null	Cost per minute used when no deck row matches USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.billingIncrement	string \| null	-
`currency`requireddata.currency	string \| null	-
`capacity`requireddata.capacity	integer \| null	Max concurrent channels
`maxCps`requireddata.maxCps	integer \| null	-
`settlementMode`requireddata.settlementMode	string	-One of `ap`, `prepaid`
`balance`requireddata.balance	money	Prepaid credit remaining with this supplier (prepaid settlement) USD as a decimal string with exactly 6 places, e.g. "0.012500".
`smsDeliveryMethod`requireddata.smsDeliveryMethod	string \| null	-One of `http`, `smpp`
`reachable`requireddata.reachable	boolean \| null	-
`reachCheckedAt`requireddata.reachCheckedAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`ipAcls`requireddata.ipAcls	object[]	-
`id`requireddata.ipAcls[].id	string (uuid)	-
`entityType`requireddata.ipAcls[].entityType	string	-One of `customer`, `trunk`
`entityId`requireddata.ipAcls[].entityId	string (uuid)	-
`cidr`requireddata.ipAcls[].cidr	string	-
`description`requireddata.ipAcls[].description	string \| null	-
`createdAt`requireddata.ipAcls[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`hairpin`requireddata.hairpin	object \| null	Warning when this address is also one of your own customers (loopback)
`health`requireddata.health	object	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`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	-
`days`requiredschedule[].days	integer[]	-
`from`requiredschedule[].from	string	-max 5 chars
`to`requiredschedule[].to	string	-max 5 chars
`tz`requiredschedule[].tz	string	-max 64 chars
`maintenanceWindows`	object[] \| null	-
`from`requiredmaintenanceWindows[].from	string	-max 40 chars
`to`requiredmaintenanceWindows[].to	string	-max 40 chars
`note`maintenanceWindows[].note	string	-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`qosThresholds.asrMin	number	-0 to 100
`acdMin`qosThresholds.acdMin	number	-0 to 86400
`nerMin`qosThresholds.nerMin	number	-0 to 100
`pddMaxMs`qosThresholds.pddMaxMs	integer	-0 to 600000
`mosMin`qosThresholds.mosMin	number	-1 to 5
`shortCallMaxPct`qosThresholds.shortCallMaxPct	number	-0 to 100
`minCalls`qosThresholds.minCalls	integer	-1 to 1000000
`windowMinutes`qosThresholds.windowMinutes	integer	-5 to 10080
`action`qosThresholds.action	string	-One of `alert`, `demote`, `reduce_cps`, `block_destination`, `disable_trunk`
`mode`qosThresholds.mode	string	-One of `observe`, `enforce`
`fraudControls`	object \| null	-
`shortCallSeconds`fraudControls.shortCallSeconds	integer	-1 to 3600
`longCallSeconds`fraudControls.longCallSeconds	integer	-1 to 86400
`duplicateDetect`fraudControls.duplicateDetect	boolean	-
`spikeMultiple`fraudControls.spikeMultiple	number	-1.1 to 1000
`spendVelocityPerHour`fraudControls.spendVelocityPerHour	number	-0 to 1000000
`highCostRate`fraudControls.highCostRate	number	-0 to 10000
`action`fraudControls.action	string	-One of `alert`, `demote`, `reduce_cps`, `block_destination`, `disable_trunk`
`mode`fraudControls.mode	string	-One of `observe`, `enforce`

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X 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

Name	In	Type	Description
`id`required	path	string	-

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`trunkId`requireddata.trunkId	string (uuid)	-
`exempt`requireddata.exempt	boolean	-
`exemptReason`requireddata.exemptReason	string \| null	-
`state`requireddata.state	string	-One of `ready`, `not_ready`, `exempt`
`checks`requireddata.checks	object[]	-
`id`requireddata.checks[].id	string	-
`spec`requireddata.checks[].spec	string	-
`title`requireddata.checks[].title	string	-
`status`requireddata.checks[].status	string	pass, warn or fail
`evidence`requireddata.checks[].evidence	string	-
`fix`requireddata.checks[].fix	string	-One of `supplier`, `contacts`, `endpoints`, `configuration`, `cost_deck`, `diagnostics`, `settings`, `routing`
`failing`requireddata.failing	integer	-
`warning`requireddata.warning	integer	-
`grandfathered`requireddata.grandfathered	boolean	-
`blockingEnabled`requireddata.blockingEnabled	boolean	-

Errors

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

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

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`version`requireddata[].version	integer	-
`source`requireddata[].source	string	Which door the change came through, e.g. update, approval, api
`changedFields`requireddata[].changedFields	string[]	-
`diff`requireddata[].diff	object \| null	-
`note`requireddata[].note	string \| null	-
`checksum`requireddata[].checksum	string \| null	-
`changeRequestId`requireddata[].changeRequestId	string (uuid) \| null	-
`actorUserId`requireddata[].actorUserId	string (uuid) \| null	-
`actorEmail`data[].actorEmail	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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

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

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

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`version`requireddata.version	integer	-
`source`requireddata.source	string	Which door the change came through, e.g. update, approval, api
`changedFields`requireddata.changedFields	string[]	-
`diff`requireddata.diff	object \| null	-
`note`requireddata.note	string \| null	-
`checksum`requireddata.checksum	string \| null	-
`changeRequestId`requireddata.changeRequestId	string (uuid) \| null	-
`actorUserId`requireddata.actorUserId	string (uuid) \| null	-
`actorEmail`data.actorEmail	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`snapshot`requireddata.snapshot	object	-
`previous`requireddata.previous	object \| null	-
`id`requireddata.previous.id	string (uuid)	-
`version`requireddata.previous.version	integer	-
`snapshot`requireddata.previous.snapshot	object	-
`createdAt`requireddata.previous.createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`pass`requireddata.pass	boolean	-
`via`requireddata.via	string	-One of `http`, `smpp`
`checks`requireddata.checks	object[]	-
`label`requireddata.checks[].label	string	-
`value`requireddata.checks[].value	string	-
`ok`requireddata.checks[].ok	boolean	-
`message`requireddata.message	string	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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)

Field	Type	Description
`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

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`sent`requireddata.sent	boolean	-One of `true`
`to`requireddata.to	string	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

List 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

Name	In	Type	Description
`id`required	path	string	-
`search`	query	string	Digits; matches prefixes starting with them
`limit`	query	string	1-1000, default 100
`offset`	query	string	-

Response 200

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string (uuid)	-
`vendorTrunkId`requireddata.rows[].vendorTrunkId	string (uuid)	-
`prefix`requireddata.rows[].prefix	string	-
`originPrefix`requireddata.rows[].originPrefix	string	Caller-origin prefix; "" = any origin
`ratePerUnit`requireddata.rows[].ratePerUnit	money	Cost per minute USD as a decimal string with exactly 6 places, e.g. "0.012500".
`destinationName`requireddata.rows[].destinationName	string \| null	-
`billingIncrement`requireddata.rows[].billingIncrement	string \| null	e.g. "6/6"; null inherits the trunk default
`status`requireddata.rows[].status	string	-
`effectiveFrom`requireddata.rows[].effectiveFrom	string (date-time) \| null	ISO-8601 timestamp (UTC)
`total`requireddata.total	integer	-
`limit`requireddata.limit	integer	-
`offset`requireddata.offset	integer	-

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`prefix`required	string	-max 24 chars
`rate`required	number	Cost per minute, USDmin 0
`origin`	string	-max 24 chars
`billingIncrement`	string	-max 10 chars

Response 201

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`rows`required	object[]	-
`prefix`requiredrows[].prefix	string	-max 24 chars
`rate`requiredrows[].rate	number	Cost per minute, USDmin 0
`origin`rows[].origin	string	-max 24 chars
`billingIncrement`rows[].billingIncrement	string	-max 10 chars

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
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

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

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`deleted`requireddata.deleted	integer	-
`archived`requireddata.archived	integer	-
`recoverable`requireddata.recoverable	boolean	-
`revisionId`requireddata.revisionId	string (uuid) \| null	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object[]	-
`revisionId`requireddata[].revisionId	string (uuid) \| null	-
`archivedAt`requireddata[].archivedAt	string (date-time)	ISO-8601 timestamp (UTC)
`rows`requireddata[].rows	integer	-
`label`requireddata[].label	string	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`revisionId`	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`restored`requireddata.restored	integer	-
`skipped`requireddata.skipped	integer	-
`revisionId`requireddata.revisionId	string (uuid) \| null	-

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`prefix`required	string	-max 24 chars
`rate`required	number	Cost per minute, USDmin 0
`origin`	string	-max 24 chars
`billingIncrement`	string	-max 10 chars
`effectiveFrom`required	string (date-time)	-

Response 201

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

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

Response 200

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

Response 202

Field	Type	Description
`data`required	object	-
`approvalRequired`data.approvalRequired	boolean	-One of `true`
`approvalRequestId`data.approvalRequestId	string (uuid) \| null	-
`permission`data.permission	string	-
`expiresAt`data.expiresAt	string (date-time)	-
`message`data.message	string	-

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string	-
`kind`requireddata.rows[].kind	string	-One of `deck`, `row`, `removed`
`prefix`requireddata.rows[].prefix	string	-
`destination`requireddata.rows[].destination	string \| null	-
`currentRate`requireddata.rows[].currentRate	money \| null	US dollars as a decimal string with exactly 6 decimal places, e.g. "0.012500". Do money arithmetic with a decimal type, not floating point. USD as a decimal string with exactly 6 places, e.g. "0.012500".
`newRate`requireddata.rows[].newRate	string \| null	-
`deltaPct`requireddata.rows[].deltaPct	number \| null	-
`effectiveFrom`requireddata.rows[].effectiveFrom	string (date-time)	ISO-8601 timestamp (UTC)
`minutes30d`requireddata.rows[].minutes30d	number	-
`calls30d`requireddata.rows[].calls30d	integer	-
`monthlyDelta`requireddata.rows[].monthlyDelta	number \| null	-
`totalRows`requireddata.totalRows	integer	-
`decks`requireddata.decks	object[]	-
`impactTruncated`requireddata.impactTruncated	boolean	-
`summary`requireddata.summary	object	-

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
402SWITCH_SUBSCRIPTION_REQUIRED: the account has no active Switch plan or trial.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
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.