---
title: Get started with the API
url: https://help.telecomsxchange.com/sellers/api/
audience: For Sellers
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). Read your balance and payout history, manage the
  numbers you sell and message your buyers. 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). Read your balance and payout history, manage the numbers you sell and message your buyers. The API reference documents every endpoint.

## What the seller API gives you

1. **Your code**: Username, with the API key as password
2. **TelecomsXchange API** (via `POST /sellers/balance`): Digest auth, hourly quota and per-second cap
3. **JSON reply** (via `status: success`): Balance, payouts, numbers and buyers
4. **Your buyers** (via `/sellers/buyers/message`): Get your message in inbox and email

This quickstart takes you from no key to reading your earnings and managing the numbers you sell. Every request and
response below is real in shape; your figures will differ. For every endpoint and parameter, see the
[API reference](https://help.telecomsxchange.com/reference/).

## 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.

The examples read your credentials from the environment:

```bash
export TCXC_USERNAME="your-portal-username"
export TCXC_API_KEY="the-key-from-preferences"
```

## Read your balance

Your seller balance is what buyers' traffic has earned you, less payouts and fees.

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  https://apiv2.telecomsxchange.com/sellers/balance
```

```json
{"status": "success", "balance": "22631.26"}
```

!!! 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).

## Check your payouts

Payout History, as in the portal: payouts, their fees, HLR lookups and anonymous-listing fees.

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  https://apiv2.telecomsxchange.com/sellers/payhistory \
  -d "date_from=2026-10-01 00:00:00" -d "date_to=2026-10-31 23:59:59"
```

```json
{
  "status": "success",
  "transactions": [
    {"i_payout": "2873", "amount": "500", "ts": "2026-10-14 22:14:41", "notepad": "Bank Wire"}
  ]
}
```

## Manage the numbers you sell

List your numbers, optionally from a prefix:

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  https://apiv2.telecomsxchange.com/sellers/did/list -d prefix=380
```

Each number shows its rates (`price_1`, `smpp_price`), `setup_fee` and `monthly_fee`, its `status` (`idle` until a
buyer purchases it), capabilities (`voice`, `sms`, `fax`, `video`) and whether it needs KYC
(`verification_required`). Add a number with `/sellers/did/add` and change one with `/sellers/did/edit/{i_did}`;
see [Phone numbers](https://help.telecomsxchange.com/reference/numbers/) for every field.

## Message your buyers

List the buyers who use your routes, then write to one or all of them. Messages land in their portal inbox and by
email.

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  https://apiv2.telecomsxchange.com/sellers/buyers/list
```

See [Messages](https://help.telecomsxchange.com/reference/messages/) for sending, replying and reading your inbox.

## Where next

| To | Use |
|---|---|
| Check a number's carrier, ported and roaming status | [HLR lookups](https://help.telecomsxchange.com/reference/hlr/) |
| See the busiest destinations on the exchange | [Voice and SMS market](https://help.telecomsxchange.com/reference/market/) |
| Read the same records your buyers see | [Reports](https://help.telecomsxchange.com/reference/reports/) |

## 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**. |
| `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: Can I upload my rate deck through the API?**

A: Not yet. Rate decks are uploaded in the portal; see Upload your rate deck. The seller API covers your balance, payouts, phone numbers, buyers, messages and HLR lookups.

**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.