Skip to main content
POST
Add number
Scope requis : PARTNER
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

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.

Autorisations

Authorization
string
header
requis

En-têtes

Idempotency-Key
string

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

Pattern: ^[A-Za-z0-9_-]{8,100}$

Paramètres de chemin

id
string
requis

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

Corps

application/json
country
string
requis

ISO country code.

Exemple:

"FR"

prefix
string | null

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

Exemple:

"7"

esim
boolean | 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.

Exemple:

true

Réponse

Number added

data
object