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 way 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 require to set 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.

Not a Developer?

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

REST API

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" }

Authentication

Introduction

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

OAuth ﹣ Technology Partners

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-v2.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. Contact us on marketplace@aircall.io, we will get back to you shortly with those credentials!

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-v2.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" }

Basic Auth ﹣ Aircall customers

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" }

Rate limiting

Aircall limits the number of requests to its Public API to 60 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:

header description
X-AircallApi-Limit Limit of requests for the API key used.
X-AircallApi-Remaining Remaining requests for this API key.
X-AircallApi-Reset Timestamp when the counter will be reset.

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!

Pagination

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 }, ... }

Errors

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 }
code description
200 OK - The request has succeeded.
201 Created - The request has been fulfilled and has resulted in one or more new resources being created.
204 No Content - Server has successfully fulfilled the request, no additional content sent in the response payload body.
400 Bad Request - Server cannot process the request due to something that is perceived to be a client error.
401 Unauthorized - Lack of valid authentication credentials for the target resource.
404 Not Found - Server did not find the target resource.
405 Method Not Allowed - The method is known by the server but not supported.
500 Internal Server Error - Server encountered an unexpected condition.

Content-Type

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" }

User

User overview

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 an 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.
  • 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!

List all Users

Fetch all Users 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 /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", "wrap_up_time": 0 }, { "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", "wrap_up_time": 0 }, { "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", "wrap_up_time": 0 } ] }

Retrieve a User

Retrieve details of a specific User.

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

    Path params
  • id
    Integer
    Unique identifier for the User.
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", "wrap_up_time": 0, "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" } } ] } }

Create a User

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.

    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
  • is_admin
    Boolean
    If true, User will have access to the Dashboard. This attribute can only be set on User creation, not on update.
    Default value is false
code description
422 Mandatory attribute missing, check the troubleshoot field.
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 } }

Update a User

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.

    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.
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": 0 } }

Delete a User

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.
code description
204 User will be deleted in the next minutes, depending on how many calls and data are associated to them.
422 Server unable to process the request, error will be described in the troubleshoot field.
Request
DELETE /v1/users/:id
Response
Status: 204 No Content

Retrieve list of Users availability

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" } ] }

Check availability of a User

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" }

Start an outbound call

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.

    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.
code description
204 Success.
400 Number not found or invalid number to dial.
405 User not available.
Request
POST /v1/users/:id/calls { "number_id": 123, "to": "+18001231234" }
Response
Status: 204 No Content

Dial a phone number in the Phone

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.
code description
204 Success.
400 Invalid number to dial.
405 User not available.
Request
POST /v1/users/:id/dial { "to": "+18001231234" }
Response
Status: 204 No Content

Team

Team overview

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 64 characters maximum.
  • created_at
    String
    Timestamp when the Team was created, in UTC.
  • users
    Array
    List of Users associated to this Team.
    User attributes available and availability_status are not available in Teams endpoint.

List all Teams

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.

code description
200 Success.
401 Unauthorized. Invalid API key or Bearer access token
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", "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" } ] } ] }

Retrieve a Team

Retrieve details of a specific Team.

    Path params
  • id
    Integer
    Unique identifier for the Team.
code description
200 Success.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Id does not exist
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" } ] } }

Create a Team

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.
code description
201 Success.
400 Company might have reached the maximum number of teams allowed on their plan. Name must be smaller than 64 characters and unique in the company.
401 Unauthorized. Invalid API key or Bearer access token
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": [] } }

Delete a Team

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.
code description
204 Success.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Id does not exist
422 Server unable to process the request, error will be described in the troubleshoot field.
Request
DELETE /v1/teams/:id
Response
Status: 200 OK

Add a User to a Team

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.
code description
201 Success.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Either team_id or user_id does not exist
422 Server unable to process the request, error will be described in the troubleshoot field.
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" } ] } }

Remove a User from a Team

Users can be delete 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.
code description
200 Success.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Either team_id or user_id does not exist
422 Server unable to process the request, error will be described in the troubleshoot field.
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": [] } }

Call

Call overview

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.
  • 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 started_at - ended_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 10min. only.
  • 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 10min. only.
  • 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.
    More information on Call pricing in our Knowledge Base.
  • 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.
  • 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.



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

List all Calls

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.

    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

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, "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": [] }, { "id": 813, "direct_link": "https://api.aircall.io/v1/calls/813", "direction": "inbound", "status": "done", "missed_call_reason": null, "started_at": 1584998199, "answered_at": "no_available_agent", "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" } ] }, ... ] }

Retrieve a Call

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.

    Path params
  • id
    Integer
    Unique identifier for the Call.
Request
GET /v1/calls/:id
Response
Status: 200 OK { "call": { "id": 812, "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": [] } }

Search Calls

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.

    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.

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, "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": [...] }, { "id": 813, "direct_link": "https://api.aircall.io/v1/calls/813", "direction": "inbound", "status": "done", "missed_call_reason": null, "started_at": 1584998199, "answered_at": "no_available_agent", "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": [...] }, ... ] }

Transfer a Call

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

Only cold transfers are available via the Public API:

  • 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 dispatching strategy can be specified with parameter: dispatching_strategy: The "simultaneous" strategy (default one if argument is not specified) will ring each available members 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.

When call is ringing, transferring to a team is limited to teams with 25 users or less.

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

    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.
code description
204 Success.
400 Call already ended.
400 Call cannot be transferred to a team with more than 25 users.
400 Invalid usage of dispatching strategy with user or external phone number.
404 User or Call not found.
Request
POST /v1/calls/:id/transfers { "user_id": 456 }
Response
Status: 204 No Content

Comment a Call

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.
code description
201 Success.
400 Maximum of 5 notes can be added to a Call.
Request
POST /v1/calls/:id/comments { "content": "Please call back this customer!" }
Response
Status: 201 Created

Tag a Call

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.
code description
201 Success.
Request
POST /v1/calls/:id/tags { "tags": [545] }
Response
Status: 201 Created

Archive a Call

Missed calls non-archived will be displayed in the To-do view and can be Mark 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, "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": [...] } }

Unarchive a Call

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, "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": [...] } }

Pause recording on a Call

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

    Path params
  • id
    Integer
    Unique identifier for the Call.
code description
204 Success.
400 Call has already ended.
404 Call not found.
405 Recording is disabled on the Call's number.
Request
POST /v1/calls/:id/pause_recording
Response
Status: 204 No Content

Resume recording on a Call

When live recording is actived 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.
code description
204 Success.
400 Call has already ended.
404 Call not found.
405 Recording is disabled on the Call's Number.
Request
POST /v1/calls/:id/resume_recording
Response
Status: 204 No Content

Delete Call recording

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.

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 Call voicemail

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

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

Insight cards will only be seen on a 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.

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

Insight Card

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

    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 preceeds the user card.
    Mandatory field.
  • user_id
    Integer
    The id of the user to be displayed.
    Mandatory field.
code description
201 Success.
400 Payload malformed.
404 Call not found.
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 Campaign

Dialer Campaign overview

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.

Retrieve a Dialer Campaign

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.
code description
404 User has no active campaign.
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 a Dialer Campaign

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.
code description
422 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

Delete a Dialer Campaign

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.
code description
404 User has no active campaign.
Request
DELETE /v1/users/:user_id/dialer_campaign
Response
Status: 204 No Content

Retrieve phone numbers

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.
code description
404 User has no active campaign.
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" } ] }

Add phone numbers

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.
code description
422 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 a phone number

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

Number

Number overview

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

A Number can be either Classic or IVR:

  • Classic: Assigned users and teams will make and receive calls from that number.
  • IVR (Interactive Voice Response): Callers will reach a voice menu first, and choose among options through their keypad.
    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.
  • 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
    Current opening state of the Number, based on its opening hours.
  • availability_status
    String
    Current availability status of the Number.
    open, custom, closed
  • is_ivr
    Boolean
    true if Number is an IVR, false if Number is a Classic Number.
    More information on our Knowledge Base.
  • 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
    Welcome message URL. This file is played at the beginning of an incoming call.
    Available for Classic & IVR numbers.
  • waiting
    String
    Waiting music URL. Caller will hear this if they are put on hold during an ongoing call or while the call is being transfered.
    Available for Classic & IVR numbers.
  • ringing_tone
    String
    Ringing tone URL. During an incoming call, caller will hear this music while waiting for the call to be answered.
    Available for Classic numbers.
  • unanswered_call
    String
    Unanswered Call message URL. Caller will hear this message if their call is not answered when the business hours are open.
    Available for Classic numbers.
  • after_hours
    String
    After Hours message URL. Caller will hear this message if they call outside of this number's business hours.
    Available for Classic numbers.
  • ivr
    String
    IVR message URL. Caller will hear this right after the Welcome message. This message will be played twice.
    Available for IVR numbers.
  • voicemail
    String
    Voicemail message URL. Deprecated: replaced by unanswered_call.
    Available for IVR numbers.
  • closed
    String
    Closed message URL. Deprecated: replaced by after_hours.
    Available for IVR numbers.
  • callback_later
    String
    Callback Later message.
    Available for IVR numbers.

List all Numbers

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 a Number

Retrieve details of a specific Numbers.

    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" } ] } }

Update a Number

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
    Can be open, custom or closed.
  • is_ivr
    Boolean
    If true, Number will be converted into an IVR. Classic otherwise.
  • 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" } ] } }

Update Music and Messages

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.

More information on how Music & Messages work in our Knowledge Base.

    Query params
  • id
    Integer
    Unique identifier for the Number.
    Body params
  • messages
    Object
    Check the messages object format below.
    Messages object
  • welcome
    String
    Must be a valid public URL.
  • waiting
    String
    Must be a valid public URL.
  • ivr
    String
    Must be a valid public URL.
  • voicemail
    String
    Must be a valid public URL.
  • closed
    String
    Must be a valid public URL.
  • callback_later
    String
    Must be a valid public URL.
  • unanswered_call
    String
    Must be a valid public URL.
  • after_hours
    String
    Must be a valid public URL.
  • ringing_tone
    String
    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": [ ... ] } }

Contact

Contact overview

Contacts are a core part of Aircall experience.

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

Aircall Public API allows creating, updating and deleting shared Contacts only.

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.
    Emails attribute
  • id
    Integer
    Unique identifier for this email address.
  • label
    String
    A custom label like work, home...
  • value
    String
    The email address.

List all Contacts

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 Contacts

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

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/search
Response
Status: 200 OK { "meta": { "count": 1, "total": 1, "current_page": 1, "per_page": 20, "next_page_link": null, "previous_page_link": null }, "contacts": [ { "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" } ] } ] }

Retrieve a Contact

Retrieve details of a specific Contact.

Only shared contacts can be found.

    Path params
  • id
    Integer
    Unique identifier for the Contact.
Request
GET /v1/contacts/:id
Response
Status: 200 OK { "contact": { "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" } ] } }

Create a Contact

Contacts created via Aircall Public API will be automatically shared across the company.

phone_numbers is required when creating a Contact.

    Body params
  • first_name
    String
    Can't be blank if defined.
  • last_name
    String
    Can't be blank if defined.
  • company_name
    String
    Can't be blank if defined.
  • information
    String
    Can't be blank if defined.
  • emails
    Array
    Array of email address objects.
    For each email, label and value must be set.
  • phone_numbers
    Array
    Array of phone_numbers objects.
    Mandatory field. For each phone_number, label and value must be set.
Request
POST /v1/contacts { "first_name": "Gary", "last_name": "Jennings", "information": "external_custom_id:87123", "phone_numbers": [ { "label": "Work", "value": "+19001112222" } ], "emails": [ { "label": "Office", "value": "gary.jennings@acme.com" } ] }
Response
Status: 201 Created { "contact": { "id": 719, "direct_link": "https://api.aircall.io/v1/contacts/719", "first_name": "Gary", "last_name": "Jennings", "company_name": null, "information": "external_custom_id:87123", "is_shared": true, "created_at": 1585083040, "updated_at": 1585083040, "emails": [ { "id": 9170, "label": "Office", "value": "gary.jennings@acme.com" } ], "phone_numbers": [ { "id": 9171, "label": "Work", "value": "+19001112222" } ] } }

Update a Contact

Update a shared Contact. Response will be the updated Contact.

To update a Contact's phone numbers or emails, please use the approriate endpoints described below.

This request is a POST method, and not a PUT method!

    Path params
  • id
    Integer
    Unique identifier for the Contact.
    Body params
  • first_name
    String
    Can't be blank if defined.
  • last_name
    String
    Can't be blank if defined.
  • company_name
    String
    Can't be blank if defined.
  • information
    String
    Can't be blank if defined.
Request
POST /v1/contacts/:id { "first_name": "Vicente UPDATED", "company_name": "Lerox Inc." }
Response
Status: 200 OK { "contact": { "id": 710, "direct_link": "https://api.aircall.io/v1/contacts/710", "first_name": "Vicente UPDATED", "last_name": "Abad", "company_name": "Lerox Inc.", "information": null, "is_shared": true, "created_at": 1400691054, "updated_at": 1444336506, "emails": [], "phone_numbers": [ { "id": 3367, "label": "Mobile", "value": "+34664673697" } ] } }

Delete a Contact

Delete a contact from the Company.

Only shared contacts can be deleted.

    Path params
  • id
    Integer
    Unique identifier for the Contact.
Request
DELETE /v1/contacts/:id
Response
Status: 204 No Content

Add phone number to a Contact

Phone numbers can be added one by one to a Contact.

Phone number's value will be normalized before being stored.

    Attributes
  • id
    Integer
    Unique identifier for the Contact.
    Body params
  • label
    String
    Can't be blank if defined.
  • value
    String
    Aircall stores any phone number format. It is recommended to store a valid phone number so agent can dial them easily.
    Mandatory field.
Request
POST /v1/contacts/:id/phone_details { "label": "Work", "value": "+19161110000" }
Response
Status: 201 Created { "phone_detail": { "id": 5200, "label": "Work", "value": "19161110000" } }

Update a phone number from a Contact

Phone number's value will be normalized before being stored.

The value field must be sent each time a phone number is updated.

    Attributes
  • id
    Integer
    Unique identifier for the Contact.
  • phone_number_id
    Integer
    Unique identifier for the phone number.
    Body params
  • label
    String
    Can't be blank if defined.
  • value
    String
    Aircall stores any phone number format. It is recommended to store a valid phone number so agent can dial them easily.
    Mandatory field.
Request
PUT /v1/contacts/:id/phone_details/:phone_number_id { "label": "Home UPDATED", "value": "+19161110011" }
Response
Status: 202 Accepted { "phone_detail": { "id": 5200, "label": "Home UPDATED", "value": "19161110011" } }

Delete a phone number from a Contact

Phone numbers can be removed from a Contact by using the following endpoint.

    Attributes
  • id
    Integer
    Unique identifier for the Contact.
  • phone_number_id
    Integer
    Unique identifier for the phone number.
Request
DELETE /v1/contacts/:id/phone_details/:phone_number_id
Response
Status: 204 No Content

Add email to a Contact

Emails can be added one by one to a Contact.

    Attributes
  • id
    Integer
    Unique identifier for the Contact.
    Body params
  • label
    String
    Can't be blank if defined.
  • value
    String
    Aircall stores any email format.
    Mandatory field.
Request
POST /v1/contacts/:id/email_details { "value": "v.lightner@example.com" }
Response
Status: 201 Created { "email_detail": { "id": 5201, "label": "Work", "value": "v.lightner@example.com" } }

Update an email from a Contact

The value field must be sent each time an email address is updated.

    Attributes
  • id
    Integer
    Unique identifier for the Contact.
  • email_id
    Integer
    Unique identifier for the Email address.
    Body params
  • label
    String
    Can't be blank if defined.
  • value
    String
    Aircall stores any email format.
    Mandatory field.
Request
PUT /v1/contacts/:id/email_details/:email_id { "value": "v.updated@example.com" }
Response
Status: 202 Accepted { "email_detail": { "id": 5201, "label": "Work", "value": "v.updated@example.com" } }

Delete an email from a Contact

Email addresses can be removed from a Contact by using the following endpoint.

    Attributes
  • id
    Integer
    Unique identifier for the Contact.
  • email_id
    Integer
    Unique identifier for the email address.
Request
DELETE /v1/contacts/:id/email_details/:email_id
Response
Status: 204 No Content

Tag

Tag overview

Calls can be tagged by Agents from the Phone app.

Tags can be created either by Admins from their Dashboard, or via the Public API, and are made of a name and a color.

Tags in the Phone app

    Attributes
  • id
    Integer
    Unique identifier for the Tag.
  • direct_link
    String
    Direct API URL.
  • name
    String
    Tag's name.
  • color
    String
    The color that this tag is displayed in.
  • description
    String
    Field used by Aircall to qualify Tags.

List all Tags

Fetch all Tags associated to a company and their information.

Pagination params can be used on this request.

code description
200 Success.
401 Unauthorized. Invalid API key or Bearer access token
Request
GET /v1/tags
Response
Status: 200 OK { "meta": { "count": 3, "total": 3, "current_page": 1, "per_page": 20, "next_page_link": null, "previous_page_link": null }, "tags": [ { "id": 678, "name": "General Inquiries", "color": "#0662B5", "description": null }, { "id": 679, "name": "Feedback", "color": "#008f6c", "description": null }, { "id": 680, "name": "Spam Call", "color": "#FCBB26", "description": null } ] }

Retrieve a Tag

Retrieve details of a specific Tag.

    Path params
  • id
    Integer
    Unique identifier for the Tag.
code description
200 Success.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Id does not exist
Request
GET /v1/tags/:id
Response
Status: 200 OK { "tag": { "id": 678, "name": "General Inquiries", "color": "#0662B5", "description": null } }

Create a Tag

Aircall will perform validation before inserting new Tag (like presence of a name).

    Body params
  • name
    String
    Can't be blank if defined.
    Mandatory field.
  • color
    String
    Can't be blank and must ne formatted in hexadecimal
    Mandatory field.
code description
201 Success.
400 Invalid payload.
401 Unauthorized. Invalid API key or Bearer access token
Request
POST /v1/tags { "name": "VIP Customer", "color": "#00B388" }
Response
Status: 201 Created { "tag": { "id": 681, "name": "VIP Customer", "color": "#00B388", "description": null } }

Update a Tag

Some fields can be updated via the Public API.

    Path params
  • id
    Integer
    Unique identifier for the Tag.
    Body params
  • name
    String
    Can't be blank if defined.
    Mandatory field.
  • color
    String
    Can't be blank and must be formatted in Hexadecimal.
    Mandatory field.
code description
200 Success.
400 Invalid payload.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Id does not exist
Request
PUT /v1/tags/:id { "name": "Tier 2 Customer" }
Response
Status: 200 OK { "tag": { "id": 681, "name": "Tier 2 Customer", "color": "#00B388", "description": null } }

Delete a Tag

Tag will be removed from Calls.

    Path params
  • id
    Integer
    Unique identifier for the Tag.
code description
204 Success.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Id does not exist
422 Server unable to process the request, error will be described in the troubleshoot field.
Request
DELETE /v1/tags/:id
Response
Status: 204 No Content

Webhook

Webhook API overview

This section describes only REST endpoints related to Webhooks. If you want to know more about Webhook events and how to use them, please refer to this section.

Aircall Public API allows any developer to fetch, create, update and delete Webhooks for an Aircall account. With OAuth, only the webhook linked to the token is accessible. With Basic Auth, webhooks created through the Aircall's dashboard and Basic Auth API requests are accessible.

Webhooks are mainly composed of a custom_name and a list of events (see full events list here).

Use the token field to identify from which Aircall account a Webhook is sent from!

    Attributes
  • id
    Integer
    Unique identifier for the Webhook.
  • direct_link
    String
    Direct API URL.
  • created_at
    String
    Timestamp when the webhook was created, in UTC.
  • custom_name
    String
    Webhook's custom name.
    Default is Webhook.
  • url
    String
    Valid URL to a web server.
  • active
    Boolean
    Status of the Webhook. If active, events will be sent to the url.
    Default is true.
  • token
    String
    Unique token for request's authentication.
  • events
    Array
    List of events registered.

List all Webhooks

Fetch all Webhooks 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.

code description
200 Success.
401 Unauthorized. Invalid API key or Bearer access token
Request
GET /v1/webhooks
Response
Status: 200 OK { "meta": { "count": 2, "total": 2, "current_page": 1, "per_page": 20, "next_page_link": null, "previous_page_link": null }, "webhooks": [ { "id": 1001, "direct_link": "https://api.aircall.io/v1/webhooks/1001", "created_at": "2020-04-01T15:56:18.000Z", "url": "https://my-server.example.com/webhooks/calls", "active": true, "token": "abc123def456ghi789", "events": [ "call.assigned", "call.transferred", "call.ringing_on_agent" ] }, { "id": 1002, "direct_link": "https://api.aircall.io/v1/webhooks/1002", "created_at": "2020-04-02T09:14:31.000Z", "url": "https://my-server.example.com/webhooks/numbers", "active": true, "token": "4567ghi789abc123def", "events": [ "number.opened", "number.closed" ] } ] }

Retrieve a Webhook

Retrieve details of a specific Webhook.

    Path params
  • id
    Integer
    Unique identifier for the Webhook.
code description
200 Success.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Id does not exist
Request
GET /v1/webhooks/:id
Response
Status: 200 OK { "webhook": { "id": 1001, "direct_link": "https://api.aircall.io/v1/webhooks/1001", "created_at": "2020-04-01T15:56:18.000Z", "url": "https://my-server.example.com/webhooks/calls", "active": true, "token": "abc123def456ghi789", "events": [ "call.assigned", "call.transferred", "call.ringing_on_agent" ] } }

Create a Webhook

Webhook creation can be done either from the Aircall Dashboard or via the Public API. Webhook have a list of events attached to it, linked to Calls, Users, Contacts and/or Numbers.

A company can have up to 100 Webhooks maximum.

    Body params
  • url
    String
    Can't be blank and must be a valid URL.
    Mandatory field.
  • custom_name
    String
  • events
    Array
    If events field is empty, all events will be attached to this webhook.
    Check here for a full list of available events.
code description
201 Success.
400 Either url param is missing, company reached their maximum Webhooks count (100) or events are not valid.
401 Unauthorized. Invalid API key or Bearer access token
Request
POST /v1/webhooks { "custom_name": "My Custom Workflow", "url": "https://my-server.example.com/webhooks/contacts", "events": [ "contact.created", "contact.updated", "contact.deleted" ] }
Response
Status: 201 Created { "webhook": { "id": 26316, "direct_link": "https://api.aircall.io/v1/webhooks/26316", "created_at": "2020-03-24T19:51:24.000Z", "url": "https://my-server.example.com/webhooks/contacts", "active": true, "events": [ "contact.created", "contact.updated", "contact.deleted" ], "token": "df76g76dpziygs567f0" } }

Update a Webhook

Webhook objects can be updated either from the Aircall Dashboard or via the Public API.

This endpoint is also useful to re-activate Webhooks that are automatically disabled by Aircall (more info in the Webhook usage section).

If the events field is not specified, Webhook will be registered to all events by default. Make sure to specify this field if you don't want the events array to be overridden by the default value!

    Path params
  • id
    Integer
    Unique identifier for the Webhook.
    Body params
  • url
    String
    Can't be blank and must be a valid URL.
  • custom_name
    String
  • events
    Array
    If events field is empty, all events will be attached to this webhook.
    Check here for a full list of available events.
  • active
    Boolean
    Set this field to true to re-activate a Webhook or false to disable it.
code description
200 Success.
400 Either url param is missing, company reached their maximum Webhooks count (100) or events are not valid.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Id does not exist
Request
PUT /v1/webhooks/:id { "url": "https://my-new-server.example.com/webhooks/contacts", "events": [ "contact.created", "contact.updated", "contact.deleted" ] }
Response
Status: 200 OK { "webhook": { "id": 26316, "direct_link": "https://api.aircall.io/v1/webhooks/26316", "created_at": "2020-03-24T19:51:24.000Z", "url": "https://my-new-server.example.com/webhooks/contacts", "active": true, "events": [ "contact.created", "contact.updated", "contact.deleted" ], "token": "df76g76dpziygs567f0" } }

Delete a Webhook

Webhook objects can be deleted either from the Aircall Dashboard or via the Public API. Aircall will stop sending events and configuration of the Webhook will be lost.

    Path params
  • id
    Integer
    Unique identifier for the Webhook.
code description
204 Success.
401 Unauthorized. Invalid API key or Bearer access token
404 Not found. Id does not exist
Request
DELETE /v1/webhooks/:id
Response
Status: 204 No Content

Company

Company overview

The Company object is a brief representation of the state of a company with its name, the number of Users and Numbers.

Companies are not updatable nor destroyable via Aircall Public API. The only way to do so is via the Aircall Dashboard.

    Attributes
  • name
    String
    Name of the Company.
  • users_count
    Number
    Number of Users in the Company.
  • numbers_count
    Number
    Number of Numbers in the Company.

Retrieve Company information

Company information can be retrieve with this GET request.

code description
200 Success.
401 Unauthorized. Invalid Bearer access token
Request
GET /v1/company
Response
Status: 200 OK { "company": { "name": "Acme Inc.", "users_count": 146, "numbers_count": 28 } }

Integration

Integration overview

The Integration object is a brief representation of the state of an integration with its name, logo, status, amount of Numbers connected and User that installed it.

Integrations are not updatable nor destroyable via Aircall Public API. The only way to do so is via the Aircall Dashboard.

    Attributes
  • name
    String
    Name of the Integration.
  • custom_name
    String
    Custom name of the Integration.
  • logo
    String
    Url to the Integration logo
  • company_id
    Number
    Id of the associated Company
  • status
    String
    Status of the integration
  • active
    Boolean
    true if status == "active".
  • number_ids
    Number[]
    The ids of Numbers in the Integration.
  • numbers_count
    Number
    Number of Numbers in the Integration.
  • user
    User
    User that installed the Integration.
    Can be null if the user was deleted

Retrieve Integration information

Integration information can be retrieved with this GET request. The return of this endpoint is the integration associated to the accessToken.

This information can only be retrieved for integrations built by aircall, or 3rd party using OAuth. Integrations using Basic Auth aren’t retrievable through this endpoint.

code description
200 Success.
401 Unauthorized. Invalid Bearer access token
403 Forbidden. Cannot be used with API KEY (Oauth only)
404 Not found. Integration does not exist anymore
Request
GET /v1/integrations/me
Response
Status: 200 OK { "integration": { "id": 1234, "name": "My app", "logo": "https://cdn.aircall.io/applications/standard/staging/ico_91.svg", "company_id": 1, "status": "active", "active": true, "created_at": "2020-11-02T15:38:16.000+00:00", "updated_at": "2020-11-02T15:38:29.000+00:00", "deleted_at": null, "number_ids": [123456], "numbers_count": 1, "custom_name": null, "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" } }, } }

Enable Integration

Use this endpoint to enable the integration associated to the access token and activate webhooks on it.

When an integration is first installed, it is enabled by default. This endpoint is handy to programatically re-enable an integration that has been disabled.

If used upon the installation of your integration, with the install true query parameter, this will redirect the user who installed it to your integration settings page in the dashboard at the end of the flow, instead of the aircall integration list. This isn’t mandatory as part of the install flow.

This endpoint can only be used for integrations built by aircall, or 3rd party using OAuth. Integrations using Basic Auth cannot be enabled through this endpoint.

query-params-field type description
install Boolean Pass if first time enabled to see the integration in the dashboard
code description
204 Success.
401 Unauthorized. Invalid Bearer access token
403 Forbidden. Cannot be used with API KEY (Oauth only)
Request
POST /v1/integrations/enable
Response
Status: 204 OK

Disable Integration

Use this endpoint to disable the integration associated to the access token and de-activate webhooks on it.

This endpoint can only be used for integrations built by aircall, or 3rd party using OAuth. Integrations using Basic Auth cannot be disabled through this endpoint. <!-- URL -->

code description
204 Success.
401 Unauthorized. Invalid Bearer access token
403 Forbidden. Cannot be used with API KEY (Oauth only)
Request
POST /v1/integrations/disable
Response
Status: 204 OK

Participant

Participant overview

The Participant object is a representation of a member in a conference call

Participant are not updatable nor destroyable via Aircall Public API.

Participant information is only present in conference calls and it can be accessed inside the call object. See: Retrieve a Call

    Attributes
  • id
    String
    Either Contact or User id. Not present for external
  • type
    String
    It will be 'user', 'contact' or 'external'
  • name
    String
    Participant's full name. Not present for external
  • phone_number
    String
    Not present in a user type participant

Webhooks

Webhooks allow Aircall to provide and send real-time information to other applications.

Aircall Webhooks are designed to notify external system each time an event occurs on an Aircall account, like when a call is started, when a user is created and even when a contact is updated!

With that in mind, any developer can build automated tasks, specific to any businesses, based on these events.

User's events

Number's events

Call's events

Contact's events

Click on an event's name to get more information on how and when it is trigger by Aircall!

Register an endpoint

The following steps describe how to register a server endpoint to start receiving Webhook events. Up to 100 Webhooks can be registered per account!

  1. Login on your Aircall account (sign up here if you don't have one).
  2. Go to the Integrations' page.
  3. In the Discover more integrations section, find and click on the Webhook block.
  4. Create a Webhook by clicking on the green Install button.
  5. Provide a name and a valid URL and select all the events you want to subscribe to.
  6. Click on the green Save button and… that's it!

Your Webhook URL must be behind a SSL certificate and start with https.

Aircall will start sending events to your server right after the Webhook creation, make sure your server is up and running.

Webhook creation

Webhook usage

Make sure your server can receive POST requests, reads JSON format and always answers a 200 HTTP Code!

During development, you can create SSH tunnels to your local environment. At Aircall, we use and recommand ngrok which is free and open-source.

Web server

Once the endpoints are registered, a simple web server is needed in order to receive events. Then, Aircall will send a POST request to the Webhook's URL each time an event occurs with a JSON payload body.

The Web server must be publicly available, Aircall does not provide a list of static IP addresses to whitelist.

Automatic deactivation

Aircall will automatically disable Webhooks after ten failed requests in a row.

A request is considered as failed if the HTTP Status Code answered is not 2XX or if the request times out. Make sure your server always answers a 200 HTTP Code, that will prevent Aircall Webhooks from being deactivated!

Aircall's HTTP requests sent to external web servers are set up to timeout after 5 seconds.

Filtering by Numbers

If the integration is built using the OAuth authentication method, Admins will be able to filter from which Numbers they want to receive Call events from on their Aircall Dashboard.

If the integration is using the Basic Auth method, Call webhook events will be sent for all Numbers of a Company.

Payload

Webhook events are sent with a JSON payload attached.

This payload mixes the JSON formatting of an Aircall's object (User, Number, Call, Contact) and some metadata like an absolute timestamp or the name of the event.

    Webhook attributes
  • resource
    String
    Name of the resource for this event.
    Can be number, user, contact or call.
  • event
    String
    Event's name for this payload.
    See the complete list here.
  • timestamp
    Integer
    UNIX timestamp for when the payload was built, in UTC.
  • token
    String
    Token associated to the Webhook. Use it to identify from which Aircall account a Webhook event is sent from.
  • data
    Object
    Modelization of the resource at the timestamp value.
    User, Number, Call or Contact for more info on the data structure.
Payload
{ "resource": "number", "event": "number.closed", "timestamp": 1585001020, "token": "45XXYYZZa08", "data": { "id": 456, "direct_link": "https://api.aircall.io/v1/numbers/123", "name": "My first Aircall Number", "digits": "+33 1 76 36 06 95", "country": "FR", "time_zone": "Europe/Paris", "open": false, "users": [ { "id": 456, "direct_link": "https://api.aircall.io/v1/users/456", "name": "Madelaine Dupont", "email": "madelaine.dupont@aircall.io", "available": false, "language": "en-US" } ] } }

User events

The following events refers to the User object.

Users can be invited by Aircall Admin users, from the Aircall Dashboard, or via the Public API (see here).

user.created

Sent when new users are invited in an Aircall company.s

Payload
{ "event": "user.created", "resource": "user", "timestamp": 1585601319, "token": "45XXYYZZa08", "data": { // the User object } }

user.deleted

Sent when users are deleted from an Aircall company by Admin users.

Payload
{ "event": "user.deleted", "resource": "user", "timestamp": 1589609314, "token": "45XXYYZZa08", "data": { // the User object } }

user.connected

Sent when users open their Aircall Phone.

Payload
{ "event": "user.connected", "resource": "user", "timestamp": 158555000, "token": "45XXYYZZa08", "data": { // the User object } }

user.disconnected

Sent when users close their Aircall Phone.

Payload
{ "event": "user.disconnected", "resource": "user", "timestamp": 1585603000, "token": "45XXYYZZa08", "data": { // the User object } }

user.opened

Sent when users become available according to their working hours.

Payload
{ "event": "user.opened", "resource": "user", "timestamp": 158556187, "token": "45XXYYZZa08", "data": { // the User object } }

user.closed

Sent when users become unavailable according to their working hours.

Payload
{ "event": "user.closed", "resource": "user", "timestamp": 158554819, "token": "45XXYYZZa08", "data": { // the User object } }

user.wut_start

Sent when user start their wrap up time (WUT) work according to their setting.

Payload
{ "event": "user.wut_start", "resource": "user", "timestamp": 158554819, "token": "45XXYYZZa08", "data": { // the User object } }

user.wut_end

Sent when user finishes their wrap up time (WUT) work according to their setting.

Payload
{ "event": "user.wut_end", "resource": "user", "timestamp": 158554819, "token": "45XXYYZZa08", "data": { // the User object } }

Call events

The following events refers to the Call object.

  • If your app is using the OAuth authentication method, Admins will be able to filter from which Numbers they want to receive Call events from on their Aircall Dashboard.

  • If your app is using the Basic Auth method, Call webhook events will be sent for all Numbers of a Company. You can implement this logic on your server!

Inbound calls

Here is a diagram showing when call events are being triggered during inbound calls:

Inbound Call flow

Outbound calls

Here is a diagram showing when call events are being triggered during outbound calls:

Outbound Call flow

call.created

Sent when a call is started.

  • For inbound calls, this event is sent when calls hits an Aircall number.
  • For outbound calls, this event is sent when Agents start a call from their Phone.
Payload
{ "event": "call.created", "resource": "call", "timestamp": 1585001000, "token": "45XXYYZZa08", "data": { // the Call object } }

call.ringing_on_agent

Sent when calls start ringing on Agents' Phone.

Payload
{ "event": "call.ringing_on_agent", "resource": "call", "timestamp": 1585001010, "token": "45XXYYZZa08", "data": { // the Call object } }

call.agent_declined

Sent when Agents decline inbound calls.

Payload
{ "event": "call.agent_declined", "resource": "call", "timestamp": 1585001020, "token": "45XXYYZZa08", "data": { // the Call object } }

call.answered

For inbound calls, this event is sent only when one Agent picks the call up.

For outbound calls, this event is sent only when the external person picks the call up.

The call direction is in the data object present in the payload.

Payload
{ "event": "call.answered", "resource": "call", "timestamp": 1585001020, "token": "45XXYYZZa08", "data": { // the Call object } }

call.transferred

Calls can be transferred either by Agents from their Aircall Phone, or via the Public API (see here).

  • When calls are transferred to another Agent, this event is sent when the other agent answers the call.
  • When calls are transferred to a Team, this event is sent when one agent answers the call.
  • When calls are transferred to an external number via the Aircall Phone, this event is not sent.
  • When calls are transferred to an external number via the Public API, this event is sent without the transferred_to field in the payload.

If the external party does not answer the call, call.transferred event will not be sent and call will return back to the original agent.

More details on Transferring calls in our Knowledge Base.

Payload
{ "event": "call.transferred", "resource": "call", "timestamp": 1585001030, "token": "45XXYYZZa08", "data": { // the Call object } }

call.unsuccessful_transfer

Calls can be transferred either by Agents from their Aircall Phone, or via the Public API (see here).

  • For calls that are unsuccessfully transferred to another Agent, this event is sent when the other agent doesn't answer the call.
  • For calls that are unsuccessfully transferred to a Team, this event is sent when no agent answers the call.
  • For calls that are unsuccessfully transferred to an external number via the Aircall Phone, this event is not sent.
  • For calls that are unsuccessfully transferred to an external number via the Public API, this event is sent when the external line is busy and without the transferred_to field in the payload.

More details on Transferring calls in our Knowledge Base.

Payload
{ "event": "call.unsuccessful_transfer", "resource": "call", "timestamp": 1585001030, "token": "45XXYYZZa08", "data": { // the Call object } }

call.hungup

Sent immediately after calls are hung up.

Some fields present in the payload body might be null as Aircall needs ~30sec to gather extra data like the duration and recording files.

This event must only be used to know when a call is hung up whereas call.ended and call.voicemail_left can be used to retrieve extra data such as the recording file, call duration etc.

Payload
{ "event": "call.hungup", "resource": "call", "timestamp": 1585001040, "token": "45XXYYZZa08", "data": { // the Call object } }

call.ended

Sent ~30sec after calls are actually hung up as Aircall server needs time to gather and process extra data like duration and recording files.

This event must only be used to retrieve all calls information whereas call.hungup can be used to know in real time when a call is ended.

Payload
{ "event": "call.ended", "resource": "call", "timestamp": 1585002050, "token": "45XXYYZZa08", "data": { // the Call object } }

call.voicemail_left

Sent ~30sec after calls end if a voicemail is present. Voicemail file will be included in the data object under the voicemail and asset fields.

Payload
{ "event": "call.voicemail_left", "resource": "call", "timestamp": 1585002050, "token": "45XXYYZZa08", "data": { // the Call object } }

call.commented

Calls can be commented, either by Agents from their Aircall Phone, or via the Public API (see here).

This event is sent when this action is performed and a new comment is created on a Call.

If the call is ongoing and the action is done by the agent in the in-call view, this event will be triggered at the end of the call.

Payload
{ "event": "call.commented", "resource": "call", "timestamp": 1585601319, "token": "45XXYYZZa08", "data": { // the Call object } }

call.tagged

Calls can be tagged either by Agents from their Aircall Phone, or via the Public API (see here).

This event is sent when this action is performed.

If the call is ongoing and the action is done by the agent in the in-call view, this event will be triggered at the end of the call.

Payload
{ "event": "call.tagged", "resource": "call", "timestamp": 1585601319, "token": "45XXYYZZa08", "data": { // the Call object } }

call.untagged

Tags can be removed from calls by Agents from their Aircall Phone.

This event is sent when this action is performed and does not apply on ongoing calls.

Payload
{ "event": "call.untagged", "resource": "call", "timestamp": 1585601319, "token": "45XXYYZZa08", "data": { // the Call object } }

call.assigned

Calls can be assigned to an Agent by another Agent, from the Aircall Phone.

This event is sent when this action is performed.

Payload
{ "event": "call.assigned", "resource": "call", "timestamp": 1585601319, "token": "45XXYYZZa08", "data": { // the Call object } }

call.archived

Calls can be archived (=mark as done) either by Agents from their Aircall Phone, or via the Public API (see here).

This event is sent when this action is performed.

Payload
{ "event": "call.archived", "resource": "call", "timestamp": 1585601319, "token": "45XXYYZZa08", "data": { // the Call object } }

call.hold

Sent when a call is put on hold.

Payload
{ "event": "call.hold", "resource": "call", "timestamp": 1585001000, "token": "45XXYYZZa08", "data": { // the Call object } }

call.unhold

Sent when a call is removed from on hold.

Payload
{ "event": "call.unhold", "resource": "call", "timestamp": 1585001000, "token": "45XXYYZZa08", "data": { // the Call object } }

Number events

The following events refers to the Number object.

Numbers can be bought and deleted by Aircall Admin users.

number.created

Sent when new numbers are created on Aircall accounts.

Payload
{ "event": "number.created", "resource": "number", "timestamp": 1585601319, "token": "45XXYYZZa08", "data": { // the Number object } }

number.deleted

Sent when numbers are deleted from Aircall accounts by Admin users.

Payload
{ "event": "number.deleted", "resource": "number", "timestamp": 1589609314, "token": "45XXYYZZa08", "data": { // the Number object } }

number.opened

Sent when a number opens according to its opening hours.

Payload
{ "event": "number.opened", "resource": "number", "timestamp": 158556187, "token": "45XXYYZZa08", "data": { // the Number object } }

number.closed

Sent when a number closes according to its opening hours.

Payload
{ "event": "number.closed", "resource": "number", "timestamp": 158554819, "token": "45XXYYZZa08", "data": { // the Number object } }

Contact events

The following events refers to the Contact object.

Contacts can be created, updated and deleted via the Aircall Phone and via the Public API (see here).

contact.created

Sent when new contacts are created on an Aircall account.

Payload
{ "event": "contact.created", "resource": "contact", "timestamp": 1585601319, "token": "45XXYYZZa08", "data": { // the Contact object } }

contact.updated

Sent when new contacts are updated on an Aircall account.

Payload
{ "event": "contact.updated", "resource": "contact", "timestamp": 158561587, "token": "45XXYYZZa08", "data": { // the Contact object } }

contact.deleted

Sent when new contacts are deleted on an Aircall account.

Payload
{ "event": "contact.deleted", "resource": "contact", "timestamp": 158562010, "token": "45XXYYZZa08", "data": { // the Contact object } }

Integration events

The following events refer to the Integration object.

Integrations can be created and deleted by Aircall Admin users.

integration.deleted

Sent when an integration is deleted. This event is only sent for webhooks created by applications that use Aircall OAuth credentials.

This event is useful for technology partners, to make sure uninstall flows are synced between Aircall and their application. When the integration is deleted in Aircall, we recommend deleting it on your side as well.

Payload
{ "event": "integration.deleted", "resource": "integration", "timestamp": 158554819, "token": "45XXYYZZa08", "data": { "integration_id": 42, "company_id": 1 } }

Extras

In this section, we will describe a few non-essential things to know when working with Aircall Public API, like Timezones, Phone numbers formats and emojis.

CTI - Aircall Everywhere SDK

Looking to build a more advanced integration with Aircall? Aircall Everywhere is a JavaScript SDK that lets you embed and control the Phone app in your website.

The Phone app will be loaded in a HTML iframe and will send events to your main page when incoming calls are ringing, when calls are answered, when agents log in... You can also send instructions to the Phone app such as dial a number or exit the keyboard! The full list of events is available on GitHub.

A demo website is available here and the full documentation of it is available on GitHub!

import AircallPhone from 'aircall-everywhere';

const aircallPhone = new AircallPhone({
  onLogin: settings => {
    console.log('phone loaded');
    doStuff();
  },
  onLogout: () => {},
  domToLoadPhone: '#phone',
  integrationToLoad: 'zendesk',
  size: 'big'
});

Dealing with phone numbers

Aircall uses international phone number formatting in its Public API.

But dealing with phone number formatting can be complex and time consuming. We recommend using libphonenumber, built by Google, complete and up-to-date!

It extracts useful information from any phone number, like the number's type (mobile, toll-free, landline...), the country, the international/national/e164 format...

SIP trunking

Aircall uses several providers under the hood to buy and configure phone numbers all around the World.

As each provider is specific, Aircall does not offer SIP trunking capabilities or any advanced voice feature via its Public API yet!

The best way to get access to the audio data is to get the recording mp3 file URL at the end of a Call.

Timezones

Aircall dates and times are rendered in UTC.

Timezones listed in Aircall's products follow the tz database format.

Emojis

We love emojis, but they don't fit well everywhere in our products (yet!). You can display emojis in Insight Cards, to make caller insights displayed on the phone more compelling 💅 . For the rest, the Public API will return an error if you try to update any string with an emoji 😱

Changelog

There's only one version of our Public API. This changelog is here to present fields and endpoints that have been added overtime!

    Versions
  • 1.26.0
    2021-09-22
    Add call.hold and call.unhold event Webhook
  • 1.25.0
    2021-09-27
    When a call is transferred to an external number via the Public API, transfer Webhook events are now fired.
  • 1.24.0
    2021-09-20
    Add user.wut_start and user.wut_end event Webhook
  • 1.23.0
    2021-09-15
    Remove User available and availability_status parameters on Teams. Those properties didn't reflect the correct value, use User endpoint directly for it.
  • 1.22.0
    2021-07-30
    Add priority parameter on Number. This property is used during routing to dequeue the agent's tasks. Can be null, 0 (no priority) or 1 (top priority). Default null
  • 1.21.0
    2021-08-17
    Update the endpoint [POST] /v1/contacts, phone_numbers parameter is mandatory to create a contact.
  • 1.20.0
    2021-06-14
    Add transferred_by parameter on Call
  • 1.19.0
    2021-04-28
    Add call.unsuccessful_transfer event Webhook
  • 1.18.0
    2021-03-31
    Add [POST] v1/integrations/enable and [POST] v1/integrations/disable to Integration endpoints.
  • 1.17.0
    2021-02-18
    Add integration.deleted Webhook event.
  • 1.16.0
    2021-02-17
    Add Participants to [GET] v1/calls/:id endpoint. The participant is a representation of a member in a conference call.
  • 1.15.0
    2021-01-12
    Add dispatching_strategy parameter on Call transfer.
  • 1.14.0
    2020-11-26
    Add User to [GET] v1/integrations/me endpoint. The user is the one that installed the integration.
  • 1.13.0
    2020-11-26
    Add language attribute on User object.
  • 1.12.2
    2020-11-20
    When an inbound call is anonymous, the raw_digits value is anonymous .
  • 1.12.2
    2020-11-10
    Scope the webhook access: it is now only possible to list, update and delete webhooks linked to the request credentials.
  • 1.12.1
    2020-11-04
    Update the endpoint [DELETE] v1/calls/:id/recording, it takes between 10 and 15 minutes to delete a call's recording from our servers.
  • 1.12.0
    2020-10-02
    Add time_zone parameter on User object.
  • 1.11.3
    2020-09-16
    Make call's recording and voicemail links valid for strictly 10 minutes (as specified in this API reference). Call's asset link is still valid forever
  • 1.11.2
    2020-06-22
    Add a user type to the Insight Card model.
  • 1.11.1
    2020-04-15
    When call is ringing, transfering to a team is now limited to teams with 25 users or less.
    Transfering to a user or after call as been answered is unchanged.
  • 1.11.0
    2020-04-14
    New documentation design for this API References! 🎉
  • 1.10.1
    2019-11-21
    Deprecate the [POST] /v1/calls/:id/metadata and [POST] /v1/calls/:id/link endpoints, available on the Call object.
  • 1.10.0
    2019-04-08
    Add [GET] /v1/users/availabilities and [GET] /v1/users/:id/availability to Users endpoints.
  • 1.9.1
    2019-02-08
    Add number parameter for external call transfers via Public API.
  • 1.9.0
    2019-01-10
    Add [DELETE] /v1/teams/:id endpoint on Team object.
  • 1.8.9
    2018-11-26
    Add created_at parameter on Number, User, Team and Webhook objects.
  • 1.8.8
    2018-11-07
    Add cost parameter on Call object.
  • 1.8.7
    2018-07-24
    Add call.voicemail_left Webhook event.
  • 1.8.6
    2018-07-09
    Add [DELETE] /v1/users/:id endpoint on User object.
  • 1.8.5
    2018-06-27
    Add live_recording_activated to Number.
  • 1.8.4
    2018-06-27
    Add is_shared attribute to Contact object.
  • 1.8.3
    2018-06-26
    New [POST] /v1/users/:id/dial endpoint for User object.
  • 1.8.2
    2018-06-15
    Add possibility to transfer a call to a Team.
  • 1.8.1
    2018-05-31
    Add call.agent_declined Webhook event.
  • 1.8.0
    2018-05-30
    Add call.ringing_on_agent Webhook event.
  • 1.7.9
    2018-05-25
    New [POST] /v1/users/:id/calls endpoint for User object.
  • 1.7.8
    2018-05-16
    Add asset attribute to the Call object.
  • 1.7.7
    2018-04-25
    New [POST] /v1/calls/:id/pause_recording and [POST] /v1/calls/:id/resume_recording endpoints for Call object.
  • 1.7.6
    2018-04-03
    New [POST] /v1/calls/:id/tags endpoint for Tags.
  • 1.7.5
    2018-04-02
    Add Tag actions via Public API.
  • 1.7.4
    2018-03-20
    Allow user_id and phone_number query params on [GET] /v1/calls/search search endpoint. Add call.transferred Webhook event.
  • 1.7.3
    2018-01-11
    Allow emails and phone_number update via [PUT] /v1/contacts/:id Contact update endpoint.
  • 1.7.2
    2017-12-16
    Add call.tagged, call.untagged and call.commented Webhook events.
  • 1.7.1
    2017-12-15
    New [POST] /v1/calls/:id/comments route to add a comment to a call.
  • 1.7.0
    2017-12-05
    Add Team creation via Public API.
  • 1.6.0
    2017-11-22
    Add User creation via Public API.
  • 1.5.0
    2017-10-02
    Add Webhooks management via Public API.
  • 1.4.4
    2017-09-18
    Add possibility to update User's & Number's name.
  • 1.4.3
    2017-09-15
    Add call.hungup event to Webhooks object.
  • 1.4.2
    2017-09-06
    Add is_ivr parameter on Number object.
  • 1.4.1
    2017-07-21
    Add order_by parameter on Contact list.
  • 1.4.0
    2017-03-07
    Add availability_status update on Users and Numbers objects.
  • 1.3.0
    2017-01-16
    Add user.connected and user.disconnected events for Webhooks.
  • 1.2.0
    2016-11-08
  • 1.1.7
    2016-10-23
    Add search by tags on Call list.
  • 1.1.6
    2016-05-23
    Add information field on Contact object.
  • 1.1.5
    2016-05-02
    Add tags in Call object.
  • 1.1.3
    2015-10-08
    Add call.answered event for Webhooks.
  • 1.1.2
    2015-10-01
    Add two timestamps in Call object.
  • 1.1.1
    2015-09-28
    Add recording URL in Call object.
  • 1.1.0
    2015-08-03
    API public release.
  • 1.0.9
    2015-07-31
    API beta release.
  • 1.0.4
    2015-07-30
    Add comments to Call object.
  • 1.0.3
    2015-07-29
    Add assignment to Call object.
  • 1.0.2
    2015-07-28
    Introducing direct API links.
  • 1.0.1
    2015-07-27
    Update Contact object.
  • 1.0.0
    2015-06-02
    Public release.
  • 0.9.0
    2015-05-25
    Beta release.
  • 0.1.0
    2015-05-18
    Alpha release.
  • 0.0.1
    2015-05-10
    🎉 Initial release.

Aircall Developer