API reference
Buy numbers and read SMS codes from your own software. One endpoint: https://theduotalk.io/api/v1.php
Introduction
The DuoTalk API lets approved partners buy private virtual numbers and read the SMS codes they receive, from any language that can send HTTPS requests. It uses the same stock, balance and refund rules as the dashboard. API access is switched on per account: request it under Reseller API in your account.
Authentication
Create a key under Reseller API once access is on. The key is shown once; store it on your server, never in a browser or app. Send it on every request:
Authorization: Bearer dt_live_••••••••••••••••
Creating a new key stops the old one; deleting it stops it immediately.
Requests and answers
Every request is a POST to the endpoint above with a JSON body that names the action plus its fields. Every answer is JSON:
{
"ok": true,
"data": {
"…": "…"
}
}{
"ok": false,
"error": "Not enough balance."
}Money amounts are strings in USD with up to three decimals. Times are UTC.
Errors
| HTTP status | Type | Required | Description |
|---|---|---|---|
401 | — | Optional | Invalid key, or API access is off for the account |
402 | — | Optional | Not enough balance |
404 | — | Optional | Unknown number or service, or not yours |
409 | — | Optional | Out of stock for that service or area code |
422 | — | Optional | A field is missing or invalid |
429 | — | Optional | Rate limit reached: slow down |
502 | — | Optional | A purchase could not be confirmed: don't retry, it is checked and delivered or refunded |
503 | — | Optional | Number suppliers briefly unavailable: try again shortly |
Rate limits
120 requests per minute per key and up to 30 purchases per minute; up to 10 numbers per purchase. Poll sms every 5 to 10 seconds per number.
Partner prices
Purchases made with your API key use your partner price: by default 10% below the public price, or the rate set for your account. catalog returns both price (what you pay) and retail_price (the public price).
action: balancebalance
Your current balance in USD.
No fields.
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"balance"}'{
"ok": true,
"data": {
"balance": "24.62",
"currency": "USD"
}
}action: catalogcatalog
Every country and service you can buy, with your partner price (price), the public price (retail_price) and live stock. Cache it for about a minute.
| Field | Type | Required | Description |
|---|---|---|---|
type | integer | Optional | 1 first card (default), 2 restart, 3 renewal |
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"catalog","type":1}'{
"ok": true,
"data": {
"type": 1,
"currency": "USD",
"discount_percent": 10,
"max_qty": 10,
"countries": [
{
"id": 8,
"name": "United States (Virtual card)",
"iso": "US",
"dial": "+1",
"projects": [
{
"app_id": 73,
"title": "WhatsApp",
"price": "0.36",
"retail_price": "0.40",
"stock": 1125885
}
]
}
]
}
}action: area_codesarea_codes
Area codes in stock for one service, with how many numbers each has. Pass one as prefix to buy.
| Field | Type | Required | Description |
|---|---|---|---|
app_id | integer | Required | From catalog |
type | integer | Optional | Same as catalog |
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"area_codes","app_id":73}'{
"ok": true,
"data": {
"list": [
{
"prefix": "1270",
"area": "270",
"num": 13008
}
]
}
}action: buybuy
Buys numbers at your partner price and returns them. The price is taken from your balance when the purchase succeeds; a failed purchase is refunded at once. Never repeat a buy after a timeout: call numbers first.
| Field | Type | Required | Description |
|---|---|---|---|
app_id | integer | Required | From catalog |
qty | integer | Optional | 1 to 10, default 1 |
prefix | string | Optional | An area code from area_codes, with country code |
type | integer | Optional | Card type, default 1 |
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"buy","app_id":73,"qty":1}'{
"ok": true,
"data": {
"order_id": 1048,
"numbers": [
{
"id": 2291,
"tel": "14845550147",
"title": "WhatsApp",
"country": "United States (Virtual card)",
"end_time": "2026-11-10 12:05:00"
}
],
"balance": "24.26"
}
}action: numbersnumbers
Your active numbers with access time, last code and status.
No fields.
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"numbers"}'{
"ok": true,
"data": [
{
"id": 2291,
"order_id": 1048,
"tel": "14845550147",
"title": "WhatsApp",
"last_code": "482913",
"received": true
}
]
}action: smssms
Checks one number for new messages and returns the latest code. Poll every 5 to 10 seconds while you wait.
| Field | Type | Required | Description |
|---|---|---|---|
number_id | integer | Required | The id from buy or numbers |
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"sms","number_id":2291}'{
"ok": true,
"data": {
"id": 2291,
"tel": "14845550147",
"title": "WhatsApp",
"received": true,
"last_sms": "Your WhatsApp code: 482-913",
"last_code": "482913",
"last_sms_time": "2026-11-10 11:06:12"
}
}action: sms_historysms_history
Every message received, newest first. Leave number_id out to get all your numbers.
| Field | Type | Required | Description |
|---|---|---|---|
number_id | integer | Optional | Limit to one number |
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"sms_history","number_id":2291}'{
"ok": true,
"data": [
{
"id": 551,
"number_id": 2291,
"tel": "14845550147",
"title": "WhatsApp",
"sms": "Your WhatsApp code: 482-913",
"code": "482913",
"sms_time": "2026-11-10 11:06:12"
}
]
}action: extendextend
Gives a number more time once, free, when no code has arrived yet.
| Field | Type | Required | Description |
|---|---|---|---|
number_id | integer | Required |
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"extend","number_id":2291}'{
"ok": true,
"data": {
"id": 2291
}
}action: renewrenew
Renews a number that supports renewal, at the renewal price.
| Field | Type | Required | Description |
|---|---|---|---|
number_id | integer | Required |
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"renew","number_id":2291}'{
"ok": true,
"data": {
"balance": "23.86",
"access_ends": "2026-12-10T11:06:12+00:00"
}
}action: reportreport
Reports a number that did not work. Reports are reviewed; when the number failed, its price goes back to your balance.
| Field | Type | Required | Description |
|---|---|---|---|
number_id | integer | Required | |
reason | string | Required | no_sms, wrong_code, used, banned or other |
details | string | Optional | What you saw |
curl -X POST https://theduotalk.io/api/v1.php \
-H "Authorization: Bearer $DUOTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"report","number_id":2291,"reason":"no_sms"}'{
"ok": true,
"data": {
"id": 77
}
}