Skip to main content

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.

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

  1. Go to Allo Settings > API
  2. Click Create API Key
  3. Select the scopes your integration needs
  4. 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.
ScopeDescription
CONVERSATIONS_READRead calls, SMS, and conversation history
CONTACTS_READRead contact information
CONTACTS_READ_WRITERead and write contact information
SMS_SENDSend SMS and MMS messages
WEBHOOKS_READ_WRITECreate and manage webhook configurations
PHONE_NUMBERS_READList phone numbers and their capabilities
USERS_READList team members and their roles
TAGS_READList available tags
TAGS_WRITEAdd and remove tags on conversation items
BILLINGAccess billing and subscription information
DIALING_QUEUE_READ_WRITEManage dialing queues

​
Scope-to-endpoint mapping

EndpointMethodRequired scope
/v2/api/conversationsGETCONVERSATIONS_READ
/v2/api/conversations/items/searchPOSTCONVERSATIONS_READ
/v2/api/conversations/items/{id}GETCONVERSATIONS_READ
/v2/api/conversations/items/batchPOSTCONVERSATIONS_READ
/v2/api/conversations/{contact_number}/actionPUTCONVERSATIONS_READ
/v2/api/conversations/items/{id}/tagsPOSTTAGS_WRITE
/v2/api/conversations/items/{id}/tags/{tag}DELETETAGS_WRITE
/v2/api/usersGETUSERS_READ
/v2/api/users/{id}GETUSERS_READ
/v2/api/tagsGETTAGS_READ
/v2/api/numbersGETPHONE_NUMBERS_READ

​
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