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

# Commander une eSIM

> Orders an eSIM for one of the account's numbers. The setup fee and the first period of the tier are charged on the subscription you pay for the account: Allo draws on your prepaid credit first, then charges your card on file for the rest. The eSIM is returned with status `PROVISIONING` and is usually ready 5 to 15 minutes later: Allo then sends the `partner.esim.ready` webhook. A number whose eSIM was revoked can get a new eSIM: the order charges the setup fee again. A card that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED`. Requires the `PARTNER` scope.

> [!NOTE]
>
> **Scope requis :** `PARTNER`

Commande une eSIM pour l'un des numéros du compte et la débite sur votre crédit prépayé en priorité, puis sur votre carte enregistrée. La réponse renvoie l'eSIM avec le statut `PROVISIONING`. L'eSIM est en général prête 5 à 15 minutes plus tard, et Allo vous envoie alors le webhook [`partner.esim.ready`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partneresimready).

## Requête

* `phone_number` est requis. Ce doit être l'un des numéros du compte ou de ses membres, créé avec `number_preference.esim` à `true` (voir [Créer un compte](https://help.withallo.com/fr/v2/api-reference/partner/create-account.md), [Ajouter un numéro](https://help.withallo.com/fr/v2/api-reference/white-label/add-number.md) et [Ajouter un membre](https://help.withallo.com/fr/v2/api-reference/white-label/add-member.md)). Tout autre numéro échoue avec `PARTNER_ESIM_NUMBER_NOT_FOUND` ou `ESIM_NOT_ELIGIBLE`.
* `tier` est requis : un `code` renvoyé par [Obtenir l'offre eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim-offer.md), par exemple `ESIM_20GB`. Un code inconnu échoue avec `INVALID_ESIM_TIER`.
* `holder_id` est optionnel : l'utilisateur Allo auquel l'eSIM est rattachée. Omettez-le pour que le compte lui-même en soit le titulaire. Pour le numéro d'un membre, envoyez l'`id` du membre renvoyé par [Ajouter un membre](https://help.withallo.com/fr/v2/api-reference/white-label/add-member.md) ou [Lister les membres](https://help.withallo.com/fr/v2/api-reference/white-label/list-members.md). Cela vaut aussi pour un numéro que le membre a repris avec `phone_number`.
* `identity` est requis : l'entreprise à laquelle la ligne est enregistrée. `corporate_name`, `postal_address`, `postal_code` (5 chiffres) et `city` sont requis. `first_name`, `last_name`, `company_name`, `siret`, `naf` et `email` sont optionnels. Un champ requis manquant échoue avec `ESIM_IDENTITY_INCOMPLETE`.

## Facturation

* Les frais de mise en service et la première période du palier sont facturés sur l'abonnement que vous payez pour le compte, avec votre remise partenaire appliquée. Allo prélève d'abord votre [crédit prépayé](https://help.withallo.com/fr/v2/api-reference/partner/get-credit.md), puis débite le reste sur votre carte enregistrée. Allo ne facture jamais votre client.
* Si votre crédit prépayé ne couvre pas la commande et qu'aucune carte n'est enregistrée, la requête échoue avec `402 PARTNER_CREDIT_INSUFFICIENT`. Rechargez votre crédit ou ajoutez une carte, puis réessayez avec une nouvelle `Idempotency-Key`.
* Une carte qui exige 3D Secure est refusée avec `402 ESIM_PAYMENT_FAILED`. Une carte refusée échoue de la même façon. Rien ne reste en attente : mettez à jour votre carte dans le [portail partenaire](https://help.withallo.com/fr/support/partner-portal.md), puis réessayez.
* Un numéro dont l'eSIM a été [révoquée](https://help.withallo.com/fr/v2/api-reference/white-label/revoke-esim.md) peut recevoir une nouvelle eSIM. La nouvelle commande facture à nouveau les frais de mise en service. Si vous la passez juste après la révocation, elle reste `PROVISIONING` jusqu'à ce que le réseau mobile ait confirmé la révocation.
* Si l'abonnement que vous payez pour le compte ne peut pas recevoir d'eSIM pour le moment, la requête échoue avec `ESIM_SUBSCRIPTION_CONFLICT`. Si l'erreur indique `retryable: true`, réessayez dans quelques minutes.

## 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 commande. 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`.

## Erreurs propres au numéro

| Code | Signification |
| - | - |
| `ESIM_ALREADY_EXISTS` | Le numéro a déjà une eSIM non révoquée. Consultez-la avec [Obtenir une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim.md), ou [révoquez-la](https://help.withallo.com/fr/v2/api-reference/white-label/revoke-esim.md) pour en commander une nouvelle. |
| `ESIM_ORDER_IN_PROGRESS` | Une commande pour ce numéro est encore en cours de provisionnement. Attendez `partner.esim.ready` ou `partner.esim.failed`. |
| `ESIM_ORDER_NEEDS_SUPPORT` | Une précédente commande a été débitée sans aboutir, et le support Allo la traite. Écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) avant de commander à nouveau. |
| `PARTNER_ESIM_HOLDER_NOT_FOUND` | `holder_id` ne peut pas détenir d'eSIM pour ce numéro. Omettez-le pour utiliser le compte. |


## OpenAPI

````yaml POST /v2/api/partner/accounts/{account_id}/esims
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: Fax
    description: >-
      Send a PDF as a fax from an Allo line with fax turned on. Sent and
      received faxes appear in conversation items.
  - 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.
  - name: Inboxes
    description: >-
      Personal inboxes: saved views of one or more lines, optionally narrowed to
      phone-menu options, with their own filters and notification setting.
paths:
  /v2/api/partner/accounts/{account_id}/esims:
    post:
      tags:
        - White label
      summary: Order eSIM
      description: >-
        Orders an eSIM for one of the account's numbers. The setup fee and the
        first period of the tier are charged on the subscription you pay for the
        account: Allo draws on your prepaid credit first, then charges your card
        on file for the rest. The eSIM is returned with status `PROVISIONING`
        and is usually ready 5 to 15 minutes later: Allo then sends the
        `partner.esim.ready` webhook. A number whose eSIM was revoked can get a
        new eSIM: the order charges the setup fee again. A card that requires 3D
        Secure is refused with `ESIM_PAYMENT_FAILED`. Requires the `PARTNER`
        scope.
      operationId: orderPartnerEsim
      parameters:
        - name: account_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:
                - phone_number
                - tier
                - identity
              properties:
                phone_number:
                  type: string
                  description: >-
                    One of the account's numbers that can carry an eSIM:
                    created, added or given to a member with
                    `number_preference.esim` set to `true`.
                  example: '+33745805999'
                tier:
                  type: string
                  description: A tier `code` from Get eSIM offer.
                  example: ESIM_20GB
                holder_id:
                  type: string
                  nullable: true
                  description: >-
                    Optional. The Allo user the eSIM is registered to: the
                    account itself by default, or the `id` of a member returned
                    by Add member for the member's own number, including a
                    number the member took over with `phone_number`.
                  example: null
                identity:
                  type: object
                  description: The business the line is registered to.
                  required:
                    - corporate_name
                    - postal_address
                    - postal_code
                    - city
                  properties:
                    corporate_name:
                      type: string
                      example: Plomberie Martin
                    postal_address:
                      type: string
                      example: 12 rue de la Paix
                    postal_code:
                      type: string
                      description: 5 digits.
                      example: '75001'
                    city:
                      type: string
                      example: Paris
                    first_name:
                      type: string
                      nullable: true
                      example: Jean
                    last_name:
                      type: string
                      nullable: true
                      example: Martin
                    company_name:
                      type: string
                      nullable: true
                      example: Plomberie Martin
                    siret:
                      type: string
                      nullable: true
                      example: '12345678900012'
                    naf:
                      type: string
                      nullable: true
                      example: 4322A
                    email:
                      type: string
                      nullable: true
                      example: jean@plomberie-martin.fr
            example:
              phone_number: '+33745805999'
              tier: ESIM_20GB
              identity:
                corporate_name: Plomberie Martin
                postal_address: 12 rue de la Paix
                postal_code: '75001'
                city: Paris
                first_name: Jean
                last_name: Martin
                email: jean@plomberie-martin.fr
      responses:
        '201':
          description: eSIM ordered
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The eSIM id (`eso-*`).
                        example: eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61
                      account_id:
                        type: string
                        description: The account the eSIM was ordered for.
                        example: usr-575966AF3661061265263C58882BC409D2A427B8
                      partner_client_ref:
                        type: string
                        nullable: true
                        description: Your own reference, set when the account was created.
                        example: crm-12345
                      phone_number:
                        type: string
                        description: The number the eSIM carries.
                        example: '+33745805999'
                      tier:
                        type: string
                        description: The tier code that was ordered.
                        example: ESIM_20GB
                      scheduled_tier:
                        type: string
                        nullable: true
                        description: >-
                          The tier a scheduled downgrade will switch the eSIM
                          to. Always `null` on a new order.
                        example: null
                      scheduled_tier_at:
                        type: string
                        format: date-time
                        nullable: true
                        description: >-
                          When the scheduled downgrade applies. Always `null` on
                          a new order.
                        example: null
                      status:
                        type: string
                        enum:
                          - PROVISIONING
                          - ACTIVE
                          - FAILED
                          - REVOKED
                        description: >-
                          `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.
                        example: PROVISIONING
                      failure_code:
                        type: string
                        nullable: true
                        description: >-
                          Why the order failed. Set only when `status` is
                          `FAILED`.
                        example: null
                      data:
                        type: object
                        nullable: true
                        description: >-
                          Mobile data use this month. Always `null` here, since
                          a new eSIM is not `ACTIVE` yet: read it with Get eSIM
                          once the eSIM is ready.
                        example: null
                      created_at:
                        type: string
                        format: date-time
                        description: When the eSIM was ordered.
                        example: '2026-10-14T10:05:00'
              example:
                data:
                  id: eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61
                  account_id: usr-575966AF3661061265263C58882BC409D2A427B8
                  partner_client_ref: crm-12345
                  phone_number: '+33745805999'
                  tier: ESIM_20GB
                  scheduled_tier: null
                  scheduled_tier_at: null
                  status: PROVISIONING
                  failure_code: null
                  data: null
                  created_at: '2026-10-14T10:05:00'
        '400':
          description: >-
            Validation error: MISSING_FIELD, INVALID_ESIM_TIER,
            ESIM_IDENTITY_INCOMPLETE 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 left pending. PARTNER_CREDIT_INSUFFICIENT:
            your prepaid credit does not cover the order and your billing
            account has no card on file. ESIM_PAYMENT_FAILED: your card was
            declined or requires 3D Secure.
          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: >-
            The account was not provisioned by your API key
            (PARTNER_ACCOUNT_NOT_FOUND), the number does not belong to the
            account (PARTNER_ESIM_NUMBER_NOT_FOUND), or `holder_id` cannot hold
            an eSIM for this number (PARTNER_ESIM_HOLDER_NOT_FOUND).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '409':
          description: >-
            The number cannot carry an eSIM (ESIM_NOT_ELIGIBLE), already has an
            eSIM that is not revoked (ESIM_ALREADY_EXISTS), has an order in
            progress (ESIM_ORDER_IN_PROGRESS) or one handled by Allo support
            (ESIM_ORDER_NEEDS_SUPPORT), or the subscription you pay for the
            account cannot take an eSIM right now (ESIM_SUBSCRIPTION_CONFLICT).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '429':
          $ref: '#/components/responses/ApiRateLimited'
        '500':
          description: >-
            eSIMs cannot be ordered for this account right now
            (ESIM_UNAVAILABLE).
          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.