API reference

Offers

Propose, counter and accept prices on marketplace routes.

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

BrowseOffers

List offers you made and received

GET/api/v1/offers

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Parameters

Name	In	Type	Description
`role`	query	string	Default allOne of buyer, seller, all
`status`	query	string	-One of pending, countered, accepted, rejected, withdrawn, expired

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`routeId`requireddata[].routeId	string (uuid)	-
`groupId`requireddata[].groupId	string (uuid) \| null	Set when the offer is part of a bulk (multi-route) offer
`listPrice`requireddata[].listPrice	money \| null	The route list price when the offer was made USD as a decimal string with exactly 6 places, e.g. "0.012500".
`proposedPrice`requireddata[].proposedPrice	money	The latest price on the table USD as a decimal string with exactly 6 places, e.g. "0.012500".
`agreedPrice`requireddata[].agreedPrice	money \| null	Set once accepted USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata[].status	string	-One of `pending`, `countered`, `accepted`, `rejected`, `withdrawn`, `expired`
`lastActor`requireddata[].lastActor	string	-One of `buyer`, `seller`
`message`requireddata[].message	string \| null	Cleaned of contact details
`expiresAt`requireddata[].expiresAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata[].updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`role`requireddata[].role	string	Your side of this offerOne of `buyer`, `seller`
`yourTurn`requireddata[].yourTurn	boolean	-
`counterparty`requireddata[].counterparty	string	Pseudonym for the other side, stable per route
`route`requireddata[].route	object \| null	-
`id`requireddata[].route.id	string (uuid)	-
`destinationName`requireddata[].route.destinationName	string	The seller reads the name they gave the route; the buyer reads the platform-generated name (see MarketplaceRoute.destinationName)
`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.
`country`requireddata[].route.country	string	-
`countryCode`requireddata[].route.countryCode	string	-
`type`requireddata[].route.type	string	-One of `voice`, `sms`
`routeType`requireddata[].route.routeType	string	-
`pricePerUnit`requireddata[].route.pricePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".

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.

Make an offer on a route

POST/api/v1/offers

Access: API key. Scoped keys need offers:write.
Rate limit: 100 requests per second (the default)
Safe retries: Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Moves money: Makes or answers a binding offer on a route.

Opens a negotiation at proposedPrice (6-decimal USD string). The seller can accept, reject or counter.

Parameters

Name	In	Type	Description
`X-Idempotency-Key`	header	string	Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

Field	Type	Description
`routeId`required	string (uuid)	-
`proposedPrice`required	string	-
`message`	string	-max 500 chars

Response 200

Field	Type	Description
`data`required	object	Same fields as Offer, 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/offers" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "routeId": "<routeId>",
  "proposedPrice": "<proposedPrice>"
}'

Run it here with a test key.

Make offers on several routes at once

POST/api/v1/offers/bulk

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

One offer per item, grouped. Routes that cannot take an offer (your own, inactive, already negotiating) are skipped and reported back.

Request body (application/json)

Field	Type	Description
`items`required	object[]	-
`routeId`requireditems[].routeId	string (uuid)	-
`proposedPrice`requireditems[].proposedPrice	string	-
`message`	string	-max 500 chars

Response 200

Field	Type	Description
`data`required	object	-
`group`requireddata.group	object	-
`id`requireddata.group.id	string (uuid)	-
`message`requireddata.group.message	string \| null	-
`status`requireddata.group.status	string	-
`createdAt`requireddata.group.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`offers`requireddata.offers	object[]	Same fields as Offer, shown earlier on this page.
`skipped`requireddata.skipped	object[]	-
`routeId`requireddata.skipped[].routeId	string (uuid)	-
`reason`requireddata.skipped[].reason	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.
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/offers/bulk" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "routeId": "<routeId>",
      "proposedPrice": "<proposedPrice>"
    }
  ]
}'

Run it here with a test key.

List your bulk offers

GET/api/v1/offers/groups

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Response 200

Field	Type	Description
`data`required	object[]	-
`id`requireddata[].id	string (uuid)	-
`message`requireddata[].message	string \| null	-
`status`requireddata[].status	string	-
`createdAt`requireddata[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`offers`requireddata[].offers	object[]	Same fields as Offer, shown earlier on this page.
`total`requireddata[].total	integer	-
`counts`requireddata[].counts	object	Child offers per status

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.

Accept or reject every open offer in a bulk offer

POST/api/v1/offers/groups/{id}/respond

Access: API key. Scoped keys need offers: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
`action`required	string	-One of `accept`, `reject`
`message`	string	-max 500 chars

Response 200

Field	Type	Description
`data`required	object	-
`groupId`requireddata.groupId	string (uuid)	-
`applied`requireddata.applied	integer	-
`results`requireddata.results	object[]	-
`ok`requireddata.results[].ok	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.
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/offers/groups/<id>/respond" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "accept"
}'

Run it here with a test key.

Get an offer with its negotiation history

GET/api/v1/offers/{id}

Access: API key. Full-access keys only; not reachable by scoped keys.
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)	-
`routeId`requireddata.routeId	string (uuid)	-
`groupId`requireddata.groupId	string (uuid) \| null	Set when the offer is part of a bulk (multi-route) offer
`listPrice`requireddata.listPrice	money \| null	The route list price when the offer was made USD as a decimal string with exactly 6 places, e.g. "0.012500".
`proposedPrice`requireddata.proposedPrice	money	The latest price on the table USD as a decimal string with exactly 6 places, e.g. "0.012500".
`agreedPrice`requireddata.agreedPrice	money \| null	Set once accepted USD as a decimal string with exactly 6 places, e.g. "0.012500".
`status`requireddata.status	string	-One of `pending`, `countered`, `accepted`, `rejected`, `withdrawn`, `expired`
`lastActor`requireddata.lastActor	string	-One of `buyer`, `seller`
`message`requireddata.message	string \| null	Cleaned of contact details
`expiresAt`requireddata.expiresAt	string (date-time) \| null	ISO-8601 timestamp (UTC)
`createdAt`requireddata.createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`updatedAt`requireddata.updatedAt	string (date-time)	ISO-8601 timestamp (UTC)
`role`requireddata.role	string	Your side of this offerOne of `buyer`, `seller`
`yourTurn`requireddata.yourTurn	boolean	-
`counterparty`requireddata.counterparty	string	Pseudonym for the other side, stable per route
`route`requireddata.route	object \| null	-
`id`requireddata.route.id	string (uuid)	-
`destinationName`requireddata.route.destinationName	string	The seller reads the name they gave the route; the buyer reads the platform-generated name (see MarketplaceRoute.destinationName)
`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.
`country`requireddata.route.country	string	-
`countryCode`requireddata.route.countryCode	string	-
`type`requireddata.route.type	string	-One of `voice`, `sms`
`routeType`requireddata.route.routeType	string	-
`pricePerUnit`requireddata.route.pricePerUnit	money	USD as a decimal string with exactly 6 places, e.g. "0.012500".
`events`requireddata.events	object[]	The negotiation timeline, oldest first
`id`requireddata.events[].id	string (uuid)	-
`offerId`requireddata.events[].offerId	string (uuid)	-
`actor`requireddata.events[].actor	string	-
`action`requireddata.events[].action	string	-
`price`requireddata.events[].price	money \| null	US dollars as a decimal string with exactly 6 decimal places, e.g. "0.012500". Do money arithmetic with a decimal type, not floating point. USD as a decimal string with exactly 6 places, e.g. "0.012500".
`message`requireddata.events[].message	string \| null	-
`createdAt`requireddata.events[].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.
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.

Accept, reject, counter or withdraw an offer

PATCH/api/v1/offers/{id}

Access: API key. Scoped keys need offers:write.
Rate limit: 100 requests per second (the default)
Safe retries: Send X-Idempotency-Key; a replay within 24 hours returns the first response.
Moves money: Makes or answers a binding offer on a route.

price is required for counter. Accepting creates or reprices the purchase at the agreed price.

Parameters

Name	In	Type	Description
`id`required	path	string	-
`X-Idempotency-Key`	header	string	Any unique string (a UUID is ideal). Replays within 24 hours return the first response instead of acting twice.

Request body (application/json)

Field	Type	Description
`action`required	string	-One of `counter`, `accept`, `reject`, `withdraw`
`price`	string	-
`message`	string	-max 500 chars

Response 200

Field	Type	Description
`data`required	object	Same fields as Offer, 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 PATCH "https://packetexchange.io/api/v1/offers/<id>" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "counter"
}'

Run it here with a test key.