# Allo — Help Center: English API Reference

> Documentation and support for Allo, the business phone system that does the work your calls create

## API Reference

### API

- [Overview](https://help.withallo.com/en/v2/api-reference/introduction.md): Integrate Allo's communication capabilities into your applications
- [Authentication](https://help.withallo.com/en/v2/api-reference/guides/authentication.md): Authenticate API requests using API keys
- [Rate limits](https://help.withallo.com/en/v2/api-reference/guides/rate-limits.md): Request limits and response headers
- [Pagination](https://help.withallo.com/en/v2/api-reference/guides/pagination.md): Page-based pagination with total counts on all list endpoints
- [Error handling](https://help.withallo.com/en/v2/api-reference/guides/error-handling.md): Standardized error responses with actionable suggestions
- [Error codes](https://help.withallo.com/en/v2/api-reference/guides/error-codes.md): Complete catalog of all API error codes with recovery instructions
- [Common use cases](https://help.withallo.com/en/v2/api-reference/guides/common-use-cases.md): Examples of how to use the Allo API to answer business questions and automate workflows

### Webhooks

- [Overview](https://help.withallo.com/en/v2/api-reference/webhooks/overview.md): Receive real-time notifications when events occur in your Allo account
- [List webhooks](https://help.withallo.com/en/v2/api-reference/webhooks/get-webhooks.md): Returns all webhook endpoints configured for your account.
- [Get webhook](https://help.withallo.com/en/v2/api-reference/webhooks/get-webhook.md): Returns a single webhook endpoint by ID, including its `signing_secret`.
- [Create webhook](https://help.withallo.com/en/v2/api-reference/webhooks/create-webhook.md): Creates a webhook endpoint subscribed to one or more event topics. The `signing_secret` is returned only in this response — store it to verify delivery signatures.
- [Update webhook](https://help.withallo.com/en/v2/api-reference/webhooks/update-webhook.md): Updates a webhook endpoint. Only the fields you provide are changed. Omitted fields are left untouched.
- [Delete webhook](https://help.withallo.com/en/v2/api-reference/webhooks/delete-webhook.md): Permanently deletes a webhook endpoint and its delivery history.
- [List event types](https://help.withallo.com/en/v2/api-reference/webhooks/list-event-types.md): Returns the catalog of event topics you can subscribe a webhook to.
- [Event catalog](https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog.md): Full reference for all webhook event types and their payloads
- [Verifying webhook signatures](https://help.withallo.com/en/v2/api-reference/webhooks/verifying-signatures.md): Authenticate incoming webhooks using HMAC-SHA256 signatures
- [Delivery and retries](https://help.withallo.com/en/v2/api-reference/webhooks/delivery-and-retries.md): How Allo delivers webhooks, retries failures, and handles recovery
- [Testing webhooks](https://help.withallo.com/en/v2/api-reference/webhooks/testing.md): Test your webhook endpoints before going live
- [Best practices](https://help.withallo.com/en/v2/api-reference/webhooks/best-practices.md): Recommendations for building reliable webhook consumers
- [Troubleshoot](https://help.withallo.com/en/v2/api-reference/webhooks/troubleshooting.md): Diagnose and fix common webhook delivery issues

### Conversations

- [Overview](https://help.withallo.com/en/v2/api-reference/conversations/overview.md): Unified call and SMS history with keyword search and rich filtering
- [List conversations](https://help.withallo.com/en/v2/api-reference/conversations/list-conversations.md): Returns a paginated list of conversations grouped by contact phone number, sorted by most recent activity.
- [Get conversation item](https://help.withallo.com/en/v2/api-reference/conversations/get-item.md): Returns a single call or SMS message by its ID.
- [Search conversation items](https://help.withallo.com/en/v2/api-reference/conversations/search-conversation-items.md): Search and filter items across all conversations. Supports keyword search across transcripts, summaries, and message content.
- [Get many conversation items](https://help.withallo.com/en/v2/api-reference/conversations/batch-get.md): Returns multiple conversation items by their IDs in a single request. Use this to fetch full details (summary, tags, recording, etc.) for items returned by the analytics drilldown or any other list.
- [Execute conversation action](https://help.withallo.com/en/v2/api-reference/conversations/execute-action.md): Execute an action on a conversation.
- [Update call summary](https://help.withallo.com/en/v2/api-reference/conversations/update-summary.md): Replace the markdown content of a call's AI-generated summary.

### CRM

- [Overview](https://help.withallo.com/en/v2/api-reference/crm/overview.md): Manage people, companies, and deals in your Allo CRM

### People

- [Overview](https://help.withallo.com/en/v2/api-reference/crm/people-overview.md): Manage people in your Allo CRM
- [Get person](https://help.withallo.com/en/v2/api-reference/crm/get-person.md): Returns a single person by ID.
- [Create person](https://help.withallo.com/en/v2/api-reference/crm/create-person.md): Creates a new person in your CRM.
- [Update person](https://help.withallo.com/en/v2/api-reference/crm/update-person.md): Updates an existing person. Only provided fields will be updated.
- [Search people](https://help.withallo.com/en/v2/api-reference/crm/search-people.md): Search and filter people in your CRM with advanced filtering, sorting, and pagination.

### Companies

- [Overview](https://help.withallo.com/en/v2/api-reference/crm/companies-overview.md): Manage companies in your Allo CRM
- [Get company](https://help.withallo.com/en/v2/api-reference/crm/get-company.md): Returns a single company by ID.
- [Create company](https://help.withallo.com/en/v2/api-reference/crm/create-company.md): Creates a new company in your CRM.
- [Update company](https://help.withallo.com/en/v2/api-reference/crm/update-company.md): Updates an existing company. Only provided fields will be updated.
- [Search companies](https://help.withallo.com/en/v2/api-reference/crm/search-companies.md): Search and filter companies in your CRM.

### Deals

- [Overview](https://help.withallo.com/en/v2/api-reference/crm/deals-overview.md): Access deals synced from your CRM integrations
- [Search deals](https://help.withallo.com/en/v2/api-reference/crm/search-deals.md): Search and filter deals in your CRM.
- [Get deal](https://help.withallo.com/en/v2/api-reference/crm/get-deal.md): Returns a single deal by ID.

### Notes

- [Overview](https://help.withallo.com/en/v2/api-reference/notes/overview.md): Internal team notes on conversations and person profiles, with @mentions
- [List conversation notes](https://help.withallo.com/en/v2/api-reference/notes/list-conversation-notes.md): Returns the internal team notes on a conversation, paginated.
- [Create conversation note](https://help.withallo.com/en/v2/api-reference/notes/create-conversation-note.md): Adds an internal team note to a conversation. Notes are never visible to the contact.
- [Get conversation note](https://help.withallo.com/en/v2/api-reference/notes/get-conversation-note.md): Returns a single conversation note by ID.
- [Update conversation note](https://help.withallo.com/en/v2/api-reference/notes/update-conversation-note.md): Updates a note's content. Only the note's author can edit it.
- [Delete conversation note](https://help.withallo.com/en/v2/api-reference/notes/delete-conversation-note.md): Deletes a note. Only the note's author can delete it.
- [List person notes](https://help.withallo.com/en/v2/api-reference/notes/list-person-notes.md): Returns the notes on a person's CRM profile, paginated.
- [Create person note](https://help.withallo.com/en/v2/api-reference/notes/create-person-note.md): Adds a note to a person's CRM profile.
- [Update person note](https://help.withallo.com/en/v2/api-reference/notes/update-person-note.md): Updates a person note's content. Only the note's author can edit it.
- [Delete person note](https://help.withallo.com/en/v2/api-reference/notes/delete-person-note.md): Deletes a person note. Only the note's author can delete it.

### Threads

- [Overview](https://help.withallo.com/en/v2/api-reference/threads/overview.md): Team discussion threads attached to calls, SMS, and conversation notes
- [Get thread](https://help.withallo.com/en/v2/api-reference/threads/get-thread.md): Returns a thread with all its comments.
- [Find thread](https://help.withallo.com/en/v2/api-reference/threads/find-thread.md): Finds the discussion thread attached to a conversation item. Returns zero or one thread — each item has at most one thread.
- [Create thread](https://help.withallo.com/en/v2/api-reference/threads/create-thread.md): Starts a discussion thread on a conversation item with a first comment. Each item can have only one thread.
- [Create thread comment](https://help.withallo.com/en/v2/api-reference/threads/create-comment.md): Adds a comment to an existing thread.
- [Update thread comment](https://help.withallo.com/en/v2/api-reference/threads/update-comment.md): Updates a comment's content. Only the comment's author can edit it.
- [Resolve thread](https://help.withallo.com/en/v2/api-reference/threads/resolve-thread.md): Marks a thread as resolved.
- [Unresolve thread](https://help.withallo.com/en/v2/api-reference/threads/unresolve-thread.md): Reopens a resolved thread.

### Phone Numbers

- [Overview](https://help.withallo.com/en/v2/api-reference/phone-numbers/overview.md): Access your Allo phone numbers, sender IDs, and their capabilities
- [List phone numbers](https://help.withallo.com/en/v2/api-reference/phone-numbers/list-numbers.md): Returns all phone numbers and sender IDs on your team.
- [Get call flow](https://help.withallo.com/en/v2/api-reference/phone-numbers/get-call-flow.md): Returns the call flow for a phone number. By default returns the published flow (or an in-memory synthesis of the legacy IVR if none is published); pass `?status=draft` to return the working draft instead.
- [Get call flow draft](https://help.withallo.com/en/v2/api-reference/phone-numbers/get-call-flow-draft.md): Returns the working draft of a phone number's call flow. Unlike `GET /v2/api/numbers/{number}/call_flow?status=draft`, this endpoint does NOT fall back to the published flow when no draft exists — it returns `404 CALL_FLOW_DRAFT_NOT_FOUND`. Use it to read a draft's `lock_version` without risk of acc…
- [Save call flow draft](https://help.withallo.com/en/v2/api-reference/phone-numbers/save-call-flow-draft.md): Creates or updates the working draft of a phone number's call flow. The draft is validated leniently and is not live until published. Optimistic concurrency: pass the `lock_version` returned by a previous read to detect a concurrent edit, and `base_published_version` to detect a publish that happene…
- [Publish call flow](https://help.withallo.com/en/v2/api-reference/phone-numbers/publish-call-flow.md): Publishes the working draft, making it the live call flow for the phone number. This changes live inbound routing immediately. Runs full validation, which is stricter than the lenient validation a draft save runs, so a draft that saved successfully can still fail to publish; the whole publish rolls…

### AI Receptionist

- [Overview](https://help.withallo.com/en/v2/api-reference/agent/overview.md): Read and write the AI receptionist of an Allo line: prompt, voice, business hours, transfer rules, calendars and knowledge
- [Get configuration](https://help.withallo.com/en/v2/api-reference/agent/get-agent.md): Returns the whole configuration of a line's AI receptionist in one call: business details, voice and language, prompt, capabilities, business hours, transfer rules, connected calendars and knowledge sources. Call this before a write, because `PATCH` replaces whole collections.
- [Update configuration](https://help.withallo.com/en/v2/api-reference/agent/update-agent.md): Updates any part of the configuration except the prompt and the on/off status. Single values are merged, collections are replaced. This does not put the receptionist on the line: that is `PUT /v2/api/numbers/{number}/agent/status`.
- [Set prompt](https://help.withallo.com/en/v2/api-reference/agent/set-agent-prompt.md): Replaces the receptionist's prompt: what it is trying to achieve, who it is, how it handles the call. A prompt is only valid whole, so read the current sections with `GET /v2/api/numbers/{number}/agent` and send them all back, including the ones you are not changing. Facts about the business belong…
- [Turn on or off](https://help.withallo.com/en/v2/api-reference/agent/set-agent-status.md): Puts the receptionist on the line (`ACTIVE`) or takes it off (`FORWARDING`, which sends calls to your business phone instead). This reprograms how a live line routes real calls, so confirm with a person before calling it.
- [Add website knowledge](https://help.withallo.com/en/v2/api-reference/agent/add-website-knowledge.md): Adds a page to the receptionist's knowledge. Allo scrapes and summarizes it during the request, so the call takes a few seconds. Up to 5 websites per receptionist.
- [Enable or disable a website](https://help.withallo.com/en/v2/api-reference/agent/update-website-knowledge.md): Turns a website entry on or off without losing its scraped content.
- [Delete website knowledge](https://help.withallo.com/en/v2/api-reference/agent/delete-website-knowledge.md): Removes a website entry from the receptionist's knowledge.
- [Delete file knowledge](https://help.withallo.com/en/v2/api-reference/agent/delete-file-knowledge.md): Removes an uploaded document from the receptionist's knowledge. Documents are uploaded in the Allo app; this API lists and deletes them.
- [List calendars](https://help.withallo.com/en/v2/api-reference/agent/list-calendars.md): Lists the calendars connected to your workspace that you can see, whether or not a receptionist books on them. An admin sees every calendar in the workspace, a team member only the ones they connected. Connecting a calendar is an OAuth flow done in the Allo app.
- [Get a calendar](https://help.withallo.com/en/v2/api-reference/agent/get-calendar.md): Returns one connected calendar with the event types its provider currently offers, read live from the provider. This is the catalog you pick from when filling `scheduling.calendars`.
- [List voices](https://help.withallo.com/en/v2/api-reference/agent/list-voices.md): Lists the voices an AI receptionist can speak with, the same catalog the Allo app offers. Each `id` is what `voice_id` takes, and a voice speaks the language it is listed under.

### Tags

- [Overview](https://help.withallo.com/en/v2/api-reference/tags/overview.md): Discover available call tags for filtering conversations
- [List tags](https://help.withallo.com/en/v2/api-reference/tags/list-tags.md): Returns all tags configured on the team.
- [Create tag](https://help.withallo.com/en/v2/api-reference/tags/create-tag.md): Creates a new tag on the team. The tag key is auto-generated by slugifying the name.
- [Delete tag](https://help.withallo.com/en/v2/api-reference/tags/delete-tag.md): Soft-deletes a tag by its key. Tags synced from a CRM integration cannot be deleted via the API.
- [Add tags](https://help.withallo.com/en/v2/api-reference/tags/add-tags.md): Add one or more tags to a conversation item.
- [Remove tag](https://help.withallo.com/en/v2/api-reference/tags/remove-tag.md): Remove a tag from a conversation item.

### Summary Templates

- [Overview](https://help.withallo.com/en/v2/api-reference/summary-templates/overview.md): Manage the call summary templates that shape AI-generated call summaries
- [List summary templates](https://help.withallo.com/en/v2/api-reference/summary-templates/list-summary-templates.md): Returns the team's call summary templates.
- [Get summary template](https://help.withallo.com/en/v2/api-reference/summary-templates/get-summary-template.md): Returns a single call summary template by ID.
- [Create summary template](https://help.withallo.com/en/v2/api-reference/summary-templates/create-summary-template.md): Creates a call summary template for the team.
- [Update summary template](https://help.withallo.com/en/v2/api-reference/summary-templates/update-summary-template.md): Replaces a summary template's name, call context, icon, and sections.
- [Delete summary template](https://help.withallo.com/en/v2/api-reference/summary-templates/delete-summary-template.md): Soft-deletes (deactivates) a summary template.
- [Set a number's default template](https://help.withallo.com/en/v2/api-reference/summary-templates/set-number-default-summary-template.md): Sets or clears the default summary template used for a phone number's call summaries. Pass `summary_template_id` to set it, or null/omit to clear it.

### Users

- [Overview](https://help.withallo.com/en/v2/api-reference/users/overview.md): Access your team roster with roles and status
- [Me](https://help.withallo.com/en/v2/api-reference/users/me.md): Returns information about the authenticated API key: its scopes, available endpoints, team, and rate limits. No specific scope is required — any valid API key can call this endpoint.
- [List users](https://help.withallo.com/en/v2/api-reference/users/list-users.md): Returns all team members.
- [Get user](https://help.withallo.com/en/v2/api-reference/users/get-user.md): Returns a single team member by their ID.

### SMS

- [Overview](https://help.withallo.com/en/v2/api-reference/sms/overview.md): Send SMS and MMS messages programmatically
- [Send SMS](https://help.withallo.com/en/v2/api-reference/sms/send-sms.md): Send an SMS message to a US phone number using one of your Allo phone numbers. The recipient must be in the same country as your Allo number.
- [Send SMS (France)](https://help.withallo.com/en/v2/api-reference/sms/send-sms-france.md): Send an SMS message to a French phone number using a verified Sender ID. The Sender ID must be verified by the Allo team before use. Contact support to register your Sender ID.

### Analytics

- [Overview](https://help.withallo.com/en/v2/api-reference/analytics/overview.md): Pre-computed call metrics and team performance analytics
- [Team metrics](https://help.withallo.com/en/v2/api-reference/analytics/team-summary.md): Returns team-wide KPIs with period-over-period comparison and a per-user breakdown. Covers all calls (inbound + outbound).
- [Outbound metrics](https://help.withallo.com/en/v2/api-reference/analytics/outbound.md): Returns outbound call metrics: dial funnel (dials → connected → conversations → conversions), time series, heatmap, leaderboard, and time spent metrics.

### Power Dialer

- [Overview](https://help.withallo.com/en/v2/api-reference/dialing-queues/overview.md): Manage Power Dialer queues programmatically
- [List current queue numbers](https://help.withallo.com/en/v2/api-reference/dialing-queues/get-current.md): Returns the numbers in the Power Dialer queue currently assigned to the authenticated user, paginated and ordered by `position` ascending. `data` is the list of numbers (use `page`/`size` and read `pagination` to page through them); the `queue` key carries the queue's metadata (id, name, settings) w…
- [Upsert current queue](https://help.withallo.com/en/v2/api-reference/dialing-queues/update-current.md): Creates or updates the config of the queue assigned to the authenticated user. Send `user_id` or `email` to act on a teammate's queue instead — `user_id` wins when both are provided.
- [Append numbers](https://help.withallo.com/en/v2/api-reference/dialing-queues/append-numbers.md): Appends phone numbers to the Power Dialer queue assigned to the authenticated user. Creates the queue implicitly if none exists. Send `user_id` or `email` to append to a teammate's queue — if that teammate has no current queue, one is created with the API key owner as `creator_id` and the teammate a…
- [Clear queue numbers](https://help.withallo.com/en/v2/api-reference/dialing-queues/clear-numbers.md): Removes numbers from the queue assigned to the authenticated user. Exactly one filter must be supplied via query string: `number` (E.164), `position` (0-based index), `number` + `position` together (delete a specific occurrence of a duplicate), or `unassigned=true` (remove every entry that has not b…
- [Reset current queue](https://help.withallo.com/en/v2/api-reference/dialing-queues/reset-current.md): Creates a fresh, empty queue assigned to the authenticated user. Any older queue with the same assignee stops being returned by `GET /current` (the newest queue wins). Send `user_id` or `email` to create the queue for a teammate instead — the API key owner is recorded as `creator_id`, the teammate a…

### Partner

- [Overview](https://help.withallo.com/en/v2/api-reference/partner/overview.md): Provision and manage Allo accounts for your customers as a reseller.
- [Create account](https://help.withallo.com/en/v2/api-reference/partner/create-account.md): Creates an Allo account for one of your customers, provisions a phone number, and returns a scoped API key for the account. Requires the `PARTNER` scope. The account is billed as one seat on your subscription.
- [Get account](https://help.withallo.com/en/v2/api-reference/partner/get-account.md): Returns the status and activation state of an account you provisioned. Requires the `PARTNER` scope.
- [Deactivate account](https://help.withallo.com/en/v2/api-reference/partner/delete-account.md): Deactivates an account you provisioned and releases its seat. The account stays active until the end of the current paid period, then expires. Requires the `PARTNER` scope.