Allo

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

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. 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 first to see the amount.
  • Allo draws on your prepaid 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 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 and 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:

ScopeWhat the key can do on the account
CRM_READGet and search people, companies and deals, and list custom fields
CRM_WRITECreate and update people and companies, and create custom fields
WEBHOOKS_READ_WRITECreate and manage the account's webhook endpoints
CONVERSATIONS_READRead the account's calls, SMS, transcripts and summaries
PHONE_NUMBERS_READList the account's numbers, and read a number's published call flow and its draft
PHONE_NUMBERS_WRITESave and publish a number's call flow draft. The key cannot buy or release numbers
AGENTS_READRead a number's AI receptionist, and list the connected calendars and the available voices
AGENTS_WRITEConfigure the AI receptionist: its settings, its prompt, turning it on or off, and its knowledge (add, update and remove websites, remove files)
SUMMARY_TEMPLATES_READList and read the account's call summary templates
SUMMARY_TEMPLATES_WRITECreate, update and delete summary templates, and set a number's default template with PUT /v2/api/numbers/{number}/default_summary_template
TAGS_READList the account's tags with GET /v2/api/tags
TAGS_WRITECreate and delete tags, and add or remove a tag on a call with POST and DELETE /v2/api/conversations/items/{id}/tags
USERS_READList the account's members, and get one, with GET /v2/api/users
SMS_SENDSend 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 for the endpoints each scope covers.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Body

emailstringrequired

Becomes the account's login.

namestringrequired
intervalenum<string>required

Billing interval of the account's own subscription, billed to you.

MONTHLYYEARLY

personal_mobilestring | null

Optional. An existing mobile the new number can attach to.

partner_client_refstring

Your own reference for this customer. Echoed back and on the activation webhook.

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

Responses

201Account created
dataobject
6 fields
idstring
api_keystring | null

Scoped API key for the new account, with the scopes CRM_READ, CRM_WRITE, WEBHOOKS_READ_WRITE, CONVERSATIONS_READ, PHONE_NUMBERS_READ, PHONE_NUMBERS_WRITE, AGENTS_READ, AGENTS_WRITE, SUMMARY_TEMPLATES_READ and SUMMARY_TEMPLATES_WRITE (no SMS_SEND). Returned only on create.

phone_numbersstring[]
statusstring
activatedboolean

True once the customer has signed in on a device.

partner_client_refstring | null
400Validation error: a required field is missing (MISSING_FIELD), or number_preference.esim is true with a country other than FR (ESIM_NOT_AVAILABLE_IN_COUNTRY).
errorobject
401
402Billing error, nothing is created. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the first period and your billing account has no card on file. PARTNER_BILLING_FAILED: your card was declined. PARTNER_SUBSCRIPTION_NOT_BILLABLE: you have no billing account Allo can charge.
errorobject
403The API key lacks the PARTNER scope, your account is not an enabled partner (PARTNER_ACCESS_REQUIRED), or your partner contract cannot create accounts (PARTNER_CONTRACT_CANNOT_PROVISION). Only Discounted licence (reseller) partners can create accounts.
errorobject
409An account already exists (PARTNER_ACCOUNT_ALREADY_EXISTS) or no number is available (NO_NUMBER_AVAILABLE).
errorobject
429