Authentication

All API requests require an API key passed in the Authorization header.

Header format

Authorization: Api-Key ak_live_your_key_here

Generating API keys

Go to Allo Settings > API
Click Create API Key
Select the scopes your integration needs
Copy the key. It won’t be shown again

API key scopes

Each API key has specific scopes that determine what operations it can perform.

Scope	Description
`CONVERSATIONS_READ`	Read calls, SMS, and conversation history
`CONVERSATIONS_WRITE`	Edit call summaries and archive or mark conversations
`CRM_READ`	Get and search people, companies, and deals
`CRM_WRITE`	Create and update people and companies
`SMS_SEND`	Send SMS and MMS messages
`WEBHOOKS_READ_WRITE`	Create and manage webhook configurations
`PHONE_NUMBERS_READ`	List phone numbers and their capabilities
`PHONE_NUMBERS_WRITE`	Save and publish call flows
`USERS_READ`	List team members and their roles
`TAGS_READ`	List available tags
`TAGS_WRITE`	Create and delete tags, add and remove them on conversation items
`NOTES_READ`	Read conversation notes and person notes
`NOTES_WRITE`	Create, edit, and delete notes
`THREADS_READ`	Read discussion threads and their comments
`THREADS_WRITE`	Create threads and comments, edit comments, resolve threads
`SUMMARY_TEMPLATES_READ`	Read the team’s call summary templates
`SUMMARY_TEMPLATES_WRITE`	Create, update, and delete summary templates, and set a number’s default
`BILLING`	Access billing and subscription information
`DIALING_QUEUE_READ_WRITE`	Manage Power Dialer queues
`AGENTS_READ`	Read AI receptionist configuration, connected calendars, and voices
`AGENTS_WRITE`	Configure the AI receptionist, its prompt, its knowledge, and turn it on or off
`PARTNER`	Provision and manage Allo accounts as a reseller. Granted manually to approved resellers, it cannot be self-issued

GET /v2/api/me requires no scope. Any valid key can call it, and its endpoints array is the authoritative list of what your key can reach.

Scope-to-endpoint mapping

Every documented endpoint and the scope it needs. If a call returns 403 with code API_KEY_INSUFFICIENT_SCOPE, the key is valid but missing the scope listed here. Discovery

Endpoint	Method	Required scope
`/v2/api/me`	GET	none

Conversations

Endpoint	Method	Required scope
`/v2/api/conversations`	GET	`CONVERSATIONS_READ`
`/v2/api/conversations/items/batch`	POST	`CONVERSATIONS_READ`
`/v2/api/conversations/items/search`	POST	`CONVERSATIONS_READ`
`/v2/api/conversations/items/{id}`	GET	`CONVERSATIONS_READ`
`/v2/api/conversations/items/{id}/summary`	PATCH	`CONVERSATIONS_WRITE`
`/v2/api/conversations/items/{id}/tags`	POST	`TAGS_WRITE`
`/v2/api/conversations/items/{id}/tags/{tag}`	DELETE	`TAGS_WRITE`
`/v2/api/conversations/notes/{id}`	DELETE	`NOTES_WRITE`
`/v2/api/conversations/notes/{id}`	GET	`NOTES_READ`
`/v2/api/conversations/notes/{id}`	PATCH	`NOTES_WRITE`
`/v2/api/conversations/{contact_number}/action`	PUT	`CONVERSATIONS_WRITE`
`/v2/api/conversations/{contact_number}/notes`	GET	`NOTES_READ`
`/v2/api/conversations/{contact_number}/notes`	POST	`NOTES_WRITE`

CRM

Endpoint	Method	Required scope
`/v2/api/crm/companies`	POST	`CRM_WRITE`
`/v2/api/crm/companies/search`	POST	`CRM_READ`
`/v2/api/crm/companies/{id}`	GET	`CRM_READ`
`/v2/api/crm/companies/{id}`	PUT	`CRM_WRITE`
`/v2/api/crm/deals/search`	POST	`CRM_READ`
`/v2/api/crm/deals/{id}`	GET	`CRM_READ`
`/v2/api/crm/people`	POST	`CRM_WRITE`
`/v2/api/crm/people/search`	POST	`CRM_READ`
`/v2/api/crm/people/{id}`	GET	`CRM_READ`
`/v2/api/crm/people/{id}`	PUT	`CRM_WRITE`
`/v2/api/crm/people/{person_id}/notes`	GET	`NOTES_READ`
`/v2/api/crm/people/{person_id}/notes`	POST	`NOTES_WRITE`
`/v2/api/crm/people/{person_id}/notes/{note_id}`	DELETE	`NOTES_WRITE`
`/v2/api/crm/people/{person_id}/notes/{note_id}`	PATCH	`NOTES_WRITE`

Threads

Endpoint	Method	Required scope
`/v2/api/threads`	GET	`THREADS_READ`
`/v2/api/threads`	POST	`THREADS_WRITE`
`/v2/api/threads/comments/{comment_id}`	PATCH	`THREADS_WRITE`
`/v2/api/threads/{id}`	GET	`THREADS_READ`
`/v2/api/threads/{id}/comments`	POST	`THREADS_WRITE`
`/v2/api/threads/{id}/resolve`	POST	`THREADS_WRITE`
`/v2/api/threads/{id}/unresolve`	POST	`THREADS_WRITE`

SMS

Endpoint	Method	Required scope
`/v1/api/sms`	POST	`SMS_SEND`
`/v1/api/sms#france`	POST	`SMS_SEND`

Phone numbers and call flows

Endpoint	Method	Required scope
`/v2/api/numbers`	GET	`PHONE_NUMBERS_READ`
`/v2/api/numbers/{number}/agent`	GET	`AGENTS_READ`
`/v2/api/numbers/{number}/agent`	PATCH	`AGENTS_WRITE`
`/v2/api/numbers/{number}/agent/knowledge/files/{id}`	DELETE	`AGENTS_WRITE`
`/v2/api/numbers/{number}/agent/knowledge/websites`	POST	`AGENTS_WRITE`
`/v2/api/numbers/{number}/agent/knowledge/websites/{id}`	DELETE	`AGENTS_WRITE`
`/v2/api/numbers/{number}/agent/knowledge/websites/{id}`	PATCH	`AGENTS_WRITE`
`/v2/api/numbers/{number}/agent/prompt`	PUT	`AGENTS_WRITE`
`/v2/api/numbers/{number}/agent/status`	PUT	`AGENTS_WRITE`
`/v2/api/numbers/{number}/call_flow`	GET	`PHONE_NUMBERS_READ`
`/v2/api/numbers/{number}/call_flow/draft`	GET	`PHONE_NUMBERS_READ`
`/v2/api/numbers/{number}/call_flow/draft`	PUT	`PHONE_NUMBERS_WRITE`
`/v2/api/numbers/{number}/call_flow/publish`	POST	`PHONE_NUMBERS_WRITE`
`/v2/api/numbers/{number}/default_summary_template`	PUT	`SUMMARY_TEMPLATES_WRITE`

AI receptionist

Endpoint	Method	Required scope
`/v2/api/calendars`	GET	`AGENTS_READ`
`/v2/api/calendars/{id}`	GET	`AGENTS_READ`
`/v2/api/voices`	GET	`AGENTS_READ`

Summary templates

Endpoint	Method	Required scope
`/v2/api/summary_templates`	GET	`SUMMARY_TEMPLATES_READ`
`/v2/api/summary_templates`	POST	`SUMMARY_TEMPLATES_WRITE`
`/v2/api/summary_templates/{id}`	DELETE	`SUMMARY_TEMPLATES_WRITE`
`/v2/api/summary_templates/{id}`	GET	`SUMMARY_TEMPLATES_READ`
`/v2/api/summary_templates/{id}`	PUT	`SUMMARY_TEMPLATES_WRITE`

Tags

Endpoint	Method	Required scope
`/v2/api/tags`	GET	`TAGS_READ`
`/v2/api/tags`	POST	`TAGS_WRITE`
`/v2/api/tags/{id}`	DELETE	`TAGS_WRITE`

Users

Endpoint	Method	Required scope
`/v2/api/users`	GET	`USERS_READ`
`/v2/api/users/{id}`	GET	`USERS_READ`

Webhooks

Endpoint	Method	Required scope
`/v2/api/webhooks`	GET	`WEBHOOKS_READ_WRITE`
`/v2/api/webhooks`	POST	`WEBHOOKS_READ_WRITE`
`/v2/api/webhooks/event_types`	GET	`WEBHOOKS_READ_WRITE`
`/v2/api/webhooks/{webhook_id}`	DELETE	`WEBHOOKS_READ_WRITE`
`/v2/api/webhooks/{webhook_id}`	GET	`WEBHOOKS_READ_WRITE`
`/v2/api/webhooks/{webhook_id}`	PUT	`WEBHOOKS_READ_WRITE`

Analytics

Endpoint	Method	Required scope
`/v2/api/analytics/outbound`	POST	`CONVERSATIONS_READ`
`/v2/api/analytics/overview`	POST	`CONVERSATIONS_READ`

Dialing queues

Endpoint	Method	Required scope
`/v2/api/dialing-queues/current`	GET	`DIALING_QUEUE_READ_WRITE`
`/v2/api/dialing-queues/current`	PATCH	`DIALING_QUEUE_READ_WRITE`
`/v2/api/dialing-queues/current`	POST	`DIALING_QUEUE_READ_WRITE`
`/v2/api/dialing-queues/current/numbers`	DELETE	`DIALING_QUEUE_READ_WRITE`
`/v2/api/dialing-queues/current/numbers`	POST	`DIALING_QUEUE_READ_WRITE`

Partner

Endpoint	Method	Required scope
`/v2/api/partner/accounts`	POST	`PARTNER`
`/v2/api/partner/accounts/{id}`	DELETE	`PARTNER`
`/v2/api/partner/accounts/{id}`	GET	`PARTNER`

Example request

curl -X GET "https://api.withallo.com/v2/api/conversations" \
  -H "Authorization: Api-Key ak_live_abc123def456"

Error responses

Invalid or missing key (401)

{
  "error": {
    "type": "authentication_error",
    "code": "API_KEY_INVALID",
    "message": "The API key provided is invalid or has been revoked.",
    "retryable": false,
    "request_id": "req_a1b2c3d4e5f6",
    "doc_url": "https://help.withallo.com/en/v2/api-reference/guides/error-codes#API_KEY_INVALID"
  }
}

Insufficient scope (403)

{
  "error": {
    "type": "permission_error",
    "code": "API_KEY_INSUFFICIENT_SCOPE",
    "message": "This API key lacks the 'CONVERSATIONS_READ' scope required for this endpoint.",
    "retryable": false,
    "request_id": "req_a1b2c3d4e5f6",
    "suggestion": "Create a new API key with the required scope at https://web.withallo.com/settings/api"
  }
}

Security

API keys are scoped to a single team
Keys can be revoked at any time from settings
Never expose keys in client-side code or public repositories
Use environment variables to store keys in your application

API

Webhooks

Conversations

CRM

People

Companies

Deals

Notes

Threads

Phone Numbers

AI Receptionist

Tags

Summary Templates

Users

SMS

Analytics

Power Dialer

Partner

Header format

Generating API keys

API key scopes

Scope-to-endpoint mapping

Example request

Error responses

Security

​Header format

​Generating API keys

​API key scopes

​Scope-to-endpoint mapping

​Example request

​Error responses

​Security

Header format

Generating API keys

API key scopes

Scope-to-endpoint mapping

Example request

Error responses

Security