Overview

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

Authentication

API key setup, scopes, and the scope-to-endpoint mapping

Rate limits

Request limits and headers

Pagination

Page-based results with total counts

Error handling

Error format and recovery

Error codes

Every error code and what to do about it

Common use cases

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
CRM	`/v2/api/crm/people`, `/v2/api/crm/companies`, `/v2/api/crm/deals`	Create, read, update, and search people, companies, and deals
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
Partner	`/v2/api/partner/accounts`	Provision and manage Allo accounts as a white-label reseller

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 Partner.

Is there an MCP server?

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

Next steps

Common use cases

Copy-ready requests for syncing, searching, and reporting

Authentication

Scopes and the scope-to-endpoint mapping

Webhooks

Stop polling and receive events instead

Allo MCP

Connect an AI agent to Allo without writing HTTP calls

API

Webhooks

Conversations

CRM

People

Companies

Deals

Notes

Threads

Phone Numbers

AI Receptionist

Tags

Summary Templates

Users

SMS

Analytics

Power Dialer

Partner

Base URL

Start here

Getting started

Authentication

Guides

Authentication

Rate limits

Pagination

Error handling

Error codes

Common use cases

Resources

Rate limiting

Quick example

FAQ

Next steps

Common use cases

Authentication

Webhooks

Allo MCP

​Base URL

​Start here

​Getting started

​Authentication

​Guides

Authentication

Rate limits

Pagination

Error handling

Error codes

Common use cases

​Resources

​Rate limiting

​Quick example

​FAQ

​Next steps

Common use cases

Authentication

Webhooks

Allo MCP

Base URL

Start here

Getting started

Authentication

Guides

Resources

Rate limiting

Quick example

FAQ

Next steps