Signlift

SMS transactionnels

Envoyer un SMS d'un seul segment et suivre son acheminement.

POST /api/v1/sms_messages

Enregistre un SMS d'un seul segment. La réponse est rendue avant l'envoi : le status évolue ensuite de façon asynchrone, lisez-le avec le GET ci-dessous.

Le service est activé sur demande, pour les organisations Pro et Entreprise. Tant qu'il ne l'est pas, l'appel répond 403 sms_service_disabled, y compris en sandbox.

Headers

HeaderRequisValeur
X-Api-Key✓Votre clé API.
Content-Type✓application/json

Body

ChampTypeRequisDescription
tostring✓Numéro au format E.164. Refusé s'il est reconnu comme non mobile (fixe, numéro vert...). Un type inconnu est accepté.
bodystring✓Texte d'un seul segment : alphabet GSM-7, 160 septets au plus. € [ ] { } \ ^ ~ | comptent double.
senderstring✓Un des expéditeurs déclarés pour votre organisation. Comparé sans tenir compte de la casse, jamais remplacé par Signlift.
referencestringClé d'idempotence, chaîne de 100 caractères au plus, unique pour toute la vie de l'application. Voir Idempotence.
resendbooleantrue quand ce message renvoie un SMS que le destinataire n'a pas reçu. Voir Renvoi.

Un champ qui n'est pas une chaîne (nombre, tableau, objet) est lu comme absent.

Exemple

curl https://app.signlift.eu/api/v1/sms_messages \
  -H "X-Api-Key: $SIGNLIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+33612345678",
    "body": "Votre colis arrive demain entre 9h et 12h.",
    "sender": "Signlift",
    "reference": "order-1042"
  }'

Réponse 202

{
  "id": "sms_k3Jx9aPq2LmN7vRt5BwYc8Zd",
  "status": "queued",
  "to": "+33612345678",
  "sender": "Signlift",
  "country": "FR",
  "unit_price": 0.08,
  "currency": "EUR",
  "reference": "order-1042",
  "resend": false,
  "environment": "production",
  "created_at": "2026-11-12T08:30:00Z"
}
  • id est un identifiant opaque : conservez-le pour suivre le message.
  • sender renvoie le nom tel qu'il est déclaré, quelle que soit la casse envoyée.
  • country est déduit du numéro.
  • unit_price est le prix facturé du SMS dans currency, remise éventuelle de l'organisation comprise, figé à la création : une évolution ultérieure des tarifs ou de la remise ne touche pas les messages déjà enregistrés. Il peut valoir 0 quand les SMS sont offerts. Pour une organisation Entreprise, dont les prix sont fixés par contrat, unit_price et currency valent null.
  • En sandbox, status vaut simulated dès la réponse et environment vaut sandbox.

Réponse 200

Rejouer l'appel avec la même reference et les mêmes to, body, sender et resend renvoie le message existant avec un 200, sans nouvel envoi.

Idempotence

La reference est unique par application. Deux clés d'une même application partagent donc leurs références ; deux applications distinctes, non.

AppelRésultat
Même reference, mêmes to, body, sender et resend200, message existant, aucun envoi
Même reference, autre to, body, sender ou resend409 reference_conflict
Deux appels simultanés avec la même referenceUn seul message ; l'autre appel reçoit 200 (ou 409 si son contenu diffère)

La comparaison du contenu porte sur les valeurs telles que vous les envoyez : rejouer avec un sender dont la casse diffère donne 409, même si les deux désignent le même expéditeur.

Un rejeu passe même si le plafond mensuel est atteint, même si l'expéditeur a été supprimé depuis. Il ne passe pas si le service a été désactivé : sms_service_disabled est contrôlé avant tout.

GET /api/v1/sms_messages/{id}

Lit un message et son état d'acheminement. La lecture reste possible après une désactivation du service, pour suivre les accusés de réception des messages déjà enregistrés.

Exemple

curl https://app.signlift.eu/api/v1/sms_messages/sms_k3Jx9aPq2LmN7vRt5BwYc8Zd \
  -H "X-Api-Key: $SIGNLIFT_API_KEY"

Réponse 200

{
  "id": "sms_k3Jx9aPq2LmN7vRt5BwYc8Zd",
  "status": "delivered",
  "to": "+33612345678",
  "sender": "Signlift",
  "country": "FR",
  "unit_price": 0.08,
  "currency": "EUR",
  "reference": "order-1042",
  "resend": false,
  "environment": "production",
  "created_at": "2026-11-12T08:30:00Z",
  "provider": "twilio",
  "sent_at": "2026-11-12T08:30:04Z",
  "delivered_at": "2026-11-12T08:30:09Z",
  "failure_reason": null
}

Les champs de la création, plus :

ChampTypeDescription
providerstring ou nullsms_mode ou twilio : l'opérateur qui a pris le message. null tant qu'aucun ne l'a pris.
sent_atstring ou nullDate d'acceptation par l'opérateur.
delivered_atstring ou nullDate de l'accusé de livraison.
failure_reasonstring ou nullCause d'un échec. Voir Statuts.

Périmètre de lecture

Une clé lit les messages de son organisation et de son environnement, créés par l'API. Une autre clé de la même organisation et du même environnement lit donc les mêmes messages.

Tout le reste répond 404 not_found : un message d'une autre organisation, de l'autre environnement, un identifiant inconnu, ou un identifiant de SMS de code de signature (ceux-ci ne sont jamais visibles par l'API).

Purge des données personnelles

DonnéeEffacée
Le texte7 jours après sent_at (à défaut, après la création)
Le numéro30 jours après la création

La purge est une tâche quotidienne, à 00:35 UTC : l'effacement peut intervenir jusqu'à un jour après ces délais. Après la purge du numéro, to vaut null.

L'API ne renvoie jamais le texte (body), ni avant ni après la purge : conservez-le de votre côté si vous en avez besoin.

Statuts et causes d'échec

statusSignificationFacturé
queuedEnregistré, pas encore pris en charge.non
sendingPris en charge, issue pas encore connue.non
sentAccepté par un opérateur.oui
deliveredAccusé de livraison reçu.oui
undeliveredAccepté par un opérateur puis non livré.oui
failedAucun opérateur ne l'a pris, ou l'issue est restée inconnue. failure_reason en donne la cause.non
simulatedSandbox : aucun appel à un opérateur.non

failure_reason prend l'une de ces valeurs :

failure_reasonPosée surSignification
expiredfailedNon pris en charge environ 15 minutes après la création.
outcome_unknownfailedPris en charge, mais aucune issue environ 1 heure après.
no_providerfailedAucun opérateur disponible pour ce message.
invalid_recipientfailed ou undeliveredNuméro refusé ou désabonné.
sender_unavailablefailedExpéditeur utilisable par aucun opérateur pour ce pays.
unsupported_destinationfailedDestination non desservie.
provider_unavailablefailedOpérateurs indisponibles.
insufficient_creditfailedCrédit insuffisant chez l'opérateur.
undeliverableundeliveredNon livré par l'opérateur.
unknown_failureundeliveredCause non précisée.

failure_reason n'est donc pas réservé à failed : un message undelivered en porte aussi une.

Les délais de expired et outcome_unknown sont approximatifs : la tâche qui les pose tourne toutes les 5 minutes.

Signlift ne renvoie jamais automatiquement un message dont l'issue est inconnue. Le renvoyer, avec une nouvelle reference, est votre décision.

Renvoi

Quand le destinataire dit ne pas avoir reçu un SMS (un bouton « Renvoyer », par exemple), envoyez un nouveau message avec resend: true (booléen JSON). Vous n'avez rien à conserver du premier envoi : Signlift le retrouve.

Un SMS non reçu vient souvent d'un problème sur le chemin qu'il a emprunté : opérateur intermédiaire, filtrage, réseau du destinataire. Un nouvel envoi sans resend reprend le même chemin et peut échouer de la même façon ; avec resend: true, il passe par un autre opérateur.

Le renvoi peut porter un autre body, par exemple un nouveau code : Signlift retrouve le SMS précédent par son destinataire, pas par son texte.

Utilisez-le aussi quand votre suivi montre undelivered : l'opérateur a refusé le message, un autre a ses chances. Pour un failed dont l'issue est inconnue, le premier SMS a peut-être été reçu : renvoyer reste votre décision.

Au moment de l'envoi, Signlift prend le dernier SMS d'API de votre organisation vers ce to, dans l'environnement de la clé et les 30 minutes précédentes, qu'un opérateur a pris en charge, et envoie d'abord par l'autre opérateur. Deux renvois successifs alternent donc d'opérateur.

La réponse porte resend: true quand un SMS précédent vers ce numéro existe dans les 30 minutes, et false sinon : le message part alors comme un premier envoi. resend: true ne garantit pas un autre opérateur. Le renvoi repart par le même quand :

  • le pays ou l'expéditeur n'est desservi que par un opérateur ;
  • le SMS précédent n'a encore été pris en charge par aucun opérateur, ou son issue reste inconnue.

En sandbox, resend est accepté mais sans effet : aucun opérateur n'est appelé.

Un renvoi est facturé et compte dans le plafond mensuel comme tout message. Signlift ne limite pas leur nombre : temporisez le bouton de votre côté.

Ordre des contrôles

Un appel POST est contrôlé dans cet ordre, et la première règle violée détermine l'erreur :

  1. service activé (403 sms_service_disabled) ;
  2. type et longueur de la reference, type de resend (422 validation_error) ;
  3. rejeu de la reference (200, ou 409 reference_conflict) ;
  4. expéditeur (unknown_sender) ;
  5. numéro (invalid_recipient), puis numéro marqué injoignable (invalid_recipient) ;
  6. texte (invalid_body) ;
  7. destination avec un prix (unsupported_destination), puis routage (unsupported_destination, sender_unavailable, 503 sms_temporarily_unavailable) ;
  8. plafond mensuel, en production seulement (403 sms_quota_exceeded).

Un numéro que tous les opérateurs ont signalé injoignable (refusé, désabonné) est refusé en invalid_recipient pendant 7 jours.

Erreurs

HTTPCodeCas
403sms_service_disabledService non activé, ou plan non éligible.
403sms_quota_exceededPlafond mensuel atteint. Pas de Retry-After : il se lève au mois suivant ou si Signlift relève le plafond.
409reference_conflictreference déjà utilisée avec un autre to, body, sender ou resend.
422invalid_recipientNuméro invalide, non mobile, ou marqué injoignable.
422unsupported_destinationPays exclu (États-Unis, Canada, Porto Rico, Guam, îles Vierges américaines, Samoa américaines, Mariannes du Nord, îles mineures éloignées des États-Unis), sans prix ou non desservi.
422invalid_bodyTexte vide ou de plus de 160 septets, ou caractères hors GSM-7 (listés dans le message).
422unknown_senderExpéditeur absent de la liste de l'organisation.
422sender_unavailableExpéditeur utilisable par aucun opérateur du pays.
422validation_errorreference qui n'est pas une chaîne, ou de plus de 100 caractères ; resend qui n'est pas un booléen JSON.
503sms_temporarily_unavailableAucun opérateur ne peut prendre un message vers ce numéro pour l'instant. Rien n'est enregistré : rejouez le même appel après le délai de l'en-tête Retry-After, en secondes.

Les erreurs communes à toute l'API (401, 402, 429) sont décrites dans la vue d'ensemble. Le GET répond en plus 404 not_found, comme décrit plus haut.

Les appels en erreur, comme les appels réussis, sont comptés dans le rate-limit de l'organisation.

On this page