Allo

Ajouter un membre

Ajoute un collaborateur à l'un de vos comptes, avec son propre numéro de téléphone : un nouveau numéro, ou un numéro que le compte détient déjà, que le…

POST/v2/api/partner/accounts/{id}/members

Ajoute un collaborateur à l'un de vos comptes, avec son propre numéro de téléphone : un nouveau numéro, ou un numéro que le compte détient déjà, que le membre reprend avec son historique. La réponse renvoie le membre, dont l'id qui sert à commander son eSIM.

Requête

  • email est requis et devient l'identifiant de connexion du membre.
  • name est requis.
  • personal_mobile est optionnel, au format E.164, par exemple +33612345679. Un numéro illisible échoue avec INVALID_PHONE_NUMBER.
  • role est optionnel : ADMIN, MANAGER ou MEMBER, MEMBER par défaut. Toute autre valeur échoue avec INVALID_MEMBER_ROLE.
  • number_preference donne au membre un nouveau numéro, avec les mêmes champs que sur Créer un compte. number_preference.country est requis. Passez number_preference.esim à true pour donner au membre un numéro mobile français qui peut porter une eSIM.
  • phone_number donne plutôt au membre un numéro que le compte détient déjà, au format E.164. Voir Comment donner au membre un numéro existant.
  • Envoyez soit number_preference, soit phone_number. Envoyer les deux échoue avec 400 PARTNER_MEMBER_NUMBER_CHOICE_CONFLICT. N'envoyer aucun des deux échoue avec MISSING_FIELD.
  • Si l'email ou le mobile personnel appartient déjà à un compte Allo, la requête échoue avec 409 PARTNER_ACCOUNT_ALREADY_EXISTS, et param indique le champ concerné.

{id} est l'identifiant du compte renvoyé par Créer un compte. Un compte que votre API key n'a pas créé, ou déjà désactivé, renvoie 404 PARTNER_ACCOUNT_NOT_FOUND.

Ce que fait Allo

  • Allo crée le membre dans le workspace du compte et lui attribue son numéro, ou lui transfère le phone_number.
  • Allo n'envoie aucun email d'invitation au membre. C'est vous qui l'accompagnez. Le membre se connecte à Allo avec l'email (ou le mobile personnel) que vous avez envoyé, et activated passe à true dès sa première connexion sur un appareil.
  • Le membre occupe un siège sur l'abonnement du compte. Ce siège inclut son numéro : le numéro n'est pas facturé en plus.

Facturation

  • Si le compte paie déjà un siège que personne n'occupe, le membre le prend et rien n'est débité.
  • Sinon, Allo ajoute un siège à l'abonnement du compte, que vous payez, et débite tout de suite le reste de la période de facturation en cours, avec la remise de l'abonnement appliquée. Allo prélève d'abord votre crédit prépayé, puis débite le reste sur votre carte enregistrée. Allo ne facture jamais votre client.
  • Allo vérifie l'email, le mobile personnel et le numéro avant tout débit. Si aucun numéro ne correspond, la requête échoue avec 409 NO_NUMBER_AVAILABLE et rien n'est débité.
  • Si votre crédit prépayé ne couvre pas le siège et qu'aucune carte n'est enregistrée, la requête échoue avec 402 PARTNER_CREDIT_INSUFFICIENT et rien n'est créé. Une carte refusée échoue avec 402 PARTNER_BILLING_FAILED.
  • Si le numéro du membre ne peut pas être configuré après le débit, Allo supprime le membre et retire le siège de l'abonnement.

Comment donner au membre un numéro existant

Envoyez phone_number pour donner au membre un numéro que le compte détient lui-même, par exemple un numéro conservé d'un membre retiré. Le numéro passe du compte au membre avec son historique d'appels et de messages.

  • Le numéro doit faire partie des phone_numbers du compte renvoyés par Obtenir un compte, et être détenu par le compte lui-même, pas par un membre. Tout autre numéro échoue avec 404 PARTNER_ACCOUNT_NUMBER_NOT_FOUND.
  • Si le numéro a encore une eSIM non révoquée, la requête échoue avec 409 PARTNER_NUMBER_HAS_LIVE_ESIM. Révoquez l'eSIM d'abord, pour que le téléphone de l'ancien titulaire ne sonne jamais pour le nouveau membre. Retirer un membre la révoque pour vous.
  • Le siège est facturé comme pour tout nouveau membre. Comme le siège inclut le numéro, Allo retire aussi un numéro supplémentaire de l'abonnement du compte, si le compte en paie un dont il n'a plus besoin, sans prorata.
  • Le membre ne reçoit pas d'eSIM. Pour lui en donner une, appelez Commander une eSIM avec le numéro comme phone_number et l'id du membre comme holder_id. La nouvelle eSIM facture les frais de mise en service.

L'endpoint ne prend pas d'Idempotency-Key. Si une requête expire, consultez Lister les membres avant de réessayer : une fois le membre créé, une nouvelle tentative avec le même email échoue avec PARTNER_ACCOUNT_ALREADY_EXISTS.

Comment donner une eSIM au membre

Ajoutez le membre avec un numéro eSIM

Envoyez number_preference: {"country": "FR", "esim": true}. Le membre reçoit un numéro mobile français qui peut porter une eSIM, listé dans phone_numbers.

Commandez l'eSIM pour le membre

Appelez Commander une eSIM sur le même compte (POST /v2/api/partner/accounts/{account_id}/esims). Envoyez le numéro du membre comme phone_number et l'id du membre comme holder_id. L'eSIM est alors rattachée au membre, et non au compte.

Remettez l'eSIM

Attendez partner.esim.ready, puis envoyez au membre le code de Obtenir le code d'activation d'une eSIM.

Erreurs

CodeSignification
PARTNER_ACCOUNT_NUMBER_NOT_FOUNDLe compte ne détient pas lui-même phone_number : le numéro n'est pas sur le compte, ou un membre le détient (404).
PARTNER_NUMBER_HAS_LIVE_ESIMphone_number a encore une eSIM non révoquée (409). Révoquez-la avec Révoquer une eSIM, puis réessayez.
PARTNER_MEMBER_NUMBER_CHOICE_CONFLICTLa requête envoie à la fois phone_number et number_preference (400). Envoyez l'un des deux.
REGULATORY_VERIFICATION_REQUIREDUn numéro dans ce pays demande d'abord la vérification réglementaire du compte. Rien n'est débité.
PARTNER_ACCOUNT_BUSYUn autre numéro ou membre est en cours d'ajout sur ce compte, ou cet email est en cours d'ajout ailleurs. Toujours retryable: true : réessayez dans quelques secondes.
PARTNER_ACCOUNT_DEACTIVATINGLe compte est en cours de désactivation à la fin de sa période de facturation : il ne prend plus de membres.
PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICTL'abonnement du compte ne peut pas être facturé pour le moment. Si retryable vaut true, réessayez dans quelques minutes. Sinon, écrivez à [email protected].
PARTNER_SUBSCRIPTION_NOT_BILLABLELe compte n'a pas d'abonnement qu'Allo peut facturer (402).
PARTNER_BILLING_UNAVAILABLELa facturation est temporairement indisponible (500). Réessayez dans quelques secondes.
PARTNER_NUMBER_SETUP_FAILEDLe numéro du membre n'a pas pu être configuré (500). Le membre et le débit ont été annulés. Écrivez à [email protected].
PARTNER_NUMBER_KEPTLe numéro a été attribué mais sa configuration n'a pas abouti (500). Il reste sur le compte avec le siège du membre. Ne réessayez pas : écrivez à [email protected] en indiquant le numéro.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de chemin

idstringrequis

The account id returned by Create account (usr-*).

Corps

emailstringrequis

Becomes the member's login. It must not belong to an Allo account yet.

namestringrequis
personal_mobilestring | null

Optional, E.164. The member's own mobile. It must not belong to an Allo account yet.

roleenum<string>

Optional, default MEMBER. The member's role in the account's workspace.

ADMINMANAGERMEMBER

number_preferenceobject

The member's new number. Required unless you send phone_number. Do not send both.

3 champs
countrystringrequis

ISO country code.

prefixstring | null

Optional. Digits the number should start with, after the country code, for example +337 or 7.

esimboolean | null

Optional, default false. Set to true to get a French mobile number that can carry an eSIM, which you can then order with POST /v2/api/partner/accounts/{account_id}/esims. eSIM numbers are only available with country set to FR, otherwise the request fails with ESIM_NOT_AVAILABLE_IN_COUNTRY.

phone_numberstring | null

A number the account holds itself, for example one kept from a removed member, in E.164 format. The member takes it over, with its call and message history, instead of getting a new number. Send either phone_number or number_preference, not both. If the number had an eSIM, revoke it first, then order a new eSIM for the member with holder_id.

Réponses

201Member added
dataobject
8 champs
idstring

The member's user id (usr-*). Pass it as holder_id to Order eSIM to register the member's eSIM to the member.

account_idstring

The account the member was added to.

emailstring

The member's login.

namestring
roleenum<string>

ADMINMANAGERMEMBER

phone_numbersstring[]

The member's own numbers.

statusstring

The member's status: ACTIVE, or SUSPENDED while the account is suspended with Suspend account.

activatedboolean

True once the member has signed in on a device.

400Validation error: MISSING_FIELD (email, name, number_preference or number_preference.country), INVALID_PHONE_NUMBER (personal_mobile or phone_number), INVALID_MEMBER_ROLE, INVALID_NUMBER_PREFERENCE, ESIM_NOT_AVAILABLE_IN_COUNTRY, or PARTNER_MEMBER_NUMBER_CHOICE_CONFLICT (both phone_number and number_preference were sent).
errorobject
401
402Billing error, nothing is created. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. PARTNER_BILLING_FAILED: your card was declined. PARTNER_SUBSCRIPTION_NOT_BILLABLE: the account has no subscription Allo can bill.
errorobject
403The API key lacks the PARTNER scope.
errorobject
404No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND), or the account does not hold the phone_number itself: it is not on the account, or a member holds it (PARTNER_ACCOUNT_NUMBER_NOT_FOUND).
errorobject
409Nothing is charged for PARTNER_ACCOUNT_ALREADY_EXISTS (the email or personal mobile already belongs to an Allo account), NO_NUMBER_AVAILABLE or REGULATORY_VERIFICATION_REQUIRED. Also PARTNER_ACCOUNT_BUSY (another number or member is being added to the account, retryable: true), PARTNER_ACCOUNT_DEACTIVATING (the account is being deactivated) or PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT (the account's subscription cannot be billed right now; retry when retryable is true). PARTNER_NUMBER_HAS_LIVE_ESIM: the phone_number still has an eSIM that is not revoked; revoke it with POST /v2/api/partner/esims/{id}/revoke first.
errorobject
429
500PARTNER_BILLING_UNAVAILABLE: billing is temporarily unavailable, retry in a few seconds. PARTNER_NUMBER_SETUP_FAILED: the member's number could not be set up, and the member and the charge were removed. PARTNER_NUMBER_KEPT: the number was assigned but its setup did not complete, and it stays on the account with the member's seat. Do not retry these two: write to [email protected].
errorobject