Introduction

{
  "resource": "Aircall Documentation",
  "version": "1.4.0",
  "contact": "dev@aircall.io"
}

Feel free to ping us if you’ve suggestions!

Welcome on Aircall for Developers! Just like you, we are enthusiastic web developers and we love to automate things. With 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 your Aircall data. Please find below the full documentation and API reference in order to reach this goal. Happy hacking!

We’re supporting Webhooks. It means that we’re able to call back an endpoint of your choice each time an event occured on your Aircall account (contact added, call created, user switched off… see the events section for a complete list). Webhooks allow you to build many integrations with third-parties you already use (Slack, Zendesk, Zapier…) and require only to set up a public web server.

We’re also maintaining a public API. This service allows you to retrieve your data. For User, Number and Call objects, we are currently supporting index and read actions. For Contact object, we are supporting all of common actions and, bonus point, you’ll be able to perform searches within your contacts!

If you want to know our future plans, feel free to check our public roadmap and upvote your favorite items!

Objects

Aircall data are structured around 4 main types of objects: Number, User, Contact and Call. Whatever you are using (API or Webhooks), you’ll find these objects in the format described below.

Number

Example of a Number object

{
  "id": 123,
  "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": true,
  "users": [
    {
      "id": 456,
      "direct_link": "https://api.aircall.io/v1/users/456",
      "name": "Madelaine Dupont",
      "email": "madelaine.dupont@aircall.io",
      "available": false
    }
  ]
}

The Number object is a modelization of Aircall’s numbers like you see them in your dashboard (on the left part).

Field	Type	Description
id	Integer	Unique ID of this number
direct_link	String	API endpoint
name	String	The name of your Aircall’s Number
digits	String	International format of the number
country	String	2 characters code for the country
time_zone	String	Time zone of the number set in the dashboard
open	Boolean	Current state of the number
availability_status	String	Current availability status of the number. Can be open, custom or closed
users	Array	List of User linked to this number

There is a lot of libraries that can handle phone numbers’ formatting. We are using libphonenumber, a complex (and complete!) list of Regex pusblished by Google.

User

Example of a User object

{
  "id": 456,
  "direct_link": "https://api.aircall.io/v1/users/456",
  "name": "Madelaine Dupont",
  "email": "madelaine.dupont@aircall.io",
  "available": "false",
  "numbers": [
    {
      "id": 123,
      "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": true
    }
  ]
}

The User object is a modelization of Aircall’s users like you see them in your dashboard (on the right part).

Field	Type	Description
id	Integer	Unique ID of this user
direct_link	String	API endpoint
name	String	Full name of the user
email	String	Email of the user
available	Boolean	Availability status of the user
availability_status	String	Current availability status of the user. Can be available, custom or unavailable
numbers	Array	List of Number linked to this user

Contact

Example of a Contact object

{
  "id": 789,
  "direct_link": "https://api.aircall.io/v1/contacts/789",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme",
  "information": "",
  "phone_numbers": [
    {
      "label": "Work",
      "value": "+33631000000"
    }
  ],
  "emails": [
    {
      "label": "Work",
      "value": "john.doe@something.io"
    }
  ]
}

The Contact object is a modelization of Aircall’s contacts like you see them in your Aircall App.

Field	Type	Description
id	Integer	Unique ID of this contact
direct_link	String	API endpoint
first_name	String	First name of the contact
last_name	String	Last name of the contact
company_name	String	Company name of the contact
information	String	Extra information about the contact
phone_numbers	Array	Phone numbers of this contact
emails	Array	Email addresses of this contact

Phone numbers and email addresses are special properties of the Contact object. Each entry is using extra fields describing its value.

Field	Type	Description
label	String	Type of contact for this entry
value	String	Raw email address or phone number

Phone number’s values should be formatted as E.164. This is a standard format we are using for the API too.

Please contact us for specific needs on this object. Contact’s management is something hard because of the diversity of the sources and we don’t want to create a pain on that subject.

Call

Example of a Call object

{
  "id": 1234567,
  "direct_link": "https://api.aircall.io/v1/calls/1234567",
  "status": "done",
  "direction": "inbound",
  "started_at": 1431272855,
  "answered_at": 1431272875,
  "ended_at": 1431272928,
  "duration": 32,
  "raw_digits": "+33631000000",
  "voicemail": "https://voicemails.com/010203",
  "recording": "https://recordings.com/090807",
  "archived": false,
  "number": {
    "id": 123,
    "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": true
  },
  "user": {
    "id": 456,
    "direct_link": "https://api.aircall.io/v1/users/456",
    "name": "Madelaine Dupont",
    "email": "madelaine.dupont@aircall.io",
    "available": "false"
  },
  "contact": {
    "id": 789,
    "direct_link": "https://api.aircall.io/v1/contacts/789",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": "Acme",
    "phone_numbers": [
      {
        "label": "Work",
        "value": "+33631000000"
      }
    ],
    "emails": [
      {
        "label": "Work",
        "value": "john.doe@something.io"
      }
    ]
  },
  "assigned_to": {
    "id": 212,
    "direct_link": "https://api.aircall.io/v1/users/212",
    "name": "Josh Smith",
    "email": "josh.smith@aircall.io",
    "available": "false"
  },
  "comments": [],
  "tags": []
}

The Call object is a modelization of Aircall’s calls like you see them in your Activity Feed. The structure is a mix of other objects.

Field	Type	Description
id	Integer	Unique ID of this call
direct_link	String	API endpoint
status	String	Current status of the call. Could be initial, answered or done
direction	String	Direction of the call. Could be inbound or outbound
started_at	Integer	UNIX timestamp when the call started
answered_at	Integer	UNIX timestamp when the call has been answered
ended_at	Integer	UNIX timestamp when the call ended
duration	Integer	Duration of the call in seconds
raw_digits	String	International format of the number of the caller or the callee
voicemail	String	If present, the full URL of a voicemail for this call
recording	String	If present, the full URL of a live recording for this call
archived	Boolean	Tells you if this call needs follow up
number	Object	Number attached to this call
user	Object	User who took or made the call
contact	Object	Contact attached to this call
assigned_to	Object	User assigned to this call
comments	Array	Notes added to this call
tags	Array	Tags added to this call

In order to analyze this object, you can follow these steps:

1. Check the status of the call. Every ended call has its status set to “done” and has been hangup.
2. Discover the metadata of the call by reading the direction and duration fields.
3. Link the raw_digits of the callee (for an outbound call) or the caller (for an inbound call) to your own data.
4. Listen to the voicemail if the value is not empty.
5. Inspect number, user and contact in order to make something particular for this call like archive, call back or compute analytics!

API

The root endpoint of Aircall API is: https://api.aircall.io/v1. We recommend you to fetch our API over https.

Authentication

If you’re using curl, try this…

> curl https://apiID:apiToken@api.aircall.io/v1/ping

You should get the response { “ping”: pong }

In order to start using API, you need an Aircall account. Sign up if you don’t have one.

Once you’re logged in, go to your company’s settings and open the developer section. Click on Add a new API key and get your API ID and your API token in order to start using the API. Do not forget to copy/paste your API token somewhere, we don’t store it as plain text!

We use HTTP basic authentication in order to authorize API requests. Just add your API ID as username and your API token as password to each of your API requests.

Please note that you can create as many API keys as you want. Feel free to create a lot of applications with your data and ping us if you think we should integrate one of them directly into Aircall.

Usage

GET https://api.aircall.io/v1/numbers

{
  "meta": {
    "count": 2,
    "current_page": 1,
    "per_page": 2,
    "next_page": "https://api.aircall.io/v1/numbers?page=2&per_page=2",
    "previous_page": null
  },
  "numbers": [
    {
      "id": 123,
      "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": true
    },
    {
      "id": 444,
      "direct_link": "https://api.aircall.io/v1/numbers/444",
      "name": "My second Aircall Number",
      "digits": "+1 510 444 8209",
      "country": "US",
      "time_zone": "US/Pacific",
      "open": false
    }
  ]
}

We’re currently limiting the rate of API requests to 60 requests per minute per company. You can use extra headers available in API responses.

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.

Tell us if you need to make more requests per minute, we would add a higher rate limit to your API keys.

Each API response is formatted as JSON. We encapsulate data under the name of the resource (plural form if it’s a list). When you’re retrieving a list of objects, we are sending a meta property in order to allow you to browse objects easily.

Property	Description
count	number of resources in the response,
current_page	index of pagination,
per_page	number of objects sent per page,
next_page	URL to be fetched for more objects,
previous_page	URL to be fetched for the previous objects.

Endpoints

GET https://api.aircall.io/v1/contacts/789

{
  "contact": {
    "id": 789,
    "direct_link": "https://api.aircall.io/v1/contacts/789",
    "first_name": "John",
    "last_name": "Doe",
    "company_name": "Acme",
    "phone_numbers": [
      {
        "label": "Work",
        "value": "+33631000000"
      }
    ],
    "emails": [
      {
        "label": "Work",
        "value": "john.doe@something.io"
      }
    ]
  }
}

Currently, we have 19 endpoints you can fetch when you’re authenticated.

Method	Path	Description
GET	/ping	Test purpose
GET	/company	Generic data about the account
GET	/users	List of users
GET	/users/:id	Retrieve data for a specific User
PUT	/users/:id	Update data for a specific User
GET	/numbers	List of numbers
GET	/numbers/:id	Retrieve data for a specific Number
PUT	/numbers/:id	Update data for a specific Number
GET	/calls	List of calls
GET	/calls/search	Search for calls
GET	/calls/:id	Retrieve data for a specific Call
POST	/calls/:id/link	Display a link in-app to the User who answered a specific Call
POST	/calls/:id/transfers	Transfer the Call to another user (see details below)
DELETE	/calls/:id/recording	Delete the recording of a specific Call, this action cannot be undone
DELETE	/calls/:id/voicemail	Delete the voicemail of a specific Call, this action cannot be undone
GET	/contacts	List of contacts
GET	/contacts/search	Search within contacts (see parameters below)
POST	/contacts	Create a new Contact
GET	/contacts/:id	Retrieve data for a specific Contact
POST	/contacts/:id	Update data for a specific Contact
DELETE	/contacts/:id	Delete a specific Contact

You’ve to replace :id by the effective ID of the object.

Please refer to the Contact object description in order to see which parameters you should send to our API. We’ll perform validation before inserting new contacts (like presence of a name or value of a field).

Transfer a call

POST https://api.aircall.io/v1/calls/123/transfers

{
  "user_id": 456
}

If you want to transfer a Call to another User, you have to provide its ID in the request’s body.

Parameter	Description
call_id	ID of the call to transfer

Property	Description
user_id	ID of the user you want to transfer the call to

Here are the possible HTTP codes for the response:

HTTP Code	Description
204	Success
400	The given call has already ended
404	User not found or Call not found

Extra parameters

When you’re browsing or performing searches within objects, you can add extra parameter to your queries, as GET parameters.

Parameter	Description	Default
page	Pagination for list of objects	1
per_page	Number of objects fetched per request	50
order	Reorder entries per creation date, asc or desc	asc
from	Set a minimal creation date for objects (UNIX timestamp)	(none)
to	Set a maximal creation date for objects (UNIX timestamp)	(none)

If you’re performing searches within contacts, you would like to add some parameters in order to retrieve them.

Parameter	Description
phone_number	Phone number of a contact you’re searching for
email	Email address of a contact you’re searching for

If you want to display a specific link in-app to an User who answered a specific Call, you can use the related endpoint. Please also add the link in the body of your request as a JSON object.

Parameter	Description
link	Link you want to display in-app

If you’re performing searches within calls, you would like to add some parameters in order to retrieve them.

Parameter	Description
tags	Tags of a call you’re searching for (it will match all the tags if you send an array)

Webhooks

Register endpoints

If you’re using ngrok, typing this…

ngrok -subdomain=my-webhooks 80

…will create https://my-webhooks.ngrok.com

In order to start using webhooks, you need an Aircall account. Sign up if you don’t have one.

Once you’re logged in, go to your company’s settings and open the developer section. Click on Add a new integration and add a valid URL in the text field. Select the events you want to subscribe and… you’re ready to work with webhooks!

Please note that you can register as many webhooks as you want. Feel free to mix events in order to create a powerful automation of your phone system.

Usage

Example of a simple web server written in NodeJS

var http = require('http');

var server = http.createServer(function (req, res) {
  response.end('ok');
});

server.listen(80);

Each time an event occurs on your Aircall account, we are calling back your webhooks. It means that you can build automated tasks, specific to your business, based on these events. Find below the list of events and their description.

Once you’ve registered endpoints, you need to set up a simple web server in order to receive events on these endpoints. Events are sent through payloads and your server needs only to allow POST requests and has to be able to parse JSON in order to read them.

Payloads

Example of a JSON payload

{
  "resource": "number",
  "event": "number.closed",
  "timestamp": 1431272855,
  "token": "1f9c0c4f16f1afad6b00dc998f3d41ce",
  "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
      }
    ]
  }
}

When we trigger an event, we build a JSON payload and send it to your webhook. This payload mixes the JSON formatting of an Aircall’s object (Number, User, Contact, Call) and some metadata like an absolute timestamp or the name of the event.

Field	Type	Description
resource	String	Name of the resourcefor this event. Could be number, user, contact or call
event	String	Event’s name for this payload. See the complete list below
timestamp	Integer	UNIX timestamp when the payload was built
token	String	Unique token used by Aircall in order to authenticate the request
data	Object	Modelization of the resource at the timestamp value

Of course, you can mix webhooks with our API. A best practice could be to fetch the direct link each time you receive a webhook in order to get the latest data about an object.

Examples

We would like to share with you some implementations of webhooks. We’ve already built Slack, Zendesk and Zapier integrations in order to make them directly available from your dashboard (ie without coding)!

• Slack: Get notified of events on your Aircall account directly into Slack. Add calls in your favorite chat tool!
• Zendesk: Create tickets from missed calls. Give some super powers to your support team!
• Zapier: Build your own custom integrations without coding. Start automating your workflows in two minutes!

Events

Here is the complete list of events sent on webhooks. We refresh every half hour the availability of each number and user for the events “opened” and “closed”.

Name	Description
number.created	When a new number is created on your account
number.opened	When a number opens according to its opening hours
number.closed	When a number closes according to its opening hours
number.deleted	When a number is deleted on your account
contact.created	When a new contact is created on Aircall
contact.updated	When a contact is updated on Aircall
contact.deleted	When a contact is deleted on Aircall
user.created	When a new user is created on your account
user.opened	When an user becomes available according to its working hours
user.connected	When an user is logged in Aircall Phone
user.closed	When an user becomes unavailable according to its working hours
user.disconnected	When an user is logged out of Aircall Phone
user.deleted	When a user is deleted on your account
call.created	When a new call starts
call.answered	When a call is answered
call.ended	When a call ends on your account
call.assigned	When a call is assigned to someone
call.archived	When a call is archived

Feel free to contact us if we forgot some valuable events. We could add them in order to fit your needs!

Libraries

Currently we don’t provide libraries for specific programming languages. However, our webhooks and API use JSON. This format is widespread in the web ecosystem and you can easily find a parser for your favorite language :)

Feel free to ping us if you’ve special queries on this subject or if you built an open-source library for Aircall in order to share it with our community!

Changelog

Date	Version	Changes
2017-03-07	1.4.0	Add availability_status update on Users and Numbers objects
2017-01-16	1.3.0	Add user.connected and user.disconnected events for Webhooks
2016-11-08	1.2.0	Add transfers endpoint
2016-10-24	1.1.8	Add delete endpoints on Call object
2016-10-23	1.1.7	Add search by tags on Call list
2016-05-23	1.1.6	Add information field on Contact object
2016-05-02	1.1.5	Add tags in Call object
2015-11-17	1.1.4	Add link in-app endpoint for Call object
2015-10-08	1.1.3	Add call.answered event for Webhooks
2015-10-01	1.1.2	Add two timestamps in Call object
2015-09-28	1.1.1	Add recording URL in Call object
2015-08-03	1.1.0	API public release
2015-07-31	1.0.9	API beta release
2015-07-30	1.0.4	Add comments to Call object
2015-07-29	1.0.3	Add assignment to Call object
2015-07-28	1.0.2	Introducing direct API links
2015-07-27	1.0.1	Update Contact object
2015-06-02	1.0.0	Public release
2015-05-25	0.9.0	Beta release
2015-05-18	0.1.0	Alpha release
2015-05-10	0.0.1	Initial release