Just like you, we are enthusiastic builders and we love to automate things. At Aircall, we are building the next-gen business phone system and we know that one of the best ways to do that is to give you the ability to have the hands on Aircall features.

👁 Aircall Developer

We are maintaining a Public API. This service allows any developers to retrieve and manage Aircall data with HTTP requests.

We are also supporting Webhooks. We can call back any endpoint of your choice, each time an event occurs on an Aircall account (contact added, call created, user switched off... see the Webhooks section for a complete list). Webhooks provide great scalability to your application and only requires setting up a public web server!

Want to see an example of how easy it is to connect with Aircall Public API and Webhooks? Take a look at our tutorials!

Our Engineering team is on Twitter, follow them @aircalltech!

Check the Changelog if you've already implemented something based on previous versions of this documentation.

By visiting or using this developers website, you agree to be bound by Aircall’s API License Agreement

Not a Developer?

Install one of many integrations built by our partners in our Marketplace!

Aircall Public API is a classic REST API. It can be used with any programming languages and offers a fast, reliable and secure access to an Aircall account information.

The root endpoint of Aircall Public API is https://api.aircall.io/v1.

Please note that only HTTPS requests are valid as requests will communicate over SSL connection.

Each Public API request must be authenticated and should not exceed the rate limit, please check the Authentication and the rate limiting sections before jumping in our documentation!

Request
GET https://api.aircall.io

Response
{
 "resource": "Aircall Documentation",
 "contact": "support@aircall.io"
}

With Aircall Public API, Authentication can be done through OAuth or Basic Auth.

If you want to build an App for companies using Aircall - this is mainly the case for Technology Partners - please use the OAuth flow. It is a requirement to be listed on the Aircall App Marketplace. You can create a partner-specific account by signing up here!

If you are an Aircall customer, building for your own Aircall account only, the Basic Auth flow will do the trick.

All endpoints behave similarly between the two authentication methods, unless indicated otherwise in the documentation.

Aircall built a powerful Ecosystem of apps, providing its customers an easy way to enhance their voice experience.

In Aircall, integrations are enabled at the Company level, which means they can only be set by an Admin user. It is possible to configure several instances of an integration on one Aircall account.

Aircall implemented the OAuth 2.0 authentication protocol so you can easily build an app on top of Aircall and deploy it on Aircall's Marketplace.

Beyond the added security and scalability, the Aircall OAuth flow will make your app visible to all customers in the Aircall Dashboard and provide a simple way for customers to install your app from Aircall or from your own website.

Want to know every secret about OAuth? Read the official documentation RFC 6750!

Oauth terminology
• install_uri

  String
  Aircall fetches the install_uri URI when starting the OAuth flow. This step is often used to display a Settings page, instructions on how to use the app or any useful information for the Admin.
  It must eventually forward to https://dashboard.aircall.io/oauth/authorize with client_id, redirect_uri, response_type=code and scope=public_api query params. See Step 3 of the OAuth flow.
  Must use HTTPS.
• redirect_uri

  String
  Aircall sends the Admin's authorization code to the redirect_uri URI, once they authorized the app, or the error if any.
  Must use HTTPS.
• client_id

  String
  Used in both the [DASHBOARD] /oauth/authorize and [API] /v1/oauth/token request.
  Provided by Aircall.
• client_secret

  String
  Used in the request body of [API] /v1/oauth/token.
  Provided by Aircall.
• code

  String
  An authentication code provided by Aircall valid for 10min.
  Must be converted in an access_token (see this endpoint).
• access_token

  String
  Token used to send requests to Aircall Public API as a Company.
  More info on how to use it here.
• state

  String
  An optional string value created by your app to maintain state between the request and callback. This parameter should be used for preventing Cross-site Request Forgery and will be passed back to you, unchanged, in your redirect_uri.

OAuth credentials

Before starting building the OAuth flow for your app, you will need to get OAuth client_id and client_secret from Aircall. Click the start building button on top of the page and fill in the form. We will get back to you shortly.

When signing up, an install_uri and a redirect_uri will be asked, make sure you have them ready. Read the OAuth flow first to understand what they are!

OAuth flow

👁 Aircall OAuth flow

1. Aircall ﹣ When an Admin installs an App, a popup opens up and loads the install_uri URL.
2. Partner ﹣ A Web server receives the GET request on the install_uri route. This step is often used to display a custom Settings page, instructions on how to use the app and/or any useful information for the Admin.
3. Partner ﹣ Once Step 2 is done, Web server redirects/forwards the request to the following Aircall URL: https://dashboard.aircall.io/oauth/authorize?client_id=XX&redirect_uri=YY&response_type=code&scope=public_api&state=ZZ
4. Aircall ﹣ Aircall then displays the authorization window. Only users who are Admins will be able to see this window, others will be redirected to the Download page. Once the Admin consented to the permissions the app is requesting (scope=public_api), Aircall loads the redirect_uri URL with a code parameter.
5. Partner ﹣ Web server receives the GET request on the redirect_uri route with the code query param…
6. Partner ﹣ …and sends a [POST] https://api.aircall.io/v1/oauth/token request to Aircall's Public API with the proper body params (see here).
7. Aircall ﹣ Aircall authenticates the [POST] request, create an access_token and sends it back to the Web server.
8. Partner ﹣ Web server stores the access_token for further use!

Start the instructions at Step 3 if you want to trigger the install flow directly from your interface and not from the Aircall Dashboard. Integrations can only be installed by users who are Admins on Aircall!

Check out our Ruby example app on Github to better understand how to implement the Aircall OAuth flow!

Get an access_token via the Public API

Once you get an OAuth authorization code from the OAuth flow, you need to convert it into a Public API access_token with the following request.

This access_token will then be used as a Bearer token in the Authorization header of each Public API requests you will make and does not expire.

Body params
• client_id

  String
  The client_id provided by Aircall. More information in the Oauth credentials section.
  Mandatory field.
• client_secret

  String
  The client_secret provided by Aircall. More information in the Oauth credentials section.
  Mandatory field.
• code

  String
  The OAuth authorization code Aircall sent back to your server.
  Mandatory field.
• redirect_uri

  String
  Your redirect_uri.
  Mandatory field.
• grant_type

  String
  Must be authorization_code.
  Mandatory field.

Request
POST https://api.aircall.io/v1/oauth/token
{
 "client_id": YOUR_AIRCALL_CLIENT_ID,
 "client_secret": YOUR_AIRCALL_CLIENT_SECRET,
 "code": TMP_AUTHORIZATION_CODE,
 "redirect_uri": YOUR_REDIRECT_URI,
 "grant_type": "authorization_code"
}

Response
Status: 200 OK

{
 "access_token": "2d492d492d492d492d492d492d492d",
 "token_type": "Bearer",
 "created_at": 1585868617
}

Test the access_token

A /v1/ping endpoint is available to test the access_token retrieved via the Public API (as described here).

The access_token must be used in the Authorization HTTP header of your request, as a Bearer token.

Request

curl -X GET https://api.aircall.io/v1/ping \
 -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Response
Status: 200 OK

{
 "ping": "pong"
}

As an Aircall customer, an api_id and api_token are needed to use Aircall Public API: go to your Company's Settings page. In the API Keys section, click on Add a new API key and get your api_token and api_token.

Do not forget to copy/paste your api_token somewhere safe, we won't be able to retrieve it for you as Aircall does not store it in plain text!

If you are building an App for several companies using Aircall, please refer to the OAuth section.

👁 Aircall Basic auth

Public API requests must be authenticated using HTTP Basic Authentication. The api_id is the username and the api_token is the password for each Public API requests.

The Authorization HTTP header is constructed as follows:

1. The api_id and api_token are concatenated with a single colon :.
2. The resulting string is encoded using Base64.
3. The authorization header results in Authorization: Basic YOUR_ENCODED_STRING.

Always prefer Base64 encoding in the Authorization HTTP header rather than the following: https://api_id:api_token@api.aircall.io.
It is not recommended to authenticate requests passing the api_id and api_token in the URL for security reasons and as some programming languages and platforms do not support it!

Request

curl -X GET https://api.aircall.io/v1/ping \
 -H "Authorization: Basic {YOUR_ENCODED_STRING}"

Response
Status: 200 OK

{
 "ping": "pong"
}

Aircall limits the number of requests to its Public API to 120 requests per minute per company. The following headers are available in API headers' responses when the rate limit has been reached, giving more insight on your API usage:

Contact us on support.aircall.io if you need to make more requests per minute, we will add a higher rate limit to your API keys!

When retrieving a list of objects with a [GET] request, results are being paginated by Aircall.

Pagination information will be presented in the meta object, available in the payload body and described below.

The meta object
• count

  Integer
  Count of items present in the current page.
• total

  Integer
  Count of items in total, according to search params.
• current_page

  Integer
  Current page number.
• per_page

  Integer
  Number of results retrieved per page.
  Default is 20. Minimum is 1, maximum is 50.
• next_page_link

  String
  URL to follow to go to the next page results.
  Can be null.
• previous_page_link

  String
  URL to follow to go to the previous page results.
  Can be null.

The two following attributes can be set in any URL query params to navigate from one page to the other:

Query params
• page

  Integer
  Current page.
  Default is 1.
• per_page

  Integer
  Number of results retrieved per page
  Default is 20.

Calls and Contacts are limited to 10,000 items, even with pagination on. To pass over this limit, we encourage you to use the from param as much as you can!

Response
{
 "meta": {
 "count": 20,
 "total": 2234,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": "https://api.aircall.io/v1/calls?page=2&per_page=20",
 "previous_page_link": null
 },
 ...
}

Aircall uses standard HTTP response codes to indicate the success or failure of an API request:

• 2xx codes indicate success
• 4xx codes indicate an error that failed given the information provided
• 5xx codes indicate an error with Aircall's servers

An error and a troubleshoot key will be present in the response payload body. The troubleshoot key is a readable description of the error.

More detailed HTTP response codes will be provided in endpoints documentation.

Response
{
 "error": "...", // Title
 "troubleshoot": "..." // Verbose message
}

Aircall APIs and Webhooks are versioned to allow for continuous evolution and improvement while maintaining backward compatibility for existing integrations. API versions are indicated in the URL path. The webhook event names are now suffixed with “v2”.

For APIs, Aircall uses URL-based versioning, where the API version is included directly in the endpoint path. For example:

• Version 1 endpoints: /v1/users, /v1/calls, etc.

• Version 2 endpoints: /v2/users, etc.

For Webhook events, the version number is suffixed in the event name. For example:

• Version 1 webhook event: user.connected

• Version 2 webhook event: user.connected.v2

As of now, v2 of user APIs and webhook events is available

Every POST, PUT and DELETE HTTP request sent to Aircall Public API must specify the Content-Type entity header to application/json.

Request
HTTP headers:
{ "Content-Type": "application/json" }

Please refer to this section for announcements related to deprecation or changes as well as availability of new APIs and Webhooks.

Contact us on support.aircall.io if you need more info regarding these announcements.

In this section, we list all the available Public APIs.

Get all users associated to an Aircall account, or retrieve, create and update info about one specific User! You can also start outbound calls on a User's Phone app.

Users can be either Admins or Agents:

• Admins: can access the Dashboard and the Phone app, and can invite other users.
• Agents: can only access the Phone app and recording files.

Users are assigned to Numbers.

Attributes
• id

  Integer
  Unique identifier for the User.
• direct_link

  String
  Direct API URL.
• name

  String
  Full name of the User.
  Results of first_name last_name.
• email

  String
  Email of the User.
• created_at

  String
  Timestamp when the User was created, in UTC.
• available

  Boolean
  Current availability status of the User, based on their working hours.
• availability_status

  String
  Current working status of the User.
  Can be available, custom (= available according to their Working Hours and Timezone) or unavailable (= Do Not Disturb or other unavailable status). More availablility statuses can be retrieved, see the Availability table below.
• substatus

  String
  Current substatus of the User.
  If user selects availability_status as available or custom (available according to working hours or timezone) then substatus will be always_open.
  If user selects availability_status as unavailable and doesn't select a substatus or unavailability reason in Phone App then it will be always_closed.
  If user selects availability_status as unavailable and selects a substatus or unavailability reason in Phone App i.e. Out for lunch, On a break, In training, Back office or Other. The substatus will contain the exact substauts or unavailability reason selected.
• numbers

  Array
  List of Numbers associated to this User.
• time_zone

  String
  The User's timezone. This can be set either from the Dashboard or the Phone (check our Knowledge Base).
  Default is Etc/UTC. More details on Timezones here.
• language

  String
  The User's preferred language. This can be set either from the Dashboard or the Phone (check our Knowledge Base).
  The format is IETF language tag. Default is en-US.
• wrap_up_time

  Integer
  A pre-set timer triggered after a call has ended, during which the user can’t receive any calls. Learn more..

Availability
• available

  String
  Agent ready to answer calls.
• offline

  String
  Agent not online.
• do_not_disturb

  String
  Agent toggled themself as do not disturb.
• in_call

  String
  Agent is currently on a call.
• after_call_work

  String
  Agent is performing their after-call work (tagging a call or wrapping up).

Find a proper definition of each of those availability statuses in our Knowledge Base and retrieve those granular availability statuses with this endpoint!

Endpoints
GET /v1/usersList all Users
GET /v1/users/456Retrieve a User
GET /v1/users/john.doe@aircall.ioRetrieve a User
GET /v1/users/:idRetrieve a User
POST /v1/usersCreate a User
PUT /v1/users/:idUpdate a User
DELETE /v1/users/:idDelete a User
GET /v1/users/availabilitiesRetrieve list of Users availability
GET /v1/users/:id/availabilityCheck availability of a User
POST /v1/users/:id/callsStart an outbound call
POST /v1/users/:id/dialDial a phone number in the Phone

Fetch all Users associated to a Company and their information.

Looking for more granular availability statuses? Check the availability endpoint! User V1 API will be deprecated soon. Please migrate to User V2 API.

Query params
• from

  String
  Set a minimal creation date for Users (UNIX timestamp).
• to

  String
  Set a maximal creation date for Users (UNIX timestamp).
• order

  String
  Reorder entries by created_at. Can be asc or desc.
  Default value is asc

Pagination params can be used on this request.

Request
GET /v1/users

Response
Status: 200 OK

{
 "meta": {
 "count": 3,
 "total": 3,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": null,
 "previous_page_link": null
 },
 "users": [
 {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US",
 "substatus": "always_opened",
 "wrap_up_time": 0,
 "extension": "001"
 },
 {
 "id": 457,
 "direct_link": "https://api.aircall.io/v1/users/457",
 "name": "Amy Rudd",
 "email": "amy.rudd@aircall.io",
 "available": true,
 "availability_status": "custom",
 "created_at": "2019-12-30T18:10:21.000Z",
 "time_zone": "Etc/UTC",
 "language": "en-US",
 "substatus": "always_opened",
 "wrap_up_time": 0,
 "extension": "002"
 },
 {
 "id": 458,
 "direct_link": "https://api.aircall.io/v1/users/458",
 "name": "Vera Martin",
 "email": "vera.martin@aircall.io",
 "available": false,
 "availability_status": "unavailable",
 "created_at": "20120-01-02T09:01:58.000Z",
 "time_zone": "Europe/Paris",
 "language": "fr-FR",
 "substatus": "always_opened",
 "wrap_up_time": 0,
 "extension": "003"
 }
 ]
}

Retrieve details of a specific User.

Looking for more granular availability statuses for a User? Check this dedicated endpoint.

User V1 API will be deprecated soon. Please migrate to User V2 API.

Path params
• id

  Integer/String
  Unique identifier or email address of the User.

Retrieve by ID:

Request
GET /v1/users/456

Retrieve by email:

Request
GET /v1/users/john.doe@aircall.io

Request
GET /v1/users/:id

Response
Status: 200 OK

{
 "user": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US",
 "substatus": "always_opened",
 "wrap_up_time": 0,
 "extension": "001",
 "default_number_id": 1234,
 "numbers": [
 {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 "welcome": "https://example.com/welcome.mp3",
 "waiting": "https://example.com/waiting_music.mp3",
 "ivr": "https://example.com/ivr_message.mp3",
 "voicemail": "https://example.com/voicemail.mp3",
 "closed": "https://example.com/closed_message.mp3",
 "callback_later": "https://example.com/callback_later.mp3",
 "unanswered_call": "https://example.com/unanswered_call.mp3",
 "after_hours": "https://example.com/closed_message.mp3",
 "ringing_tone": "https://example.com/waiting_music.mp3"
 }
 }
 ]
 }
}

Users can be created one at a time. After creation, a unique user ID will be included in the response's payload. An invitation email will be sent to the User, they will have to confirm their account before being able to use Aircall.

A user.created Webhook event is sent on User creation. More information in the Webhooks section.

User V1 API will be deprecated soon. Please migrate to User V2 API.

Body params
• email

  String
  Must be a valid and unique email.
  Mandatory field.
• first_name

  String
  Can't be blank if defined.
  Mandatory field.
• last_name

  String
  Can't be blank if defined.
  Mandatory field.
• availability_status

  String
  available, custom or unavailable.
  Default value is available
• role_ids

  Array<String>
  owner, supervisor, admin or agent.
  Default value is agent
• wrap_up_time

  Integer
  Optional number of seconds as wrap-up time after a call. It applies only to a user that includes the role agent
  Default value is 0 seconds
• inviter_user_id

  Integer
  Optional id of the user who invited the user to create
  The inviter must be an admin. If a non-admin user ID is provided, the request will return a 400 error.

Request
POST /v1/users

{
 "email": "jeffrey.curtis@aircall.io",
 "first_name": "Jeffrey",
 "last_name": "Curtis"
}

Response
Status: 201 Created

{
 "user": {
 "id": 458,
 "direct_link": "https://api.aircall.io/v1/users/458",
 "name": "Jeffrey Curtis",
 "email": "jeffrey.curtis@aircall.io",
 "available": false,
 "availability_status": "available",
 "created_at": "2020-02-18T20:52:22.000Z",
 "time_zone": "Etc/UTC",
 "language": "en-US",
 "numbers": [],
 "wrap_up_time": 0
 }
}

Some fields can be updated via the Public API. For instance, a User's availability status could be automatically updated based on information from their calendar or a workforce management tool.

User V1 API will be deprecated soon. Please migrate to User V2 API.

Path params
• id

  Integer
  Unique identifier for the User.

Body params
• first_name

  String
  Can't be blank if defined.
• last_name

  String
  Can't be blank if defined.
• availability_status

  String
  available, custom or unavailable.
• substatus

  String
  Possible values of substatus when availability_status is unavailable: out_for_lunch, on_a_break, in_training, doing_back_office, other
• role_ids

  Array<String>
  owner, supervisor, admin or agent.
• wrap_up_time

  Integer
  Number of seconds as wrap-up time after a call. It applies only to a user that has the role agent.

Request
PUT /v1/users/:id

{
 "first_name": "Jeff Updated"
}

Response
Status: 200 OK

{
 "user": {
 "id": 458,
 "direct_link": "https://api.aircall.io/v1/users/458",
 "name": "Jeff Updated Curtis",
 "email": "jeffrey.curtis@aircall.io",
 "available": false,
 "availability_status": "available",
 "created_at": "2020-02-18T20:52:22.000Z",
 "time_zone": "America/New_York",
 "language": "en-US",
 "numbers": [],
 "wrap_up_time": 55,
 "extension": "001",
 "substatus": "always_opened"
 }
}

When deleting a User, all data associated to them will also be destroyed and won't be recoverable.

A user.deleted Webhook event is sent on User deletion. More information in the Webhooks section.

Path params
• id

  Integer
  Unique identifier for the User.

Request
DELETE /v1/users/:id

Response
Status: 204 No Content

List the detailed availability of all Users, displayed in the Dashboard's Activity Feed.

Please refer to the User object definition to see all the possible values of the availability field.

👁 Users availabilities

Find a detailed definition of each availability status in our Knowledge Base.

Query params
• from

  String
  Set a minimal creation date for Users (UNIX timestamp).
• to

  String
  Set a maximal creation date for Users (UNIX timestamp).
• order

  String
  Reorder entries by created_at. Can be asc or desc.
  Default value is asc

Request
GET /v1/users/availabilities

Response
Status: 200 OK

{
 "meta": {
 "count": 3,
 "total": 3,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": null,
 "previous_page_link": null
 },
 "users": [
 {
 "id": 456,
 "availability": "available"
 },
 {
 "id": 457,
 "availability": "offline"
 }
 {
 "id": 458,
 "availability": "do_not_disturb"
 }
 ]
}

Retrieve the detailed availability of a specific User, displayed in the Dashboard's Activity Feed.

Please refer to the User object definition to see all the possible values of the availability field.

Find a proper definition of each availability status in our Knowledge Base.

Path params
• id

  Integer
  Unique identifier for the User.

Request
GET /v1/users/:id/availability

Response
Status: 200 OK

{
 "availability": "after_call_work"
}

Outbound calls can be automatically started for a User from their Phone app. It is often used to build a Click-to-call feature!

A Number ID and a phone number to dial must be provided in the request's body.

The User must be available, not on a call and associated to the Number.

Number must be active (validated), inactive numbers can be seen in the Aircall Dashboard.

This feature is only available on Aircall Phone app on Desktop for now, not yet on iOS and Android.

Please note, the API doesn’t support multiple sessions. It is not recommended to use this API along with Aircall CTI or Web App when multiple tabs are open

Path params
• id

  Integer
  Unique identifier for the User.

Body params
• number_id

  Integer
  Unique identifier of the Number to use for the call.
  Mandatory field.
• to

  String
  The number to dial in E.164 format.
  Mandatory field.

Request
POST /v1/users/:id/calls

{
 "number_id": 123,
 "to": "+18001231234"
}

Response
Status: 204 No Content

Sending a request to this endpoint will fill the User's Phone app with the to params. They will then be able to start the call within the Phone app and will be free to choose from which Number they want to start the call from. It is often used to build a Click-to-dial feature!

User must be available and not on a call.

This feature is also available from the Aircall Everywhere CTI.

This feature is only available on Aircall Phone app on Desktop for now, not yet on iOS and Android.

Path params
• id

  Integer
  Unique identifier for the User.

Body params
• to

  String
  The phone number to dial in E.164 format.
  Mandatory field.

Request
POST /v1/users/:id/dial

{
 "to": "+18001231234"
}

Response
Status: 204 No Content

Get all users associated to an Aircall account, or retrieve, create and update info about one specific User V2! You can also start outbound calls on an User V2's Phone app.

Users can be either Admins or Agents:

• Admins: can access the Dashboard and the Phone app, and can invite other users.
• Agents: can only access the Phone app and recording files.

Please note User v2 object doesn't include a numbers object

Attributes
• id

  Integer
  Unique identifier for the User.
• direct_link

  String
  Direct API URL.
• name

  String
  Full name of the User.
  Results of first_name last_name.
• email

  String
  Email of the User.
• created_at

  String
  Timestamp when the User was created, in UTC.
• available

  Boolean
  Current availability status of the User, based on their working hours.
• availability_status

  String
  Current working status of the User.
  Can be available, custom (= available according to their Working Hours and Timezone) or unavailable (= Do Not Disturb or other unavailable status). More availablility statuses can be retrieved, see the Availability table below.
• substatus

  String
  Current substatus of the User.
  If user selects availability_status as available or custom (available according to working hours or timezone) then substatus will be always_open.
  If user selects availability_status as unavailable and doesn't select a substatus or unavailability reason in Phone App then it will be always_closed.
  If user selects availability_status as unavailable and selects a substatus or unavailability reason in Phone App i.e. Out for lunch, On a break, In training, Back office or Other. The substatus will contain the exact substauts or unavailability reason selected.
• time_zone

  String
  The User's timezone. This can be set either from the Dashboard or the Phone (check our Knowledge Base).
  Default is Etc/UTC. More details on Timezones here.
• language

  String
  The User's preferred language. This can be set either from the Dashboard or the Phone (check our Knowledge Base).
  The format is IETF language tag. Default is en-US.
• wrap_up_time

  Integer
  A pre-set timer triggered after a call has ended, during which the user can't receive any calls. Learn more..
• last_call_id

  Integer
  The unique identifier of the last call associated with the user's wrap-up time.
  This attribute is only available in user.wut_start.v2 and user.wut_end.v2 webhook events and not in User APIs.
  If mandatory call tagging is enabled in Aircall Workspace and wrap-up time is set to zero or any other duration, or if a call is transferred to an external number and does not connect, then last_call_id won't be available.

Availability
• available

  String
  Agent ready to answer calls.
• offline

  String
  Agent not online.
• do_not_disturb

  String
  Agent toggled themself as do not disturb.
• in_call

  String
  Agent is currently on a call.
• after_call_work

  String
  Agent is performing their after-call work (tagging a call or wrapping up).

Find a proper definition of each of those availability statuses in our Knowledge Base and retrieve those granular availability statuses with this endpoint!

Endpoints
GET /v2/usersList all Users V2
GET /v2/users/456Retrieve a User V2
GET /v2/users/john.doe@aircall.ioRetrieve a User V2
GET /v2/users/:idRetrieve a User V2
POST /v2/usersCreate a User V2
PUT /v2/users/:idUpdate a User V2
GET /v2/users/:id/numbersList all Numbers for a User V2

Fetch all Users V2 associated to a Company and their information.

Looking for more granular availability statuses? Check the availability endpoint!

Query params
• from

  String
  Set a minimal creation date for Users (UNIX timestamp).
• to

  String
  Set a maximal creation date for Users (UNIX timestamp).
• order

  String
  Reorder entries by created_at. Can be asc or desc.
  Default value is asc

Pagination params can be used on this request.

Request
GET /v2/users

Response
Status: 200 OK

{
 "meta": {
 "count": 3,
 "total": 3,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": null,
 "previous_page_link": null
 },
 "users": [
 {
 "id": 456,
 "direct_link": "https://api.aircall.io/v2/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US",
 "substatus": "always_opened",
 "wrap_up_time": 0,
 "extension": "001"
 },
 {
 "id": 457,
 "direct_link": "https://api.aircall.io/v2/users/457",
 "name": "Amy Rudd",
 "email": "amy.rudd@aircall.io",
 "available": true,
 "availability_status": "custom",
 "created_at": "2019-12-30T18:10:21.000Z",
 "time_zone": "Etc/UTC",
 "language": "en-US",
 "substatus": "always_opened",
 "wrap_up_time": 0,
 "extension": "002"
 },
 {
 "id": 458,
 "direct_link": "https://api.aircall.io/v2/users/458",
 "name": "Vera Martin",
 "email": "vera.martin@aircall.io",
 "available": false,
 "availability_status": "unavailable",
 "created_at": "20120-01-02T09:01:58.000Z",
 "time_zone": "Europe/Paris",
 "language": "fr-FR",
 "substatus": "always_opened",
 "wrap_up_time": 0,
 "extension": "003"
 }
 ]
}

Retrieve details of a specific User V2.

Looking for more granular availability statuses for a User V2? Check this dedicated endpoint.

Path params
• id

  Integer/String
  Unique identifier or email address of the User.

Retrieve by ID:

Request
GET /v2/users/456

Retrieve by email:

Request
GET /v2/users/john.doe@aircall.io

Request
GET /v2/users/:id

Response
Status: 200 OK

{
 "user": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v2/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US",
 "substatus": "always_opened",
 "wrap_up_time": 0,
 "extension": "001",
 "default_number_id": 1234
 }
}

Users can be created one at a time. After creation, a unique user ID will be included in the response's payload. An invitation email will be sent to the User V2, they will have to confirm their account before being able to use Aircall.

A user.created.v2 Webhook event is sent on User creation. More information in the Webhooks section.

Body params
• email

  String
  Must be a valid and unique email.
  Mandatory field.
• first_name

  String
  Can't be blank if defined.
  Mandatory field.
• last_name

  String
  Can't be blank if defined.
  Mandatory field.
• availability_status

  String
  available, custom or unavailable.
  Default value is available
• role_ids

  Array<String>
  owner, supervisor, admin or agent.
  Default value is agent
• wrap_up_time

  Integer
  Optional number of seconds as wrap-up time after a call. It applies only to a user that includes the role agent
  Default value is 0 seconds
• inviter_user_id

  Integer
  Optional id of the user who invited the user to create
  The value will be ignored if the inviter is not an admin

Request
POST /v2/users

{
 "email": "jeffrey.curtis@aircall.io",
 "first_name": "Jeffrey",
 "last_name": "Curtis"
}

Response
Status: 201 Created

{
 "user": {
 "id": 458,
 "direct_link": "https://api.aircall.io/v2/users/458",
 "name": "Jeffrey Curtis",
 "email": "jeffrey.curtis@aircall.io",
 "available": false,
 "availability_status": "available",
 "created_at": "2020-02-18T20:52:22.000Z",
 "time_zone": "Etc/UTC",
 "language": "en-US",
 "wrap_up_time": 0
 }
}

Some fields can be updated via the Public API. For instance, a User V2's availability status could be automatically updated based on information from their calendar or a workforce management tool.

Path params
• id

  Integer
  Unique identifier for the User.

Body params
• first_name

  String
  Can't be blank if defined.
• last_name

  String
  Can't be blank if defined.
• availability_status

  String
  available, custom or unavailable.
• substatus

  String
  Possible values of substatus when availability_status is unavailable: out_for_lunch, on_a_break, in_training, doing_back_office, other
• role_ids

  Array<String>
  owner, supervisor, admin or agent.
• wrap_up_time

  Integer
  Number of seconds as wrap-up time after a call. It applies only to a user that has the role agent.

Request
PUT /v2/users/:id

{
 "first_name": "Jeff Updated"
}

Response
Status: 200 OK

{
 "user": {
 "id": 458,
 "direct_link": "https://api.aircall.io/v2/users/458",
 "name": "Jeff Updated Curtis",
 "email": "jeffrey.curtis@aircall.io",
 "available": false,
 "availability_status": "available",
 "created_at": "2020-02-18T20:52:22.000Z",
 "time_zone": "America/New_York",
 "language": "en-US",
 "wrap_up_time": 55,
 "extension": "001",
 "substatus": "always_opened"
 }
}

Fetch all Numbers associated to a specific User V2.

Path params
• id

  Integer
  Unique identifier for the User.

Query params
• order

  String
  Reorder entries by created_at. Can be asc or desc.
  Default value is asc

Pagination params can be used on this request.

Request
GET /v2/users/:id/numbers

Response
Status: 200 OK

{
 "numbers": [
 {
 "id": 673,
 "direct_link": "https://api.aircall.io/v1/numbers/673",
 "name": "Matheus",
 "digits": "+33 1 76 42 03 02",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "open",
 "is_ivr": false,
 "live_recording_activated": false,
 "priority": 0,
 "messages": {
 "welcome": "https://example.com/welcome.mp3",
 "waiting": "https://example.com/waiting_music.mp3",
 "ivr": "https://example.com/ivr_message.mp3",
 "voicemail": "https://example.com/voicemail.mp3",
 "closed": "https://example.com/closed_message.mp3",
 "callback_later": "https://example.com/callback_later.mp3",
 "unanswered_call": "https://example.com/unanswered_call.mp3",
 "after_hours": "https://example.com/after_hours.mp3",
 "ringing_tone": "https://example.com/ringing_tone.mp3"
 },
 "created_at": "2016-12-28T10:15:05.000Z",
 "flow_editor_enabled": true
 },
 {
 "id": 719,
 "direct_link": "https://api.aircall.io/v1/numbers/719",
 "name": "Pokedex Twilio Staging",
 "digits": "+33 4 20 88 02 82",
 "country": "RO",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "open",
 "is_ivr": false,
 "live_recording_activated": false,
 "priority": 0,
 "messages": {
 "welcome": "https://example.com/welcome.mp3",
 "waiting": "https://example.com/waiting_music.mp3",
 "ivr": "https://example.com/ivr_message.mp3",
 "voicemail": "https://example.com/voicemail.mp3",
 "closed": "https://example.com/closed_message.mp3",
 "callback_later": "https://example.com/callback_later.mp3",
 "unanswered_call": "https://example.com/unanswered_call.mp3",
 "after_hours": "https://example.com/after_hours.mp3",
 "ringing_tone": "https://example.com/ringing_tone.mp3"
 },
 "created_at": "2017-02-06T11:01:05.000Z",
 "flow_editor_enabled": true
 }
 ],
 "meta": {
 "count": 2,
 "total": 1872,
 "current_page": 2,
 "per_page": 2,
 "next_page_link": "https://api.aircall.io/v2/users/123/numbers?order=asc&page=3&per_page=2",
 "previous_page_link": "https://api.aircall.io/v2/users/123/numbers?order=asc&page=1&per_page=2"
 }
}

Users can be grouped in Teams and managed from the Dashboard.

Teams are only used in call distributions of Numbers.

More info on how to use Aircalls' Team feature in our Knowledge Base.

Attributes
• id

  Integer
  Unique identifier for the Team.
• direct_link

  String
  Direct API URL.
• name

  String
  Full name of the Team.
  name must be unique in a company and the length of the string should be 64 characters maximum.
• created_at

  String
  Timestamp when the Team was created, in UTC.
• users

  Array
  List of Users associated to this Team.
  User attribute available is not available in Teams endpoint. User's availability_status and default_number_id can be retrieved using List all Teams endpoint.

Endpoints
GET /v1/teamsList all Teams
GET /v1/teams/:idRetrieve a Team
POST /v1/teamsCreate a Team
DELETE /v1/teams/:idDelete a Team
POST /v1/teams/:team_id/users/:user_idAdd a User to a Team
DELETE /v1/teams/:team_id/users/:user_idRemove a User from a Team

Fetch all Teams associated to a company and their information.

Query params
• order

  String
  Reorder entries by created_at. Can be asc or desc.
  Default value is asc

Pagination params can be used on this request.

Request
GET /v1/teams

Response
Status: 200 OK

{
 "meta": {
 "count": 1,
 "total": 1,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": null,
 "previous_page_link": null
 },
 "teams": [
 {
 "id": 678,
 "name": "Global Sales",
 "direct_link": "https://api.aircall.io/v1/teams/678",
 "created_at": "2020-03-10T08:31:43.000Z",
 "users": [
 {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/4c56",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "availability_status": "available",
 "default_number_id": 1234,
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York"
 },
 {
 "id": 457,
 "direct_link": "https://api.aircall.io/v1/users/457",
 "name": "Amy Rudd",
 "email": "amy.rudd@aircall.io",
 "availability_status": "available",
 "default_number_id": 1234,
 "created_at": "2019-12-30T18:10:21.000Z",
 "time_zone": "Etc/UTC"
 }
 ]
 }
 ]
}

Retrieve details of a specific Team.

Path params
• id

  Integer
  Unique identifier for the Team.

Request
GET /v1/teams/:id

Response
Status: 200 OK

{
 "team": {
 "id": 678,
 "name": "Global Sales",
 "direct_link": "https://api.aircall.io/v1/teams/678",
 "created_at": "2020-03-10T08:31:43.000Z",
 "users": [
 {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/4c56",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York"
 },
 {
 "id": 457,
 "direct_link": "https://api.aircall.io/v1/users/457",
 "name": "Amy Rudd",
 "email": "amy.rudd@aircall.io",
 "created_at": "2019-12-30T18:10:21.000Z",
 "time_zone": "Etc/UTC"
 }
 ]
 }
}

A name must be provided when creating a Team.

Please use the following endpoint to add Users to it.

Body params
• name

  String
  Can't be blank if defined.
  Mandatory field.

Request
POST /v1/teams

{
 "name": "Support USA"
}

Response
Status: 201 Created

{
 "team": {
 "id": 679,
 "name": "Support USA",
 "direct_link": "https://api.aircall.io/v1/teams/679",
 "created_at": "2020-03-10T20:29:52.000Z",
 "users": []
 }
}

When deleting Teams, they will be removed from the Numbers call distribution.

Users and Calls won't be deleted.

Path params
• id

  Integer
  Unique identifier for the Team.

Request
DELETE /v1/teams/:id

Response
Status: 200 OK

Users can be added one by one to a Team.

Path params
• team_id

  Integer
  Unique identifier for the Team.
• user_id

  Integer
  Unique identifier for the User.

Request
POST /v1/teams/:team_id/users/:user_id

Response
Status: 201 Created

{
 "team": {
 "id": 679,
 "name": "Support USA",
 "direct_link": "https://api.aircall.io/v1/teams/679",
 "created_at": "2020-03-10T20:29:52.000Z",
 "users": [
 {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/4c56",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York"
 }
 ]
 }
}

Users can be deleted one by one from a Team.

Calls made and received by this User won't be deleted.

Path params
• team_id

  Integer
  Unique identifier for the Team.
• userid

  Integer
  Unique identifier for the User.

Request
DELETE /v1/teams/:team_id/users/:user_id

Response
Status: 200 OK

{
 "team": {
 "id": 679,
 "name": "Support USA",
 "direct_link": "https://api.aircall.io/v1/teams/679",
 "created_at": "2020-03-10T20:29:52.000Z",
 "users": []
 }
}

Calls are an essential part of how Aircall users interact with the product. Our mission is to give real-time insights to make the call experience as delightful as possible!

There are three types of calls:

1. Inbound calls: where an external person reaches an Agent.
2. Outbound calls: where an Agent starts a call from their Phone app to reach an external person.
3. Internal calls: where an Agent calls another Agent.

More information available on each type of Call at the bottom of this section.

Please refer to the User object if you are looking to start an outbound call or to dial a phone number!

Attributes
• id

  Integer
  Unique identifier for the Call.
  Please note, Call id Data Type is Int64
• sid

  String
  Call identifier from call provider
  Please note sid attribute refers to call_uuid and has same value as call_uuid. sid is only available in Call APIs
• call_uuid

  String
  Call identifier from call provider
  Please note call_uuid attribute refers to sid and has same value as sid. call_uuid is only available in Call Webhook events
• direct_link

  String
  Direct API URL.
• started_at

  Integer
  UNIX timestamp when the Call started, in UTC.
• answered_at

  Integer
  UNIX timestamp when the Call has been answered, in UTC.
• ended_at

  Integer
  UNIX timestamp when the Call ended, in UTC.
• duration

  Integer
  Duration of the Call in seconds.
  This field is computed by ended_at - started_at.
• status

  String
  Current status of the Call.
  Can be initial, answered or done.
• direction

  String
  Direction of the Call.
  Could be inbound or outbound.
• raw_digits

  String
  International format of the number of the caller or the callee. For an anonymous call, the value is anonymous.
• asset

  String
  If present, a secured webpage containing the voicemail or live recording for this Call.
  URL format is https://assets.aircall.io/[recording,voicemail]/:call_id.
• recording

  String
  If present, the direct URL of the live recording (mp3 file) for this Call. This feature can be enabled from the Aircall Dashboard, on each Number - more information in our Knowledge Base.
  This link is valid for 1 hour only.
• recording_short_url

  String
  When recording is present, a unique short URL redirecting to it.
  This link is valid for 3 hours only.
  URL format is https://short-urls.aircall.io/v1/:uuid.
• voicemail

  String
  Only present if a voicemail was left. Voicemails can only be left by callers on inbound calls. If present, the direct URL of a voicemail (mp3 file) for this Call.
  This link is valid for 1 hour only.
• voicemail_short_url

  String
  When voicemail is present, a unique short URL redirecting to it.
  This link is valid for 3 hours only.
  URL format is https://short-urls.aircall.io/v1/:uuid.
• archived

  Boolean
  Describe if Call needs follow up.
• missed_call_reason

  String
  Representing the reason why the Call was missed.
  Can be out_of_opening_hours, short_abandoned, abandoned_in_ivr, abandoned_in_classic, no_available_agent or agents_did_not_answer.
• cost

  String
  Cost of the Call in U.S. cents.
  Cost is a legacy field which has been deprecated, we might reintroduce it in the future. For more info please reach out to us on support.aircall.io.
• number

  Object
  Full Number object attached to the Call.
• user

  Object
  Full User object who took or made the Call.
• contact

  Object
  Full Contact object attached to the Call.
• assigned_to

  Object
  Full User object assigned to the Call.
• teams

  Array
  Full Teams object assigned to the Call.
  Teams are only assigned to inbound calls.
• transferred_by

  Object
  User who performed the Call transfer.
• transferred_to

  Object
  User to whom the Call was transferred to.
  If Call is transferred to a Team, this field will represent the first User of the Team. It won't be available in case of external call transfers.
• external_transferred_to

  String
  External number to which the Call was transferred to.
  Only available via call.external_transferred event
• external_caller_number

  String
  Caller Number from whom call was received.
  Only available via call.external_transferred event
• automatic_callback_call_id

  Integer
  The Call ID of the call that requested callback.
  Only available via call.created, call.answered, call.archived, call.assigned, call.hungup and call.ended Webhook events
• comments

  Array
  Notes added to this Call by Users.
• tags

  Array
  Tags added to this Call by Users.
• participants

  Array
  Participants involved in a conference call.
  Please note participants attribute is referred as conference_participants in Call APIs and as participants in call Webhook events
• ivr_options_selected

  Array
  IVR options selected in a smartflow enabled number.
  ivr_options_selected is retrievable via Call APIs using fetch timeline query param

1. Inbound calls

Inbound calls are initiated by an external person, calling an Aircall Number. Once started, calls will follow the Call distribution tree defined in the Aircall Dashboard (see our Knowledge Base).

If an Inbound call is not answered, it is then considered as missed. All missed calls will have the missed_call_reason field defined in their payload, and the answered_at field will be null.

The duration field is computed by the following: ended_at - started_at. As the ringing time is included in it, use the ended_at - answered_at calculation to get the talking time of the call!

More info on Inbound calls lifecycle in the Webhook section.

2. Outbound calls

Outbound calls are initiated by Agents from their Phone app, calling an external person.

If an Outbound call is not answered by the external person, the answered_at field will be null.

The duration field is computed by the following: ended_at - started_at. As the ringing time is included in it, use the ended_at - answered_at calculation to get the talking time of the call. If an outbound call is answered by a voicemail, it will be considered as answered (Aircall does not support Answering Machine Detection yet).

More info on Outbound calls lifecycle in the Webhook section.

Starting an outbound call from an Agent's Phone is feasible with the Start Outbound Call endpoint, defined on the User object.

3. Internal calls

Internal calls are initiated by an Agent, calling another Agent. Those calls are not rendered in the Public API.

More info on how to use Intercall calls in our Knowledge Base.

Call Comments (also called Notes)

Calls can be commented by Agents or via the Public API endpoint [POST] /v1/calls/:id/comments.

Here is the object description of a comment:

Attributes
• id

  Integer
  Unique identifier for the Comment.
• content

  String
  Content of the Comment, written by Agent or via Public API.
• posted_at

  String
  Timestamp of when the Comment was created.
• posted_by

  Object
  User object who created the Comment.
  Will be null if Comment is posted via Public API.

Endpoints
GET /v1/callsList all Calls
GET /v1/calls/:idRetrieve a Call
GET /v1/calls/searchSearch Calls
POST /v1/calls/:id/transfersTransfer a Call
POST /v1/calls/:id/commentsComment a Call
POST /v1/calls/:id/tagsTag a Call
PUT /v1/calls/:id/archiveArchive a Call
PUT /v1/calls/:id/unarchiveUnarchive a Call
POST /v1/calls/:id/pause_recordingPause recording on a Call
POST /v1/calls/:id/resume_recordingResume recording on a Call
DELETE /v1/calls/:id/recordingDelete Call recording
DELETE /v1/calls/:id/voicemailDelete Call voicemail
POST /v1/calls/:id/insight_cardsInsight Cards
GET /v1/calls/:call_id/transcriptionRetrieve a transcription
GET /v1/calls/:call_id/realtime_transcriptionRetrieve realtime transcription
GET /v1/calls/:call_id/sentimentsRetrieve sentiments
GET /v1/calls/:call_id/topicsRetrieve topics
GET /v1/calls/:call_id/summaryRetrieve a summary
GET /v1/calls/:call_id/custom_summary_resultRetrieve a custom summary result
GET /v1/calls/:call_id/action_itemsRetrieve action items
GET /v1/calls/:call_id/playbook_resultRetrieve a playbook result
GET /v1/calls/:call_id/evaluationsRetrieve call evaluations

Fetch all Calls associated to a company and their information.

By default, Calls are ordered by ascending IDs - consider using the order=desc query param if you want to get the last calls made by an account!

Only six months of history is available. Please contact our Support team on support.aircall.io to get a one-time export of calls. By default contact details are not added in response payload. To add the contact details in response set fetch_contact to true in query parameters.

Query params
• from

  String
  Set a minimal creation date for Calls (UNIX timestamp).
• to

  String
  Set a maximal creation date for Calls (UNIX timestamp).
• order

  String
  Reorder entries by created_at. Can be asc or desc.
  Default value is asc
• fetch_contact

  Boolean
  When set to true, adds contacts details in response.
• fetch_short_urls

  Boolean
  When set to true, adds short urls in response.
• fetch_call_timeline

  Boolean
  When set to true, it will ivr_options_selected at the same level of the call

Using the pagination system, you can retrieve up to 10,000 Calls. To pass over this limit, we encourage you to use the from param as much as you can!

Request
GET /v1/calls

Response
Status: 200 OK

{
 "meta": {
 "count": 20,
 "total": 2234,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": "https://api.aircall.io/v1/calls?order=asc&page=2&per_page=20",
 "previous_page_link": null
 },
 "calls": [
 {
 "id": 812,
 "sid": "CA1234567890",
 "direct_link": "https://api.aircall.io/v1/calls/812",
 "direction": "outbound",
 "status": "done",
 "missed_call_reason": null,
 "started_at": 1584998199,
 "answered_at": 1584998205,
 "ended_at": 1584998210,
 "duration": 11,
 "voicemail": null,
 "recording": null,
 "asset": null,
 "raw_digits": "+1 800-123-4567",
 "user": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US"
 },
 "contact": null,
 "archived": false,
 "assigned_to": null,
 "transferred_by": null,
 "transferred_to": null,
 "cost": "2.34",
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 ...
 }
 },
 "comments": [
 {
 "id": 735,
 "content": "Please call back this customer!",
 "posted_at": 1587994808,
 "posted_by": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "Johnn Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z"
 }
 },
 ...
 ],
 "tags": [
 {
 "id": 678,
 "name": "General Inquiries",
 "created_at": 1587995020,
 "tagged_by": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "Johnn Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z"
 }
 },
 ...
 ],
 "teams": [],
 "ivr_options_selected": [
 {
 "id": "5cb41cde-aed2-4357-a98c-e1b33d68851a",
 "title": "",
 "key": "1",
 "branch": "Default",
 "created_at": "2024-10-01T06:54:45.556Z",
 "transition_started_at": "2024-10-01T06:54:35.332Z",
 "transition_ended_at": "2024-10-01T06:54:45.513Z"
 }
 ]
 },
 {
 "id": 813,
 "direct_link": "https://api.aircall.io/v1/calls/813",
 "direction": "inbound",
 "status": "done",
 "missed_call_reason": "no_available_agent",
 "started_at": 1584998199,
 "answered_at": null,
 "ended_at": 1584998210,
 "duration": 22,
 "voicemail": null,
 "recording": null,
 "asset": null,
 "raw_digits": "+1 800-123-4567",
 "user": null,
 "contact": null,
 "archived": false,
 "assigned_to": null,
 "transferred_by": null,
 "transferred_to": null,
 "cost": "0",
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 ...
 }
 },
 "comments": [...],
 "tags": [...],
 "teams": [
 {
 "id": 678,
 "name": "Global Sales",
 "direct_link": "https://api.aircall.io/v1/teams/678",
 "created_at": "2020-03-10T08:31:43.000Z"
 }
 ],
 "ivr_options_selected": [
 {
 "id": "5cb41cde-aed2-4357-a98c-e1b33d68851a",
 "title": "",
 "key": "1",
 "branch": "Default",
 "created_at": "2024-10-01T06:54:45.556Z",
 "transition_started_at": "2024-10-01T06:54:35.332Z",
 "transition_ended_at": "2024-10-01T06:54:45.513Z"
 }
 ]
 }
 ...
 ]
}

Use this endpoint to asynchronously retrieve a Call data like duration, direction, status, timestamps, comments or tags…

To get Calls information in real time, we recommend using Calls Webhooks events - for instance to log information automatically in your database after a Call. By default contact details are not added in response payload. To add the contact details in response set fetch_contact to true in query parameters.

Path params
• id

  Integer
  Unique identifier for the Call.
• fetch_contact

  Boolean
  When set to true, adds contacts details in response.
• fetch_short_urls

  Boolean
  When set to true, adds short urls in response.
• fetch_call_timeline

  Boolean
  When set to true, it will return ivr_options_selected at the same level of the call

Request
GET /v1/calls/:id

Response
Status: 200 OK

{
 "call": {
 "id": 812,
 "sid": "CA1234567890",
 "direct_link": "https://api.aircall.io/v1/calls/812",
 "direction": "outbound",
 "status": "done",
 "missed_call_reason": null,
 "started_at": 1584998199,
 "answered_at": 1584998205,
 "ended_at": 1584998210,
 "duration": 11,
 "voicemail": null,
 "recording": null,
 "asset": null,
 "raw_digits": "+1 800-123-4567",
 "user": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US"
 },
 "contact": null,
 "archived": false,
 "assigned_to": null,
 "transferred_by": null,
 "transferred_to": null,
 "cost": "2.34",
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 ...
 }
 },
 "comments": [
 {
 "id": 735,
 "content": "Please call back this customer!",
 "posted_at": 1587994808,
 "posted_by": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "Johnn Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z"
 }
 }
 ],
 "tags": [
 {
 "id": 678,
 "name": "General Inquiries",
 "created_at": 1587995020,
 "tagged_by": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "Johnn Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z"
 }
 },
 ...
 ],
 "participants": [
 {
 "name": "John Doe",
 "id": 456,
 "type": "user"
 },
 {
 "name": "Jennifer Smith",
 "phone_number": "+33 7 49 88 29 71",
 "id": 5443,
 "type": "contact"
 },
 {
 "name": "Rafael Lopez",
 "id": 457,
 "type": "user"
 }
 ],
 "teams": [],
 "ivr_options_selected": [
 {
 "id": "5cb41cde-aed2-4357-a98c-e1b33d68851a",
 "title": "",
 "key": "1",
 "branch": "Default",
 "created_at": "2024-10-01T06:54:45.556Z",
 "transition_started_at": "2024-10-01T06:54:35.332Z",
 "transition_ended_at": "2024-10-01T06:54:45.513Z"
 }
 ]
 }
}

Search for specific Calls depending on several Query Params like user_id, phone_number or tags. Given a call transferred between A and B phone numbers, the call will not appear when filtering by A but it will for B.

Only six months of history is available. Please contact our Support team on support.aircall.io to get a one-time export of calls. By default contact details are not added in response payload. To add the contact details in response set fetch_contact to true in query parameters.

Query params
• from

  String
  Set a minimal creation date for Calls (UNIX timestamp).
• to

  String
  Set a maximal creation date for Calls (UNIX timestamp).
• order

  String
  Reorder entries by created_at. Can be asc or desc.
  Default value is asc.
• direction

  String
  Direction of the Calls.
  If specified, can be inbound or outbound.
• user_id

  Integer
  Unique ID of the User who made or received Calls.
• phone_number

  String
  The calling or receiving phone number of Calls.
• tags

  Array
  Array of Tags IDs.
  Implemented as an AND condition: Aircall will search for Calls matching all the tags present in this array.
• fetch_contact

  Boolean
  When set to true, adds contacts details in response.
• fetch_short_urls

  Boolean
  When set to true, adds short urls in response.
• fetch_call_timeline

  Boolean
  When set to true, it will return ivr_options_selected at the same level of the call

Using the pagination system, you can retrieve up to 10,000 Calls. To pass over this limit, we encourage you to use the from param as much as you can!

Request
GET /v1/calls/search

Response
Status: 200 OK

{
 "meta": {
 "count": 3,
 "total": 2,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": null,
 "previous_page_link": null
 },
 "calls": [
 {
 "id": 812,
 "sid": "CA1234567890",
 "direct_link": "https://api.aircall.io/v1/calls/812",
 "direction": "outbound",
 "status": "done",
 "missed_call_reason": null,
 "started_at": 1584998199,
 "answered_at": 1584998205,
 "ended_at": 1584998210,
 "duration": 11,
 "voicemail": null,
 "recording": null,
 "asset": null,
 "raw_digits": "+1 800-123-4567",
 "user": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US"
 },
 "contact": null,
 "archived": false,
 "assigned_to": null,
 "transferred_by": null,
 "transferred_to": null,
 "cost": "2.34",
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 ...
 }
 },
 "comments": [...],
 "tags": [...],
 "teams": [...],
 "ivr_options_selected": [...],
 },
 {
 "id": 813,
 "direct_link": "https://api.aircall.io/v1/calls/813",
 "direction": "inbound",
 "status": "done",
 "missed_call_reason": "no_available_agent",
 "started_at": 1584998199,
 "answered_at": null,
 "ended_at": 1584998210,
 "duration": 22,
 "voicemail": null,
 "recording": null,
 "asset": null,
 "raw_digits": "+1 800-123-4567",
 "user": null,
 "contact": null,
 "archived": false,
 "assigned_to": null,
 "transferred_by": null,
 "transferred_to": null,
 "cost": "0",
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 ...
 }
 },
 "comments": [...],
 "tags": [...],
 "teams": [...],
 "ivr_options_selected": [...],
 },

 ...
 ]
}

Calls can be transferred to another User, Team or phone number.

Transfers initiated through the API are only supported for scenarios where a call is transferred directly to a specific agent. The transfer won’t reroute to other agents if the original transfer target is unavailable. For more complex scenarios -such as those requiring multiple sequential transfers or fallback routing— we recommend using the "Ring to via API" widget within Smartflows. This widget allows for advanced routing logic and provides greater flexibility in managing call flows.

Only cold transfers are available via the Public API. Calls can be transferred to a single User, a single Team or a single external phone number:

• To transfer a Call to another User, provide a user ID in the request's body. A call.transferred Webhook event will be sent.

If the agent to whom the call was transferred to is not available, call will be directed to the No one answers strategy: the Unanswered call message will be played.

• To transfer a Call to a Team, provide a team ID in the request's body. A call.transferred Webhook event will be sent. When transferring a call to a team, a dispatching strategy can be specified with parameter: dispatching_strategy: The "simultaneous" strategy (default one if argument is not specified) will ring each available member simultaneously. The "random" one will ring each available member one by one. The "longest_idle" one will ring each available member one by one starting with the agent having the longest idle time.

• To transfer an Incoming Call to an external phone number, provide a phone number in the request body. When transfer is initiated, a message will be played to the caller informing them that their call is being transferred. A call.transferred Webhook event will be sent without the transferred_to field in the payload.

Transfers to external phone numbers will only work for inbound calls that have not yet been answered.

• If the transfer is not successful, a call.unsuccessful_transfer Webhook event will be sent.

Path params
• id

  Integer
  Unique identifier for the Call.

Body params
• user_id

  String
  Unique identifier of the User the Call will be transferred to.
• team_id

  String
  Unique identifier of the Team the Call will be transferred to.
• number

  String
  External phone number the Call will be transferred to.
  Format must be e164. More information in the dedicated phone numbers format section.
• dispatching_strategy

  String
  Specify dispatching strategy on team transfer, only values 'random', 'simultaneous' and 'longest_idle' are accepted. This parameter is optional if not specified 'simultaneous' strategy is implicitly used.

Only one of user_id, team_id or number parameters are allowed for each request.

Request
POST /v1/calls/:id/transfers

{
 "user_id": 456
}

Response
Status: 204 No Content

Comments (also called Notes) can be added to Calls and a Call can have a maximum of five of them. After five comments added, those requests will fail with a 400 HTTP code. A comment posted via the Public API does not have an owner.

Once a Comment is posted on a Call, it cannot be updated nor deleted.

A call.commented Webhook event will be sent every time a call is commented. More info in the Webhooks section.

Path params
• id

  Integer
  Unique identifier for the Call.

Body params
• content

  String
  Content of the Comment.
  Emojis are removed from Comments.

Request
POST /v1/calls/:id/comments

{
 "content": "Please call back this customer!"
}

Response
Status: 201 Created

Tags are created in the Dashboard by Admins and calls can be tagged by Agent from the Phone.

A call.tagged Webhook event will be sent every time a call is tagged. More info in the Webhooks section.

Path params
• id

  Integer
  Unique identifier for the Call.

Body params
• tags

  Array
  Array of Tag IDs.

Request
POST /v1/calls/:id/tags

{
 "tags": [545]
}

Response
Status: 201 Created

Missed calls non-archived will be displayed in the To-do view and can be marked as done (= archived).

👁 Archive

A call.archived Webhook event will be sent every time a call is archived. More info in the Webhooks section.

Path params
• id

  Integer
  Unique identifier for the Call.

Request
PUT /v1/calls/:id/archive

Response
Status: 200 OK

{
 "call": {
 "id": 812,
 "sid": "CA1234567890",
 "direct_link": "https://api.aircall.io/v1/calls/812",
 "direction": "outbound",
 "status": "done",
 "missed_call_reason": null,
 "started_at": 1584998199,
 "answered_at": 1584998205,
 "ended_at": 1584998210,
 "duration": 11,
 "voicemail": null,
 "recording": null,
 "asset": null,
 "raw_digits": "+1 800-123-4567",
 "user": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US"
 },
 "contact": null,
 "archived": true,
 "assigned_to": null,
 "transferred_by": null,
 "transferred_to": null,
 "cost": "2.34",
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 ...
 }
 },
 "comments": [...],
 "tags": [...],
 "teams": [...]
 }
}

Archived calls can be placed back in the To-do view of the Phone app.

Path params
• id

  Integer
  Unique identifier for the Call.

Request
PUT /v1/calls/:id/unarchive

Response
Status: 200 OK

{
 "call": {
 "id": 812,
 "sid": "CA1234567890",
 "direct_link": "https://api.aircall.io/v1/calls/812",
 "direction": "outbound",
 "status": "done",
 "missed_call_reason": null,
 "started_at": 1584998199,
 "answered_at": 1584998205,
 "ended_at": 1584998210,
 "duration": 11,
 "voicemail": null,
 "recording": null,
 "asset": null,
 "raw_digits": "+1 800-123-4567",
 "user": {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York",
 "language": "en-US",
 },
 "contact": null,
 "archived": false,
 "assigned_to": null,
 "transferred_by": null,
 "transferred_to": null,
 "cost": "2.34",
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 ...
 }
 },
 "comments": [...],
 "tags": [...],
 "teams": [...]
 }
}

When live recording is active on a Call, it can be automatically paused via the Public API.

Path params
• id

  Integer
  Unique identifier for the Call.

Request
POST /v1/calls/:id/pause_recording

Response
Status: 204 No Content

When live recording is active on a Call and has been paused, it can be automatically resumed via the Public API.

Path params
• id

  Integer
  Unique identifier for the Call.

Request
POST /v1/calls/:id/resume_recording

Response
Status: 204 No Content

Delete the recording of a specific Call. It takes between 10 and 15 minutes to delete a call recording from our servers.

Please note the recording can take up to 24 hours to be received. If it is not present, it will not be deleted. In this case retry the deletion later.

This action cannot be undone.

Important: If your account includes AI Assist or AI Assist Pro, deleting a call recording will also permanently delete the transcription and all AI-generated insights, including summaries, topics, action items, and sentiment analysis.

Check this endpoint to delete the voicemail of a Call.

Path params
• id

  Integer
  Unique identifier for the Call.

Request
DELETE /v1/calls/:id/recording

Response
Status: 200 OK

Delete the voicemail of a specific Call. It can take up to 1 minute to delete a call voicemail from our servers.

Please note the voicemail can take up to 24 hours to be received. If it is not present, it will not be deleted. In this case retry the deletion later.

This action cannot be undone.

Check this endpoint to delete the live recording of a Call.

Path params
• id

  Integer
  Unique identifier for the Call.

Request
DELETE /v1/calls/:id/voicemail

Response
Status: 200 OK

Insight Cards display custom data to Agents in their Phone apps during ongoing Calls.

Insight cards will only be seen on ongoing calls and are not stored after Calls are over.

Three types of content can be sent in an Insight Card:

• title is a large text. It should describe the name of a custom app.
• shortText is a normal line in the Insight Card section.
• user is a user card in the Insight Card section displaying the name and availability of the user.

Please note Insight Card payload size should be less than 10KB.

  More info on what Insight Cards are in our Knowledge Base.

👁 Insight Card

Path params
• id

  Integer
  Unique identifier for the Call.

Body params
• contents

  Array
  Represents lines displayed on the Insight Card.
  Please check the following tables to see how to structure this object.

Title
• type

  String
  Type of line. Should be title.
  Mandatory field. Possible values are title, shortText or user (check other tables).
• text

  String
  Text displayed in the line of the Insight Card.
  Mandatory field.
• link

  String
  Transform the line in a link.

Short text
• type

  String
  Type of line. Should be shortText.
  Mandatory field. Possible values are title, shortText or user (check other tables).
• text

  String
  Text displayed in the title field of the Insight Card.
  Mandatory field.
• link

  String
  Transform the line in a link.
• label

  String
  The text field can be preceded by a label if one is provided.

User
• type

  String
  Type of line. Should be user.
  Mandatory field. Possible values are title, shortText or user (check other tables).
• label

  String
  The text that precedes the user card.
  Mandatory field.
• user_id

  Integer
  The id of the user to be displayed.
  Mandatory field.

Request
POST /v1/calls/:id/insight_cards

{
 "contents": [
 {
 "type": "title",
 "text": "My Custom CRM",
 "link": "https://my-custom-crm.com"
 },
 {
 "type": "shortText",
 "label": "Account ID",
 "text": "6789",
 "link": "https://my-custom-crm.com/6789"
 },
 {
 "type": "shortText",
 "label": "Company name",
 "text": "Acme Inc."
 },
 {
 "type": "user",
 "label": "Account Owner",
 "user_id": 12345
 }
 ]
}

Response
Status: 201 Created

Dialer Campaigns refer to the Power Dialer feature. More info on how it works in our Knowledge Base.

Dialer Campaigns are composed of one or several phone numbers.

👁 Dialer Campaign

Attributes
• id

  Integer
  Unique identifier for the Dialer Campaign.
• number_id

  String
  Set if the Dialer Campaign is associated to a Number.
• created_at

  String
  Dialer campaign's creation date, in UTC.

Phone number attributes
• id

  Integer
  Unique identifier for the phone number.
• number

  String
  The actual phone number.
• called

  Boolean
  true if the number was called by the User.
• created_at

  String
  Phone number's creation date, in UTC.

Endpoints
GET /v1/users/:user_id/dialer_campaignRetrieve a Dialer Campaign
POST /v1/users/:user_id/dialer_campaignCreate a Dialer Campaign
DELETE /v1/users/:user_id/dialer_campaignDelete a Dialer Campaign
GET /v1/users/:user_id/dialer_campaign/phone_numbersRetrieve phone numbers
POST /v1/users/:user_id/dialer_campaign/phone_numbersAdd phone numbers
DELETE /v1/users/:user_id/dialer_campaign/phone_numbers/:idDelete a phone number

A User can have only one active Dialer Campaign.

To list all the phone numbers associated to it, please refer to the Retrieve phone numbers endpoint.

Path params
• user_id

  Integer
  Unique identifier for the User.

Request
GET /v1/users/:user_id/dialer_campaign

Response
Status: 200 OK

{
 "id": 75555,
 "number_id": null,
 "created_at": "2020-03-21T20:20:04.000Z"
}

Create an active Dialer Campaign for a User.

A User can have only one active Dialer Campaign.

Path params
• user_id

  Integer
  Unique identifier for the User.

Body params
• phone_numbers

  Array
  Array of valid phone numbers.
  Mandatory field. Must include at least one valid phone number.

Request
POST /v1/users/:user_id/dialer_campaign

{
 "phone_numbers": ["+19161112222", "+18001112222"]
}

Response
Status: 204 No Content

Dialer Campaign created by Agents or via the Public API can be deleted.

Phone numbers associated to it will be destroyed as well.

Path params
• user_id

  Integer
  Unique identifier for the User.

Request
DELETE /v1/users/:user_id/dialer_campaign

Response
Status: 204 No Content

A Dialer Campaign is made of a list of phone numbers. Those lists can be retrieved thanks to the following request.

Path params
• user_id

  Integer
  Unique identifier for the User.

Request
GET /v1/users/:user_id/dialer_campaign/phone_numbers

Response
Status: 200 OK

{
 "numbers": [
 {
 "id": 4671488,
 "number": "+18002112223",
 "called": false,
 "created_at": "2020-03-20T20:42:57.000Z"
 },
 {
 "id": 4671489,
 "number": "+18003112224",
 "called": false,
 "created_at": "2020-03-20T20:42:57.000Z"
 },
 {
 "id": 4671490,
 "number": "+18004112225",
 "called": false,
 "created_at": "2020-03-20T20:42:57.000Z"
 }
 ]
}

Phone numbers can be added to an Agent's active Dialer Campaign.

Those phone numbers will be automatically appended in the Phone app.

Path params
• user_id

  Integer
  Unique identifier for the User.

Body params
• phone_numbers

  Array
  Array of valid phone numbers.
  Mandatory field. Must include at least one valid phone number.

Request
POST /v1/users/:user_id/dialer_campaign/phone_numbers

{
 "phone_numbers": [
 "+19161112222",
 "+18001112222"
 ]
}

Response
Status: 204 No Content

Delete one phone number from a Dialer Campaign.

Path params
• user_id

  Integer
  Unique identifier for the User.
• id

  Integer
  Unique identifier for the phone number.

Request
DELETE /v1/users/:user_id/dialer_campaign/phone_numbers/:id

Response
Status: 204 No Content

Users (Admins) can buy Numbers from the Dashboard. They can then update the call distribution order, upload custom Music & Messages, enable or disable call recording...

Attributes
• id

  Integer
  Unique identifier for the Number.
• direct_link

  String
  Direct API URL.
• name

  String
  The name of the Number.
• digits

  String
  International format of the Number.
• e164_digits

  String
  Number in E.164 format
  Number in following format [+][country code][area code][local phone number] i.e. without any space or special characters e.g. +18001234567, +33176360695. Only available in Webhook events
• created_at

  String
  Timestamp when the Number was created, in UTC.
• country

  String
  ISO 3166-1 alpha-2 country code of the Number.
  Listed on Wikipedia.
• time_zone

  String
  Number's time zone, set in the Dashboard.
  More details on Timezones here.
• open

  Boolean
  Deprecated. This field is no longer updated for Smartflows numbers and may return outdated or incorrect values.
  Availability should now be determined based on the Time Rule widget.
• availability_status

  String
  Returns the availability status based on the first Time Rule widget in the number flow.
  Possible values: open, custom, closed. The availability status setting has been deprecated. Business Hours are now managed via the Time Rule widget and holidays or special dates via the Date Rule widget.
• is_ivr

  Boolean
  Deprecated. This field is no longer supported and may return outdated or incorrect value.
  An IVR can now be configured directly within the Smartflows Editor for any number.
• live_recording_activated

  Boolean
  Whether a Number has live recording activated or not.
  More information on our Knowledge Base.
• users

  Array
  List of Users linked to this Number.
• priority

  Integer
  Priority level of the number used during routing of the calls
  Can be null, 0 (no priority) or 1 (top priority). Default value is null
• messages

  Object
  URL to Number's music & messages files.
  See Music & Messages section below for more details.

Music and Messages

The messages object, present for each Number, represents the different audio files played during a call.

A custom file can be used for any of the following field by uploading it on a server with a public URL to it. Check our encoding recommendations on our Knowledge Base first!

Attributes
• welcome

  String
  Returns the value from the first Audio widget found in the number flow, as long as it is not located inside an IVR widget (this is not supported and will be treated as an invalid request).
• waiting

  String
  Returns the value (URL) for the Music on hold setting at the number level.
• ringing_tone

  String
  Returns the value (URL) of the first Waiting Experience widget found in the number flow.
• unanswered_call

  String
  Deprecated. Updating this will not change any behavior.
  The concept of unanswered call was replaced by the Voicemail widget.
• after_hours

  String
  Returns the value (URL) of the first Voicemail widget found in the “At any other time” branch of the number flow. If none exists, returns the URL for the first Audio widget in that branch.
• ivr

  String
  Returns the value (URL) of the first IVR widget instructions message found in the number flow.
• voicemail

  String
  Returns the value (URL) of the first Voicemail widget found in the number flow.
• closed

  String
  Deprecated. This field is no longer supported and may return outdated or incorrect value.
  The concept of Open/Closed lines was replaced by the Time Rule widget.
• callback_later

  String
  Deprecated. This field is no longer supported and may return outdated or incorrect value.

Endpoints
GET /v1/numbersList all Numbers
GET /v1/numbers/:idRetrieve a Number
PUT /v1/numbers/:idUpdate a Number
GET /v1/numbers/:id/registration_statusRegistration Status
GET /v1/numbers/:id/templatesList WhatsApp Templates
GET /v1/numbers/:id/whatsapp_statusGet WhatsApp Line Status

Fetch all Numbers associated to a company and their information.

Query params
• from

  String
  Set a minimal creation date for Numbers (UNIX timestamp).
• to

  String
  Set a maximal creation date for Numbers (UNIX timestamp).
• order

  String
  Reorder entries by created_at. Can be asc or desc.
  Default value is asc

Pagination params can be used on this request.

Request
GET /v1/numbers

Response
Status: 200 OK

{
 "meta": {
 "count": 3,
 "total": 2,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": null,
 "previous_page_link": null
 },
 "numbers": [
 {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 "welcome": "https://example.com/welcome.mp3",
 "waiting": "https://example.com/waiting_music.mp3",
 "ivr": "https://example.com/ivr_message.mp3",
 "voicemail": "https://example.com/voicemail.mp3",
 "closed": "https://example.com/closed_message.mp3",
 "callback_later": "https://example.com/callback_later.mp3",
 "unanswered_call": "https://example.com/unanswered_call.mp3",
 "after_hours": "https://example.com/closed_message.mp3",
 "ringing_tone": "https://example.com/waiting_music.mp3"
 }
 },
 {
 "id": 2345,
 "direct_link": "https://api.aircall.io/v1/numbers/2345",
 "name": "UK office",
 "digits": "+44 20 0000 0000",
 "created_at": "2020-01-04T19:28:58.000Z",
 "country": "GB",
 "time_zone": "Europe/London",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": false,
 "priority": null,
 "messages": {
 "welcome": "https://example.com/welcome.mp3",
 "waiting": "https://example.com/waiting_music.mp3",
 "ivr": "https://example.com/ivr_message.mp3",
 "voicemail": "https://example.com/voicemail.mp3",
 "closed": "https://example.com/closed_message.mp3",
 "callback_later": "https://example.com/callback_later.mp3",
 "unanswered_call": "https://example.com/unanswered_call.mp3",
 "after_hours": "https://example.com/closed_message.mp3",
 "ringing_tone": "https://example.com/waiting_music.mp3"
 }
 }
 ]
}

Retrieve details of a specific Number.

Path params
• id

  Integer
  Unique identifier for the Number.

Request
GET /v1/numbers/:id

Response
Status: 200 OK

{
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 "welcome": "https://example.com/welcome.mp3",
 "waiting": "https://example.com/waiting_music.mp3",
 "ivr": "https://example.com/ivr_message.mp3",
 "voicemail": "https://example.com/voicemail.mp3",
 "closed": "https://example.com/closed_message.mp3",
 "callback_later": "https://example.com/callback_later.mp3",
 "unanswered_call": "https://example.com/unanswered_call.mp3",
 "after_hours": "https://example.com/closed_message.mp3",
 "ringing_tone": "https://example.com/waiting_music.mp3"
 },
 "users": [
 {
 "id": 456,
 "direct_link": "https://api.aircall.io/v1/users/456",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "created_at": "2019-12-29T10:03:18.000Z",
 "time_zone": "America/New_York"
 }
 ]
 }
}

Updates a specific Number. Response will be the updated Number.

Path params
• id

  Integer
  Unique identifier for the Number.

Body params
• name

  String
  Can't be empty or null.
• availability_status

  String
  Updates the first Time Rule widget in the call flow. This widget has replaced the legacy availability setting.
  The availability status setting has been deprecated. Business Hours are now managed with the Time Rule widget, and holidays or special dates with the Date Rule widget.
• is_ivr

  Boolean
  Deprecated. Updating this will not change any behavior.
  This setting has been deprecated as the distinction between Classic and IVR widget numbers is no longer applicable. An IVR can now be configured directly within the Smartflows Editor for any number.
• live_recording_activated

  Boolean
  Set to true if you want to enable call recording on the specified Number. It will enable both inbound AND outbound at the same time.
  More information on our Knowledge Base.
• priority

  Integer
  Can be null, 0 (no priority) or 1 (top priority). Default value is null
• messages

  Object
  See Update a Number's Music & Messages section.

Request
PUT /v1/numbers/:id

{
 "name": "French Office UPDATED"
}

Response
Status: 200 OK

{
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office UPDATED",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 "welcome": "https://example.com/welcome.mp3",
 "waiting": "https://example.com/waiting_music.mp3",
 "ivr": "https://example.com/ivr_message.mp3",
 "voicemail": "https://example.com/voicemail.mp3",
 "closed": "https://example.com/closed_message.mp3",
 "callback_later": "https://example.com/callback_later.mp3",
 "unanswered_call": "https://example.com/unanswered_call.mp3",
 "after_hours": "https://example.com/closed_message.mp3",
 "ringing_tone": "https://example.com/waiting_music.mp3"
 },
 "users": [
 {
 "id": 3456,
 "direct_link": "https://api.aircall.io/v1/users/3456",
 "created_at": "2019-12-29T10:03:18.000Z",
 "name": "John Doe",
 "email": "john.doe@aircall.io",
 "available": true,
 "availability_status": "available",
 "time_zone": "America/New_York"
 }
 ]
 }
}

A Number's Music & Messages URLs can be updated by using the same request as to update a Number. Response will be the targeted Number, with updated messages section.

Query params
• id

  Integer
  Unique identifier for the Number.

Body params
• messages

  Object
  Check the messages object format below.

Messages object
• welcome

  String
  Updates the first Audio widget found in the number flow, as long as it is not located inside an IVR widget (this is not supported and will be treated as an invalid request).
  Must be a valid public URL.
• waiting

  String
  Updates the Music on hold setting at the number level.
  Must be a valid public URL.
• ivr

  String
  Updates the instructions message of the first IVR widget found in the number flow, even if multiple IVR widgets are present.
  Must be a valid public URL.
• voicemail

  String
  Updates all Voicemail widget in the number flow with the new message.
  Must be a valid public URL.
• closed

  String
  Deprecated. Updating this will not change any behavior.
  Must be a valid public URL. The concept of Open/Closed lines was replaced by the Time Rule widget
• callback_later

  String
  Deprecated. Updating this will not change any behavior.
  Must be a valid public URL.
• unanswered_call

  String
  Deprecated. Updating this will not change any behavior.
  The concept of unanswered call was replaced by the Voicemail widget.
• after_hours

  String
  Updates the first Voicemail widget found in the “At any other time” branch. If none exists, updates the first Audio widget in that branch.
  Must be a valid public URL.
• ringing_tone

  String
  Updates all Waiting Music files (Waiting Experience widget) found in the number flow.
  Must be a valid public URL.

For more information on each messages field, please refer to the Number object overview.

Request
PUT /v1/numbers/:id

{
 "messages": {
 "welcome": "https://example.com/welcome_NEW.mp3"
 }
}

Response
Status: 200 OK

{
 "number": {
 "id": 1234,
 "direct_link": "https://api.aircall.io/v1/numbers/1234",
 "name": "French Office UPDATED",
 "digits": "+33 1 76 11 11 11",
 "created_at": "2020-01-02T11:41:01.000Z",
 "country": "FR",
 "time_zone": "Europe/Paris",
 "open": true,
 "availability_status": "custom",
 "is_ivr": true,
 "live_recording_activated": true,
 "priority": null,
 "messages": {
 "welcome": "https://example.com/welcome.mp3",
 "waiting": "https://example.com/waiting_music.mp3",
 "ivr": "https://example.com/ivr_message.mp3",
 "voicemail": "https://example.com/voicemail.mp3",
 "closed": "https://example.com/closed_message.mp3",
 "callback_later": "https://example.com/callback_later.mp3",
 "unanswered_call": "https://example.com/unanswered_call.mp3",
 "after_hours": "https://example.com/closed_message.mp3",
 "ringing_tone": "https://example.com/waiting_music.mp3"
 },
 "users": [
 ...
 ]
 }
}

Fetch compliance status for:

• A2P10DLC messaging registration in the US
• Toll-free messaging registration in the US & Canada

for a specific Number.

Path params
• id

  Integer
  Unique identifier for the Number.

Headers
• content-type

  string
  Content type of the request. It will be application/json.

Send message function & number configuration for such use case can be found under “Message” section here.

Request
GET /v1/numbers/:id/registration_status

Response
Status: 200 OK

{
 "status": "approved" 
 "updatedAt": "2024-05-07T10:42:55.676Z",
}

The Conversation Intelligence object is a representation of different AI-generated entities such as Key Topics, Call Transcription, Sentiment Analysis etc.

Conversation Intelligence object is not updatable nor destroyable via Aircall Public API.

The Conversation Intelligence object and APIs can only be retrieved if a company has signed up for Aircall AI Package with AI Assist or AI Assist Pro.

Please note the attributes of Conversation Intelligence Object are different for Real-time Transcription webhook event. Please view the attribute lists below.

Attributes list for AI entities (Transcription, Sentiment, Topics, Summary, Action Items, Playbook Results)

Attributes
• id

  Integer
  Unique identifier for the Conversation Intelligence event.
• call_id

  String
  Unique identifier for the call.
  For sentiment.created event id and call_id will have same value
• call_uuid

  String
  Unique identifier for the call.
  Available via Webhook events only. Not available for action_item.created when is created in the Agent Workspace
• number_id

  Integer
  Unique identifier for the number.
  This field is only applicable for transcription.created event. Not available for action_item.created when is created in the Agent Workspace
• participants

  Array
  Participants involved in the call. Not available for [action_item.created]
• type

  String
  Type of the call. It will be 'call' or 'voicemail'.
  This field is only applicable for transcription.created event and to retrieve a transcription
• content

  string or Array or Object
  The Content of the Conversation Intelligence object
  This field is applicable for retrieve a transcription
  This field is applicable for retrieve topics
  This field is applicable for retrieve a summary
  This field is applicable for retrieve an action item
• call_created_at

  String
  Timestamp when the call was created, in UTC.
  This field is applicable for retrieve a transcription
• created_at

  String
  Timestamp when the topics were created, in UTC.
  This field is applicable for retrieve topics
  This field for retrieve a summary
  This field for retrieve an action item
• created_by

  Integer
  Unique identifier for the user that created the action item.
  This field is applicable for retrieve action items
• updated_at

  String
  Timestamp when the action item was updated, in UTC.
  This field is applicable for retrieve action items
• updated_by

  Integer
  Unique identifier for the user that updated the action item.
  This field is applicable for retrieve action items
• ai_generated

  Boolean
  Whether the content has been generated by AI or not.
  This field is applicable for retrieve action items
• adherence_score

  Number
  Adherence score of the playbook
  This field is only applicable for playbook_result
• playbook

  Object
  Playbook definition
  This field is only applicable for playbook_result
• playbook_result_topics

  Array
  An array containing the name of the playbook topic and the result associated
  This field is only applicable for playbook_result
• custom_summary

  Object
  Custom summary metadata containing the template name
  This field is only applicable for custom_summary_result
• language

  String
  Language code of the custom summary
  This field is only applicable for custom_summary_result
• summary_template_results

  Array
  Array of Summary Template Result objects
  This field is only applicable for custom_summary_result

Attributes list for realtime_transcription.utterances_received webhook event

Attributes
• id

  String
  UUID of the call (matches call.uuid).
• call

  Object
  Call information object
• call.id

  Integer
  Aircall call ID - best-effort delivery (may be undefined)
• call.uuid

  String
  Unique UUID for the call
• call.number_id

  Integer
  Aircall number/line ID (e.g., 67567). This is an internal ID, not a phone number string like +1234567890
• call.direction

  String
  Call direction: inbound or outbound
• utterances

  Array
  Array of utterance objects (currently single element)
• utterances.participant_type

  String
  internal or external
• utterances.user_id

  Integer
  User ID when participant is internal. Only present when participant_type is internal
• utterances.timestamp

  Integer
  Unix timestamp (milliseconds) when utterance was received
• utterances.duration_ms

  Integer
  Duration of the utterance in milliseconds
• utterances.text

  String
  Transcribed text of the utterance
• utterances.language

  String
  The language of the transcribed text. The format is IETF language tag (e.g., en-US, fr-FR, es-ES)

Attributes list for Summary Template Result (used in custom_summary.result_created and custom_summary.result_updated webhook events)

The updated_at and updated_by fields are only present when a result has been manually updated after its initial creation. This is the key difference between custom_summary.result_created and custom_summary.result_updated webhook events.

Attributes
• name

  String
  Name of the summary field
• type

  String
  Field type
• content

  String
  The actual summary content
• ai_generated

  Boolean
  Whether the content was AI-generated (true) or manually edited (false)
• created_at

  String
  ISO 8601 timestamp when the result was created
• updated_at

  String
  ISO 8601 timestamp when the result was last updated
  Only present if the result has been updated
• updated_by

  Integer
  User ID who made the update
  Only present if the result has been manually updated

The Call Evaluations object is a subset of the Conversation Intelligence Object that represents quality assurance evaluation data for calls. It contains scoring information, feedback, and detailed question-level assessments.

Call Evaluations object is not updatable nor destroyable via Aircall Public API.

The Call Evaluations object and APIs can only be retrieved if a company has signed up for Aircall AI Package with AI Assist or AI Assist Pro.

Please note the attributes of Call Evaluations Object are different between the API endpoint and webhook events. The retrieve call evaluations endpoint returns the full object, while the call_evaluation.created and call_evaluation.updated webhook events return a simplified subset.

Attributes list for Call Evaluations Object

Attributes
• id

  Integer
  Unique identifier for the Call Evaluation event
  Only available for retrieve call evaluations
• call_id

  Integer
  Unique identifier for the call
• ai_generated

  Boolean
  Whether this evaluation was AI-generated or manually created
• created_at

  String
  ISO 8601 timestamp when the evaluation was created
• updated_at

  String
  ISO 8601 timestamp when the evaluation was last updated
• created_by

  Integer
  User ID of the creator
  Can be null if AI-generated
• updated_by

  Integer
  User ID of the last updater
  Can be null if AI-generated or never updated
• reviewed_at

  String
  ISO 8601 timestamp when the evaluation was reviewed
  Only available for retrieve call evaluations. Can be null if not yet reviewed
• evaluations

  Array
  Array of Evaluation objects containing the full assessment
  Only available for retrieve call evaluations. See Evaluation Object attributes below
• scorecard_name

  String
  Name of the scorecard used for the evaluation
  Only available for call_evaluation.created and call_evaluation.updated webhook events
• reviewee_id

  Integer
  The agent/user being evaluated
  Only available for call_evaluation.created and call_evaluation.updated webhook events
• reviewer_id

  Integer
  User who performed the evaluation
  Only available for call_evaluation.created and call_evaluation.updated webhook events. Can be null if AI-generated

Attributes list for Evaluation Object (within the evaluations array, only available for retrieve call evaluations)

Attributes
• scorecard

  Object
  Scorecard information
  Contains name and description
• scorecard.name

  String
  Name of the scorecard used
• scorecard.description

  String
  Description of the scorecard
• feedback

  String
  Overall feedback for the call
• reviewee_user_id

  Integer
  The agent/user being evaluated
  First agent on call for AI-generated evaluations
• reviewer_user_id

  Integer
  User who performed the evaluation
  null if AI-generated
• score

  Object
  Overall score information
  Contains score_points, total_points, and normalized_score
• score.score_points

  Integer
  Points achieved
• score.total_points

  Integer
  Maximum possible points
• score.normalized_score

  Integer
  Normalized score (0-100 scale)
• categories

  Array
  Array of Category objects
  See Category Object attributes below

Attributes list for Category Object (within the categories array)

Attributes
• name

  String
  Name of the evaluation category
• order

  Integer
  Display order of the category
• score

  Object
  Category score information
  Same structure as overall score
• score.score_points

  Integer
  Points achieved in this category
• score.total_points

  Integer
  Maximum possible points in this category
• score.normalized_score

  Integer
  Normalized score for this category (0-100 scale)
• questions

  Array
  Array of Question objects
  See Question Object attributes below

Attributes list for Question Object (within the questions array)

Attributes
• text

  String
  The question text
• type

  String
  Question type
  BINARY or RATING
• order

  Integer
  Display order of the question
• strictness

  Integer
  Question strictness level
  0-2
• ai_enabled

  Boolean
  Whether AI evaluation is enabled for this question
• answer

  String
  Answer value
  YES/NO/N/A for BINARY; EXCELLENT/GOOD/FAIR/POOR/VERY_POOR/N/A for RATING.
• score

  Object
  Question score information
  Same structure as overall score
• score.score_points

  Integer
  Points achieved for this question
• score.total_points

  Integer
  Maximum possible points for this question
• score.normalized_score

  Integer
  Normalized score for this question (0-100 scale)
• feedback

  String
  Specific feedback for this question

Use this endpoint to retrieve a transcription after a call is ended.

To get transcription for a call in real time, we recommend you to subscribe to transcription.created event to be notified about availability of Transcription for a call. This can be useful if you want to be notified about when transcription is generated and will like to use API to retrieve and store it. Also, please note Transcription API doesn't contains any info related to the Calls. Please use Calls APIs to retrieve call details.

Retrieval of realtime transcriptions requires the AI Assist Pro package to be enabled for your company. Only calls with available transcriptions will return data. To get realtime transcription events, subscribe to realtime_transcription.utterances_received event.

Path params
• call_id

  Integer
  Unique identifier for the Call.

Query params
• mode

  String
  Transcription mode. Can be async or realtime.

Request
GET /v1/calls/:call_id/transcription

Response
Status: 200 OK

{
 "transcription": {
 "id": 68271,
 "call_id": 5237603,
 "call_created_at": "2024-07-26T13:30:54.000Z",
 "type": "call",
 "content": {
 "language": "en",
 "utterances": [
 {
 "start_time": 12.54,
 "end_time": 13.8,
 "text": "Okay,",
 "participant_type": "external",
 "phone_number": "+33679198915"
 },
 {
 "start_time": 238.08,
 "end_time": 239.48,
 "text": "Okay, I guess that's enough.",
 "participant_type": "internal",
 "user_id": 123
 }
 ]
 }
 }
}

realtime_transcription endpoint will be deprecated soon. Please migrate to transcription endpoint.

Use this endpoint to retrieve a realtime transcription of a specific call, including transcribed text from each participant with timestamps and associated metadata.

This endpoint requires the AI Assist Pro package to be enabled for your company. Only calls with available transcriptions will return data. Please note Realtime Transcription API doesn't contain any info related to the Calls. Please use Calls APIs to retrieve call details.

Path params
• call_id

  Integer
  Unique identifier for the Call.

Request
GET /v1/calls/:call_id/realtime_transcription

Response
Status: 200 OK

{
 "call_id": 5237603,
 "call_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "content": {
 "language": "en-US",
 "utterances": [
 {
 "duration_ms": 3500,
 "participant_type": "internal",
 "text": "Hello, thank you for calling. How can I help you today?",
 "timestamp": 1633024800000,
 "user_id": 12345
 },
 {
 "duration_ms": 4200,
 "participant_type": "external",
 "text": "Hi, I'm calling about my recent order. It hasn't arrived yet.",
 "timestamp": 1633024803500,
 },
 {
 "duration_ms": 2800,
 "participant_type": "internal",
 "text": "I understand. Let me check that for you right away.",
 "timestamp": 1633024807700,
 "user_id": 12345
 }
 ]
 }
}

Use this endpoint to retrieve sentiments.

Path params
• call_id

  Integer
  Unique identifier for the Call.

Request
GET /v1/calls/:call_id/sentiments

Response
Status: 200 OK

{
 "sentiment": {
 "id": 5237603,
 "call_id": 5237603,
 "participants": [
 {
 "phone_number": "+33679198915",
 "value": "POSITIVE",
 "type": "external"
 }
 ]
 }
}

Use this endpoint to retrieve topics from a call.

Path params
• call_id

  Integer
  Unique identifier for the Call.

Request
GET /v1/calls/:call_id/topics

Response
Status: 200 OK

{
 "topic": {
 "id": 786,
 "call_id": 123,
 "created_at": "2024-08-27T10:54:16.000Z",
 "content": [
 "payment",
 "billing"
 ]
 }
}

Use this endpoint to retrieve summary from a call.

Path params
• call_id

  Integer
  Unique identifier for the Call.

Request
GET /v1/calls/:call_id/summary

Response
Status: 200 OK

{
 "summary": {
 "id": 974,
 "call_id": 786,
 "created_at": "2024-08-27T10:54:16.000Z",
 "content": "Short summary of the call"
 }
}

Use this endpoint to retrieve the custom summary result for a specific call.

This endpoint requires the AI Assist Pro package to be enabled for your company.

Path params
• call_id

  Integer
  Unique identifier for the Call.

Request
GET /v1/calls/:call_id/custom_summary_result

Response
Status: 200 OK

{
 "id": 999,
 "custom_summary": {
 "name": "BANT"
 },
 "language": "en",
 "call_id": "12345",
 "number_id": 789,
 "summary_template_results": [
 {
 "name": "Budget",
 "type": "OPTIONS",
 "content": "content",
 "ai_generated": true,
 "created_at": "2024-08-28T12:49:12.000Z"
 },
 {
 "name": "Authority",
 "type": "DISCOVERY",
 "content": "content",
 "ai_generated": false,
 "created_at": "2024-08-28T12:49:12.000Z",
 "updated_at": "2025-08-28T12:49:12.000Z",
 "updated_by": 123
 }
 ]
}

Use this endpoint to get action items from a call.

Path params
• call_id

  Integer
  Unique identifier for the Call.

Request
GET /v1/calls/:call_id/action_items

Response
Status: 200 OK

{
 "call_id": 123,
 "action_items: [{
 "ai_generated": false,
 "content": "Send email to customer next week with updated offer details.",
 "created_at": "2024-08-28T12:32:16.000Z",
 "created_by": 74550,
 "id": 1,
 "updated_at": "2024-08-28T12:49:12.000Z",
 "updated_by": 74550
 }, {
 "ai_generated": true,
 "content": "Schedule meeting for next monday to discuss final agreement.",
 "created_at": "2024-08-27T10:54:16.000Z",
 "id": 2
 }]
}

Use this endpoint to get playbook result from a call. You'll need to subscribe to AI Assist Pro to generate and to call this endpoint.

Path params
• call_id

  Integer
  Unique identifier for the Call.
• fetch_playbook

  Boolean
  When set to true, adds playbook details in response.

Request
GET /v1/calls/:call_id/playbook_result

Response
Status: 200 OK

{
 "id": 1,
 "call_id": 974,
 "user_id": 786,
 "number_id": 35550,
 "adherence_score": 0,
 "playbook_result_topics": [
 {
 "name": "Budget",
 "result": "content"
 },
 {
 "name": "Authority",
 "result": "content"
 },
 {
 "name": "Need",
 "result": "content"
 },
 {
 "name": "Timing",
 "result": "content"
 }
 ],
 "created_at": 1753095768.
 "playbook": {
 "id": 2,
 "name": "BANT",
 "language": "en"
 }
}

Use this endpoint to retrieve the evaluations for a specific call.

This endpoint requires the AI Assist Pro or AI Assist package to be enabled for your company.

This endpoint returns the Call Evaluations Object. Please refer to the Call Evaluations Object definition for full attribute details.

Path params
• call_id

  Integer
  Unique identifier for the Call.

Request
GET /v1/calls/:call_id/evaluations

Response
Status: 200 OK

{
 "id": 456,
 "call_id": 456,
 "ai_generated": false,
 "created_at": "2025-11-18T10:00:00.000Z",
 "updated_at": "2025-11-18T10:30:00.000Z",
 "created_by": 101,
 "updated_by": 102,
 "reviewed_at": "2025-11-18T10:05:00.000Z",
 "evaluations": [
 {
 "scorecard": {
 "name": "Customer Service Evaluation",
 "description": "Standard customer service evaluation scorecard"
 },
 "feedback": "Great job handling the customer!",
 "reviewee_user_id": 456,
 "reviewer_user_id": 789,
 "score": {
 "score_points": 18,
 "total_points": 20,
 "normalized_score": 90
 },
 "categories": [
 {
 "name": "Communication Skills",
 "order": 1,
 "score": {
 "score_points": 18,
 "total_points": 20,
 "normalized_score": 90
 },
 "questions": [
 {
 "text": "Did the agent greet the caller?",
 "type": "BINARY",
 "order": 1,
 "strictness": 1,
 "ai_enabled": true,
 "answer": "YES",
 "score": {
 "score_points": 10,
 "total_points": 10,
 "normalized_score": 100
 },
 "feedback": "Agent greeted warmly"
 },
 {
 "text": "How was the agent's tone?",
 "type": "RATING",
 "order": 2,
 "strictness": 2,
 "ai_enabled": false,
 "answer": "GOOD",
 "score": {
 "score_points": 8,
 "total_points": 10,
 "normalized_score": 80
 },
 "feedback": "Tone was professional throughout"
 }
 ]
 }
 ]
 }
 ]
}

The Content object is a representation of the content of Conversation Intelligence

Content are not updatable nor destroyable via Aircall Public API.

Content information is only present in transcriptions, summaries, topics, action items and it can be accessed inside the conversation intelligence object

Please note the attributes of Content Object are different for each type of Conversation Intelligence.

Attributes list for Transcription Object

Attributes
• content

  Object
  The content of the transcription
• language

  String
  The language of the transcription. Possible values: en, en-US, en-GB, en-AU, fr-FR, fr, es-ES, es, de-DE, de, nl-NL, nl, it-IT, it
• utterances

  Array
  Sentences of the transcription
• utterances.start_time

  Number
  Time when the sentence started
• utterances.end_time

  Number
  Time when the sentence ended
• utterances.text

  String
  The sentence content
• utterances.participant_type

  String
  The type of participant external or internal
• utterances.user_id

  Number
  The user_id when it's an internal participant
• utterances.phone_number

  String
  The phone number when it's an external participant

Attributes list for Summary Object

Attributes
• content

  String
  The summary content

Attributes list for Topics Object

Attributes
• content

  Array
  An array of string with all topics of the call

Attributes list for Action Items Object

Attributes
• content

  String
  The action item content

Messages including SMS, MMS, and WhatsApp are an essential part of how Aircall users interact with the product. Our mission is to make the communication experience as delightful as possible!

There are two types of messages:

• Inbound Messages: when a user receives a message from an external person.
• Outbound Messages: when a user sends a message to an external person.

Message objects are neither updatable nor destroyable via Aircall Public API.

The attributes specific for whatsapp won’t be present if this is an SMS or MMS.

Attributes
• id

  String
  A unique identifier for the message.
• direct_link

  String
  Direct API URL.
• direction

  String
  Direction of the Message.
  Could be inbound or outbound.
• external_number

  String
  The phone number associated with the message, including the country code.
• body

  String
  The content or text of the message.
• status

  String
  The status of the message.
• raw_digits

  String
  International format of the number.
• media_details

  String
  A list of media files attached to the message.
  for each media_details, file_name string , file_type stringand presigned_url string fields are also required.
• created_at

  String
  Timestamp when the Message was created, in UTC.
• updated_at

  String
  Timestamp when the Message was updated for the last time, in UTC.
• sent_at

  String
  Timestamp when the Message was sent, in UTC.
• channel

  String
  Channel of the message (null=sms or mms, whatsapp).
• template_content

  String
  Template content of the message for whatsapp template message.
• type

  String
  Message type for whatsapp message.
• metadata

  String
  Metadata of the whatsapp message.
• parent_id

  String
  Parent message id in case of reply for whatsapp message.
• whatsapp_message_category

  String
  Template category of whatsapp message send to customer - marketing, utility, authentication.
• whatsapp_message_type

  String
  whatsapp message type for billing - regular, free_entry_point, free_customer_serivce.
• recipient_country

  String
  Country of the customer whom to send whatsapp message.
• number

  Object
  Full Number object attached to the Message.
• contact

  Object
  Full Contact object attached to the Message.

Endpoints
POST /v1/numbers/:id/messages/configurationCreate Number Configuration
GET /v1/numbers/:id/messages/configurationFetch Number Configuration
DELETE /v1/numbers/:id/messages/configurationDelete Number Configuration
POST /v1/numbers/:id/messages/native/sendSend Message in agent conversation
POST /v1/numbers/:id/messages/sendSend Message Skipping Aircall Inbox
POST /v1/numbers/:id/messages/group/native/sendSend Group Message in agent conversation
POST /v1/numbers/:id/messages/group/sendSend Group Message Skipping Aircall Inbox

Create or update the number configuration to allow a number to use the Send Message Skipping Aircall Inbox or Send WhatsApp Message Skipping Aircall Inbox endpoints.

Use the type field to specify whether the number is being configured for SMS (sms the default) or WhatsApp (whatsapp).

Once numbers are configured, they won't be able to send or receive messages via Aircall apps.

Numbers meant to be used with Send message in agent conversation or Send WhatsApp Message in Agent Conversation do not require to be configured.

For US long codes and US/CA toll free lines, numbers must be registered before SMS configuration. See here to check registration status.

Set a callbackURL that will be used not only to retrieve the status of messages sent, to get the messages received. Webhooks to retrieve messages activity expose messages sent and received with numbers that are active using the configuration exposed in this section. See Message Callbacks for the full payload structure and examples.

Path params
• id

  Integer
  Unique identifier for the Number.

Body params
• callbackUrl

  String
  The callback URL used to receive message status updates and inbound messages from the recipient.
  Optional field
• type

  String
  The channel to configure the number for. Allowed values: sms, whatsapp. Defaults to sms.
  Optional field

Response type values

Request
POST /v1/numbers/:id/messages/configuration

{
 "callbackUrl": "yourCallbackUrl",
 "type": "sms"
}

Response
Status: 200 OK

{
 "token": "token",
 "callbackUrl": "yourCallbackUrl",
 "type": "Public Api"
}

Fetch settings associated to a number Numbers and their information for Aircall Messaging public api.

Query params
• id

  Integer
  Unique identifier for the Number.

Headers
• content-type

  string
  Content type of the request. It will be application/json.

Request
GET /v1/numbers/:id/messages/configuration

Response
Status: 200 OK

{
 "token": "token",
 "callbackUrl": "yourCallbackUrl",
 "type": "PublicApi",
}

Delete configuration associated to a number Numbers for Aircall Messaging public api.

Query params
• id

  Integer
  Unique identifier for the Number.

Request
DELETE /v1/numbers/:id/messages/configuration

Response
Status: 204 No Content

When a number is configured using the Create Number Configuration endpoint with a callbackUrl, Aircall will POST callback payloads to that URL for two events:

• message.received — an inbound message arrived on the number.
• message.updated — the delivery status of an outbound message changed.

Callbacks are distinct from Aircall Webhooks. Callbacks are sent to the URL configured via the Create Number Configuration endpoint.

Delivery semantics

Aircall expects a 2xx HTTP response within 5 seconds. There is no automatic retry on failure. The token field in the payload can be used to verify the request comes from Aircall.

Callback payload envelope

Additional fields in data

The data object contains the standard Message attributes plus the following callback-specific ones:

Attributes
• error

  String
  Error description when a message fails. Format: "Code <code> (<description>)".
  Only present on failed message.updated callbacks.
• whatsapp

  Object
  WhatsApp-specific metadata. Only present for WhatsApp messages. See The whatsapp object below.
  Only present for WhatsApp messages.

The whatsapp object

When the message is a WhatsApp message, the data object includes a whatsapp field with the following attributes:

Attributes
• type

  String
  WhatsApp message type (e.g. "text", "image", "location", "button").
• parent_message_id

  String
  ID of the message being replied to.
  Only present for replies.
• location

  Object
  Location details. Contains latitude (Number), longitude (Number), and optionally label (String) and address (String).
  Only present for location messages.
• button

  Object
  Button interaction details. Contains text (String) and payload (String).
  Only present for button interactions.
• referral_source_id

  String
  ID of the ad or post that started the conversation.
  Only present when the conversation originated from a referral.
• external_user

  Object
  WhatsApp user identity. Only present when the contact has a WhatsApp Username. See The external_user object below.
  Only present when the contact has a WhatsApp Username.

The external_user object

When the contact has a WhatsApp Username, the whatsapp object includes an external_user field with the following attributes:

When a WhatsApp user has chosen to hide their phone number, the raw_digits field will contain their BSUID instead of a valid phone number. Use the bsuid field from the external_user object as the stable identifier for that contact in this case.

Sent when an inbound message arrives on the configured number. Applies to SMS, MMS, and WhatsApp.

For WhatsApp messages, the data object includes a whatsapp field.

Payload
{
 "resource": "message",
 "event_name": "message.received",
 "timestamp": 1722317361216,
 "token": "your_token",
 "data": {
 "id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "status": "received",
 "direction": "inbound",
 "raw_digits": "+13001234567",
 "body": "Hello, I need help with my order.",
 "media_url": [],
 "direct_link": "https://api.aircall.io/v1/numbers/123/messages/wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "created_at": 1722317361216,
 "sent_at": 1722317361216,
 "updated_at": 1722317361216,
 "number": {
 "id": 123,
 "direct_link": "https://api.aircall.io/v1/numbers/123",
 "name": "Support Line",
 "digits": "+18005550100",
 "country": "US",
 "time_zone": "America/New_York",
 "open": true,
 "created_at": "2023-01-15T10:00:00.000Z"
 },
 "whatsapp": {
 "type": "text",
 "external_user": {
 "bsuid": "US.abc123def456",
 "username": "john.doe",
 "profile_name": "John Doe"
 }
 }
 }
}

Sent when the delivery status of an outbound message changes. Applies to SMS and WhatsApp.

For failed deliveries, the data object includes an error field with a description in the format "Code <code> (<description>)".

Payload
{
 "resource": "message",
 "event_name": "message.updated",
 "timestamp": 1722317400000,
 "token": "your_token",
 "data": {
 "id": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "status": "delivered",
 "direction": "outbound",
 "raw_digits": "+13001234567",
 "body": "Your appointment is confirmed for tomorrow at 10am.",
 "direct_link": "https://api.aircall.io/v1/numbers/123/messages/SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "created_at": 1722317400000,
 "sent_at": 1722317400000,
 "updated_at": 1722317400000,
 "number": {
 "id": 123,
 "direct_link": "https://api.aircall.io/v1/numbers/123",
 "name": "Support Line",
 "digits": "+18005550100",
 "country": "US",
 "time_zone": "America/New_York",
 "open": true,
 "created_at": "2023-01-15T10:00:00.000Z"
 }
 }
}

Send a text message from an Aircall SMS-capable number that will be stored and added in the agents’ conversation. If no conversation with the recipient already exists, it will be created.

Any agent added to this number will be able to see the messages sent from this endpoint in their Aircall apps and they will be able to continue the conversation with the recipients.

Any number configured for use with Send Message Skipping Aircall Inbox won’t be able to use this endpoint. The configuration would need to be deleted first.

This endpoint is not meant for high volume use cases or non-conversational use cases. For such use cases use Send Message Skipping Aircall Inbox. Too many messages sent via this endpoint will disrupt agents work within the Aircall apps.

Query params
• id

  Integer
  Unique identifier for the Number.

Body params
• to

  String
  number you want to send the message
  Mandatory field
• body

  String
  text you want to send
  Mandatory field
• agentId

  Integer
  user's id
  Optional field

Request
POST /v1/numbers/:id/messages/native/send

{
 "to": "+130...",
 "body": "text you want to send",
}

Response
Status: 200 OK

{
 "id": "messageId",
 "status": "pending",
 "direct_link": "https://api.aircall.io/v1/numbers/:lineId/messages/:messageId",
 "direction": "outbound",
 "created_at": 1722317361216,
 "sent_at": 1722317361216,
 "updated_at": 1722317361216,
 "raw_digits": "+130...",
 "media_url": ["", ""],
 "body": "text you want to send",
 ...number object,
}

Send a text message or a multimedia message from a public api configured number.

Numbers not configured won't be able to send messages via API. Number can be configured from here.

Query params
• id

  Integer
  Unique identifier for the Number.

Body params
• to

  String
  number you want to send the message
  Mandatory field
• body

  String
  text you want to send
• mediaUrl

  Array<String>
  media urls you want to send
  Optional field

Request
POST /v1/numbers/:id/messages/send

{
 "to": "+130...",
 "body": "text you want to send",
 "mediaUrl": ["", ""]
}

Response
Status: 200 OK

{
 "id": "messageId",
 "status": "pending",
 "direct_link": "https://api.aircall.io/v1/numbers/:lineId/messages/:messageId",
 "direction": "outbound",
 "created_at": 1722317361216,
 "sent_at": 1722317361216,
 "updated_at": 1722317361216,
 "raw_digits": "+130...",
 "media_url": ["", ""],
 "body": "text you want to send",
 ...number object
}

Send a group text message from an Aircall SMS-capable number that will be stored and added in the group conversation. If no group conversation with the recipients already exists, it will be created.

Any agent added to this number will be able to see the messages sent from this endpoint in their Aircall apps and they will be able to continue the conversation with the recipients.

Any number configured for use with Send Group Message Skipping Aircall Inbox won’t be able to use this endpoint. The configuration would need to be deleted first.

Group messaging supports up to 10 participants total per group conversation, including the sender.

This endpoint is not meant for high volume use cases or non-conversational use cases. For such use cases use Send Group Message Skipping Aircall Inbox. Too many messages sent via this endpoint will disrupt agents work within the Aircall apps.

Query params
• id

  Integer
  Unique identifier for the Number.

Body params
• participants

  Array
  array of phone numbers to include in the group conversation
  Mandatory field
• body

  String
  text you want to send
  Mandatory field
• agentId

  Integer
  user's id
  Optional field

Request
POST /v1/numbers/:id/messages/group/native/send

{
 "body": "text you want to send",
 "participants":["+130...","+130...."]
}

Response
Status: 200 OK

{
 "group_message_id":"8f3c2c4e-9c6c-4c8e-9b4a-2c1f7e3d9c52",
 "status": "pending",
 "direct_link": "https://api.aircall.io/v1/numbers/:lineId/messages/:messageId",
 "direction": "outbound",
 "created_at": 1722317361216,
 "sent_at": 1722317361216,
 "group_conversation_id":"c4b8c1c0-0c6e-4c3f-9c1c-5c2f8e7a91d4",
 "updated_at": 1722317361216,
 "participants":["+130...","+130..."]
 "media_url": [],
 "body": "text you want to send",
 ...number object,
}

Send a group message with text or multimedia from a public api configured number.

Numbers not configured won't be able to send group conversations via API. Number can be configured from here.

This endpoint does not support sending both media and a text body in the same request; use one or the other.

Group messaging supports up to 10 participants total per group conversation, including the sender.

Query params
• id

  Integer
  Unique identifier for the Number.

Body params
• participants

  Array
  array of phone numbers to include in the group conversation
  Mandatory field
• body

  String
  text you want to send
  Optioal field
• mediaUrl

  Array<String>
  media urls you want to send
  Optional field

Request
POST /v1/numbers/:id/messages/group/send

{
 "participants":["+130...","+130...."]
 "body": "text you want to send",
}

POST /v1/numbers/:id/messages/group/send

{
 "participants":["+130...","+130...."]
 "mediaUrl": ["", ""]
}

Response
Status: 200 OK

{
 "group_message_id":"8f3c2c4e-9c6c-4c8e-9b4a-2c1f7e3d9c52",
 "status": "pending",
 "direct_link": "https://api.aircall.io/v1/numbers/:lineId/messages/:messageId",
 "direction": "outbound",
 "created_at": 1722317361216,
 "sent_at": 1722317361216,
 "updated_at": 1722317361216,
 "participants":["+130...","+130..."]
 "group_conversation_id":"c4b8c1c0-0c6e-4c3f-9c1c-5c2f8e7a91d4",
 "media_url": ["", ""],
 "body": "text you want to send",
 ...number object
}

Send a WhatsApp message from an Aircall WhatsApp-capable number that will be stored and visible in the agents' conversation inbox. If no conversation with the recipient already exists, it will be created.

Any agent added to this number will be able to see the messages sent from this endpoint in their Aircall apps and will be able to continue the conversation with the recipients.

This endpoint supports text messages and template messages.

This endpoint is not meant for high-volume or non-conversational use cases. For such use cases use Send WhatsApp Message Skipping Aircall Inbox. Too many messages sent via this endpoint will disrupt agents' work within the Aircall apps.

Any line registered for use with Send WhatsApp Message Skipping Aircall Inbox cannot use this endpoint. The configuration must be deleted first.

Body params
• lineId

  Integer
  Unique identifier for the WhatsApp-capable Number.
  Mandatory field
• externalNumber

  String
  Recipient phone number in E.164 format.
  Mandatory field
• agentId

  Integer
  The agent's user ID to associate with the sent message.
  Optional field
• text

  String
  Text message body (max 4096 characters). Mutually exclusive with templateParams. Can only be sent within an open 24-hour conversation window. Outside the window, use templateParams to initiate or re-initiate contact. Sending text outside the window fails synchronously with a 422 error.
  Optional field
• templateParams

  Object
  Template send parameters. Mutually exclusive with text.
  Optional field
• templateParams.id

  String
  Unique identifier of the WhatsApp template to use. Retrieve available template IDs from the List WhatsApp Templates endpoint.
  Mandatory when templateParams is present
• templateParams.body

  Array<Object>
  Variable substitutions for the template body. Each item must have key (String) and value (String).
  Optional field
• templateParams.buttons

  Array<Object>
  Variable substitutions for template buttons. Each item must have key (String) and value (String).
  Optional field
• templateParams.header

  Object
  Variable substitution for the template header component (image, document, or video URL).
  Optional field

Request
POST /v1/messages/send/whatsapp/native

{
 "lineId": 123,
 "externalNumber": "+130...",
 "text": "Text you want to send."
}

POST /v1/messages/send/whatsapp/native

{
 "lineId": 123,
 "externalNumber": "+130...",
 "templateParams": {
 "id": "1234",
 "body": [
 {"key": "{{1}}", "value": "Jordan"},
 {"key": "{{2}}", "value": "2026-06-15"}
 ]
 }
}

Response
Status: 200 OK

{
 "id": "550e8400-e29b-41d4-a716-446655440000",
 "status": "sent",
 "direction": "outbound",
 "created_at": 1722317361216,
 "sent_at": 1722317361216,
 "updated_at": 1722317361216,
 "raw_digits": "+130...",
 "direct_link": "https://api.aircall.io/v1/numbers/:lineId/messages/:messageId",
 "body": "text you want to send",
 ...number object
}

Send a WhatsApp message (text, media, or template) from a WhatsApp-capable number directly to a recipient, without storing the message in the Aircall agent inbox.

This endpoint is designed for high-volume or non-conversational use cases, such as notifications or automated messages. For conversational use cases where agents need visibility, use Send WhatsApp Message in Agent Conversation.

Licence requirement: The company must have an active whatsapp_messaging addon. If the addon is not active, the request will be rejected with a 403 error. Contact your Aircall account manager to enable this addon.

You can send one of the following per request: - A text message (text) - A media message (mediaUrl) - A template message (templateParams)

Providing both text/mediaUrl and templateParams in the same request is not allowed.

Body params
• lineId

  Integer
  Unique identifier for the WhatsApp-capable Number.
  Mandatory field
• to

  String
  Recipient phone number in E.164 format.
  Mandatory field
• text

  String
  Text message body (max 4096 characters). Mutually exclusive with templateParams. Can only be sent within an open 24-hour conversation window. Outside the window, use templateParams to initiate contact. Sending text outside the window returns 200 but delivers error 63016 to your registered webhook.
  Optional field
• mediaUrl

  String (URI)
  Publicly accessible media URL to send. Mutually exclusive with templateParams.
  Optional field
• templateParams

  Object
  Template send parameters. Mutually exclusive with text and mediaUrl.
  Optional field
• templateParams.id

  String
  Unique identifier of the WhatsApp template to use. Retrieve available template IDs from the List WhatsApp Templates endpoint.
  Mandatory when templateParams is present
• templateParams.body

  Array<Object>
  Variable substitutions for the template body. Each item must have key (String) and value (String).
  Optional field
• templateParams.buttons

  Array<Object>
  Variable substitutions for template buttons. Each item must have key (String) and value (String).
  Optional field
• templateParams.header

  Object
  Variable substitution for the template header component (image, document, or video URL). Required only for templates that include a media header.
  Optional field

Request
POST /v1/messages/whatsapp/send

{
 "lineId": 123,
 "to": "+130...",
 "text": "Text you want to send."
}

POST /v1/messages/whatsapp/send

{
 "lineId": 123,
 "to": "+130...",
 "templateParams": {
 "id": "1234",
 "body": [
 {"key": "{{1}}", "value": "Jordan"},
 {"key": "{{2}}", "value": "123456"}
 ]
 }
}

Response
Status: 200 OK

{
 "id": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "status": "sent",
 "direction": "outbound",
 "created_at": 1722317361216,
 "sent_at": 1722317361216,
 "updated_at": 1722317361216,
 "raw_digits": "+130...",
 "direct_link": "https://api.aircall.io/v1/numbers/:lineId/messages/:messageId",
 "media_url": [],
 "body": "text you want to send",
 ...number object
}

Retrieve a paginated list of WhatsApp templates associated with a WhatsApp-capable number. The number must be registered for WhatsApp to use this endpoint.

Results can be filtered by template status and category, and are paginated using a token-based cursor.

Path params
• id

  Integer
  Unique identifier for the WhatsApp-capable Number.
  Mandatory field

Query params
• status

  String
  Filter templates by approval status. See the status descriptions below.
  Optional field
• category

  String
  Filter templates by category. Allowed values: UTILITY, MARKETING, AUTHENTICATION.
  Optional field
• token

  Integer
  Pagination cursor. Use the nextToken from a previous response to fetch the next page.
  Optional field
• limit

  Integer
  Maximum number of templates to return per page.
  Optional field
• sort

  String
  Sort direction for results. Allowed values: asc, desc.
  Optional field

Template statuses

Headers
• content-type

  string
  Only JSON is currently supported. Use application/json.

Request
GET /v1/numbers/:id/templates

Response
Status: 200 OK

{
 "templates": [
 {
 "id": 1,
 "wabaId": "123456789",
 "name": "order_confirmation",
 "category": "UTILITY",
 "status": "APPROVED",
 "language": "en",
 "twilioType": "text",
 "createdAtTimestamp": 1722317361216,
 "updatedAtTimestamp": 1722317361216,
 "isFavourite": false,
 "template": { ... }
 }
 ],
 "pageInfo": {
 "currentToken": 0,
 "nextToken": 10,
 "totalCount": 50
 }
}

Retrieve the current WhatsApp registration and health status of a WhatsApp-capable number. Use this endpoint to check whether a number is online, its messaging limit tier, and whether it can currently send messages.

Path params
• id

  Integer
  Unique identifier for the WhatsApp-capable Number.
  Mandatory field

Status values

Headers
• content-type

  string
  Only JSON is currently supported. Use application/json.

Request
GET /v1/numbers/:id/whatsapp_status

Response
Status: 200 OK

{
 "wabaId": "123456789",
 "status": "ONLINE",
 "canSendMessage": true,
 "messagingLimitTier": "TIER_1K",
 "qualityRating": "GREEN",
 "businessVerificationStatus": "VERIFIED"
}

Contacts are a core part of Aircall experience.

Every time Agents are on a call, Aircall fetches their contact information from different sources.

Please note that contacts created by third-party integrations will not be accessible from the public-api, but you will still be able to see them in the phone app (mobile & desktop)

To better understand how contacts sync from third-party integrations works, you can have a look at this article from our knowledge base.

Contacts CSV files can be uploaded by Agents in the Phone app. More info here.

Attributes
• id

  Integer
  Unique identifier for the Contact.
• direct_link

  String
  Direct API URL.
• first_name

  String
  Contact's first name.
• last_name

  String
  Contact's last name.
• company_name

  String
  Contact's company name.
• description

  String
  Field used by Aircall to qualify tags.
• information

  String
  Extra information about the contact.
  Can be used to store outside data.
• is_shared

  Boolean
  Contact can be shared within the organization.
  All Contacts retrieved via the Public API are shared.
• phone_numbers

  Array
  Phone numbers of this contact.
  More details in the Phone numbers attribute table below.
• emails

  Array
  Email addresses of this contact.
  More details in the Emails attribute table below.

Phone numbers attribute
• id

  Integer
  Unique identifier for this phone number.
• label

  String
  A custom label like work, home...
• value

  String
  The raw phone number.
  The value needs to be valid

Emails attribute
• id

  Integer
  Unique identifier for this email address.
• label

  String
  A custom label like work, home...
• value

  String
  The email address.

Emojis can't be used in Contact's attributes (they will be removed). Please note that in the payload of Contact Webhook Events, the created_at and updated_at attributes will contain timestamps in UTC format (i.e., YYYY-MM-DDTHH:mm:ssZ)

Endpoints
GET /v1/contactsList all Contacts
GET /v1/contacts/searchSearch Contacts
GET /v1/contacts/:idRetrieve a Contact
POST /v1/contactsCreate a Contact
POST /v1/contacts/:idUpdate a Contact
DELETE /v1/contacts/:idDelete a Contact
POST /v1/contacts/:id/phone_detailsAdd phone number to a Contact
PUT /v1/contacts/:id/phone_details/:phone_number_idUpdate a phone number from a Contact
DELETE /v1/contacts/:id/phone_details/:phone_number_idDelete a phone number from a Contact
POST /v1/contacts/:id/email_detailsAdd email to a Contact
PUT /v1/contacts/:id/email_details/:email_idUpdate an email from a Contact
DELETE /v1/contacts/:id/email_details/:email_idDelete an email from a Contact

Fetch all the shared Contacts associated to a company with their phone numbers and emails information.

Query params
• from

  String
  Set a minimal creation date for contacts (UNIX timestamp).
• to

  String
  Set a maximal creation date for contacts (UNIX timestamp).
• order

  String
  Reorder entries by order_by, created_at otherwise. Can be asc or desc.
  Default value is asc
• order_by

  String
  Set the order field, created_at or updated_at.
  Default value is created_at

Using the pagination system, you can retrieve up to 10,000 Contacts. To pass over this limit, we encourage you to use the from param as much as you can!

Request
GET /v1/contacts

Response
Status: 200 OK

{
 "meta": {
 "count": 2,
 "total": 2,
 "current_page": 1,
 "per_page": 20,
 "next_page_link": null,
 "previous_page_link": null
 },
 "contacts": [
 {
 "id": 710,
 "direct_link": "https://api.aircall.io/v1/contacts/710",
 "first_name": "Vicente",
 "last_name": "Abad",
 "company_name": null,
 "information": null,
 "is_shared": true,
 "created_at": 1400691054,
 "updated_at": 1444336506,
 "emails": [],
 "phone_numbers": [
 {
 "id": 3367,
 "label": "Mobile",
 "value": "+34664673697"
 }
 ]
 },
 {
 "id": 711,
 "direct_link": "https://api.aircall.io/v1/contacts/711",
 "first_name": "Margaret",
 "last_name": "Morrison",
 "company_name": "TeleWorm",
 "information": null,
 "is_shared": true,
 "created_at": 1400692007,
 "updated_at": 1444336507,
 "emails": [],
 "phone_numbers": [
 {
 "id": 3368,
 "label": "Mobile",
 "value": "+34768776683"
 },
 {
 "id": 3369,
 "label": "Work",
 "value": "+49111000460"
 }
 ],
 "emails": [
 {
 "id": 3200,
 "label": "Work",
 "value": "m.morrison@teleworm.es"
 }
 ]
 }
 ]
}

Search within a company's shared Contacts with extra query parameters.

Query params
• from

  String
  Set a minimal creation date for contacts (UNIX timestamp).
• to

  String
  Set a maximal creation date for contacts (UNIX timestamp).
• order

  String
  Reorder entries by order_by, created_at otherwise. Can be asc or desc.
  Default value is asc
• order_by

  String
  Set the order field, created_at or updated_at.
  Default value is created_at
• phone_number

  String
  Phone number of a contact
• email

  String
  Email address of a contact