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

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
operatorIdrequired
string (uuid) · data[].operatorId
namerequired
string · data[].name
descriptionrequired
string | null · data[].description
enabledrequired
boolean · data[].enabled
failoverSipCodesrequired
integer[] · data[].failoverSipCodes
SIP results that move the call to the next supplier
maxAttemptsrequired
integer · data[].maxAttempts
1 to 6
selectionModerequired
string · data[].selectionMode
How the first supplier is picked; failover is always sequentialOne of priority, least_cost, weighted
failoverTimeoutSecondsrequired
integer | null · data[].failoverTimeoutSeconds
null = the platform budget
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data[].updatedAt
ISO-8601 timestamp (UTC)
entryCountrequired
integer · data[].entryCount

Errors

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

FieldDescription

namerequired
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

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
operatorIdrequired
string (uuid) · data.operatorId
namerequired
string · data.name
descriptionrequired
string | null · data.description
enabledrequired
boolean · data.enabled
failoverSipCodesrequired
integer[] · data.failoverSipCodes
SIP results that move the call to the next supplier
maxAttemptsrequired
integer · data.maxAttempts
1 to 6
selectionModerequired
string · data.selectionMode
How the first supplier is picked; failover is always sequentialOne of priority, least_cost, weighted
failoverTimeoutSecondsrequired
integer | null · data.failoverTimeoutSeconds
null = the platform budget
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)

Response 202

FieldDescription

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

Errors

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

HTTP

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
operatorIdrequired
string (uuid) · data.operatorId
namerequired
string · data.name
descriptionrequired
string | null · data.description
enabledrequired
boolean · data.enabled
failoverSipCodesrequired
integer[] · data.failoverSipCodes
SIP results that move the call to the next supplier
maxAttemptsrequired
integer · data.maxAttempts
1 to 6
selectionModerequired
string · data.selectionMode
How the first supplier is picked; failover is always sequentialOne of priority, least_cost, weighted
failoverTimeoutSecondsrequired
integer | null · data.failoverTimeoutSeconds
null = the platform budget
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
entriesrequired
object[] · data.entries
idrequired
string (uuid) · data.entries[].id
prefixrequired
string · data.entries[].prefix
"" = any destination
routeIdrequired
string (uuid) | null · data.entries[].routeId
A marketplace route you bought
vendorTrunkIdrequired
string (uuid) | null · data.entries[].vendorTrunkId
One of your supplier trunks
priorityrequired
integer · data.entries[].priority
weightPctrequired
integer | null · data.entries[].weightPct
minAsrrequired
string | null · data.entries[].minAsr
ASR gate in percent, as a decimal string; null = off
maxPddrequired
integer | null · data.entries[].maxPdd
PDD gate in ms; null = off
enabledrequired
boolean · data.entries[].enabled
destinationNamerequired
string | null · data.entries[].destinationName
countryrequired
string | null · data.entries[].country
externalrequired
boolean · data.entries[].external
True for a supplier trunk, false for a marketplace route
supplierLabelrequired
string · data.entries[].supplierLabel
supplierMetarequired
string · data.entries[].supplierMeta
trunkLabelrequired
string | null · data.entries[].trunkLabel
trunkHostrequired
string | null · data.entries[].trunkHost
Withheld (null) for marketplace-promoted trunks
trunkStatusrequired
string | null · data.entries[].trunkStatus

Errors

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

idrequired
path · string

Request body (application/json)

FieldDescription

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

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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

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

idrequired
path · string

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
entriesClonedrequired
integer · data.entriesCloned

Response 202

FieldDescription

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

Errors

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

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

idrequired
path · string

Request body (application/json)

FieldDescription

entriesrequired
object[]
prefix
string · entries[].prefix
max 24 chars
routeId
string (uuid) | null · entries[].routeId
vendorTrunkId
string (uuid) | null · entries[].vendorTrunkId
priority
integer · entries[].priority
1 to 99
weightPct
integer | null · entries[].weightPct
0 to 100
minAsr
number | null · entries[].minAsr
0 to 100
maxPdd
integer | null · entries[].maxPdd
min 0
enabled
boolean · entries[].enabled

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
operatorIdrequired
string (uuid) · data.operatorId
namerequired
string · data.name
descriptionrequired
string | null · data.description
enabledrequired
boolean · data.enabled
failoverSipCodesrequired
integer[] · data.failoverSipCodes
SIP results that move the call to the next supplier
maxAttemptsrequired
integer · data.maxAttempts
1 to 6
selectionModerequired
string · data.selectionMode
How the first supplier is picked; failover is always sequentialOne of priority, least_cost, weighted
failoverTimeoutSecondsrequired
integer | null · data.failoverTimeoutSeconds
null = the platform budget
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
entriesrequired
object[] · data.entries
idrequired
string (uuid) · data.entries[].id
prefixrequired
string · data.entries[].prefix
"" = any destination
routeIdrequired
string (uuid) | null · data.entries[].routeId
A marketplace route you bought
vendorTrunkIdrequired
string (uuid) | null · data.entries[].vendorTrunkId
One of your supplier trunks
priorityrequired
integer · data.entries[].priority
weightPctrequired
integer | null · data.entries[].weightPct
minAsrrequired
string | null · data.entries[].minAsr
ASR gate in percent, as a decimal string; null = off
maxPddrequired
integer | null · data.entries[].maxPdd
PDD gate in ms; null = off
enabledrequired
boolean · data.entries[].enabled
destinationNamerequired
string | null · data.entries[].destinationName
countryrequired
string | null · data.entries[].country
externalrequired
boolean · data.entries[].external
True for a supplier trunk, false for a marketplace route
supplierLabelrequired
string · data.entries[].supplierLabel
supplierMetarequired
string · data.entries[].supplierMeta
trunkLabelrequired
string | null · data.entries[].trunkLabel
trunkHostrequired
string | null · data.entries[].trunkHost
Withheld (null) for marketplace-promoted trunks
trunkStatusrequired
string | null · data.entries[].trunkStatus

Response 202

FieldDescription

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

Errors

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

HTTP

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

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
operatorIdrequired
string (uuid) · data[].operatorId
namerequired
string · data[].name
descriptionrequired
string | null · data[].description
enabledrequired
boolean · data[].enabled
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data[].updatedAt
ISO-8601 timestamp (UTC)
ruleCountrequired
integer · data[].ruleCount

Errors

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

FieldDescription

namerequired
string
max 120 chars
description
string | null
max 2000 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
operatorIdrequired
string (uuid) · data.operatorId
namerequired
string · data.name
descriptionrequired
string | null · data.description
enabledrequired
boolean · data.enabled
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)

Response 202

FieldDescription

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

Errors

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

HTTP

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
operatorIdrequired
string (uuid) · data.operatorId
namerequired
string · data.name
descriptionrequired
string | null · data.description
enabledrequired
boolean · data.enabled
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
rulesrequired
object[] · data.rules
idrequired
string (uuid) · data.rules[].id
dialplanIdrequired
string (uuid) · data.rules[].dialplanId
positionrequired
integer · data.rules[].position
labelrequired
string | null · data.rules[].label
enabledrequired
boolean · data.rules[].enabled
matchPrefixrequired
string · data.rules[].matchPrefix
"" = any dialled number
matchRegexrequired
string | null · data.rules[].matchRegex
minLenrequired
integer | null · data.rules[].minLen
maxLenrequired
integer | null · data.rules[].maxLen
matchClirequired
string | null · data.rules[].matchCli
jurisdictionrequired
string · data.rules[].jurisdiction
One of any, intrastate, interstate, local, international, domestic
timeStartrequired
string | null · data.rules[].timeStart
HH:MM in your timezone
timeEndrequired
string | null · data.rules[].timeEnd
daysOfWeekrequired
integer[] | null · data.rules[].daysOfWeek
0 = Sunday; null = every day
stripDigitsrequired
integer · data.rules[].stripDigits
prependDigitsrequired
string · data.rules[].prependDigits
cliModerequired
string · data.rules[].cliMode
One of passthrough, set, strip, prepend, anonymous, did
cliValuerequired
string | null · data.rules[].cliValue
actionrequired
string · data.rules[].action
One of route_group, block
routeGroupIdrequired
string (uuid) | null · data.rules[].routeGroupId
blockCauserequired
integer · data.rules[].blockCause
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

idrequired
path · string

Request body (application/json)

FieldDescription

name
string
max 120 chars
description
string | null
max 2000 chars
enabled
boolean

Response 200

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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

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

idrequired
path · string

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
namerequired
string · data.name
rulesClonedrequired
integer · data.rulesCloned

Response 202

FieldDescription

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

Errors

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

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

idrequired
path · string

Request body (application/json)

FieldDescription

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

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
operatorIdrequired
string (uuid) · data.operatorId
namerequired
string · data.name
descriptionrequired
string | null · data.description
enabledrequired
boolean · data.enabled
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
rulesrequired
object[] · data.rules
idrequired
string (uuid) · data.rules[].id
dialplanIdrequired
string (uuid) · data.rules[].dialplanId
positionrequired
integer · data.rules[].position
labelrequired
string | null · data.rules[].label
enabledrequired
boolean · data.rules[].enabled
matchPrefixrequired
string · data.rules[].matchPrefix
"" = any dialled number
matchRegexrequired
string | null · data.rules[].matchRegex
minLenrequired
integer | null · data.rules[].minLen
maxLenrequired
integer | null · data.rules[].maxLen
matchClirequired
string | null · data.rules[].matchCli
jurisdictionrequired
string · data.rules[].jurisdiction
One of any, intrastate, interstate, local, international, domestic
timeStartrequired
string | null · data.rules[].timeStart
HH:MM in your timezone
timeEndrequired
string | null · data.rules[].timeEnd
daysOfWeekrequired
integer[] | null · data.rules[].daysOfWeek
0 = Sunday; null = every day
stripDigitsrequired
integer · data.rules[].stripDigits
prependDigitsrequired
string · data.rules[].prependDigits
cliModerequired
string · data.rules[].cliMode
One of passthrough, set, strip, prepend, anonymous, did
cliValuerequired
string | null · data.rules[].cliValue
actionrequired
string · data.rules[].action
One of route_group, block
routeGroupIdrequired
string (uuid) | null · data.rules[].routeGroupId
blockCauserequired
integer · data.rules[].blockCause
SIP code sent when action = block

Response 202

FieldDescription

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

Errors

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

HTTP

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

torequired
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

FieldDescription

datarequired
object
dialplanIdrequired
string (uuid) | null · data.dialplanId
dialplanNamerequired
string | null · data.dialplanName
matchedrequired
boolean · data.matched
ruleIdrequired
string (uuid) | null · data.ruleId
ruleLabelrequired
string | null · data.ruleLabel
blockedrequired
boolean · data.blocked
blockCauserequired
integer | null · data.blockCause
translatedNumberrequired
string · data.translatedNumber
outClirequired
string | null · data.outCli
routeGroupIdrequired
string (uuid) | null · data.routeGroupId
routeGroupNamerequired
string | null · data.routeGroupName
kindrequired
string · data.kind
fixed route or route group
selectionModerequired
string | null · data.selectionMode
failoverModerequired
string · data.failoverMode
One of sequential
failoverSipCodesrequired
integer[] · data.failoverSipCodes
maxAttemptsrequired
integer · data.maxAttempts
setupBudgetSecondsrequired
number | null · data.setupBudgetSeconds
refusalrequired
object | null · data.refusal
Why the chain is empty on purpose
restrictionrequired
object | null · data.restriction
A customer or trunk restriction that would refuse this call
skippedrequired
object[] · data.skipped
supplierrequired
string · data.skipped[].supplier
reasonrequired
string · data.skipped[].reason
detailrequired
string | null · data.skipped[].detail
vendorTrunkIdrequired
string (uuid) | null · data.skipped[].vendorTrunkId
candidatesrequired
object[] · data.candidates
attemptrequired
integer · data.candidates[].attempt
routeIdrequired
string · data.candidates[].routeId
destinationrequired
string | null · data.candidates[].destination
countryrequired
string | null · data.candidates[].country
pricePerUnitrequired
string · data.candidates[].pricePerUnit
Cost per minute of this supplier, 6-decimal string
matchedPrefixrequired
string | null · data.candidates[].matchedPrefix
priorityrequired
integer | null · data.candidates[].priority
externalrequired
boolean · data.candidates[].external
supplierrequired
string · data.candidates[].supplier
One of external trunk, marketplace
endpointrequired
string | null · data.candidates[].endpoint

Errors

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

FieldDescription

torequired
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

FieldDescription

datarequired
object
traceIdrequired
string (uuid) · data.traceId
atrequired
string (date-time) · data.at
ISO-8601 timestamp (UTC)
savedrequired
boolean · data.saved
savedNoterequired
string | null · data.savedNote
inputrequired
object · data.input
torequired
string · data.input.to
clirequired
string | null · data.input.cli
typerequired
string · data.input.type
One of voice, sms
subAccountIdrequired
string (uuid) | null · data.input.subAccountId
subAccountLabelrequired
string | null · data.input.subAccountLabel
customerTrunkIdrequired
string (uuid) | null · data.input.customerTrunkId
customerTrunkLabelrequired
string | null · data.input.customerTrunkLabel
verdictrequired
object · data.verdict
routesrequired
boolean · data.verdict.routes
Would the call be carried?
sipCoderequired
integer | null · data.verdict.sipCode
What the customer's switch would receive
reasonrequired
string | null · data.verdict.reason
summaryrequired
string · data.verdict.summary
stepsrequired
object[] · data.steps
Each decision stage with its result
numberrequired
object · data.number
dialledrequired
string · data.number.dialled
digitsrequired
string · data.number.digits
afterTechPrefixrequired
string · data.number.afterTechPrefix
translatedrequired
string · data.number.translated
countryrequired
string | null · data.number.country
outClirequired
string | null · data.outCli
sellrequired
object | null · data.sell
A price, or the reason there is none. Only kind = rated carries a rate.
kindrequired
string · data.sell.kind
One of rated, no_matching_rate, not_yet_effective, expired, forbidden, rating_failed, not_billable
rate
number · data.sell.rate
Present when kind = rated. May legitimately be 0.
matchedPrefix
string · data.sell.matchedPrefix
deckVersion
integer | null · data.sell.deckVersion
source
string · data.sell.source
destination
string · data.sell.destination
effectiveFrom
string · data.sell.effectiveFrom
expiredAt
string · data.sell.expiredAt
reason
string · data.sell.reason
Why it is forbidden or failed
sellBillingRaterequired
number | null · data.sellBillingRate
USD as a JSON number (engine output, up to 6 decimal places)
candidatesrequired
object[] · data.candidates
Suppliers in the chain, in attempt order, with buy rate, capacity and margin
excludedrequired
object[] · data.excluded
Suppliers considered and not used, each with the reason
selectedrequired
object | null · data.selected
durationrequired
object | null · data.duration
secondsrequired
integer · data.duration.seconds
boundByrequired
string · data.duration.boundBy
One of balance, platform, trunk
sideEffectsrequired
object · data.sideEffects
createdCdrrequired
boolean · data.sideEffects.createdCdr
One of false
movedBalancerequired
boolean · data.sideEffects.movedBalance
One of false
consumedCapacityrequired
boolean · data.sideEffects.consumedCapacity
One of false

Response 202

FieldDescription

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

Errors

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

HTTP

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

limit
query · integer
Default 25
offset
query · integer

Response 200

FieldDescription

datarequired
object
itemsrequired
object[] · data.items
idrequired
string (uuid) · data.items[].id
traceIdrequired
string (uuid) · data.items[].traceId
noterequired
string | null · data.items[].note
destinationrequired
string · data.items[].destination
clirequired
string | null · data.items[].cli
callTyperequired
string · data.items[].callType
subAccountIdrequired
string (uuid) | null · data.items[].subAccountId
customerTrunkIdrequired
string (uuid) | null · data.items[].customerTrunkId
routesrequired
boolean · data.items[].routes
sipCoderequired
integer | null · data.items[].sipCode
reasonrequired
string | null · data.items[].reason
summaryrequired
string · data.items[].summary
selectedLabelrequired
string | null · data.items[].selectedLabel
buyRaterequired
string | null · data.items[].buyRate
Decimal string
sellRaterequired
string | null · data.items[].sellRate
Decimal string
savedByrequired
string | null · data.items[].savedBy
ranAtrequired
string (date-time) · data.items[].ranAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.items[].createdAt
ISO-8601 timestamp (UTC)
totalrequired
integer · data.total
limitrequired
integer · data.limit
offsetrequired
integer · data.offset

Errors

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

FieldDescription

traceIdrequired
string (uuid)
note
string | null
max 2000 chars

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
traceIdrequired
string (uuid) · data.traceId
alreadySavedrequired
boolean · data.alreadySaved

Response 202

FieldDescription

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

Errors

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

HTTP

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

idrequired
path · string

Response 200

FieldDescription

datarequired
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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id

Response 202

FieldDescription

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

Errors

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

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

entityType
query · string
One of customer, trunk
entityIdrequired
query · string (uuid)
The customer or trunk id

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
entityTyperequired
string · data[].entityType
One of customer, trunk
entityIdrequired
string (uuid) · data[].entityId
cidrrequired
string · data[].cidr
descriptionrequired
string | null · data[].description
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

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

FieldDescription

entityTyperequired
string
One of customer, trunk
entityIdrequired
string (uuid)
cidrrequired
string
max 64 chars
description
string | null
max 160 chars

Response 201

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

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

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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