Help Center
All API resources

API reference

70 endpoints for buying and selling on TelecomsXchange, each with its parameters, a request in cURL, Python and PHP, and an example response.

The TelecomsXchange API is organised around the same objects you use in the members portal: accounts, routes and interconnects, phone numbers, eSIMs, records and balances. It accepts form-encoded request bodies, returns JSON, and uses HTTP Digest authentication. Everything you can do in the portal as a buyer or a seller, you can automate here.

Base URL#

Text
https://apiv2.telecomsxchange.com

Every endpoint in this reference is relative to that host, except the message classifiers (Open Text Shield), which are served from https://ots.telecomsxchange.com and need no credentials.

The whole reference is also available as an OpenAPI 3.0 spec for code generators, API clients and AI agents, and each page has a Markdown version (add .md to the address, such as /reference/hlr.md).

Authentication#

Authenticate with HTTP Digest: your portal username as the user name and your API key as the password. Calls run as your account, with its balances, routes and limits, so keep the key secret: never put it in client-side code or a public repository.

  1. In the members portal, go to Settings → Profile & Preferences.
  2. Tick Allow API Access and click Save.
  3. Copy the API Key. Regenerate replaces it at once, and the old key stops working.
Shell
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  https://apiv2.telecomsxchange.com/buyers/balance

A request without credentials gets 401 Unauthorized with a Digest challenge, which every HTTP client that supports Digest answers automatically. Wrong credentials, or Allow API Access switched off, return:

JSON
{"status": "fail", "error": "authorization error"}

Requests and responses#

  • Send parameters as application/x-www-form-urlencoded form fields, or in the query string for GET endpoints. Path parameters are part of the URL, such as the number in /buyers/hlr/lookup/{number}.
  • Every response is JSON with a status field: success when the call worked, error or fail when it didn't.
  • Many buyer endpoints take i_account, the ID of one of your accounts. Get the IDs from List buyer accounts.
  • List endpoints page with pager (rows per page) and off (the offset of the first row).

Errors#

A call that fails validation answers HTTP 200 with status: error and a message that says what to fix:

JSON
{"status": "error", "message": "Account balance insufficient to run query"}

Each endpoint in this reference lists the messages it can return and when. Check status on every reply rather than relying on the HTTP status code.

HTTP status Meaning
200 The request was processed. Read status for the outcome.
401 Missing or wrong credentials, or API access is off for the account.
429 Too many requests. Wait and retry with backoff.

Rate limits#

Each account has an hourly request quota and a per-second cap. Above either, the API answers 429 with {"status": "error", "message": "Rate limit exceeded"}. Contact support if your integration needs more.

Calls that spend money#

Some calls charge a balance exactly as the portal does: purchasing a phone number or an eSIM, HLR lookups ($0.05 each), and route tests. Their reference entries say what they charge and when. There is no sandbox, so test against a low-balance account first.

Use the API from an AI assistant#

TelecomsXchange publishes an MCP server that gives assistants such as Claude the same endpoints with your API key, so you can search routes, read records or check a balance in a chat.

Resources