Allo

Ajouter un numéro

Ajoute un numéro de téléphone à l'un de vos comptes. La réponse renvoie le nouveau numéro et indique s'il a été facturé. Appelez d'abord Obtenir le prix d'un…

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

Ajoute un numéro de téléphone à l'un de vos comptes. La réponse renvoie le nouveau numéro et indique s'il a été facturé. Appelez d'abord Obtenir le prix d'un numéro pour connaître le montant.

Requête

Le corps est une préférence de numéro, identique à number_preference sur Créer un compte :

  • country est requis (code pays ISO, par exemple FR). Un pays inconnu échoue avec INVALID_NUMBER_PREFERENCE.
  • prefix est optionnel : les chiffres par lesquels le numéro doit commencer, par exemple 7 ou +337.
  • esim est optionnel, false par défaut. Passez-le à true pour obtenir un numéro mobile français qui peut porter une eSIM, à commander ensuite avec Commander une eSIM. Avec un country autre que FR, la requête échoue avec ESIM_NOT_AVAILABLE_IN_COUNTRY.

{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.

Facturation

  • Le numéro est facturé sur l'abonnement du compte, que vous payez. 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 débite tout de suite le reste de la période de facturation en cours du compte, avec la remise de l'abonnement appliquée. Le numéro se renouvelle ensuite avec l'abonnement.
  • Si le compte paie déjà un emplacement de numéro qu'aucun numéro n'occupe, le nouveau numéro prend cet emplacement et rien n'est débité. La réponse indique alors charged: false.
  • Allo vérifie qu'un numéro est disponible avant tout débit. Si aucun ne correspond au pays et au préfixe, la requête échoue avec 409 NO_NUMBER_AVAILABLE et rien n'est débité. Un pays qui demande d'abord la vérification réglementaire du compte échoue avec 409 REGULATORY_VERIFICATION_REQUIRED, là aussi avant tout débit.
  • Si votre crédit prépayé ne couvre pas le montant et qu'aucune carte n'est enregistrée, la requête échoue avec 402 PARTNER_CREDIT_INSUFFICIENT et rien n'est créé. Rechargez votre crédit ou ajoutez une carte, puis réessayez avec une nouvelle Idempotency-Key.
  • Une carte refusée échoue avec 402 PARTNER_BILLING_FAILED, et rien n'est créé.
  • Si le numéro ne peut pas être configuré après le débit, Allo retire le montant de l'abonnement et crédite la période non utilisée sur votre solde.

Nouvelles tentatives

Envoyez un en-tête Idempotency-Key (8 à 100 lettres, chiffres, - ou _, par exemple un UUID) et réutilisez-le pour réessayer la même requête. Une nouvelle tentative avec la même clé ne vous débite pas deux fois. Une clé dans un autre format échoue avec INVALID_IDEMPOTENCY_KEY.

Si vous ne savez pas si une tentative précédente a abouti, vérifiez les phone_numbers du compte avec Obtenir un compte avant de réessayer.

Erreurs

CodeSignification
PARTNER_ACCOUNT_BUSYUn autre numéro ou membre est en cours d'ajout sur ce compte. Toujours retryable: true : réessayez dans quelques secondes.
IDEMPOTENCY_KEY_ALREADY_USEDUne tentative précédente a déjà utilisé cette Idempotency-Key. Vérifiez les numéros du compte avec Obtenir un compte avant de réessayer avec une nouvelle clé.
PARTNER_ACCOUNT_DEACTIVATINGLe compte est en cours de désactivation à la fin de sa période de facturation : il ne prend plus de numéros.
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 avec la même Idempotency-Key, qui reprend le même débit.
PARTNER_NUMBER_SETUP_FAILEDLe numéro n'a pas pu être configuré (500), et le débit a été annulé. Ne réessayez pas : écrivez à [email protected].
PARTNER_NUMBER_KEPTLe numéro a été attribué mais sa configuration n'a pas abouti (500). Il reste sur le compte et sur sa facturation. Ne réessayez pas, une nouvelle tentative ajouterait un autre numéro : écrivez à [email protected] en indiquant le numéro.

Réponse

  • phone_number est le nouveau numéro, au format E.164. Il apparaît aussi dans les phone_numbers du compte sur Obtenir un compte.
  • country est le pays tel qu'Allo le nomme : GB revient sous la forme UK.
  • charged vaut true quand un nouvel emplacement a été facturé, false quand le numéro a pris un emplacement déjà payé par le compte.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de chemin

idstringrequis

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

En-têtes

Idempotency-Keystring

Optional. 8 to 100 letters, digits, - or _, for example a UUID. Retrying with the same key does not charge you twice.

Corps

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.

Réponses

201Number added
dataobject
3 champs
phone_numberstring

The number added to the account, in E.164 format.

countrystring

The number's country, as Allo names it (GB is returned as UK).

chargedboolean

false when the number took a slot the account already paid for, true when a new slot was charged.

400Validation error: MISSING_FIELD (country), INVALID_NUMBER_PREFERENCE (unknown country), ESIM_NOT_AVAILABLE_IN_COUNTRY or INVALID_IDEMPOTENCY_KEY.
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).
errorobject
409Nothing is charged for NO_NUMBER_AVAILABLE (no number matches the country and prefix) or REGULATORY_VERIFICATION_REQUIRED (the country needs the account's regulatory verification first). Also IDEMPOTENCY_KEY_ALREADY_USED (an earlier attempt used this key), 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).
errorobject
429
500PARTNER_BILLING_UNAVAILABLE: billing is temporarily unavailable, retry with the same Idempotency-Key. PARTNER_NUMBER_SETUP_FAILED: the number could not be set up, and Allo took the charge back. PARTNER_NUMBER_KEPT: the number was assigned but its setup did not complete, and it stays on the account and its billing. Do not retry these two: write to [email protected].
errorobject