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

# Ajouter un membre

> Adds a member to one of your accounts, with a phone number of their own. The member takes a seat the account already pays for and no one uses, or one more seat on the account's subscription, which you pay: Allo draws on your prepaid credit first, then charges your card on file for the rest. The seat includes the member's number, so the number is not billed on top. Allo sends the member no invitation email. Allo checks that a number is available before charging anything. Requires the `PARTNER` scope.

<Note>
  **Scope requis :** `PARTNER`
</Note>

Ajoute un collaborateur à l'un de vos comptes, avec son propre numéro de téléphone. La réponse renvoie le membre, dont l'`id` qui sert à commander son eSIM.

## Requête

* `email` est requis et devient l'identifiant de connexion du membre.
* `name` est requis.
* `personal_mobile` est optionnel, au format E.164, par exemple `+33612345679`. Un numéro illisible échoue avec `INVALID_PHONE_NUMBER`.
* `role` est optionnel : `ADMIN`, `MANAGER` ou `MEMBER`, `MEMBER` par défaut. Toute autre valeur échoue avec `INVALID_MEMBER_ROLE`.
* `number_preference` est requis : le numéro du membre, avec les mêmes champs que sur [Créer un compte](/fr/v2/api-reference/partner/create-account). `number_preference.country` est requis. Passez `number_preference.esim` à `true` pour donner au membre un numéro mobile français qui peut porter une eSIM.
* Si l'email ou le mobile personnel appartient déjà à un compte Allo, la requête échoue avec `409 PARTNER_ACCOUNT_ALREADY_EXISTS`, et `param` indique le champ concerné.

`{id}` est l'identifiant du compte renvoyé par Créer un compte. Un compte que votre API key n'a pas créé, ou déjà désactivé, renvoie `404 PARTNER_ACCOUNT_NOT_FOUND`.

## Ce que fait Allo

* Allo crée le membre dans le workspace du compte et lui attribue son numéro.
* Allo n'envoie aucun email d'invitation au membre. C'est vous qui l'accompagnez. Le membre se connecte à Allo avec l'email (ou le mobile personnel) que vous avez envoyé, et `activated` passe à `true` dès sa première connexion sur un appareil.
* Le membre occupe un siège sur l'abonnement du compte. Ce siège inclut son numéro : le numéro n'est pas facturé en plus.

## Facturation

* Si le compte paie déjà un siège que personne n'occupe, le membre le prend et rien n'est débité.
* Sinon, Allo ajoute un siège à l'abonnement du compte, que vous payez, et débite tout de suite le reste de la période de facturation en cours, avec la remise de l'abonnement appliquée. Allo prélève d'abord votre [crédit prépayé](/fr/v2/api-reference/partner/get-credit), puis débite le reste sur votre carte enregistrée. Allo ne facture jamais votre client.
* Allo vérifie l'email, le mobile personnel et le numéro avant tout débit. Si aucun numéro ne correspond, la requête échoue avec `409 NO_NUMBER_AVAILABLE` et rien n'est débité.
* Si votre crédit prépayé ne couvre pas le siège et qu'aucune carte n'est enregistrée, la requête échoue avec `402 PARTNER_CREDIT_INSUFFICIENT` et rien n'est créé. Une carte refusée échoue avec `402 PARTNER_BILLING_FAILED`.
* Si le numéro du membre ne peut pas être configuré après le débit, Allo supprime le membre et retire le siège de l'abonnement.

L'endpoint ne prend pas d'`Idempotency-Key`. Si une requête expire, consultez [Lister les membres](/fr/v2/api-reference/partner/list-members) avant de réessayer : une fois le membre créé, une nouvelle tentative avec le même email échoue avec `PARTNER_ACCOUNT_ALREADY_EXISTS`.

## Comment donner une eSIM au membre

<Steps>
  <Step title="Ajoutez le membre avec un numéro eSIM">
    Envoyez `number_preference: {"country": "FR", "esim": true}`. Le membre reçoit un numéro mobile français qui peut porter une eSIM, listé dans `phone_numbers`.
  </Step>

  <Step title="Commandez l'eSIM pour le membre">
    Appelez [Commander une eSIM](/fr/v2/api-reference/partner/order-esim) sur le même compte (`POST /v2/api/partner/accounts/{account_id}/esims`). Envoyez le numéro du membre comme `phone_number` et l'`id` du membre comme `holder_id`. L'eSIM est alors rattachée au membre, et non au compte.
  </Step>

  <Step title="Remettez l'eSIM">
    Attendez [`partner.esim.ready`](/fr/v2/api-reference/webhooks/event-catalog#partneresimready), puis envoyez au membre le code de [Obtenir le code d'activation d'une eSIM](/fr/v2/api-reference/partner/get-esim-activation-code).
  </Step>
</Steps>

## Erreurs

| Code | Signification |
| - | - |
| `REGULATORY_VERIFICATION_REQUIRED` | Un numéro dans ce pays demande d'abord la vérification réglementaire du compte. Rien n'est débité. |
| `PARTNER_ACCOUNT_BUSY` | Un autre numéro ou membre est en cours d'ajout sur ce compte, ou cet email est en cours d'ajout ailleurs. Toujours `retryable: true` : réessayez dans quelques secondes. |
| `PARTNER_ACCOUNT_DEACTIVATING` | Le compte est en cours de désactivation à la fin de sa période de facturation : il ne prend plus de membres. |
| `PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT` | L'abonnement du compte ne peut pas être facturé pour le moment. Si `retryable` vaut `true`, réessayez dans quelques minutes. Sinon, écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). |
| `PARTNER_SUBSCRIPTION_NOT_BILLABLE` | Le compte n'a pas d'abonnement qu'Allo peut facturer (`402`). |
| `PARTNER_BILLING_UNAVAILABLE` | La facturation est temporairement indisponible (`500`). Réessayez dans quelques secondes. |
| `PARTNER_NUMBER_SETUP_FAILED` | Le numéro du membre n'a pas pu être configuré (`500`). Le membre et le débit ont été annulés. Écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). |
| `PARTNER_NUMBER_KEPT` | Le numéro a été attribué mais sa configuration n'a pas abouti (`500`). Il reste sur le compte avec le siège du membre. Ne réessayez pas : écrivez à [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) en indiquant le numéro. |


## OpenAPI

````yaml POST /v2/api/partner/accounts/{id}/members
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/{id}/members:
    post:
      tags:
        - Partner
      summary: Add member
      description: >-
        Adds a member to one of your accounts, with a phone number of their own.
        The member takes a seat the account already pays for and no one uses, or
        one more seat on the account's subscription, which you pay: Allo draws
        on your prepaid credit first, then charges your card on file for the
        rest. The seat includes the member's number, so the number is not billed
        on top. Allo sends the member no invitation email. Allo checks that a
        number is available before charging anything. Requires the `PARTNER`
        scope.
      operationId: addPartnerAccountMember
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The account id returned by Create account (`usr-*`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
                - number_preference
              properties:
                email:
                  type: string
                  description: >-
                    Becomes the member's login. It must not belong to an Allo
                    account yet.
                  example: paul@example.com
                name:
                  type: string
                  example: Paul Martin
                personal_mobile:
                  type: string
                  nullable: true
                  description: >-
                    Optional, E.164. The member's own mobile. It must not belong
                    to an Allo account yet.
                  example: '+33612345679'
                role:
                  type: string
                  enum:
                    - ADMIN
                    - MANAGER
                    - MEMBER
                  nullable: true
                  description: >-
                    Optional, default `MEMBER`. The member's role in the
                    account's workspace.
                  example: MEMBER
                number_preference:
                  type: object
                  required:
                    - country
                  description: The member's number.
                  properties:
                    country:
                      type: string
                      description: ISO country code.
                      example: FR
                    prefix:
                      type: string
                      nullable: true
                      example: '7'
                      description: >-
                        Optional. Digits the number should start with, after the
                        country code, for example `+337` or `7`.
                    esim:
                      type: boolean
                      nullable: true
                      description: >-
                        Optional, default `false`. Set to `true` to get a French
                        mobile number that can carry an eSIM, which you can then
                        order with `POST
                        /v2/api/partner/accounts/{account_id}/esims`. eSIM
                        numbers are only available with `country` set to `FR`,
                        otherwise the request fails with
                        `ESIM_NOT_AVAILABLE_IN_COUNTRY`.
                      example: true
            example:
              email: paul@example.com
              name: Paul Martin
              personal_mobile: '+33612345679'
              role: MEMBER
              number_preference:
                country: FR
                esim: true
      responses:
        '201':
          description: Member added
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: >-
                          The member's user id (`usr-*`). Pass it as `holder_id`
                          to Order eSIM to register the member's eSIM to the
                          member.
                        example: usr-8C1B2E7F4A9D3C6B0E5F1A2D7C4B9E3F6A0D8C21
                      account_id:
                        type: string
                        description: The account the member was added to.
                        example: usr-575966AF3661061265263C58882BC409D2A427B8
                      email:
                        type: string
                        description: The member's login.
                        example: paul@example.com
                      name:
                        type: string
                        example: Paul Martin
                      role:
                        type: string
                        enum:
                          - ADMIN
                          - MANAGER
                          - MEMBER
                        example: MEMBER
                      phone_numbers:
                        type: array
                        items:
                          type: string
                        description: The member's own numbers.
                        example:
                          - '+33745805111'
                      status:
                        type: string
                        example: ACTIVE
                      activated:
                        type: boolean
                        description: True once the member has signed in on a device.
                        example: false
              example:
                data:
                  id: usr-8C1B2E7F4A9D3C6B0E5F1A2D7C4B9E3F6A0D8C21
                  account_id: usr-575966AF3661061265263C58882BC409D2A427B8
                  email: paul@example.com
                  name: Paul Martin
                  role: MEMBER
                  phone_numbers:
                    - '+33745805111'
                  status: ACTIVE
                  activated: false
        '400':
          description: >-
            Validation error: MISSING_FIELD (`email`, `name`,
            `number_preference` or `number_preference.country`),
            INVALID_PHONE_NUMBER (`personal_mobile`), INVALID_MEMBER_ROLE,
            INVALID_NUMBER_PREFERENCE or ESIM_NOT_AVAILABLE_IN_COUNTRY.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '402':
          description: >-
            Billing error, nothing is created. PARTNER_CREDIT_INSUFFICIENT: your
            prepaid credit does not cover the charge and your billing account
            has no card on file. PARTNER_BILLING_FAILED: your card was declined.
            PARTNER_SUBSCRIPTION_NOT_BILLABLE: the account has no subscription
            Allo can bill.
          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: >-
            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: >-
            Nothing is charged for PARTNER_ACCOUNT_ALREADY_EXISTS (the email or
            personal mobile already belongs to an Allo account),
            NO_NUMBER_AVAILABLE or REGULATORY_VERIFICATION_REQUIRED. Also
            PARTNER_ACCOUNT_BUSY (another number or member is being added to the
            account, `retryable: true`), PARTNER_ACCOUNT_DEACTIVATING (the
            account is being deactivated) or
            PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT (the account's subscription
            cannot be billed right now; retry when `retryable` is `true`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '429':
          $ref: '#/components/responses/ApiRateLimited'
        '500':
          description: >-
            PARTNER_BILLING_UNAVAILABLE: billing is temporarily unavailable,
            retry in a few seconds. PARTNER_NUMBER_SETUP_FAILED: the member's
            number could not be set up, and the member and the charge were
            removed. PARTNER_NUMBER_KEPT: the number was assigned but its setup
            did not complete, and it stays on the account with the member's
            seat. Do not retry these two: write to
            partnership@themobilefirst.co.
          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.