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

# Revoke eSIM

> Revokes an eSIM right away: it stops working on its phone for good. The number stays on the account, keeps its history and rings the Allo apps instead. The eSIM's data tier ends now. To put the number on a phone again, order a new eSIM for it, which charges the setup fee. Idempotent: revoking an eSIM that is already `REVOKED` returns it unchanged. Requires the `PARTNER` scope.

> [!NOTE]
>
> **Required scope:** `PARTNER`

Revokes an eSIM right away: it stops working on its phone for good, for example when the phone is lost or its holder leaves. The response returns the eSIM with status `REVOKED`.

## What happens to the number

* The number stays on the account, with the same owner and its call and message history.
* Calls to the number ring the Allo apps instead of the eSIM.
* The eSIM's data tier ends now and is no longer billed.
* A revoked eSIM cannot be reactivated. To put the number on a phone again, [order a new eSIM](https://help.withallo.com/en/v2/api-reference/white-label/order-esim.md) for it. The new order charges the setup fee.

[Remove member](https://help.withallo.com/en/v2/api-reference/white-label/remove-member.md) revokes the member's eSIMs for you, so you do not need to call this endpoint first.

## Idempotency

Revoking an eSIM that is already `REVOKED` returns it unchanged. An eSIM replaced by a later eSIM on the same number also reads `REVOKED`, and revoking it never touches the new one.

## Errors

| Code | What it means |
| - | - |
| `PARTNER_ESIM_NOT_REVOCABLE` | The eSIM is not live: it is still `PROVISIONING`, it `FAILED`, or it is being moved between the network and the eSIM (`409`). Only an `ACTIVE` eSIM can be revoked. Check it with [Get eSIM](https://help.withallo.com/en/v2/api-reference/white-label/get-esim.md). |
| `PARTNER_ESIM_MOVE_FAILED` | The eSIM failed to move between the network and the eSIM (`409`), so it cannot be revoked until it is checked. Contact Allo support. Nothing was changed. |
| `PARTNER_ESIM_NOT_FOUND` | No eSIM with this id was ordered on an account your API key created (`404`). |


## OpenAPI

````yaml POST /v2/api/partner/esims/{id}/revoke
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/esims/{id}/revoke:
    post:
      tags:
        - White label
      summary: Revoke eSIM
      description: >-
        Revokes an eSIM right away: it stops working on its phone for good. The
        number stays on the account, keeps its history and rings the Allo apps
        instead. The eSIM's data tier ends now. To put the number on a phone
        again, order a new eSIM for it, which charges the setup fee. Idempotent:
        revoking an eSIM that is already `REVOKED` returns it unchanged.
        Requires the `PARTNER` scope.
      operationId: revokePartnerEsim
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The eSIM id returned by Order eSIM (`eso-*`).
      responses:
        '200':
          description: The revoked eSIM, with status `REVOKED`
          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
                          - 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
                      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: REVOKED
                  failure_code: null
                  created_at: '2026-10-14T10:05:00'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '403':
          description: The API key lacks the PARTNER scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '404':
          description: >-
            No eSIM with this id was ordered on an account your API key
            provisioned (PARTNER_ESIM_NOT_FOUND).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '409':
          description: >-
            The eSIM is not live: it is still provisioning, it failed, or it is
            being moved between the network and the eSIM
            (PARTNER_ESIM_NOT_REVOCABLE). Only an `ACTIVE` eSIM can be revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      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.