A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Aircall API is how an app or AI agent works with an Aircall phone system: listing and reading calls, tagging and commenting on them, managing the contacts shared across the workspace, and registering for live call events. Access is granted through an account-level credential, either an API ID and token for one company or an authorized partner connection, and because Aircall has no per-area permissions that one credential reaches the entire workspace. Aircall can also push events to a webhook URL the moment a call is created, answered, or ended.
How an app or AI agent connects to Aircall determines what it can reach. There are two routes, one for an Aircall customer building on their own account and one for a partner building for many customers, each carrying a credential that reaches the whole company workspace.
The Public API answers at https://api.aircall.io. It is the single way to read and write data, and it carries a v2 line for the Users area alongside v1 for everything else.
Webhooks deliver the chosen events to a receiver URL the moment they happen, such as a call being created, answered, or ended, so an app does not have to poll for changes.
An Aircall customer building on their own account uses an API ID and an API token, created in Company Settings, sent together as HTTP Basic Auth. The pair reaches every endpoint and all company data, with no narrower option.
A partner building for many Aircall customers uses OAuth 2.0. An admin authorizes the connection and Aircall returns an access token. There is one scope, public_api, so the token reaches every endpoint rather than a chosen subset.
The Aircall API is split into areas an agent can act on, such as calls, contacts, users, teams, numbers, tags, and webhooks. Each area has its own methods, and because the credential is account-level, the same key reaches every one of them.
List and search calls, read a single call, transfer it, add a comment or a tag, and archive it.
List, search, read, create, update, and delete the contacts shared across the workspace.
List users, read a single user, create a user, and update a user's details.
List teams, read a single team, create a team, and add or remove a user from it.
List the phone numbers in the workspace, read a single number, and update its settings.
List tags, read a single tag, create a tag, update one, and delete one.
List the registered webhooks, read one, create a webhook, update it, and delete it.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CallsList and search calls, read a single call, transfer it, add a comment or a tag, and archive it.8 | ||||||
| GET | /v1/calls | List the calls in the workspace. | read | — | Current | |
Aircall has no per-endpoint scopes. The single OAuth scope is public_api, and an API key reaches every endpoint, so any valid credential can list calls. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/calls/{id} | Retrieve a single call by ID. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can read a call. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/calls/search | Search calls by direction, number, date range, tags, and other filters. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can search calls. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/calls/{id}/transfers | Transfer a live call to a user or a number. | write | — | Current | |
Aircall has no per-endpoint scopes, so the same credential that reads a call can also transfer it. Only a call that is currently ongoing can be transferred. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.transferredRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/calls/{id}/comments | Add a comment to a call. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can comment on a call. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.commentedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/calls/{id}/tags | Apply one or more tags to a call. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can tag a call. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.taggedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/calls/{id}/archive | Archive a call so it no longer appears in the active list. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can archive a call. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.archivedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/calls/{id}/recording | Permanently delete a call's recording. | write | — | Current | |
Aircall has no per-endpoint scopes, so any credential that can read a call can also erase its recording. The deletion is permanent. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ContactsList, search, read, create, update, and delete the contacts shared across the workspace.5 | ||||||
| GET | /v1/contacts | List the contacts shared across the workspace. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can list contacts, which include people's names, phone numbers, and email addresses. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/contacts/{id} | Retrieve a single contact by ID. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can read a contact. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/contacts | Create a contact with its phone numbers and emails. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can create a contact, which is then visible to the whole workspace. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/contacts/{id} | Update a contact's details. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can update a contact. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/contacts/{id} | Delete a contact. | write | — | Current | |
Aircall has no per-endpoint scopes, so any credential that can read a contact can also delete it for the whole workspace. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList users, read a single user, create a user, and update a user's details.4 | ||||||
| GET | /v1/users | List the users in the workspace. | read | — | Current | |
Aircall has no per-endpoint scopes. A v2 version of the Users area exists, released 20 January 2026, with an updated payload. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/users/{id} | Retrieve a single user by ID. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can read a user. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/users | Create a user in the workspace. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can create a teammate account. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook event user.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/users/{id} | Update a user's details. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can update a user. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsList teams, read a single team, create a team, and add or remove a user from it.3 | ||||||
| GET | /v1/teams | List the teams in the workspace. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can list teams. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/teams/{id} | Retrieve a single team by ID. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can read a team. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/teams/{team_id}/users/{user_id} | Add a user to a team. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can change team membership, which affects call routing. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
NumbersList the phone numbers in the workspace, read a single number, and update its settings.3 | ||||||
| GET | /v1/numbers | List the phone numbers in the workspace. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can list numbers. Acts onnumber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/numbers/{id} | Retrieve a single phone number by ID. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can read a number. Acts onnumber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/numbers/{id} | Update a phone number's settings. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can change how a live number behaves. Acts onnumber Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList tags, read a single tag, create a tag, update one, and delete one.3 | ||||||
| GET | /v1/tags | List the tags in the workspace. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can list tags. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/tags | Create a tag. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can create a tag in the shared list. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/tags/{id} | Delete a tag. | write | — | Current | |
Aircall has no per-endpoint scopes. Deleting a tag removes it from the shared list for everyone. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList the registered webhooks, read one, create a webhook, update it, and delete it.3 | ||||||
| GET | /v1/webhooks | List the registered webhooks. | read | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can list webhooks. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/webhooks | Create a webhook subscribed to the chosen events. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can register a webhook and start receiving live event data. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/webhooks/{id} | Delete a webhook. | write | — | Current | |
Aircall has no per-endpoint scopes. Any valid credential can delete a webhook and stop its event delivery. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Aircall can notify an app or AI agent the moment something happens on the phone system, instead of the app repeatedly asking. Aircall posts the event payload to a webhook URL that has been registered for the chosen events, such as a call starting or ending.
| Event | What it signals | Triggered by |
|---|---|---|
call.created | Fires when a new call is created, at the start of an inbound or outbound call. | /v1/calls |
call.answered | Fires when a call is answered by an agent. | In-app only |
call.ended | Fires when a call ends, carrying the final details of the call. | In-app only |
call.transferred | Fires when a call is transferred to another user or number. | /v1/calls/{id}/transfers |
call.commented | Fires when a comment is added to a call. | /v1/calls/{id}/comments |
call.tagged | Fires when a tag is applied to a call. | /v1/calls/{id}/tags |
call.archived | Fires when a call is archived. | /v1/calls/{id}/archive |
contact.created | Fires when a contact is created. | /v1/contacts |
contact.updated | Fires when a contact is updated. | /v1/contacts/{id} |
contact.deleted | Fires when a contact is deleted. | /v1/contacts/{id} |
user.created | Fires when a user is created in the workspace. | /v1/users |
user.connected | Fires when a user connects and becomes available to take calls. | In-app only |
Aircall limits how fast an app or AI agent can call, through a per-minute request quota that applies to the whole company rather than to a single key. Going over returns an error, and response headers report how much of the quota is left.
Aircall sets a single rate limit of 120 requests per minute, applied per company rather than per key, so every integration on the same account shares the same budget. Three response headers report the current state: X-AircallApi-Limit is the ceiling, X-AircallApi-Remaining is how many requests are left in the window, and X-AircallApi-Reset is the UNIX timestamp when the counter resets. A higher limit is available by contacting Aircall support.
List endpoints use offset pagination through the page parameter and the per_page parameter, which defaults to 20 and tops out at 50. The Calls and Contacts lists are capped at 10,000 items reachable through pagination, so a longer history has to be narrowed with filters or the search endpoint.
Requests and responses are JSON, and write requests must send a Content-Type of application/json. Aircall does not document a single maximum payload size across the API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The server cannot process the request because of a client error, such as a malformed body or a missing required field. | Read the error and troubleshoot fields in the response body, correct the request, and resend. |
| 403 | Forbidden | The authentication credentials are invalid. Aircall uses 403 rather than 401 for a bad API ID and token or an expired access token. | Check the API ID and token or the OAuth access token, then send valid credentials. |
| 404 | Not Found | The target resource does not exist, such as a call or contact ID that is not in the workspace. | Confirm the ID and the path are correct before retrying. |
| 405 | Method Not Allowed | The HTTP method is not supported for that path, such as a POST to a read-only endpoint. | Use the method the endpoint documents, then resend. |
| 422 | Unprocessable Entity | The request was well-formed but failed validation, such as a value that is not allowed for a field. | Read the troubleshoot field, fix the named field, and resend. |
| 500 | Internal Server Error | An unexpected condition on Aircall's side prevented the request from completing. | Retry after a short wait, and contact Aircall support if it persists. |
Aircall versions its API in the path, with v1 as the stable line and v2 introduced for the Users area. It does not use dated versions, so changes ship through the developer changelog rather than a new version string.
Aircall versions its Public API in the URL path. v1 is the stable line for every area, and the platform ships dated changes through its developer changelog rather than minting a new version string. A v2 line was added for the Users area on 20 January 2026 with an updated payload and new webhook events.
Through 2025 Aircall expanded the Conversation Intelligence and AI Voice Agent areas of the v1 API, adding endpoints and webhook events for call analysis, all on the same v1 line.
An integration stays on v1 and moves an area to v2 when Aircall publishes a v2 for it, as it has for Users.
Aircall API changelog ↗Bollard AI sits between a team's AI agents and Aircall. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.