Allo

Obtenir une eSIM

Renvoie le statut d'une eSIM que vous avez commandée, son palier et sa consommation de données mobiles ce mois-ci. Les webhooks partner.esim.ready et…

GET/v2/api/partner/esims/{id}

Renvoie le statut d'une eSIM que vous avez commandée, son palier et sa consommation de données mobiles ce mois-ci. Les webhooks partner.esim.ready et partner.esim.failed vous préviennent quand le statut change. Sans endpoint webhook, interrogez cet endpoint à la place, dans la limite de 20 requêtes de lecture par seconde et par clé.

statusSignification
PROVISIONINGL'eSIM est commandée mais pas encore prête. Cela prend en général 5 à 15 minutes.
ACTIVEL'eSIM est prête. Les appels vers le numéro sonnent sur l'eSIM. Obtenez le code d'activation pour la remettre à votre client.
FAILEDLa commande n'a pas abouti. failure_code en donne la raison.
REVOKEDL'eSIM a été révoquée, ou remplacée par une eSIM plus récente sur le même numéro. Elle ne fonctionne plus sur son téléphone, et les appels vers le numéro sonnent sur les apps Allo.

failure_code vaut null sauf si status vaut FAILED. Vous ne pouvez consulter que les eSIM commandées sur des comptes créés par votre propre clé API. Tout autre id échoue avec PARTNER_ESIM_NOT_FOUND.

Palier

  • tier est le palier actuel de l'eSIM. Il change quand une montée de palier demandée avec Changer le palier d'une eSIM est payée, ou quand une baisse prévue s'applique. D'ici là, c'est le palier commandé.
  • scheduled_tier est le palier vers lequel une baisse prévue fera passer l'eSIM, et scheduled_tier_at la date à laquelle elle s'applique, à la fin de la période déjà payée. Les deux valent null quand aucune baisse n'est prévue.

Consommation de données

data donne la consommation de données mobiles de l'eSIM pour le mois en cours. Il vaut null sauf si status vaut ACTIVE.

ChampSignification
used_mbDonnées mobiles utilisées ce mois-ci, en Mo. null tant que le réseau ne l'a pas encore remontée.
allowance_mbDonnées mobiles dont l'eSIM dispose ce mois-ci, en Mo : les données du palier plus les recharges achetées ce mois-ci.
remaining_mballowance_mb moins used_mb, en Mo, jamais en dessous de 0. null quand used_mb vaut null.
cycle_started_atDébut du mois en cours, en UTC.
cycle_ends_atFin du mois en cours, en UTC. Le mois suivant commence à cette heure-là.
  • Le cycle est le mois civil, à l'heure de Paris. Les dates sont en UTC : en novembre 2026, le cycle va de 2026-10-31T23:00:00 à 2026-11-30T23:00:00.
  • Allo lit la consommation en direct sur le réseau à chaque appel. Elle peut avoir quelques minutes de retard sur l'usage réel.
  • Quand l'eSIM atteint son quota, les données mobiles s'arrêtent jusqu'au mois suivant ou jusqu'à l'achat d'une recharge. Les appels et les SMS continuent de fonctionner. La ligne n'est jamais facturée pour des données au-delà du quota.
  • Allo envoie partner.esim.data_low quand l'eSIM a utilisé 80 % de son quota, et partner.esim.data_exhausted quand elle l'a utilisé en entier. Inutile d'interroger cet endpoint pour surveiller les données.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de chemin

idstringrequis

The eSIM id returned by Order eSIM (eso-*).

Réponses

200eSIM
dataobject
11 champs
idstring

The eSIM id (eso-*).

account_idstring

The account the eSIM was ordered for.

partner_client_refstring | null

Your own reference, set when the account was created.

phone_numberstring

The number the eSIM carries.

tierstring

The eSIM's current tier code. It changes when an upgrade is paid or a scheduled downgrade applies.

statusenum<string>

PROVISIONING: ordered, not ready yet. ACTIVE: ready, calls to the number ring the eSIM. FAILED: the order did not complete, see failure_code. REVOKED: the eSIM was revoked, or replaced by a later eSIM on the same number, and no longer works.

PROVISIONINGACTIVEFAILEDREVOKED

failure_codestring | null

Why the order failed. Set only when status is FAILED.

dataobject | null

Mobile data use for the current cycle, the calendar month in Paris time. null unless status is ACTIVE. Read live from the network on each call: it can lag real use by a few minutes.

5 champs
used_mbinteger<int64> | null

Mobile data used this month, in MB. null when the network has not reported it yet.

allowance_mbinteger<int64>

Mobile data the eSIM can use this month, in MB: the tier's data plus the top-ups bought this month.

remaining_mbinteger<int64> | null

allowance_mb minus used_mb, in MB. null when used_mb is null.

cycle_started_atstring<date-time>

Start of the current cycle, in UTC: midnight on the 1st of the month in Paris time.

cycle_ends_atstring<date-time>

End of the current cycle, in UTC: midnight on the 1st of the next month in Paris time.

created_atstring<date-time>

When the eSIM was ordered.

scheduled_tierstring | null

The tier a scheduled downgrade will switch the eSIM to. null when no downgrade is scheduled.

scheduled_tier_atstring<date-time> | null

When the scheduled downgrade applies: the end of the period already paid. null when no downgrade is scheduled.

401
403The API key lacks the PARTNER scope.
errorobject
404No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND).
errorobject
429