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
`CONTACTS_READ`	Read contact information
`CONTACTS_READ_WRITE`	Read and write contact information
`SMS_SEND`	Send SMS and MMS messages
`WEBHOOKS_READ_WRITE`	Create and manage webhook configurations
`PHONE_NUMBERS_READ`	List phone numbers and their capabilities
`USERS_READ`	List team members and their roles
`TAGS_READ`	List available tags
`TAGS_WRITE`	Add and remove tags 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
`BILLING`	Access billing and subscription information
`DIALING_QUEUE_READ_WRITE`	Manage Power Dialer queues

Scope-to-endpoint mapping

Endpoint	Method	Required scope
`/v2/api/conversations`	GET	`CONVERSATIONS_READ`
`/v2/api/conversations/items/search`	POST	`CONVERSATIONS_READ`
`/v2/api/conversations/items/{id}`	GET	`CONVERSATIONS_READ`
`/v2/api/conversations/items/batch`	POST	`CONVERSATIONS_READ`
`/v2/api/conversations/{contact_number}/action`	PUT	`CONVERSATIONS_READ`
`/v2/api/conversations/items/{id}/tags`	POST	`TAGS_WRITE`
`/v2/api/conversations/items/{id}/tags/{tag}`	DELETE	`TAGS_WRITE`
`/v2/api/users`	GET	`USERS_READ`
`/v2/api/users/{id}`	GET	`USERS_READ`
`/v2/api/tags`	GET	`TAGS_READ`
`/v2/api/numbers`	GET	`PHONE_NUMBERS_READ`
`/v2/api/conversations/{contact_number}/notes`	GET	`NOTES_READ`
`/v2/api/conversations/{contact_number}/notes`	POST	`NOTES_WRITE`
`/v2/api/conversations/notes/{id}`	GET	`NOTES_READ`
`/v2/api/conversations/notes/{id}`	PATCH	`NOTES_WRITE`
`/v2/api/conversations/notes/{id}`	DELETE	`NOTES_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}`	PATCH	`NOTES_WRITE`
`/v2/api/crm/people/{person_id}/notes/{note_id}`	DELETE	`NOTES_WRITE`
`/v2/api/threads`	GET	`THREADS_READ`
`/v2/api/threads`	POST	`THREADS_WRITE`
`/v2/api/threads/{id}`	GET	`THREADS_READ`
`/v2/api/threads/{id}/comments`	POST	`THREADS_WRITE`
`/v2/api/threads/comments/{comment_id}`	PATCH	`THREADS_WRITE`
`/v2/api/threads/{id}/resolve`	POST	`THREADS_WRITE`
`/v2/api/threads/{id}/unresolve`	POST	`THREADS_WRITE`

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

Overview Rate limits

API

Webhooks

Conversations

People

Companies

Deals

Notes

Threads

Phone Numbers

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