Allo

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

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. 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.
  • 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 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. 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, 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 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 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 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

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.

Order the eSIM for the member

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

Deliver the eSIM

Wait for partner.esim.ready, then send the member the code from Get eSIM activation code.

Errors

CodeWhat it means
PARTNER_ACCOUNT_NUMBER_NOT_FOUNDThe account does not hold phone_number itself: the number is not on the account, or a member holds it (404).
PARTNER_NUMBER_HAS_LIVE_ESIMphone_number still has an eSIM that is not revoked (409). Revoke it with Revoke eSIM, then retry.
PARTNER_MEMBER_NUMBER_CHOICE_CONFLICTThe request sent both phone_number and number_preference (400). Send one of them.
REGULATORY_VERIFICATION_REQUIREDA number in this country needs the account's regulatory verification first. Nothing is charged.
PARTNER_ACCOUNT_BUSYAnother 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_DEACTIVATINGThe account is being deactivated at the end of its billing period, so it takes no more members.
PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICTThe account's subscription cannot be billed right now. When retryable is true, retry in a few minutes. Otherwise write to [email protected].
PARTNER_SUBSCRIPTION_NOT_BILLABLEThe account has no subscription Allo can bill (402).
PARTNER_BILLING_UNAVAILABLEBilling is temporarily unavailable (500). Retry in a few seconds.
PARTNER_NUMBER_SETUP_FAILEDThe member's number could not be set up (500). The member and the charge were removed. Write to [email protected].
PARTNER_NUMBER_KEPTThe 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 [email protected] with the number.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

idstringrequired

The account id returned by Create account (usr-*).

Body

emailstringrequired

Becomes the member's login. It must not belong to an Allo account yet.

namestringrequired
personal_mobilestring | null

Optional, E.164. The member's own mobile. It must not belong to an Allo account yet.

roleenum<string>

Optional, default MEMBER. The member's role in the account's workspace.

ADMINMANAGERMEMBER

number_preferenceobject

The member's new number. Required unless you send phone_number. Do not send both.

3 fields
countrystringrequired

ISO country code.

prefixstring | null

Optional. Digits the number should start with, after the country code, for example +337 or 7.

esimboolean | null

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.

phone_numberstring | null

A number the account holds itself, for example one kept from a removed member, in E.164 format. The member takes it over, with its call and message history, instead of getting a new number. Send either phone_number or number_preference, not both. If the number had an eSIM, revoke it first, then order a new eSIM for the member with holder_id.

Responses

201Member added
dataobject
8 fields
idstring

The member's user id (usr-*). Pass it as holder_id to Order eSIM to register the member's eSIM to the member.

account_idstring

The account the member was added to.

emailstring

The member's login.

namestring
roleenum<string>

ADMINMANAGERMEMBER

phone_numbersstring[]

The member's own numbers.

statusstring

The member's status: ACTIVE, or SUSPENDED while the account is suspended with Suspend account.

activatedboolean

True once the member has signed in on a device.

400Validation error: MISSING_FIELD (email, name, number_preference or number_preference.country), INVALID_PHONE_NUMBER (personal_mobile or phone_number), INVALID_MEMBER_ROLE, INVALID_NUMBER_PREFERENCE, ESIM_NOT_AVAILABLE_IN_COUNTRY, or PARTNER_MEMBER_NUMBER_CHOICE_CONFLICT (both phone_number and number_preference were sent).
errorobject
401
402Billing 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.
errorobject
403The API key lacks the PARTNER scope.
errorobject
404No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND), or the account does not hold the phone_number itself: it is not on the account, or a member holds it (PARTNER_ACCOUNT_NUMBER_NOT_FOUND).
errorobject
409Nothing 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). PARTNER_NUMBER_HAS_LIVE_ESIM: the phone_number still has an eSIM that is not revoked; revoke it with POST /v2/api/partner/esims/{id}/revoke first.
errorobject
429
500PARTNER_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 [email protected].
errorobject