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.

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.

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

Not a Developer?

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

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

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

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

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

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.

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

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

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

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

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

Oauth terminology
• install_uri

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

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

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

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

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

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

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

OAuth credentials

Before starting building the OAuth flow for your app, you will need to get OAuth client_id and client_secret from Aircall. 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

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

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

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

Get an access_token via the Public API

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

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

Body params
• client_id

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

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

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

  String
  Your redirect_uri.
  Mandatory field.
• grant_type

  String
  Must be authorization_code.
  Mandatory field.

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.

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.

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!

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:

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

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

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

The meta object
• count

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

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

  Integer
  Current page number.
• per_page

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

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

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

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

Query params
• page

  Integer
  Current page.
  Default is 1.
• per_page

  Integer
  Number of results retrieved per page
  Default is 20.

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

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.

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

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

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

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

Get all users associated to an Aircall account, or retrieve, create and update info about one specific User! You can also start outbound calls on 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!

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.

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.

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

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

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

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

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

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

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.

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.

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

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.

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.

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.

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.

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.

Retrieve details of a specific Team.

Path params
• id

  Integer
  Unique identifier for the 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.

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.

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.

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.

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 ended_at - started_at.
• status

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

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

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

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

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

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

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

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

  Boolean
  Describe if Call needs follow up.
• missed_call_reason

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

  String
  Cost of the Call in U.S. cents.
  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.
• ivr_options

  Array
  IVR options selected in a smartflow enabled number.
  ivr_options is not retrievable via Call APIs.

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.

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

Query params
• from

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

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

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

  Boolean
  when sets to true, adds contacts details in response

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!

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

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

Path params
• id

  Integer
  Unique identifier for the Call.
• fetch_contact

  Boolean
  when sets to true, adds contacts details in response

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

Query params
• from

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

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

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

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

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

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

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

  Boolean
  when sets to true, adds contacts details in response

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!

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.

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

Path params
• id

  Integer
  Unique identifier for the Call.

Body params
• user_id

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

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

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

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

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.

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.

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

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.

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

Path params
• id

  Integer
  Unique identifier for the 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Retrieve details of a specific Numbers.

Path params
• id

  Integer
  Unique identifier for the 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.
  This cannot be updated when number have smartflow enabled.
• is_ivr

  Boolean
  If true, Number will be converted into an IVR. Classic otherwise.
  This cannot be updated when number have smartflow enabled.
• 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.
  This cannot be updated when number have smartflow enabled.

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.

Contacts are a core part of Aircall experience.

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

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

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

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

Attributes
• id

  Integer
  Unique identifier for the Contact.
• direct_link

  String
  Direct API URL.
• first_name

  String
  Contact's first name.
• last_name

  String
  Contact's last name.
• company_name

  String
  Contact's company name.
• description

  String
  Field used by Aircall to qualify tags.
• information

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

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

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

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

Phone numbers attribute
• id

  Integer
  Unique identifier for this phone number.
• label

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

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

Emails attribute
• id

  Integer
  Unique identifier for this email address.
• label

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

  String
  The email address.

Emojis can't be used in Contact's attributes (they will be removed).

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!

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!

Retrieve details of a specific Contact.

Only shared contacts can be found.

Path params
• id

  Integer
  Unique identifier for the 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.
  Can’t exceed 255 characters
• last_name

  String
  Can't be blank if defined.
  Can’t exceed 255 characters
• company_name

  String
  Can't be blank if defined.
  Can’t exceed 255 characters
• information

  String
  Can't be blank if defined.
• emails

  Array
  Array of email address objects.
  For each email, label and value must be set. Limit of 20 emails, beyond, a 400 error will be returned
• phone_numbers

  Array
  Array of phone_numbers objects.
  Mandatory field. For each phone_number, label and value must be set. Limit of 20 phone numbers, beyond, a 400 error will be returned

Duplicate calls to POST /v1/contacts with the same payload will create duplicate contacts.

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.

Delete a contact from the Company.

Only shared contacts can be deleted.

Path params
• id

  Integer
  Unique identifier for the Contact.

Phone numbers can be added one by one to a Contact (with a limit of 20, beyond 20 numbers, a 409 error will be returned).

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. The number needs to be valid, if not, agents won't be able to dial the contact
  Mandatory field.

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.

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.

Emails can be added one by one to a Contact (with a limit of 20, beyond 20 emails, a 409 error will be returned).

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.

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.

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.

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.

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.
  In Hexadecimal format.
• description

  String
  Field used by Aircall to qualify Tags.

Emojis can't be used in Tag's attributes (they will be removed).

Fetch all Tags associated to a company and their information.

Pagination params can be used on this request.

Retrieve details of a specific Tag.

Path params
• id

  Integer
  Unique identifier for the 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.

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.

Tag will be removed from Calls.

Path params
• id

  Integer
  Unique identifier for the Tag.

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.
  It’s recommend to use value in property “Webhook_id” instead of “id” to retrieve, update and delete a Webhook using APIs. The property “Webhook_id” will be returned on creation of a Webhook . The property “id” will be deprecated in future.
• webhook_id

  string (uuid)
  New 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.

Fetch all Webhooks associated to a company and their information.

It’s recommend to use value in property “Webhook_id” instead of “id” to retrieve, update and delete a Webhook using APIs. The property “Webhook_id” will be returned on creation of a Webhook . The property “id” will be deprecated in future

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.

Retrieve details of a specific Webhook.

Path params
• id

  Integer / String
  Unique identifier for the Webhook.
  webhook_id should be used as id

It’s recommend to use value in property “Webhook_id” instead of “id” to retrieve, update and delete a Webhook using APIs. The property “Webhook_id” will be returned on creation of a Webhook . The property “id” will be deprecated in future

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.

It’s recommend to use value in property “Webhook_id” instead of “id” to retrieve, update and delete a Webhook using APIs. The property “Webhook_id” will be returned on creation of a Webhook . The property “id” will be deprecated in future

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.

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 / String
  Unique identifier for the Webhook.
  webhook_id should be used as id

It’s recommend to use value in property “Webhook_id” instead of “id” to retrieve, update and delete a Webhook using APIs. The property “Webhook_id” will be returned on creation of a Webhook . The property “id” will be deprecated in future

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.

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 / String
  Unique identifier for the Webhook.
  webhook_id should be used as id

It’s recommend to use value in property “Webhook_id” instead of “id” to retrieve, update and delete a Webhook using APIs. The property “Webhook_id” will be returned on creation of a Webhook . The property “id” will be deprecated in future

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.

Company information can be retrieve with this GET request.

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

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.

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.

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

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

The IVR Option object is a representation of ivr option selected in smartflow enabled number

IVR object are not retrievable, updatable nor destroyable via Aircall Public API.

IVR information is only present in calls on smartflow enabled numbers and it can be accessed inside the call object.

Attributes
• id

  String
  Id of the ivr option selected
• title

  String
  Title of the ivr option selected
• key

  String
  Key pressed by the caller in ivr widget
• created_at

  Integer
  Timestamp when the ivr option is selected, in UNIX timestamp

In order to comply to 10DLC regulation in the US, partners have to associate their Aircall numbers with campaigns previously declared with TCR (The Campaign Registry).

Aircall Public API allows any developer to fetch, create, update and delete A2P campaign associations to numbers. This process involving external APIs of carriers and TCR is executed asynchronously. This mean each API call will be taken into account immediately but those changes will be propagated to the external services after few seconds. A status column is exposed on the configuration entity to let you know what is the status of the background operation. Following any creation or update action this statuswill be pending and updated to done once the background operation is completed. In case of error status will be set to failed with additional information in the updateMessage field.

Fetch all A2P campaign associations associated to a Company and their information.

Pagination params can be used on this request.

Retrieve details of a specific A2P campaign association.

Path params
• id

  Integer
  Unique identifier for the A2P campaign association.

A2P campaign association are created via this endpoint to associate Aircall numbers to an external campaign previously declared in TCR. After creation, a unique ID will be included in the response's payload for further actions.

Aircall numbers can be associated to a single 10DLC campaign. Trying to associate a number to multiple campaigns or associating a campaign twice will result in bad request error.

Body params
• external_campaign_id

  String
  TCR external campaign Id.
  Mandatory field.
• numbers

  Array<String>
  List of numbers in e.164 format (without + prefix) to associate to the A2P campaign.
  Mandatory field.

Aircall numbers associated to an existing A2P campaign association can be updated via this endpoint. The numbers associated will be fully replaced by the one provided in the udpate payload.

Aircall numbers can be associated to a single 10DLC campaign. Trying to associate a number to multiple campaigns via this endpoint will result in bad request error.

Path params
• id

  Integer
  Unique identifier for the A2P campaign association.

Body params
• numbers

  Array<String>
  List of numbers in e.164 format (without + prefix) to associate to the existing A2P campaign.
  Mandatory field.

Deletes an existing A2P campaign association.

This endpoint deletes the association of Aircall numbers to the A2P external campaign but does not modify the campaign itself.

Path params
• id

  Integer
  Unique identifier for the A2P campaign association.

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

• user.created
• user.deleted
• user.connected
• user.disconnected
• user.opened
• user.closed
• user.wut_start
• user.wut_end

Number's events

• number.created
• number.deleted
• number.opened
• number.closed

Call's events

• call.created
• call.ringing_on_agent
• call.agent_declined
• call.answered
• call.transferred
• call.unsuccessful_transfer
• call.hungup
• call.ended
• call.voicemail_left
• call.assigned
• call.archived
• call.tagged
• call.untagged
• call.commented
• call.hold
• call.unhold
• call.ivr_option_selected
• call.comm_assets_generated

Contact's events

• contact.created
• contact.updated
• contact.deleted

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.

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

For failed events, Aircall will perform fifty (50) retries and post that if the issue still persists webhook will be disabled and no new events will be sent. An alert on Aircall Dashboard will also indicate webhook being disabled.

Once Webhook is disabled, Aircall will retry only failed events for next 12 hours. In case, a success message is received for failed event(s) the webhook will be automatically enabled.

Admin users can receive email notification regarding webhook being disabled or enabled by enabling email notification via user settings in Aircall dashboard.

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.

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.

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

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

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

Sent when users open their Aircall Phone.

Sent when users close their Aircall Phone.

Sent when users become available according to their working hours.

Sent when users become unavailable according to their working hours.

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

If wrap up time is set as zero and have mandatory call tagging enabled, user.wut_start event will be sent if user tags the call at the end of the call. However if call was tagged during the call(having mandatory call tagging enabled), the event would not be sent.

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

If wrap up time is set as zero and have mandatory call tagging enabled, user.wut_end event will be sent if user tags the call at the end of the call. However if call was tagged during the call(having mandatory call tagging enabled), the event would not be sent.

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:

Outbound calls

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

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.

Sent when calls start ringing on Agents' Phone.

Sent when Agents decline inbound calls.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

This event is sent when this action is performed.

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.

Sent when a call is put on hold.

Sent when a call is removed from on hold.

Sent after ivr option is selected on a smartflow enabled number.

This event must only be used to know when a ivr option is selected on a smartflow enabled number.

Event is sent when communication assets for a call i.e. call recording or voicemail is generated. Only one event per call is sent. This event can be referred if call recording or voicemail link is not available in call.ended event.

This event will be sent only when a call is recorded or a voicemail is left.

The following events refers to the Number object.

Numbers can be bought and deleted by Aircall Admin users.

Sent when new numbers are created on Aircall accounts.

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

Sent when a number opens according to its opening hours.

Sent when a number closes according to its opening hours.

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

Sent when new contacts are created on an Aircall account.

Sent when new contacts are updated on an Aircall account.

Sent when new contacts are deleted on an Aircall account.

The following events refer to the Integration object.

Integrations can be created and deleted by Aircall Admin users.

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.

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

Versions
• 1.34.0

  2024-04-04
  Deprecate isAdmin parameter in the Create a User endpoint.
• 1.33.0

  2024-03-25
  Add recording_short_url and voicemail_short_url attributes in Call object for webhook events.
• 1.32.0

  2024-03-04
  Add call.ivr_option_selected and call.comm_assets_generated event event Webhook
• 1.31.0

  2023-11-02
  Update of Webhook Automatic deactivation Process.
• 1.30.0

  2023-09-28
  Change call history window time from 6 months to 3 months.
• 1.29.0

  2023-09-19
  Add wrap_up_time input parameter for User's Create and Update methods.
• 1.28.1

  2023-07-13
  Add Information regarding using Number API with Smartflow enabled Numbers.
• 1.28.0

  2023-05-17
  Introduce a new property webhook_id for Webhook endpoints.
• 1.27.0

  2022-09-30
  Introduce a limit of 20 for Contact's emails and phone_numbers
• 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
  Add transfers endpoint.
• 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.

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.

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!

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

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.

Aircall dates and times are rendered in UTC.

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

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 😱