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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`userId`requireddata[].userId	string (uuid)	-
`ipAddress`requireddata[].ipAddress	string	IPv4/IPv6 address, optionally with a CIDR suffix
`label`requireddata[].label	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.
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)

Field	Type	Description
`ipAddress`required	string	-max 49 chars
`label`	string	-max 100 chars

Response 201

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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`message`requireddata.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.
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

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`purchaseId`requireddata[].purchaseId	string (uuid)	-
`type`requireddata[].type	string	-One of `sip`, `smpp`, `api`
`buyerEndpoint`requireddata[].buyerEndpoint	object \| null	Your own connection settings and credentials
`sellerEndpoint`requireddata[].sellerEndpoint	enum \| null	Always null: the seller endpoint is never shown to buyersOne of `null`
`status`requireddata[].status	string	-One of `active`, `inactive`
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`purchase`requireddata[].purchase	object \| null	-
`id`requireddata[].purchase.id	string (uuid)	-
`status`requireddata[].purchase.status	string	-
`sipUsername`requireddata[].purchase.sipUsername	string \| null	-
`sipPassword`requireddata[].purchase.sipPassword	string \| null	-
`smppSystemId`requireddata[].purchase.smppSystemId	string \| null	-
`smppPassword`requireddata[].purchase.smppPassword	string \| null	-
`route`requireddata[].route	object \| null	-
`id`requireddata[].route.id	string (uuid)	-
`type`requireddata[].route.type	string	-One of `voice`, `sms`
`country`requireddata[].route.country	string \| null	-
`countryCode`requireddata[].route.countryCode	string \| null	-
`prefix`requireddata[].route.prefix	string[]	-
`destinationName`requireddata[].route.destinationName	string \| null	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`data[].route.listingRef	string	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.
`pricePerUnit`requireddata[].route.pricePerUnit	money	List price only; see `pricing` for what you pay USD as a decimal string with exactly 6 places, e.g. "0.012500".
`billingIncrement`requireddata[].route.billingIncrement	string \| null	-
`jingleSipIp`requireddata[].route.jingleSipIp	enum \| null	-One of `null`
`capacity`requireddata[].route.capacity	integer \| null	-
`rateCount`requireddata[].route.rateCount	integer	Destinations on the rate deck; > 0 means priced per destination
`pricing`requireddata[].pricing	object \| null	Your real rate basis for this route
`basis`requireddata[].pricing.basis	string	-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

Name	In	Type	Description
`id`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`id`requireddata.id	string (uuid)	-
`purchaseId`requireddata.purchaseId	string (uuid)	-
`type`requireddata.type	string	-One of `sip`, `smpp`, `api`
`buyerEndpoint`requireddata.buyerEndpoint	object \| null	Your own connection settings and credentials
`sellerEndpoint`requireddata.sellerEndpoint	enum \| null	Always null: the seller endpoint is never shown to buyersOne of `null`
`status`requireddata.status	string	-One of `active`, `inactive`
`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.
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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`buyerEndpoint`	object	-
`status`	string	-One of `active`, `inactive`

Response 200

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

Name	In	Type	Description
`id`required	path	string	-

Request body (application/json)

Field	Type	Description
`requestDlrs`required	boolean	-
`dlrCallbackUrl`	string (uri) \| null	-

Response 200

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

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

Field	Type	Description
`data`required	object	-
`status`requireddata.status	string	Outcome: connected, degraded, failed, no_answer, error or unknown
`message`requireddata.message	string	-
`details`requireddata.details	object	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

Field	Type	Description
`data`required	object	-
`whitelistedIps`requireddata.whitelistedIps	integer	-
`activePurchases`requireddata.activePurchases	integer	-
`activeInterconnections`requireddata.activeInterconnections	integer	-
`totalInterconnections`requireddata.totalInterconnections	integer	-
`sipPublicIp`requireddata.sipPublicIp	string	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

Field	Type	Description
`data`required	object[]	-
`purchaseId`requireddata[].purchaseId	string (uuid)	-
`protocol`requireddata[].protocol	string	-One of `sip`, `smpp`
`bound`requireddata[].bound	boolean	-
`boundAt`requireddata[].boundAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`lastMessageAt`requireddata[].lastMessageAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`remoteIp`requireddata[].remoteIp	string \| null	-
`configured`data[].configured	boolean	-
`reachable`requireddata[].reachable	boolean	-

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

Name	In	Type	Description
`purchaseId`required	path	string	-

Response 200

Field	Type	Description
`data`required	object	-
`sipUsername`requireddata.sipUsername	string	-
`sipPassword`requireddata.sipPassword	string	-
`smppSystemId`requireddata.smppSystemId	string	-
`smppPassword`requireddata.smppPassword	string	-
`unboundSessions`requireddata.unboundSessions	integer	-
`message`requireddata.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.
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.