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

# Add member

> 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>
  **Required scope:** `PARTNER`
</Note>

Adds a teammate to one of your accounts, with a phone number of their own. The response returns the member, including the `id` you need to order the member's eSIM.

## Request

* `email` is required and becomes the member's login.
* `name` is required.
* `personal_mobile` is optional, in E.164 format, for example `+33612345679`. A number Allo cannot read fails with `INVALID_PHONE_NUMBER`.
* `role` is optional: `ADMIN`, `MANAGER` or `MEMBER`, `MEMBER` by default. Any other value fails with `INVALID_MEMBER_ROLE`.
* `number_preference` is required: the member's number, with the same fields as on [Create account](/en/v2/api-reference/partner/create-account). `number_preference.country` is required. Set `number_preference.esim` to `true` to give the member a French mobile number that can carry an eSIM.
* If the email or the personal mobile already belongs to an Allo account, the request fails with `409 PARTNER_ACCOUNT_ALREADY_EXISTS`, and `param` names the field.

`{id}` is the account id returned by Create account. An account your API key did not create, or one already deactivated, returns `404 PARTNER_ACCOUNT_NOT_FOUND`.

## What Allo does

* Allo creates the member in the account's workspace and assigns the member's number.
* Allo sends the member no invitation email. You onboard the member yourself. The member signs in to Allo with the email (or the personal mobile) you sent, and `activated` turns `true` once they sign in on a device.
* The member takes a seat on the account's subscription. The seat includes the member's number, so the number is not billed on top.

## Billing

* If the account already pays for a seat that no one uses, the member takes it and nothing is charged.
* Otherwise Allo adds one seat to the account's subscription, which you pay, and charges the rest of the current billing period now, with the subscription's discount applied. Allo draws on your [prepaid credit](/en/v2/api-reference/partner/get-credit) first, then charges your card on file for the rest. Allo never charges your customer.
* Allo checks the email, the personal mobile and the number before charging anything. If no number matches, the request fails with `409 NO_NUMBER_AVAILABLE` and nothing is charged.
* If your prepaid credit does not cover the seat and you have no card on file, the request fails with `402 PARTNER_CREDIT_INSUFFICIENT` and nothing is created. A declined card fails with `402 PARTNER_BILLING_FAILED`.
* If the member's number cannot be set up after the charge, Allo removes the member and takes the seat back off the subscription.

The endpoint takes no `Idempotency-Key`. If a request times out, check [List members](/en/v2/api-reference/partner/list-members) before you retry: once the member exists, a retry with the same email fails with `PARTNER_ACCOUNT_ALREADY_EXISTS`.

## How to give the member an eSIM

<Steps>
  <Step title="Add the member with an eSIM number">
    Send `number_preference: {"country": "FR", "esim": true}`. The member gets a French mobile number that can carry an eSIM, listed in `phone_numbers`.
  </Step>

  <Step title="Order the eSIM for the member">
    Call [Order eSIM](/en/v2/api-reference/partner/order-esim) on the same account (`POST /v2/api/partner/accounts/{account_id}/esims`). Send the member's number as `phone_number` and the member's `id` as `holder_id`. The eSIM is then registered to the member, not to the account.
  </Step>

  <Step title="Deliver the eSIM">
    Wait for [`partner.esim.ready`](/en/v2/api-reference/webhooks/event-catalog#partneresimready), then send the member the code from [Get eSIM activation code](/en/v2/api-reference/partner/get-esim-activation-code).
  </Step>
</Steps>

## Errors

| Code | What it means |
| - | - |
| `REGULATORY_VERIFICATION_REQUIRED` | A number in this country needs the account's regulatory verification first. Nothing is charged. |
| `PARTNER_ACCOUNT_BUSY` | Another number or member is being added to this account, or this email is being added elsewhere, right now. Always `retryable: true`: retry in a few seconds. |
| `PARTNER_ACCOUNT_DEACTIVATING` | The account is being deactivated at the end of its billing period, so it takes no more members. |
| `PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT` | The account's subscription cannot be billed right now. When `retryable` is `true`, retry in a few minutes. Otherwise write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). |
| `PARTNER_SUBSCRIPTION_NOT_BILLABLE` | The account has no subscription Allo can bill (`402`). |
| `PARTNER_BILLING_UNAVAILABLE` | Billing is temporarily unavailable (`500`). Retry in a few seconds. |
| `PARTNER_NUMBER_SETUP_FAILED` | The member's number could not be set up (`500`). The member and the charge were removed. Write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). |
| `PARTNER_NUMBER_KEPT` | The number was assigned but its setup did not complete (`500`). It stays on the account with the member's seat. Do not retry: write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) with the number. |


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