NAV
JSON

Introduction

{
  "resource": "Aircall Documentation",
  "version": "1.3.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
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
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 API key. 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
GET /numbers List of numbers
GET /numbers/:id Retrieve 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)!

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