GET
/balance
Consulter le solde
Renvoie le solde actuel de votre compte en dollars américains. La réception de codes et l'envoi de SMS utilisent le même solde.
Paramètres
Aucun paramètre.
Exemple de requête
request
$ curl https://today-sms.com/api/v1/balance \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
response
{
"balance": "42.5000",
"currency": "USD"
}
Erreurs possibles
| unauthorized | Clé API manquante ou incorrecte |
| not_allowed | L'API s'ouvre une fois votre première recharge créditée |
| rate_limited | Trop de requêtes en 1 minute |
GET
/apps
Lister les applications
Liste les applications qui ont des numéros en ce moment. Renvoie le code de l'application, son nom, le prix le plus bas et le nombre de pays disposant de numéros.
Paramètres
Aucun paramètre.
Exemple de requête
request
$ curl https://today-sms.com/api/v1/apps \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
response
[
{ "app": "telegram", "name": "Telegram", "from": "0.4515", "countries": 61 }
]
Erreurs possibles
| unauthorized | Clé API manquante ou incorrecte |
| not_allowed | L'API s'ouvre une fois votre première recharge créditée |
GET
/prices?app=telegram
Pays et prix d'une application
Renvoie les pays d'une application, du moins cher au plus cher. Comprend l'indicatif, le code ISO, le prix et le nombre de numéros disponibles en ce moment.
Paramètres
| Nom | Type | Obligatoire | Description |
|---|
| app | string | Obligatoire | Code de l'application (la valeur app de GET /apps) |
Exemple de requête
request
$ curl https://today-sms.com/api/v1/prices?app=telegram \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
response
[
{ "country": "indonesia", "iso": "id", "price": "0.4515", "stock": 702866 }
]
Erreurs possibles
| bad_request | Une valeur obligatoire est manquante ou au mauvais format |
| unauthorized | Clé API manquante ou incorrecte |
POST
/numbers
Acheter un numéro
Achète un numéro pour l'application et le pays choisis. Le prix est débité de votre solde et le numéro attend les SMS pendant le délai prévu. Si la confirmation du numéro prend plus de temps, la réponse est 202 avec le statut de vérification.
Paramètres
| Nom | Type | Obligatoire | Description |
|---|
| app | string | Obligatoire | Code de l'application |
| country | string | Obligatoire | Code du pays (la valeur country de GET /prices) |
Exemple de requête
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"}'
Exemple de réponse
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": []
}
Erreurs possibles
| bad_request | Une valeur obligatoire est manquante ou au mauvais format |
| not_enough_balance | Solde insuffisant, merci de recharger d'abord |
| too_many_open | Trop de numéros ouverts, merci d'en terminer ou d'en annuler |
| no_numbers | Aucun numéro pour cette application et ce pays en ce moment |
GET
/numbers/{id}
Statut du numéro et SMS
Renvoie le statut du numéro et tous les SMS reçus jusqu'ici. Le code de vérification est aussi fourni à part dans code.
Paramètres
| Nom | Type | Obligatoire | Description |
|---|
| id | string | Obligatoire | L'id reçu lors de l'achat du numéro (commence par N-) |
Exemple de requête
request
$ curl https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "received",
"sms": [
{ "code": "482913", "text": "Your code is 482913", "at": "2026-10-18T09:02:11.000Z" }
]
}
Erreurs possibles
| not_found | Aucun numéro ou message correspondant dans votre compte |
POST
/numbers/{id}/cancel
Annuler un numéro
Annule un numéro qui n'a reçu aucun SMS, à partir de 120 secondes après l'achat. Le montant total revient sur votre solde.
Paramètres
| Nom | Type | Obligatoire | Description |
|---|
| id | string | Obligatoire | Id du numéro (commence par N-) |
Exemple de requête
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "canceled",
"refunded": "0.4515"
}
Erreurs possibles
| too_early | Vous pouvez annuler à partir de 120 secondes après l'achat |
| has_sms | Les numéros qui ont reçu des SMS ne peuvent pas être annulés |
| try_again | Annulation pas encore confirmée, merci de réessayer dans 1 minute |
| not_found | Aucun numéro ou message correspondant dans votre compte |
POST
/numbers/{id}/finish
Terminer un numéro
Ferme le numéro après réception du code. Un numéro fermé ne reçoit plus de SMS.
Paramètres
| Nom | Type | Obligatoire | Description |
|---|
| id | string | Obligatoire | Id du numéro (commence par N-) |
Exemple de requête
request
$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/finish \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
response
{
"id": "N-7K2M-QX4P-9D3A",
"status": "finished"
}
Erreurs possibles
| not_found | Aucun numéro ou message correspondant dans votre compte |
GET
/messages/prices
Prix des SMS par pays
Renvoie le prix par SMS de chaque pays pour l'envoi de SMS. Comprend le code ISO, l'indicatif et le prix par SMS (USD).
Paramètres
Aucun paramètre.
Exemple de requête
request
$ curl https://today-sms.com/api/v1/messages/prices \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
response
[
{ "iso": "us", "dial": "1", "price": "0.0042" },
{ "iso": "gb", "dial": "44", "price": "0.0066" }
]
Erreurs possibles
| unauthorized | Clé API manquante ou incorrecte |
| not_allowed | L'API s'ouvre une fois votre première recharge créditée |
POST
/messages
Envoyer des SMS
Envoie des SMS à une liste de destinataires avec votre message. Jusqu'à 1 000 destinataires par requête, et les numéros en double ne reçoivent qu'un seul message. Ajoutez at pour programmer l'envoi à cette heure (UTC). Le coût total est réservé sur votre solde à l'envoi, et les parties en échec sont remboursées sur votre solde.
Paramètres
| Nom | Type | Obligatoire | Description |
|---|
| to | string[] | Obligatoire | Liste de numéros au format international (avec + et indicatif), jusqu'à 1 000 |
| text | string | Obligatoire | Texte du message. 160 caractères GSM-7 ou 70 caractères Unicode font un SMS |
| at | string | Facultatif | Heure programmée, ISO 8601 UTC (ex. 2026-10-18T10:00:00Z) |
| ref | string | Facultatif | Votre propre référence, comme un numéro de commande, jusqu'à 64 caractères |
Exemple de requête
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"}'
Exemple de réponse
response
{
"id": "m_7Q2K9X",
"status": "queued",
"recipients": 2,
"parts": 1,
"encoding": "GSM-7",
"cost": "0.0136"
}
Erreurs possibles
| bad_request | Une valeur obligatoire est manquante ou au mauvais format |
| too_many_recipients | Jusqu'à 1 000 destinataires par requête |
| not_enough_balance | Solde insuffisant, merci de recharger d'abord |
| not_available | Ce produit ouvre bientôt. Cette requête n'a pas été acceptée et votre solde reste inchangé |
GET
/messages/{id}
Statut d'envoi et rapports de livraison
Renvoie le statut global d'un message envoyé et un rapport de livraison pour chaque destinataire. Les montants des parties en échec sont ajoutés à refunded.
Paramètres
| Nom | Type | Obligatoire | Description |
|---|
| id | string | Obligatoire | L'id reçu lors de l'envoi |
Exemple de requête
request
$ curl https://today-sms.com/api/v1/messages/m_7Q2K9X \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
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" }
]
}
Erreurs possibles
| not_found | Aucun numéro ou message correspondant dans votre compte |
POST
/messages/{id}/cancel
Annuler un envoi programmé
Annule un envoi programmé qui n'est pas encore parti. Le montant total réservé revient sur votre solde.
Paramètres
| Nom | Type | Obligatoire | Description |
|---|
| id | string | Obligatoire | Id du message |
Exemple de requête
request
$ curl -X POST https://today-sms.com/api/v1/messages/m_7Q2K9X/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
Exemple de réponse
response
{
"id": "m_7Q2K9X",
"status": "canceled",
"refunded": "0.0136"
}
Erreurs possibles
| too_late | Les messages dont l'envoi a commencé ne peuvent pas être annulés |
| not_found | Aucun numéro ou message correspondant dans votre compte |