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 statusTypeRequiredDescription
401—OptionalInvalid key, or API access is off for the account
402—OptionalNot enough balance
404—OptionalUnknown number or service, or not yours
409—OptionalOut of stock for that service or area code
422—OptionalA field is missing or invalid
429—OptionalRate limit reached: slow down
502—OptionalA purchase could not be confirmed: don't retry, it is checked and delivered or refunded
503—OptionalNumber 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).

POSTaction: balance

balance

Your current balance in USD.

No fields.

Request
curl -X POST https://theduotalk.io/api/v1.php \
  -H "Authorization: Bearer $DUOTALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"balance"}'
Answer · 200
{
  "ok": true,
  "data": {
    "balance": "24.62",
    "currency": "USD"
  }
}
POSTaction: catalog

catalog

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.

FieldTypeRequiredDescription
typeintegerOptional1 first card (default), 2 restart, 3 renewal
Request
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}'
Answer · 200
{
  "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
          }
        ]
      }
    ]
  }
}
POSTaction: area_codes

area_codes

Area codes in stock for one service, with how many numbers each has. Pass one as prefix to buy.

FieldTypeRequiredDescription
app_idintegerRequiredFrom catalog
typeintegerOptionalSame as catalog
Request
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}'
Answer · 200
{
  "ok": true,
  "data": {
    "list": [
      {
        "prefix": "1270",
        "area": "270",
        "num": 13008
      }
    ]
  }
}
POSTaction: buy

buy

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.

FieldTypeRequiredDescription
app_idintegerRequiredFrom catalog
qtyintegerOptional1 to 10, default 1
prefixstringOptionalAn area code from area_codes, with country code
typeintegerOptionalCard type, default 1
Request
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}'
Answer · 200
{
  "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"
  }
}
POSTaction: numbers

numbers

Your active numbers with access time, last code and status.

No fields.

Request
curl -X POST https://theduotalk.io/api/v1.php \
  -H "Authorization: Bearer $DUOTALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"numbers"}'
Answer · 200
{
  "ok": true,
  "data": [
    {
      "id": 2291,
      "order_id": 1048,
      "tel": "14845550147",
      "title": "WhatsApp",
      "last_code": "482913",
      "received": true
    }
  ]
}
POSTaction: sms

sms

Checks one number for new messages and returns the latest code. Poll every 5 to 10 seconds while you wait.

FieldTypeRequiredDescription
number_idintegerRequiredThe id from buy or numbers
Request
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}'
Answer · 200
{
  "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"
  }
}
POSTaction: sms_history

sms_history

Every message received, newest first. Leave number_id out to get all your numbers.

FieldTypeRequiredDescription
number_idintegerOptionalLimit to one number
Request
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}'
Answer · 200
{
  "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"
    }
  ]
}
POSTaction: extend

extend

Gives a number more time once, free, when no code has arrived yet.

FieldTypeRequiredDescription
number_idintegerRequired
Request
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}'
Answer · 200
{
  "ok": true,
  "data": {
    "id": 2291
  }
}
POSTaction: renew

renew

Renews a number that supports renewal, at the renewal price.

FieldTypeRequiredDescription
number_idintegerRequired
Request
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}'
Answer · 200
{
  "ok": true,
  "data": {
    "balance": "23.86",
    "access_ends": "2026-12-10T11:06:12+00:00"
  }
}
POSTaction: report

report

Reports a number that did not work. Reports are reviewed; when the number failed, its price goes back to your balance.

FieldTypeRequiredDescription
number_idintegerRequired
reasonstringRequiredno_sms, wrong_code, used, banned or other
detailsstringOptionalWhat you saw
Request
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"}'
Answer · 200
{
  "ok": true,
  "data": {
    "id": 77
  }
}