> ## 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 to your payment method on file, on the subscription you pay for the account. 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 card that requires 3D Secure is refused with `ESIM_PAYMENT_FAILED`. Requires the `PARTNER` scope. **Scope requis :** `PARTNER` Commande une eSIM pour l'un des numéros du compte et la débite sur votre moyen de paiement enregistré. 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`](/fr/v2/api-reference/webhooks/event-catalog#partneresimready). ## Requête * `phone_number` est requis. Ce doit être l'un des numéros du compte, créé avec `number_preference.esim` à `true` (voir [Créer un compte](/fr/v2/api-reference/partner/create-account)). 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](/fr/v2/api-reference/partner/get-esim-offer), 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. * `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 débités sur votre moyen de paiement, sur l'abonnement que vous payez pour le compte, avec votre remise partenaire appliquée. Allo ne facture jamais votre client. * Une carte qui exige 3D Secure est refusée avec `402 ESIM_PAYMENT_FAILED`, comme sur [Créer un compte](/fr/v2/api-reference/partner/create-account). Un moyen de paiement absent ou refusé échoue de la même façon. Rien ne reste en attente : mettez à jour votre moyen de paiement dans le [portail partenaire](/fr/support/partner-portal), puis réessayez. * 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. Consultez-la avec [Obtenir une eSIM](/fr/v2/api-reference/partner/get-esim). | | `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: 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/{account_id}/esims: post: tags: - Partner 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 to your payment method on file, on the subscription you pay for the account. 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 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, created 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. Defaults to the account itself. 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 status: type: string enum: - PROVISIONING - ACTIVE - FAILED description: >- `PROVISIONING`: ordered, not ready yet. `ACTIVE`: ready, calls to the number ring the eSIM. `FAILED`: the order did not complete, see `failure_code`. example: PROVISIONING failure_code: type: string nullable: true description: >- Why the order failed. Set only when `status` is `FAILED`. 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 status: PROVISIONING failure_code: 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: >- Allo could not charge your payment method (ESIM_PAYMENT_FAILED): no default payment method, a declined card, or a card that requires 3D Secure. Nothing is left pending. 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 one (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.