# TelecomsXchange API reference

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

```
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](/reference/openapi.json) 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](/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.

```bash
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](/reference/market/#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](mailto:support@telecomsxchange.com) 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](https://www.telecomsxchange.com/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

- [Accounts](https://help.telecomsxchange.com/reference/accounts.md): A buyer account is how traffic reaches TelecomsXchange: a SIP trunk authorised by IP or digest login, an SMPP bind, or an IoT (MQTT) login. Each account has its own balance (or uses another account's), its own purchased routes and its own alerts. Create accounts, change their credentials and authorise extra IP addresses.
- [Voice and SMS market](https://help.telecomsxchange.com/reference/market.md): Market View is the exchange's live order book: every seller's routes with their current price, quality (ASR, ACD) and capacity. Search it for a destination, download a seller's full rate deck, read the busiest destinations, and list your active calls and call or message records.
- [Interconnects](https://help.telecomsxchange.com/reference/interconnects.md): Buying a route from Market View creates an interconnect between one of your accounts and the seller's route. Traffic sent with the route's tech prefix then terminates on it, billed per minute or per message from the account's balance. Purchasing is free; you pay only for traffic.
- [Routing groups](https://help.telecomsxchange.com/reference/routing-groups.md): A routing group combines several purchased routes behind one tech prefix (444 and three digits) and chooses a route for each call or message by least cost, failover order or weighted load balancing, with optional rules per destination or caller prefix.
- [Phone numbers (DIDs)](https://help.telecomsxchange.com/reference/numbers.md): Buy and sell virtual phone numbers. Buyers search the number market, purchase numbers and point them at a SIP or SMPP endpoint; sellers list their numbers with setup and recurring fees. Numbers renew automatically from the billing account's balance.
- [eSIMs](https://help.telecomsxchange.com/reference/esims.md): Prepaid data eSIMs for single countries, regions and the whole world, sold by the eSIM providers on the exchange, such as Airalo and eSimplified. Purchases are charged to an account balance and return the activation code, LPA string and QR code at once.
- [HLR lookups](https://help.telecomsxchange.com/reference/hlr.md): Ask the mobile networks about a number: its current carrier and MCC/MNC, whether it has been ported and whether it is roaming. Each lookup costs $0.05 and is charged as soon as it is sent.
- [Balances and payments](https://help.telecomsxchange.com/reference/money.md): Read buyer account balances and payment history, and the seller balance and payout history.
- [Reports](https://help.telecomsxchange.com/reference/reports.md): Traffic summaries by period, and the detail records for IoT (MQTT) messages.
- [Messages](https://help.telecomsxchange.com/reference/messages.md): The exchange's internal messaging between buyers and sellers: read your inbox, reply, write to a seller about one of their routes, and, as a seller, list your buyers and message them.
- [Tools](https://help.telecomsxchange.com/reference/tools.md): Helpers for testing and integration: list seller IDs and score a phone number by whether it has carried traffic on the exchange.
- [Message classification (AI)](https://help.telecomsxchange.com/reference/ai.md): Open Text Shield, the TelecomsXchange SMS classifiers, served from their own host. The threat classifier labels a message as ham, spam or phishing; the category classifier labels what kind of message it is.