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

Field	Type	Description
`data`required	object	-
`operatorId`requireddata.operatorId	string (uuid)	-
`isAccountHolder`requireddata.isAccountHolder	boolean	-
`role`requireddata.role	string \| null	-
`roleLabel`requireddata.roleLabel	string \| null	-
`permissions`requireddata.permissions	string[]	-
`sensitivePermissions`requireddata.sensitivePermissions	string[]	-
`scope`requireddata.scope	object	-
`customerIds`requireddata.scope.customerIds	string (uuid)[] \| null	null = all customers
`trunkIds`requireddata.scope.trunkIds	string (uuid)[] \| null	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

Field	Type	Description
`data`required	object	-
`members`requireddata.members	object[]	-
`id`requireddata.members[].id	string (uuid)	-
`userId`requireddata.members[].userId	string (uuid)	-
`email`requireddata.members[].email	string	-
`contactName`requireddata.members[].contactName	string \| null	-
`role`requireddata.members[].role	string	-
`roleLabel`requireddata.members[].roleLabel	string	-
`status`requireddata.members[].status	string	-
`customerIds`requireddata.members[].customerIds	string (uuid)[] \| null	-
`trunkIds`requireddata.members[].trunkIds	string (uuid)[] \| null	-
`note`requireddata.members[].note	string \| null	-
`permissions`requireddata.members[].permissions	string[]	-
`scopeSummary`requireddata.members[].scopeSummary	object	-
`customers`requireddata.members[].scopeSummary.customers	string	-
`trunks`requireddata.members[].scopeSummary.trunks	string	-
`createdAt`requireddata.members[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.members[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`roles`requireddata.roles	object[]	-

Errors

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

Field	Type	Description
`email`required	string (email)	-max 255 chars
`role`required	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

Field	Type	Description
`data`required	object	Same fields as SwitchTeamMember, 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/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

Name	In	Type	Description
`memberId`required	path	string	-

Request body (application/json)

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

Field	Type	Description
`data`required	object	Same fields as SwitchTeamMember, 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.

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

Name	In	Type	Description
`memberId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchTeamMember, 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.

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

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

Field	Type	Description
`data`required	object	-
`entries`requireddata.entries	object[]	-
`nextCursor`requireddata.nextCursor	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.

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

Field	Type	Description
`data`required	object	-
`actors`requireddata.actors	object[]	-
`permissions`requireddata.permissions	string[]	-
`sensitivePermissions`requireddata.sensitivePermissions	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.
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

Name	In	Type	Description
`status`	query	string	Comma-separated statuses
`limit`	query	integer	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`status`requireddata[].status	string	pending, approved, rejected, expired...
`permission`data[].permission	string	-
`requestedAt`requireddata[].requestedAt	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.

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`decision`required	string	-One of `approve`, `reject`
`note`	string \| null	-max 2000 chars

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchApproval, 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.

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

Field	Type	Description
`data`required	object	-
`policies`requireddata.policies	object[]	-
`eligible`requireddata.eligible	string[]	Permissions that can be put behind an approval
`pending`requireddata.pending	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.

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)

Field	Type	Description
`permission`required	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
`enabled`required	boolean	-
`minAmountUsd`	number \| null	-min 0
`requireDifferentPerson`	boolean	-
`expiresAfterHours`	integer	-1 to 2160
`requireReason`	boolean	-

Response 200

Field	Type	Description
`data`required	object	-

Response 202

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

Errors

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