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

# Déclarer un Sender ID

> Declares an alphanumeric sender ID on one of your accounts, so the account can send SMS under that name. The sender ID is created with status `PENDING` and Allo reviews it by hand, usually in 1 to 5 business days. Allo then sends the `partner.sender_id.validated` or `partner.sender_id.failed` webhook. A sender ID belongs to one Allo account only, and an account holds at most 3. Sending the same `sender_id` again for the same account returns the existing one. Requires the `PARTNER` scope.

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

Déclare un Sender ID alphanumérique sur l'un de vos comptes, pour que le compte envoie des SMS sous le nom de sa marque plutôt que depuis un numéro. En France, les SMS automatisés ne peuvent pas partir d'un numéro mobile : le Sender ID est donc ce qui permet à votre logiciel d'écrire aux clients du compte. La réponse renvoie le Sender ID avec le statut `PENDING`.

## Requête

* `sender_id` est requis : 1 à 11 lettres ou chiffres, sans espace ni symbole, par exemple `PLOMBMARTIN`. Une valeur absente échoue avec `MISSING_FIELD`, tout autre format avec `SENDER_ID_INVALID_FORMAT`. Le nom doit représenter l'activité réelle du compte, voir les [règles de nommage du Sender ID](https://help.withallo.com/fr/phone-numbers/sms-france.md).
* `example_content` est optionnel : un exemple de message que le compte enverra, jusqu'à 1 000 caractères. Le relecteur d'Allo le lit. Une valeur plus longue échoue avec `EXAMPLE_CONTENT_TOO_LONG`.

## Règles

* Un Sender ID n'appartient qu'à un seul compte Allo. Un nom déjà détenu par un autre compte Allo échoue avec `409 SENDER_ID_ALREADY_EXISTS`.
* Un compte détient au plus 3 Sender ID. Un quatrième échoue avec `409 MAX_SENDER_IDS_REACHED`.
* Renvoyer le même `sender_id` pour le même compte renvoie le Sender ID existant : une nouvelle tentative est sans risque.
* Vous ne pouvez déclarer des Sender ID que sur les comptes créés par votre propre clé API. Tout autre compte renvoie `404 PARTNER_ACCOUNT_NOT_FOUND`.

## Validation

Allo valide chaque Sender ID à la main, en général en 1 à 5 jours ouvrés. À la fin de la validation, Allo envoie [`partner.sender_id.validated`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partnersender_idvalidated) ou [`partner.sender_id.failed`](https://help.withallo.com/fr/v2/api-reference/webhooks/event-catalog#partnersender_idfailed) à votre propre endpoint webhook. Sans endpoint webhook, interrogez [Obtenir un Sender ID](https://help.withallo.com/fr/v2/api-reference/white-label/get-sender-id.md).

Une fois le Sender ID `VALIDATED`, le compte envoie des SMS avec lui via [Envoyer un SMS (France)](https://help.withallo.com/fr/v2/api-reference/sms/send-sms-france.md).


## OpenAPI

````yaml POST /v2/api/partner/accounts/{account_id}/sender_ids
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}/sender_ids:
    post:
      tags:
        - White label
      summary: Declare sender ID
      description: >-
        Declares an alphanumeric sender ID on one of your accounts, so the
        account can send SMS under that name. The sender ID is created with
        status `PENDING` and Allo reviews it by hand, usually in 1 to 5 business
        days. Allo then sends the `partner.sender_id.validated` or
        `partner.sender_id.failed` webhook. A sender ID belongs to one Allo
        account only, and an account holds at most 3. Sending the same
        `sender_id` again for the same account returns the existing one.
        Requires the `PARTNER` scope.
      operationId: createPartnerSenderId
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
          description: The account id returned by Create account (`usr-*`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePartnerSenderIdRequest'
            example:
              sender_id: PLOMBMARTIN
              example_content: >-
                Bonjour, votre intervention est confirmée demain à 9h. Plomberie
                Martin
      responses:
        '201':
          description: Sender ID declared, waiting for Allo's review
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PartnerSenderId'
              example:
                data:
                  id: vsi-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61
                  account_id: usr-575966AF3661061265263C58882BC409D2A427B8
                  partner_client_ref: crm-12345
                  sender_id: PLOMBMARTIN
                  status: PENDING
                  example_content: >-
                    Bonjour, votre intervention est confirmée demain à 9h.
                    Plomberie Martin
                  created_at: '2026-11-16T10:05:00'
        '400':
          description: >-
            Validation error: MISSING_FIELD (`sender_id`),
            SENDER_ID_INVALID_FORMAT (`sender_id` is not 1 to 11 letters or
            digits) or EXAMPLE_CONTENT_TOO_LONG (`example_content` is longer
            than 1000 characters).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '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 account with this id was provisioned by your API key, or the
            account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '409':
          description: >-
            The sender ID already belongs to another Allo account
            (SENDER_ID_ALREADY_EXISTS), or the account already has 3 sender IDs
            (MAX_SENDER_IDS_REACHED).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreatePartnerSenderIdRequest:
      type: object
      required:
        - sender_id
      properties:
        sender_id:
          type: string
          minLength: 1
          maxLength: 11
          description: >-
            1 to 11 letters or digits, with no spaces or symbols. It must not
            belong to another Allo account.
          example: PLOMBMARTIN
        example_content:
          type: string
          nullable: true
          maxLength: 1000
          description: >-
            Optional. An example of a message the account will send, shown to
            the Allo reviewer.
          example: >-
            Bonjour, votre intervention est confirmée demain à 9h. Plomberie
            Martin
    PartnerSenderId:
      type: object
      description: An alphanumeric sender ID declared on an account you provisioned.
      properties:
        id:
          type: string
          description: The sender ID's id (`vsi-*`).
          example: vsi-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61
        account_id:
          type: string
          description: The account the sender ID is declared on.
          example: usr-575966AF3661061265263C58882BC409D2A427B8
        partner_client_ref:
          type: string
          nullable: true
          description: Your own reference, set when the account was created.
          example: crm-12345
        sender_id:
          type: string
          description: The name recipients see instead of a phone number.
          example: PLOMBMARTIN
        status:
          type: string
          enum:
            - PENDING
            - VALIDATED
            - FAILED
            - DISABLED
          description: >-
            `PENDING`: waiting for Allo's review. `VALIDATED`: approved, the
            account can send SMS with it. `FAILED`: rejected, declare another
            name. `DISABLED`: deactivated by Allo after validation, sending with
            it is refused.
          example: PENDING
        example_content:
          type: string
          nullable: true
          description: The example message sent with the declaration.
          example: >-
            Bonjour, votre intervention est confirmée demain à 9h. Plomberie
            Martin
        created_at:
          type: string
          format: date-time
          description: When the sender ID was declared.
          example: '2026-11-16T10:05:00'
    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
  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'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.