Switch API reference

Switch: operations

NOC, live calls, issues, fraud, the operations queue and AI control.

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

BrowseSwitch: operations

See which caller IDs are presented, and by whom

GET/api/v1/switch/fraud/cli-watch

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

Observe only: nothing here blocks traffic. wouldBlock states how much real traffic a "same caller ID N times" rule would refuse before anyone enables one.

Parameters

Name	In	Type	Description
`hours`	query	number	-
`minCalls`	query	integer	-
`limit`	query	integer	-

Response 200

Field	Type	Description
`data`required	object	-
`hours`requireddata.hours	number	-
`minCalls`requireddata.minCalls	integer	-
`watch`requireddata.watch	object[]	-
`spoofingSuspects`requireddata.spoofingSuspects	integer	-
`wouldBlock`requireddata.wouldBlock	object	-
`clis`requireddata.wouldBlock.clis	integer	-
`calls`requireddata.wouldBlock.calls	integer	-
`totalCalls`requireddata.wouldBlock.totalCalls	integer	-
`percent`requireddata.wouldBlock.percent	number	-

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.

See which senders rotate through many caller IDs

GET/api/v1/switch/fraud/ani-watch

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

Observe only. Per sender, how many distinct caller IDs were presented in the window.

Parameters

Name	In	Type	Description
`hours`	query	number	-
`minCalls`	query	integer	-
`maxDistinct`	query	integer	-
`limit`	query	integer	-

Response 200

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

Get fraud screening settings

GET/api/v1/switch/fraud/settings

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

Response 200

Field	Type	Description
`data`required	object	-
`fraudEnabled`requireddata.fraudEnabled	boolean	-
`fraudBlockScore`requireddata.fraudBlockScore	integer	Risk score at or above which a call is refused1 to 100
`fraudAlertScore`requireddata.fraudAlertScore	integer	Risk score at or above which a call is flagged1 to 100
`highRiskPrefixes`requireddata.highRiskPrefixes	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.

Update fraud screening settings

POST/api/v1/switch/fraud/settings

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

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

Request body (application/json)

Field	Type	Description
`fraudEnabled`	boolean	-
`fraudBlockScore`	integer	Risk score at or above which a call is refused1 to 100
`fraudAlertScore`	integer	Risk score at or above which a call is flagged1 to 100
`highRiskPrefixes`	string[]	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchFraudSettings, 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/fraud/settings" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fraudEnabled": true,
  "fraudBlockScore": 1
}'

Run it here with a test key.

List fraud screening events

GET/api/v1/switch/fraud/events

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

Calls that were flagged or blocked by fraud screening, newest first.

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`customerLabel`requireddata[].customerLabel	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.

List what needs attention first on the switch

GET/api/v1/switch/operations-queue

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

Derived on every request from live trunk state, 24-hour margin and post-dial delay, rating and deck provenance. Each item carries the same issue reference used everywhere else.

Response 200

Field	Type	Description
`data`required	object[]	-
`priority`requireddata[].priority	string	-
`kind`requireddata[].kind	string	-One of `trunk`, `margin`, `quality`, `fraud`, `rating`, `deck`, `credit`, `setup`
`title`requireddata[].title	string	-
`subject`requireddata[].subject	string	-
`detail`requireddata[].detail	string	-
`since`requireddata[].since	string	-
`href`requireddata[].href	string	Dashboard path where it can be acted on
`ref`requireddata[].ref	string	Issue reference, e.g. OPS-3F9A1C22
`severity`requireddata[].severity	string	-One of `critical`, `warning`, `review`

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 operational issues

GET/api/v1/switch/issues

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

Every warning the product shows comes from this list. Team members see only issues within their customer and trunk scope. Nothing here changes routing, admission or rating: issue actions only change what people see and who owns it.

Parameters

Name	In	Type	Description
`customerId`	query	string (uuid)	-
`customerTrunkId`	query	string (uuid)	-
`trunkId`	query	string (uuid)	Supplier trunk
`supplierId`	query	string (uuid)	-
`destination`	query	string	-
`includeReview`	query	string	Include review-severity issues (default true)One of true, false

Response 200

Field	Type	Description
`data`required	object[]	-
`key`requireddata[].key	string	-
`ref`requireddata[].ref	string	Quotable reference, e.g. OPS-3F9A1C22
`detector`requireddata[].detector	string	-
`severity`requireddata[].severity	string	-One of `critical`, `warning`, `review`
`actionable`requireddata[].actionable	boolean	-
`status`requireddata[].status	string	-One of `open_unacknowledged`, `open_acknowledged`, `resolved`
`title`requireddata[].title	string	-
`summary`requireddata[].summary	string	-
`reason`requireddata[].reason	string	-
`trigger`requireddata[].trigger	string	-
`recovery`requireddata[].recovery	string	-
`objectName`requireddata[].objectName	string \| null	-
`subjects`requireddata[].subjects	object	The customer, trunks, supplier and destination the issue is about
`evidence`requireddata[].evidence	object[]	-
`label`requireddata[].evidence[].label	string	-
`value`requireddata[].evidence[].value	string	-
`firstDetectedAt`requireddata[].firstDetectedAt	string	-
`lastDetectedAt`requireddata[].lastDetectedAt	string	-
`detections`requireddata[].detections	integer	-
`acknowledgedAt`requireddata[].acknowledgedAt	string \| null	-
`resolvedAt`requireddata[].resolvedAt	string \| null	-
`resolvedVia`requireddata[].resolvedVia	string \| null	-One of `operator`, `recovery`, `dismissed`
`dismissRule`requireddata[].dismissRule	string \| null	What would reopen the issue if it were dismissed

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 an operational issue by reference

GET/api/v1/switch/issues/{ref}

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

Parameters

Name	In	Type	Description
`ref`required	path	string	-

Response 200

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

Get the history of an operational issue

GET/api/v1/switch/issues/{ref}/timeline

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

Parameters

Name	In	Type	Description
`ref`required	path	string	-

Response 200

Field	Type	Description
`data`required	object[]	-
`action`requireddata[].action	string	-
`fromStatus`requireddata[].fromStatus	string \| null	-
`toStatus`requireddata[].toStatus	string \| null	-
`note`requireddata[].note	string \| null	-
`at`requireddata[].at	string (date-time)	ISO-8601 timestamp (UTC)
`by`requireddata[].by	string	Who acted, or "the platform" for automatic changes

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.

Acknowledge an operational issue

POST/api/v1/switch/issues/{ref}/acknowledge

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
`ref`required	path	string	-

Request body (application/json)

Field	Type	Description
`note`	string	-max 1000 chars

Response 200

Field	Type	Description
`data`required	object	-
`ref`requireddata.ref	string	-
`status`requireddata.status	string	-One of `open_unacknowledged`, `open_acknowledged`, `resolved`

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/issues/<ref>/acknowledge" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Example"
}'

Run it here with a test key.

Assign an operational issue to a team member

POST/api/v1/switch/issues/{ref}/assign

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

Pass userId: null to unassign.

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
`ref`required	path	string	-

Request body (application/json)

Field	Type	Description
`userId`required	string (uuid) \| null	-

Response 200

Field	Type	Description
`data`required	object	-
`ref`requireddata.ref	string	-
`ownerUserId`requireddata.ownerUserId	string (uuid) \| null	-

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/issues/<ref>/assign" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "<userId>"
}'

Run it here with a test key.

Resolve an operational issue

POST/api/v1/switch/issues/{ref}/resolve

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
`ref`required	path	string	-

Request body (application/json)

Field	Type	Description
`resolution`	string	-max 2000 chars

Response 200

Field	Type	Description
`data`required	object	-
`ref`requireddata.ref	string	-
`status`requireddata.status	string	-One of `open_unacknowledged`, `open_acknowledged`, `resolved`

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/issues/<ref>/resolve" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resolution": "<resolution>"
}'

Run it here with a test key.

Dismiss an operational issue

POST/api/v1/switch/issues/{ref}/dismiss

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

Closes it as dismissed. It reopens automatically if the condition in reopensWhen occurs.

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
`ref`required	path	string	-

Request body (application/json)

Field	Type	Description
`reason`	string	-max 500 chars

Response 200

Field	Type	Description
`data`required	object	-
`ref`requireddata.ref	string	-
`status`requireddata.status	string	-One of `open_unacknowledged`, `open_acknowledged`, `resolved`
`resolvedVia`requireddata.resolvedVia	string	-One of `dismissed`
`reason`requireddata.reason	string \| null	-
`reopensWhen`requireddata.reopensWhen	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.

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/issues/<ref>/dismiss" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Example"
}'

Run it here with a test key.

Reopen a resolved or dismissed operational issue

POST/api/v1/switch/issues/{ref}/reopen

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
`ref`required	path	string	-

Request body (application/json)

Field	Type	Description
`note`	string	-max 1000 chars

Response 200

Field	Type	Description
`data`required	object	-
`ref`requireddata.ref	string	-
`status`requireddata.status	string	-One of `open_unacknowledged`, `open_acknowledged`, `resolved`

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/issues/<ref>/reopen" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Example"
}'

Run it here with a test key.

Snooze notifications for an operational issue

POST/api/v1/switch/issues/{ref}/snooze

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

Mutes notifications only; the issue stays open and visible. Up to 14 days.

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
`ref`required	path	string	-

Request body (application/json)

Field	Type	Description
`minutes`required	integer	-1 to 20160

Response 200

Field	Type	Description
`data`required	object	-
`ref`requireddata.ref	string	-
`snoozedUntil`requireddata.snoozedUntil	string (date-time)	ISO-8601 timestamp (UTC)
`issueStatus`requireddata.issueStatus	string	-One of `open_unacknowledged`, `open_acknowledged`, `resolved`

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/issues/<ref>/snooze" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "minutes": 1
}'

Run it here with a test key.

Count fraud screening events

GET/api/v1/switch/fraud/summary

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

Response 200

Field	Type	Description
`data`required	object	-
`total`requireddata.total	integer	-
`blocked`requireddata.blocked	integer	-
`flagged`requireddata.flagged	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.

Get the learned traffic baseline used for risk scoring

GET/api/v1/switch/fraud/baseline

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

Response 200

Field	Type	Description
`data`required	object \| 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.

Retrain the traffic baseline from recent calls

POST/api/v1/switch/fraud/retrain

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.

Response 200

Field	Type	Description
`data`required	object	-
`sampleCalls`requireddata.sampleCalls	integer	-
`baseline`requireddata.baseline	object \| 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.
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.

Score the risk of a call without placing it

POST/api/v1/switch/fraud/score

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

Dry run of the risk assessment for a customer calling a destination. An unknown customer answers 404 NOT_FOUND.

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
`subAccountId`required	string (uuid)	-
`destination`required	string	-max 32 chars

Response 200

Field	Type	Description
`data`required	object	Risk score, the factors behind it and the action screening would take

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/fraud/score" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subAccountId": "<subAccountId>",
  "destination": "+447700900123"
}'

Run it here with a test key.

List calls in progress

GET/api/v1/switch/live

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

Calls up now, from the live monitor. Filters narrow the list; unsupported names any requested filter this surface cannot apply.

Parameters

Name	In	Type	Description
`subAccountId`	query	string (uuid)	-
`countryPrefix`	query	string	-
`destination`	query	string	-
`kind`	query	string	-One of voice, sms
`answeredState`	query	string	-One of answered, unanswered
`supplierName`	query	string	-

Response 200

Field	Type	Description
`data`required	object	Live calls plus the filter vocabulary this surface supports
`population`data.population	any	-
`supports`requireddata.supports	string[]	-
`unsupported`requireddata.unsupported	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.

Ask AI Control a question about your switch

POST/api/v1/switch/noc/ask

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

Natural-language questions and requests about your traffic, answered from your own switch data within your team permissions. Returns a reply and any actions it proposes or took. Nothing changes unless your role allows it.

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
`message`required	string	-max 4000 chars
`history`	any[]	Earlier turns of the conversation

Response 200

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

HTTP

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

Run it here with a test key.

Get Do Not Call list sizes and recent hits

GET/api/v1/switch/dnc/summary

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

Do Not Call on the Switch uses ONE list: the same entries as the Dialer's suppression list (/dnc), plus the platform-wide list. A call from a customer or trunk with "Honor Do Not Call" on is checked against both. This returns the list sizes, your entries by source, the Switch calls that matched in the last 7 and 30 days, how many customers and trunks honour the list, and the platform mode.

Response 200

Field	Type	Description
`data`required	object	-
`ownCount`requireddata.ownCount	integer	Entries on your own list
`globalCount`requireddata.globalCount	integer	Entries on the platform-wide list
`bySource`requireddata.bySource	object	Your entries per source (manual, upload, sms_stop, callguard_optout)
`hits`requireddata.hits	object	Switch calls that matched, refused or only warned, over 7 and 30 days
`refused7`requireddata.hits.refused7	integer	-
`warned7`requireddata.hits.warned7	integer	-
`refused30`requireddata.hits.refused30	integer	-
`warned30`requireddata.hits.warned30	integer	-
`customersHonoring`requireddata.customersHonoring	integer	-
`trunksHonoring`requireddata.trunksHonoring	integer	Trunks with the setting explicitly on
`mode`requireddata.mode	string	The platform setting for Switch calls: off = not checked; warn = matches are recorded but the call proceeds; enforce = matches are refusedOne of `off`, `warn`, `enforce`
`timeoutMs`requireddata.timeoutMs	integer	The lookup time budget per call; a slower lookup lets the call through

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 Do Not Call entries

GET/api/v1/switch/dnc/entries

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

Your own list and the platform-wide list. Reasons are shown only for your own entries.

Parameters

Name	In	Type	Description
`q`	query	string	Number prefix to search for
`scope`	query	string	-One of all, own, global
`limit`	query	integer	-
`offset`	query	integer	-

Response 200

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string (uuid)	-
`phoneNumber`requireddata.rows[].phoneNumber	string	-
`source`requireddata.rows[].source	string \| null	-
`createdAt`requireddata.rows[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`scope`requireddata.rows[].scope	string	own = your list; global = the platform-wide listOne of `own`, `global`
`reason`requireddata.rows[].reason	string \| null	-
`hasMore`requireddata.hasMore	boolean	-

Errors

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

List calls refused or warned by Do Not Call

GET/api/v1/switch/dnc/hits

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

Your customers' Switch calls whose number matched a Do Not Call list, newest first (default 50, max 200).

Parameters

Name	In	Type	Description
`limit`	query	integer	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`phoneNumber`requireddata[].phoneNumber	string	-
`listScope`requireddata[].listScope	string	Which list matchedOne of `own`, `global`
`outcome`requireddata[].outcome	string	refused = the call was blocked (enforce mode); warned = recorded onlyOne of `refused`, `warned`
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`subAccountId`requireddata[].subAccountId	string (uuid) \| null	-
`customerTrunkId`requireddata[].customerTrunkId	string (uuid) \| null	-
`customer`requireddata[].customer	string \| null	-
`trunk`requireddata[].trunk	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.

Check whether a number is on a Do Not Call list

GET/api/v1/switch/dnc/check

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

Checks one number against your list and the platform list. When it is on both, your own entry is returned. The platform list never shows its reason.

Parameters

Name	In	Type	Description
`number`required	query	string	-

Response 200

Field	Type	Description
`data`required	object	-
`input`requireddata.input	string	What you sent
`number`requireddata.number	string \| null	The number as stored on the list (digits); null when nothing could be read
`valid`requireddata.valid	boolean	Whether it reads as a dialable number
`listed`requireddata.listed	boolean	-
`scope`requireddata.scope	string \| null	own = your list; global = the platform-wide listOne of `own`, `global`
`entry`requireddata.entry	object \| null	-
`id`requireddata.entry.id	string (uuid)	-
`source`requireddata.entry.source	string \| null	-
`createdAt`requireddata.entry.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`reason`requireddata.entry.reason	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.

List which customers and trunks honour Do Not Call

GET/api/v1/switch/dnc/customers

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

Every customer's setting with each trunk's own value (null = inherits from the customer) and the effective result.

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`label`requireddata[].label	string	-
`status`requireddata[].status	string	-
`honorDnc`requireddata[].honorDnc	boolean	-
`trunks`requireddata[].trunks	object[]	-
`id`requireddata[].trunks[].id	string (uuid)	-
`label`requireddata[].trunks[].label	string	-
`status`requireddata[].trunks[].status	string	-
`honorDnc`requireddata[].trunks[].honorDnc	boolean \| null	-
`effective`requireddata[].trunks[].effective	boolean	-

Errors

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

Get the Do Not Call setting of a customer or trunk

GET/api/v1/switch/dnc/honor

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

Name subAccountId or customerTrunkId. A customer or trunk that is not yours answers 404.

Parameters

Name	In	Type	Description
`subAccountId`	query	string (uuid)	-
`customerTrunkId`	query	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object	-
`scope`requireddata.scope	string	-One of `customer`, `trunk`
`id`requireddata.id	string (uuid)	-
`label`requireddata.label	string	-
`value`requireddata.value	boolean \| null	The setting itself; null on a trunk means it inherits from its customer
`inherited`requireddata.inherited	boolean \| null	-
`customerLabel`requireddata.customerLabel	string \| null	-
`effective`requireddata.effective	boolean	Whether calls are actually checked against Do Not Call
`decidedBy`requireddata.decidedBy	string	Which level decided `effective`One of `customer`, `trunk`
`mode`requireddata.mode	string	The platform setting for Switch calls: off = not checked; warn = matches are recorded but the call proceeds; enforce = matches are refusedOne of `off`, `warn`, `enforce`
`trunkOverrides`data.trunkOverrides	object	Customer only: trunks that set their own value instead of inheriting
`on`requireddata.trunkOverrides.on	integer	-
`off`requireddata.trunkOverrides.off	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.

Turn Do Not Call on or off for a customer or trunk

PATCH/api/v1/switch/dnc/honor

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

Name exactly one of subAccountId or customerTrunkId. A trunk can pass honor: null to inherit from its customer; a customer is either on or off. Takes effect on the next call and is audited with the before and after values.

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
`subAccountId`	string (uuid)	-
`customerTrunkId`	string (uuid)	-
`honor`required	boolean \| null	-

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchDncHonorSetting, 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 PATCH "https://packetexchange.io/api/v1/switch/dnc/honor" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "honor": true
}'

Run it here with a test key.

Remove Do Not Call numbers from an uploaded list

POST/api/v1/switch/dnc/scrub

Access: API key. Scoped keys need switch:manage.
Rate limit: 10 requests per minute

Upload a CSV or text file (multipart, field file, up to 500,000 rows and 16 MB). Rows whose number is on your list or the platform list are removed; every other row, including a header, comes back unchanged. With ?format=csv the cleaned file is returned directly (counts in the X-Dnc-Rows, X-Dnc-Clean, X-Dnc-Removed-Own, X-Dnc-Removed-Global and X-Dnc-Invalid headers); otherwise the counts are returned and the file can be fetched from GET /switch/dnc/scrub/{id} for one hour. Rows that cannot be read as a number are kept and counted as invalid.

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
`format`	query	string	-One of csv, json

Request body (multipart/form-data)

Field	Type	Description
`file`required	string	CSV or text file of numbers (max 16 MB)

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid) \| null	Download id, valid for one hour; null when the copy could not be stored (the counts are still correct: run again with ?format=csv)
`filename`requireddata.filename	string	-
`counts`requireddata.counts	object	-
`rows`requireddata.counts.rows	integer	-
`clean`requireddata.counts.clean	integer	-
`removedOwn`requireddata.counts.removedOwn	integer	-
`removedGlobal`requireddata.counts.removedGlobal	integer	-
`invalid`requireddata.counts.invalid	integer	-
`hadHeader`requireddata.counts.hadHeader	boolean	-
`invalidSamples`requireddata.invalidSamples	string[]	Up to 10 unreadable rows (first 80 characters each)
`ms`requireddata.ms	integer	Processing time in milliseconds

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/dnc/scrub" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -F "file=@rates.csv"

Run it here with a test key.

Download a scrubbed file

GET/api/v1/switch/dnc/scrub/{id}

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

Scrub results are kept for one hour; after that (or for an id that is not yours) the answer is 404 and the scrub must be run again.

Parameters

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

Response 200 (text/csv)

The cleaned CSV, as an attachment.

Errors

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

Add numbers to your Do Not Call list from a file

POST/api/v1/switch/dnc/import

Access: API key. Scoped keys need switch:manage.
Rate limit: 10 requests per minute

Multipart upload: field file (CSV or text of numbers, up to 500,000 rows and 16 MB) and an optional reason, which must come BEFORE the file part. The number column is found from the first line (a phone-like header, else the first column). Numbers already listed are skipped. Audited.

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 (multipart/form-data)

Field	Type	Description
`file`required	string	CSV or text file of numbers (max 16 MB)
`reason`	string	-max 500 chars

Response 200

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	integer	Number rows read (a header row is not counted)
`added`requireddata.added	integer	-
`skipped`requireddata.skipped	integer	Valid numbers already listed, or repeated within the file
`invalid`requireddata.invalid	integer	Rows that could not be read as a number

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/dnc/import" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -F "file=@rates.csv" \
  -F "reason=..."

Run it here with a test key.

Download your Do Not Call list as CSV

GET/api/v1/switch/dnc/export

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

Response 200 (text/csv)

Your own Do Not Call list, as an attachment named do-not-call-<date>.csv. Columns: phone_number, source, reason, added_at.

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.