Switch API reference

Switch: invoicing

Invoices, credit notes, payables, netting, settlement and ageing.

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

BrowseSwitch: invoicing

List customer invoices

GET/api/v1/switch/invoices

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

Parameters

customerId
query · string (uuid)
status
query · string
One of draft, open, partial, paid, overdue, void
limit
query · integer
Page size (default 50, max 500)
offset
query · integer

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string (uuid) · data.rows[].id
customerIdrequired
string (uuid) · data.rows[].customerId
invoiceNumberrequired
string · data.rows[].invoiceNumber
Sequential per operator, gap-free
periodStartrequired
string (date-time) | null · data.rows[].periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.rows[].periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) · data.rows[].issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.rows[].dueDate
ISO-8601 timestamp (UTC)
currencyrequired
string · data.rows[].currency
max 3 chars
subtotalrequired
money · data.rows[].subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
taxrequired
money · data.rows[].tax
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.rows[].total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
amountPaidrequired
money · data.rows[].amountPaid
USD as a decimal string with exactly 6 places, e.g. "0.012500".
statusrequired
string · data.rows[].status
One of draft, open, partial, paid, overdue, void
overduerequired
boolean · data.rows[].overdue
notesrequired
string | null · data.rows[].notes
replacesInvoiceId
string (uuid) | null · data.rows[].replacesInvoiceId
sentAt
string (date-time) | null · data.rows[].sentAt
ISO-8601 timestamp (UTC)
sendCount
integer · data.rows[].sendCount
customerLabel
string | null · data.rows[].customerLabel
On list rows
totalrequired
integer · data.total
limitrequired
integer · data.limit
offsetrequired
integer · data.offset

Errors

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

Issue an invoice from a reviewed preview

POST/api/v1/switch/invoices

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

Irreversible: allocates the next invoice number and claims the usage. Requires the reviewToken from a preview that still matches live data. Does not send the invoice; use POST /switch/invoices/{id}/send.

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

Request body (application/json)

FieldDescription

customerIdrequired
string (uuid)
periodStartrequired
string
ISO-8601 date or timestamp; start of the billing period
periodEndrequired
string
ISO-8601 date or timestamp; end of the billing period
notes
string | null
max 2000 chars
includeBroughtForward
boolean
Also bill priced, still-unbilled usage from before the period
applyCredits
boolean
Consume the customer's open credit notes on this invoice
excludeUnrated
object | null
Issue despite unpriced usage, leaving it unbilled for the stated reason (needs the billing adjustment permission)
reasonrequired
string · excludeUnrated.reason
max 2000 chars
reviewTokenrequired
string
max 120 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
customerIdrequired
string (uuid) · data.customerId
invoiceNumberrequired
string · data.invoiceNumber
Sequential per operator, gap-free
periodStartrequired
string (date-time) | null · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) · data.issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.dueDate
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
max 3 chars
subtotalrequired
money · data.subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
taxrequired
money · data.tax
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
amountPaidrequired
money · data.amountPaid
USD as a decimal string with exactly 6 places, e.g. "0.012500".
statusrequired
string · data.status
One of draft, open, partial, paid, overdue, void
overduerequired
boolean · data.overdue
notesrequired
string | null · data.notes
replacesInvoiceId
string (uuid) | null · data.replacesInvoiceId
sentAt
string (date-time) | null · data.sentAt
ISO-8601 timestamp (UTC)
sendCount
integer · data.sendCount
customerLabel
string | null · data.customerLabel
On list rows
reviewDigestrequired
string | null · data.reviewDigest
preview
object · data.preview
customerrequired
object · data.preview.customer
idrequired
string (uuid) · data.preview.customer.id
labelrequired
string · data.preview.customer.label
legalNamerequired
string · data.preview.customer.legalName
currencyrequired
string · data.preview.customer.currency
periodrequired
object · data.preview.period
startrequired
string · data.preview.period.start
endrequired
string · data.preview.period.end
timezonerequired
string · data.preview.period.timezone
labelrequired
string · data.preview.period.label
dueDaterequired
string · data.preview.dueDate
paymentTermsDaysrequired
integer · data.preview.paymentTermsDays
currencyrequired
string · data.preview.currency
usagerequired
object · data.preview.usage
Billable, rated-at-zero, by-trunk and by-channel usage
broughtForwardrequired
object · data.preview.broughtForward
unratedrequired
object · data.preview.unrated
Usage that could not be priced. Blocks issue unless excluded with a reason.
linesrequired
object[] · data.preview.lines
chargesrequired
number · data.preview.charges
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
creditsrequired
object · data.preview.credits
taxrequired
object · data.preview.tax
totalrequired
number · data.preview.total
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
provenancerequired
object · data.preview.provenance
reviewToken
string · data.preview.reviewToken
Pass to POST /switch/invoices to issue exactly what was reviewed

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/invoices" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "<customerId>",
  "periodStart": "<periodStart>",
  "periodEnd": "<periodEnd>",
  "reviewToken": "<reviewToken>"
}'

Run it here with a test key.

Preview an invoice before issuing it

POST/api/v1/switch/invoices/preview

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

A read: allocates no number and claims no usage. Returns every figure the invoice would carry, the usage it could not price, and a review token. Issue with that token; if live data changes in between, issuing fails with INVOICE_REVIEW_STALE.

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

Request body (application/json)

FieldDescription

customerIdrequired
string (uuid)
periodStartrequired
string
ISO-8601 date or timestamp; start of the billing period
periodEndrequired
string
ISO-8601 date or timestamp; end of the billing period
notes
string | null
max 2000 chars
includeBroughtForward
boolean
Also bill priced, still-unbilled usage from before the period
applyCredits
boolean
Consume the customer's open credit notes on this invoice
excludeUnrated
object | null
Issue despite unpriced usage, leaving it unbilled for the stated reason (needs the billing adjustment permission)
reasonrequired
string · excludeUnrated.reason
max 2000 chars
releaseInvoiceId
string (uuid) | null
Reissue only: review as if this invoice were already voided

Response 200

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/invoices/preview" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "<customerId>",
  "periodStart": "<periodStart>",
  "periodEnd": "<periodEnd>"
}'

Run it here with a test key.

Get an invoice with lines, payments and history

GET/api/v1/switch/invoices/{id}

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
customerIdrequired
string (uuid) · data.customerId
invoiceNumberrequired
string · data.invoiceNumber
Sequential per operator, gap-free
periodStartrequired
string (date-time) | null · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) · data.issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.dueDate
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
max 3 chars
subtotalrequired
money · data.subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
taxrequired
money · data.tax
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
amountPaidrequired
money · data.amountPaid
USD as a decimal string with exactly 6 places, e.g. "0.012500".
statusrequired
string · data.status
One of draft, open, partial, paid, overdue, void
overduerequired
boolean · data.overdue
notesrequired
string | null · data.notes
replacesInvoiceId
string (uuid) | null · data.replacesInvoiceId
sentAt
string (date-time) | null · data.sentAt
ISO-8601 timestamp (UTC)
sendCount
integer · data.sendCount
customerLabel
string | null · data.customerLabel
On list rows
linesrequired
object[] · data.lines
Invoice lines in print order
paymentsrequired
object[] · data.payments
idrequired
string (uuid) · data.payments[].id
amountrequired
money · data.payments[].amount
USD as a decimal string with exactly 6 places, e.g. "0.012500".
methodrequired
string | null · data.payments[].method
referencerequired
string | null · data.payments[].reference
paidAtrequired
string (date-time) · data.payments[].paidAt
ISO-8601 timestamp (UTC)
createdAtrequired
string (date-time) · data.payments[].createdAt
ISO-8601 timestamp (UTC)
customerrequired
object | null · data.customer
idrequired
string (uuid) · data.customer.id
labelrequired
string · data.customer.label
sourcerequired
string | null · data.customer.source
currencyrequired
string · data.customer.currency
countryBreakdownrequired
object · data.countryBreakdown
Voice usage on this invoice by destination country (derived, read-only)
billingProfilerequired
object | null · data.billingProfile
The billing identity frozen onto the document at issue
identityFrozenrequired
boolean · data.identityFrozen
exclusionsrequired
object[] · data.exclusions
Usage consciously left unbilled on this run, with the reason
replacesrequired
object | null · data.replaces
idrequired
string (uuid) · data.replaces.id
invoiceNumberrequired
string · data.replaces.invoiceNumber
statusrequired
string · data.replaces.status
One of draft, open, partial, paid, overdue, void
replacedByrequired
object | null · data.replacedBy
idrequired
string (uuid) · data.replacedBy.id
invoiceNumberrequired
string · data.replacedBy.invoiceNumber
statusrequired
string · data.replacedBy.status
One of draft, open, partial, paid, overdue, void

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 a payment received against an invoice

POST/api/v1/switch/invoices/{id}/payments

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

Updates amountPaid and the status (partial or paid). Overpayment is refused.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

amountrequired
number
Amount received, in the document currencymin 0
method
string | null
max 32 chars
reference
string | null
max 160 chars

Response 201

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/invoices/<id>/payments" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 1
}'

Run it here with a test key.

Void an invoice

POST/api/v1/switch/invoices/{id}/void

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

A correction, never an erasure: needs a reason, refuses an invoice that has payments against it (issue a credit note instead), and releases the usage it claimed so it can be billed again. Applied credit notes are returned to the 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

idrequired
path · string

Request body (application/json)

FieldDescription

reasonrequired
string
max 2000 chars

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
customerIdrequired
string (uuid) · data.customerId
invoiceNumberrequired
string · data.invoiceNumber
Sequential per operator, gap-free
periodStartrequired
string (date-time) | null · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) · data.issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.dueDate
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
max 3 chars
subtotalrequired
money · data.subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
taxrequired
money · data.tax
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
amountPaidrequired
money · data.amountPaid
USD as a decimal string with exactly 6 places, e.g. "0.012500".
statusrequired
string · data.status
One of draft, open, partial, paid, overdue, void
overduerequired
boolean · data.overdue
notesrequired
string | null · data.notes
replacesInvoiceId
string (uuid) | null · data.replacesInvoiceId
sentAt
string (date-time) | null · data.sentAt
ISO-8601 timestamp (UTC)
sendCount
integer · data.sendCount
customerLabel
string | null · data.customerLabel
On list rows
releasedCallsrequired
integer · data.releasedCalls
returnedCreditNotesrequired
integer · data.returnedCreditNotes

Response 202

FieldDescription

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

Errors

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

HTTP

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

Run it here with a test key.

Void an invoice and issue its replacement

POST/api/v1/switch/invoices/{id}/reissue

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

Voids this invoice and issues a replacement over the same period in one step. Preview the replacement first (with releaseInvoiceId) and pass its review token. If the void succeeds but the issue fails, the original stays void and its usage is unbilled; the error says so.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

reasonrequired
string
max 2000 chars
reviewTokenrequired
string
max 120 chars
notes
string | null
max 2000 chars
includeBroughtForward
boolean
applyCredits
boolean
excludeUnrated
object | null
reasonrequired
string · excludeUnrated.reason
max 2000 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
customerIdrequired
string (uuid) · data.customerId
invoiceNumberrequired
string · data.invoiceNumber
Sequential per operator, gap-free
periodStartrequired
string (date-time) | null · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) · data.issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.dueDate
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
max 3 chars
subtotalrequired
money · data.subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
taxrequired
money · data.tax
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
amountPaidrequired
money · data.amountPaid
USD as a decimal string with exactly 6 places, e.g. "0.012500".
statusrequired
string · data.status
One of draft, open, partial, paid, overdue, void
overduerequired
boolean · data.overdue
notesrequired
string | null · data.notes
replacesInvoiceId
string (uuid) | null · data.replacesInvoiceId
sentAt
string (date-time) | null · data.sentAt
ISO-8601 timestamp (UTC)
sendCount
integer · data.sendCount
customerLabel
string | null · data.customerLabel
On list rows
replacesInvoiceNumberrequired
string · data.replacesInvoiceNumber

Response 202

FieldDescription

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

Errors

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

HTTP

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

Run it here with a test key.

Email an invoice to its recipients

POST/api/v1/switch/invoices/{id}/send

Access: API key. Scoped keys need switch:manage.
Rate limit: 60 requests per 10 minutes
Sends email: Emails the invoice to its recipients.

Safe to repeat. Sends to the billing contacts, or to up to 20 addresses in to. Only accepted sends count as delivered.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

to
string (email)[]

Response 200

FieldDescription

datarequired
object
sentrequired
boolean · data.sent
torequired
string[] · data.to
Addresses the mail transport accepted
failedrequired
any[] · data.failed
Addresses that could not be sent to
sendCountrequired
integer · data.sendCount
sentAtrequired
string (date-time) | null · data.sentAt
ISO-8601 timestamp (UTC)

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/invoices/<id>/send" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "you@example.com"
  ]
}'

Run it here with a test key.

Render an invoice as printable HTML

GET/api/v1/switch/invoices/{id}/print

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

Parameters

idrequired
path · string

Response 200 (text/html)

The invoice as a standalone HTML document.

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.

Download an invoice as XML

GET/api/v1/switch/invoices/{id}/xml

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

Parameters

idrequired
path · string

Response 200 (application/xml)

The invoice as a structured XML document.

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.

Download an invoice as PDF

GET/api/v1/switch/invoices/{id}/pdf

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

Parameters

idrequired
path · string

Response 200 (application/pdf)

The invoice PDF, as an attachment.

Errors

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

List credit notes

GET/api/v1/switch/credit-notes

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

Parameters

customerId
query · string (uuid)
limit
query · integer
Page size (default 50, max 500)
offset
query · integer

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
customerIdrequired
string (uuid) · data[].customerId
creditNoteNumberrequired
string · data[].creditNoteNumber
invoiceIdrequired
string (uuid) | null · data[].invoiceId
amountrequired
money · data[].amount
USD as a decimal string with exactly 6 places, e.g. "0.012500".
reasonrequired
string | null · data[].reason
statusrequired
string · data[].status
issued (open credit) or applied
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
customerLabel
string | null · data[].customerLabel

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.

Issue a credit note to a customer

POST/api/v1/switch/credit-notes

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

Open credit reduces net receivables and can be applied to a later invoice with applyCredits. invoiceId, when given, must belong to 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.

Request body (application/json)

FieldDescription

customerIdrequired
string (uuid)
amountrequired
number
min 0
reason
string | null
max 2000 chars
invoiceId
string (uuid) | null

Response 201

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/credit-notes" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "<customerId>",
  "amount": 1
}'

Run it here with a test key.

Get accounts-receivable ageing

GET/api/v1/switch/ar-aging

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

Outstanding customer invoice balances by days past due. totalOutstanding is net of open credit notes; the buckets are gross.

Response 200

FieldDescription

datarequired
object
totalOutstandingrequired
number · data.totalOutstanding
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
grossOutstandingrequired
number · data.grossOutstanding
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
creditNotesOpenrequired
number · data.creditNotesOpen
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
openCountrequired
integer · data.openCount
bucketsrequired
object · data.buckets
currentrequired
number · data.buckets.current
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
d1_30required
number · data.buckets.d1_30
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
d31_60required
number · data.buckets.d31_60
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
d61_90required
number · data.buckets.d61_90
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
d90plusrequired
number · data.buckets.d90plus
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)

Errors

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

List supplier payables

GET/api/v1/switch/payables

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

Parameters

vendorTrunkId
query · string (uuid)
status
query · string
One of draft, open, partial, paid, overdue, void
limit
query · integer
Page size (default 50, max 500)
offset
query · integer

Response 200

FieldDescription

datarequired
object
rowsrequired
object[] · data.rows
idrequired
string (uuid) · data.rows[].id
vendorTrunkIdrequired
string (uuid) · data.rows[].vendorTrunkId
payableNumberrequired
string · data.rows[].payableNumber
periodStartrequired
string (date-time) | null · data.rows[].periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.rows[].periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) · data.rows[].issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.rows[].dueDate
ISO-8601 timestamp (UTC)
currencyrequired
string · data.rows[].currency
max 3 chars
subtotalrequired
money · data.rows[].subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.rows[].total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
amountPaidrequired
money · data.rows[].amountPaid
USD as a decimal string with exactly 6 places, e.g. "0.012500".
statusrequired
string · data.rows[].status
One of draft, open, partial, paid, overdue, void
notesrequired
string | null · data.rows[].notes
overdue
boolean · data.rows[].overdue
trunkLabel
string | null · data.rows[].trunkLabel
On list rows
createdAtrequired
string (date-time) · data.rows[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.rows[].updatedAt
ISO-8601 timestamp (UTC)
totalrequired
integer · data.total
limitrequired
integer · data.limit

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.

Raise a payable for a supplier trunk over a period

POST/api/v1/switch/payables

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

Totals the supplier cost of the usage on that trunk in the period and claims it, so it cannot be paid twice.

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

Request body (application/json)

FieldDescription

vendorTrunkIdrequired
string (uuid)
periodStartrequired
string
ISO-8601 date or timestamp; start of the billing period
periodEndrequired
string
ISO-8601 date or timestamp; end of the billing period
notes
string | null
max 2000 chars

Response 201

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/payables" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "vendorTrunkId": "<vendorTrunkId>",
  "periodStart": "<periodStart>",
  "periodEnd": "<periodEnd>"
}'

Run it here with a test key.

Get a payable with lines and payments

GET/api/v1/switch/payables/{id}

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
vendorTrunkIdrequired
string (uuid) · data.vendorTrunkId
payableNumberrequired
string · data.payableNumber
periodStartrequired
string (date-time) | null · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) · data.issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.dueDate
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
max 3 chars
subtotalrequired
money · data.subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
amountPaidrequired
money · data.amountPaid
USD as a decimal string with exactly 6 places, e.g. "0.012500".
statusrequired
string · data.status
One of draft, open, partial, paid, overdue, void
notesrequired
string | null · data.notes
overdue
boolean · data.overdue
trunkLabel
string | null · data.trunkLabel
On list rows
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
linesrequired
object[] · data.lines
paymentsrequired
object[] · data.payments
Same fields as SwitchPayment, shown earlier on this page.
trunkrequired
object | null · data.trunk
idrequired
string (uuid) · data.trunk.id
labelrequired
string · data.trunk.label
settlementModerequired
string | null · data.trunk.settlementMode

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 a payment made to a supplier

POST/api/v1/switch/payables/{id}/payments

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

Payments larger than the outstanding balance, or against a void payable, are refused.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

amountrequired
number
Amount received, in the document currencymin 0
method
string | null
max 32 chars
reference
string | null
max 160 chars

Response 201

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/payables/<id>/payments" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 1
}'

Run it here with a test key.

Void a payable

POST/api/v1/switch/payables/{id}/void

Access: API key. Scoped keys need switch:manage.
Rate limit: 100 requests per second (the default)
Moves money: Issues, voids or settles a billing document.

Releases the usage it claimed so a corrected payable can pick it up. Voiding an already void payable is a no-op.

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
vendorTrunkIdrequired
string (uuid) · data.vendorTrunkId
payableNumberrequired
string · data.payableNumber
periodStartrequired
string (date-time) | null · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.periodEnd
ISO-8601 timestamp (UTC)
issueDaterequired
string (date-time) · data.issueDate
ISO-8601 timestamp (UTC)
dueDaterequired
string (date-time) | null · data.dueDate
ISO-8601 timestamp (UTC)
currencyrequired
string · data.currency
max 3 chars
subtotalrequired
money · data.subtotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
totalrequired
money · data.total
USD as a decimal string with exactly 6 places, e.g. "0.012500".
amountPaidrequired
money · data.amountPaid
USD as a decimal string with exactly 6 places, e.g. "0.012500".
statusrequired
string · data.status
One of draft, open, partial, paid, overdue, void
notesrequired
string | null · data.notes
overdue
boolean · data.overdue
trunkLabel
string | null · data.trunkLabel
On list rows
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data.updatedAt
ISO-8601 timestamp (UTC)
releasedCallsrequired
integer · data.releasedCalls

Response 202

FieldDescription

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

Errors

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

Get accounts-payable ageing

GET/api/v1/switch/ap-aging

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

What you owe suppliers on open payables, by days past due.

Response 200

FieldDescription

datarequired
object
totalOwedrequired
number · data.totalOwed
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
openCountrequired
integer · data.openCount
bucketsrequired
object · data.buckets
currentrequired
number · data.buckets.current
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
d1_30required
number · data.buckets.d1_30
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
d31_60required
number · data.buckets.d31_60
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
d61_90required
number · data.buckets.d61_90
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
d90plusrequired
number · data.buckets.d90plus
US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)

Errors

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

List bilateral counterparties

GET/api/v1/switch/counterparties

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

A counterparty pairs a customer you sell to with a supplier trunk you buy from, so the two balances can be netted.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
namerequired
string · data[].name
customerIdrequired
string (uuid) | null · data[].customerId
The customer side of this counterparty
vendorTrunkIdrequired
string (uuid) | null · data[].vendorTrunkId
The supplier side of this counterparty
currencyrequired
string · data[].currency
nettingEnabledrequired
boolean · data[].nettingEnabled
notesrequired
string | null · data[].notes
customerLabel
string | null · data[].customerLabel
trunkLabel
string | null · data[].trunkLabel
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data[].updatedAt
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.

Create a bilateral counterparty

POST/api/v1/switch/counterparties

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

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

Request body (application/json)

FieldDescription

namerequired
string
max 160 chars
customerId
string (uuid) | null
vendorTrunkId
string (uuid) | null
currency
string | null
max 3 chars
nettingEnabled
boolean
notes
string | null
max 2000 chars

Response 201

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

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

Run it here with a test key.

Update a bilateral counterparty

PATCH/api/v1/switch/counterparties/{id}

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

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

name
string
max 160 chars
customerId
string (uuid) | null
vendorTrunkId
string (uuid) | null
currency
string | null
max 3 chars
nettingEnabled
boolean
notes
string | null
max 2000 chars

Response 200

FieldDescription

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

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X PATCH "https://packetexchange.io/api/v1/switch/counterparties/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme",
  "customerId": "<customerId>"
}'

Run it here with a test key.

Delete a bilateral counterparty

DELETE/api/v1/switch/counterparties/{id}

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

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

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
deletedrequired
boolean · data.deleted
One of true

Response 202

FieldDescription

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

Errors

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

Run netting for a counterparty over a period

POST/api/v1/switch/counterparties/{id}/netting

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

Open receivables (less issued credit notes) minus open payables in the period give one net figure and direction. The run is recorded as final and fires the netting.run webhook; the money itself moves off-platform.

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

periodStartrequired
string
ISO date or datetime
periodEndrequired
string
ISO date or datetime (exclusive)
notes
string | null
max 2000 chars

Response 201

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
counterpartyIdrequired
string (uuid) · data.counterpartyId
counterpartyNamerequired
string · data.counterpartyName
periodStartrequired
string (date-time) | null · data.periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data.periodEnd
ISO-8601 timestamp (UTC)
arTotalrequired
money · data.arTotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
apTotalrequired
money · data.apTotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
netAmountrequired
money · data.netAmount
Absolute net amount; see direction USD as a decimal string with exactly 6 places, e.g. "0.012500".
directionrequired
string · data.direction
One of receivable, payable, settled
statusrequired
string · data.status
notesrequired
string | null · data.notes
createdAtrequired
string (date-time) · data.createdAt
ISO-8601 timestamp (UTC)

Response 202

FieldDescription

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/counterparties/<id>/netting" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "periodStart": "<periodStart>",
  "periodEnd": "<periodEnd>"
}'

Run it here with a test key.

List netting runs

GET/api/v1/switch/netting-runs

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

Settlements that offset what a bilateral counterparty owes you against what you owe them (latest 200).

Parameters

counterpartyId
query · string (uuid)

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
counterpartyIdrequired
string (uuid) · data[].counterpartyId
counterpartyNamerequired
string | null · data[].counterpartyName
periodStartrequired
string (date-time) | null · data[].periodStart
ISO-8601 timestamp (UTC)
periodEndrequired
string (date-time) | null · data[].periodEnd
ISO-8601 timestamp (UTC)
arTotalrequired
money · data[].arTotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
apTotalrequired
money · data[].apTotal
USD as a decimal string with exactly 6 places, e.g. "0.012500".
netAmountrequired
money · data[].netAmount
USD as a decimal string with exactly 6 places, e.g. "0.012500".
directionrequired
string · data[].direction
statusrequired
string · data[].status
notesrequired
string | null · data[].notes
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)

Errors

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