API SMS Vert Pro V2

API REST en JSON pour l'envoi de SMS professionnels, la gestion des crédits, les rapports de livraison et plus encore.

Télécharger la collection Postman Importez-la dans Postman pour tester l'API en quelques clics (variables base_url, token et email préremplies).

Authentification

L'API supporte deux méthodes d'authentification. Le Bearer Token est recommandé pour la performance et la sécurité.

Méthode 1 : Bearer Token (recommandé)

Envoyez votre token API dans le header HTTP Authorization. C'est la méthode la plus rapide : un seul lookup indexé en base, idéal pour les envois en masse.

Header
Authorization: Bearer votre_token_api_64_caracteres

Le body JSON ne contient plus que la requête :

JSON
{
}

Obtenir votre token

POST /api/v2/generate_token

Appelez cet endpoint avec vos identifiants. Le token est permanent : tant que vous ne le renouvelez pas, chaque appel renvoie le même token.

C'est le seul endpoint où vous utilisez login/pass (puisque vous n'avez pas encore de token). Tous les autres endpoints utilisent ensuite le header Authorization: Bearer votre_token.
Requête (body)
{
    "login": {
        "user": "votre@email.com",
        "pass": "md5_de_votre_mot_de_passe"
    }
}
Réponse
{
    "status": "OK",
    "token": "a1b2c3d4e5f6...64 caractères"
}
Conservez votre token en lieu sûr. Pour le remplacer (en cas de fuite par exemple), ajoutez "renew": true au body : un nouveau token est créé et l'ancien cesse immédiatement de fonctionner.
Requête de renouvellement (body)
{
    "login": {
        "user": "votre@email.com",
        "pass": "md5_de_votre_mot_de_passe"
    },
    "renew": true
}

Votre token actuel

Votre token est visible depuis votre compte. Il s'obtient en une fois, et il ne s'affiche jamais en clair sans votre mot de passe.

Voir mon token Créer un compte, 10 SMS offerts

Méthode 2 : Login / Password (fallback)

Pour la compatibilité, vous pouvez toujours envoyer vos identifiants dans le body JSON. Le mot de passe doit être en MD5.

JSON
{
    "login": {
        "user": "votre@email.com",
        "pass": "md5_de_votre_mot_de_passe"
    },
}
Le Bearer Token est prioritaire. Si les deux méthodes sont présentes, le token est utilisé et le login/pass est ignoré.

Format des requêtes

POST https://www.smsvertpro.com/api/v2/nom_du_endpoint

Exemples : /api/v2/send_sms, /api/v2/credits, /api/v2/generate_token

HeaderValeur
Content-Typeapplication/json
AuthorizationBearer votre_token_api

Body JSON avec uniquement les paramètres de l'endpoint :

JSON (body)
{
    // paramètres spécifiques à l'endpoint
}

Les requêtes comme les réponses sont en UTF-8, avec l'en-tête Content-Type: application/json; charset=UTF-8. Les caractères accentués sont transmis tels quels : configurez votre client en UTF-8 pour les lire correctement.

Si vous n'avez pas encore de Bearer Token, vous pouvez utiliser un fallback login/password :

JSON (body)
{
    "login": {
        "user": "votre@email.com",
        "pass": "md5_de_votre_mot_de_passe"
    }
}

Codes de statut

Chaque réponse contient un champ status et retourne un code HTTP cohérent. Voici tous les codes possibles :

Succès (2xx)

StatusHTTPDescription
OK200Succès générique
SEND_OK200SMS envoyé avec succès
CANCEL_OK200Annulation de SMS réussie
OK + result=OTP_SENT200OTP envoyé par SMS
OK + result=OTP_TRUE200Code OTP correct
OK + result=OTP_VERIFIED200OTP déjà vérifié précédemment

Erreurs de requête (400 Bad Request)

StatusHTTPDescription
MISSING_ELEMENTS400Paramètres manquants dans la requête
JSON_ERROR_0400JSON invalide ou vide
JSON_ERROR_1400JSON mal formé
INVALID_EMAIL400Format d'email invalide
INVALID_SENDER400Expéditeur invalide (max 12 caractères)
INVALID_REQUEST400Endpoint inconnu
CONTACT_ERROR400Aucun destinataire valide
DELAY_ERROR400Date d'envoi différé invalide ou passée
STOPSMS_ERROR400Mention STOP manquante (route marketing)
EMOJI_NOT_ALLOWED400Le message contient des emojis ou caractères non-GSM
GSM_ERROR400Format de numéro de téléphone invalide
INVALID_CREDITS400Montant de crédits invalide
INVALID_MASTER400Compte master invalide
INVALID_PASSWORD400Mot de passe invalide (trop court, etc.)
INVALID_TEL400Format de téléphone invalide
INVALID_CODE400Code parrain invalide
INVALID_CP400Code postal invalide
INVALID_RCS400Numéro RCS invalide
FORMAT_ERROR400Format des paramètres d'envoi invalide
NO_RECIPIENTS400Aucun destinataire fourni

Méthode non autorisée (405)

StatusHTTPDescription
METHOD_NOT_ALLOWED405Méthode HTTP non supportée — seul POST est accepté

Erreurs d'authentification et d'accès (401, 402, 403)

StatusHTTPDescription
INVALID_USER_OR_PASS401Email ou mot de passe incorrect
INVALID_USER401Utilisateur non authentifié / token invalide
OTP_FALSE401Code OTP incorrect
NOT_ENOUGH_CREDITS402Solde de crédits insuffisant
FRAUD_DETECTED403Tentative de fraude détectée

Ressources introuvables (404 Not Found)

StatusHTTPDescription
REPORT_ID_ERROR404ID de campagne introuvable
SMS_ID_ERROR404ID de SMS introuvable
INVALID_SMS404SMS introuvable en base
INVALID_CAMPAIGN404Campagne introuvable en base
INVALID_LIST404Liste de contacts introuvable
INVALID_CONTACT404Contact introuvable

Conflit (409)

StatusHTTPDescription
OTP_ALREADY_EXIST409OTP déjà généré pour ce numéro
ALREADY_SENT409Envoi déjà parti : l'annulation n'est plus possible
ALREADY_CANCELLED409Envoi déjà annulé lors d'un appel précédent
NOT_CANCELLABLE409Envoi connu, mais dans un état qui n'autorise pas l'annulation

Erreurs serveur (500 Internal Server Error)

StatusHTTPDescription
CAMPAIGN_ERROR500Erreur lors de la création de la campagne
SEND_ERROR500Échec technique d'envoi SMS
TRANSFER_ERROR500Échec technique du transfert de crédits
CANCEL_ERROR500Échec technique de l'annulation SMS
ADD_ERROR500Échec d'ajout en base
OTP_SEND_ERROR500Échec d'envoi SMS de l'OTP
OTP_ERROR500Erreur générique OTP
CREATE_ERROR500Échec de création de ressource
INSERT_ERROR500Échec d'insertion en base
UPDATE_ERROR500Échec de mise à jour en base
DELETE_ERROR500Échec de suppression en base
AJOUT_ERROR500Échec de création du compte
GENERAL_ERROR500Erreur générique serveur
UNKNOWN_ERROR500Erreur d'envoi non identifiée
Rappel : tous les endpoints ci-dessous nécessitent le header HTTP Authorization: Bearer votre_token_api (ou un bloc login en fallback). Voir la section Authentification.

Envoi de SMS

POST /api/v2/send_sms

Envoie un ou plusieurs SMS immédiatement ou en différé.

Paramètres

ChampTypeRequisDescription
message.senderstringOuiNom de l'expéditeur (max 12 car.)
message.textstringOuiContenu du SMS
message.idstringNonIdentifiant personnalisé de la campagne. Si non fourni, un identifiant unique est généré automatiquement et retourné dans la réponse.
message.delaystringNonDate d'envoi différé, obligatoirement dans le futur. Format recommandé : YYYY-MM-DD HH:MM:SS. Les formats DD-MM-YYYY HH:MM:SS et DD/MM/YYYY HH:MM:SS sont également acceptés, avec un espace ou un slash entre la date et l'heure. Une date invalide ou déjà passée retourne DELAY_ERROR.
message.delay_cancelbooleanNonSi true, le SMS programmé est annulable
recipientsarrayOui*Liste des destinataires (obligatoire si liste_id n'est pas fourni)
liste_idintegerOui*ID d'une liste de contacts existante (obligatoire si recipients n'est pas fourni). Peut être combiné avec recipients.

Les destinataires peuvent être envoyés sous trois formats :

Format simple (international)
"recipients": ["33612345678", "32475123456"]
Format avec ID personnalisé
"recipients": [
    { "gsm": "33612345678", "id": "sms_001" },
    { "gsm": "33698765432", "id": "sms_002" }
]

Le champ id de chaque destinataire est optionnel. Si non fourni, un identifiant unique par SMS est généré automatiquement. Cet identifiant permet de suivre le statut de délivrabilité de chaque SMS individuellement dans les rapports.

Format avec pays (recommandé pour les numéros locaux)
"recipients": [
    { "gsm": "0612345678", "country": "FR" },
    { "gsm": "0475123456", "country": "BE" },
    { "gsm": "079 123 45 67", "country": "CH" }
]
Normalisation automatique : quand le champ country est fourni (code ISO 2 lettres), les numéros locaux commençant par 0 sont automatiquement convertis au format international. Exemples :
- 0612345678 + FR → 33612345678
- 0475123456 + BE → 32475123456
- 079 123 45 67 + CH → 41791234567

Sans country, seuls les numéros français (06/07) sont convertis automatiquement (compatibilité V1). Les espaces, points, tirets et parenthèses sont nettoyés automatiquement.

Pays supportés : FR, BE, CH, LU, DE, ES, IT, PT, NL, GB, US, CA, IE, AT, PL, MA, TN, DZ, SN, CI, CM, MG, RE, GP, MQ, GF, NC, et 50+ autres.

Exemple - Envoi immédiat

Requête
{
    "message": {
        "sender": "MonEntreprise",
        "text": "Bonjour, votre commande est prete. A retirer en magasin.",
        "id": "camp_20260402"
    },
    "recipients": [
        "33612345678",
        "33698765432"
    ]
}
Réponse
{
    "status": "SEND_OK",
    "credits": 4852,
    "id": "camp_1234_1744224000_5678",
    "sender": "MonEntreprise",
    "nbsms": 2,
    "date": "2026-04-02 14:30:00"
}

Note : le champ id contient l'identifiant de la campagne. Si vous n'en avez pas fourni dans message.id, un identifiant unique est généré automatiquement. Conservez cet identifiant pour consulter les rapports de délivrabilité et les réponses SMS.

Exemple - Envoi différé

Requête
{
    "message": {
        "sender": "MonEntreprise",
        "text": "Rappel : votre rendez-vous est demain a 10h.",
        "id": "camp_rdv_001",
        "delay": "2026-04-10 08:00:00",
        "delay_cancel": true
    },
    "recipients": [
        { "gsm": "33612345678", "id": "sms_001" }
    ]
}

Exemple - Envoi à une liste de contacts

Plutôt que d'envoyer tous les numéros dans la requête, vous pouvez envoyer à une liste existante en passant son liste_id. Tous les contacts de la liste recevront le SMS.

Requête
{
    "message": {
        "sender": "MonEntreprise",
        "text": "Nouvelle collection disponible en magasin !"
    },
    "liste_id": 42
}
Vous pouvez aussi combiner liste_id et recipients pour envoyer à une liste + quelques numéros supplémentaires dans le même envoi. La liste doit appartenir au compte authentifié.

Crédits

POST /api/v2/credits

Récupère le solde de crédits SMS du compte, ou de ses sous-comptes.

Paramètres optionnels

ChampTypeDescription
souscomptestring / trueEmail d'un sous-compte spécifique, ou true pour tous les sous-comptes

Exemple - Solde du compte principal

Aucun paramètre n'est nécessaire : le corps de la requête peut être vide, {} ou null.

Réponse
{
    "status": "OK",
    "credits": 4852
}

Exemple - Solde des sous-comptes

Requête
{
    "souscompte": true
}
Réponse
{
    "status": "OK",
    "souscomptes": [
        {
            "id": 4567,
            "email": "filiale@example.com",
            "societe": "Filiale Paris",
            "credits": 1200
        }
    ]
}

Infos compte

POST /api/v2/infos_compte

Récupère les informations du compte client.

Réponse
{
    "status": "OK",
    "nom": "Dupont",
    "prenom": "Jean",
    "societe": "Ma Société SAS",
    "rcs": "123456789",
    "adresse": "10 rue de la Paix",
    "cp": "75001",
    "ville": "Paris",
    "type": "normal"   // "normal", "master" ou "sous-compte"
}

Tarifs SMS

POST /api/v2/infos_sms

Récupère le tarif unitaire du SMS pour votre compte.

Réponse
{
    "status": "OK",
    "prix_sms": 0.063,
    "tva": 20,
    "smsmin": 1600,
    "smsmax": 50000
}

Créer un compte

POST /api/v2/create_account

Crée un nouveau compte client avec un code parrain.

Requête
{
    "nom": "Dupont",
    "prenom": "Jean",
    "societe": "Ma Société SAS",
    "rcs": "123456789",
    "tel": "0612345678",
    "adresse": "10 rue de la Paix",
    "cp": "75001",
    "ville": "Paris",
    "email": "jean@societe.com",
    "pass": "motdepasse",
    "code": "moncode"
}
Réponse
{
    "status": "OK",
    "message": "compte créé"
}
ParamètreTypeRequisDescription
nomstringouiNom du client
prenomstringouiPrénom du client
societestringouiNom de la société
rcsstringouiNuméro RCS (numérique)
telstringouiNuméro de téléphone (min 6 chiffres)
adressestringouiAdresse postale
cpstringouiCode postal (min 3 chiffres)
villestringouiVille
emailstringouiAdresse email (servira de login)
passstringouiMot de passe (min 6 caractères)
codestringouiCode parrain
Erreurs possibles
MISSING_ELEMENTS, INVALID_TEL, INVALID_EMAIL, INVALID_PASSWORD, INVALID_RCS, INVALID_CP, INVALID_CODE, AJOUT_ERROR

Rapports

POST /api/v2/reports

Récupère les rapports de livraison de vos campagnes SMS.

Paramètres optionnels

ChampTypeDescription
campaign_idstringID de campagne spécifique
message_idstringID de message spécifique
date_startstringDate de début du filtre, format YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS. Permet de remonter l'historique au-delà des 12 derniers mois (limite par défaut).
date_endstringDate de fin du filtre, format YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS. Si l'heure n'est pas spécifiée, la journée entière est incluse jusqu'à 23:59:59.

Exemple

Tous les paramètres sont facultatifs : sans aucun filtre (corps vide, {} ou null), l'API renvoie les campagnes des 12 derniers mois.

Requête — campagne précise
{
    "campaign_id": "camp_20260402"
}
Requête — filtre par dates
{
    "date_start": "2026-01-01",
    "date_end": "2026-03-31"
}
Réponse
{
    "status": "OK",
    "campaigns": [
        {
            "id": "camp_20260402",
            "date": "2026-04-02 14:30:00",
            "sender": "MonEntreprise",
            "text": "Bonjour, votre commande est prete.",
            "total_credits": 2,
            "total_sms": 2,
            "sms": [
                {
                    "id": "sms_001",
                    "gsm": "33612345678",
                    "sent_date": "2026-04-02 14:30:01",
                    "done_date": "2026-04-02 14:30:04",
                    "status": "DELIVERED",
                    "credits": 1,
                    "cancelled": false
                },
                {
                    "id": "sms_002",
                    "gsm": "33698765432",
                    "sent_date": "2026-04-02 14:30:01",
                    "done_date": null,
                    "status": "PENDING",
                    "credits": 1,
                    "cancelled": false
                }
            ]
        }
    ]
}

Statuts de livraison

StatutDescription
DELIVEREDMessage remis au destinataire, confirmé par l'accusé de réception. C'est le statut final attendu.
PENDINGEn attente. Deux cas : le message est parti mais l'accusé de réception n'est pas encore revenu (téléphone éteint, hors réseau), ou il s'agit d'un envoi programmé qui n'est pas encore parti. Statut transitoire : il évolue ensuite vers DELIVERED, UNDELIVERABLE ou EXPIRED.
UNDELIVERABLEMessage non remis : numéro inexistant ou non attribué, terminal incompatible, ou destinataire injoignable de façon définitive.
EXPIREDDélai de validité dépassé : le destinataire est resté injoignable pendant toute la période de tentative de remise. Le message n'a pas été délivré.
REJECTEDMessage refusé avant toute tentative de remise. Causes les plus fréquentes : numéro inscrit en liste STOP, numéro au format invalide, nom d'expéditeur non autorisé, ou filtrage appliqué par l'opérateur du destinataire.
CANCELLEDEnvoi programmé annulé avant son départ, via la route cancel. Les crédits sont restitués : le champ cancelled vaut true et credits repasse à 0.

Cette liste est exhaustive : le champ status ne peut prendre aucune autre valeur. Il n'est jamais null — un message dont l'accusé de réception n'est pas encore parvenu est renvoyé en PENDING.

Seuls DELIVERED, UNDELIVERABLE, EXPIRED, REJECTED et CANCELLED sont des états définitifs. Un message en PENDING doit être réinterrogé ultérieurement pour connaître son issue.

SMS 2-Way (réponses)

POST /api/v2/sms_2way

Récupère les SMS de réponse reçus dans les 3 dernières heures.

Réponse — avec données
{
    "status": "OK",
    "content": [
        {
            "id": 12345,
            "date": "2026-04-02 15:42:00",
            "text": "OK merci",
            "gsm": "33612345678"
        }
    ]
}
Réponse — aucune donnée
{
    "status": "OK",
    "content": [],
    "message": "no data"
}

status: "OK" indique que la requête a réussi. Le champ message est uniquement présent quand aucune donnée n'est retournée.

Exemples d'intégration

cURL (ligne de commande)

Bash
curl -X POST https://www.smsvertpro.com/api/v2/credits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_TOKEN_API"

PHP

PHP
$token = 'VOTRE_TOKEN_API';

$data = [
    'message' => [
        'sender' => 'MonEntreprise',
        'text'   => 'Bonjour, votre colis est en livraison.'
    ],
    'recipients' => ['33612345678']
];

$ch = curl_init('https://www.smsvertpro.com/api/v2/send_sms');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = json_decode(curl_exec($ch));
curl_close($ch);

echo $response->status;  // SEND_OK
echo $response->credits; // 4851

Python

Python
import requests

token = "VOTRE_TOKEN_API"

data = {
    "message": {
        "sender": "MonEntreprise",
        "text": "Bonjour, votre colis est en livraison."
    },
    "recipients": ["33612345678"]
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

r = requests.post("https://www.smsvertpro.com/api/v2/send_sms", json=data, headers=headers)
print(r.json())

C# / .NET

C#
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "VOTRE_TOKEN_API");

var content = new StringContent("{}", Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://www.smsvertpro.com/api/v2/credits", content
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

WinDev (WLangage)

WLangage
sToken est une chaine = "VOTRE_TOKEN_API"

sJSON est une chaine = [
{
    "message": {
        "sender": "MonEntreprise",
        "text": "Bonjour, votre colis est pret."
    },
    "recipients": ["33612345678"]
}
]

cRequete est un httpRequete
cRequete.URL = "https://www.smsvertpro.com/api/v2/send_sms"
cRequete.Methode = httpPost
cRequete.ContentType = "application/json"
cRequete.Entete["Authorization"] = "Bearer " + sToken
cRequete.Contenu = sJSON

cReponse est un httpReponse = HTTPEnvoie(cRequete)

SI cReponse.CodeEtat = 200 ALORS
    sResultat est une chaine = cReponse.Contenu
    Info(sResultat)
FIN

Réponses par campagne

POST /api/v2/responses

Récupère les SMS de réponse reçus, filtrables par campagne.

Paramètres optionnels

ChampTypeDescription
campaign_idstringID de campagne pour filtrer les réponses
Réponse — avec données
{
    "status": "OK",
    "responses": [
        {
            "campaign_id": "camp_001",
            "date": "2026-04-02 16:30:00",
            "gsm": "33612345678",
            "text": "OK merci pour l'info"
        }
    ]
}
Réponse — aucune donnée
{
    "status": "OK",
    "responses": [],
    "message": "no data"
}

Liste noire (STOP SMS)

POST /api/v2/blacklist

Récupère la liste des numéros qui ont envoyé STOP (désinscrits).

Réponse
{
    "status": "OK",
    "blacklist": [
        {
            "gsm": "33612345678",
            "date": "2026-03-15 09:12:00",
            "text": "STOP"
        }
    ]
}

Ajouter un numéro en liste noire

POST /api/v2/add_blacklist

Ajoute manuellement un numéro dans la liste noire du compte. Les numéros blacklistés sont automatiquement exclus de tous vos envois SMS.

Paramètres

ChampTypeRequisDescription
gsmstringOuiNuméro de téléphone au format international (ex: 33612345678)
Requête
{
    "gsm": "33612345678"
}
Réponse
{
    "status": "OK",
    "gsm": "33612345678"
}
Si le numéro est déjà en liste noire, la réponse reste OK avec un champ info précisant que le numéro est déjà présent. Les caractères non numériques (espaces, +, tirets) sont nettoyés automatiquement.

Transfert de crédits

POST /api/v2/transfer

Transfère des crédits SMS du compte master vers un sous-compte.

Paramètres

ChampTypeRequisDescription
emailstringOuiEmail du sous-compte destinataire
idintegerOuiID du sous-compte destinataire (retourné par add_subaccount ou credits)
creditsintegerOuiNombre de crédits à transférer
Requête
{
    "email": "souscompte@email.com",
    "id": 4567,
    "credits": 500
}
Réponse
{
    "status": "OK",
    "message": "transfert effectué",
    "credits": 4352   // solde restant du master
}

Annulation de SMS programmés

POST /api/v2/cancel

Annule un SMS spécifique ou une campagne entière programmée (non encore envoyée).

Paramètres

ChampTypeRequisDescription
campaign_idstringOuiID de la campagne
sms_idstringNonID d'un SMS spécifique (si absent, annule toute la campagne)

Annuler toute une campagne

Requête
{
    "campaign_id": "camp_promo_001"
}

Annuler un SMS spécifique

Requête
{
    "campaign_id": "camp_promo_001",
    "sms_id": "sms_002"
}
Réponse
{
    "status": "CANCEL_OK",
    "credits": 4853   // solde du compte après restitution
}

Seuls les SMS programmés et non encore partis sont annulables ; les crédits correspondants sont immédiatement restitués. Après annulation, le rapport renvoie pour ces SMS le statut CANCELLED, cancelled: true et credits: 0. Un campaign_id ou un sms_id inconnu retourne INVALID_CAMPAIGN ou INVALID_SMS (404).

Si l'envoi visé existe bien mais n'est plus annulable, la réponse est un 409 Conflict qui distingue les deux cas :

StatusHTTPSituation
ALREADY_SENT409Le SMS ou la campagne est déjà parti : il n'y a plus rien à annuler ni à restituer.
ALREADY_CANCELLED409L'annulation a déjà été faite lors d'un appel précédent ; les crédits ont déjà été restitués à ce moment-là.
NOT_CANCELLABLE409L'envoi n'est jamais parti mais n'est plus en attente : il s'est soldé par une erreur d'acheminement. Son statut est consultable dans le rapport.

Sur une campagne partiellement partie, les SMS encore programmés sont annulés normalement et la réponse reste CANCEL_OK ; ALREADY_SENT n'est renvoyé que lorsqu'il ne reste plus aucun SMS annulable.

Créer un sous-compte

POST /api/v2/add_subaccount

Crée un nouveau sous-compte rattaché au compte master.

Paramètres

ChampTypeRequisDescription
emailstringOuiEmail du sous-compte
servicestringOuiNom de la société / service
nomstringOuiNom
prenomstringOuiPrénom
telstringOuiTéléphone (min 6 chiffres)
passstringOuiMot de passe (min 6 caractères, sera hashé en MD5)
Requête
{
    "email": "filiale@example.com",
    "service": "Filiale Lyon",
    "nom": "Dupont",
    "prenom": "Marie",
    "tel": "0612345678",
    "pass": "motdepasse123"
}
Réponse
{
    "status": "OK",
    "id": 4567
}
L'id retourné est nécessaire pour les transferts de crédits vers ce sous-compte.

Générer un OTP

POST /api/v2/generate_otp

Génère un code à usage unique et l'envoie par SMS au numéro indiqué. Le code expire après 5 minutes.

Paramètres

ChampTypeRequisDescription
gsmstringOuiNuméro de téléphone du destinataire
senderstringNonExpéditeur du SMS (défaut: 36173)
Requête
{
    "gsm": "33612345678",
    "sender": "MonApp"
}
Réponse
{
    "status": "OK",
    "result": "OTP_SENT",
    "expires": "2026-04-02 15:05:00"
}
Le code OTP n'est pas retourné dans la réponse API pour des raisons de sécurité. Il est uniquement envoyé par SMS au destinataire. Utilisez ensuite verify_otp pour vérifier le code saisi par l'utilisateur.

Vérifier un OTP

POST /api/v2/verify_otp

Vérifie si le code OTP saisi par l'utilisateur est valide.

Paramètres

ChampTypeRequisDescription
codestringOuiCode OTP saisi par l'utilisateur
gsmstringOuiNuméro de téléphone associé
Requête
{
    "code": "847392",
    "gsm": "33612345678"
}

Réponses possibles

statusresultDescription
OKOTP_TRUECode valide, authentification réussie
OKOTP_VERIFIEDCode déjà utilisé (retourne aussi verified_at)
OTP_FALSE—Code invalide ou expiré (HTTP 401)
Réponse (succès)
{
    "status": "OK",
    "result": "OTP_TRUE"
}
Réponse (déjà utilisé)
{
    "status": "OK",
    "result": "OTP_VERIFIED",
    "verified_at": "2026-04-02 15:02:30"
}

Créer une liste de contacts

POST /api/v2/create_list

Crée une nouvelle liste de contacts vide, prête à recevoir des numéros.

Paramètres

ChampTypeRequisDescription
namestringOuiNom de la liste
Requête
{
    "name": "Clients VIP Mars 2026"
}
Réponse
{
    "status": "OK",
    "liste_id": 123,
    "name": "Clients VIP Mars 2026"
}

Ajouter des contacts à une liste

POST /api/v2/add_contacts

Ajoute un ou plusieurs contacts à une liste existante. Les contacts peuvent être envoyés avec des champs personnalisés (info1 à info5) pour le publipostage.

Paramètres

ChampTypeRequisDescription
liste_idintegerOuiID de la liste
contactsarrayOuiListe des contacts à ajouter

Les contacts peuvent être envoyés sous deux formats :

Format simple (numéros uniquement)
{
    "liste_id": 123,
    "contacts": ["33612345678", "33698765432"]
}
Format avec champs personnalisés
{
    "liste_id": 123,
    "contacts": [
        {
            "gsm": "33612345678",
            "info1": "Marie Dupont",
            "info2": "Paris",
            "info3": "Client VIP"
        },
        {
            "gsm": "33698765432",
            "info1": "Jean Martin",
            "info2": "Lyon"
        }
    ]
}
Réponse
{
    "status": "OK",
    "added": 2,
    "errors": 0
}
Les champs info1 à info5 sont optionnels. Ils peuvent être utilisés pour le publipostage dans vos messages SMS (nom, prénom, ville, etc.). Les numéros sont nettoyés automatiquement (espaces, points, tirets supprimés). L'insertion est optimisée par lots de 500 contacts.

Récupérer les contacts d'une liste

POST /api/v2/get_contacts

Récupère tous les contacts d'une liste, avec pagination optionnelle.

Paramètres

ChampTypeRequisDescription
liste_idintegerOuiID de la liste
limitintegerNonNombre maximum de contacts à retourner (0 = tous)
offsetintegerNonDécalage pour la pagination (défaut: 0)
Requête
{
    "liste_id": 42,
    "limit": 100,
    "offset": 0
}
Réponse
{
    "status": "OK",
    "liste_id": 42,
    "total": 523,
    "count": 100,
    "contacts": [
        {
            "id": 1,
            "gsm": "33612345678",
            "info1": "Jean",
            "info2": "Dupont",
            "info3": "Paris",
            "info4": null,
            "info5": null
        }
    ]
}
Le champ total contient le nombre total de contacts dans la liste, count le nombre retourné dans cet appel. Utilisez limit et offset pour paginer les listes volumineuses.

Modifier un contact

POST /api/v2/update_contact

Modifie le numéro ou les champs personnalisés d'un contact existant.

Paramètres

ChampTypeRequisDescription
liste_idintegerOuiID de la liste
contact_idintegerOuiID du contact
gsmstringNonNouveau numéro
info1 à info5stringNonChamps personnalisés
Requête
{
    "liste_id": 123,
    "contact_id": 4567,
    "gsm": "33699887766",
    "info1": "Marie Martin"
}
Réponse
{
    "status": "OK"
}

Supprimer un contact

POST /api/v2/delete_contact

Supprime un contact d'une liste.

Paramètres

ChampTypeRequisDescription
liste_idintegerOuiID de la liste
contact_idintegerOuiID du contact à supprimer
Requête
{
    "liste_id": 123,
    "contact_id": 4567
}
Réponse
{
    "status": "OK"
}

Supprimer une liste de contacts

POST /api/v2/delete_list

Supprime une liste de contacts ainsi que tous les contacts qu'elle contient. Cette action est irréversible.

Paramètres

ChampTypeRequisDescription
liste_idintegerOuiID de la liste à supprimer
Requête
{
    "liste_id": 123
}
Réponse
{
    "status": "OK",
    "liste_id": 123
}

Vérifier le format des numéros

POST /api/v2/verify_numbers

Vérifie et corrige le format des numéros de téléphone d'une liste de contacts. Identifie les numéros erronés et convertit les numéros français locaux (06/07) au format international (336/337).

Paramètres

ChampTypeRequisDescription
liste_idintegerOuiID de la liste de contacts
actionstringNon"check" (défaut) pour identifier les problèmes, "fix" pour convertir les numéros FR et lister les invalides

Vérifier (check)

Liste les numéros au mauvais format et indique combien sont convertibles automatiquement.

Requête
{
    "liste_id": 42
}
Réponse
{
    "status": "OK",
    "invalid": [
        { "id": 1234, "gsm": "061234" },
        { "id": 1235, "gsm": "abc123" }
    ],
    "nb_invalid": 2,
    "convertible": 15,
    "liste_id": 42
}

convertible indique le nombre de numéros au format local français (06/07) qui seront convertis automatiquement avec l'action "fix".

Corriger (fix)

Convertit les numéros FR au format international et retourne la liste des numéros toujours invalides après conversion.

Requête
{
    "liste_id": 42,
    "action": "fix"
}
Réponse
{
    "status": "OK",
    "converted": 15,
    "invalid": [
        { "id": 1235, "gsm": "abc123" }
    ],
    "nb_invalid": 1
}
Conversions effectuées : 0612345678 → 33612345678, 612345678 → 33612345678. Les espaces, points, tirets et le préfixe +33 sont nettoyés automatiquement. Les numéros déjà au format international ne sont pas modifiés.

Nettoyer les contacts en liste noire

POST /api/v2/clean_blacklist

Identifie et supprime d'une liste de contacts les numéros qui ont envoyé STOP (présents dans votre liste noire). Permet de nettoyer vos listes avant un envoi pour éviter les envois inutiles.

Paramètres

ChampTypeRequisDescription
liste_idintegerOuiID de la liste de contacts
actionstringNon"check" (défaut) pour lister les contacts en liste noire, "delete" pour les supprimer

Vérifier (check)

Requête
{
    "liste_id": 42
}
Réponse
{
    "status": "OK",
    "found": [
        { "id": 1234, "gsm": "33612345678" },
        { "id": 1235, "gsm": "33698765432" }
    ],
    "nb_found": 2,
    "liste_id": 42
}

Supprimer (delete)

Requête
{
    "liste_id": 42,
    "action": "delete"
}
Réponse
{
    "status": "OK",
    "deleted": 2
}
Les contacts en liste noire sont ceux dont le numéro a été enregistré suite à un STOP SMS. Les supprimer de votre liste de contacts évite de les recontacter lors de vos prochaines campagnes.

Dédoublonner une liste de contacts

POST /api/v2/deduplicate

Identifie et supprime les numéros en doublon dans une liste de contacts. Deux modes disponibles : vérification (check) ou suppression (delete).

Paramètres

ChampTypeRequisDescription
liste_idintegerOuiID de la liste de contacts
actionstringNon"check" (défaut) pour lister les doublons, "delete" pour les supprimer

Vérifier les doublons

Requête
{
    "liste_id": 42,
    "action": "check"
}
Réponse
{
    "status": "OK",
    "doublons": [
        { "gsm": "33612345678", "count": 3 },
        { "gsm": "33698765432", "count": 2 }
    ],
    "total": 3,
    "liste_id": 42
}

total indique le nombre de contacts en trop (qui seront supprimés). count est le nombre d'occurrences de chaque numéro.

Supprimer les doublons

Requête
{
    "liste_id": 42,
    "action": "delete"
}
Réponse
{
    "status": "OK",
    "deleted": 3
}
La suppression conserve un exemplaire de chaque numéro et supprime les occurrences en trop. Par exemple, un numéro présent 3 fois sera réduit à 1 seule occurrence.
SMS Vert Pro — API V2 Documentation — 2026