# Add member

> Adds a member to one of your accounts, with a phone number of their own: a new number from number preference , or a number the account already holds from…

`POST /v2/api/partner/accounts/{id}/members`

<Note>
**Required scope:** `PARTNER`
</Note>

Adds a teammate to one of your accounts, with a phone number of their own: a new number, or a number the account already holds, which the member takes over with its history. 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` gives the member a new number, with the same fields as on [Create account](/docs/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.
- `phone_number` gives the member a number the account already holds instead, in E.164 format. See [How to give the member an existing number](#how-to-give-the-member-an-existing-number).
- Send either `number_preference` or `phone_number`. Sending both fails with `400 PARTNER_MEMBER_NUMBER_CHOICE_CONFLICT`. Sending neither fails with `MISSING_FIELD`.
- 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, or moves the `phone_number` to the member.
- 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](/docs/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.

## How to give the member an existing number

Send `phone_number` to give the member a number the account holds itself, for example one kept from a member you [removed](/docs/white-label/remove-member). The number moves from the account to the member with its call and message history.

- The number must be one of the account's `phone_numbers` from [Get account](/docs/partner/get-account), held by the account itself and not by a member. Any other number fails with `404 PARTNER_ACCOUNT_NUMBER_NOT_FOUND`.
- If the number still has an eSIM that is not revoked, the request fails with `409 PARTNER_NUMBER_HAS_LIVE_ESIM`. [Revoke the eSIM](/docs/white-label/revoke-esim) first, so the former holder's phone never rings for the new member. Remove member revokes it for you.
- The seat is billed as for any new member. Since the seat includes the number, Allo also removes one extra number from the account's subscription, if the account pays for one it no longer needs, with no proration.
- The member gets no eSIM. To give them one, call [Order eSIM](/docs/white-label/order-esim) with the number as `phone_number` and the member's `id` as `holder_id`. The new eSIM charges the setup fee.

The endpoint takes no `Idempotency-Key`. If a request times out, check [List members](/docs/white-label/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](/docs/white-label/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`](/docs/webhooks/event-catalog#partneresimready), then send the member the code from [Get eSIM activation code](/docs/white-label/get-esim-activation-code).
  </Step>
</Steps>

## Errors

| Code | What it means |
|------|---------------|
| `PARTNER_ACCOUNT_NUMBER_NOT_FOUND` | The account does not hold `phone_number` itself: the number is not on the account, or a member holds it (`404`). |
| `PARTNER_NUMBER_HAS_LIVE_ESIM` | `phone_number` still has an eSIM that is not revoked (`409`). Revoke it with [Revoke eSIM](/docs/white-label/revoke-esim), then retry. |
| `PARTNER_MEMBER_NUMBER_CHOICE_CONFLICT` | The request sent both `phone_number` and `number_preference` (`400`). Send one of them. |
| `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. |
