Switch API - PacketExchange

01 / Authentication

One operator token, two portal rails

All operator endpoints live under /api/v1/switch and require your operator bearer token in the Authorization header. Self-service portals are separate, magic-link-authenticated rails.

Operator API: Authorization: Bearer <operator_api_key> under /api/v1/switch.
Customer portal: /api/v1/sub-portal - the auth/* endpoints are public (magic-link request/verify); all others need the portal session token minted at verify.
Supplier portal: /api/v1/vendor-portal - same magic-link model as the customer portal.
Every response is wrapped as { success, data } except raw documents (invoice HTML/XML, portal CSV). Resources are scoped to your operator - another operator's resource returns 404.

bash

curl "https://packetexchange.io/api/v1/switch/entity-counts" \
  -H "Authorization: Bearer <operator_api_key>"

# → { "success": true, "data": { "customers": 0, ... } }

02 / Getting started

Zero to a previewable route

Create a supplier trunk

POST /suppliers with { label, sipHost, transport }. (Or promote a purchased marketplace route via /suppliers/promote.)

Add a cost deck

POST /suppliers/:id/rates/bulk with your termination rates - billed longest-prefix on live traffic.

Create a route group

POST /route-plans, then PUT /route-plans/:id/entries. Priorities give failover; weights load-balance.

Create a customer

POST /customers. The 201 returns the customer’s first apiKey + sipPassword (shown once) - hand these off so they can send you traffic.

Assign routing + preview

POST /customers/:id/routing to bind a plan, then GET /routing/preview?to=... for the resolved dialplan verdict + ordered failover chain (no side effects).

From there: add a retail SELL deck (POST /sell-rates/bulk), and once traffic flows, generate invoices, record payments, and run settlement. Give both sides self-serve visibility by setting portalEmail and calling the portal-invite endpoints.

bash

curl "https://packetexchange.io/api/v1/switch/routing/preview?to=14155551234&subAccountId=<customerId>" \
  -H "Authorization: Bearer <operator_api_key>"

# → resolved dialplan verdict + ordered
# candidates[] failover chain (supplier,
# matchedPrefix, price) - no side effects

03 / Customers, Suppliers & Provisioning

Bring suppliers in, connect customers out

Sell-side customers (sub-accounts with their own API key + SIP creds) and buy-side supplier vendor trunks, plus inbound IP ACLs and magic-link portal invites. All under /api/v1/switch, operator bearer auth.

Customers

GET/switch/customers

List sell-side customers

POST/switch/customers

Create customer (returns apiKey + sipPassword once)

GET/switch/customers/:id

Get customer + IP ACLs

PATCH/switch/customers/:id

Update fields / status

POST/switch/customers/:id/portal-invite

Email a magic-link portal login

POST/application/sub-accounts/:id/credit

Move funds operator → customer. Body { amount } (positive)

POST/application/sub-accounts/:id/debit

Charge a customer balance, e.g. a plan or bundle. Body { amount (positive), reason }

Suppliers

GET/switch/suppliers

List supplier vendor trunks

POST/switch/suppliers

Create external supplier trunk

POST/switch/suppliers/promote

Promote a purchased marketplace route

GET/switch/suppliers/:id

Get trunk + IP ACLs

PATCH/switch/suppliers/:id

Update trunk

DEL/switch/suppliers/:id

Delete trunk (cascades plan entries)

POST/switch/suppliers/:id/portal-invite

Email a magic-link portal login

IP ACLs

GET/switch/acls

List ACLs for a customer/trunk

POST/switch/acls

Add an inbound IP/CIDR ACL

DEL/switch/acls/:id

Delete an ACL

Overview

GET/switch/entity-counts

Customer + supplier counts (native vs external)

04 / Routing

Dialplans, route groups, LCR & failover

Route plans (ordered suppliers with priority/weight and SIP-code failover), dialplans (match → manipulate → route/block rules), per-customer assignment, and a read-only preview that resolves the full failover chain with no side effects.

Route plans (route groups)

GET/switch/route-plans

List route plans

POST/switch/route-plans

Create route plan (maxAttempts, failoverSipCodes)

GET/switch/route-plans/:id

Get plan + entries

PATCH/switch/route-plans/:id

Update plan

DEL/switch/route-plans/:id

Delete plan (entries cascade)

PUT/switch/route-plans/:id/entries

Replace all entries (priority/weight)

Dialplans

GET/switch/dialplans

List dialplans

POST/switch/dialplans

Create dialplan

GET/switch/dialplans/:id

Get dialplan + rules

PATCH/switch/dialplans/:id

Update dialplan

DEL/switch/dialplans/:id

Delete dialplan (rules cascade)

PUT/switch/dialplans/:id/rules

Replace all rules (match/manipulate/route)

Per-customer routing

GET/switch/customers/:id/routing

Get assigned dialplan / plan / strategy

POST/switch/customers/:id/routing

Assign dialplan / plan / strategyOverride

Preview

GET/switch/routing/preview

Resolve dialplan + ordered failover chain (no side effects)

05 / Rating

Retail SELL decks & per-trunk COST decks

A-Z rate decks billed longest-prefix on live traffic. Prefixes are cleaned to digits (max 24 chars). Single upserts, bulk imports (up to 50,000 rows), deletes, and clears.

Sell rates (retail SELL deck)

GET/switch/sell-rates

List sell rates (search/limit/offset)

POST/switch/sell-rates

Upsert a sell rate (fires webhook)

POST/switch/sell-rates/bulk

Bulk upsert sell deck (fires webhook)

DEL/switch/sell-rates/:id

Delete a sell rate

POST/switch/sell-rates/clear

Clear deck (all or given prefixes)

Supplier cost rates (per-trunk)

GET/switch/suppliers/:id/rates

List cost rates for a trunk

POST/switch/suppliers/:id/rates

Upsert a supplier cost rate

POST/switch/suppliers/:id/rates/bulk

Bulk upsert cost deck

DEL/switch/suppliers/:id/rates/:rateId

Delete a cost rate (archived, recoverable)

POST/switch/suppliers/:id/rates/clear

Clear the trunk cost deck (archives it)

GET/switch/suppliers/:id/rates/archived

List archived deck generations

POST/switch/suppliers/:id/rates/restore

Restore an archived cost deck

06 / Billing (AR invoices)

Invoices from settled CDR usage

Generate AR invoices over a period, record payments, void, email, render HTML/XML, issue credit notes, and pull AR aging. Invoice print (HTML) and xml return raw documents (not envelope-wrapped).

Invoices

GET/switch/invoices

List invoices (customer/status filters)

POST/switch/invoices

Generate invoice from settled CDRs

GET/switch/invoices/:id

Get invoice + lines + payments

POST/switch/invoices/:id/payments

Record a payment

POST/switch/invoices/:id/void

Void invoice

POST/switch/invoices/:id/send

Email invoice to portal email

GET/switch/invoices/:id/print

Render invoice HTML (raw)

GET/switch/invoices/:id/xml

Export invoice XML (raw)

Credit notes, aging & settings

GET/switch/credit-notes

List credit notes

POST/switch/credit-notes

Issue a credit note

GET/switch/ar-aging

AR aging buckets

POST/switch/customers/:id/billing-settings

Set billing cycle + payment terms

07 / Settlement (AP, counterparties, netting)

Payables, counterparties & netting

AP payables generated from supplier cost, bilateral counterparties, and netting runs that offset AR against AP over a period.

Payables

GET/switch/payables

List payables (trunk/status filters)

POST/switch/payables

Generate payable from CDR cost

GET/switch/payables/:id

Get payable + lines + payments

POST/switch/payables/:id/payments

Record supplier payment

POST/switch/payables/:id/void

Void payable

GET/switch/ap-aging

AP aging buckets

Counterparties & netting

GET/switch/counterparties

List counterparties

POST/switch/counterparties

Create counterparty

PATCH/switch/counterparties/:id

Update counterparty

DEL/switch/counterparties/:id

Delete counterparty

POST/switch/counterparties/:id/netting

Run netting (AR minus AP)

GET/switch/netting-runs

List netting runs

08 / Reporting & Fraud

Analytics & fraud controls

A shared metric shape (revenue, cost, margin, ASR, ACD, minutes, PDD) across overview, daily time-series, and top-100 breakdowns by customer / supplier / destination - plus per-operator fraud thresholds, high-risk prefixes, and an event feed.

Analytics

GET/switch/analytics/overview

Single metric object for a range

GET/switch/analytics/timeseries

Daily time-series metrics

GET/switch/analytics/breakdown

Top-100 by customer/supplier/destination

Fraud

GET/switch/fraud/settings

Get fraud config (scores, prefixes)

POST/switch/fraud/settings

Update fraud thresholds + prefixes

GET/switch/fraud/events

Event feed (newest first)

GET/switch/fraud/summary

30-day total / blocked / flagged

09 / Self-service Portals

Magic-link portals for both sides

Customers (/api/v1/sub-portal) and suppliers (/api/v1/vendor-portal) get self-serve visibility into CDRs, invoices/payables, rate cards, and key rotation. The auth/* endpoints are public; everything else uses the portal session token minted at verify.

Customer portal (/sub-portal)

POST/sub-portal/auth/request-link

Request magic link (public)

POST/sub-portal/auth/verify

Verify → mint session token (public)

GET/sub-portal/me

Identity, balance, usage, branding

GET/sub-portal/cdrs

Recent CDRs

GET/sub-portal/cdrs-filtered

CDRs filtered by date/kind

GET/sub-portal/cdrs.csv

CDR CSV download (raw)

GET/sub-portal/invoices

Their invoices

GET/sub-portal/rate-card

Markup + effective rates

GET/sub-portal/keys

API key metadata

POST/sub-portal/keys/rotate

Rotate key (returned once)

POST/sub-portal/topup-request

Request a top-up (notify only)

Supplier portal (/vendor-portal)

POST/vendor-portal/auth/request-link

Request magic link (public)

POST/vendor-portal/auth/verify

Verify → mint session token (public)

GET/vendor-portal/me

Identity, earnings, outstanding owed

GET/vendor-portal/cdrs

Their traffic CDRs (sellerCredit)

GET/vendor-portal/cdrs.csv

Traffic CSV download (raw)

GET/vendor-portal/payables

Their payables

GET/vendor-portal/payments

Payments received

10 / Webhooks

Events emitted on key writes

Certain Switch writes fire webhooks you can subscribe to:

sell_rate.changedinvoice.createdinvoice.paymentinvoice.sentcredit_note.issuedsub_account.topup_requested

sell_rate.changed carries a kind of upsert or bulk_import. Register webhook endpoints via the core account API.

Integration Support

Moving traffic onto your own switch?

Our carrier team helps with interconnects, rate deck imports, routing design and settlement, from the first trunk to the first invoice.

Email Support

Write to our team and we'll get back to you.

Contact form

Send us a message from the support page.

Get Your Operator Key

Your carrierin a box