--- title: Get started with the API url: https://help.telecomsxchange.com/buyers/api/ audience: For Buyers summary: Tick Allow API Access in Profile & Preferences and copy your API key. Call https://apiv2.telecomsxchange.com with HTTP Digest authentication (your username, and the API key as the password). In four calls you can read your balances, search Market View, buy a route and pull your call records. The API reference documents every endpoint. updated: '2026-10-22' verified_commit: 83b4ebc96d0081a25213776d5a8871bd04941125 --- # Get started with the API > Tick Allow API Access in Profile & Preferences and copy your API key. Call https://apiv2.telecomsxchange.com with HTTP Digest authentication (your username, and the API key as the password). In four calls you can read your balances, search Market View, buy a route and pull your call records. The API reference documents every endpoint. ## How an API call is authenticated 1. **API key**: Enabled with Allow API Access in preferences 2. **Your code** (via key as password): cURL, Python or PHP with Digest support 3. **TelecomsXchange API** (via `POST /buyers/balance`): Checks credentials, account and rate limit 4. **JSON reply** (via `status: success`): Balances, routes, tech prefix or call records This quickstart takes you from no key to buying a route and reading its call records in five steps, in about ten minutes. Every request and response below is real in shape; your IDs and prices will differ. For every endpoint and parameter, see the [API reference](https://help.telecomsxchange.com/reference/). ## Before you start - A buyer login with at least one [account](https://help.telecomsxchange.com/buyers/create-your-first-account/) that has [funds](https://help.telecomsxchange.com/buyers/add-funds/). - `curl`, or Python with `requests`, or PHP with the curl extension. The examples use cURL; the reference shows each call in all three. ## Turn on API access 1. Go to **Settings → Profile & Preferences**. 2. Tick **Allow API Access**. 3. Copy the **API Key** and click **Save**. **Regenerate** replaces the key at once; the old one stops working. Keep the key out of source code. The examples read it from the environment: ```bash export TCXC_USERNAME="your-portal-username" export TCXC_API_KEY="the-key-from-preferences" ``` ## Make your first call Read the balance of every account. Each call uses HTTP Digest authentication: your username, and the API key as the password. ```bash curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \ https://apiv2.telecomsxchange.com/buyers/balance ``` ```json { "status": "success", "accounts": [ { "i_account": "1022", "name": "Northwind", "currency": "USD", "balance": "4106.06", "credit_limit": "0", "smpp": "0", "blocked": "0" } ] } ``` Note the `i_account` of the account you'll send traffic from: most buyer calls take it. An account that shares another account's balance shows that account in `use_balance` and its balance in `parent_balance`. !!! tip `{"status": "fail", "error": "authorization error"}` means the username or key is wrong, or **Allow API Access** is off. See [Errors](https://help.telecomsxchange.com/reference/#errors). ## Find a route Search Market View for a destination prefix. Leave `smpp` out for voice routes, or set it to `1` for SMS. ```bash curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \ https://apiv2.telecomsxchange.com/marketview/search \ -d searchform=1 -d prefix=4477 -d type=CLI -d pager=20 -d off=0 ``` Each route in `rates` carries its seller, price per minute (`price_1`, `price_n` with the billing intervals), daily and weekly ASR and ACD, and its `i_connection`: the ID you buy it with. Prices already include the platform commission, as in the portal. See [Search Market View](https://help.telecomsxchange.com/reference/market/#search-market-view) for every filter. ## Buy the route Purchasing creates an interconnect between your account and the seller's route. It costs nothing; you pay per minute or message as traffic flows. ```bash curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \ https://apiv2.telecomsxchange.com/buyers/interconnect \ -d add=1 -d i_account=1022 -d id=38 -d agree=yes ``` ```json { "status": "success", "message": "Interconnection with TATA Communications completed", "rates_url": "https://members.telecomsxchange.com/accounts.php?download=38", "tech_prefix": "33270#", "route_type": "voice" } ``` Send calls to `sip01.telecomsxchange.com`, port 5060, with the `tech_prefix` in front of the number in E.164 format: `33270#447700900123`. See [Send your first call](https://help.telecomsxchange.com/buyers/send-your-first-call/). ## Read your call records Fetch the call detail records for a time range. `show=good` returns answered calls, `bad` failed ones, `all` both. ```bash curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \ https://apiv2.telecomsxchange.com/buyers/callhistory \ -d show=all -d "date_from=2026-10-21 00:00:00" -d "date_to=2026-10-21 23:59:59" ``` Each record has the number dialled (`CLD`), caller (`CLI`), `connect_time`, `billed_duration`, the price, the amount charged (`customer_amount`), the seller and route, and the SIP `disconnect_code` with its reason. ## Where next | To | Use | |---|---| | Create accounts and authorise IP addresses | [Accounts](https://help.telecomsxchange.com/reference/accounts/) | | Route through several sellers with failover or load balancing | [Routing groups](https://help.telecomsxchange.com/reference/routing-groups/) | | Test a route with a callback call | [Start a route test call](https://help.telecomsxchange.com/reference/market/#start-a-route-test-call) | | Buy phone numbers or eSIMs | [Phone numbers](https://help.telecomsxchange.com/reference/numbers/), [eSIMs](https://help.telecomsxchange.com/reference/esims/) | | Check a number's carrier before you dial | [HLR lookups](https://help.telecomsxchange.com/reference/hlr/) | | Reconcile spend | [Balances and payments](https://help.telecomsxchange.com/reference/money/), [Reports](https://help.telecomsxchange.com/reference/reports/) | | Talk to a seller | [Messages](https://help.telecomsxchange.com/reference/messages/) | ## What if something goes wrong? | You see | What to do | |---|---| | HTTP 401, `authorization required` | Send Digest credentials. Most clients need Digest switched on explicitly, such as `--digest` in cURL. | | `authorization error` | Check the username and key, and that **Allow API Access** is ticked in **Profile & Preferences**. | | `Account error` | The `i_account` isn't one of your accounts. Read the IDs from `/buyers/balance`. | | `Rate limit exceeded` (HTTP 429) | Slow down and retry with backoff. | | A call works in the portal but not in the API | Compare the fields with the [API reference](https://help.telecomsxchange.com/reference/); they match the portal's form fields. | ## Frequently asked questions **Q: Where do I find my API key?** A: In Profile & Preferences, under API Key. Once Allow API Access is on, the dashboard also shows an API Keys card with your API Login and the key. **Q: Is there a sandbox?** A: No. Calls run against your live account, and calls that spend money charge it exactly as the portal does. Try purchases on an account with a small balance first. **Q: Which languages are supported?** A: Any language with an HTTP client that supports Digest authentication. The API reference shows every call in cURL, Python and PHP. **Q: Is there a request limit?** A: Yes. Each account has an hourly quota and a per-second cap. Above either you get HTTP 429 with the message "Rate limit exceeded". Contact support if you need more. **Q: Can my AI assistant use the API?** A: Yes. TelecomsXchange publishes an MCP server at telecomsxchange.com/mcp-server that gives assistants such as Claude access to the same endpoints with your API key.