API reference

Interconnections

The SIP IP whitelist and connectivity tests for your traffic.

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

BrowseInterconnections

List your whitelisted source IPs

GET/api/v1/interconnections/ips

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

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
userIdrequired
string (uuid) · data[].userId
ipAddressrequired
string · data[].ipAddress
IPv4/IPv6 address, optionally with a CIDR suffix
labelrequired
string | null · data[].label
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.
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.

Whitelist a source IP for your traffic

POST/api/v1/interconnections/ips

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

An address can authenticate for one account only; an address already registered elsewhere is refused with VALIDATION_ERROR.

Request body (application/json)

FieldDescription

ipAddressrequired
string
max 49 chars
label
string
max 100 chars

Response 201

FieldDescription

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

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
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/interconnections/ips" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ipAddress": "203.0.113.10"
}'

Run it here with a test key.

Remove a whitelisted source IP

DELETE/api/v1/interconnections/ips/{id}

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

Traffic from the address is refused from then on.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
messagerequired
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.
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.

List your interconnections

GET/api/v1/interconnections

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

One per purchase, with your credentials, the route (never its seller endpoint) and pricing: what you are actually billed on the route. route.pricePerUnit is the list price only.

Response 200

FieldDescription

datarequired
object[]
idrequired
string (uuid) · data[].id
purchaseIdrequired
string (uuid) · data[].purchaseId
typerequired
string · data[].type
One of sip, smpp, api
buyerEndpointrequired
object | null · data[].buyerEndpoint
Your own connection settings and credentials
sellerEndpointrequired
enum | null · data[].sellerEndpoint
Always null: the seller endpoint is never shown to buyersOne of null
statusrequired
string · data[].status
One of active, inactive
createdAtrequired
string (date-time) · data[].createdAt
ISO-8601 timestamp (UTC)
updatedAtrequired
string (date-time) · data[].updatedAt
ISO-8601 timestamp (UTC)
purchaserequired
object | null · data[].purchase
idrequired
string (uuid) · data[].purchase.id
statusrequired
string · data[].purchase.status
sipUsernamerequired
string | null · data[].purchase.sipUsername
sipPasswordrequired
string | null · data[].purchase.sipPassword
smppSystemIdrequired
string | null · data[].purchase.smppSystemId
smppPasswordrequired
string | null · data[].purchase.smppPassword
routerequired
object | null · data[].route
idrequired
string (uuid) · data[].route.id
typerequired
string · data[].route.type
One of voice, sms
countryrequired
string | null · data[].route.country
countryCoderequired
string | null · data[].route.countryCode
prefixrequired
string[] · data[].route.prefix
destinationNamerequired
string | null · data[].route.destinationName
The listing name as a buyer reads it: generated by the platform, never the seller's text, and ending in the listing reference (e.g. "Niger Mobile · Ref 7K2Q", "A-Z Voice · Premium · Full CLI · Ref 3MX9"). Your own listings keep the name you gave them.
listingRef
string · data[].route.listingRef
Anonymous short reference of the listing (4 characters, e.g. "7K2Q"): stable for the life of the listing, unique enough to tell two same-named listings apart, and derived from the listing alone (it says nothing about the seller). Absent on your own listings.
pricePerUnitrequired
money · data[].route.pricePerUnit
List price only; see pricing for what you pay USD as a decimal string with exactly 6 places, e.g. "0.012500".
billingIncrementrequired
string | null · data[].route.billingIncrement
jingleSipIprequired
enum | null · data[].route.jingleSipIp
One of null
capacityrequired
integer | null · data[].route.capacity
rateCountrequired
integer · data[].route.rateCount
Destinations on the rate deck; > 0 means priced per destination
pricingrequired
object | null · data[].pricing
Your real rate basis for this route
basisrequired
string · data[].pricing.basis
One of flat, per_destination

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.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get an interconnection

GET/api/v1/interconnections/{id}

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

In buyerEndpoint the SIP password is replaced by sipPasswordSet (here and on the two PUTs); the list endpoint carries your plaintext credentials for the connection card.

Parameters

idrequired
path · string

Response 200

FieldDescription

datarequired
object
idrequired
string (uuid) · data.id
purchaseIdrequired
string (uuid) · data.purchaseId
typerequired
string · data.type
One of sip, smpp, api
buyerEndpointrequired
object | null · data.buyerEndpoint
Your own connection settings and credentials
sellerEndpointrequired
enum | null · data.sellerEndpoint
Always null: the seller endpoint is never shown to buyersOne of null
statusrequired
string · data.status
One of active, inactive
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.
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.

Update an interconnection

PUT/api/v1/interconnections/{id}

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

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

buyerEndpoint
object
status
string
One of active, inactive

Response 200

FieldDescription

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

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
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 PUT "https://packetexchange.io/api/v1/interconnections/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "buyerEndpoint": {},
  "status": "active"
}'

Run it here with a test key.

Set delivery-receipt settings on an SMS interconnection

PUT/api/v1/interconnections/{id}/dlr-config

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

Stores whether to request delivery receipts and the https callback URL for them.

Parameters

idrequired
path · string

Request body (application/json)

FieldDescription

requestDlrsrequired
boolean
dlrCallbackUrl
string (uri) | null

Response 200

FieldDescription

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

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
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 PUT "https://packetexchange.io/api/v1/interconnections/<id>/dlr-config" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "requestDlrs": true
}'

Run it here with a test key.

Test connectivity on a purchased route

POST/api/v1/interconnections/test

Access: API key. Scoped keys need account:write.
Rate limit: 100 requests per second (the default)
Real traffic: Sends real test traffic over the purchased route.

sip_options probes reachability from every media worker. test_call places a real billed test call to testNumber; smpp_bind checks an SMS bind. Test calls and binds are capped per purchase per hour and per day.

Request body (application/json)

FieldDescription

purchaseIdrequired
string (uuid)
testType
string
default "sip_options"One of sip_options, test_call, smpp_bind
testNumber
string
max 30 chars
testCli
string
max 30 chars

Response 200

FieldDescription

datarequired
object
statusrequired
string · data.status
Outcome: connected, degraded, failed, no_answer, error or unknown
messagerequired
string · data.message
detailsrequired
object · data.details
Diagnostic trace. Never carries the seller address.

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.
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/interconnections/test" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "purchaseId": "<purchaseId>"
}'

Run it here with a test key.

Get a summary of your interconnect setup

GET/api/v1/interconnections/status/summary

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

Response 200

FieldDescription

datarequired
object
whitelistedIpsrequired
integer · data.whitelistedIps
activePurchasesrequired
integer · data.activePurchases
activeInterconnectionsrequired
integer · data.activeInterconnections
totalInterconnectionsrequired
integer · data.totalInterconnections
sipPublicIprequired
string · data.sipPublicIp
The edge address to send SIP traffic to

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.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get live connection health per purchase

GET/api/v1/interconnections/health

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

SIP purchases report whether the switch is up and the route configured; SMS purchases report their SMPP bind state.

Response 200

FieldDescription

datarequired
object[]
purchaseIdrequired
string (uuid) · data[].purchaseId
protocolrequired
string · data[].protocol
One of sip, smpp
boundrequired
boolean · data[].bound
boundAtrequired
string (date-time) | null · data[].boundAt
ISO-8601 timestamp (UTC)
lastMessageAtrequired
string (date-time) | null · data[].lastMessageAt
ISO-8601 timestamp (UTC)
remoteIprequired
string | null · data[].remoteIp
configured
boolean · data[].configured
reachablerequired
boolean · data[].reachable

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

Rotate the SIP and SMPP credentials on a purchase

POST/api/v1/interconnections/{purchaseId}/rotate-credentials

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

Issues new credentials, returned once. The old ones stop working immediately and open SMPP binds are dropped.

Parameters

purchaseIdrequired
path · string

Response 200

FieldDescription

datarequired
object
sipUsernamerequired
string · data.sipUsername
sipPasswordrequired
string · data.sipPassword
smppSystemIdrequired
string · data.smppSystemId
smppPasswordrequired
string · data.smppPassword
unboundSessionsrequired
integer · data.unboundSessions
messagerequired
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.
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/interconnections/<purchaseId>/rotate-credentials" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY"

Run it here with a test key.