> ## Documentation Index
> Fetch the complete documentation index at: https://help.withallo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ajouter un numéro

> Adds a phone number to one of your accounts. The number is billed on the account's subscription, which you pay: Allo draws on your prepaid credit first, then charges your card on file for the rest. When the account already pays for a number slot that no number uses, the new number takes that slot and nothing is charged (`charged: false`). Allo checks that a number is available before charging anything. Requires the `PARTNER` scope.

<Note>
  **Scope requis :** `PARTNER`
</Note>

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](/fr/v2/api-reference/partner/get-number-price) 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](/fr/v2/api-reference/partner/create-account) :

* `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](/fr/v2/api-reference/partner/order-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é](/fr/v2/api-reference/partner/get-credit), 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](/fr/v2/api-reference/partner/get-account) avant de réessayer.

## Erreurs

| Code | Signification |
| - | - |
| `PARTNER_ACCOUNT_BUSY` | Un autre numéro ou membre est en cours d'ajout sur ce compte. Toujours `retryable: true` : réessayez dans quelques secondes. |
| `IDEMPOTENCY_KEY_ALREADY_USED` | Une tentative précédente a déjà utilisé cette `Idempotency-Key`. Vérifiez les numéros du compte avec [Obtenir un compte](/fr/v2/api-reference/partner/get-account) avant de réessayer avec une nouvelle clé. |
| `PARTNER_ACCOUNT_DEACTIVATING` | Le 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_CONFLICT` | L'abonnement du compte ne peut pas être facturé pour le moment. Si `retryable` vaut `true`, réessayez dans quelques minutes. Sinon, écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). |
| `PARTNER_SUBSCRIPTION_NOT_BILLABLE` | Le compte n'a pas d'abonnement qu'Allo peut facturer (`402`). |
| `PARTNER_BILLING_UNAVAILABLE` | La facturation est temporairement indisponible (`500`). Réessayez avec la même `Idempotency-Key`, qui reprend le même débit. |
| `PARTNER_NUMBER_SETUP_FAILED` | Le numéro n'a pas pu être configuré (`500`), et le débit a été annulé. Ne réessayez pas : écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). |
| `PARTNER_NUMBER_KEPT` | Le 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 à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) 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](/fr/v2/api-reference/partner/get-account).
* `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.


## OpenAPI

````yaml POST /v2/api/partner/accounts/{id}/numbers
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
  - name: AI Receptionist
    description: >-
      Read and write the AI receptionist configuration of a phone line: business
      details, voice, prompt, capabilities, business hours, transfer rules,
      scheduling calendars and knowledge sources.
paths:
  /v2/api/partner/accounts/{id}/numbers:
    post:
      tags:
        - Partner
      summary: Add number
      description: >-
        Adds a phone number to one of your accounts. The number is billed on the
        account's subscription, which you pay: Allo draws on your prepaid credit
        first, then charges your card on file for the rest. When the account
        already pays for a number slot that no number uses, the new number takes
        that slot and nothing is charged (`charged: false`). Allo checks that a
        number is available before charging anything. Requires the `PARTNER`
        scope.
      operationId: addPartnerAccountNumber
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The account id returned by Create account (`usr-*`).
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            pattern: ^[A-Za-z0-9_-]{8,100}$
          description: >-
            Optional. 8 to 100 letters, digits, `-` or `_`, for example a UUID.
            Retrying with the same key does not charge you twice.
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - country
              properties:
                country:
                  type: string
                  description: ISO country code.
                  example: FR
                prefix:
                  type: string
                  nullable: true
                  example: '7'
                  description: >-
                    Optional. Digits the number should start with, after the
                    country code, for example `+337` or `7`.
                esim:
                  type: boolean
                  nullable: true
                  description: >-
                    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`.
                  example: true
            example:
              country: FR
              prefix: '7'
              esim: true
      responses:
        '201':
          description: Number added
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      phone_number:
                        type: string
                        description: The number added to the account, in E.164 format.
                        example: '+33745805222'
                      country:
                        type: string
                        description: >-
                          The number's country, as Allo names it (`GB` is
                          returned as `UK`).
                        example: FR
                      charged:
                        type: boolean
                        description: >-
                          `false` when the number took a slot the account
                          already paid for, `true` when a new slot was charged.
                        example: true
              example:
                data:
                  phone_number: '+33745805222'
                  country: FR
                  charged: true
        '400':
          description: >-
            Validation error: MISSING_FIELD (`country`),
            INVALID_NUMBER_PREFERENCE (unknown country),
            ESIM_NOT_AVAILABLE_IN_COUNTRY or INVALID_IDEMPOTENCY_KEY.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '402':
          description: >-
            Billing 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.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '403':
          description: The API key lacks the PARTNER scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '404':
          description: >-
            No account with this id was provisioned by your API key, or the
            account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '409':
          description: >-
            Nothing 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`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '429':
          $ref: '#/components/responses/ApiRateLimited'
        '500':
          description: >-
            PARTNER_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 partnership@themobilefirst.co.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
      security:
        - ApiKeyAuth: []
components:
  responses:
    ApiUnauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiRateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            request_id:
              type: string
            retry_after_seconds:
              type: integer
              nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.