Switch API reference

Switch: routing

Route plans, dialplans, routing rules, ACLs and route traces.

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

BrowseSwitch: routing

List route groups

GET/api/v1/switch/route-plans

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

Route groups (stored as route plans): ordered supplier chains with failover rules. Newest change first, with entry counts.

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`operatorId`requireddata[].operatorId	string (uuid)	-
`name`requireddata[].name	string	-
`description`requireddata[].description	string \| null	-
`enabled`requireddata[].enabled	boolean	-
`failoverSipCodes`requireddata[].failoverSipCodes	integer[]	SIP results that move the call to the next supplier
`maxAttempts`requireddata[].maxAttempts	integer	1 to 6
`selectionMode`requireddata[].selectionMode	string	How the first supplier is picked; failover is always sequentialOne of `priority`, `least_cost`, `weighted`
`failoverTimeoutSeconds`requireddata[].failoverTimeoutSeconds	integer \| null	null = the platform budget
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`entryCount`requireddata[].entryCount	integer	-

Errors

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

Create a route group

POST/api/v1/switch/route-plans

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

Names must be unique per operator. Defaults: priority selection, 3 attempts, the platform failover timeout.

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

Request body (application/json)

Field	Type	Description
`name`required	string	-max 120 chars
`description`	string \| null	-max 2000 chars
`selectionMode`	string	-One of `priority`, `least_cost`, `weighted`
`failoverSipCodes`	integer[]	-
`maxAttempts`	integer	-1 to 6
`failoverTimeoutSeconds`	integer \| null	-5 to 600

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`operatorId`requireddata.operatorId	string (uuid)	-
`name`requireddata.name	string	-
`description`requireddata.description	string \| null	-
`enabled`requireddata.enabled	boolean	-
`failoverSipCodes`requireddata.failoverSipCodes	integer[]	SIP results that move the call to the next supplier
`maxAttempts`requireddata.maxAttempts	integer	1 to 6
`selectionMode`requireddata.selectionMode	string	How the first supplier is picked; failover is always sequentialOne of `priority`, `least_cost`, `weighted`
`failoverTimeoutSeconds`requireddata.failoverTimeoutSeconds	integer \| null	null = the platform budget
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Response 202

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

Errors

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

HTTP

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

Run it here with a test key.

Get a route group with its suppliers

GET/api/v1/switch/route-plans/{id}

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`operatorId`requireddata.operatorId	string (uuid)	-
`name`requireddata.name	string	-
`description`requireddata.description	string \| null	-
`enabled`requireddata.enabled	boolean	-
`failoverSipCodes`requireddata.failoverSipCodes	integer[]	SIP results that move the call to the next supplier
`maxAttempts`requireddata.maxAttempts	integer	1 to 6
`selectionMode`requireddata.selectionMode	string	How the first supplier is picked; failover is always sequentialOne of `priority`, `least_cost`, `weighted`
`failoverTimeoutSeconds`requireddata.failoverTimeoutSeconds	integer \| null	null = the platform budget
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`entries`requireddata.entries	object[]	-
`id`requireddata.entries[].id	string (uuid)	-
`prefix`requireddata.entries[].prefix	string	"" = any destination
`routeId`requireddata.entries[].routeId	string (uuid) \| null	A marketplace route you bought
`vendorTrunkId`requireddata.entries[].vendorTrunkId	string (uuid) \| null	One of your supplier trunks
`priority`requireddata.entries[].priority	integer	-
`weightPct`requireddata.entries[].weightPct	integer \| null	-
`minAsr`requireddata.entries[].minAsr	string \| null	ASR gate in percent, as a decimal string; null = off
`maxPdd`requireddata.entries[].maxPdd	integer \| null	PDD gate in ms; null = off
`enabled`requireddata.entries[].enabled	boolean	-
`destinationName`requireddata.entries[].destinationName	string \| null	-
`country`requireddata.entries[].country	string \| null	-
`external`requireddata.entries[].external	boolean	True for a supplier trunk, false for a marketplace route
`supplierLabel`requireddata.entries[].supplierLabel	string	-
`supplierMeta`requireddata.entries[].supplierMeta	string	-
`trunkLabel`requireddata.entries[].trunkLabel	string \| null	-
`trunkHost`requireddata.entries[].trunkHost	string \| null	Withheld (null) for marketplace-promoted trunks
`trunkStatus`requireddata.entries[].trunkStatus	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.

Update a route group's settings

PATCH/api/v1/switch/route-plans/{id}

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

Send failoverTimeoutSeconds: null to go back to the platform budget; omit it to leave it unchanged.

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`name`	string	-max 120 chars
`description`	string \| null	-max 2000 chars
`enabled`	boolean	-
`selectionMode`	string	-One of `priority`, `least_cost`, `weighted`
`failoverSipCodes`	integer[]	-
`maxAttempts`	integer	-1 to 6
`failoverTimeoutSeconds`	integer \| null	-5 to 600

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchRouteGroup, 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/route-plans/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "description": "Example"
}'

Run it here with a test key.

Delete a route group

DELETE/api/v1/switch/route-plans/{id}

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

Customers assigned to it are detached and fall back to their routing strategy.

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

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

Response 202

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

Errors

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

Clone a route group with all its suppliers

POST/api/v1/switch/route-plans/{id}/clone

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

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`entriesCloned`requireddata.entriesCloned	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.

Replace the suppliers in a route group

PUT/api/v1/switch/route-plans/{id}/entries

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

Up to 200 entries, each naming exactly one supplier: a marketplace route you bought or one of your active supplier trunks. Duplicate supplier for the same prefix is refused.

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`entries`required	object[]	-
`prefix`entries[].prefix	string	-max 24 chars
`routeId`entries[].routeId	string (uuid) \| null	-
`vendorTrunkId`entries[].vendorTrunkId	string (uuid) \| null	-
`priority`entries[].priority	integer	-1 to 99
`weightPct`entries[].weightPct	integer \| null	-0 to 100
`minAsr`entries[].minAsr	number \| null	-0 to 100
`maxPdd`entries[].maxPdd	integer \| null	-min 0
`enabled`entries[].enabled	boolean	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`operatorId`requireddata.operatorId	string (uuid)	-
`name`requireddata.name	string	-
`description`requireddata.description	string \| null	-
`enabled`requireddata.enabled	boolean	-
`failoverSipCodes`requireddata.failoverSipCodes	integer[]	SIP results that move the call to the next supplier
`maxAttempts`requireddata.maxAttempts	integer	1 to 6
`selectionMode`requireddata.selectionMode	string	How the first supplier is picked; failover is always sequentialOne of `priority`, `least_cost`, `weighted`
`failoverTimeoutSeconds`requireddata.failoverTimeoutSeconds	integer \| null	null = the platform budget
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`entries`requireddata.entries	object[]	-
`id`requireddata.entries[].id	string (uuid)	-
`prefix`requireddata.entries[].prefix	string	"" = any destination
`routeId`requireddata.entries[].routeId	string (uuid) \| null	A marketplace route you bought
`vendorTrunkId`requireddata.entries[].vendorTrunkId	string (uuid) \| null	One of your supplier trunks
`priority`requireddata.entries[].priority	integer	-
`weightPct`requireddata.entries[].weightPct	integer \| null	-
`minAsr`requireddata.entries[].minAsr	string \| null	ASR gate in percent, as a decimal string; null = off
`maxPdd`requireddata.entries[].maxPdd	integer \| null	PDD gate in ms; null = off
`enabled`requireddata.entries[].enabled	boolean	-
`destinationName`requireddata.entries[].destinationName	string \| null	-
`country`requireddata.entries[].country	string \| null	-
`external`requireddata.entries[].external	boolean	True for a supplier trunk, false for a marketplace route
`supplierLabel`requireddata.entries[].supplierLabel	string	-
`supplierMeta`requireddata.entries[].supplierMeta	string	-
`trunkLabel`requireddata.entries[].trunkLabel	string \| null	-
`trunkHost`requireddata.entries[].trunkHost	string \| null	Withheld (null) for marketplace-promoted trunks
`trunkStatus`requireddata.entries[].trunkStatus	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 PUT "https://packetexchange.io/api/v1/switch/route-plans/<id>/entries" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entries": [
    {
      "prefix": "44",
      "routeId": "<routeId>"
    }
  ]
}'

Run it here with a test key.

List dialplans

GET/api/v1/switch/dialplans

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

Dialplans are ordered rules above route groups: match a number, rewrite it and the caller ID, then route or block.

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`operatorId`requireddata[].operatorId	string (uuid)	-
`name`requireddata[].name	string	-
`description`requireddata[].description	string \| null	-
`enabled`requireddata[].enabled	boolean	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`ruleCount`requireddata[].ruleCount	integer	-

Errors

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

Create a dialplan

POST/api/v1/switch/dialplans

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.

Request body (application/json)

Field	Type	Description
`name`required	string	-max 120 chars
`description`	string \| null	-max 2000 chars

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`operatorId`requireddata.operatorId	string (uuid)	-
`name`requireddata.name	string	-
`description`requireddata.description	string \| null	-
`enabled`requireddata.enabled	boolean	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Response 202

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

Errors

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

HTTP

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

Run it here with a test key.

Get a dialplan with its rules

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

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`operatorId`requireddata.operatorId	string (uuid)	-
`name`requireddata.name	string	-
`description`requireddata.description	string \| null	-
`enabled`requireddata.enabled	boolean	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`rules`requireddata.rules	object[]	-
`id`requireddata.rules[].id	string (uuid)	-
`dialplanId`requireddata.rules[].dialplanId	string (uuid)	-
`position`requireddata.rules[].position	integer	-
`label`requireddata.rules[].label	string \| null	-
`enabled`requireddata.rules[].enabled	boolean	-
`matchPrefix`requireddata.rules[].matchPrefix	string	"" = any dialled number
`matchRegex`requireddata.rules[].matchRegex	string \| null	-
`minLen`requireddata.rules[].minLen	integer \| null	-
`maxLen`requireddata.rules[].maxLen	integer \| null	-
`matchCli`requireddata.rules[].matchCli	string \| null	-
`jurisdiction`requireddata.rules[].jurisdiction	string	-One of `any`, `intrastate`, `interstate`, `local`, `international`, `domestic`
`timeStart`requireddata.rules[].timeStart	string \| null	HH:MM in your timezone
`timeEnd`requireddata.rules[].timeEnd	string \| null	-
`daysOfWeek`requireddata.rules[].daysOfWeek	integer[] \| null	0 = Sunday; null = every day
`stripDigits`requireddata.rules[].stripDigits	integer	-
`prependDigits`requireddata.rules[].prependDigits	string	-
`cliMode`requireddata.rules[].cliMode	string	-One of `passthrough`, `set`, `strip`, `prepend`, `anonymous`, `did`
`cliValue`requireddata.rules[].cliValue	string \| null	-
`action`requireddata.rules[].action	string	-One of `route_group`, `block`
`routeGroupId`requireddata.rules[].routeGroupId	string (uuid) \| null	-
`blockCause`requireddata.rules[].blockCause	integer	SIP code sent when action = block

Errors

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

Rename, describe, enable or disable a dialplan

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`name`	string	-max 120 chars
`description`	string \| null	-max 2000 chars
`enabled`	boolean	-

Response 200

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

Run it here with a test key.

Delete a dialplan

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

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

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

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

Response 202

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

Errors

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

Clone a dialplan with all its rules

POST/api/v1/switch/dialplans/{id}/clone

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

Cloned rules keep their route-group targets.

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`name`requireddata.name	string	-
`rulesCloned`requireddata.rulesCloned	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.

Replace the rules in a dialplan

PUT/api/v1/switch/dialplans/{id}/rules

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

Up to 200 rules, evaluated in position order. A route_group action must name one of your route groups; regular expressions that risk catastrophic backtracking are refused.

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`rules`required	object[]	-
`position`rules[].position	integer	-
`label`rules[].label	string \| null	-max 120 chars
`enabled`rules[].enabled	boolean	-
`matchPrefix`rules[].matchPrefix	string	-max 24 chars
`matchRegex`rules[].matchRegex	string \| null	-max 400 chars
`minLen`rules[].minLen	integer \| null	-0 to 24
`maxLen`rules[].maxLen	integer \| null	-0 to 24
`matchCli`rules[].matchCli	string \| null	-max 48 chars
`jurisdiction`rules[].jurisdiction	string	-One of `any`, `intrastate`, `interstate`, `local`, `international`, `domestic`
`timeStart`rules[].timeStart	string \| null	-
`timeEnd`rules[].timeEnd	string \| null	-
`daysOfWeek`rules[].daysOfWeek	integer[] \| null	-
`stripDigits`rules[].stripDigits	integer	-0 to 20
`prependDigits`rules[].prependDigits	string	-max 24 chars
`cliMode`rules[].cliMode	string	-One of `passthrough`, `set`, `strip`, `prepend`, `anonymous`, `did`
`cliValue`rules[].cliValue	string \| null	-max 32 chars
`action`rules[].action	string	-One of `route_group`, `block`
`routeGroupId`rules[].routeGroupId	string (uuid) \| null	-
`blockCause`rules[].blockCause	integer	-400 to 699

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`operatorId`requireddata.operatorId	string (uuid)	-
`name`requireddata.name	string	-
`description`requireddata.description	string \| null	-
`enabled`requireddata.enabled	boolean	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`rules`requireddata.rules	object[]	-
`id`requireddata.rules[].id	string (uuid)	-
`dialplanId`requireddata.rules[].dialplanId	string (uuid)	-
`position`requireddata.rules[].position	integer	-
`label`requireddata.rules[].label	string \| null	-
`enabled`requireddata.rules[].enabled	boolean	-
`matchPrefix`requireddata.rules[].matchPrefix	string	"" = any dialled number
`matchRegex`requireddata.rules[].matchRegex	string \| null	-
`minLen`requireddata.rules[].minLen	integer \| null	-
`maxLen`requireddata.rules[].maxLen	integer \| null	-
`matchCli`requireddata.rules[].matchCli	string \| null	-
`jurisdiction`requireddata.rules[].jurisdiction	string	-One of `any`, `intrastate`, `interstate`, `local`, `international`, `domestic`
`timeStart`requireddata.rules[].timeStart	string \| null	HH:MM in your timezone
`timeEnd`requireddata.rules[].timeEnd	string \| null	-
`daysOfWeek`requireddata.rules[].daysOfWeek	integer[] \| null	0 = Sunday; null = every day
`stripDigits`requireddata.rules[].stripDigits	integer	-
`prependDigits`requireddata.rules[].prependDigits	string	-
`cliMode`requireddata.rules[].cliMode	string	-One of `passthrough`, `set`, `strip`, `prepend`, `anonymous`, `did`
`cliValue`requireddata.rules[].cliValue	string \| null	-
`action`requireddata.rules[].action	string	-One of `route_group`, `block`
`routeGroupId`requireddata.rules[].routeGroupId	string (uuid) \| null	-
`blockCause`requireddata.rules[].blockCause	integer	SIP code sent when action = block

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/dialplans/<id>/rules" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": [
    {
      "position": 1,
      "label": "Acme"
    }
  ]
}'

Run it here with a test key.

Preview how a number would route

GET/api/v1/switch/routing/preview

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

Read-only: the dialplan rule matched, number and caller-ID rewrites, the route group, the ordered supplier chain, any customer or trunk restriction that would refuse the call, and candidates that were skipped. Failover is always sequential. For the full reasoning use POST /routing/trace.

Parameters

Name	In	Type	Description
`to`required	query	string	Dialled number
`cli`	query	string	-
`type`	query	string	-One of voice, sms
`subAccountId`	query	string (uuid)	The customer
`customerTrunkId`	query	string (uuid)	Name the trunk for an exact restriction check

Response 200

Field	Type	Description
`data`required	object	-
`dialplanId`requireddata.dialplanId	string (uuid) \| null	-
`dialplanName`requireddata.dialplanName	string \| null	-
`matched`requireddata.matched	boolean	-
`ruleId`requireddata.ruleId	string (uuid) \| null	-
`ruleLabel`requireddata.ruleLabel	string \| null	-
`blocked`requireddata.blocked	boolean	-
`blockCause`requireddata.blockCause	integer \| null	-
`translatedNumber`requireddata.translatedNumber	string	-
`outCli`requireddata.outCli	string \| null	-
`routeGroupId`requireddata.routeGroupId	string (uuid) \| null	-
`routeGroupName`requireddata.routeGroupName	string \| null	-
`kind`requireddata.kind	string	fixed route or route group
`selectionMode`requireddata.selectionMode	string \| null	-
`failoverMode`requireddata.failoverMode	string	-One of `sequential`
`failoverSipCodes`requireddata.failoverSipCodes	integer[]	-
`maxAttempts`requireddata.maxAttempts	integer	-
`setupBudgetSeconds`requireddata.setupBudgetSeconds	number \| null	-
`refusal`requireddata.refusal	object \| null	Why the chain is empty on purpose
`restriction`requireddata.restriction	object \| null	A customer or trunk restriction that would refuse this call
`skipped`requireddata.skipped	object[]	-
`supplier`requireddata.skipped[].supplier	string	-
`reason`requireddata.skipped[].reason	string	-
`detail`requireddata.skipped[].detail	string \| null	-
`vendorTrunkId`requireddata.skipped[].vendorTrunkId	string (uuid) \| null	-
`candidates`requireddata.candidates	object[]	-
`attempt`requireddata.candidates[].attempt	integer	-
`routeId`requireddata.candidates[].routeId	string	-
`destination`requireddata.candidates[].destination	string \| null	-
`country`requireddata.candidates[].country	string \| null	-
`pricePerUnit`requireddata.candidates[].pricePerUnit	string	Cost per minute of this supplier, 6-decimal string
`matchedPrefix`requireddata.candidates[].matchedPrefix	string \| null	-
`priority`requireddata.candidates[].priority	integer \| null	-
`external`requireddata.candidates[].external	boolean	-
`supplier`requireddata.candidates[].supplier	string	-One of `external trunk`, `marketplace`
`endpoint`requireddata.candidates[].endpoint	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.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Run a route trace for a number

POST/api/v1/switch/routing/trace

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

Explains the routing decision end to end: normalisation, the policy matched, the sell price, every eligible supplier with its buy rate, capacity and margin, and why each excluded supplier was excluded. Uses the same resolvers as live calls but is NOT a call: no call record, balance movement or capacity use. The result is kept for an hour so it can be saved.

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
`to`required	string	-max 32 chars
`cli`	string \| null	-max 32 chars
`type`	string	-One of `voice`, `sms`
`subAccountId`	string (uuid) \| null	The customer
`customerTrunkId`	string (uuid) \| null	-

Response 200

Field	Type	Description
`data`required	object	-
`traceId`requireddata.traceId	string (uuid)	-
`at`requireddata.at	string (date-time)	ISO-8601 timestamp (UTC)
`saved`requireddata.saved	boolean	-
`savedNote`requireddata.savedNote	string \| null	-
`input`requireddata.input	object	-
`to`requireddata.input.to	string	-
`cli`requireddata.input.cli	string \| null	-
`type`requireddata.input.type	string	-One of `voice`, `sms`
`subAccountId`requireddata.input.subAccountId	string (uuid) \| null	-
`subAccountLabel`requireddata.input.subAccountLabel	string \| null	-
`customerTrunkId`requireddata.input.customerTrunkId	string (uuid) \| null	-
`customerTrunkLabel`requireddata.input.customerTrunkLabel	string \| null	-
`verdict`requireddata.verdict	object	-
`routes`requireddata.verdict.routes	boolean	Would the call be carried?
`sipCode`requireddata.verdict.sipCode	integer \| null	What the customer's switch would receive
`reason`requireddata.verdict.reason	string \| null	-
`summary`requireddata.verdict.summary	string	-
`steps`requireddata.steps	object[]	Each decision stage with its result
`number`requireddata.number	object	-
`dialled`requireddata.number.dialled	string	-
`digits`requireddata.number.digits	string	-
`afterTechPrefix`requireddata.number.afterTechPrefix	string	-
`translated`requireddata.number.translated	string	-
`country`requireddata.number.country	string \| null	-
`outCli`requireddata.outCli	string \| null	-
`sell`requireddata.sell	object \| null	A price, or the reason there is none. Only kind = rated carries a rate.
`kind`requireddata.sell.kind	string	-One of `rated`, `no_matching_rate`, `not_yet_effective`, `expired`, `forbidden`, `rating_failed`, `not_billable`
`rate`data.sell.rate	number	Present when kind = rated. May legitimately be 0.
`matchedPrefix`data.sell.matchedPrefix	string	-
`deckVersion`data.sell.deckVersion	integer \| null	-
`source`data.sell.source	string	-
`destination`data.sell.destination	string	-
`effectiveFrom`data.sell.effectiveFrom	string	-
`expiredAt`data.sell.expiredAt	string	-
`reason`data.sell.reason	string	Why it is forbidden or failed
`sellBillingRate`requireddata.sellBillingRate	number \| null	USD as a JSON number (engine output, up to 6 decimal places)
`candidates`requireddata.candidates	object[]	Suppliers in the chain, in attempt order, with buy rate, capacity and margin
`excluded`requireddata.excluded	object[]	Suppliers considered and not used, each with the reason
`selected`requireddata.selected	object \| null	-
`duration`requireddata.duration	object \| null	-
`seconds`requireddata.duration.seconds	integer	-
`boundBy`requireddata.duration.boundBy	string	-One of `balance`, `platform`, `trunk`
`sideEffects`requireddata.sideEffects	object	-
`createdCdr`requireddata.sideEffects.createdCdr	boolean	-One of `false`
`movedBalance`requireddata.sideEffects.movedBalance	boolean	-One of `false`
`consumedCapacity`requireddata.sideEffects.consumedCapacity	boolean	-One of `false`

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/routing/trace" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+447700900123"
}'

Run it here with a test key.

List saved route traces

GET/api/v1/switch/routing/traces

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

Parameters

Name	In	Type	Description
`limit`	query	integer	Default 25
`offset`	query	integer	-

Response 200

Field	Type	Description
`data`required	object	-
`items`requireddata.items	object[]	-
`id`requireddata.items[].id	string (uuid)	-
`traceId`requireddata.items[].traceId	string (uuid)	-
`note`requireddata.items[].note	string \| null	-
`destination`requireddata.items[].destination	string	-
`cli`requireddata.items[].cli	string \| null	-
`callType`requireddata.items[].callType	string	-
`subAccountId`requireddata.items[].subAccountId	string (uuid) \| null	-
`customerTrunkId`requireddata.items[].customerTrunkId	string (uuid) \| null	-
`routes`requireddata.items[].routes	boolean	-
`sipCode`requireddata.items[].sipCode	integer \| null	-
`reason`requireddata.items[].reason	string \| null	-
`summary`requireddata.items[].summary	string	-
`selectedLabel`requireddata.items[].selectedLabel	string \| null	-
`buyRate`requireddata.items[].buyRate	string \| null	Decimal string
`sellRate`requireddata.items[].sellRate	string \| null	Decimal string
`savedBy`requireddata.items[].savedBy	string \| null	-
`ranAt`requireddata.items[].ranAt	string (date-time)	ISO-8601 timestamp (UTC)
`createdAt`requireddata.items[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`total`requireddata.total	integer	-
`limit`requireddata.limit	integer	-
`offset`requireddata.offset	integer	-

Errors

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

Save a route trace

POST/api/v1/switch/routing/traces

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

Keeps a trace run within the last hour, by its traceId, with an optional note. The stored copy is the server's own result. Saving the same trace twice returns alreadySaved: true.

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

Request body (application/json)

Field	Type	Description
`traceId`required	string (uuid)	-
`note`	string \| null	-max 2000 chars

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`traceId`requireddata.traceId	string (uuid)	-
`alreadySaved`requireddata.alreadySaved	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.
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/routing/traces" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "traceId": "<traceId>"
}'

Run it here with a test key.

Get a saved route trace

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

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

The snapshot as it was saved. It is never re-run; running again produces a new trace.

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

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

Errors

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

Delete a saved route trace

DELETE/api/v1/switch/routing/traces/{id}

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

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

Parameters

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-

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.

List inbound IP ACLs for a customer or trunk

GET/api/v1/switch/acls

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

Parameters

Name	In	Type	Description
`entityType`	query	string	-One of customer, trunk
`entityId`required	query	string (uuid)	The customer or trunk id

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`entityType`requireddata[].entityType	string	-One of `customer`, `trunk`
`entityId`requireddata[].entityId	string (uuid)	-
`cidr`requireddata[].cidr	string	-
`description`requireddata[].description	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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

Add an inbound IP ACL entry

POST/api/v1/switch/acls

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

Authorises an address or CIDR for a customer (IP authentication) or a trunk (identity).

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
`entityType`required	string	-One of `customer`, `trunk`
`entityId`required	string (uuid)	-
`cidr`required	string	-max 64 chars
`description`	string \| null	-max 160 chars

Response 201

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

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/acls" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entityType": "customer",
  "entityId": "<entityId>",
  "cidr": "<cidr>"
}'

Run it here with a test key.

Remove an inbound IP ACL entry

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

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

Removing a customer address stops calls from that address 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	-

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.