Allo

Overview

Integrate Allo's communication capabilities into your applications

Updated on

The Allo API enables developers to integrate Allo's communication capabilities directly into their applications. Build CRM integrations, automate post-call workflows, sync conversation data, and power AI agents with your team's call and SMS history.

Base URL

Every endpoint lives under https://api.withallo.com. The version is part of the path, not a header.

Path prefixUsed by
/v2/api/...Everything except SMS sending: conversations, CRM, notes, threads, webhooks, phone numbers, users, tags, summary templates, analytics, dialing queues, AI receptionist, partner
/v1/api/...SMS sending (POST /v1/api/sms)

There is no POST /v2/api/sms. Sending an SMS is a v1 call. Full path and body: Send SMS.

Start here

Call GET /v2/api/me first. It returns your key's scopes, the exact endpoints that key can reach, your team, and your rate limits, so you never have to guess what is available.

curl -X GET "https://api.withallo.com/v2/api/me" \
  -H "Authorization: Api-Key ak_live_your_key_here"
{
  "data": {
    "api_key_id": "api-abc123def456",
    "scopes": ["CONVERSATIONS_READ", "PHONE_NUMBERS_READ", "TAGS_READ"],
    "endpoints": [
      { "method": "GET", "path": "/v2/api/conversations", "description": "List conversations grouped by contact number", "scope": "CONVERSATIONS_READ" }
    ],
    "team": { "id": "team-xyz789", "name": "Acme Sales" },
    "rate_limits": { "read_per_second": 20, "write_per_second": 5 }
  }
}

Any valid API key can call /v2/api/me. No specific scope is required. See Me.

Getting started

Before using the API, make sure you have:

  • An active Allo subscription
  • Admin or Manager permissions on your workspace
  • An API key generated from Settings > API

Authentication

API keys are generated through your workspace settings. Include the key in the Authorization header of every request:

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

The scheme is Api-Key, not Bearer. Store your API key securely. Do not expose it in client-side code or public repositories.

Guides

Resources

ResourceMain pathsWhat it covers
ConversationsGET /v2/api/conversations, POST /v2/api/conversations/items/searchUnified call and SMS timeline, keyword search across transcripts and message content
SMSPOST /v1/api/smsSend SMS and MMS from your Allo numbers or sender IDs
FaxPOST /v2/api/faxesSend a PDF as a fax from an Allo line with fax turned on
CRM/v2/api/crm/people, /v2/api/crm/companies, /v2/api/crm/deals, /v2/api/crm/attributes, /v2/api/crm/companies/attributesCreate, read, update, and search people, companies, and deals, and manage custom contact fields and company attributes
Notes/v2/api/conversations/{contact_number}/notes, /v2/api/crm/people/{person_id}/notesInternal team notes on conversations and person profiles, with @mentions
Threads/v2/api/threadsTeam discussion threads on calls, SMS, and conversation notes
Webhooks/v2/api/webhooksReal-time event notifications with HMAC signatures and automatic retries
Phone numbersGET /v2/api/numbers, /v2/api/numbers/{number}/call_flowYour Allo numbers with capabilities and member access, plus inbound call routing
UsersGET /v2/api/users, GET /v2/api/meTeam roster with roles and assigned numbers, and API key capabilities
Tags/v2/api/tags, /v2/api/conversations/items/{id}/tagsCreate and list call tags, add and remove them on calls and SMS
Summary templates/v2/api/summary_templatesTemplates that shape how AI structures call summaries
AnalyticsPOST /v2/api/analytics/overview, POST /v2/api/analytics/outboundTeam KPIs with period-over-period comparison and per-user breakdown
Dialing queues/v2/api/dialing-queues/currentRead and fill the Power Dialer queue
AI receptionist/v2/api/numbers/{number}/agentConfigure the receptionist, its prompt, its knowledge, and its on/off status
Partners/v2/api/partner/accounts, /v2/api/partner/creditCreate, price and deactivate Allo accounts as a reseller
White label/v2/api/partner/accounts/{id}/..., /v2/api/partner/esimsManage the members, numbers, eSIMs, suspensions and sender IDs of your accounts from your own product

Rate limiting

Rate limits vary by request type and are applied per API key:

OperationLimit
Read requests (GET)20 requests/second
Write requests (POST, PUT, PATCH, DELETE)5 requests/second

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can monitor your usage. See Rate limits for details.

Quick example

Get your recent conversations:

curl -X GET "https://api.withallo.com/v2/api/conversations?size=5" \
  -H "Authorization: Api-Key ak_live_your_key_here"
{
  "data": [
    {
      "contact_number": "+14155551234",
      "contacts": [{ "id": "cnt-abc", "name": "Sarah Johnson", "company": { "name": "Acme Corp" } }],
      "last_activity": "2026-04-21T14:30:00Z",
      "last_item": { "id": "cll-abc123", "type": "CALL", "direction": "INBOUND", "result": "ANSWERED", "summary": "Customer called about upgrading their plan.", "duration": 145 }
    }
  ],
  "pagination": { "page": 1, "size": 5, "total_count": 156, "has_more": true }
}

FAQ

What is the base URL and how is the API versioned?

The host is always https://api.withallo.com. The version is the first path segment. Almost everything is /v2/api/.... SMS sending is /v1/api/sms. There is no version header and no Accept header to set.

How do I authenticate?

Send Authorization: Api-Key ak_live_your_key_here on every request. The scheme is Api-Key, not Bearer. Generate keys at Settings > API with Admin or Manager permissions. A key is scoped to a single team and is shown only once. See Authentication.

Which scope does an endpoint need?

Call GET /v2/api/me. Its endpoints array lists every path your key can reach along with the scope each one needs. The full table is also in Authentication. A 403 with code API_KEY_INSUFFICIENT_SCOPE means the key is valid but missing a scope, so create a new key with that scope.

How do I send an SMS?

POST /v1/api/sms for a US Allo number, and POST /v1/api/sms with a French sender ID for France. The scope is SMS_SEND and phone numbers are E.164 (+14155551234). See Send SMS and Send SMS (France).

How do I find a specific call or message?

Use POST /v2/api/conversations/items/search with filters such as date, direction, type, and a search string that matches transcripts and message content. GET /v2/api/conversations groups activity by contact number instead. To fetch known IDs in bulk, use POST /v2/api/conversations/items/batch. See Conversations.

How does pagination work?

Paginated endpoints take page and size and return a pagination object with page, size, total_count, and has_more. Increment page until has_more is false. To count results without fetching them, request size=1 and read pagination.total_count. See Pagination.

What does an error look like and can I retry it?

Every error returns an error object with type, code, message, retryable, request_id, and often param, suggestion, and doc_url. Retry only when retryable is true. On 429, wait retry_after_seconds before retrying. See Error handling and Error codes.

What are the rate limits?

20 GET requests per second and 5 write requests per second, per API key. Read X-RateLimit-Remaining and X-RateLimit-Reset on every response. See Rate limits.

What format do phone numbers use?

E.164, with the leading + and country code, for example +14155551234. When a number goes in a query string, URL-encode the + as %2B.

How do I get notified when a call ends instead of polling?

Create a webhook with POST /v2/api/webhooks and subscribe to the events you need. Payloads are signed with HMAC and retried automatically. List the available events with GET /v2/api/webhooks/event_types. See Webhooks.

Can I provision Allo accounts for my own customers?

Yes, with the PARTNER scope. POST /v2/api/partner/accounts creates an account, provisions a number, and returns a scoped API key for it. The PARTNER scope is granted manually to approved resellers and cannot be self-issued. See Partners, and White label to run the accounts from your own product.

Is there an MCP server?

Yes. See Allo MCP to connect an AI agent to Allo without writing HTTP calls.

Next steps