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

# Overview

> Integrate Allo's communication capabilities into your applications

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](/en/v2/api-reference/sms/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.

```bash theme={null}
curl -X GET "https://api.withallo.com/v2/api/me" \
  -H "Authorization: Api-Key ak_live_your_key_here"
```

```json theme={null}
{
  "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](/en/v2/api-reference/users/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](https://web.withallo.com/settings/api)

## Authentication

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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Authentication" href="/en/v2/api-reference/guides/authentication">
    API key setup, scopes, and the scope-to-endpoint mapping
  </Card>

  <Card title="Rate limits" href="/en/v2/api-reference/guides/rate-limits">
    Request limits and headers
  </Card>

  <Card title="Pagination" href="/en/v2/api-reference/guides/pagination">
    Page-based results with total counts
  </Card>

  <Card title="Error handling" href="/en/v2/api-reference/guides/error-handling">
    Error format and recovery
  </Card>

  <Card title="Error codes" href="/en/v2/api-reference/guides/error-codes">
    Every error code and what to do about it
  </Card>

  <Card title="Common use cases" href="/en/v2/api-reference/guides/common-use-cases">
    Ready-made request patterns for the usual jobs
  </Card>
</CardGroup>

## Resources

| Resource | Main paths | What it covers |
| - | - | - |
| [Conversations](/en/v2/api-reference/conversations/overview) | `GET /v2/api/conversations`, `POST /v2/api/conversations/items/search` | Unified call and SMS timeline, keyword search across transcripts and message content |
| [SMS](/en/v2/api-reference/sms/overview) | `POST /v1/api/sms` | Send SMS and MMS from your Allo numbers or sender IDs |
| [CRM](/en/v2/api-reference/crm/people-overview) | `/v2/api/crm/people`, `/v2/api/crm/companies`, `/v2/api/crm/deals` | Create, read, update, and search people, companies, and deals |
| [Notes](/en/v2/api-reference/notes/overview) | `/v2/api/conversations/{contact_number}/notes`, `/v2/api/crm/people/{person_id}/notes` | Internal team notes on conversations and person profiles, with @mentions |
| [Threads](/en/v2/api-reference/threads/overview) | `/v2/api/threads` | Team discussion threads on calls, SMS, and conversation notes |
| [Webhooks](/en/v2/api-reference/webhooks/overview) | `/v2/api/webhooks` | Real-time event notifications with HMAC signatures and automatic retries |
| [Phone numbers](/en/v2/api-reference/phone-numbers/overview) | `GET /v2/api/numbers`, `/v2/api/numbers/{number}/call_flow` | Your Allo numbers with capabilities and member access, plus inbound call routing |
| [Users](/en/v2/api-reference/users/overview) | `GET /v2/api/users`, `GET /v2/api/me` | Team roster with roles and assigned numbers, and API key capabilities |
| [Tags](/en/v2/api-reference/tags/overview) | `/v2/api/tags`, `/v2/api/conversations/items/{id}/tags` | Create and list call tags, add and remove them on calls and SMS |
| [Summary templates](/en/v2/api-reference/summary-templates/overview) | `/v2/api/summary_templates` | Templates that shape how AI structures call summaries |
| [Analytics](/en/v2/api-reference/analytics/overview) | `POST /v2/api/analytics/overview`, `POST /v2/api/analytics/outbound` | Team KPIs with period-over-period comparison and per-user breakdown |
| [Dialing queues](/en/v2/api-reference/dialing-queues/overview) | `/v2/api/dialing-queues/current` | Read and fill the Power Dialer queue |
| [AI receptionist](/en/v2/api-reference/agent/overview) | `/v2/api/numbers/{number}/agent` | Configure the receptionist, its prompt, its knowledge, and its on/off status |
| [Partner](/en/v2/api-reference/partner/overview) | `/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](/en/v2/api-reference/guides/rate-limits) for details.

## Quick example

Get your recent conversations:

```bash theme={null}
curl -X GET "https://api.withallo.com/v2/api/conversations?size=5" \
  -H "Authorization: Api-Key ak_live_your_key_here"
```

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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](https://web.withallo.com/settings/api) with Admin or Manager permissions. A key is scoped to a single team and is shown only once. See [Authentication](/en/v2/api-reference/guides/authentication).
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/guides/authentication#scope-to-endpoint-mapping). 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.
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/sms/send-sms) and [Send SMS (France)](/en/v2/api-reference/sms/send-sms-france).
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/conversations/overview).
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/guides/pagination).
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/guides/error-handling) and [Error codes](/en/v2/api-reference/guides/error-codes).
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/guides/rate-limits).
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/webhooks/overview).
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/partner/overview).
  </Accordion>

  <Accordion title="Is there an MCP server?">
    Yes. See [Allo MCP](/en/integrations/mcp) to connect an AI agent to Allo without writing HTTP calls.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Common use cases" href="/en/v2/api-reference/guides/common-use-cases">
    Copy-ready requests for syncing, searching, and reporting
  </Card>

  <Card title="Authentication" href="/en/v2/api-reference/guides/authentication">
    Scopes and the scope-to-endpoint mapping
  </Card>

  <Card title="Webhooks" href="/en/v2/api-reference/webhooks/overview">
    Stop polling and receive events instead
  </Card>

  <Card title="Allo MCP" href="/en/integrations/mcp">
    Connect an AI agent to Allo without writing HTTP calls
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.