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

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

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string (uuid)	-
`customerId`requireddata.rows[].customerId	string (uuid)	-
`invoiceNumber`requireddata.rows[].invoiceNumber	string	Sequential per operator, gap-free
`periodStart`requireddata.rows[].periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.rows[].periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`issueDate`requireddata.rows[].issueDate	string (date-time)	ISO-8601 timestamp (UTC)
`dueDate`requireddata.rows[].dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.rows[].currency	string	-max 3 chars
`subtotal`requireddata.rows[].subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`tax`requireddata.rows[].tax	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.rows[].total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`amountPaid`requireddata.rows[].amountPaid	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.rows[].status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`overdue`requireddata.rows[].overdue	boolean	-
`notes`requireddata.rows[].notes	string \| null	-
`replacesInvoiceId`data.rows[].replacesInvoiceId	string (uuid) \| null	-
`sentAt`data.rows[].sentAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`sendCount`data.rows[].sendCount	integer	-
`customerLabel`data.rows[].customerLabel	string \| null	On list rows
`total`requireddata.total	integer	-
`limit`requireddata.limit	integer	-
`offset`requireddata.offset	integer	-

Errors

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

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)

Field	Type	Description
`customerId`required	string (uuid)	-
`periodStart`required	string	ISO-8601 date or timestamp; start of the billing period
`periodEnd`required	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)
`reason`requiredexcludeUnrated.reason	string	-max 2000 chars
`reviewToken`required	string	-max 120 chars

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`customerId`requireddata.customerId	string (uuid)	-
`invoiceNumber`requireddata.invoiceNumber	string	Sequential per operator, gap-free
`periodStart`requireddata.periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`issueDate`requireddata.issueDate	string (date-time)	ISO-8601 timestamp (UTC)
`dueDate`requireddata.dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-max 3 chars
`subtotal`requireddata.subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`tax`requireddata.tax	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`amountPaid`requireddata.amountPaid	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`overdue`requireddata.overdue	boolean	-
`notes`requireddata.notes	string \| null	-
`replacesInvoiceId`data.replacesInvoiceId	string (uuid) \| null	-
`sentAt`data.sentAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`sendCount`data.sendCount	integer	-
`customerLabel`data.customerLabel	string \| null	On list rows
`reviewDigest`requireddata.reviewDigest	string \| null	-
`preview`data.preview	object	-
`customer`requireddata.preview.customer	object	-
`id`requireddata.preview.customer.id	string (uuid)	-
`label`requireddata.preview.customer.label	string	-
`legalName`requireddata.preview.customer.legalName	string	-
`currency`requireddata.preview.customer.currency	string	-
`period`requireddata.preview.period	object	-
`start`requireddata.preview.period.start	string	-
`end`requireddata.preview.period.end	string	-
`timezone`requireddata.preview.period.timezone	string	-
`label`requireddata.preview.period.label	string	-
`dueDate`requireddata.preview.dueDate	string	-
`paymentTermsDays`requireddata.preview.paymentTermsDays	integer	-
`currency`requireddata.preview.currency	string	-
`usage`requireddata.preview.usage	object	Billable, rated-at-zero, by-trunk and by-channel usage
`broughtForward`requireddata.preview.broughtForward	object	-
`unrated`requireddata.preview.unrated	object	Usage that could not be priced. Blocks issue unless excluded with a reason.
`lines`requireddata.preview.lines	object[]	-
`charges`requireddata.preview.charges	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`credits`requireddata.preview.credits	object	-
`tax`requireddata.preview.tax	object	-
`total`requireddata.preview.total	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`provenance`requireddata.preview.provenance	object	-
`reviewToken`data.preview.reviewToken	string	Pass to POST /switch/invoices to issue exactly what was reviewed

Response 202

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

Errors

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

Field	Type	Description
`customerId`required	string (uuid)	-
`periodStart`required	string	ISO-8601 date or timestamp; start of the billing period
`periodEnd`required	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)
`reason`requiredexcludeUnrated.reason	string	-max 2000 chars
`releaseInvoiceId`	string (uuid) \| null	Reissue only: review as if this invoice were already voided

Response 200

Field	Type	Description
`data`required	object	Same fields as SwitchInvoicePreview, shown earlier on this page.

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`customerId`requireddata.customerId	string (uuid)	-
`invoiceNumber`requireddata.invoiceNumber	string	Sequential per operator, gap-free
`periodStart`requireddata.periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`issueDate`requireddata.issueDate	string (date-time)	ISO-8601 timestamp (UTC)
`dueDate`requireddata.dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-max 3 chars
`subtotal`requireddata.subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`tax`requireddata.tax	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`amountPaid`requireddata.amountPaid	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`overdue`requireddata.overdue	boolean	-
`notes`requireddata.notes	string \| null	-
`replacesInvoiceId`data.replacesInvoiceId	string (uuid) \| null	-
`sentAt`data.sentAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`sendCount`data.sendCount	integer	-
`customerLabel`data.customerLabel	string \| null	On list rows
`lines`requireddata.lines	object[]	Invoice lines in print order
`payments`requireddata.payments	object[]	-
`id`requireddata.payments[].id	string (uuid)	-
`amount`requireddata.payments[].amount	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`method`requireddata.payments[].method	string \| null	-
`reference`requireddata.payments[].reference	string \| null	-
`paidAt`requireddata.payments[].paidAt	string (date-time)	ISO-8601 timestamp (UTC)
`createdAt`requireddata.payments[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`customer`requireddata.customer	object \| null	-
`id`requireddata.customer.id	string (uuid)	-
`label`requireddata.customer.label	string	-
`source`requireddata.customer.source	string \| null	-
`currency`requireddata.customer.currency	string	-
`countryBreakdown`requireddata.countryBreakdown	object	Voice usage on this invoice by destination country (derived, read-only)
`billingProfile`requireddata.billingProfile	object \| null	The billing identity frozen onto the document at issue
`identityFrozen`requireddata.identityFrozen	boolean	-
`exclusions`requireddata.exclusions	object[]	Usage consciously left unbilled on this run, with the reason
`replaces`requireddata.replaces	object \| null	-
`id`requireddata.replaces.id	string (uuid)	-
`invoiceNumber`requireddata.replaces.invoiceNumber	string	-
`status`requireddata.replaces.status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`replacedBy`requireddata.replacedBy	object \| null	-
`id`requireddata.replacedBy.id	string (uuid)	-
`invoiceNumber`requireddata.replacedBy.invoiceNumber	string	-
`status`requireddata.replacedBy.status	string	-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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`amount`required	number	Amount received, in the document currencymin 0
`method`	string \| null	-max 32 chars
`reference`	string \| null	-max 160 chars

Response 201

Field	Type	Description
`data`required	object	Same fields as SwitchInvoice, shown earlier on this page.

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`reason`required	string	-max 2000 chars

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`customerId`requireddata.customerId	string (uuid)	-
`invoiceNumber`requireddata.invoiceNumber	string	Sequential per operator, gap-free
`periodStart`requireddata.periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`issueDate`requireddata.issueDate	string (date-time)	ISO-8601 timestamp (UTC)
`dueDate`requireddata.dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-max 3 chars
`subtotal`requireddata.subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`tax`requireddata.tax	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`amountPaid`requireddata.amountPaid	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`overdue`requireddata.overdue	boolean	-
`notes`requireddata.notes	string \| null	-
`replacesInvoiceId`data.replacesInvoiceId	string (uuid) \| null	-
`sentAt`data.sentAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`sendCount`data.sendCount	integer	-
`customerLabel`data.customerLabel	string \| null	On list rows
`releasedCalls`requireddata.releasedCalls	integer	-
`returnedCreditNotes`requireddata.returnedCreditNotes	integer	-

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`reason`required	string	-max 2000 chars
`reviewToken`required	string	-max 120 chars
`notes`	string \| null	-max 2000 chars
`includeBroughtForward`	boolean	-
`applyCredits`	boolean	-
`excludeUnrated`	object \| null	-
`reason`requiredexcludeUnrated.reason	string	-max 2000 chars

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`customerId`requireddata.customerId	string (uuid)	-
`invoiceNumber`requireddata.invoiceNumber	string	Sequential per operator, gap-free
`periodStart`requireddata.periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`issueDate`requireddata.issueDate	string (date-time)	ISO-8601 timestamp (UTC)
`dueDate`requireddata.dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-max 3 chars
`subtotal`requireddata.subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`tax`requireddata.tax	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`amountPaid`requireddata.amountPaid	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`overdue`requireddata.overdue	boolean	-
`notes`requireddata.notes	string \| null	-
`replacesInvoiceId`data.replacesInvoiceId	string (uuid) \| null	-
`sentAt`data.sentAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`sendCount`data.sendCount	integer	-
`customerLabel`data.customerLabel	string \| null	On list rows
`replacesInvoiceNumber`requireddata.replacesInvoiceNumber	string	-

Response 202

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

Errors

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`to`	string (email)[]	-

Response 200

Field	Type	Description
`data`required	object	-
`sent`requireddata.sent	boolean	-
`to`requireddata.to	string[]	Addresses the mail transport accepted
`failed`requireddata.failed	any[]	Addresses that could not be sent to
`sendCount`requireddata.sendCount	integer	-
`sentAt`requireddata.sentAt	string (date-time) \| null	ISO-8601 timestamp (UTC)

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

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

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

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

Name	In	Type	Description
`customerId`	query	string (uuid)	-
`limit`	query	integer	Page size (default 50, max 500)
`offset`	query	integer	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`customerId`requireddata[].customerId	string (uuid)	-
`creditNoteNumber`requireddata[].creditNoteNumber	string	-
`invoiceId`requireddata[].invoiceId	string (uuid) \| null	-
`amount`requireddata[].amount	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`reason`requireddata[].reason	string \| null	-
`status`requireddata[].status	string	issued (open credit) or applied
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`customerLabel`data[].customerLabel	string \| null	-

Errors

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

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)

Field	Type	Description
`customerId`required	string (uuid)	-
`amount`required	number	-min 0
`reason`	string \| null	-max 2000 chars
`invoiceId`	string (uuid) \| null	-

Response 201

Field	Type	Description
`data`required	object	Same fields as SwitchCreditNote, shown earlier on this page.

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Field	Type	Description
`data`required	object	-
`totalOutstanding`requireddata.totalOutstanding	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`grossOutstanding`requireddata.grossOutstanding	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`creditNotesOpen`requireddata.creditNotesOpen	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`openCount`requireddata.openCount	integer	-
`buckets`requireddata.buckets	object	-
`current`requireddata.buckets.current	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`d1_30`requireddata.buckets.d1_30	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`d31_60`requireddata.buckets.d31_60	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`d61_90`requireddata.buckets.d61_90	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`d90plus`requireddata.buckets.d90plus	number	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

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

Field	Type	Description
`data`required	object	-
`rows`requireddata.rows	object[]	-
`id`requireddata.rows[].id	string (uuid)	-
`vendorTrunkId`requireddata.rows[].vendorTrunkId	string (uuid)	-
`payableNumber`requireddata.rows[].payableNumber	string	-
`periodStart`requireddata.rows[].periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.rows[].periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`issueDate`requireddata.rows[].issueDate	string (date-time)	ISO-8601 timestamp (UTC)
`dueDate`requireddata.rows[].dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.rows[].currency	string	-max 3 chars
`subtotal`requireddata.rows[].subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.rows[].total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`amountPaid`requireddata.rows[].amountPaid	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.rows[].status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`notes`requireddata.rows[].notes	string \| null	-
`overdue`data.rows[].overdue	boolean	-
`trunkLabel`data.rows[].trunkLabel	string \| null	On list rows
`createdAt`requireddata.rows[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.rows[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`total`requireddata.total	integer	-
`limit`requireddata.limit	integer	-

Errors

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

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)

Field	Type	Description
`vendorTrunkId`required	string (uuid)	-
`periodStart`required	string	ISO-8601 date or timestamp; start of the billing period
`periodEnd`required	string	ISO-8601 date or timestamp; end of the billing period
`notes`	string \| null	-max 2000 chars

Response 201

Field	Type	Description
`data`required	object	Same fields as SwitchPayable, shown earlier on this page.

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`vendorTrunkId`requireddata.vendorTrunkId	string (uuid)	-
`payableNumber`requireddata.payableNumber	string	-
`periodStart`requireddata.periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`issueDate`requireddata.issueDate	string (date-time)	ISO-8601 timestamp (UTC)
`dueDate`requireddata.dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-max 3 chars
`subtotal`requireddata.subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`amountPaid`requireddata.amountPaid	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`notes`requireddata.notes	string \| null	-
`overdue`data.overdue	boolean	-
`trunkLabel`data.trunkLabel	string \| null	On list rows
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`lines`requireddata.lines	object[]	-
`payments`requireddata.payments	object[]	Same fields as SwitchPayment, shown earlier on this page.
`trunk`requireddata.trunk	object \| null	-
`id`requireddata.trunk.id	string (uuid)	-
`label`requireddata.trunk.label	string	-
`settlementMode`requireddata.trunk.settlementMode	string \| null	-

Errors

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`amount`required	number	Amount received, in the document currencymin 0
`method`	string \| null	-max 32 chars
`reference`	string \| null	-max 160 chars

Response 201

Field	Type	Description
`data`required	object	Same fields as SwitchPayable, shown earlier on this page.

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`vendorTrunkId`requireddata.vendorTrunkId	string (uuid)	-
`payableNumber`requireddata.payableNumber	string	-
`periodStart`requireddata.periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`issueDate`requireddata.issueDate	string (date-time)	ISO-8601 timestamp (UTC)
`dueDate`requireddata.dueDate	string (date-time) \| null	ISO-8601 timestamp (UTC)
`currency`requireddata.currency	string	-max 3 chars
`subtotal`requireddata.subtotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`total`requireddata.total	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`amountPaid`requireddata.amountPaid	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.status	string	-One of `draft`, `open`, `partial`, `paid`, `overdue`, `void`
`notes`requireddata.notes	string \| null	-
`overdue`data.overdue	boolean	-
`trunkLabel`data.trunkLabel	string \| null	On list rows
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`releasedCalls`requireddata.releasedCalls	integer	-

Response 202

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

Errors

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

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

Field	Type	Description
`data`required	object	-
`totalOwed`requireddata.totalOwed	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`openCount`requireddata.openCount	integer	-
`buckets`requireddata.buckets	object	-
`current`requireddata.buckets.current	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`d1_30`requireddata.buckets.d1_30	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`d31_60`requireddata.buckets.d31_60	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`d61_90`requireddata.buckets.d61_90	number	US dollars as a JSON number rounded to 6 decimals (a computed figure, not a ledger string)
`d90plus`requireddata.buckets.d90plus	number	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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`name`requireddata[].name	string	-
`customerId`requireddata[].customerId	string (uuid) \| null	The customer side of this counterparty
`vendorTrunkId`requireddata[].vendorTrunkId	string (uuid) \| null	The supplier side of this counterparty
`currency`requireddata[].currency	string	-
`nettingEnabled`requireddata[].nettingEnabled	boolean	-
`notes`requireddata[].notes	string \| null	-
`customerLabel`data[].customerLabel	string \| null	-
`trunkLabel`data[].trunkLabel	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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

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)

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

Field	Type	Description
`data`required	object	Same fields as SwitchCounterparty, shown earlier on this page.

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

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

Field	Type	Description
`data`required	object	Same fields as SwitchCounterparty, shown earlier on this page.

Response 202

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

Errors

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

HTTP

curl -X PATCH "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`deleted`requireddata.deleted	boolean	-One of `true`

Response 202

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

Errors

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

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`periodStart`required	string	ISO date or datetime
`periodEnd`required	string	ISO date or datetime (exclusive)
`notes`	string \| null	-max 2000 chars

Response 201

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`counterpartyId`requireddata.counterpartyId	string (uuid)	-
`counterpartyName`requireddata.counterpartyName	string	-
`periodStart`requireddata.periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata.periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`arTotal`requireddata.arTotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`apTotal`requireddata.apTotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`netAmount`requireddata.netAmount	money	Absolute net amount; see direction USD as a decimal string with exactly 6 places, e.g. "0.012500".
`direction`requireddata.direction	string	-One of `receivable`, `payable`, `settled`
`status`requireddata.status	string	-
`notes`requireddata.notes	string \| null	-
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Response 202

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

Errors

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

HTTP

curl -X POST "https://packetexchange.io/api/v1/switch/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

Name	In	Type	Description
`counterpartyId`	query	string (uuid)	-

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`counterpartyId`requireddata[].counterpartyId	string (uuid)	-
`counterpartyName`requireddata[].counterpartyName	string \| null	-
`periodStart`requireddata[].periodStart	string (date-time) \| null	ISO-8601 timestamp (UTC)
`periodEnd`requireddata[].periodEnd	string (date-time) \| null	ISO-8601 timestamp (UTC)
`arTotal`requireddata[].arTotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`apTotal`requireddata[].apTotal	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`netAmount`requireddata[].netAmount	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`direction`requireddata[].direction	string	-
`status`requireddata[].status	string	-
`notes`requireddata[].notes	string \| null	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)

Errors

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