Skip to content

Switch API reference

Switch: customer trunks

Customer trunks: addressing, credentials, limits, readiness and approvals.

48 operationsBase URL https://packetexchange.io/api/v1Postman collection
BrowseSwitch: customer trunks

List the trunk authentication methods available to you

GET/api/v1/switch/customer-trunks/auth-modes

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

For each method: what the customer must send and what the switch checks. Methods the platform cannot honour for you are omitted.

Response 200

  • datarequired

    object[]

  • moderequired

    string · data[].mode

    One of ip, credentials, ip_and_credentials, registration, certificate

  • titlerequired

    string · data[].title

  • summaryrequired

    string · data[].summary

  • sendsrequired

    string[] · data[].sends

    What the customer must send

  • checksrequired

    string[] · data[].checks

    What the switch checks on every call

  • requiresrequired

    string[] · data[].requires

    One of addresses, credentials

  • needsPlatformSupport

    boolean · data[].needsPlatformSupport

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 a Switch customer trunk

PATCH/api/v1/switch/customer-trunks/{trunkId}

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

Setting status to disabled stops new calls but keeps the trunk configurable. A sipPassword sent here is echoed back once. Archived trunks are frozen: restore first. Send X-If-Unchanged-Since: <updatedAt you loaded> to have the save refused with 409 STALE_WRITE if someone changed the record since.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • label

    string

    max 120 chars

  • authMode

    string

    What the customer must present; the service refuses a mode the trunk is not configured forOne of ip, credentials, ip_and_credentials, registration, certificate

  • sipUsername

    string | null

    max 64 chars

  • sipPassword

    string | null

    max 64 chars

  • maxConcurrentCalls

    integer | null

    0 to 100000

  • maxCps

    integer | null

    0 to 10000

  • markupPct

    number | null

    0 to 10000

  • billingIncrement

    string | null

    max 10 chars

  • blockedPrefixes

    string | null

    max 8000 chars

  • status

    string

    One of active, disabled

  • mediaMode

    string

    One of proxy, direct

  • techPrefix

    string | null

    max 24 chars

  • cliRewrite

    object | null

  • mode

    string · cliRewrite.mode

    One of pattern

  • value

    string · cliRewrite.value

    max 24 chars

  • strip

    integer · cliRewrite.strip

    0 to 15

  • add

    string · cliRewrite.add

    max 12 chars

  • match

    string · cliRewrite.match

    max 200 chars

  • replace

    string · cliRewrite.replace

    max 200 chars

  • allowedPrefixes

    string[] | null

  • allowedCountries

    string[] | null

  • blockedCountries

    string[] | null

  • maxCallDurationSeconds

    integer | null

    1 to 21600

  • requireCli

    boolean

  • allowedClis

    string[] | null

  • marginProtectionMode

    string

    One of off, monitor, enforce

  • minMarginPct

    number | null

    0 to 99.999

  • minMarginAbs

    number | null

    0 to 1000

  • maxLossPerMinute

    number | null

    0 to 1000

  • dailyLossLimit

    number | null

    Warns only; never blocks0 to 10000000

  • dailyLossLimitPct

    number | null

    0 to 100000

Response 200

  • datarequired

    object

  • idrequired

    string (uuid) · data.id

  • subAccountIdrequired

    string (uuid) · data.subAccountId

    The customer this trunk belongs to

  • labelrequired

    string · data.label

  • statusrequired

    string · data.status

    One of active, disabled, archived

  • authMode

    string · data.authMode

    One of ip, credentials, ip_and_credentials, registration, certificate

  • sipUsernamerequired

    string | null · data.sipUsername

  • sipPasswordSetrequired

    boolean · data.sipPasswordSet

  • maxConcurrentCallsrequired

    integer | null · data.maxConcurrentCalls

    Null inherits the customer ceiling

  • maxCpsrequired

    integer | null · data.maxCps

  • markupPctrequired

    string | null · data.markupPct

  • billingIncrementrequired

    string | null · data.billingIncrement

  • techPrefixrequired

    string | null · data.techPrefix

  • mediaMode

    string · data.mediaMode

    One of proxy, direct

  • cliRewriterequired

    object | null · data.cliRewrite

  • allowedPrefixesrequired

    string[] | null · data.allowedPrefixes

  • allowedCountriesrequired

    string[] | null · data.allowedCountries

  • blockedCountriesrequired

    string[] | null · data.blockedCountries

  • createdAtrequired

    string (date-time) · data.createdAt

    ISO-8601 timestamp (UTC)

  • updatedAtrequired

    string (date-time) · data.updatedAt

    ISO-8601 timestamp (UTC)

Response 202

  • 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

Delete an unused Switch customer trunk

DELETE/api/v1/switch/customer-trunks/{trunkId}

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

Refused, naming the dependency, once the trunk has carried traffic, holds rates or routing, or is the customer's last trunk. Archive it instead. Check removability first.

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

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • deletedrequired

    boolean · data.deleted

    One of true

  • labelrequired

    string · data.label

Response 202

  • 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

Show the configuration actually in force on a trunk

GET/api/v1/switch/customer-trunks/{trunkId}/effective-config

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

Every setting with the value a call would meet and the level it was inherited from, resolved by the same code as the call path. Read-only.

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • trunkrequired

    object · data.trunk

  • idrequired

    string (uuid) · data.trunk.id

  • labelrequired

    string · data.trunk.label

  • statusrequired

    string · data.trunk.status

  • customerIdrequired

    string (uuid) · data.trunk.customerId

  • customerLabelrequired

    string · data.trunk.customerLabel

  • sectionsrequired

    object[] · data.sections

    Each setting with the value in force and the level it came from

  • capacityrequired

    object · data.capacity

  • limitsrequired

    object[] · data.capacity.limits

  • refusals

    any · data.capacity.refusals

  • checkOrderrequired

    string[] · data.capacity.checkOrder

  • noterequired

    string · data.capacity.note

  • readOnlyrequired

    boolean · data.readOnly

    One of true

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.

Archive a Switch customer trunk

POST/api/v1/switch/customer-trunks/{trunkId}/archive

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

Takes the trunk out of service and out of operational lists, and freezes it. Nothing is destroyed; restore brings it back disabled.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • reason

    string | null

    max 500 chars

Response 200

Response 202

  • 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

Restore an archived Switch customer trunk

POST/api/v1/switch/customer-trunks/{trunkId}/restore

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

Comes back disabled, so no traffic starts until you enable 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.

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

Response 202

  • 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

Preview what disabling, enabling or archiving a trunk would do

GET/api/v1/switch/customer-trunks/{trunkId}/service-impact

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

Live channels, recent traffic, whether it is the customer's last enabled trunk, and what survives.

Parameters

  • trunkIdrequired

    path · string (uuid)

  • action

    query · string

    Default disableOne of disable, enable, archive, restore

Response 200

  • datarequired

    object

  • actionrequired

    string · data.action

    One of disable, enable, archive, restore

  • trunkrequired

    object · data.trunk

  • idrequired

    string (uuid) · data.trunk.id

  • labelrequired

    string · data.trunk.label

  • statusrequired

    string · data.trunk.status

  • customerrequired

    object · data.customer

  • idrequired

    string (uuid) · data.customer.id

  • labelrequired

    string · data.customer.label

  • statusrequired

    string · data.customer.status

  • liveChannelsrequired

    integer · data.liveChannels

  • last24hrequired

    object · data.last24h

  • siblingsEnabledrequired

    integer · data.siblingsEnabled

  • stopsCustomerrequired

    boolean · data.stopsCustomer

    True when this is the customer's last enabled trunk

  • reversiblerequired

    boolean · data.reversible

  • consequencesrequired

    string[] · data.consequences

  • preservedrequired

    string[] · data.preserved

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.

Check whether a Switch customer trunk can be deleted

GET/api/v1/switch/customer-trunks/{trunkId}/removability

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

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • trunkrequired

    object · data.trunk

  • idrequired

    string (uuid) · data.trunk.id

  • labelrequired

    string · data.trunk.label

  • statusrequired

    string · data.trunk.status

  • deletablerequired

    boolean · data.deletable

  • blockersrequired

    object[] · data.blockers

  • kindrequired

    string · data.blockers[].kind

    One of traffic, refusals, billing, rates, routing, audit, last_trunk

  • countrequired

    integer · data.blockers[].count

  • detailrequired

    string · data.blockers[].detail

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.

Clone a Switch customer trunk

POST/api/v1/switch/customer-trunks/{trunkId}/clone

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

Copies the trunk's settings and sell rates to a new trunk on the same customer.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • labelrequired

    string

    max 120 chars

Response 201

  • datarequired

    object

  • idrequired

    string (uuid) · data.id

  • subAccountIdrequired

    string (uuid) · data.subAccountId

    The customer this trunk belongs to

  • labelrequired

    string · data.label

  • statusrequired

    string · data.status

    One of active, disabled, archived

  • authMode

    string · data.authMode

    One of ip, credentials, ip_and_credentials, registration, certificate

  • sipUsernamerequired

    string | null · data.sipUsername

  • sipPasswordSetrequired

    boolean · data.sipPasswordSet

  • maxConcurrentCallsrequired

    integer | null · data.maxConcurrentCalls

    Null inherits the customer ceiling

  • maxCpsrequired

    integer | null · data.maxCps

  • markupPctrequired

    string | null · data.markupPct

  • billingIncrementrequired

    string | null · data.billingIncrement

  • techPrefixrequired

    string | null · data.techPrefix

  • mediaMode

    string · data.mediaMode

    One of proxy, direct

  • cliRewriterequired

    object | null · data.cliRewrite

  • allowedPrefixesrequired

    string[] | null · data.allowedPrefixes

  • allowedCountriesrequired

    string[] | null · data.allowedCountries

  • blockedCountriesrequired

    string[] | null · data.blockedCountries

  • createdAtrequired

    string (date-time) · data.createdAt

    ISO-8601 timestamp (UTC)

  • updatedAtrequired

    string (date-time) · data.updatedAt

    ISO-8601 timestamp (UTC)

  • copiedRatesrequired

    integer · data.copiedRates

Response 202

  • 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

List a trunk's allowed source addresses

GET/api/v1/switch/customer-trunks/{trunkId}/ips

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

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object[]

  • idrequired

    string (uuid) · data[].id

  • cidrrequired

    string · data[].cidr

  • descriptionrequired

    string | null · data[].description

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.

Allow a source address on a trunk

POST/api/v1/switch/customer-trunks/{trunkId}/ips

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

Stored in canonical form. Refused when it cannot be saved (see addresses/preview); overlaps with other entries are returned in conflicts. Applies to new calls only.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • cidrrequired

    string

    An IP address or CIDR blockmax 64 chars

  • description

    string

    max 160 chars

Response 201

  • datarequired

    object

  • idrequired

    string (uuid) · data.id

  • cidrrequired

    string · data.cidr

  • descriptionrequired

    string | null · data.description

  • conflictsrequired

    object[] · data.conflicts

  • kindrequired

    string · data.conflicts[].kind

  • otherIdrequired

    string (uuid) · data.conflicts[].otherId

  • otherCidrrequired

    string · data.conflicts[].otherCidr

  • otherTrunkIdrequired

    string (uuid) | null · data.conflicts[].otherTrunkId

  • otherTrunkLabelrequired

    string | null · data.conflicts[].otherTrunkLabel

  • otherCustomerIdrequired

    string (uuid) | null · data.conflicts[].otherCustomerId

  • otherCustomerLabelrequired

    string | null · data.conflicts[].otherCustomerLabel

Response 202

  • 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

List a trunk's addresses with overlaps and customer-level entries

GET/api/v1/switch/customer-trunks/{trunkId}/addresses

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

The richer form of /ips: each entry with its canonical form and every overlapping entry on your switch, including addresses added on the customer.

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • trunkIdrequired

    string (uuid) · data.trunkId

  • trunkLabelrequired

    string · data.trunkLabel

  • customerIdrequired

    string (uuid) · data.customerId

  • entriesrequired

    object[] · data.entries

  • idrequired

    string (uuid) · data.entries[].id

  • cidrrequired

    string · data.entries[].cidr

  • canonicalrequired

    string | null · data.entries[].canonical

  • descriptionrequired

    string | null · data.entries[].description

  • ambiguous

    boolean · data.entries[].ambiguous

  • customerLevelrequired

    object[] · data.customerLevel

    Addresses added on the customer, which apply to every trunk

  • ambiguousCountrequired

    integer · data.ambiguousCount

  • activationrequired

    object · data.activation

  • appliesTorequired

    string · data.activation.appliesTo

    One of new_requests

  • affectsCallsInProgressrequired

    boolean · data.activation.affectsCallsInProgress

    One of false

  • noterequired

    string · data.activation.note

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.

Preview an address before allowing it on a trunk

POST/api/v1/switch/customer-trunks/{trunkId}/addresses/preview

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

Read-only: the canonical form, size, whether it would be refused, and what it overlaps.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • cidrrequired

    string

    max 64 chars

Response 200

  • datarequired

    object

  • canonicalrequired

    string · data.canonical

  • prefixBitsrequired

    integer · data.prefixBits

  • addressCountrequired

    number · data.addressCount

  • blockedrequired

    object | null · data.blocked

    Set when the address cannot be saved at all

  • reasonrequired

    string · data.blocked.reason

  • conflictsrequired

    object[] · data.conflicts

  • kindrequired

    string · data.conflicts[].kind

  • otherIdrequired

    string (uuid) · data.conflicts[].otherId

  • otherCidrrequired

    string · data.conflicts[].otherCidr

  • otherTrunkIdrequired

    string (uuid) | null · data.conflicts[].otherTrunkId

  • otherTrunkLabelrequired

    string | null · data.conflicts[].otherTrunkLabel

  • otherCustomerIdrequired

    string (uuid) | null · data.conflicts[].otherCustomerId

  • otherCustomerLabelrequired

    string | null · data.conflicts[].otherCustomerLabel

Response 202

  • 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

Test a caller-ID rewrite rule against a sample number

POST/api/v1/switch/customer-trunks/cli-rewrite/preview

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

Dry run; saves nothing and needs no trunk.

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)

  • rule

    any

    A cliRewrite rule as used on a trunk

  • samplerequired

    string

    max 32 chars

Response 200

  • datarequired

    object

  • okrequired

    boolean · data.ok

  • resultrequired

    string | null · data.result

  • error

    string · data.error

Response 202

  • 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.

Remove an allowed source address from a trunk

DELETE/api/v1/switch/customer-trunks/{trunkId}/ips/{aclId}

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

  • trunkIdrequired

    path · string (uuid)

  • aclIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • idrequired

    string (uuid) · data.id

  • cidrrequired

    string · data.cidr

  • descriptionrequired

    string | null · data.description

  • deletedrequired

    boolean · data.deleted

    One of true

Response 202

  • 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

Set routing on a Switch customer trunk

POST/api/v1/switch/customer-trunks/{trunkId}/routing

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

Route group, failover group, dialplan, strategy or a direct supplier for this trunk. Send X-If-Unchanged-Since: <updatedAt you loaded> to have the save refused with 409 STALE_WRITE if someone changed the record since.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • routePlanId

    string (uuid) | null

  • failoverRoutePlanId

    string (uuid) | null

  • directRouteId

    string (uuid) | null

  • directVendorTrunkId

    string (uuid) | null

  • dialplanId

    string (uuid) | null

  • strategyOverride

    string | null

    max 24 chars

Response 200

  • datarequired

    object

  • subAccountIdrequired

    string (uuid) · data.subAccountId

  • customerTrunkId

    string (uuid) | null · data.customerTrunkId

  • dialplanIdrequired

    string (uuid) | null · data.dialplanId

  • routePlanIdrequired

    string (uuid) | null · data.routePlanId

  • failoverRoutePlanIdrequired

    string (uuid) | null · data.failoverRoutePlanId

  • strategyOverriderequired

    string | null · data.strategyOverride

  • directRouteIdrequired

    string (uuid) | null · data.directRouteId

  • directVendorTrunkIdrequired

    string (uuid) | null · data.directVendorTrunkId

Response 202

  • 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

Show the route wired up for a trunk

GET/api/v1/switch/customer-trunks/{trunkId}/routing-path

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

Customer, trunk, fixed route or route group, then supplier trunks, with ids. For what a specific number would do, use /switch/routing/preview.

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • customerrequired

    object | null · data.customer

  • idrequired

    string (uuid) · data.customer.id

  • labelrequired

    string · data.customer.label

  • customerTrunkrequired

    object · data.customerTrunk

  • idrequired

    string (uuid) · data.customerTrunk.id

  • labelrequired

    string · data.customerTrunk.label

  • statusrequired

    string · data.customerTrunk.status

  • techPrefixrequired

    string | null · data.customerTrunk.techPrefix

  • kindrequired

    string · data.kind

    Fixed route, route group, or nothing wiredOne of fixed, group, none

  • fixedrequired

    object | null · data.fixed

  • grouprequired

    object | null · data.group

  • failoverGrouprequired

    object | null · data.failoverGroup

  • dialplanrequired

    object | null · data.dialplan

  • idrequired

    string (uuid) · data.dialplan.id

  • namerequired

    string · data.dialplan.name

  • strategyOverriderequired

    string | null · data.strategyOverride

  • unroutedrequired

    boolean · data.unrouted

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.

Reveal a Switch customer trunk's SIP credentials

GET/api/v1/switch/customer-trunks/{trunkId}/credentials

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

Returns the current username and password without changing them. Every reveal is recorded in the audit log.

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • sipUsernamerequired

    string | null · data.sipUsername

  • sipPasswordrequired

    string | null · data.sipPassword

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 a trunk's credential history and last successful authentication

GET/api/v1/switch/customer-trunks/{trunkId}/credential-status

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

Everything about the credential except its value: username, storage, last change and reveal, and the last call identified with it.

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • trunkIdrequired

    string (uuid) · data.trunkId

  • trunkLabelrequired

    string · data.trunkLabel

  • customerIdrequired

    string (uuid) · data.customerId

  • customerLabelrequired

    string | null · data.customerLabel

  • usernamerequired

    string | null · data.username

  • passwordSetrequired

    boolean · data.passwordSet

  • storagerequired

    object · data.storage

  • sealedrequired

    boolean · data.storage.sealed

  • noterequired

    string · data.storage.note

  • createdAtrequired

    string (date-time) · data.createdAt

    ISO-8601 timestamp (UTC)

  • lastChange

    any · data.lastChange

  • lastReveal

    any · data.lastReveal

  • historyAvailablerequired

    boolean · data.historyAvailable

  • lastSuccessfulAuthrequired

    object | null · data.lastSuccessfulAuth

  • atrequired

    string · data.lastSuccessfulAuth.at

  • sourceIprequired

    string | null · data.lastSuccessfulAuth.sourceIp

  • sourceIsRegisteredrequired

    boolean · data.lastSuccessfulAuth.sourceIsRegistered

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.

Record that a trunk credential was copied

POST/api/v1/switch/customer-trunks/{trunkId}/credentials/copied

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

Writes an audit entry only. Call it when your interface copies a credential to the clipboard.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • field

    string

    default "sipPassword"One of sipPassword, sipUsername

Response 202

  • 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

Response 204

Recorded.

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

Replace a Switch customer trunk's SIP password

POST/api/v1/switch/customer-trunks/{trunkId}/sip-password

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

Generate one, or set one by hand with mode: "manual". The new password is returned ONCE and the old one stops working immediately (no overlap window).

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • mode

    string

    default "generate"One of generate, manual

  • password

    string

    Required when mode is manualmax 128 chars

Response 200

  • datarequired

    object

  • trunkIdrequired

    string (uuid) · data.trunkId

  • usernamerequired

    string | null · data.username

  • passwordrequired

    string · data.password

    The new password in plain text. Returned ONCE, here.

  • moderequired

    string · data.mode

    One of generate, manual

  • changedAtrequired

    string (date-time) · data.changedAt

    ISO-8601 timestamp (UTC)

  • overlapWindowrequired

    enum | null · data.overlapWindow

    There is no grace period: the old password stops working immediatelyOne of null

  • noterequired

    string · data.note

Response 202

  • 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

List trunk configuration changes awaiting or after review

GET/api/v1/switch/trunk-changes

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

Parameters

  • trunkId

    query · string (uuid)

  • status

    query · string

    Comma-separated statuses, e.g. pending,approved

Response 200

  • datarequired

    object[]

  • idrequired

    string (uuid) · data[].id

  • vendorTrunkIdrequired

    string (uuid) · data[].vendorTrunkId

  • trunkLabelrequired

    string | null · data[].trunkLabel

  • statusrequired

    string · data[].status

  • fieldsrequired

    string[] · data[].fields

  • changesrequired

    object[] · data[].changes

    Secret fields show "(secret)", never their value

  • fieldrequired

    string · data[].changes[].field

  • from

    any · data[].changes[].from

  • to

    any · data[].changes[].to

  • patchrequired

    object · data[].patch

  • beforeValuesrequired

    object · data[].beforeValues

  • noterequired

    string | null · data[].note

  • requestedByrequired

    string (uuid) · data[].requestedBy

  • requestedByEmailrequired

    string | null · data[].requestedByEmail

  • requestedAtrequired

    string (date-time) · data[].requestedAt

    ISO-8601 timestamp (UTC)

  • reviewedByrequired

    string (uuid) | null · data[].reviewedBy

  • reviewedAtrequired

    string (date-time) | null · data[].reviewedAt

    ISO-8601 timestamp (UTC)

  • reviewNoterequired

    string | null · data[].reviewNote

  • appliedAtrequired

    string (date-time) | null · data[].appliedAt

    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 and apply a trunk configuration change

POST/api/v1/switch/trunk-changes/{id}/approve

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

applied is the trunk after the change, redacted like every trunk read (sipAuthPasswordSet / smppPasswordSet instead of the secrets). driftedSinceRequest lists fields that changed on the trunk after the request was made.

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)

  • note

    string

Response 200

  • datarequired

    object

  • appliedrequired

    object · data.applied

  • driftedSinceRequestrequired

    string[] · data.driftedSinceRequest

Response 202

  • 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.

Reject a trunk configuration change

POST/api/v1/switch/trunk-changes/{id}/reject

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)

  • note

    string

Response 200

  • datarequired

    object

  • rejectedrequired

    boolean · data.rejected

    One of true

Response 202

  • 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.

Withdraw your own pending trunk change

POST/api/v1/switch/trunk-changes/{id}/withdraw

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

  • datarequired

    object

  • withdrawnrequired

    boolean · data.withdrawn

    One of true

Response 202

  • 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.

Get whether supplier trunk changes need approval

GET/api/v1/switch/trunk-approval-setting

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

Response 200

  • datarequired

    object

  • requireTrunkApprovalrequired

    boolean · data.requireTrunkApproval

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 supplier trunk change approval on or off

POST/api/v1/switch/trunk-approval-setting

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)

  • requireTrunkApprovalrequired

    boolean

Response 200

  • datarequired

    object

  • requireTrunkApprovalrequired

    boolean · data.requireTrunkApproval

Response 202

  • 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.

Get whether trunk readiness blocks first activation

GET/api/v1/switch/trunk-readiness-setting

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

Response 200

  • datarequired

    object

  • requireTrunkReadinessrequired

    boolean · data.requireTrunkReadiness

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 the trunk readiness gate on or off

POST/api/v1/switch/trunk-readiness-setting

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

When on, it can refuse only the first-ever activation of a new trunk; existing trunks are grandfathered and bundle trunks are exempt.

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)

  • requireTrunkReadinessrequired

    boolean

Response 200

  • datarequired

    object

  • requireTrunkReadinessrequired

    boolean · data.requireTrunkReadiness

Response 202

  • 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.

Get the sell deck in force on a trunk

GET/api/v1/switch/customer-trunks/{trunkId}/sell-deck

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

The resolved deck, plus the customer and system defaults it did not pick, and a sentence saying which won.

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • deckrequired

    object | null · data.deck

  • idrequired

    string (uuid) · data.deck.id

  • namerequired

    string · data.deck.name

  • versionrequired

    integer · data.deck.version

  • statusrequired

    string · data.deck.status

  • currencyrequired

    string · data.deck.currency

  • isSystemDefaultrequired

    boolean · data.deck.isSystemDefault

  • defaultRatePerUnitrequired

    number | null · data.deck.defaultRatePerUnit

    USD per minute for destinations the deck does not list; null = refuse them

  • chargingrequired

    object · data.deck.charging

  • moderequired

    string · data.mode

  • choicerequired

    string · data.choice

    Which rule won: the trunk, the customer default or the system default

  • bypassesCustomerDefaultrequired

    boolean · data.bypassesCustomerDefault

  • customerDefaultrequired

    object | null · data.customerDefault

    Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.

  • systemDefaultrequired

    object | null · data.systemDefault

    Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.

  • liveRowCountrequired

    integer · data.liveRowCount

  • explanationrequired

    string · data.explanation

  • problemrequired

    string | null · data.problem

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.

Assign a sell deck to a trunk

PUT/api/v1/switch/customer-trunks/{trunkId}/sell-deck

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

Without confirm: true nothing changes and the response shows what would be in force. With it, the trunk reprices from the next call.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • moderequired

    string

    How a trunk picks its sell deckOne of customer_default, system_default, deck, none

  • deckId

    string (uuid) | null

  • confirm

    boolean

  • reason

    string

Response 200

  • datarequired

    object

  • changed

    boolean · data.changed

    One of true

  • before

    object · data.before

    Same fields as SwitchTrunkEffectiveSellDeck, shown earlier on this page.

  • wouldBe

    object · data.wouldBe

  • moderequired

    string · data.wouldBe.mode

  • deckrequired

    object | null · data.wouldBe.deck

    Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.

  • rates

    any · data.wouldBe.rates

  • bypassesCustomerDefaultrequired

    boolean · data.wouldBe.bypassesCustomerDefault

  • warningrequired

    string | null · data.wouldBe.warning

  • defaultRaterequired

    number | null · data.wouldBe.defaultRate

  • unlistedDestinationsrequired

    string · data.wouldBe.unlistedDestinations

  • after

    object · data.after

    Same fields as SwitchTrunkEffectiveSellDeck, shown earlier on this page.

Response 202

  • 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

Preview a sell-deck assignment for a trunk

GET/api/v1/switch/customer-trunks/{trunkId}/sell-deck/preview

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

What would be in force under a mode, computed by the same resolver. Writes nothing.

Parameters

  • trunkIdrequired

    path · string (uuid)

  • mode

    query · string

    Default customer_defaultOne of customer_default, system_default, deck, none

  • deckId

    query · string (uuid)

Response 200

  • datarequired

    object

  • moderequired

    string · data.mode

  • deckrequired

    object | null · data.deck

    Same fields as SwitchCustomerSellDeckRef, shown earlier on this page.

  • rates

    any · data.rates

  • bypassesCustomerDefaultrequired

    boolean · data.bypassesCustomerDefault

  • warningrequired

    string | null · data.warning

  • defaultRaterequired

    number | null · data.defaultRate

  • unlistedDestinationsrequired

    string · data.unlistedDestinations

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.

List a trunk's sell rates with buy cost and margin

GET/api/v1/switch/customer-trunks/{trunkId}/rates

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

Parameters

  • trunkIdrequired

    path · string (uuid)

  • search

    query · string

    Prefix or destination text

  • limit

    query · integer

  • offset

    query · integer

  • view

    query · string

    Default currentOne of current, scheduled, discontinued, expiring, all

  • origin

    query · string

    One of any, origin_only, destination_only

  • increment

    query · string

    One of any, custom, inherited

  • cost

    query · string

    One of any, missing

  • margin

    query · string

    One of any, thin, negative

Response 200

  • datarequired

    object

  • rowsrequired

    object[] · data.rows

  • idrequired

    string (uuid) · data.rows[].id

  • subAccountIdrequired

    string (uuid) · data.rows[].subAccountId

  • customerTrunkIdrequired

    string (uuid) | null · data.rows[].customerTrunkId

  • prefixrequired

    string · data.rows[].prefix

  • originPrefixrequired

    string · data.rows[].originPrefix

    "" = any origin

  • ratePerUnitrequired

    money · data.rows[].ratePerUnit

    Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".

  • billingIncrementrequired

    string | null · data.rows[].billingIncrement

  • statusrequired

    string · data.rows[].status

    active, pending (scheduled) or discontinued

  • effectiveFromrequired

    string (date-time) · data.rows[].effectiveFrom

    ISO-8601 timestamp (UTC)

  • endDaterequired

    string (date-time) | null · data.rows[].endDate

    ISO-8601 timestamp (UTC)

  • buyCostrequired

    number | null · data.rows[].buyCost

    Best eligible buy cost per minute (USD number); null = no supplier prices it

  • marginPctrequired

    number | null · data.rows[].marginPct

  • thinrequired

    boolean · data.rows[].thin

  • negativerequired

    boolean · data.rows[].negative

  • costSupplierrequired

    string | null · data.rows[].costSupplier

  • costSourcerequired

    string · data.rows[].costSource

  • costMatchedPrefixrequired

    string | null · data.rows[].costMatchedPrefix

  • costNoterequired

    string | null · data.rows[].costNote

  • totalrequired

    integer · data.total

  • totalIsPageScopedrequired

    boolean · data.totalIsPageScoped

    True when a cost or margin filter narrowed the page, so total counts this page only

  • limitrequired

    integer · data.limit

  • offsetrequired

    integer · data.offset

  • viewrequired

    string · data.view

  • summaryrequired

    object · data.summary

  • prefixesrequired

    integer · data.summary.prefixes

  • blendedMarginPctrequired

    number | null · data.summary.blendedMarginPct

  • thinCountrequired

    integer · data.summary.thinCount

  • negativeCountrequired

    integer · data.summary.negativeCount

  • defaultRateCostCountrequired

    integer · data.summary.defaultRateCostCount

  • unpricedCountrequired

    integer · data.summary.unpricedCount

  • basis

    any · data.basis

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 or replace one sell rate on a trunk

POST/api/v1/switch/customer-trunks/{trunkId}/rates

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • prefixrequired

    string

    max 24 chars

  • raterequired

    number

    USD per minutemin 0

  • origin

    string

    max 24 chars

  • billingIncrement

    string

    max 10 chars

Response 201

  • datarequired

    object

  • idrequired

    string (uuid) · data.id

  • subAccountIdrequired

    string (uuid) · data.subAccountId

  • customerTrunkIdrequired

    string (uuid) | null · data.customerTrunkId

  • prefixrequired

    string · data.prefix

  • originPrefixrequired

    string · data.originPrefix

    "" = any origin

  • ratePerUnitrequired

    money · data.ratePerUnit

    Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".

  • billingIncrementrequired

    string | null · data.billingIncrement

  • statusrequired

    string · data.status

    active, pending (scheduled) or discontinued

  • effectiveFromrequired

    string (date-time) · data.effectiveFrom

    ISO-8601 timestamp (UTC)

  • endDaterequired

    string (date-time) | null · data.endDate

    ISO-8601 timestamp (UTC)

Response 202

  • 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

Count a trunk's sell rates by view

GET/api/v1/switch/customer-trunks/{trunkId}/rates/counts

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

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • currentrequired

    integer · data.current

  • scheduledrequired

    integer · data.scheduled

  • expiringrequired

    integer · data.expiring

  • discontinuedrequired

    integer · data.discontinued

  • allrequired

    integer · data.all

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.

List upcoming sell-rate starts and ends on a trunk

GET/api/v1/switch/customer-trunks/{trunkId}/rates/upcoming

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

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object[]

  • idrequired

    string (uuid) · data[].id

  • subAccountIdrequired

    string (uuid) · data[].subAccountId

  • customerTrunkIdrequired

    string (uuid) | null · data[].customerTrunkId

  • prefixrequired

    string · data[].prefix

  • originPrefixrequired

    string · data[].originPrefix

    "" = any origin

  • ratePerUnitrequired

    money · data[].ratePerUnit

    Sell price per minute, 6-decimal USD string USD as a decimal string with exactly 6 places, e.g. "0.012500".

  • billingIncrementrequired

    string | null · data[].billingIncrement

  • statusrequired

    string · data[].status

    active, pending (scheduled) or discontinued

  • effectiveFromrequired

    string (date-time) · data[].effectiveFrom

    ISO-8601 timestamp (UTC)

  • endDaterequired

    string (date-time) | null · data[].endDate

    ISO-8601 timestamp (UTC)

  • kindrequired

    string · data[].kind

    One of starts, ends

  • atrequired

    string (date-time) | null · data[].at

    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.
  • 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.

List sell-rate discontinuation events on a trunk

GET/api/v1/switch/customer-trunks/{trunkId}/rates/discontinuations

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

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object[]

  • revisionIdrequired

    string (uuid) | null · data[].revisionId

  • discontinuedAtrequired

    string (date-time) · data[].discontinuedAt

    ISO-8601 timestamp (UTC)

  • rowsrequired

    integer · data[].rows

  • labelrequired

    string · data[].label

  • effective

    any | null · data[].effective

  • timezonerequired

    string | null · data[].timezone

  • changeModerequired

    string | null · data[].changeMode

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.

Preview discontinuing a trunk's whole sell deck

POST/api/v1/switch/customer-trunks/{trunkId}/rates/discontinue-all/preview

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

Omit the effective fields to act now. Send either effectiveFrom (an instant with an offset) or effectiveLocal plus timezone; a bare date is refused because midnight differs by country.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • effectiveFrom

    string

    An instant with offset, e.g. "2026-10-01T00:00:00Z". A bare date is refused.max 40 chars

  • effectiveLocal

    string

    A wall-clock time, e.g. "2026-10-01T00:00"; requires timezonemax 30 chars

  • timezone

    string | null

    IANA zone, e.g. Europe/London; always recordedmax 64 chars

Response 200

  • datarequired

    object

  • customerLabelrequired

    string · data.customerLabel

  • activeRatesrequired

    integer · data.activeRates

  • scheduledRatesrequired

    integer · data.scheduledRates

  • alreadyDiscontinuedrequired

    integer · data.alreadyDiscontinued

  • endDaterequired

    string (date-time) · data.endDate

    ISO-8601 timestamp (UTC)

  • immediaterequired

    boolean · data.immediate

  • timezonerequired

    string | null · data.timezone

  • effectOnNewCallsrequired

    string · data.effectOnNewCalls

  • minutes30drequired

    number · data.minutes30d

  • calls30drequired

    integer · data.calls30d

  • revenue30drequired

    number · data.revenue30d

    US dollars as a JSON number (computed figure)

  • impactTruncatedrequired

    boolean · data.impactTruncated

  • samplerequired

    object[] · data.sample

  • prefixrequired

    string · data.sample[].prefix

  • originPrefixrequired

    string · data.sample[].originPrefix

  • ratePerUnitrequired

    money · data.sample[].ratePerUnit

    USD as a decimal string with exactly 6 places, e.g. "0.012500".

  • billingIncrementrequired

    string | null · data.sample[].billingIncrement

Response 202

  • 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

Discontinue a trunk's whole sell deck

POST/api/v1/switch/customer-trunks/{trunkId}/rates/discontinue-all

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

Nothing is deleted; priced calls keep their rate. Omit the effective fields to act now. Send either effectiveFrom (an instant with an offset) or effectiveLocal plus timezone; a bare date is refused because midnight differs by country.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • effectiveFrom

    string

    An instant with offset, e.g. "2026-10-01T00:00:00Z". A bare date is refused.max 40 chars

  • effectiveLocal

    string

    A wall-clock time, e.g. "2026-10-01T00:00"; requires timezonemax 30 chars

  • timezone

    string | null

    IANA zone, e.g. Europe/London; always recordedmax 64 chars

  • includeScheduled

    boolean

Response 200

  • datarequired

    object

  • endDaterequired

    string (date-time) · data.endDate

    ISO-8601 timestamp (UTC)

  • effective

    any · data.effective

    The moment described in words and in the recorded zone

  • revisionId

    string (uuid) | null · data.revisionId

  • discontinuedrequired

    integer · data.discontinued

  • deletedrequired

    integer · data.deleted

    Deprecated alias of discontinued; nothing is deleted

  • scheduledLeftrequired

    integer · data.scheduledLeft

Response 202

  • 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

Discontinue one sell rate on a trunk

POST/api/v1/switch/customer-trunks/{trunkId}/rates/{rateId}/discontinue

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

Omit the effective fields to act now. Send either effectiveFrom (an instant with an offset) or effectiveLocal plus timezone; a bare date is refused because midnight differs by country.

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

  • trunkIdrequired

    path · string (uuid)

  • rateIdrequired

    path · string (uuid)

Request body (application/json)

  • effectiveFrom

    string

    An instant with offset, e.g. "2026-10-01T00:00:00Z". A bare date is refused.max 40 chars

  • effectiveLocal

    string

    A wall-clock time, e.g. "2026-10-01T00:00"; requires timezonemax 30 chars

  • timezone

    string | null

    IANA zone, e.g. Europe/London; always recordedmax 64 chars

Response 200

  • datarequired

    object

  • endDaterequired

    string (date-time) · data.endDate

    ISO-8601 timestamp (UTC)

  • effective

    any · data.effective

    The moment described in words and in the recorded zone

  • revisionId

    string (uuid) | null · data.revisionId

  • discontinuedrequired

    boolean · data.discontinued

    One of true

  • deletedrequired

    boolean · data.deleted

    Deprecated alias; the rate is discontinued, not deletedOne of true

  • immediaterequired

    boolean · data.immediate

Response 202

  • 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

Add or replace many sell rates on a trunk

POST/api/v1/switch/customer-trunks/{trunkId}/rates/bulk

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • rowsrequired

    object[]

  • prefixrequired

    string · rows[].prefix

    max 24 chars

  • raterequired

    number · rows[].rate

    min 0

  • origin

    string · rows[].origin

    max 24 chars

  • billingIncrement

    string · rows[].billingIncrement

    max 10 chars

Response 200

  • datarequired

    object

  • appliedrequired

    integer · data.applied

  • revisionIdrequired

    string (uuid) | null · data.revisionId

Response 202

  • 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

Discontinue one sell rate on a trunk now

DELETE/api/v1/switch/customer-trunks/{trunkId}/rates/{rateId}

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

Kept for existing clients: the rate is discontinued immediately, not deleted.

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

  • trunkIdrequired

    path · string (uuid)

  • rateIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • endDaterequired

    string (date-time) · data.endDate

    ISO-8601 timestamp (UTC)

  • effective

    any · data.effective

    The moment described in words and in the recorded zone

  • revisionId

    string (uuid) | null · data.revisionId

  • discontinuedrequired

    boolean · data.discontinued

    One of true

  • deletedrequired

    boolean · data.deleted

    Deprecated alias; the rate is discontinued, not deletedOne of true

  • immediaterequired

    boolean · data.immediate

Response 202

  • 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

Discontinue every sell rate on a trunk now

POST/api/v1/switch/customer-trunks/{trunkId}/rates/clear

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

  • trunkIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • endDaterequired

    string (date-time) · data.endDate

    ISO-8601 timestamp (UTC)

  • effective

    any · data.effective

    The moment described in words and in the recorded zone

  • revisionId

    string (uuid) | null · data.revisionId

  • discontinuedrequired

    integer · data.discontinued

  • deletedrequired

    integer · data.deleted

    Deprecated alias of discontinued; nothing is deleted

  • scheduledLeftrequired

    integer · data.scheduledLeft

Response 202

  • 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

List scheduled (future-dated) sell rates on a trunk

GET/api/v1/switch/customer-trunks/{trunkId}/rates/scheduled

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

Parameters

  • trunkIdrequired

    path · string (uuid)

Response 200

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.

Schedule a future sell-rate change on a trunk

POST/api/v1/switch/customer-trunks/{trunkId}/rates/schedule

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

The rate becomes active at the effective moment. Omit the effective fields to act now. Send either effectiveFrom (an instant with an offset) or effectiveLocal plus timezone; a bare date is refused because midnight differs by country.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • effectiveFrom

    string

    An instant with offset, e.g. "2026-10-01T00:00:00Z". A bare date is refused.max 40 chars

  • effectiveLocal

    string

    A wall-clock time, e.g. "2026-10-01T00:00"; requires timezonemax 30 chars

  • timezone

    string | null

    IANA zone, e.g. Europe/London; always recordedmax 64 chars

  • prefixrequired

    string

    max 24 chars

  • raterequired

    number

    USD per minutemin 0

  • origin

    string

    max 24 chars

  • billingIncrement

    string

    max 10 chars

Response 201

Response 202

  • 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

Cancel a scheduled sell rate on a trunk

DELETE/api/v1/switch/customer-trunks/{trunkId}/rates/scheduled/{rateId}

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

  • trunkIdrequired

    path · string (uuid)

  • rateIdrequired

    path · string (uuid)

Response 200

  • datarequired

    object

  • cancelledrequired

    boolean · data.cancelled

    One of true

Response 202

  • 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

Reprice as a markup over buy cost from a trunk

POST/api/v1/switch/customer-trunks/{trunkId}/rates/apply-markup

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

Applies to the customer's deck; on a single-trunk customer that is this trunk's deck.

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

  • trunkIdrequired

    path · string (uuid)

Request body (application/json)

  • markupPctrequired

    number

    min -100

  • prefixes

    string[]

    Only these prefixes; omit for the whole deck

Response 200

  • datarequired

    object

  • updatedrequired

    integer · data.updated

  • skippedrequired

    integer · data.skipped

  • basis

    any · data.basis

  • revisionIdrequired

    string (uuid) | null · data.revisionId

Response 202

  • 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

Export a trunk's sell rates as CSV

GET/api/v1/switch/customer-trunks/{trunkId}/rates.csv

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

Scoped to this trunk's deck; takes the same filters as the list.

Parameters

  • trunkIdrequired

    path · string (uuid)

  • search

    query · string

    Prefix or destination text

  • view

    query · string

    Default currentOne of current, scheduled, discontinued, expiring, all

  • origin

    query · string

    One of any, origin_only, destination_only

  • increment

    query · string

    One of any, custom, inherited

  • cost

    query · string

    One of any, missing

  • margin

    query · string

    One of any, thin, negative

Response 200 (text/csv)

The trunk's filtered sell deck as a CSV 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.