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 prefix | Used 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
API key setup, scopes, and the scope-to-endpoint mapping
Request limits and headers
Page-based results with total counts
Error format and recovery
Every error code and what to do about it
Ready-made request patterns for the usual jobs
Resources
| Resource | Main paths | What it covers |
|---|---|---|
| Conversations | GET /v2/api/conversations, POST /v2/api/conversations/items/search | Unified call and SMS timeline, keyword search across transcripts and message content |
| SMS | POST /v1/api/sms | Send SMS and MMS from your Allo numbers or sender IDs |
| Fax | POST /v2/api/faxes | Send 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/attributes | Create, 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}/notes | Internal team notes on conversations and person profiles, with @mentions |
| Threads | /v2/api/threads | Team discussion threads on calls, SMS, and conversation notes |
| Webhooks | /v2/api/webhooks | Real-time event notifications with HMAC signatures and automatic retries |
| Phone numbers | GET /v2/api/numbers, /v2/api/numbers/{number}/call_flow | Your Allo numbers with capabilities and member access, plus inbound call routing |
| Users | GET /v2/api/users, GET /v2/api/me | Team roster with roles and assigned numbers, and API key capabilities |
| Tags | /v2/api/tags, /v2/api/conversations/items/{id}/tags | Create and list call tags, add and remove them on calls and SMS |
| Summary templates | /v2/api/summary_templates | Templates that shape how AI structures call summaries |
| Analytics | POST /v2/api/analytics/overview, POST /v2/api/analytics/outbound | Team KPIs with period-over-period comparison and per-user breakdown |
| Dialing queues | /v2/api/dialing-queues/current | Read and fill the Power Dialer queue |
| AI receptionist | /v2/api/numbers/{number}/agent | Configure the receptionist, its prompt, its knowledge, and its on/off status |
| Partners | /v2/api/partner/accounts, /v2/api/partner/credit | Create, price and deactivate Allo accounts as a reseller |
| White label | /v2/api/partner/accounts/{id}/..., /v2/api/partner/esims | Manage 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:
| Operation | Limit |
|---|---|
| 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
Copy-ready requests for syncing, searching, and reporting
Scopes and the scope-to-endpoint mapping
Stop polling and receive events instead
Connect an AI agent to Allo without writing HTTP calls