GET
/balance
Отримати баланс
Повертає поточний баланс акаунта в доларах США. Прийом кодів і надсилання SMS використовують один баланс.
Параметри
Параметрів немає.
Приклад запиту
request
$ curl https://today-sms.com/api/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
{
"balance": "42.5000",
"currency": "USD"
}
Можливі помилки
| unauthorized | API-ключ відсутній або неправильний |
| not_allowed | API відкривається після зарахування першого поповнення |
| rate_limited | Забагато запитів за 1 хвилину |
GET
/apps
Список застосунків
Список застосунків, для яких зараз є номери. Повертає код застосунку, назву, найнижчу ціну й кількість країн із номерами.
Параметри
Параметрів немає.
Приклад запиту
request
$ curl https://today-sms.com/api/v1/apps \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
[
{ "app": "telegram", "name": "Telegram", "from": "0.4515", "countries": 61 }
]
Можливі помилки
| unauthorized | API-ключ відсутній або неправильний |
| not_allowed | API відкривається після зарахування першого поповнення |
GET
/prices?app=telegram
Країни й ціни для застосунку
Повертає країни для одного застосунку, починаючи з найдешевшої. Містить код країни, ISO-код, ціну й кількість доступних зараз номерів.
Параметри
| Назва | Тип | Обов'язковий | Опис |
|---|
| app | string | Обов'язковий | Код застосунку (значення app з GET /apps) |
Приклад запиту
request
$ curl https://today-sms.com/api/v1/prices?app=telegram \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
[
{ "country": "indonesia", "iso": "id", "price": "0.4515", "stock": 702866 }
]
Можливі помилки
| bad_request | Бракує обов'язкового значення або неправильний формат |
| unauthorized | API-ключ відсутній або неправильний |
POST
/numbers
Купити номер
Купує номер для обраного застосунку й країни. Ціна списується з балансу, а номер чекає на SMS заданий час. Якщо підтвердження номера триває довше, повертається 202 зі статусом перевірки.
Параметри
| Назва | Тип | Обов'язковий | Опис |
|---|
| app | string | Обов'язковий | Код застосунку |
| country | string | Обов'язковий | Код країни (значення country з GET /prices) |
Приклад запиту
request
$ curl -X POST https://today-sms.com/api/v1/numbers \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"app":"telegram","country":"indonesia"}'
Приклад відповіді
response
{
"id": "N-7K2M-QX4P-9D3A",
"app": "telegram",
"country": "indonesia",
"phone": "+6281234567890",
"price": "0.4515",
"refunded": "0.0000",
"status": "waiting",
"expires_at": "2026-10-18T09:20:00.000Z",
"sms": []
}
Можливі помилки
| bad_request | Бракує обов'язкового значення або неправильний формат |
| not_enough_balance | Недостатньо коштів, спочатку поповніть баланс |
| too_many_open | Забагато відкритих номерів, завершіть або скасуйте частину |
| no_numbers | Зараз немає номерів для цього застосунку й країни |
GET
/numbers/{id}
Статус номера та SMS
Повертає статус номера й усі отримані на цей момент SMS. Код підтвердження також передається окремо в code.
Параметри
| Назва | Тип | Обов'язковий | Опис |
|---|
| id | string | Обов'язковий | id, отриманий під час купівлі номера (починається з N-) |
Приклад запиту
request
$ curl https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "received",
"sms": [
{ "code": "482913", "text": "Your code is 482913", "at": "2026-10-18T09:02:11.000Z" }
]
}
Можливі помилки
| not_found | Такого номера чи повідомлення немає у вашому акаунті |
POST
/numbers/{id}/cancel
Скасувати номер
Скасовує номер без SMS, починаючи з 120 секунд після покупки. Уся сума повертається на баланс.
Параметри
| Назва | Тип | Обов'язковий | Опис |
|---|
| id | string | Обов'язковий | id номера (починається з N-) |
Приклад запиту
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "canceled",
"refunded": "0.4515"
}
Можливі помилки
| too_early | Скасувати можна через 120 секунд після покупки |
| has_sms | Номери, на які надійшли SMS, скасувати не можна |
| try_again | Скасування ще не підтверджено, повторіть через 1 хвилину |
| not_found | Такого номера чи повідомлення немає у вашому акаунті |
POST
/numbers/{id}/finish
Завершити номер
Закриває номер після отримання коду. Закритий номер більше не приймає SMS.
Параметри
| Назва | Тип | Обов'язковий | Опис |
|---|
| id | string | Обов'язковий | id номера (починається з N-) |
Приклад запиту
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/finish \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "finished"
}
Можливі помилки
| not_found | Такого номера чи повідомлення немає у вашому акаунті |
GET
/messages/prices
Ціни на SMS за країнами
Повертає ціну за SMS для кожної країни під час надсилання SMS. Містить ISO-код, код країни й ціну за SMS (USD).
Параметри
Параметрів немає.
Приклад запиту
request
$ curl https://today-sms.com/api/v1/messages/prices \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
[
{ "iso": "us", "dial": "1", "price": "0.0042" },
{ "iso": "gb", "dial": "44", "price": "0.0066" }
]
Можливі помилки
| unauthorized | API-ключ відсутній або неправильний |
| not_allowed | API відкривається після зарахування першого поповнення |
POST
/messages
Надіслати SMS
Надсилає SMS списку одержувачів із вашим текстом. До 1,000 одержувачів у запиті, на номери, що повторюються, іде лише одне повідомлення. Додайте at, щоб запланувати надсилання на цей час (UTC). Підсумкова вартість утримується з балансу під час надсилання, а за недоставлені частини гроші повертаються на баланс.
Параметри
| Назва | Тип | Обов'язковий | Опис |
|---|
| to | string[] | Обов'язковий | Список номерів у міжнародному форматі (з + і кодом країни), до 1,000 |
| text | string | Обов'язковий | Текст повідомлення. 160 символів GSM-7 або 70 символів Unicode це одне SMS |
| at | string | Необов'язковий | Запланований час, ISO 8601 UTC (наприклад, 2026-10-18T10:00:00Z) |
| ref | string | Необов'язковий | Ваша власна мітка, наприклад номер замовлення, до 64 символів |
Приклад запиту
request
$ curl -X POST https://today-sms.com/api/v1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":["+14155550100","+447700900123"],"text":"Your code is 482913"}'
Приклад відповіді
response
{
"id": "m_7Q2K9X",
"status": "queued",
"recipients": 2,
"parts": 1,
"encoding": "GSM-7",
"cost": "0.0136"
}
Можливі помилки
| bad_request | Бракує обов'язкового значення або неправильний формат |
| too_many_recipients | До 1,000 одержувачів в одному запиті |
| not_enough_balance | Недостатньо коштів, спочатку поповніть баланс |
| not_available | Ця послуга скоро відкриється. Запит не прийнято, баланс не змінився |
GET
/messages/{id}
Статус надсилання та звіти про доставку
Повертає загальний статус надісланого повідомлення й звіт про доставку за кожним одержувачем. Суми за недоставлені частини додаються в refunded.
Параметри
| Назва | Тип | Обов'язковий | Опис |
|---|
| id | string | Обов'язковий | id, отриманий під час надсилання |
Приклад запиту
request
$ curl https://today-sms.com/api/v1/messages/m_7Q2K9X \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
{
"id": "m_7Q2K9X",
"status": "done",
"cost": "0.0136",
"refunded": "0.0083",
"reports": [
{ "to": "+14155550100", "status": "delivered", "at": "2026-10-18T10:00:04Z" },
{ "to": "+447700900123", "status": "failed", "at": "2026-10-18T10:00:09Z" }
]
}
Можливі помилки
| not_found | Такого номера чи повідомлення немає у вашому акаунті |
POST
/messages/{id}/cancel
Скасувати заплановане надсилання
Скасовує заплановане надсилання, яке ще не почалося. Уся утримана сума повертається на баланс.
Параметри
| Назва | Тип | Обов'язковий | Опис |
|---|
| id | string | Обов'язковий | id повідомлення |
Приклад запиту
request
$ curl -X POST https://today-sms.com/api/v1/messages/m_7Q2K9X/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Приклад відповіді
response
{
"id": "m_7Q2K9X",
"status": "canceled",
"refunded": "0.0136"
}
Можливі помилки
| too_late | Повідомлення, надсилання яких почалося, скасувати не можна |
| not_found | Такого номера чи повідомлення немає у вашому акаунті |