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

# Révoquer une 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]
>
> **Scope requis :** `PARTNER`

Révoque immédiatement une eSIM : elle cesse définitivement de fonctionner sur son téléphone, par exemple quand le téléphone est perdu ou que son titulaire part. La réponse renvoie l'eSIM avec le statut `REVOKED`.

## Ce que devient le numéro

* Le numéro reste sur le compte, avec le même titulaire et son historique d'appels et de messages.
* Les appels vers le numéro sonnent sur les apps Allo au lieu de l'eSIM.
* Le palier de données de l'eSIM s'arrête tout de suite et n'est plus facturé.
* Une eSIM révoquée ne peut pas être réactivée. Pour remettre le numéro sur un téléphone, [commandez une nouvelle eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/order-esim.md) pour ce numéro. La nouvelle commande facture les frais de mise en service.

[Retirer un membre](https://help.withallo.com/fr/v2/api-reference/white-label/remove-member.md) révoque les eSIM du membre pour vous : inutile d'appeler cet endpoint avant.

## Idempotence

Révoquer une eSIM déjà `REVOKED` la renvoie telle quelle. Une eSIM remplacée par une eSIM plus récente sur le même numéro est aussi `REVOKED`, et la révoquer ne touche jamais la nouvelle.

## Erreurs

| Code | Signification |
| - | - |
| `PARTNER_ESIM_NOT_REVOCABLE` | L'eSIM n'est pas active : elle est encore `PROVISIONING`, elle est `FAILED`, ou elle est en cours de bascule entre le réseau et l'eSIM (`409`). Seule une eSIM `ACTIVE` peut être révoquée. Vérifiez-la avec [Obtenir une eSIM](https://help.withallo.com/fr/v2/api-reference/white-label/get-esim.md). |
| `PARTNER_ESIM_MOVE_FAILED` | La bascule de l'eSIM entre le réseau et l'eSIM a échoué (`409`) : elle ne peut pas être révoquée avant d'être vérifiée. Contactez le support Allo. Rien n'a été modifié. |
| `PARTNER_ESIM_NOT_FOUND` | Aucune eSIM avec cet id n'a été commandée sur un compte créé par votre API key (`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.