Switch API reference

Switch: customers

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

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

BrowseSwitch: customers

Get a Switch customer routing assignment

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`subAccountId`requireddata.subAccountId	string (uuid)	-
`customerTrunkId`data.customerTrunkId	string (uuid) \| null	-
`dialplanId`requireddata.dialplanId	string (uuid) \| null	-
`routePlanId`requireddata.routePlanId	string (uuid) \| null	-
`failoverRoutePlanId`requireddata.failoverRoutePlanId	string (uuid) \| null	-
`strategyOverride`requireddata.strategyOverride	string \| null	-
`directRouteId`requireddata.directRouteId	string (uuid) \| null	-
`directVendorTrunkId`requireddata.directVendorTrunkId	string (uuid) \| 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.

Assign routing to a Switch customer

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`dialplanId`	string (uuid) \| null	-
`routePlanId`	string (uuid) \| null	-
`failoverRoutePlanId`	string (uuid) \| null	-
`strategyOverride`	string \| null	-One of `cheapest`, `best_quality`, `balanced`
`directRouteId`	string (uuid) \| null	-
`directVendorTrunkId`	string (uuid) \| null	-

Response 200

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

Run it here with a test key.

List a Switch customer trunks with traffic

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`scope`	query	string	Default operational (excludes archived)One of operational, archived, all
`periodHours`	query	integer	Window for the traffic figures; unrecognised values fall back to 24

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`subAccountId`requireddata[].subAccountId	string (uuid)	The customer this trunk belongs to
`label`requireddata[].label	string	-
`status`requireddata[].status	string	-One of `active`, `disabled`, `archived`
`authMode`data[].authMode	string	-One of `ip`, `credentials`, `ip_and_credentials`, `registration`, `certificate`
`sipUsername`requireddata[].sipUsername	string \| null	-
`sipPasswordSet`requireddata[].sipPasswordSet	boolean	-
`maxConcurrentCalls`requireddata[].maxConcurrentCalls	integer \| null	Null inherits the customer ceiling
`maxCps`requireddata[].maxCps	integer \| null	-
`markupPct`requireddata[].markupPct	string \| null	-
`billingIncrement`requireddata[].billingIncrement	string \| null	-
`techPrefix`requireddata[].techPrefix	string \| null	-
`mediaMode`data[].mediaMode	string	-One of `proxy`, `direct`
`cliRewrite`requireddata[].cliRewrite	object \| null	-
`allowedPrefixes`requireddata[].allowedPrefixes	string[] \| null	-
`allowedCountries`requireddata[].allowedCountries	string[] \| null	-
`blockedCountries`requireddata[].blockedCountries	string[] \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`authentication`requireddata[].authentication	object	-
`mode`requireddata[].authentication.mode	string	-One of `ip`, `credentials`, `ip_and_credentials`, `registration`, `certificate`
`title`requireddata[].authentication.title	string	-
`summary`requireddata[].authentication.summary	string	-
`sends`requireddata[].authentication.sends	string[]	-
`checks`requireddata[].authentication.checks	string[]	-
`gaps`requireddata[].authentication.gaps	string[]	Empty when the trunk is configured for its declared mode
`enforced`requireddata[].authentication.enforced	boolean	-
`identification`requireddata[].identification	object	-
`namedBy`requireddata[].identification.namedBy	string[]	-
`unique`requireddata[].identification.unique	boolean	-
`note`requireddata[].identification.note	string \| null	-
`allowedIps`requireddata[].allowedIps	string[]	-
`allowedAddresses`requireddata[].allowedAddresses	object[]	-
`id`requireddata[].allowedAddresses[].id	string (uuid)	-
`cidr`requireddata[].allowedAddresses[].cidr	string	-
`routing`requireddata[].routing	object \| null	-
`inherited`requireddata[].inherited	object	-
`from`requireddata[].inherited.from	string	-One of `customer`
`maxConcurrentCalls`requireddata[].inherited.maxConcurrentCalls	integer \| null	-
`maxCps`requireddata[].inherited.maxCps	integer \| null	-
`billingIncrement`requireddata[].inherited.billingIncrement	string \| null	-
`last24h`requireddata[].last24h	object	-
`calls`requireddata[].last24h.calls	integer	-
`minutes`requireddata[].last24h.minutes	number	-
`revenue`requireddata[].last24h.revenue	number	US dollars as a JSON number (computed figure)
`period`data[].period	any	The window the traffic figures cover
`traffic`requireddata[].traffic	object	-
`calls`requireddata[].traffic.calls	integer	-
`answered`requireddata[].traffic.answered	integer	-
`minutes`requireddata[].traffic.minutes	number	-
`revenue`requireddata[].traffic.revenue	number	US dollars as a JSON number (computed figure)
`margin`requireddata[].traffic.margin	number	US dollars as a JSON number (computed figure)
`asr`requireddata[].traffic.asr	number \| null	-
`pddMs`requireddata[].traffic.pddMs	number \| null	-
`refused`requireddata[].refused	object	-
`forbidden`requireddata[].refused.forbidden	integer	-
`capacity`requireddata[].refused.capacity	integer	-
`capacityChannels`requireddata[].refused.capacityChannels	integer	-
`capacityCps`requireddata[].refused.capacityCps	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.

Add a trunk to a Switch customer

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

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

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`subAccountId`requireddata.subAccountId	string (uuid)	The customer this trunk belongs to
`label`requireddata.label	string	-
`status`requireddata.status	string	-One of `active`, `disabled`, `archived`
`authMode`data.authMode	string	-One of `ip`, `credentials`, `ip_and_credentials`, `registration`, `certificate`
`sipUsername`requireddata.sipUsername	string \| null	-
`maxConcurrentCalls`requireddata.maxConcurrentCalls	integer \| null	Null inherits the customer ceiling
`maxCps`requireddata.maxCps	integer \| null	-
`markupPct`requireddata.markupPct	string \| null	-
`billingIncrement`requireddata.billingIncrement	string \| null	-
`techPrefix`requireddata.techPrefix	string \| null	-
`mediaMode`data.mediaMode	string	-One of `proxy`, `direct`
`cliRewrite`requireddata.cliRewrite	object \| null	-
`allowedPrefixes`requireddata.allowedPrefixes	string[] \| null	-
`allowedCountries`requireddata.allowedCountries	string[] \| null	-
`blockedCountries`requireddata.blockedCountries	string[] \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`sipPassword`requireddata.sipPassword	string \| 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/customers/<id>/trunks" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Acme",
  "authMode": "ip"
}'

Run it here with a test key.

List your Switch customers with live and 24-hour figures

GET/api/v1/switch/customers

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

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

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`label`requireddata[].label	string	-
`source`requireddata[].source	string	-One of `marketplace`, `external`
`status`requireddata[].status	string	-One of `draft`, `active`, `suspended`, `closed`
`externalRef`requireddata[].externalRef	string \| null	-
`balance`requireddata[].balance	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`creditLimit`requireddata[].creditLimit	string	USD decimal string as stored (2 decimal places), e.g. "5000.00"
`currency`requireddata[].currency	string \| null	-
`sipUsername`requireddata[].sipUsername	string \| null	-
`portalEmail`requireddata[].portalEmail	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`trunkCount`requireddata[].trunkCount	integer	Trunks excluding archived ones
`trunksUp`requireddata[].trunksUp	integer	-
`trunksDown`requireddata[].trunksDown	integer	-
`liveCalls`requireddata[].liveCalls	integer	-
`calls24h`requireddata[].calls24h	integer	-
`answered24h`requireddata[].answered24h	integer	-
`asr24h`requireddata[].asr24h	number \| null	Percent; null when no calls ran (not 0)
`revenue24h`requireddata[].revenue24h	number	US dollars as a JSON number (computed figure)
`margin24h`requireddata[].margin24h	number	US dollars as a JSON number (computed figure)
`marginPct24h`requireddata[].marginPct24h	number \| null	-
`pddMs24h`requireddata[].pddMs24h	number \| null	-
`creditUsedPct`requireddata[].creditUsedPct	number \| null	-
`contact`requireddata[].contact	object \| null	-
`name`requireddata[].contact.name	string	-
`email`requireddata[].contact.email	string \| null	-
`phone`requireddata[].contact.phone	string \| null	-
`attention`requireddata[].attention	object \| null	Open operational issues. Null means the check could not run, not that nothing is wrong.
`highest`requireddata[].attention.highest	string \| null	-
`open`requireddata[].attention.open	integer	-
`unacknowledged`requireddata[].attention.unacknowledged	integer	-
`refs`requireddata[].attention.refs	string[]	-
`setup`requireddata[].setup	object	-
`trunks`requireddata[].setup.trunks	integer	-
`enabled`requireddata[].setup.enabled	integer	-
`identified`requireddata[].setup.identified	integer	-
`routed`requireddata[].setup.routed	integer	-
`unrouted`requireddata[].setup.unrouted	integer	-
`refused24h`requireddata[].refused24h	object	-
`forbidden`requireddata[].refused24h.forbidden	integer	-
`capacity`requireddata[].refused24h.capacity	integer	-
`flags`requireddata[].flags	string[]	Filterable problem and state flags, e.g. "problem:no_traffic"

Errors

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

Create a Switch customer

POST/api/v1/switch/customers

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

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

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

Request body (application/json)

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

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`label`requireddata.label	string	-
`source`requireddata.source	string	-One of `marketplace`, `external`
`status`requireddata.status	string	-One of `draft`, `active`, `suspended`, `closed`
`externalRef`requireddata.externalRef	string \| null	-
`balance`requireddata.balance	money	Prepaid wallet balance (negative = owed), 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
`creditLimit`requireddata.creditLimit	string	USD decimal string as stored (2 decimal places), e.g. "5000.00"
`currency`requireddata.currency	string \| null	-
`markupPct`requireddata.markupPct	string \| null	Default markup over cost, percent as a decimal string
`billingIncrement`requireddata.billingIncrement	string \| null	e.g. "60/60" or "6/6"
`minMarginPct`requireddata.minMarginPct	string \| null	-
`marginFloorAction`requireddata.marginFloorAction	string \| null	-One of `block`, `alert`
`dailySpendCap`requireddata.dailySpendCap	string \| null	USD decimal string as stored (2 decimal places), e.g. "5000.00"
`maxConcurrentCalls`requireddata.maxConcurrentCalls	integer \| null	-
`maxCps`requireddata.maxCps	integer \| null	-
`blockedPrefixes`requireddata.blockedPrefixes	string[] \| null	-
`sipUsername`requireddata.sipUsername	string \| null	-
`portalEmail`requireddata.portalEmail	string \| null	-
`taxCountry`requireddata.taxCountry	string \| null	-
`taxId`requireddata.taxId	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`sipPassword`requireddata.sipPassword	string	The inbound SIP password in plain text. Returned ONCE, here.
`defaultTrunkId`requireddata.defaultTrunkId	string (uuid)	The "Default" trunk created with every customer
`apiKey`requireddata.apiKey	string	The customer's first API key. Returned ONCE, here.
`apiKeyPrefix`requireddata.apiKeyPrefix	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.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

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

Run it here with a test key.

Get a Switch customer command-centre overview

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`customer`requireddata.customer	object	-
`id`requireddata.customer.id	string (uuid)	-
`label`requireddata.customer.label	string	-
`status`requireddata.customer.status	string	-One of `draft`, `active`, `suspended`, `closed`
`source`requireddata.customer.source	string	-
`kpis`requireddata.kpis	object	Balance owed, wallet, credit used and today's traffic figures (numbers)
`commercial`requireddata.commercial	object	-
`activity`requireddata.activity	object[]	-
`topDestinationsToday`requireddata.topDestinationsToday	object[]	-
`health`data.health	any	-
`setup`data.setup	any	-
`reconciliation`data.reconciliation	any	-
`freshness`data.freshness	any	-

Errors

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

Get a Switch customer

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`label`requireddata.label	string	-
`source`requireddata.source	string	-One of `marketplace`, `external`
`status`requireddata.status	string	-One of `draft`, `active`, `suspended`, `closed`
`externalRef`requireddata.externalRef	string \| null	-
`balance`requireddata.balance	money	Prepaid wallet balance (negative = owed), 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
`creditLimit`requireddata.creditLimit	string	USD decimal string as stored (2 decimal places), e.g. "5000.00"
`currency`requireddata.currency	string \| null	-
`markupPct`requireddata.markupPct	string \| null	Default markup over cost, percent as a decimal string
`billingIncrement`requireddata.billingIncrement	string \| null	e.g. "60/60" or "6/6"
`minMarginPct`requireddata.minMarginPct	string \| null	-
`marginFloorAction`requireddata.marginFloorAction	string \| null	-One of `block`, `alert`
`dailySpendCap`requireddata.dailySpendCap	string \| null	USD decimal string as stored (2 decimal places), e.g. "5000.00"
`maxConcurrentCalls`requireddata.maxConcurrentCalls	integer \| null	-
`maxCps`requireddata.maxCps	integer \| null	-
`blockedPrefixes`requireddata.blockedPrefixes	string[] \| null	-
`sipUsername`requireddata.sipUsername	string \| null	-
`sipPasswordSet`requireddata.sipPasswordSet	boolean	Whether an inbound SIP password is set. The value itself is only ever returned by the audited credentials endpoint.
`portalEmail`requireddata.portalEmail	string \| null	-
`taxCountry`requireddata.taxCountry	string \| null	-
`taxId`requireddata.taxId	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`ipAcls`requireddata.ipAcls	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.

Update a Switch customer

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`label`requireddata.label	string	-
`source`requireddata.source	string	-One of `marketplace`, `external`
`status`requireddata.status	string	-One of `draft`, `active`, `suspended`, `closed`
`externalRef`requireddata.externalRef	string \| null	-
`balance`requireddata.balance	money	Prepaid wallet balance (negative = owed), 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
`creditLimit`requireddata.creditLimit	string	USD decimal string as stored (2 decimal places), e.g. "5000.00"
`currency`requireddata.currency	string \| null	-
`markupPct`requireddata.markupPct	string \| null	Default markup over cost, percent as a decimal string
`billingIncrement`requireddata.billingIncrement	string \| null	e.g. "60/60" or "6/6"
`minMarginPct`requireddata.minMarginPct	string \| null	-
`marginFloorAction`requireddata.marginFloorAction	string \| null	-One of `block`, `alert`
`dailySpendCap`requireddata.dailySpendCap	string \| null	USD decimal string as stored (2 decimal places), e.g. "5000.00"
`maxConcurrentCalls`requireddata.maxConcurrentCalls	integer \| null	-
`maxCps`requireddata.maxCps	integer \| null	-
`blockedPrefixes`requireddata.blockedPrefixes	string[] \| null	-
`sipUsername`requireddata.sipUsername	string \| null	-
`sipPasswordSet`requireddata.sipPasswordSet	boolean	Whether an inbound SIP password is set. The value itself is only ever returned by the audited credentials endpoint.
`portalEmail`requireddata.portalEmail	string \| null	-
`taxCountry`requireddata.taxCountry	string \| null	-
`taxId`requireddata.taxId	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.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoSTALE_WRITE

HTTP

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

Run it here with a test key.

Delete a draft Switch customer

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

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

Only for a customer that never carried traffic or held financial records. Offboard a real customer with the close lifecycle action instead.

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`deleted`requireddata.deleted	boolean	-One of `true`
`id`requireddata.id	string (uuid)	-
`label`requireddata.label	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

Get a Switch customer lifecycle state and financial position

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`customer`requireddata.customer	object	-
`id`requireddata.customer.id	string (uuid)	-
`label`requireddata.customer.label	string	-
`status`requireddata.customer.status	string	-One of `draft`, `active`, `suspended`, `closed`
`source`requireddata.customer.source	string	-
`createdAt`requireddata.customer.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`available`requireddata.available	string[]	Actions allowed from the current stateOne of `activate`, `suspend`, `reactivate`, `close`, `reopen`
`liveCalls`requireddata.liveCalls	integer	-
`trunks`requireddata.trunks	object	-
`total`requireddata.trunks.total	integer	-
`active`requireddata.trunks.active	integer	-
`history`requireddata.history	object[]	-
`id`requireddata.history[].id	string	-
`at`requireddata.history[].at	string (date-time)	ISO-8601 timestamp (UTC)
`action`requireddata.history[].action	string	-
`from`requireddata.history[].from	string \| null	-
`to`requireddata.history[].to	string \| null	-
`reason`requireddata.history[].reason	string \| null	-
`actor`requireddata.history[].actor	string \| null	Email of whoever did it
`detail`requireddata.history[].detail	object	-
`financials`requireddata.financials	object	-
`currency`requireddata.financials.currency	string	-
`prepaidBalance`requireddata.financials.prepaidBalance	number	US dollars as a JSON number (computed figure)
`invoicesOutstanding`requireddata.financials.invoicesOutstanding	number	US dollars as a JSON number (computed figure)
`invoicesOverdue`requireddata.financials.invoicesOverdue	number	US dollars as a JSON number (computed figure)
`creditNotesOpen`requireddata.financials.creditNotesOpen	number	US dollars as a JSON number (computed figure)
`unbilledUsage`requireddata.financials.unbilledUsage	number	US dollars as a JSON number (computed figure)
`creditLimit`requireddata.financials.creditLimit	number	US dollars as a JSON number (computed figure)
`openInvoiceCount`requireddata.financials.openInvoiceCount	integer	-
`paidInvoiceCount`requireddata.financials.paidInvoiceCount	integer	-
`paymentCount`requireddata.financials.paymentCount	integer	-
`hasOpenPosition`requireddata.financials.hasOpenPosition	boolean	-
`canDelete`requireddata.canDelete	boolean	-
`deleteBlockers`requireddata.deleteBlockers	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.

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

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`action`required	string	-One of `activate`, `suspend`, `reactivate`, `close`, `reopen`
`reason`	string \| null	-max 2000 chars
`disconnectLiveCalls`	boolean	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`label`requireddata.label	string	-
`status`requireddata.status	string	-One of `draft`, `active`, `suspended`, `closed`
`previousStatus`requireddata.previousStatus	string	-One of `draft`, `active`, `suspended`, `closed`
`action`requireddata.action	string	-
`liveCallsAtChange`requireddata.liveCallsAtChange	integer	-
`disconnectedLiveCalls`requireddata.disconnectedLiveCalls	boolean	-
`disconnectIncomplete`data.disconnectIncomplete	boolean	-
`apiKeysRevoked`data.apiKeysRevoked	integer	-
`financialsUnchanged`requireddata.financialsUnchanged	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 POST "https://packetexchange.io/api/v1/switch/customers/<id>/lifecycle" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "activate"
}'

Run it here with a test key.

List a Switch customer lifecycle history

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`limit`	query	integer	Default 50

Response 200

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

Errors

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

Rotate a Switch customer inbound SIP password

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`sipUsername`requireddata.sipUsername	string \| null	-
`sipPassword`requireddata.sipPassword	string \| 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

Reveal a Switch customer inbound SIP credentials

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

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

Errors

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

List what needs attention on a Switch customer

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object[]	-
`kind`requireddata[].kind	string	-One of `quality`, `commercial`, `credit`, `config`, `setup`
`title`requireddata[].title	string	-
`detail`requireddata[].detail	string	-
`at`requireddata[].at	string	-
`actionable`requireddata[].actionable	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 operational issues on a Switch customer

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object[]	-
`ref`requireddata[].ref	string	Issue reference, e.g. OPS-1042
`detector`requireddata[].detector	string	-
`severity`requireddata[].severity	string	-
`status`requireddata[].status	string	-
`title`requireddata[].title	string	-
`summary`requireddata[].summary	string	-
`trigger`requireddata[].trigger	string	-
`recovery`requireddata[].recovery	string	-
`sampleSize`requireddata[].sampleSize	number	-
`evidence`requireddata[].evidence	object[]	-
`label`requireddata[].evidence[].label	string	-
`value`requireddata[].evidence[].value	string	-
`firstDetectedAt`requireddata[].firstDetectedAt	string	-
`lastDetectedAt`requireddata[].lastDetectedAt	string	-
`acknowledgedAt`requireddata[].acknowledgedAt	string \| null	-
`resolvedAt`requireddata[].resolvedAt	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.

List a Switch customer contacts

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`subAccountId`requireddata[].subAccountId	string (uuid)	-
`name`requireddata[].name	string	-
`role`requireddata[].role	string	-One of `technical`, `noc`, `billing`, `escalation`, `commercial`
`email`requireddata[].email	string \| null	-
`phone`requireddata[].phone	string \| null	-
`priority`requireddata[].priority	integer	1 = try first within this role
`isPrimary`requireddata[].isPrimary	boolean	-
`preferredMethod`requireddata[].preferredMethod	string	-One of `email`, `phone`, `either`
`availability`requireddata[].availability	string \| null	-One of `24x7`, `business_hours`, `on_call`
`timezone`requireddata[].timezone	string \| null	-
`notes`requireddata[].notes	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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

Add a Switch customer contact

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

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

Response 201

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

Run it here with a test key.

Update a Switch customer contact

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`contactId`required	path	string (uuid)	-

Request body (application/json)

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

Response 200

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

Run it here with a test key.

Delete a Switch customer contact

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`contactId`required	path	string (uuid)	-

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/customers/<id>/contacts/<contactId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

List internal notes on a Switch customer

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`subAccountId`requireddata[].subAccountId	string (uuid)	-
`body`requireddata[].body	string	-
`type`requireddata[].type	string	-One of `general`, `technical`, `billing`, `warning`
`pinned`requireddata[].pinned	boolean	-
`followUpAt`requireddata[].followUpAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdBy`requireddata[].createdBy	string (uuid) \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`authorName`requireddata[].authorName	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.

Add an internal note to a Switch customer

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`body`required	string	-max 4000 chars
`type`	string	-One of `general`, `technical`, `billing`, `warning`
`pinned`	boolean	-
`followUpAt`	string (date-time) \| null	-

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`subAccountId`requireddata.subAccountId	string (uuid)	-
`body`requireddata.body	string	-
`type`requireddata.type	string	-One of `general`, `technical`, `billing`, `warning`
`pinned`requireddata.pinned	boolean	-
`followUpAt`requireddata.followUpAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdBy`requireddata.createdBy	string (uuid) \| 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.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.
AlsoSTALE_WRITE

HTTP

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

Run it here with a test key.

Edit, pin or flag a Switch customer note

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

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

The author and creation time never change.

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`noteId`required	path	string (uuid)	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchCustomerNote, 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/customers/<id>/notes/<noteId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Hello from Acme",
  "type": "general"
}'

Run it here with a test key.

Delete a Switch customer note

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`noteId`required	path	string (uuid)	-

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 per-destination quality for a Switch customer

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`window`	query	integer	Hours: 1, 24 or 168. Default 24
`from`	query	string	Explicit window start (ISO-8601); overrides `window`
`to`	query	string	Explicit window end (ISO-8601)

Response 200

Field	Type	Description
`data`required	object	-
`windowHours`requireddata.windowHours	number	-
`window`requireddata.window	object	-
`from`requireddata.window.from	string (date-time)	ISO-8601 timestamp (UTC)
`to`requireddata.window.to	string (date-time)	ISO-8601 timestamp (UTC)
`label`requireddata.window.label	string	-
`destinationDigits`requireddata.destinationDigits	integer	-
`kpis`requireddata.kpis	object	-
`calls`requireddata.kpis.calls	integer	-
`answered`requireddata.kpis.answered	integer	-
`asr`requireddata.kpis.asr	number \| null	-
`ner`requireddata.kpis.ner	number \| null	-
`destinations`requireddata.destinations	object[]	-
`prefix`requireddata.destinations[].prefix	string	-
`calls`requireddata.destinations[].calls	integer	-
`answered`requireddata.destinations[].answered	integer	-
`asr`requireddata.destinations[].asr	number \| null	-
`ner`requireddata.destinations[].ner	number \| null	-
`health`requireddata.destinations[].health	string	-
`thresholds`data.thresholds	any	-
`minJudgeableSessions`requireddata.minJudgeableSessions	integer	-
`supports`requireddata.supports	string[]	Call Records filter ids this view honours
`unsupported`requireddata.unsupported	any[]	Filters you sent that this view could not apply

Errors

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

Drill into one destination for a Switch customer

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`window`	query	integer	Hours: 1, 24 or 168. Default 24
`from`	query	string	Explicit window start (ISO-8601); overrides `window`
`to`	query	string	Explicit window end (ISO-8601)
`prefix`required	query	string	The destination prefix to open

Response 200

Field	Type	Description
`data`required	object	-
`windowHours`requireddata.windowHours	number	-
`window`requireddata.window	object	-
`from`requireddata.window.from	string (date-time)	ISO-8601 timestamp (UTC)
`to`requireddata.window.to	string (date-time)	ISO-8601 timestamp (UTC)
`label`requireddata.window.label	string	-
`destinationDigits`requireddata.destinationDigits	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.

HTTP

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

Run it here with a test key.

Get a Switch customer receivables summary

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`balanceOwed`requireddata.balanceOwed	number	Open invoices less open credit notes
`grossBalanceOwed`requireddata.grossBalanceOwed	number	US dollars as a JSON number (computed figure)
`creditNotesOpen`requireddata.creditNotesOpen	number	US dollars as a JSON number (computed figure)
`paymentsRecorded`requireddata.paymentsRecorded	number	US dollars as a JSON number (computed figure)
`creditLimit`requireddata.creditLimit	number	US dollars as a JSON number (computed figure)
`unbilledRated`requireddata.unbilledRated	number	US dollars as a JSON number (computed figure)
`unbilledSinceLastInvoice`requireddata.unbilledSinceLastInvoice	number	US dollars as a JSON number (computed figure)
`unratedUsage`requireddata.unratedUsage	object	-
`calls`requireddata.unratedUsage.calls	integer	-
`minutes`requireddata.unratedUsage.minutes	number \| null	-
`note`requireddata.unratedUsage.note	string	-
`overdueIsSubsetOfOpenInvoices`requireddata.overdueIsSubsetOfOpenInvoices	boolean	-One of `true`
`disputed`requireddata.disputed	enum \| null	Customer-side disputes are not recorded, so always nullOne of `null`
`avgDaysToPay`requireddata.avgDaysToPay	number \| null	-
`lastInvoicePeriodEnd`requireddata.lastInvoicePeriodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-
`aging`requireddata.aging	object	-
`current`requireddata.aging.current	number	US dollars as a JSON number (computed figure)
`d1_30`requireddata.aging.d1_30	number	US dollars as a JSON number (computed figure)
`d31_60`requireddata.aging.d31_60	number	US dollars as a JSON number (computed figure)
`d61_90`requireddata.aging.d61_90	number	US dollars as a JSON number (computed figure)
`d90_plus`requireddata.aging.d90_plus	number	US dollars as a JSON number (computed figure)

Errors

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

Get a Switch customer credit position

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`customerId`requireddata.customerId	string (uuid)	-
`label`requireddata.label	string	-
`currency`requireddata.currency	string	-
`mode`requireddata.mode	string	prepaid or postpaid, derived from the credit limit
`creditLimit`requireddata.creditLimit	object	-
`value`requireddata.creditLimit.value	number	US dollars as a JSON number (computed figure)
`ambiguous`requireddata.creditLimit.ambiguous	string \| null	-
`exposure`requireddata.exposure	number	US dollars as a JSON number (computed figure)
`balance`requireddata.balance	number	US dollars as a JSON number (computed figure)
`reservations`requireddata.reservations	object	-
`amount`requireddata.reservations.amount	number	US dollars as a JSON number (computed figure)
`calls`requireddata.reservations.calls	integer	-
`enforced`requireddata.reservations.enforced	boolean	-
`basis`requireddata.reservations.basis	string	-
`availableCredit`requireddata.availableCredit	number	US dollars as a JSON number (computed figure)
`availableAfterReservations`requireddata.availableAfterReservations	number	US dollars as a JSON number (computed figure)
`admitsNextCall`requireddata.admitsNextCall	boolean	-
`usedPct`requireddata.usedPct	number \| null	-
`overCommitted`requireddata.overCommitted	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.

Preview how a payment would be allocated to invoices

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`amount`	query	number	USD amount to preview

Response 200

Field	Type	Description
`data`required	object	-
`billingMode`requireddata.billingMode	string	-
`currency`requireddata.currency	string	-
`wouldAllocate`requireddata.wouldAllocate	object[]	-
`invoiceId`requireddata.wouldAllocate[].invoiceId	string (uuid)	-
`invoiceNumber`requireddata.wouldAllocate[].invoiceNumber	string	-
`applied`requireddata.wouldAllocate[].applied	number	US dollars as a JSON number (computed figure)
`clearsInvoice`requireddata.wouldAllocate[].clearsInvoice	boolean	-
`wouldLeaveUnapplied`requireddata.wouldLeaveUnapplied	number	US dollars as a JSON number (computed figure)

Errors

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

Record a payment received from a Switch customer

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`X-Idempotency-Key`	header	string	Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

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

Response 201

Field	Type	Description
`data`required	object	-
`kind`requireddata.kind	string	-One of `payment`
`transactionId`requireddata.transactionId	string (uuid)	-
`amount`requireddata.amount	number	US dollars as a JSON number (computed figure)
`currency`requireddata.currency	string	-
`postedAt`requireddata.postedAt	string (date-time)	ISO-8601 timestamp (UTC)
`externalReference`requireddata.externalReference	string \| null	-
`method`requireddata.method	string \| null	-
`operatorLabel`requireddata.operatorLabel	string \| null	-
`billingMode`requireddata.billingMode	string	-
`allocations`requireddata.allocations	object[]	Oldest-due invoices first
`invoiceId`requireddata.allocations[].invoiceId	string (uuid)	-
`invoiceNumber`requireddata.allocations[].invoiceNumber	string	-
`applied`requireddata.allocations[].applied	number	US dollars as a JSON number (computed figure)
`outstandingAfter`requireddata.allocations[].outstandingAfter	number	US dollars as a JSON number (computed figure)
`status`requireddata.allocations[].status	string	-
`unapplied`requireddata.unapplied	number	Left on account after paying every open invoice
`positionAfter`requireddata.positionAfter	object	-

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

Run it here with a test key.

Reverse a recorded Switch customer payment

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`transactionId`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`reason`required	string	-max 500 chars

Response 201

Field	Type	Description
`data`required	object	-
`kind`requireddata.kind	string	-One of `reversal`
`reversesTransactionId`requireddata.reversesTransactionId	string (uuid)	-
`transactionId`requireddata.transactionId	string (uuid)	-
`amount`requireddata.amount	number	US dollars as a JSON number (computed figure)
`currency`requireddata.currency	string	-
`reason`requireddata.reason	string	-
`unwound`requireddata.unwound	object[]	-
`positionAfter`requireddata.positionAfter	object	-

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

Run it here with a test key.

Preview an invoice for a Switch customer unbilled period

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`notes`	string \| null	-max 2000 chars
`includeBroughtForward`	boolean	-
`applyCredits`	boolean	-
`excludeUnrated`	object \| null	Issue despite unrated usage in the period, with the reason recorded on the invoice
`reason`requiredexcludeUnrated.reason	string	-max 2000 chars

Response 200

Field	Type	Description
`data`required	object	-
`customer`requireddata.customer	object	-
`id`requireddata.customer.id	string (uuid)	-
`label`requireddata.customer.label	string	-
`legalName`requireddata.customer.legalName	string	-
`currency`requireddata.customer.currency	string	-
`period`requireddata.period	object	-
`dueDate`requireddata.dueDate	string	-
`paymentTermsDays`requireddata.paymentTermsDays	integer	-
`currency`requireddata.currency	string	-
`usage`requireddata.usage	object	-
`unrated`requireddata.unrated	object	Usage that has no price yet; blocks issue unless excluded
`reviewToken`requireddata.reviewToken	string	Pass to generate-invoice to issue exactly what was reviewed
`reviewDigest`requireddata.reviewDigest	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 POST "https://packetexchange.io/api/v1/switch/customers/<id>/invoice-preview" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "notes": "Example",
  "includeBroughtForward": true
}'

Run it here with a test key.

Issue the reviewed invoice for a Switch customer

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`notes`	string \| null	-max 2000 chars
`includeBroughtForward`	boolean	-
`applyCredits`	boolean	-
`excludeUnrated`	object \| null	Issue despite unrated usage in the period, with the reason recorded on the invoice
`reason`requiredexcludeUnrated.reason	string	-max 2000 chars
`reviewToken`required	string	-max 120 chars

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`invoiceNumber`requireddata.invoiceNumber	string	-
`customerId`requireddata.customerId	string (uuid)	-
`status`requireddata.status	string	-
`subtotal`requireddata.subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`currency`requireddata.currency	string	-
`periodStart`requireddata.periodStart	string (date-time)	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time)	ISO-8601 timestamp (UTC)
`issueDate`requireddata.issueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`dueDate`requireddata.dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`lines`requireddata.lines	object[]	-
`reviewDigest`requireddata.reviewDigest	string \| 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.
AlsoINVOICE_REVIEW_STALE, INVOICE_UNRATED_USAGE, STALE_WRITE

HTTP

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

Run it here with a test key.

Get a Switch customer billing profile

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`profile`requireddata.profile	object \| null	-
`id`requireddata.profile.id	string (uuid)	-
`legalName`requireddata.profile.legalName	string	-
`version`requireddata.profile.version	integer	Bumped on every save; frozen onto invoices issued afterwards
`updatedAt`requireddata.profile.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`resolved`requireddata.resolved	object	-
`source`requireddata.resolved.source	string	-One of `profile`, `fallback`
`profileId`requireddata.resolved.profileId	string (uuid) \| null	-
`profileVersion`requireddata.resolved.profileVersion	integer \| null	-
`customer`requireddata.resolved.customer	object	-
`billingAddress`requireddata.resolved.billingAddress	object \| null	-
`issuer`requireddata.resolved.issuer	object	-
`terms`requireddata.resolved.terms	object	-
`currency`requireddata.resolved.terms.currency	string	-
`billingCycle`requireddata.resolved.terms.billingCycle	string \| null	-
`billingTimezone`requireddata.resolved.terms.billingTimezone	string	-
`paymentTermsDays`requireddata.resolved.terms.paymentTermsDays	integer	-
`purchaseOrderRef`requireddata.resolved.terms.purchaseOrderRef	string \| null	-
`paymentInstructions`requireddata.resolved.terms.paymentInstructions	string \| null	-
`recipients`data.resolved.recipients	any	-

Errors

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

Save a Switch customer billing profile

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

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

Response 200

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

Response 202

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

Errors

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

HTTP

curl -X PUT "https://packetexchange.io/api/v1/switch/customers/<id>/billing-profile" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "legalName": "<legalName>",
  "tradingName": "<tradingName>"
}'

Run it here with a test key.

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

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

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

An unknown customer answers 404 NOT_FOUND.

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`customerId`requireddata.customerId	string (uuid)	-
`customerLabel`requireddata.customerLabel	string	-
`defaultDeck`requireddata.defaultDeck	object \| null	-
`id`requireddata.defaultDeck.id	string (uuid)	-
`name`requireddata.defaultDeck.name	string	-
`version`requireddata.defaultDeck.version	integer	-
`status`requireddata.defaultDeck.status	string	-
`currency`requireddata.defaultDeck.currency	string	-
`isSystemDefault`requireddata.defaultDeck.isSystemDefault	boolean	-
`defaultRatePerUnit`requireddata.defaultDeck.defaultRatePerUnit	number \| null	USD per minute for destinations the deck does not list; null = refuse them
`charging`requireddata.defaultDeck.charging	object	-
`systemDefault`requireddata.systemDefault	object \| null	Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.
`trunks`requireddata.trunks	object[]	-
`effective`requireddata.trunks[].effective	object	-
`deck`requireddata.trunks[].effective.deck	object \| null	Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.
`mode`requireddata.trunks[].effective.mode	string	-
`choice`requireddata.trunks[].effective.choice	string	Which rule won: the trunk, the customer default or the system default
`bypassesCustomerDefault`requireddata.trunks[].effective.bypassesCustomerDefault	boolean	-
`customerDefault`requireddata.trunks[].effective.customerDefault	object \| null	Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.
`systemDefault`requireddata.trunks[].effective.systemDefault	object \| null	Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.
`liveRowCount`requireddata.trunks[].effective.liveRowCount	integer	-
`explanation`requireddata.trunks[].effective.explanation	string	-
`problem`requireddata.trunks[].effective.problem	string \| null	-
`trunksDisagree`requireddata.trunksDisagree	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.

Set a Switch customer default sell deck

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`deckId`	string (uuid) \| null	null clears the default
`confirm`	boolean	-
`reason`	string	-

Response 200

Field	Type	Description
`data`required	object	-
`changed`data.changed	boolean	-One of `true`
`wouldChange`data.wouldChange	object	-
`trunks`requireddata.wouldChange.trunks	string[]	-
`message`requireddata.wouldChange.message	string	-
`trunks`data.trunks	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 PUT "https://packetexchange.io/api/v1/switch/customers/<id>/sell-deck" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "deckId": "<deckId>",
  "confirm": true
}'

Run it here with a test key.

Email a Switch customer a portal sign-in link

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`search`	query	string	Prefix or destination text
`limit`	query	integer	-
`offset`	query	integer	-
`view`	query	string	Default currentOne of current, scheduled, discontinued, expiring, all
`origin`	query	string	-One of any, origin_only, destination_only
`increment`	query	string	-One of any, custom, inherited
`cost`	query	string	-One of any, missing
`margin`	query	string	-One of any, thin, negative

Response 200

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string (uuid)	-
`subAccountId`requireddata.rows[].subAccountId	string (uuid)	-
`customerTrunkId`requireddata.rows[].customerTrunkId	string (uuid) \| null	-
`prefix`requireddata.rows[].prefix	string	-
`originPrefix`requireddata.rows[].originPrefix	string	"" = any origin
`ratePerUnit`requireddata.rows[].ratePerUnit	money	Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.rows[].billingIncrement	string \| null	-
`status`requireddata.rows[].status	string	active, pending (scheduled) or discontinued
`effectiveFrom`requireddata.rows[].effectiveFrom	string (date-time)	ISO-8601 timestamp (UTC)
`endDate`requireddata.rows[].endDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`buyCost`requireddata.rows[].buyCost	number \| null	Best eligible buy cost per minute (USD number); null = no supplier prices it
`marginPct`requireddata.rows[].marginPct	number \| null	-
`thin`requireddata.rows[].thin	boolean	-
`negative`requireddata.rows[].negative	boolean	-
`costSupplier`requireddata.rows[].costSupplier	string \| null	-
`costSource`requireddata.rows[].costSource	string	-
`costMatchedPrefix`requireddata.rows[].costMatchedPrefix	string \| null	-
`costNote`requireddata.rows[].costNote	string \| null	-
`total`requireddata.total	integer	-
`totalIsPageScoped`requireddata.totalIsPageScoped	boolean	True when a cost or margin filter narrowed the page, so `total` counts this page only
`limit`requireddata.limit	integer	-
`offset`requireddata.offset	integer	-
`view`requireddata.view	string	-
`summary`requireddata.summary	object	-
`prefixes`requireddata.summary.prefixes	integer	-
`blendedMarginPct`requireddata.summary.blendedMarginPct	number \| null	-
`thinCount`requireddata.summary.thinCount	integer	-
`negativeCount`requireddata.summary.negativeCount	integer	-
`defaultRateCostCount`requireddata.summary.defaultRateCostCount	integer	-
`unpricedCount`requireddata.summary.unpricedCount	integer	-
`basis`data.basis	any	-

Errors

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

Add or replace one Switch customer sell rate

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

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

Takes effect now on the customer's default trunk. Use the per-trunk rate endpoints to price a specific trunk.

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`prefix`required	string	-max 24 chars
`rate`required	number	USD per minutemin 0
`origin`	string	-max 24 chars
`billingIncrement`	string	-max 10 chars

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`subAccountId`requireddata.subAccountId	string (uuid)	-
`customerTrunkId`requireddata.customerTrunkId	string (uuid) \| null	-
`prefix`requireddata.prefix	string	-
`originPrefix`requireddata.originPrefix	string	"" = any origin
`ratePerUnit`requireddata.ratePerUnit	money	Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.billingIncrement	string \| null	-
`status`requireddata.status	string	active, pending (scheduled) or discontinued
`effectiveFrom`requireddata.effectiveFrom	string (date-time)	ISO-8601 timestamp (UTC)
`endDate`requireddata.endDate	string (date-time) \| null	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/customers/<id>/sell-rates" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prefix": "44",
  "rate": 1
}'

Run it here with a test key.

Count a Switch customer sell rates by view

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`current`requireddata.current	integer	-
`scheduled`requireddata.scheduled	integer	-
`expiring`requireddata.expiring	integer	-
`discontinued`requireddata.discontinued	integer	-
`all`requireddata.all	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.

List upcoming sell-rate starts and ends for a Switch customer

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`subAccountId`requireddata[].subAccountId	string (uuid)	-
`customerTrunkId`requireddata[].customerTrunkId	string (uuid) \| null	-
`prefix`requireddata[].prefix	string	-
`originPrefix`requireddata[].originPrefix	string	"" = any origin
`ratePerUnit`requireddata[].ratePerUnit	money	Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata[].billingIncrement	string \| null	-
`status`requireddata[].status	string	active, pending (scheduled) or discontinued
`effectiveFrom`requireddata[].effectiveFrom	string (date-time)	ISO-8601 timestamp (UTC)
`endDate`requireddata[].endDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`kind`requireddata[].kind	string	-One of `starts`, `ends`
`at`requireddata[].at	string (date-time) \| null	ISO-8601 timestamp (UTC)

Errors

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

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`rateNoticeDays`requireddata.rateNoticeDays	integer	Days of notice before a sell-rate increase takes effect; 0 = none
`queued`requireddata.queued	integer	Sell-rate changes queued and not yet in effect
`increases`requireddata.increases	integer	How many of the queued changes are increases
`nextEffectiveFrom`requireddata.nextEffectiveFrom	string (date-time) \| null	When the soonest queued change takes effect
`defaultRecipients`requireddata.defaultRecipients	string[]	Who a notice goes to when you do not name recipients

Errors

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

Set a Switch customer rate-change notice period

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`rateNoticeDays`required	integer	Whole days of notice before an increase takes effect; 0 = none0 to 365

Response 200

Field	Type	Description
`data`required	object	-
`rateNoticeDays`requireddata.rateNoticeDays	integer	-0 to 365

Response 202

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

Errors

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

HTTP

curl -X PUT "https://packetexchange.io/api/v1/switch/customers/<id>/sell-rates/notice" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rateNoticeDays": 1
}'

Run it here with a test key.

List a Switch customer queued sell-rate changes

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`trunkId`	query	string (uuid)	Only this trunk's changes

Response 200

Field	Type	Description
`data`required	object[]	-
`trunk`requireddata[].trunk	string	The customer trunk's label ("" when it has none)
`prefix`requireddata[].prefix	string	-
`origin`requireddata[].origin	string	Origin prefix for origin-based pricing; "" when the rate applies from any origin
`currentRate`requireddata[].currentRate	money \| null	The rate in force today; null for a new destination USD as a decimal string with exactly 6 places, e.g. "0.012500".
`newRate`requireddata[].newRate	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`changePct`requireddata[].changePct	number \| null	Percentage move, 2 decimals; null for a new destination
`currentIncrement`requireddata[].currentIncrement	string \| null	-
`newIncrement`requireddata[].newIncrement	string \| null	-
`effectiveFrom`requireddata[].effectiveFrom	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.

Download a Switch customer queued sell-rate changes as CSV

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`trunkId`	query	string (uuid)	Only this trunk's changes

Response 200 (text/csv)

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

Errors

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

HTTP

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

Run it here with a test key.

Email a Switch customer a rate-change notice

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	object	-
`sent`requireddata.sent	string[]	Addresses the notice was accepted for
`failed`requireddata.failed	string[]	Addresses the mail service refused
`rows`requireddata.rows	integer	Changes in the notice
`increases`requireddata.increases	integer	-
`decreases`requireddata.decreases	integer	-
`added`requireddata.added	integer	New destinations (no rate today)
`firstEffectiveFrom`requireddata.firstEffectiveFrom	string (date-time)	The earliest effective date in the notice

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

Run it here with a test key.

Preview discontinuing a Switch customer whole sell deck

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	object	-
`customerLabel`requireddata.customerLabel	string	-
`activeRates`requireddata.activeRates	integer	-
`scheduledRates`requireddata.scheduledRates	integer	-
`alreadyDiscontinued`requireddata.alreadyDiscontinued	integer	-
`endDate`requireddata.endDate	string (date-time)	ISO-8601 timestamp (UTC)
`immediate`requireddata.immediate	boolean	-
`timezone`requireddata.timezone	string \| null	-
`effectOnNewCalls`requireddata.effectOnNewCalls	string	-
`minutes30d`requireddata.minutes30d	number	-
`calls30d`requireddata.calls30d	integer	-
`revenue30d`requireddata.revenue30d	number	US dollars as a JSON number (computed figure)
`impactTruncated`requireddata.impactTruncated	boolean	-
`sample`requireddata.sample	object[]	-
`prefix`requireddata.sample[].prefix	string	-
`originPrefix`requireddata.sample[].originPrefix	string	-
`ratePerUnit`requireddata.sample[].ratePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata.sample[].billingIncrement	string \| 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/customers/<id>/sell-rates/discontinue-all/preview" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "effectiveFrom": "<effectiveFrom>",
  "effectiveLocal": "<effectiveLocal>"
}'

Run it here with a test key.

Discontinue a Switch customer whole sell deck

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	object	-
`endDate`requireddata.endDate	string (date-time)	ISO-8601 timestamp (UTC)
`effective`data.effective	any	The moment described in words and in the recorded zone
`revisionId`data.revisionId	string (uuid) \| null	-
`discontinued`requireddata.discontinued	integer	-
`deleted`requireddata.deleted	integer	Deprecated alias of `discontinued`; nothing is deleted
`scheduledLeft`requireddata.scheduledLeft	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/customers/<id>/sell-rates/discontinue-all" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "effectiveFrom": "<effectiveFrom>",
  "effectiveLocal": "<effectiveLocal>"
}'

Run it here with a test key.

Discontinue one Switch customer sell rate

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`rateId`required	path	string (uuid)	-

Request body (application/json)

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

Response 200

Field	Type	Description
`data`required	object	-
`endDate`requireddata.endDate	string (date-time)	ISO-8601 timestamp (UTC)
`effective`data.effective	any	The moment described in words and in the recorded zone
`revisionId`data.revisionId	string (uuid) \| null	-
`discontinued`requireddata.discontinued	boolean	-One of `true`
`deleted`requireddata.deleted	boolean	Deprecated alias; the rate is discontinued, not deletedOne of `true`
`immediate`requireddata.immediate	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/customers/<id>/sell-rates/<rateId>/discontinue" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "effectiveFrom": "<effectiveFrom>",
  "effectiveLocal": "<effectiveLocal>"
}'

Run it here with a test key.

List sell-rate discontinuation events for a Switch customer

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object[]	-
`revisionId`requireddata[].revisionId	string (uuid) \| null	-
`discontinuedAt`requireddata[].discontinuedAt	string (date-time)	ISO-8601 timestamp (UTC)
`rows`requireddata[].rows	integer	-
`label`requireddata[].label	string	-
`effective`data[].effective	any \| null	-
`timezone`requireddata[].timezone	string \| null	-
`changeMode`requireddata[].changeMode	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.

HTTP

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

Run it here with a test key.

Reprice a Switch customer deck as a markup over buy cost

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`markupPct`required	number	-min -100
`prefixes`	string[]	Only these prefixes; omit for the whole deck

Response 200

Field	Type	Description
`data`required	object	-
`updated`requireddata.updated	integer	-
`skipped`requireddata.skipped	integer	-
`basis`data.basis	any	-
`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/customers/<id>/sell-rates/apply-markup" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "markupPct": 1
}'

Run it here with a test key.

Export a Switch customer sell rates as CSV

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`search`	query	string	Prefix or destination text
`view`	query	string	Default currentOne of current, scheduled, discontinued, expiring, all
`origin`	query	string	-One of any, origin_only, destination_only
`increment`	query	string	-One of any, custom, inherited
`cost`	query	string	-One of any, missing
`margin`	query	string	-One of any, thin, negative

Response 200 (text/csv)

The filtered sell deck as a CSV attachment.

Errors

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

Add or replace many Switch customer sell rates

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`rows`required	object[]	-
`prefix`requiredrows[].prefix	string	-max 24 chars
`rate`requiredrows[].rate	number	-min 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	-
`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/customers/<id>/sell-rates/bulk" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "prefix": "44",
      "rate": 1
    }
  ]
}'

Run it here with a test key.

Discontinue one Switch customer sell rate now

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`rateId`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`endDate`requireddata.endDate	string (date-time)	ISO-8601 timestamp (UTC)
`effective`data.effective	any	The moment described in words and in the recorded zone
`revisionId`data.revisionId	string (uuid) \| null	-
`discontinued`requireddata.discontinued	boolean	-One of `true`
`deleted`requireddata.deleted	boolean	Deprecated alias; the rate is discontinued, not deletedOne of `true`
`immediate`requireddata.immediate	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 DELETE "https://packetexchange.io/api/v1/switch/customers/<id>/sell-rates/<rateId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.

Discontinue every Switch customer sell rate now

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`endDate`requireddata.endDate	string (date-time)	ISO-8601 timestamp (UTC)
`effective`data.effective	any	The moment described in words and in the recorded zone
`revisionId`data.revisionId	string (uuid) \| null	-
`discontinued`requireddata.discontinued	integer	-
`deleted`requireddata.deleted	integer	Deprecated alias of `discontinued`; nothing is deleted
`scheduledLeft`requireddata.scheduledLeft	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

List scheduled (future-dated) sell rates for a Switch customer

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Response 200

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

Errors

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

Schedule a future Switch customer sell-rate change

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

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

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

Response 201

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

Run it here with a test key.

Cancel a scheduled Switch customer sell rate

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-
`rateId`required	path	string (uuid)	-

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

Run it here with a test key.

Set a Switch customer billing cycle and payment terms

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string (uuid)	-

Request body (application/json)

Field	Type	Description
`billingCycle`	string \| null	-One of `weekly`, `biweekly`, `monthly`, `manual`
`paymentTermsDays`	integer \| null	-0 to 365

Response 200

Field	Type	Description
`data`required	object	-
`customerId`requireddata.customerId	string (uuid)	-
`billingCycle`requireddata.billingCycle	string \| null	-
`paymentTermsDays`requireddata.paymentTermsDays	integer \| null	-
`nextInvoiceAt`requireddata.nextInvoiceAt	string (date-time) \| null	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/customers/<id>/billing-settings" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "billingCycle": "weekly",
  "paymentTermsDays": 1
}'

Run it here with a test key.