---
canonical_url: "https://docs.composio.dev/toolkits/aircall"
markdown_url: "https://docs.composio.dev/toolkits/aircall.md"
product: "platform"
version: null
last_updated: null
---

# Aircall

Aircall is a cloud-based phone and call-center platform. This toolkit manages users, teams, phone numbers, calls, contacts, and tags on a single Aircall company account via the Public API.

- **Category:** communication
- **Auth:** OAUTH2, BASIC
- **Composio-managed OAuth available?** No
- **Tools:** 48
- **Triggers:** 0
- **Slug:** `AIRCALL`
- **Version:** 00000000_00

## Tools

### Add Contact Method

**Slug:** `AIRCALL_ADD_CONTACT_METHOD`

Add a phone number or an email address to an existing Aircall contact. Set method_type='phone' to add a phone number or method_type='email' to add an email address. The value and any supplied label must be nonblank, but this tool does not impose E.164 or strict email formatting. If the label is omitted, Aircall defaults it to 'Main'. Use when a contact already exists and needs another way to be reached; not for creating the contact itself (AIRCALL_CREATE_CONTACT), and not for changing a method that is already on the contact (AIRCALL_UPDATE_CONTACT_METHOD). Returns the created method as 'contact_method' ({id, method_type, label, value}) — keep its id to update or delete it later.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `label` | string | No | Optional label for the method. For a phone: 'Work', 'Mobile', 'Home'. For an email: 'Work', 'Personal'. If omitted, Aircall defaults the label to 'Main'. |
| `value` | string | Yes | Nonblank phone number or email value. Aircall accepts and normalizes multiple phone formats and stores any email format. |
| `contact_id` | integer | Yes | Numeric id of the contact to add the method to. |
| `method_type` | string ("email" | "phone") | Yes | Which kind of contact method to add: 'phone' for a phone number, 'email' for an email address. This selects the Aircall endpoint. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Add User to Team

**Slug:** `AIRCALL_ADD_USER_TO_TEAM`

Add a User to a Team (membership change). Returns the updated team.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | integer | Yes | Team numeric id. |
| `user_id` | integer | Yes | Numeric id of the user to add to the team. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Add Comment to Call

**Slug:** `AIRCALL_COMMENT_CALL`

Add a comment/note to a Call (max 5 comments per call; emojis are stripped). Returns success on HTTP 201.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the call to comment on. |
| `content` | string | Yes | Comment text to attach to the call (emojis are stripped by Aircall). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Contact

**Slug:** `AIRCALL_CREATE_CONTACT`

Create a shared Aircall contact. Use when adding someone to the shared address book; not for editing an existing one (AIRCALL_UPDATE_CONTACT), and not for attaching a phone number or email address to a contact that already exists — that is AIRCALL_ADD_CONTACT_METHOD with method_type='phone' or method_type='email'. At least one phone_numbers[] entry is required (1-20); emails[] is optional (max 20). Aircall rejects a name-only contact AND an email-only contact with HTTP 400.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emails` | array | No | Optional email addresses to attach, each {label, value}; at most 20. Emails alone are not sufficient — phone_numbers is still required. |
| `last_name` | string | No | Contact last name. |
| `first_name` | string | No | Contact first name. |
| `information` | string | No | Free-text note about the contact. |
| `company_name` | string | No | Company name. |
| `phone_numbers` | array | Yes | Required. Phone numbers to attach, each with nonblank {label, value}; 1-20 entries. Aircall rejects a create with no phone_numbers (HTTP 400) even when emails are supplied. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Tag

**Slug:** `AIRCALL_CREATE_TAG`

Create a Tag. name must be unique per company; color is a hex string (e.g. #00B388). Aircall does not accept a mutable description field.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Tag name (unique per company). |
| `color` | string | Yes | Tag color as a hex string, e.g. '#00B388'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Team

**Slug:** `AIRCALL_CREATE_TEAM`

Create a new Team. Requires a name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Unique nonblank team name, fewer than 64 characters. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create User

**Slug:** `AIRCALL_CREATE_USER`

Create an Aircall user and send them a real invitation email, consuming a licensed seat. Use when adding a new teammate to the account; not for changing someone who already exists (AIRCALL_UPDATE_USER). Requires email, first_name and last_name. role_ids takes role NAME strings, one of owner, supervisor, admin or agent, not numeric ids.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | Yes | Email address for the new user; the invite email is sent here. |
| `role_ids` | array | No | Optional roles to assign to the new user. Aircall documents this as an array of role NAME strings, not numeric ids: owner, supervisor, admin, or agent. Omit to let Aircall apply its documented default of agent. |
| `last_name` | string | Yes | The new user's nonblank last name. |
| `first_name` | string | Yes | The new user's nonblank first name. |
| `wrap_up_time` | integer | No | Optional number of seconds of wrap-up time after a call. Aircall documents a default of 0 seconds, and that this applies only to a user whose role_ids include agent. |
| `inviter_user_id` | integer | No | Optional id of the existing user recorded as having invited this one. On V2, this value is ignored when the inviter is not an admin. |
| `availability_status` | string ("available" | "custom" | "unavailable") | No | Optional starting availability for the new user: available, custom, or unavailable. Omit to let Aircall apply its documented default of available. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Webhook

**Slug:** `AIRCALL_CREATE_WEBHOOK`

Create an Aircall webhook targeting a public HTTPS URL. Select one or more events, or explicitly set subscribe_to_all_events=true; omission never silently subscribes the destination to every company event. Aircall permits at most 100 webhooks per company.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | Public HTTPS endpoint that will receive Aircall events. |
| `events` | array | No | Events from Aircall's documented webhook event set. Required unless subscribe_to_all_events=true. |
| `custom_name` | string | No | Optional webhook display name. |
| `subscribe_to_all_events` | boolean | No | Set true only when intentionally subscribing to every Aircall event. Aircall represents this on the wire as an empty events array. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Call Media

**Slug:** `AIRCALL_DELETE_CALL_MEDIA`

Request permanent deletion of a Call's audio recording or voicemail, for compliance or data governance. Set media_type='recording' or media_type='voicemail'; a call may have one, both, or neither. The call record is retained, but deleting a recording on an AI Assist/Pro account also permanently removes its transcription and AI insights. Use when an audio artefact and its derived AI data must be purged; not for reading call details (AIRCALL_GET_CALL). Once processed, deletion is irreversible. A successful response means Aircall accepted the request, not that deletion is complete: recordings take 10-15 minutes and voicemails up to 1 minute, and existing download URLs may work during propagation. A recording can arrive up to 24 hours after the call, so retry later when it is not present yet.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `call_id` | integer | Yes | Numeric id of the call whose media to delete. |
| `media_type` | string ("recording" | "voicemail") | Yes | Which media artefact to remove: 'recording' for the call's audio recording, or 'voicemail' for the voicemail message left on it. A call may have one, both, or neither. Recording deletion also permanently removes transcription and AI insights on AI Assist/Pro accounts. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Contact

**Slug:** `AIRCALL_DELETE_CONTACT`

Permanently delete a shared Contact and all of its phone numbers and email addresses. Irreversible — there is no undo. Use to remove a contact entirely; not for removing a single phone number or email from a contact (AIRCALL_DELETE_CONTACT_METHOD). Returns 204 (empty body).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Contact numeric id to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Contact Method

**Slug:** `AIRCALL_DELETE_CONTACT_METHOD`

Permanently remove one phone number or email address from an Aircall contact. Set method_type='phone' or method_type='email' to say which kind method_id refers to. Use when a contact should no longer be reachable that way; not for deleting the whole contact (AIRCALL_DELETE_CONTACT), and not for correcting a method's value or label (AIRCALL_UPDATE_CONTACT_METHOD). IRREVERSIBLE: the method is gone and re-adding it mints a new id. Returns {success: true} on HTTP 204.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `method_id` | integer | Yes | Id of the phone or email entry to remove. Get it from the contact's phone_numbers[] / emails[] via AIRCALL_GET_CONTACT, or from the `id` returned by AIRCALL_ADD_CONTACT_METHOD. |
| `contact_id` | integer | Yes | Numeric id of the contact that owns the method. |
| `method_type` | string ("email" | "phone") | Yes | Which kind of contact method `method_id` refers to: 'phone' for a phone number, 'email' for an email address. This selects the Aircall endpoint, so it must match the id — a phone id with method_type='email' will 404. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Tag

**Slug:** `AIRCALL_DELETE_TAG`

Delete a Tag by id. Returns 204 (empty body).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Tag numeric id to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Team

**Slug:** `AIRCALL_DELETE_TEAM`

Delete a Team by id. Returns 204 (empty body). Does not delete the users in it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Team numeric id to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete User

**Slug:** `AIRCALL_DELETE_USER`

Permanently delete a User. The deletion is processed asynchronously and returns HTTP 204 (empty body); it fires a user.deleted webhook. Returns a {success, id} confirmation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the user to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Webhook

**Slug:** `AIRCALL_DELETE_WEBHOOK`

Permanently delete an Aircall webhook. Delivery stops and its configuration is lost; use UPDATE_WEBHOOK with active=false instead when a reversible pause is preferable.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `webhook_id` | string | Yes | UUID of the webhook to delete, or its legacy numeric Aircall id. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Call

**Slug:** `AIRCALL_GET_CALL`

Retrieve a single Call by id, with optional contact / short-url / timeline enrichment via the fetch_* flags.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Call numeric id. |
| `fetch_contact` | boolean | No | Include the matched contact object. |
| `fetch_aiva_conv` | boolean | No | Include AI Voice Agent segments in call.ai_voice_agents. |
| `fetch_short_urls` | boolean | No | Include shortened asset URLs. |
| `fetch_call_timeline` | boolean | No | Include the per-call event timeline. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Company

**Slug:** `AIRCALL_GET_COMPANY`

Retrieve information about the connected Aircall company (name, users_count, numbers_count). This is the best true auth-verify endpoint: a 200 confirms the Basic Auth credentials are valid.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contact

**Slug:** `AIRCALL_GET_CONTACT`

Retrieve a single shared Contact by id, with its nested phone_numbers[] and emails[]. NOTE: contact created_at/updated_at are UNIX-epoch INTEGERS.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Contact numeric id. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Number

**Slug:** `AIRCALL_GET_NUMBER`

Retrieve a single Aircall phone Number by its numeric id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the Aircall number to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Number Registration Status

**Slug:** `AIRCALL_GET_NUMBER_REGISTRATION_STATUS`

Check whether an Aircall phone number is registered for compliance (10DLC or other regulatory registration) by reading the `status` field. Use for regulatory registration state only; not for the number's name, availability or Music & Messages (AIRCALL_GET_NUMBER).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the Aircall number whose registration status to fetch. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Tag

**Slug:** `AIRCALL_GET_TAG`

Retrieve a single Tag by id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Tag numeric id. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Team

**Slug:** `AIRCALL_GET_TEAM`

Retrieve a single Team by id, including its member users.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Team numeric id. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get User

**Slug:** `AIRCALL_GET_USER`

Retrieve one Aircall user by numeric id or by email address. Both work in the id field. Use when you already have the id or email; not for browsing the roster (AIRCALL_LIST_USERS). The user's assigned phone numbers are not included. Get them from AIRCALL_LIST_USER_NUMBERS.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | User numeric id OR email address — both are accepted in the path. The numeric id may be passed as an int (as returned by AIRCALL_LIST_USERS) or a string. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get User Availability

**Slug:** `AIRCALL_GET_USER_AVAILABILITY`

Check the current availability of one User. Returns availability ∈ available | offline | do_not_disturb | in_call | after_call_work.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | User numeric id whose availability to check. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Webhook

**Slug:** `AIRCALL_GET_WEBHOOK`

Retrieve one Aircall webhook by its UUID or legacy numeric id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `webhook_id` | string | Yes | Webhook UUID returned by LIST_WEBHOOKS or CREATE_WEBHOOK, or the legacy numeric webhook id that Aircall still accepts. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Calls

**Slug:** `AIRCALL_LIST_CALLS`

List the account's calls in chronological order, covering about 6 months of history and at most 10,000 items via pagination. Window past that with the `from` UNIX timestamp. Use for plain date-ordered browsing of call activity; not when filtering by direction, user, phone number or tag, which is what AIRCALL_SEARCH_CALLS is for. An account with no calls returns an empty list with HTTP 200, never 404.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | integer | No | Only calls created at/before this UNIX timestamp (seconds). |
| `from` | integer | No | Only calls created at/after this UNIX timestamp (seconds). Use to page past the 10,000-item cap. |
| `page` | integer | No | 1-based page number. |
| `order` | string ("asc" | "desc") | No | Sort by created_at: 'asc' (default) or 'desc'. |
| `cursor` | string | No | Continuation cursor from a prior response's next_cursor. Omit for the first page. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |
| `fetch_contact` | boolean | No | Include the matched contact object on each call. |
| `fetch_aiva_conv` | boolean | No | Include AI Voice Agent segments in each call. |
| `fetch_short_urls` | boolean | No | Include shortened asset URLs. |
| `fetch_call_timeline` | boolean | No | Include the per-call event timeline. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Contacts

**Slug:** `AIRCALL_LIST_CONTACTS`

List all shared Contacts (hard-capped at 10,000 items via pagination — window past with the `from` timestamp). Each contact embeds nested phone_numbers[] and emails[] ({id, label, value}). NOTE: contact created_at/updated_at are UNIX-epoch INTEGERS (unlike other resources). Paginated via page/per_page; pass next_cursor back as cursor while has_more is true to retrieve subsequent pages.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | integer | No | Only contacts created at/before this UNIX timestamp (seconds). |
| `from` | integer | No | Only contacts created at/after this UNIX timestamp (seconds). |
| `page` | integer | No | 1-based page number to fetch (default 1). |
| `order` | string ("asc" | "desc") | No | Sort order: 'asc' (default) or 'desc'. |
| `cursor` | string | No | Continuation cursor from a prior response's next_cursor. Omit for the first page. |
| `order_by` | string ("created_at" | "updated_at") | No | Field to sort by: 'created_at' (default) or 'updated_at'. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Numbers

**Slug:** `AIRCALL_LIST_NUMBERS`

List all Aircall phone Numbers in the account. Each number includes id, digits, name, country, availability and a `messages` object of audio URLs. Paginated via page/per_page; to page, pass the response's next_cursor back as cursor (has_more signals whether more pages remain).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | integer | No | Only numbers created at/before this UNIX timestamp (seconds). |
| `from` | integer | No | Only numbers created at/after this UNIX timestamp (seconds). |
| `page` | integer | No | 1-based page number to fetch (default 1). |
| `order` | string ("asc" | "desc") | No | Sort by created_at: 'asc' or 'desc'. |
| `cursor` | string | No | Continuation cursor from a prior response's next_cursor. Omit for the first page. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Tags

**Slug:** `AIRCALL_LIST_TAGS`

List all Tags in the account. Each tag = {id, name, color (hex), description}. Paginated via page/per_page; to page, pass the response's next_cursor back as cursor (has_more signals whether more pages remain).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | 1-based page number to fetch (default 1). |
| `cursor` | string | No | Continuation cursor from a prior response's next_cursor. Omit for the first page. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Teams

**Slug:** `AIRCALL_LIST_TEAMS`

List all Teams in the account. Each team embeds its member users (nested user objects). Paginated via page/per_page; to page, pass the response's next_cursor back as cursor (has_more signals whether more pages remain).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | 1-based page number to fetch (default 1). |
| `order` | string ("asc" | "desc") | No | Sort by created_at: 'asc' or 'desc'. |
| `cursor` | string | No | Continuation cursor from a prior response's next_cursor. Omit for the first page. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List User Numbers (V2)

**Slug:** `AIRCALL_LIST_USER_NUMBERS`

List all Aircall Numbers assigned to a specific User (V2, paginated). Returns one page plus a next_cursor to fetch the next. The number ids feed AIRCALL_START_OUTBOUND_CALL. Targets the /v2 API.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the user whose numbers to list — pass the int as returned by AIRCALL_LIST_USERS (a numeric string is also accepted). |
| `page` | integer | No | 1-based page number for the first request. |
| `order` | string ("asc" | "desc") | No | Sort by created_at: 'asc' or 'desc'. |
| `cursor` | string | No | Opaque pagination cursor from a prior response's next_cursor. Omit for the first page. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Users

**Slug:** `AIRCALL_LIST_USERS`

List the users in the Aircall account, one page at a time with a next_cursor to continue. Use when you need user ids, names, emails, availability or default_number_id; not for a single known user (AIRCALL_GET_USER), and not for the phone numbers a user can call from (AIRCALL_LIST_USER_NUMBERS).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | integer | No | Only return users created at/before this UNIX timestamp (seconds). The legacy name `created_before` is still accepted. |
| `from` | integer | No | Only return users created at/after this UNIX timestamp (seconds). Sent as the `from` query param. The legacy name `created_after` is still accepted. |
| `page` | integer | No | 1-based page number for the first request. |
| `order` | string ("asc" | "desc") | No | Sort by created_at: 'asc' (default) or 'desc'. |
| `cursor` | string | No | Continuation cursor from a previous response's next_cursor. Omit for the first page; pass the returned value back verbatim to fetch the next page. |
| `per_page` | integer | No | Number of users per page (1-50; Mercury default 10). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Users Availability

**Slug:** `AIRCALL_LIST_USERS_AVAILABILITY`

List the detailed availability of all Users (whether each user is available/offline/on a call, etc.). Paginated via page/per_page; to page, pass the response's next_cursor back as cursor (has_more signals whether more pages remain).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | integer | No | Only include users created at/before this UNIX timestamp (seconds). |
| `from` | integer | No | Only include users created at/after this UNIX timestamp (seconds). |
| `page` | integer | No | 1-based page number to fetch (default 1). |
| `order` | string ("asc" | "desc") | No | Sort by created_at: 'asc' or 'desc'. |
| `cursor` | string | No | Continuation cursor from a prior response's next_cursor. Omit for the first page. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Webhooks

**Slug:** `AIRCALL_LIST_WEBHOOKS`

List webhook subscriptions accessible to the connected Aircall company. This returns one page only. If next_cursor is non-null, call LIST_WEBHOOKS again with that cursor to retrieve the next page; continue until next_cursor is null. Use this to discover a webhook UUID before retrieving, updating, or deleting it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | integer | No | 1-based page number. |
| `order` | string ("asc" | "desc") | No | Order by created_at: 'asc' or 'desc'. |
| `cursor` | string | No | Continuation cursor from next_cursor. Omit for the first page. |
| `per_page` | integer | No | Items per page (1-50, default 10). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Publish Call Insight Card

**Slug:** `AIRCALL_PUBLISH_CALL_INSIGHT_CARD`

Display contextual title, short text, links, or Aircall user details to the agent handling an ongoing call. Cards are ephemeral: only ongoing calls show them and Aircall does not store them after the call. The JSON payload must be strictly less than 10KB.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric ID of the ongoing Aircall call. |
| `contents` | array | Yes | Lines displayed to the agent: title, shortText, and/or user entries. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove User from Team

**Slug:** `AIRCALL_REMOVE_USER_FROM_TEAM`

Remove a User from a Team (membership change). Returns the updated team when Aircall sends HTTP 200, or a success confirmation for an empty HTTP 204. Does not delete the user.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | integer | Yes | Team numeric id. |
| `user_id` | integer | Yes | Numeric id of the user to remove from the team. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Calls

**Slug:** `AIRCALL_SEARCH_CALLS`

Find calls matching any combination of direction (inbound or outbound), user_id, phone_number and tag ids, optionally narrowed to a from/to date window. Use whenever at least one of those filters applies; not for unfiltered chronological browsing (AIRCALL_LIST_CALLS). Tag ids are AND-matched and come from AIRCALL_LIST_TAGS.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | integer | No | Only calls created at/before this UNIX timestamp (seconds). |
| `from` | integer | No | Only calls created at/after this UNIX timestamp (seconds). |
| `page` | integer | No | 1-based page number. |
| `tags` | array | No | Tag ids to filter by, AND-matched (serialized as repeated ?tags= params). |
| `order` | string ("asc" | "desc") | No | Sort by created_at: 'asc' or 'desc'. |
| `cursor` | string | No | Continuation cursor from a prior response's next_cursor. Omit for the first page. |
| `user_id` | integer | No | Filter by the id of the user who handled the call. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |
| `direction` | string ("inbound" | "outbound") | No | Filter by call direction: 'inbound' or 'outbound'. |
| `phone_number` | string | No | Filter by external phone number. |
| `fetch_contact` | boolean | No | Include the matched contact object on each call. |
| `fetch_aiva_conv` | boolean | No | Include AI Voice Agent segments in each call. |
| `fetch_short_urls` | boolean | No | Include shortened asset URLs. |
| `fetch_call_timeline` | boolean | No | Include the per-call event timeline. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Contacts

**Slug:** `AIRCALL_SEARCH_CONTACTS`

Search shared Contacts by phone_number and/or email (optionally within a from/to date window). Pass next_cursor back as cursor while has_more is true to retrieve subsequent pages. NOTE: contact created_at/updated_at are UNIX-epoch INTEGERS.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | integer | No | Only contacts created at/before this UNIX timestamp (seconds). |
| `from` | integer | No | Only contacts created at/after this UNIX timestamp (seconds). |
| `page` | integer | No | 1-based page number to fetch (default 1). |
| `email` | string | No | Email address to match. |
| `order` | string ("asc" | "desc") | No | Sort order: 'asc' or 'desc'. |
| `cursor` | string | No | Continuation cursor from a prior response's next_cursor. Omit for the first page. |
| `order_by` | string ("created_at" | "updated_at") | No | Field to sort by: 'created_at' or 'updated_at'. |
| `per_page` | integer | No | Items per page (1-50; Mercury default 10). |
| `phone_number` | string | No | Phone number to match (E.164). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set Call Recording State

**Slug:** `AIRCALL_SET_CALL_RECORDING_STATE`

Pause or resume recording on an ongoing Aircall call. This is destructive: audio from a paused interval is never recorded and cannot be recovered by resuming later. The call must still be live and live recording must be enabled on its Aircall number.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric ID of an ongoing Aircall call. |
| `state` | string ("paused" | "recording") | Yes | Desired live-recording state: paused or recording (resumed). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Start Outbound Call

**Slug:** `AIRCALL_START_OUTBOUND_CALL`

Place a real, billable outbound phone call from an Aircall user's desktop Workspace to an external number. Use when a specific user should dial someone now. Requires the user's desktop Workspace app to be open, the user to be available, and a number_id the user owns, from AIRCALL_LIST_USER_NUMBERS. Returns acceptance only. No call id comes back and the call may still fail to connect; locate it afterwards with AIRCALL_SEARCH_CALLS. Calling again places a second call.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Id of the user who will place the call. |
| `to` | string | Yes | Destination phone number in E.164 format (e.g. +14155550123). |
| `number_id` | integer | Yes | Id of the Aircall number to call from (must belong to the user). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Tag Call

**Slug:** `AIRCALL_TAG_CALL`

Tag a Call with one or more existing Tag ids (create tags first with AIRCALL_CREATE_TAG). Returns success on HTTP 201.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the call to tag. |
| `tags` | array | Yes | Array of EXISTING Tag ids to apply to the call. Get/create tag ids via AIRCALL_LIST_TAGS / AIRCALL_CREATE_TAG. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Transfer Call

**Slug:** `AIRCALL_TRANSFER_CALL`

Cold-transfer a call that is live right now to one user, one team, or one external phone number. The transfer takes effect immediately and cannot be undone. Use only while a call is ringing or connected; not for a call that has already ended, and not for starting a new call (AIRCALL_START_OUTBOUND_CALL). Supply exactly one of user_id, team_id or number. External-number transfers work only for unanswered inbound calls. Returns acceptance on HTTP 204; calling again transfers again.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the live (in-progress) call to transfer. |
| `number` | string | No | External phone number to transfer an unanswered inbound call to, in E.164 format. Supply exactly one of user_id, team_id, or number. |
| `team_id` | integer | No | Id of the Aircall team to transfer the call to. Supply exactly one of user_id, team_id, or number. |
| `user_id` | integer | No | Id of the Aircall user to transfer the call to. Supply exactly one of user_id, team_id, or number. |
| `dispatching_strategy` | string ("random" | "simultaneous" | "longest_idle") | No | Team-only dispatching strategy. Defaults to 'simultaneous' when team_id is selected. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Contact

**Slug:** `AIRCALL_UPDATE_CONTACT`

Update a Contact's core fields (first_name, last_name, company_name, information). Phone numbers and emails are edited via the dedicated contact-method tools (AIRCALL_ADD_CONTACT_METHOD / AIRCALL_UPDATE_CONTACT_METHOD / AIRCALL_DELETE_CONTACT_METHOD), not here.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Contact numeric id to update. |
| `last_name` | string | No | New last name. |
| `first_name` | string | No | New first name. |
| `information` | string | No | New free-text note. |
| `company_name` | string | No | New company name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Contact Method

**Slug:** `AIRCALL_UPDATE_CONTACT_METHOD`

Update one phone number or email address that is already on an Aircall contact. Set method_type='phone' or method_type='email' to say which kind method_id refers to, and always send a nonblank value — Aircall requires it on every update even when only the label changes. Use when changing a method that already exists; not for adding a new one (AIRCALL_ADD_CONTACT_METHOD), and not for removing one (AIRCALL_DELETE_CONTACT_METHOD). Answers HTTP 202 Accepted and returns the updated method as 'contact_method'.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `label` | string | No | New label for the method, e.g. 'Work', 'Mobile', 'Personal'. Omit to leave the label unchanged. |
| `value` | string | Yes | The nonblank phone number or email value. Aircall does not require E.164 or strict email syntax. REQUIRED on every update — Aircall rejects an update that omits it, even when only the label is changing, so re-send the current value if you are not changing it. |
| `method_id` | integer | Yes | Id of the phone or email entry to update. Get it from the `id` returned by AIRCALL_ADD_CONTACT_METHOD, or from the contact's phone_numbers[] / emails[] via AIRCALL_GET_CONTACT. |
| `contact_id` | integer | Yes | Numeric id of the contact that owns the method. |
| `method_type` | string ("email" | "phone") | Yes | Which kind of contact method `method_id` refers to: 'phone' for a phone number, 'email' for an email address. This selects the Aircall endpoint, so it must match the id — a phone id with method_type='email' will 404. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Number

**Slug:** `AIRCALL_UPDATE_NUMBER`

Update at least one mutable Number field: name changes its display name; availability_status changes the first Time Rule widget and can open or close call routing; live_recording_activated enables or disables inbound and outbound recording, and audio missed while disabled cannot be recovered; priority changes routing priority; messages replaces or clears supplied Music & Messages audio slots heard by live callers. These routing, recording, and audio effects are destructive and no previous value is restored automatically. Capture current values with AIRCALL_GET_NUMBER before updating if you need to revert. Do not assume omitted fields or message slots are preserved or cleared because Aircall does not document partial PUT semantics.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the Aircall number to update. |
| `name` | string | No | New display name for the number. |
| `messages` | object | No | Documented Music & Messages slots: welcome, waiting, ivr, voicemail, closed, callback_later, unanswered_call, after_hours, and ringing_tone. Each supplied value must be a valid public HTTP(S) URL. Aircall does not document whether a partially-supplied body preserves unlisted slots, so capture the current values with AIRCALL_GET_NUMBER first if you need to revert. |
| `priority` | integer ("0" | "1") | No | Routing priority: 0 for no priority, 1 for top priority, or null to clear it. |
| `availability_status` | string ("open" | "custom" | "closed") | No | Update the first Time Rule widget's availability status. |
| `live_recording_activated` | boolean | No | Enable or disable inbound and outbound call recording for this number. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Tag

**Slug:** `AIRCALL_UPDATE_TAG`

Update a Tag (PUT, full replace). name and color are both expected. name must remain unique per company. Aircall does not accept a mutable description field.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Tag numeric id to update. |
| `name` | string | Yes | Tag name (unique per company). |
| `color` | string | Yes | Tag color as a hex string, e.g. '#00B388'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update User

**Slug:** `AIRCALL_UPDATE_USER`

Update an existing Aircall user's name, availability_status, substatus, roles or wrap-up time in place. Use when changing a user who already exists; not for creating one (AIRCALL_CREATE_USER), and not for reading their current availability (AIRCALL_GET_USER_AVAILABILITY). substatus applies only when availability_status is 'unavailable'.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Numeric id of the user to update. |
| `role_ids` | array | No | Roles to assign to the user. Aircall documents this as an array of role NAME strings, not numeric ids: owner, supervisor, admin, or agent. |
| `last_name` | string | No | New last name. |
| `substatus` | string ("out_for_lunch" | "on_a_break" | "in_training" | "doing_back_office" | "other") | No | New availability sub-status. Aircall documents these values as applying when availability_status is 'unavailable', so this is rejected if the same request explicitly sets availability_status to 'available' or 'custom'. Sending substatus without availability_status is allowed — the user may already be unavailable server-side. |
| `first_name` | string | No | New first name. |
| `wrap_up_time` | integer | No | Post-call wrap-up time in seconds. |
| `availability_status` | string ("available" | "custom" | "unavailable") | No | New availability status: one of available | custom | unavailable. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Webhook

**Slug:** `AIRCALL_UPDATE_WEBHOOK`

Update an Aircall webhook's URL, name, active state, or event subscriptions. event_update_mode makes preserve/replace/add/remove/all explicit. The safe default is preserve, because Aircall otherwise resets omitted events to all.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No | New public HTTPS destination URL. |
| `active` | boolean | No | True to reactivate the webhook or false to disable it. |
| `events` | array | No | Event names used by replace/add/remove mode. Omit in preserve/all mode. |
| `webhook_id` | string | Yes | UUID of the webhook to update, or its legacy numeric Aircall id. |
| `custom_name` | string | No | New webhook display name. |
| `event_update_mode` | string ("preserve" | "replace" | "add" | "remove" | "all") | No | Explicit event-set intent: preserve leaves events unchanged; replace sets exactly events; add/remove modifies named events; all intentionally subscribes to every event. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |