# Create account

> Creates an Allo account for one of your customers, provisions a phone number, and returns a scoped API key for the account. Requires the PARTNER scope and a…

`POST /v2/api/partner/accounts`

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

Creates an Allo account for one of your customers and provisions a phone number for it. The response returns a **scoped API key** for the new account (shown only once) alongside the provisioned number(s) and status.

- `interval` is required: `MONTHLY` or `YEARLY`. It sets the billing interval of the account's subscription.
- `number_preference.country` is required (ISO country code, e.g. `FR`); `number_preference.prefix` is optional (e.g. `+337`).
- `number_preference.esim` is optional, `false` by default. Set it to `true` to get a French mobile number that can carry an eSIM, which you then order with [Order eSIM](/docs/white-label/order-esim). eSIM numbers are only available in France: with any `country` other than `FR`, the request fails with `ESIM_NOT_AVAILABLE_IN_COUNTRY`. `prefix` still applies, for example `7` or `+337`.
- A phone number is secured **before** the account is created. If none can be assigned or purchased, the request fails with `NO_NUMBER_AVAILABLE` and nothing is created.
- The account gets its own Business plan subscription, billed to you with your partner discount applied. The full period is charged when the account is created. No charge is made to your customer. Call [Get account price](/docs/partner/get-price) first to see the amount.
- Allo draws on your [prepaid credit](/docs/partner/get-credit) first, then charges your card on file for the rest.
- If your prepaid credit does not cover the first period and you have no card on file, the request fails with `402 PARTNER_CREDIT_INSUFFICIENT` and nothing is created.
- If your card is declined, the request fails with `402 PARTNER_BILLING_FAILED` and nothing is created.
- If the email or personal mobile already belongs to an Allo account, the request fails with `PARTNER_ACCOUNT_ALREADY_EXISTS`.
- If your account is not an enabled partner, the request fails with `PARTNER_ACCESS_REQUIRED`. If your partner contract cannot create accounts, it fails with `PARTNER_CONTRACT_CANNOT_PROVISION`. Only Discounted licence (reseller) partners can create accounts.

The [partner portal](/help/support/partner-portal) creates accounts the same way, without code.

Numbers and teammates are then added in the Allo app. White-label partners add them from the API with [Add number](/docs/white-label/add-number) and [Add member](/docs/white-label/add-member).

## The account's API key

The `api_key` in the response acts on the new account, not on yours. Store it right away: Allo returns it only once, and `GET /v2/api/partner/accounts/{id}` does not return it again. The key has these 14 scopes:

| Scope | What the key can do on the account |
|-------|-------------------------------------|
| `CRM_READ` | Get and search people, companies and deals, and list custom fields |
| `CRM_WRITE` | Create and update people and companies, and create custom fields |
| `WEBHOOKS_READ_WRITE` | Create and manage the account's webhook endpoints |
| `CONVERSATIONS_READ` | Read the account's calls, SMS, transcripts and summaries |
| `PHONE_NUMBERS_READ` | List the account's numbers, and read a number's published call flow and its draft |
| `PHONE_NUMBERS_WRITE` | Save and publish a number's call flow draft. The key cannot buy or release numbers |
| `AGENTS_READ` | Read a number's AI receptionist, and list the connected calendars and the available voices |
| `AGENTS_WRITE` | Configure the AI receptionist: its settings, its prompt, turning it on or off, and its knowledge (add, update and remove websites, remove files) |
| `SUMMARY_TEMPLATES_READ` | List and read the account's call summary templates |
| `SUMMARY_TEMPLATES_WRITE` | Create, update and delete summary templates, and set a number's default template with `PUT /v2/api/numbers/{number}/default_summary_template` |
| `TAGS_READ` | List the account's tags with `GET /v2/api/tags` |
| `TAGS_WRITE` | Create and delete tags, and add or remove a tag on a call with `POST` and `DELETE /v2/api/conversations/items/{id}/tags` |
| `USERS_READ` | List the account's members, and get one, with `GET /v2/api/users` |
| `SMS_SEND` | Send an SMS with `POST /v1/api/sms` |

French regulation forbids automated SMS from a mobile number, so sending from the account's French mobile number fails with `A2P_NOT_ENABLED`. Send from a validated sender ID instead, with the `sender_id` parameter.

Keys issued before these scopes were added receive them automatically. The secret does not change, so you have nothing to update.

See [API key scopes](/docs/guides/authentication#api-key-scopes) for the endpoints each scope covers.
