> ## 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. # Order 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. **Required scope:** `PARTNER` Orders an eSIM for one of the account's numbers and charges it to your payment method on file. The response returns the eSIM with status `PROVISIONING`. The eSIM is usually ready 5 to 15 minutes later, and Allo then sends you the [`partner.esim.ready`](/en/v2/api-reference/webhooks/event-catalog#partneresimready) webhook. ## Request * `phone_number` is required. It must be one of the account's numbers, created with `number_preference.esim` set to `true` (see [Create account](/en/v2/api-reference/partner/create-account)). Any other number fails with `PARTNER_ESIM_NUMBER_NOT_FOUND` or `ESIM_NOT_ELIGIBLE`. * `tier` is required: a `code` from [Get eSIM offer](/en/v2/api-reference/partner/get-esim-offer), for example `ESIM_20GB`. An unknown code fails with `INVALID_ESIM_TIER`. * `holder_id` is optional: the Allo user the eSIM is registered to. Leave it out to make the account itself the holder. * `identity` is required: the business the line is registered to. `corporate_name`, `postal_address`, `postal_code` (5 digits) and `city` are required. `first_name`, `last_name`, `company_name`, `siret`, `naf` and `email` are optional. A missing required field fails with `ESIM_IDENTITY_INCOMPLETE`. ## Billing * The setup fee and the first period of the tier are charged to your payment method, on the subscription you pay for the account, with your partner discount applied. Allo never charges your client. * A card that requires 3D Secure is refused with `402 ESIM_PAYMENT_FAILED`, as on [Create account](/en/v2/api-reference/partner/create-account). A missing or declined payment method fails the same way. Nothing is left pending: update your payment method in the [partner portal](/en/support/partner-portal), then retry. * If the subscription you pay for the account cannot take an eSIM right now, the request fails with `ESIM_SUBSCRIPTION_CONFLICT`. When the error is `retryable: true`, retry in a few minutes. ## Retries Send an `Idempotency-Key` header (8 to 100 letters, digits, `-` or `_`, for example a UUID) and reuse it when you retry the same order. Retrying with the same key does not charge you twice. A key in another format fails with `INVALID_IDEMPOTENCY_KEY`. ## Errors specific to this number | Code | What it means | | - | - | | `ESIM_ALREADY_EXISTS` | The number already has an eSIM. Read it with [Get eSIM](/en/v2/api-reference/partner/get-esim). | | `ESIM_ORDER_IN_PROGRESS` | An order for this number is still provisioning. Wait for `partner.esim.ready` or `partner.esim.failed`. | | `ESIM_ORDER_NEEDS_SUPPORT` | A previous order was charged but did not complete, and Allo support is handling it. Write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) before ordering again. | | `PARTNER_ESIM_HOLDER_NOT_FOUND` | `holder_id` cannot hold an eSIM for this number. Leave it out to use the account. | ## 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.