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

# Overview

> Run your own product on Allo's API: manage the members, numbers, eSIMs, suspensions and sender IDs of the accounts you create, under your brand.

**White label** is for partners who build their own product on top of Allo's API. Their end users never use the Allo app: they use the partner's tool, and their Allo number rings an eSIM in their phone. The partner's software runs everything else through the API: members, numbers, eSIMs, suspensions and sender IDs.

If you resell Allo and your customers use the Allo app, the [Partners](https://help.withallo.com/en/v2/api-reference/partner/overview.md) endpoints are all you need.

The white-label endpoints use the same `PARTNER` key, authentication and billing as the Partners endpoints. Start with the [Partners overview](https://help.withallo.com/en/v2/api-reference/partner/overview.md) to get access, then create each account with [Create account](https://help.withallo.com/en/v2/api-reference/partner/create-account.md).

## How to add numbers and members to an account

An account starts with one number. You can then grow it from the API:

* [Add number](https://help.withallo.com/en/v2/api-reference/white-label/add-number.md) gives the account one more number. It is billed on the account's subscription, unless the account already pays for a free number slot. Call [Get number price](https://help.withallo.com/en/v2/api-reference/white-label/get-number-price.md) first to see the amount.
* [Add member](https://help.withallo.com/en/v2/api-reference/white-label/add-member.md) adds a teammate to the account, with a number of their own. The member takes a seat on the account's subscription, and the seat includes the number. Allo sends the member no invitation email: you onboard the member yourself.
* [List members](https://help.withallo.com/en/v2/api-reference/white-label/list-members.md) returns the account's members and their numbers.
* [Remove member](https://help.withallo.com/en/v2/api-reference/white-label/remove-member.md) takes a member out of the account and keeps their numbers on it.

Allo checks that a number is available before charging anything. If none matches, the request fails with `409 NO_NUMBER_AVAILABLE` and nothing is charged.

## How to give an account an eSIM

An eSIM puts the account's Allo number in your client's phone, like a second SIM. Calls reach the phone over the French mobile network. eSIMs are available in France only, on numbers created for them.

**1. Create the account with an eSIM number**

Call [Create account](https://help.withallo.com/en/v2/api-reference/partner/create-account.md) with `number_preference: {"country": "FR", "esim": true}`. Add a `prefix`, for example `"7"`, to choose how the number starts. The account gets a French mobile number that can carry an eSIM. [Add number](https://help.withallo.com/en/v2/api-reference/white-label/add-number.md) and [Add member](https://help.withallo.com/en/v2/api-reference/white-label/add-member.md) take the same `esim: true` for the numbers you add later.

**2. Get the offer**

Call [Get eSIM offer](https://help.withallo.com/en/v2/api-reference/white-label/get-esim-offer.md) to read the setup fee and the data tiers. The prices follow the subscription you pay for that account: its currency, its billing interval and your partner discount.

**3. Order the eSIM**

Call [Order eSIM](https://help.withallo.com/en/v2/api-reference/white-label/order-esim.md) with the number, a tier and the identity of the business the line is registered to. For a member's number, send the member's `id` as `holder_id`. Allo charges the order to your prepaid credit first, then to your card on file, and returns the eSIM with status `PROVISIONING`. Send an `Idempotency-Key` header so a retry never charges you twice.

**4. Wait for the eSIM to be ready**

The eSIM is usually ready 5 to 15 minutes later. Allo then sends [`partner.esim.ready`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneresimready) to your own webhook endpoint, not to the account's. From that moment, calls to the number ring the eSIM. If the order fails, you receive [`partner.esim.failed`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneresimfailed) instead. Without a webhook endpoint, poll [Get eSIM](https://help.withallo.com/en/v2/api-reference/white-label/get-esim.md).

**5. Get the activation code**

Call [Get eSIM activation code](https://help.withallo.com/en/v2/api-reference/white-label/get-esim-activation-code.md). It returns a QR code, the values for manual entry, and the code to build a one-tap install link for iPhone.

**6. Deliver the eSIM to your client**

Send the QR code or the install link to your client, under your own brand. Your client installs the eSIM on their phone.

> [!NOTE]
>
> Allo never emails your client about the eSIM. You deliver the activation code yourself. Allo does not detect when your client installs the eSIM.

## How to suspend an account for unpaid invoices

When your customer stops paying you, call [Suspend account](https://help.withallo.com/en/v2/api-reference/white-label/suspend-account.md). Calls, outgoing SMS, the AI receptionist and the account's eSIM lines stop right away, for every member. The account keeps its numbers, its eSIMs and its history.

When your customer pays, call [Resume account](https://help.withallo.com/en/v2/api-reference/white-label/resume-account.md). Everything works again, on the same numbers.

* A suspension does not change billing: the subscription you pay for the account keeps running. To stop paying for the account, [deactivate it](https://help.withallo.com/en/v2/api-reference/partner/delete-account.md) instead.
* Allo sends [`partner.account.suspended`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneraccountsuspended) and [`partner.account.resumed`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneraccountresumed) to your webhook endpoint. While the account is suspended, [Get account](https://help.withallo.com/en/v2/api-reference/partner/get-account.md) returns `status: SUSPENDED`, and so does each member in [List members](https://help.withallo.com/en/v2/api-reference/white-label/list-members.md).

## How to replace a collaborator who leaves

When a collaborator leaves your customer's company, you can cut their phone, then give their number, with its history, to the person who replaces them.

**1. Remove the collaborator**

Call [Remove member](https://help.withallo.com/en/v2/api-reference/white-label/remove-member.md) (`DELETE /v2/api/partner/accounts/{id}/members/{member_id}`). Allo revokes their eSIMs right away, so their phone stops ringing. Their numbers stay on the account and ring the Allo apps. Their seat stays paid until the end of the current period, then the numbers are billed as extra numbers.

**2. Add the new collaborator on the same number**

Call [Add member](https://help.withallo.com/en/v2/api-reference/white-label/add-member.md) with the kept number as `phone_number`, instead of `number_preference`. The new member takes the number over with its call and message history, on a seat billed like any new member. Since the seat includes the number, Allo takes one extra number back off the subscription.

**3. Give the new collaborator an eSIM**

Call [Order eSIM](https://help.withallo.com/en/v2/api-reference/white-label/order-esim.md) with the same `phone_number` and the new member's `id` as `holder_id`. The order charges the setup fee. Then deliver the eSIM as usual, once you receive [`partner.esim.ready`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneresimready).

To cut a single eSIM without removing anyone, for example a lost phone, call [Revoke eSIM](https://help.withallo.com/en/v2/api-reference/white-label/revoke-esim.md).

## How to let an account send SMS under its brand name

A sender ID is the name recipients see instead of a phone number, for example `PLOMBMARTIN`. In France, automated SMS cannot be sent from mobile numbers, so a sender ID is how your software texts the account's customers.

**1. Declare the sender ID**

Call [Declare sender ID](https://help.withallo.com/en/v2/api-reference/white-label/create-sender-id.md) with the name, 1 to 11 letters or digits, and an optional example message. A sender ID belongs to one Allo account only, and an account holds at most 3. The sender ID starts with status `PENDING`.

**2. Wait for Allo's review**

Allo reviews the sender ID by hand, usually in 1 to 5 business days. Allo then sends [`partner.sender_id.validated`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partnersender_idvalidated) or [`partner.sender_id.failed`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partnersender_idfailed) to your own webhook endpoint, not to the account's. Without a webhook endpoint, poll [Get sender ID](https://help.withallo.com/en/v2/api-reference/white-label/get-sender-id.md).

**3. Send SMS with it**

Once the sender ID is `VALIDATED`, the account sends SMS with [Send SMS (France)](https://help.withallo.com/en/v2/api-reference/sms/send-sms-france.md): `POST /v1/api/sms` with `sender_id` instead of `from`, using the account's API key, which needs the `SMS_SEND` scope.

```json theme={null}
{
  "sender_id": "PLOMBMARTIN",
  "to": "+33612345678",
  "message": "Bonjour, votre intervention est confirmée demain à 9h."
}
```

> [!NOTE]
>
> Allo can deactivate a sender ID after validating it. Its status becomes `DISABLED` and sending with it is refused. No webhook is sent for this change: read [Get sender ID](https://help.withallo.com/en/v2/api-reference/white-label/get-sender-id.md) or [List sender IDs](https://help.withallo.com/en/v2/api-reference/white-label/list-sender-ids.md) to check it.

## How to change an eSIM's data

Each eSIM has a data tier, renewed with the subscription you pay for the account. You can change it, or add data for the current month, from the API:

* [Change eSIM tier](https://help.withallo.com/en/v2/api-reference/white-label/change-esim-tier.md) moves the eSIM to another tier. An upgrade is charged now, prorated for the rest of the billing period, and its extra data is added within about a minute. A downgrade applies at the end of the period already paid, and nothing is refunded.
* [Buy eSIM top-up](https://help.withallo.com/en/v2/api-reference/white-label/buy-esim-topup.md) adds 5, 10 or 20 GB to the eSIM for the current calendar month (Paris time), for a one-off charge. Unused top-up data lapses at the end of that month.

Both are charged like every partner charge, prepaid credit first, then your card on file. [Get eSIM offer](https://help.withallo.com/en/v2/api-reference/white-label/get-esim-offer.md) returns the prices of the tiers and the top-ups. Send an `Idempotency-Key` header with both requests, so a retry never charges you twice. It is required to buy a top-up.

[Get eSIM](https://help.withallo.com/en/v2/api-reference/white-label/get-esim.md) returns the data used this month in `data`. When an eSIM reaches its allowance, mobile data stops until the next month or a top-up, while calls and SMS keep working. Allo sends [`partner.esim.data_low`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneresimdata_low) at 80% of the allowance and [`partner.esim.data_exhausted`](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog#partneresimdata_exhausted) at 100%.

## Endpoints

| Method | Path | Description |
| - | - | - |
| `POST` | `/v2/api/partner/accounts/{id}/suspend` | Suspend an account now: calls, SMS and eSIM lines stop, numbers and billing stay |
| `POST` | `/v2/api/partner/accounts/{id}/resume` | Resume a suspended account |
| `GET` | `/v2/api/partner/accounts/{id}/numbers/price` | Get what one more number costs on an account |
| `POST` | `/v2/api/partner/accounts/{id}/numbers` | Add a number to an account, billed on its subscription |
| `POST` | `/v2/api/partner/accounts/{id}/members` | Add a member to an account, with a new number or one the account already holds |
| `GET` | `/v2/api/partner/accounts/{id}/members` | List an account's members |
| `DELETE` | `/v2/api/partner/accounts/{id}/members/{member_id}` | Remove a member: their eSIMs are revoked, their numbers stay on the account |
| `GET` | `/v2/api/partner/accounts/{account_id}/esims/offer` | Get the eSIM setup fee, data tiers and top-ups for an account |
| `POST` | `/v2/api/partner/accounts/{account_id}/esims` | Order an eSIM for one of the account's numbers, charged to you |
| `GET` | `/v2/api/partner/esims/{id}` | Get an eSIM's status (`PROVISIONING`, `ACTIVE`, `FAILED`, `REVOKED`), tier and data use this month |
| `PUT` | `/v2/api/partner/esims/{id}/tier` | Change an eSIM's data tier (an upgrade is charged to you) |
| `POST` | `/v2/api/partner/esims/{id}/topups` | Buy a data top-up for an eSIM for the current month, charged to you |
| `POST` | `/v2/api/partner/esims/{id}/revoke` | Revoke an eSIM now: it stops working, its number stays on the account |
| `GET` | `/v2/api/partner/esims/{id}/activation_code` | Get a ready eSIM's activation code and QR code |
| `POST` | `/v2/api/partner/accounts/{account_id}/sender_ids` | Declare a sender ID on an account, reviewed by Allo |
| `GET` | `/v2/api/partner/accounts/{account_id}/sender_ids` | List an account's sender IDs |
| `GET` | `/v2/api/partner/accounts/{account_id}/sender_ids/{id}` | Get a sender ID's status (`PENDING`, `VALIDATED`, `FAILED`, `DISABLED`) |

Accounts are priced, created, read and deactivated with the [Partners](https://help.withallo.com/en/v2/api-reference/partner/overview.md#endpoints) endpoints.


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