Switch API reference

Switch: team and audit

Roles, team members, approvals and the audit history.

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

BrowseSwitch: team and audit

Get your role and permissions on the switch

GET/api/v1/switch/me

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

Response 200

FieldDescription

datarequired
object
operatorIdrequired
string (uuid) · data.operatorId
isAccountHolderrequired
boolean · data.isAccountHolder
rolerequired
string | null · data.role
roleLabelrequired
string | null · data.roleLabel
permissionsrequired
string[] · data.permissions
sensitivePermissionsrequired
string[] · data.sensitivePermissions
scoperequired
object · data.scope
customerIdsrequired
string (uuid)[] | null · data.scope.customerIds
null = all customers
trunkIdsrequired
string (uuid)[] | null · data.scope.trunkIds
null = all trunks

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.

List team members and the available roles

GET/api/v1/switch/team

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

Response 200

FieldDescription

datarequired
object
membersrequired
object[] · data.members
idrequired
string (uuid) · data.members[].id
userIdrequired
string (uuid) · data.members[].userId
emailrequired
string · data.members[].email
contactNamerequired
string | null · data.members[].contactName
rolerequired
string · data.members[].role
roleLabelrequired
string · data.members[].roleLabel
statusrequired
string · data.members[].status
customerIdsrequired
string (uuid)[] | null · data.members[].customerIds
trunkIdsrequired
string (uuid)[] | null · data.members[].trunkIds
noterequired
string | null · data.members[].note
permissionsrequired
string[] · data.members[].permissions
scopeSummaryrequired
object · data.members[].scopeSummary
customersrequired
string · data.members[].scopeSummary.customers
trunksrequired
string · data.members[].scopeSummary.trunks
createdAtrequired
string (date-time) · data.members[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.members[].updatedAt
ISO-8601 timestamp (UTC)
rolesrequired
object[] · data.roles

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 a team member

POST/api/v1/switch/team

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

Gives an email address a role on your switch, optionally limited to some customers and trunks (null = all).

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

emailrequired
string (email)
max 255 chars
rolerequired
string
One of viewer, noc, routing, billing, account_manager, administrator
customerIds
string (uuid)[] | null
trunkIds
string (uuid)[] | null
note
string | null
max 500 chars

Response 201

FieldDescription

datarequired
object
Same fields as SwitchTeamMember, 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/team" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "role": "viewer"
}'

Run it here with a test key.

Change a team member's role, scope or status

PATCH/api/v1/switch/team/{memberId}

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

memberIdrequired
path · string

Request body (application/json)

FieldDescription

role
string
One of viewer, noc, routing, billing, account_manager, administrator
status
string
One of active, suspended
customerIds
string (uuid)[] | null
trunkIds
string (uuid)[] | null
note
string | null
max 500 chars

Response 200

FieldDescription

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

HTTP

curl -X PATCH "https://packetexchange.io/api/v1/switch/team/<memberId>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "viewer",
  "status": "active"
}'

Run it here with a test key.

Suspend a team member

DELETE/api/v1/switch/team/{memberId}

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

Suspends rather than deletes, so their history stays attributed.

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

memberIdrequired
path · string

Response 200

FieldDescription

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

Search the switch audit history

GET/api/v1/switch/audit

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

Who changed what, when, and under which permission. Cursor-paginated with nextCursor.

Parameters

customerId
query · string (uuid)
trunkId
query · string (uuid)
actorUserId
query · string (uuid)
action
query · string
permission
query · string
sensitiveOnly
query · boolean
outcome
query · string
One of success, failure, denied
from
query · string (date-time)
to
query · string (date-time)
search
query · string
limit
query · integer
cursor
query · string (uuid)

Response 200

FieldDescription

datarequired
object
entriesrequired
object[] · data.entries
nextCursorrequired
string | null · data.nextCursor

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.

Get the values available to filter the audit history by

GET/api/v1/switch/audit/filter-options

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

Response 200

FieldDescription

datarequired
object
actorsrequired
object[] · data.actors
permissionsrequired
string[] · data.permissions
sensitivePermissionsrequired
string[] · data.sensitivePermissions

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.

List approval requests

GET/api/v1/switch/approvals

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

Actions waiting for (or decided by) a second person. Defaults to pending and approved.

Parameters

status
query · string
Comma-separated statuses
limit
query · integer

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
statusrequired
string · data[].status
pending, approved, rejected, expired...
permission
string · data[].permission
requestedAtrequired
string (date-time) · data[].requestedAt
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.

Approve or reject an approval request

POST/api/v1/switch/approvals/{id}/decide

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

decisionrequired
string
One of approve, reject
note
string | null
max 2000 chars

Response 200

FieldDescription

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/approvals/<id>/decide" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "approve"
}'

Run it here with a test key.

List approval policies

GET/api/v1/switch/approval-policies

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

Response 200

FieldDescription

datarequired
object
policiesrequired
object[] · data.policies
eligiblerequired
string[] · data.eligible
Permissions that can be put behind an approval
pendingrequired
integer · data.pending

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.

Set the approval policy for a permission

PUT/api/v1/switch/approval-policies

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

Require a second person to approve actions under this permission, optionally only above an amount.

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

permissionrequired
string
One of customers.view, trunks.view, routing.view, rates.view, billing.view, noc.view, audit.view, team.view, customers.edit, trunks.edit, rates.edit, billing.edit and 12 more
enabledrequired
boolean
minAmountUsd
number | null
min 0
requireDifferentPerson
boolean
expiresAfterHours
integer
1 to 2160
requireReason
boolean

Response 200

FieldDescription

datarequired
object

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 PUT "https://packetexchange.io/api/v1/switch/approval-policies" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "permission": "customers.view",
  "enabled": true
}'

Run it here with a test key.