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

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

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

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

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

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

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

Not a Developer?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Oauth terminology
• install_uri

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

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

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

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

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

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

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

OAuth credentials

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

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

OAuth flow

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 120 requests per minute per company. The following headers are available in API headers' responses when the rate limit has been reached, giving more insight on your API usage:

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

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

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

The meta object
• count

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

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

  Integer
  Current page number.
• per_page

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

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

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

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

Query params
• page

  Integer
  Current page.
  Default is 1.
• per_page

  Integer
  Number of results retrieved per page
  Default is 20.

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

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

Application error responses include an error title and a human-readable troubleshoot description. They also include message, an errors array, and success: false. Requests rejected at the API gateway before they reach an application, such as invalid credentials, can return a shorter gateway error.

For Outbound Campaigns, message is the machine-readable code to use for specific handling. A recognised domain error uses a semantic code such as INVALID_STATUS_TRANSITION or OUTCOME_IN_USE; otherwise it falls back to the HTTP status constant such as BAD_REQUEST or UNPROCESSABLE_ENTITY. errors[].detail always keeps that status-level constant for broad HTTP categorisation. Internal shared-library codes, including numeric codes, are never exposed.

More detailed HTTP response codes are provided in each endpoint's documentation.

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

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

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

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

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

• Version 1 webhook event: user.connected

• Version 2 webhook event: user.connected.v2

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

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

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

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

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

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

Users can be either Admins or Agents:

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

Users are assigned to Numbers.

Attributes
• id

  Integer
  Unique identifier for the User.
• direct_link

  String
  Direct API URL.
• name

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

  String
  Email of the User.
• created_at

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

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

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

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

  Array
  List of Numbers associated to this User.
• time_zone

  String
  The User's timezone. This can be set either from the Dashboard or Aircall Workspace (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 Aircall Workspace (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! User V1 API will be deprecated soon. Please migrate to User V2 API.

Query params
• from

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

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

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

Pagination params can be used on this request.

Retrieve details of a specific User.

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

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

Path params
• id

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

Retrieve by ID:

Request
GET /v1/users/456

Retrieve by email:

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

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

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

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

Body params
• email

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

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

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

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

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

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

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

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

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

Path params
• id

  Integer
  Unique identifier for the User.

Body params
• first_name

  String
  Can't be blank if defined.
• last_name

  String
  Can't be blank if defined.
• availability_status

  String
  available, custom or unavailable.
• substatus

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

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

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

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 Aircall Workspace. 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 Workspace on Desktop for now, not yet on iOS and Android.

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

Path params
• id

  Integer
  Unique identifier for the User.

Body params
• number_id

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

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

Sending a request to this endpoint will fill the User's Aircall Workspace with the to params. They will then be able to start the call within Aircall Workspace 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 Workspace 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.

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

Users can be either Admins or Agents:

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

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

Attributes
• id

  Integer
  Unique identifier for the User.
• direct_link

  String
  Direct API URL.
• name

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

  String
  Email of the User.
• created_at

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

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

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

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

  String
  The User's timezone. This can be set either from the Dashboard or Aircall Workspace (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 Aircall Workspace (check our Knowledge Base).
  The format is IETF language tag. Default is en-US.
• wrap_up_time

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

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

Availability
• available

  String
  Agent ready to answer calls.
• offline

  String
  Agent not online.
• do_not_disturb

  String
  Agent toggled themself as do not disturb.
• in_call

  String
  Agent is currently on a call.
• after_call_work

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

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

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

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

Query params
• from

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

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

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

Pagination params can be used on this request.

Retrieve details of a specific User V2.

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

Path params
• id

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

Retrieve by ID:

Request
GET /v2/users/456

Retrieve by email:

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

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

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

Body params
• email

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

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

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

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

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

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

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

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

Path params
• id

  Integer
  Unique identifier for the User.

Body params
• first_name

  String
  Can't be blank if defined.
• last_name

  String
  Can't be blank if defined.
• availability_status

  String
  available, custom or unavailable.
• substatus

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

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

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

Fetch all Numbers associated to a specific User V2.

Path params
• id

  Integer
  Unique identifier for the User.

Query params
• order

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

Pagination params can be used on this request.

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

Teams are only used in call distributions of Numbers.

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

Attributes
• id

  Integer
  Unique identifier for the Team.
• direct_link

  String
  Direct API URL.
• name

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

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

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

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 deleted one by one from a Team.

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

Path params
• team_id

  Integer
  Unique identifier for the Team.
• userid

  Integer
  Unique identifier for the User.

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 Aircall Workspace to reach an external person.
3. Internal calls: where an Agent calls another Agent.

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

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

Attributes
• id

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

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

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

  String
  Direct API URL.
• started_at

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

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

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

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

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

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

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

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

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

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

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

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

  Boolean
  Indicates whether the Call has been archived.
  Originally used to flag calls needing follow-up in the legacy Phone app's To-do view; has no functional impact in Aircall Workspace.
• missed_call_reason

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

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

  Object
  Full Number object attached to the Call.
• user

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

  Object
  Full Contact object attached to the Call.
• assigned_to

  Object
  Full User object assigned to the Call.
• teams

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

  Object
  User who performed the Call transfer.
• transferred_to

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

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

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

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

  Array
  Notes added to this Call by Users.
• tags

  Array
  Tags added to this Call by Users.
• participants

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

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

  Array
  Call AI Voice Agents that handled the Call.
  ai_voice_agents is retrievable via Call APIs using the fetch_aiva_conv query param

1. Inbound calls

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

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

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 Aircall Workspace, calling an external person.

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

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

More info on Outbound calls lifecycle in the Webhook section.

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

Query params
• from

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

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

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

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

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

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

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

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

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

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

Path params
• id

  Integer
  Unique identifier for the Call.
• fetch_contact

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

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

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

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

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

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

Query params
• from

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Path params
• id

  Integer
  Unique identifier for the Call.

Body params
• user_id

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

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

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

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

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

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 Agents from Aircall Workspace.

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.

Sets the archived attribute of a Call to false.

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

Note: This endpoint was designed for the legacy Aircall Phone app, where archiving removed a call from the agent's "To-do" follow-up list. With the move to Aircall Workspace — which operates at the conversation level rather than the individual call level — archiving a call no longer has any effect in the app UI. Calling this endpoint only toggles the archived flag on the call record; it does not close the conversation the call belongs to. The concept of archiving a call is deprecated for Aircall Workspace users.

Path params
• id

  Integer
  Unique identifier for the Call.

Sets the archived attribute of a Call to false.

Note: This endpoint was designed for the legacy Aircall Phone app, where unarchiving returned a call to the agent's "To-do" follow-up list. With the move to Aircall Workspace — which operates at the conversation level rather than the individual call level — unarchiving a call no longer has any effect in the app UI. Calling this endpoint only toggles the archived flag on the call record; it does not reopen the conversation the call belongs to. The concept of archiving a call is deprecated for Aircall Workspace users.

Path params
• id

  Integer
  Unique identifier for the Call.

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

Path params
• id

  Integer
  Unique identifier for the Call.

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

Path params
• id

  Integer
  Unique identifier for the Call.

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

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

This action cannot be undone.

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

Check this endpoint to delete the voicemail of a Call.

Path params
• id

  Integer
  Unique identifier for the Call.

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 Aircall Workspace during ongoing Calls.

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

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

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

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

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

Path params
• id

  Integer
  Unique identifier for the Call.

Body params
• contents

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

Title
• type

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

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

  String
  Transform the line in a link.

Short text
• type

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

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

  String
  Transform the line in a link.
• label

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

User
• type

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

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

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

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

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.

Outbound Campaigns enables automated outbound dialing from a centrally managed contact list. A Campaign defines the list, dialing strategy and outcome labels. Multiple human agents or an AI Voice Agent are assigned to it, and the system handles call distribution automatically. Every attempt and outcome is tracked per contact.

Outbound Campaigns is a distinct resource from Dialer Campaign, which covers the Power Dialer feature. A Dialer Campaign is agent-owned and manages a personal list of numbers dialled one at a time. A Campaign is admin-owned, supports multiple agents or an AI Voice Agent, and follows its own lifecycle (draft, in_progress, paused, completed, archived). The two resources are independent and do not share data.

API tokens have company-wide access to Campaigns. Since tokens are admin-scoped by nature — and admins already have full visibility in the Dashboard — all campaigns are returned with no per-agent filtering applied.

A Campaign has no overall contact limit. The synchronous Add Campaign contacts endpoint accepts up to 100 contacts per request. A contact import parses at most 10,000 data rows; a file with more rows fails outright, so split it across multiple imports.

Error responses

This section explains the error response shape and how clients should handle its fields; it is not an exhaustive catalogue of every error an endpoint can return. Errors from Outbound Campaigns requests follow a standard envelope format. Requests rejected upstream by the API gateway may return a shorter error response:

{
  "error": "Unprocessable Entity",
  "message": "INVALID_STATUS_TRANSITION",
  "errors": [
    {
      "status": 422,
      "title": "Unprocessable Entity",
      "detail": "UNPROCESSABLE_ENTITY"
    }
  ],
  "troubleshoot": "Cannot transition campaign from \"completed\" to \"in_progress\"",
  "success": false
}

Use message to get the specific reason. Outbound Campaigns exposes stable semantic codes you can handle in your integration: INVALID_STATUS_TRANSITION, CAMPAIGN_NOT_READY, CAMPAIGN_LAUNCH_REQUIRES_CALLER_ID_NUMBERS, CONCURRENT_MODIFICATION, OUTCOME_ALREADY_EXISTS, RESERVED_OUTCOME_NAME, OUTCOME_IN_USE, and BACKEND_API_UNREACHABLE.

Use errors[].detail when you only need the HTTP category, such as BAD_REQUEST, NOT_FOUND, CONFLICT, UNPROCESSABLE_ENTITY, or SERVICE_UNAVAILABLE. Validation errors, opaque 404 responses, and errors without a recognised domain code also use this status-level constant in message. Internal library codes are never exposed, including numeric codes.

Human and AI Voice Agent (AIVA) Campaigns follow the same lifecycle; all sections below apply to both unless noted. Choose the type at creation. agent_type cannot be changed later. AIVA Campaigns have specific rules for creation and contact payloads, described below.

Create an AIVA campaign

Set agent_type to aiva in Create a Campaign. Any field violation returns 400 with the field name:

• aiva_agent_id is required. The field is rejected when agent_type is not aiva.
• caller_id_strategy must be specific_number_pool, and caller_id_numbers must contain at least one number_id from List Campaign eligible numbers.
• calling_hours is required and is only valid for an AIVA Campaign. It contains an IANA timezone and between 1 and 10 slots. Each slot defines from_time, to_time (24-hour HH:MM), and days (MON–SUN). from_time must be earlier than to_time.
• agent_type is fixed at creation. Update a Campaign rejects that field; there is no endpoint for converting a human Campaign to AIVA or an AIVA Campaign to human.

Human and AIVA Campaigns have separate company entitlements. A structurally valid create request can still return 422 when AIVA Campaigns are not enabled for the company.

Add contacts to an AIVA campaign

AIVA Campaign contacts only accept aiva_variables. Standard fields (first_name, last_name, email, company_name, note) are rejected — sending any returns 422 for the whole batch. Conversely, sending aiva_variables to a human Campaign also fails the whole batch with 422.

On Add Campaign contacts, aiva_variables is a flat string-to-string map and its keys cannot be empty.

Every context variable declared as required by the selected agent must be present and non-blank on every contact. A missing variable rejects that contact with reason: "variable_missing" — the rest of the batch is still queued. The response does not identify which variable is missing.

Retrieve a Campaign returns the agent's context-variable contract, so you can discover it before building contact payloads. aiva_variable_keys lists the context variables the agent requires — the set an import's field_mapping.variables must cover — and aiva_optional_variable_keys lists the variables the agent accepts but never requires, any of which you may map. Both are null on a human Campaign and on an AIVA Campaign created before these fields existed; null means the contract is not recorded, never that the agent declares nothing.

Bulk import AIVA contacts

Use Add Campaign contacts for batches of up to 100 contacts. For larger batches, use the Campaign contact import CSV workflow.

For an AIVA Campaign, field_mapping.variables is required when you create the import. It is an ordered array of { context_key, source_key } pairs and must cover every context variable the selected agent declares as required. If any required mapping is absent, the API returns 422 before creating the import and names the missing context_key values.

The same agent-type separation as the inline endpoint applies to CSV mappings. An AIVA import must not map field_mapping.first_name, field_mapping.last_name, field_mapping.email, field_mapping.company_name or field_mapping.note; a 422 names the offending fields. Conversely, a human Campaign import must not carry field_mapping.variables; that is also a 422. field_mapping.phone_number remains required for both Campaign types because it identifies the number to dial.

The variable mapping follows these rules:

• context_key: "phone_number" is reserved and silently dropped. Map the dialled number with the required field_mapping.phone_number field instead.
• Every context_key must be unique.
• Every source_key must be unique and must not reuse the column named by field_mapping.phone_number. csv_column is a deprecated alias for source_key: exactly one of the two is set per entry, and existing integrations sending csv_column keep working.
• Array order is preserved and sets the variable-column order of a later export.
• If the agent's configuration cannot be read, the import is refused rather than created.

Worked example. This CSV maps a phone column and three required agent context variables:

Phone,Customer ID,Plan,Renewal date
+33612345678,cus_1042,Pro,2026-10-01
+33698765432,cus_2084,Starter,2026-11-15

Create the import with matching column names and the variables in the order you want a later export to use:

Upload the CSV to the presigned upload.url from the response, following the form-field rules on Create a Campaign contact import. Then poll the import until it is ready:

Request
GET /v1/campaigns/:id/contact_imports/:import_id

Finally, promote its valid rows into the Campaign queue:

Request
POST /v1/campaigns/:id/contact_imports/:import_id/promote

{
  "insertion_point": "end"
}

See Retrieve a Campaign contact import for the status loop and Promote a Campaign contact import for promotion behavior.

After contacts are queued, Launch the Campaign. The launch request requires the same compliance acknowledgment as a human Campaign.

The object returned by all Campaign endpoints — create, retrieve, list, update, and lifecycle operations.

Attributes
• id

  String
  Unique identifier for the Campaign (UUID).
• direct_link

  String
  Direct API URL.
• name

  String
  The Campaign's name.
• description

  String
  The Campaign's description.
  Can be null.
• status

  String
  The Campaign's current lifecycle status.
  One of draft, in_progress, paused, completed, archived. completed cannot return to an active or editable state; its only outgoing transition is to archived. archived has no outgoing transition and cannot be deleted.
• caller_id_strategy

  String
  How the Caller ID is chosen for outbound calls placed by this Campaign.
  One of agent_number_pool, specific_number_pool.
• local_presence

  Boolean
  Whether the Campaign uses local presence dialling (matching the contact's area code where possible).
• call_attempts

  Integer
  Maximum number of times a contact is called before being marked unreachable.
• min_interval_between_attempts

  Integer
  Minimum time, in seconds, between two attempts to the same contact.
• external_ringing_timeout

  Integer
  How long, in seconds, a call rings before being considered unanswered.
• campaign_outcome_time

  Integer
  How long, in seconds, an agent has to record a call outcome after a call ends.
• end_date

  String
  Date the Campaign is set to stop, in UTC.
  Can be null. Read-only: nothing in Aircall can currently set this, not even the Dashboard.
• outcome_ids

  Array
  Which Campaign Outcomes agents can pick from when wrapping up a call on this Campaign.
  Empty array if none are attached.
• agent_type

  String
  Who places the calls: a human agent, or an AI Voice Agent.
  One of human, aiva. Fixed when the Campaign is created - no endpoint changes it.
• run_mode

  String
  Whether the Campaign ends on its own. one_time moves to completed once every contact is resolved; continuous never auto-completes and keeps dialling contacts added later until it is paused or archived.
  One of one_time, continuous. Fixed when the Campaign is created - no endpoint changes it.
• aiva_agent_id

  String
  The AI Voice Agent placing the calls.
  Always null when agent_type is human.
• calling_hours

  Object
  The weekly window the Campaign is allowed to dial in, evaluated in its own timezone.
  Always null when agent_type is human. See the shape below.
• created_by

  Integer
  Aircall user id of whoever created the Campaign, using the same ids returned by GET /v1/users.
  Can be null. Always null when the Campaign was created through the public API, which has no user behind it.
• created_at

  String
  Campaign's creation date, in UTC.
• updated_at

  String
  Campaign's last update date, in UTC.

Only an AI Voice Agent Campaign has calling hours, and it cannot be launched without them. Times are wall-clock in timezone, so daylight saving is applied as it changes rather than baked in.

Calling hours
• timezone

  String
  IANA timezone identifier the window is evaluated in.
  For example America/New_York. Never a fixed UTC offset.
• slots

  Array
  The windows themselves.
  Between 1 and 10.
• slots[].from_time

  String
  Start of the window, inclusive.
  "HH:MM" in 24h form.
• slots[].to_time

  String
  End of the window, exclusive - 18:00 permits 17:59 and blocks 18:00.
  "HH:MM" in 24h form, and later than from_time: a window cannot wrap past midnight.
• slots[].days

  Array
  Which weekdays the window applies to.
  Any of MON, TUE, WED, THU, FRI, SAT, SUN.

{
  "timezone": "America/New_York",
  "slots": [
    { "from_time": "09:00", "to_time": "18:00", "days": ["MON", "TUE", "WED", "THU", "FRI"] },
    { "from_time": "10:00", "to_time": "16:00", "days": ["SAT"] }
  ]
}

Create a Campaign, then retrieve, list, update or delete it while it is still a draft. You can also duplicate an existing Campaign to start from its settings without copying its contacts.

When setting up caller ID, List Campaign eligible numbers shows the numbers the company may use, while List Campaign lines reads the pool configured on a Campaign.

Create a Campaign in draft status.

A draft Campaign is not live and has no dialling side effect: nothing is charged and no calls are placed until Launch a Campaign is called, which is what builds the call queue.

Both kinds of Campaign can be created here: human agent (the default) and AI Voice Agent. Each is a separate per-company entitlement, so a body this endpoint accepts can still be refused with a 422 naming the one you are missing.

A Campaign using caller_id_strategy: "specific_number_pool" must bring at least one entry in caller_id_numbers, or the request is a 400. Without numbers the Campaign could be created but never launched, so it is refused here rather than at launch. Pass the number_id values from List Campaign eligible numbers. Only ids: Aircall resolves the number itself, so an id your company cannot use for campaigns is rejected with a 400 naming it.

This endpoint does not assign Users or Teams - those are separate write operations, each documented on its own page. An AI Voice Agent Campaign needs neither: it is refused if it has any.

An AI Voice Agent Campaign, which must name its agent, dial from a specific number pool, and declare the hours it may call in:

Request
POST /v1/campaigns

{
  "name": "Q3 outreach (AI Voice Agent)",
  "agent_type": "aiva",
  "aiva_agent_id": "8f1c2c9c-9b6b-4a11-9d9f-3ab01e2e4f1a",
  "caller_id_strategy": "specific_number_pool",
  "caller_id_numbers": [12345],
  "calling_hours": {
    "timezone": "America/New_York",
    "slots": [
      { "from_time": "09:00", "to_time": "18:00", "days": ["MON", "TUE", "WED", "THU", "FRI"] }
    ]
  }
}

Body params
• name

  String
  The Campaign's name.
  Mandatory field. Cannot be blank. Max 255 characters.
• description

  String
  The Campaign's description.
  Optional. Can be null. Max 1000 characters.
• caller_id_strategy

  String
  How the Caller ID is chosen for outbound calls placed by this Campaign.
  Mandatory field. One of agent_number_pool, specific_number_pool.
• local_presence

  Boolean
  Whether the Campaign uses local presence dialling.
  Optional. Defaults to false.
• call_attempts

  Integer
  Maximum number of times a contact is called before being marked unreachable.
  Optional. Must be between 1 and 5.
• min_interval_between_attempts

  Integer
  Minimum time, in seconds, between two attempts to the same contact.
  Optional. Maximum 259200 (72 hours). The minimum floor is company-dependent (normally 3600s); a value below the applicable floor is a 400 naming the real bound.
• external_ringing_timeout

  Integer
  How long, in seconds, a call rings before being considered unanswered.
  Optional. Must be between 1 and 3600.
• campaign_outcome_time

  Integer
  How long, in seconds, an agent has to record a call outcome after a call ends.
  Optional. Must be between 1 and 3600.
• outcome_ids

  Array
  Which outcome tags (from List all Campaign Outcomes) agents can pick from when wrapping up a call on this Campaign.
  Optional because a Campaign can be created before any outcomes are attached. Each id must belong to your company's outcome catalogue; if any id does not, the whole request is rejected with a 404. Omit or send an empty array for no outcomes.
• caller_id_numbers

  Array
  The Aircall numbers this Campaign may dial out from, as number_id values from List Campaign eligible numbers.
  Mandatory when caller_id_strategy is specific_number_pool, and must hold at least one id. Rejected when caller_id_strategy is agent_number_pool. Ids only - the number itself is resolved from your company's campaign-eligible set, so an id that is not in it (including another company's number) is a 400 naming the id. List Campaign lines reads the same ids back.
• agent_type

  String
  Who places the calls.
  Optional for backward compatibility with Campaign bodies written before AIVA support. One of human, aiva; defaults to human when omitted. Cannot be changed afterwards; there is no endpoint that converts a Campaign from one to the other.
• run_mode

  String
  Whether the Campaign ends on its own once its contacts are resolved.
  Optional. One of one_time, continuous; defaults to one_time when omitted. continuous never auto-completes: stop it with Pause, and end it with Archive once paused. It can also be launched with no contacts. Cannot be changed afterwards.
• aiva_agent_id

  String
  The AI Voice Agent that will place the calls.
  Mandatory when agent_type is aiva, rejected otherwise. Max 255 characters. There is no endpoint that lists AI Voice Agents, so this id has to come from your AI Voice Agent configuration.
• calling_hours

  Object
  The weekly window this Campaign may dial in - see Calling hours on the Campaign object for the full shape.
  Mandatory when agent_type is aiva, rejected otherwise. Required rather than optional because an AI Voice Agent Campaign cannot be launched without one, so creating it without would produce a Campaign that can never run. Between 1 and 10 slots; each slot's from_time must be earlier than its to_time, so a window cannot wrap past midnight.

The request body is validated strictly: an unknown key, or a field outside its documented range, is rejected with a 400 naming the offending field rather than being silently ignored. status and end_date are not accepted here - a new Campaign always starts in draft, and end_date cannot be set by any public or dashboard action.

Fetch a single Campaign by id.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Fetch all Campaigns in your company.

This endpoint's pagination is different from the rest of the API - see the note under the response fields table below before using page or current_page, which do not apply here.

Query params
• status

  String
  Filter by status. Comma-separated for several values.
  One or more of draft, in_progress, paused, completed, archived. An unknown value returns a 400, not an empty list.
• name

  String
  Filter by name (case-insensitive, substring match).
  name=Q3 matches "Q3 outreach" and "Q3 Retry" alike, not just an exact "Q3".
• created_by

  String
  Filter by the Aircall user id of whoever created the Campaign. Comma-separated for several values.
  A Campaign whose readable created_by is null never matches any filter value. This includes Campaigns created through the public API, which has no user behind it.
• per_page

  Integer
  Number of results per page.
  Default is 20. Maximum is 50 - a higher value is not rejected, it is silently capped to 50.
• cursor

  String
  Opaque value from a previous response's next_cursor, used to fetch the next page.
  Treat as an opaque token: do not parse it, and do not expect it to still work after being reused out of order. Omit it to get the first page.

Meta object
• count

  Integer
  Number of Campaigns in this page.
• total

  Integer
  Total number of Campaigns matching the filters, across all pages.
• per_page

  Integer
  Page size that was actually used.
• next_cursor

  String
  Cursor to pass as cursor to fetch the next page.
  null on the last page.
• next_page_link

  String
  Full URL to the next page, filters included.
  null on the last page.

This endpoint pages forward only, using a cursor rather than a page number: there is no page, current_page or previous_page_link, unlike other list endpoints on this API (see Pagination). A Campaign created while you are paging through results cannot shift already-fetched rows or duplicate one, which a page-number scheme cannot guarantee.

Update a Campaign's editable configuration.

This is a partial update, despite the PUT verb. An omitted field is left untouched - it is not cleared or reset to a default. This API has no PATCH method, so PUT is reused for partial semantics rather than true replacement, which is not possible here anyway: status and end_date cannot be written by this or any endpoint.

status is not editable here. Lifecycle changes go through the dedicated actions - Launch a Campaign, Pause a Campaign, Resume a Campaign, Archive a Campaign - each with its own preconditions and side effects.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Body params
• name

  String
  The Campaign's name.
  Optional. Cannot be blank if provided. Max 255 characters.
• description

  String
  The Campaign's description.
  Optional. Can be null to clear it.
• caller_id_strategy

  String
  How the Caller ID is chosen for outbound calls placed by this Campaign.
  Optional. One of agent_number_pool, specific_number_pool.
• local_presence

  Boolean
  Whether the Campaign uses local presence dialling.
  Optional.
• call_attempts

  Integer
  Maximum number of times a contact is called before being marked unreachable.
  Optional. Must be between 1 and 5.
• min_interval_between_attempts

  Integer
  Minimum time, in seconds, between two attempts to the same contact.
  Optional. Same floor and 259200s ceiling as on Create a Campaign.
• external_ringing_timeout

  Integer
  How long, in seconds, a call rings before being considered unanswered.
  Optional. Must be between 1 and 3600.
• campaign_outcome_time

  Integer
  How long, in seconds, an agent has to record a call outcome after a call ends.
  Optional. Must be between 1 and 3600.
• outcome_ids

  Array
  Which outcome tags (from List all Campaign Outcomes) agents can pick from when wrapping up a call on this Campaign.
  Optional. Each id must belong to your company's outcome catalogue, or the whole request is rejected with a 404. Unlike every other field here, [] and omitting the field mean different things: omitting it leaves the Campaign's outcomes untouched, [] removes every outcome from it.
• caller_id_numbers

  Array
  The Aircall numbers this Campaign may dial out from, as number_id values from List Campaign eligible numbers.
  Optional, and replaces the whole pool rather than adding to it: omit the field to leave the pool alone. Ids only - the number itself is resolved from your company's campaign-eligible set, so an ineligible id is a 400. caller_id_strategy is required whenever this field is sent - see the notice below.
• calling_hours

  Object
  The weekly window this Campaign may dial in - see Calling hours on the Campaign object for the full shape.
  Optional, and only on an AI Voice Agent Campaign that is still in draft. Send null to clear it. Attempting it on a human agent Campaign, or after the Campaign has left draft, is a 422.

caller_id_numbers replaces the Campaign's pool: every number currently on it is removed and the ones you send are put in their place. To leave the pool untouched, omit the field.

The two fields travel together in both directions. Sending caller_id_numbers requires caller_id_strategy, so it is always clear which strategy the pool is for - otherwise numbers sent to a Campaign currently on agent_number_pool would store a pool that does nothing until someone later switched the strategy and silently activated it. Setting caller_id_strategy to specific_number_pool does not require you to re-send the pool if the Campaign already has one - but it is refused with a 422 if the result would be a live Campaign on that strategy with no numbers, because it would have nothing to dial from. This applies to a draft too, not only a live Campaign: Create a Campaign refuses specific_number_pool without numbers, so the API would otherwise contradict itself and you would only discover the problem at launch. With agent_number_pool the array must be empty or absent. To change neither, omit both.

On an AI Voice Agent Campaign, sending caller_id_numbers also triggers a fresh dialling pass over the new pool. That happens whenever the field is present, even if the numbers are identical to the ones already there, so avoid re-sending it from a periodic sync that has nothing to change.

Soft-delete a Campaign. The row is marked deleted and disappears from every read path - the same effect as deleting from the dashboard.

Only a Campaign in draft status can be deleted. A Campaign that has ever been launched must be moved to archived instead - see Archive a Campaign - which keeps it visible and reportable rather than removing it.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Copy a Campaign's settings into a new draft Campaign: name, run_mode, retry policy, caller-ID strategy, its assigned outcome catalogue, caller ID numbers, and whatever Users or Teams are assigned. The new Campaign's contacts start empty - this does not copy the dial queue.

For both human and AIVA Campaigns, this public endpoint never copies contacts. It is deliberately narrower than the Dashboard's duplicate flow, which can preview and copy a filtered subset of contacts by outcome. The public endpoint only reuses the Campaign's settings as a template.

Path params
• id

  String
  Unique identifier for the source Campaign (UUID).

Body params
• name

  String
  Name for the new Campaign.
  Optional. Defaults to the source Campaign's name. Cannot be blank if provided. Max 255 characters.

Add the people a Campaign will dial. You can add up to 100 contacts synchronously or use the Campaign contact import flow for a CSV. List Campaign contacts shows who is in the Campaign. Campaign queue items shows their dial order and per-attempt status.

Fetch a Campaign's call queue: the contacts it dials.

?phone_number= narrows the result to a single contact. That is the supported way to fetch one - a contact has no publicly addressable id, and within a Campaign a phone number identifies at most one contact.

Filtered or not, the response is the same paginated collection envelope - at most one element when filtered by phone_number. A filter that matches nothing returns an empty collection, not a 404: the Campaign exists and was readable, the filter simply selected no rows.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Query params
• per_page

  Integer
  Number of results per page.
  Default is 20. Maximum is 50, clamped rather than rejected.
• cursor

  String
  Opaque value from a previous response's next_cursor.
  Same forward-only cursor mechanism as List all Campaigns - not interchangeable with a cursor from another endpoint.
• phone_number

  String
  Narrow to the one contact with this number.
  Optional. Malformed values are rejected with 400.

Attributes
• phone_number

  String
  E.164 digits with no leading +. The contact's identity within the Campaign - pass it back as phone_number to fetch this contact.
• first_name

  String
  The contact's first name.
  Can be null.
• last_name

  String
  The contact's last name.
  Can be null.
• email

  String
  The contact's email address.
  Can be null.
• company_name

  String
  The contact's company name.
  Can be null.
• note

  String
  Free-text note supplied with the contact, e.g. from a CRM import.
  Can be null.
• created_at

  String
  In UTC.
• updated_at

  String
  In UTC.

Add up to 100 contacts to a Campaign and queue them for dialling in one request. A Campaign has no overall contact limit.

This is the synchronous path, for feeding contacts in as they arrive. For larger volumes use the Campaign contact import flow instead, which uploads a CSV and processes it in the background.

The contacts array in the response is positionally aligned to the one you sent: the first result describes your first contact, and so on. There is no index field. Read each result's status and, for a rejected contact, its reason at the same array position as the submitted contact.

A successful response has no success key. HTTP 201 means at least one contact was queued. HTTP 200 can mean that every contact was rejected, so check queued_count, rejected_count and each positional result instead of treating every 2xx as a queued batch.

Safe to retry. A replayed request queues nothing twice and changes nothing: within a Campaign a phone number identifies at most one contact, so every contact in the replay comes back as already_in_campaign. No idempotency key is needed.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Body params
• country_code

  String
  ISO 3166-1 alpha-2 region used to read numbers written in national format, e.g. FR turns 06 12 34 56 78 into 33612345678.
  Required, with no default. A wrong region does not fail loudly - it produces valid-looking numbers for another country, and the first sign of trouble is calls placed to strangers. Numbers already in full international form are unaffected. A well-formed but non-existent region such as ZZ is rejected with 400.
• position

  String
  Where the contacts land in the existing queue: top or bottom.
  Optional, defaults to bottom. top puts them ahead of everyone already waiting. Note this differs from Promote a Campaign contact import, which spells the same idea insertion_point with start/end.
• contacts

  Array
  The contacts to add. Between 1 and 100 elements.
  Required. More than 100 is rejected with 400; use the Campaign contact import flow for larger lists.
• contacts[].phone_number

  String
  The number to dial. National or international format; read against country_code.
  Required.
• contacts[].first_name

  String
  The contact's first name.
  Optional. Human agent Campaigns only.
• contacts[].last_name

  String
  The contact's last name.
  Optional. Human agent Campaigns only.
• contacts[].email

  String
  The contact's email address.
  Optional. Human agent Campaigns only.
• contacts[].company_name

  String
  The contact's company name.
  Optional. Human agent Campaigns only.
• contacts[].note

  String
  Free-text note to store with the contact.
  Optional. Human agent Campaigns only.
• contacts[].aiva_variables

  Object
  Context passed to the AI Voice Agent for this contact, as string keys to string values, e.g. {"plan": "Pro"}.
  AIVA Campaigns only. Every context variable the agent declares as required must be present with a non-blank value. The agent's optional context-variable declarations are not required and are ignored when the Campaign validates a contact. Extra keys are accepted and passed through. Keys must be non-empty.

The accepted fields depend on the Campaign's agent type, and mixing them fails the whole request with 422. An AIVA Campaign accepts aiva_variables only; a human agent Campaign accepts the five descriptive fields only. Both accept phone_number.

On an AIVA Campaign, a contact must carry every context variable the agent declares as required, each with a non-blank value. A contact missing one is reported individually as variable_missing rather than failing the request, so the rest of the batch can still be queued. The agent's optional context variables are not required and are ignored by Campaign validation. Extra keys are accepted and passed through to the agent.

Attributes
• queued_count

  Integer
  How many contacts were queued for dialling.
  Read this to tell a full success from a partial one - the status code only distinguishes "something was queued" from "nothing was".
• rejected_count

  Integer
  How many were not queued.
  The sum of the two always equals the number of contacts you sent.
• contacts

  Array
  One result per submitted contact, in the same order as the request.
• contacts[].status

  String
  queued, duplicate or invalid.
• contacts[].queue_item_id

  String
  Identifier of the created queue item (UUID), for use with Campaign queue items.
  Present only when status is queued.
• contacts[].phone_number

  String
  The normalised number, E.164 digits with no leading +.
  Absent when status is invalid - normalising it is what failed.
• contacts[].reason

  String
  Why the contact was not queued. See the table below.
  Absent when status is queued.

Reasons
• phone_number_unparseable

  String
  The number could not be read as a real number for the given country_code.
  Check country_code before the numbers - a wrong region invalidates every row at once.
• phone_number_not_dialable

  String
  The number is the anonymous-caller placeholder rather than a dialable number.
• field_too_long

  String
  A descriptive field exceeded its maximum length.
  first_name and last_name 100, email 255, company_name 200, note 500. Values are rejected rather than truncated.
• variable_too_long

  String
  An aiva_variables value exceeded 500 characters.
• variable_missing

  String
  A required context variable declared by the Campaign's AIVA agent was absent or had a blank value.
  The required set is fixed for as long as the Campaign can accept contacts, so this means the contact is incomplete rather than the Campaign having changed.
• duplicate_in_batch

  String
  The same number appeared earlier in this request.
  Compared after normalisation, so 06 12 34 56 78 and +33612345678 are the same number. The first occurrence is queued.
• already_in_campaign

  String
  The Campaign already holds this number.
  Also returned when the number is already in the dial queue. This is the reason a retried request returns for every contact.

Remove one contact from a Campaign's queue, so it will not be dialled. This is the undo of Add Campaign contacts.

The contact is addressed by its phone number, which is its identity within a Campaign - a contact has no id of its own. Feed back a phone_number exactly as List Campaign contacts returns it and it matches by construction.

Removing a contact also removes its queue item. The two are one thing from the outside: a contact is only in a Campaign because something is queued to dial it.

Removal has one of two effects.

Delete. A contact with no recorded attempts is deleted with no call history.

Cancel next attempts. If the contact has at least one recorded attempt, any remaining retries are cancelled and the contact leaves the queue. The latest known outcome, when one exists, is kept and made final so it remains available in the Campaign's outcomes. The API does not create a cancellation outcome.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).
• phone_number

  String
  The contact's phone number, as returned by List Campaign contacts. Lenient about formatting: 33612345678, +33612345678 and +33 6 12 34 56 78 all address the same contact. Percent-encode the + as %2B in the path. A national number such as 0612345678 cannot be used - it is only resolvable against a country, and an API token is company-wide with no country attached.

A Campaign's dial queue, in dial order: list it to see who's next and how the last attempt on each went, reorder an item to change its position, or reschedule one to change when it's next attempted. List Campaign contacts answers who is in the queue; this answers what order and when.

Fetch a Campaign's dial queue, in dial order. List Campaign contacts answers who is in the Campaign and Retrieve Campaign statistics answers the aggregate; this answers what order they will be called in and how the last attempt on each went.

Deliberately narrow. Scheduler internals - retry counters, the next intended attempt time, and the derived live-queue display state - are not published here, to avoid freezing today's retry model into the contract.

Paged by cursor like every other collection on this API, but the cursor encodes queue position rather than creation time, because the queue is ordered by position. This is invisible to a client - the cursor is opaque either way - but a cursor from this endpoint is not interchangeable with one from another.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Query params
• per_page

  Integer
  Number of results per page.
  Default is 20. Maximum is 50, clamped rather than rejected.
• cursor

  String
  Opaque value from a previous response's next_cursor.
  See the notice above - not interchangeable with a cursor from another endpoint.

Attributes
• id

  String
  Unique identifier for this queue entry (UUID).
• phone_number

  String
  The number to dial - the identity of the queued row, tied to a contact by Campaign plus phone number rather than by a contact id.
• position

  String
  Opaque lexicographic ordering key.
  Compare it, do not parse it or do arithmetic on it - positions are not consecutive and gaps carry no meaning.
• last_attempt_at

  String
  When the last attempt happened, in UTC.
  Can be null before the first attempt.
• last_attempt_id

  String
  The attempt behind last_attempt_at, joinable to the id field of List Campaign call outcomes for the typed outcome.
  Can be null before the first attempt.
• scheduled_at

  String
  When this entry is due, if it was queued for a specific time rather than for immediate dialling.
  Can be null otherwise.
• created_at

  String
  In UTC.
• updated_at

  String
  In UTC.

Move one entry of a Campaign's dial queue (see List Campaign queue items) to the top or bottom, or past its immediate neighbour in either direction.

Moving an entry already at a boundary - top when it is already first, bottom when it is already last - is not an error: the entry is returned unchanged.

The queue entry must belong to the Campaign named by id. A wrong or nonexistent Campaign id returns the same 404 as a missing or cross-company queue entry, and nothing is reordered.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).
• queue_item_id

  String
  Unique identifier for the queue entry (UUID).

Body params
• direction

  String
  Where to move the entry.
  Mandatory field. One of top, up, down, bottom.

last_attempt_at and last_attempt_id are always null in this response, even for an entry with attempt history: reordering never touches attempt data, so nothing here is re-fetched. Read them from List Campaign queue items instead.

Set, change or clear when one Campaign queue entry (see List Campaign queue items) is next due. This per-entry scheduled_at value is not the Campaign's retry interval: min_interval_between_attempts separately controls the minimum gap between attempts to the same contact.

Setting scheduled_at defers the entry to that time instead of immediate dialling; null clears it. This never changes the entry's position in the queue. A scheduled entry keeps its place and is skipped until its due time.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).
• queue_item_id

  String
  Unique identifier for the queue entry (UUID).

Body params
• scheduled_at

  String
  When the entry becomes due, in ISO-8601 with a UTC offset.
  Mandatory field, but nullable - pass null to clear it back to immediate dialling. There is no "leave unchanged" option; every call overwrites it.

last_attempt_at and last_attempt_id are always null in this response - see the equivalent notice under Reorder a Campaign queue item.

The queue entry must belong to the Campaign named by id. A wrong or nonexistent Campaign id returns the same 404 as a missing or cross-company queue entry, and nothing is rescheduled.

The CSV workflow for loading contacts into a Campaign's dial queue, in three steps: create an import and get a presigned upload target, retrieve it to poll processing status and check rows for anything invalid, then promote it to queue the valid rows for dialling.

For an AIVA Campaign, the create step must map CSV columns to every required agent context variable. See the end-to-end AIVA Campaign bulk-import example.

Creating an import and promoting it are deliberately separate steps. Promotion is what queues real calls to real people, and there is no undo once dialling starts.

Step one of three for loading a CSV file of contacts into a Campaign: create the import and get somewhere to upload the file. Promote a Campaign contact import is what actually queues the contacts, once the upload is parsed. A Campaign has no overall contact limit. One import parses at most 10,000 data rows; a file with more rows fails outright, so split it across multiple imports.

The file does not go through this endpoint or through api.aircall.io at all. The response carries a presigned upload target; your integration uploads the CSV directly there as multipart/form-data, with fields sent exactly as returned, in order, and the file part last.

One import in flight per Campaign. Creating a second one while an earlier import is still pending or processing fails with 422 - imports cannot be pipelined.

Add a separate form field literally named Content-Type, with the value from upload.content_type (currently always text/csv), before the file part. S3's upload policy checks this field, not the MIME Content-Type: header on the file part itself - omitting it fails the upload with a 403 AccessDenied ("Policy Condition failed") even though the file part's own header is correct.

An AIVA Campaign requires field_mapping.variables to map CSV columns to every context variable its agent declares as required. A missing required mapping returns 422, names the missing context_key values, and creates no import. See the complete AIVA bulk-import example.

The mapping fields must match the Campaign's agent type. An AIVA import rejects field_mapping.first_name, field_mapping.last_name, field_mapping.email, field_mapping.company_name and field_mapping.note with 422 naming the offending fields. A human Campaign import rejects field_mapping.variables with 422. field_mapping.phone_number is required for both.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Body params
• file_name

  String
  The file's name, for your own reference.
  Mandatory field. Not used to locate the object. Max 255 characters.
• file_size

  Integer
  Declared size of the CSV file in bytes.
  Mandatory field. Must be greater than 0 and no more than 1,048,576 bytes. The API validates this value before creating the import and returning an upload target.
• country_code

  String
  ISO 3166-1 alpha-2 region used to read national-format numbers in the file, e.g. FR turns 06 12 34 56 78 into 33612345678.
  Mandatory field, two uppercase letters - fr is rejected with a 400. A wrong value does not fail loudly - it produces syntactically valid numbers for the wrong country. Numbers already in full international form are unaffected.
• field_mapping

  Object
  Maps Campaign contact fields and agent context variables to CSV columns.
  Mandatory field. Every source_key (or legacy csv_column) value must exactly match a header in the file's first row.
• field_mapping.phone_number

  String
  The column holding the phone number.
  Mandatory for both human and AIVA Campaign imports - a row without one cannot be called.
• field_mapping.variables

  Array
  Ordered mappings from CSV columns to the agent's context variables, as { context_key, source_key } pairs.
  Required for an AIVA Campaign and must cover every context variable its agent declares as required. Rejected for a human Campaign. Array order is preserved and sets the variable-column order of a later export.
• field_mapping.variables[].context_key

  String
  Agent context-variable key.
  Must be unique and cannot be blank. The reserved key phone_number is silently dropped; use field_mapping.phone_number for the dialled number.
• field_mapping.variables[].source_key

  String
  CSV column mapped to this context variable. Preferred term.
  Exactly one of source_key or csv_column per entry. Must be unique across entries, cannot be blank, and cannot reuse the column mapped by field_mapping.phone_number.
• field_mapping.variables[].csv_column

  String
  CSV column mapped to this context variable. Deprecated alias for source_key - still accepted, existing integrations keep working.
  Exactly one of source_key or csv_column per entry; an entry carrying both (or neither) is rejected with a 400. Same constraints as source_key. Prefer source_key for new integrations.
• field_mapping.first_name

  String
  The column holding the first name.
  Optional - omit the key entirely to skip it. If present, cannot be blank.
• field_mapping.last_name

  String
  The column holding the last name.
  Optional - omit the key entirely to skip it. If present, cannot be blank.
• field_mapping.email

  String
  The column holding the email address.
  Optional - omit the key entirely to skip it. If present, cannot be blank.
• field_mapping.company_name

  String
  The column holding the company name.
  Optional - omit the key entirely to skip it. If present, cannot be blank.
• field_mapping.note

  String
  The column holding a free-text note.
  Optional - omit the key entirely to skip it. If present, cannot be blank.

The API refuses an AIVA import if it cannot read the selected agent's configuration. It never creates an import whose required context-variable set could not be verified.

Attributes
• contact_import.id

  String
  Unique identifier for the import (UUID).
  Use it in every following step.
• contact_import.status

  String
  Always pending here - nothing has been parsed yet.
• upload.url

  String
  Upload the file here, as multipart/form-data.
• upload.fields

  Object
  Opaque signed policy fields.
  Send all of them as form fields, in this order, before the file part. Do not reconstruct them.
• upload.expires_at

  String
  After this the URL is refused and the import must be created again, in UTC.
  One hour from creation.
• upload.max_file_size_bytes

  Integer
  Largest file the API and S3 will accept.
  Currently 1,048,576 (1 MB). The API validates the declared file_size before returning an upload target and returns 422 when it is too large. S3 also enforces the declared size during upload.
• upload.content_type

  String
  The only Content-Type the upload accepts.
  Exact match - text/csv; charset=utf-8 is rejected.
• upload.max_rows

  Integer
  Largest number of data rows one import will parse.
  Currently 10,000. A file with more rows fails the import outright once uploaded - split it instead.

Poll this while an import's status is pending, processing or promoting; stop at ready, promoted or failed. That loop is guaranteed to terminate - a stuck worker surfaces as failed rather than as processing forever.

Keeps answering after promotion. Promoting an import removes it from the active list internally, but this endpoint still reports it so the loop above has something to land on.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).
• import_id

  String
  Unique identifier for the import (UUID), from Create a Campaign contact import.

Attributes
• id

  String
  Unique identifier for the import (UUID).
• status

  String
  Where the import is in its lifecycle.
  One of pending, processing, ready, promoting, promoted, failed. ready means parsed and waiting for an explicit promote - promotion is never automatic, because it queues real calls.
• source

  String
  How the import was created.
  csv for an upload through this endpoint.
• file_name

  String
  As supplied at creation.
• country_code

  String
  As supplied at creation.
• total_count

  Integer
  Rows read from the file.
  0 until parsing finishes.
• valid_count

  Integer
  Rows that promote will queue.
• invalid_count

  Integer
  Rows that failed validation.
  Inspect them at List Campaign contact import rows.
• duplicate_count

  Integer
  Rows dropped as duplicates - repeated within the file, or already a contact on this Campaign.
• created_at

  String
  In UTC.
• updated_at

  String
  In UTC.

What happened to each row of a contact import. A ten-thousand-row import with thirty-seven bad numbers is only actionable as ?status=invalid - invalid_count: 37 on its own does not say which thirty-seven.

Read-only. The dashboard lets a person fix a mismapped row before promoting; an integrator fixes its own exporter and creates a new import instead, so there is no way to edit a row here.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).
• import_id

  String
  Unique identifier for the import (UUID).

Query params
• per_page

  Integer
  Number of results per page.
  Default is 20. Maximum is 50, clamped rather than rejected.
• cursor

  String
  Opaque value from a previous response's next_cursor.
  Encodes row position, not creation time - not interchangeable with a cursor from another endpoint.
• status

  String
  Narrow to rows in this state.
  Optional. One of valid, invalid, duplicate. An unrecognised value is rejected with 400 rather than silently returning every row.

Attributes
• id

  String
  Unique identifier for this row (UUID).
• row_index

  Integer
  Zero-based position in the file, excluding the header.
  The link back to a line in your own CSV.
• status

  String
  What happened to this row.
  valid rows are queued by promote; invalid and duplicate rows are discarded. duplicate means the number repeats within the file or is already a contact on this Campaign.
• phone_number

  String
  The parsed number.
  E.164-normalised when it could be parsed, the raw file value otherwise - which is exactly the case you are inspecting on an invalid row. Can be null if the source column was blank.
• first_name

  String
  As read from the file.
  Can be null.
• last_name

  String
  As read from the file.
  Can be null.
• email

  String
  As read from the file.
  Can be null.
• company_name

  String
  As read from the file.
  Can be null.
• note

  String
  As read from the file.
  Can be null.
• issues

  Array
  Why the row failed, empty for a valid row.
  A row can fail on more than one field. code is stable and machine-readable; message is prose and may be reworded - branch on code.
• issues[].code

  String
  Stable identifier for the kind of problem, e.g. invalid_phone_number.
• issues[].field

  String
  The field this issue is about, matching the row keys above.
• issues[].message

  String
  Human-readable explanation.
  Not stable - do not parse it.

Move a contact import's valid rows into the Campaign's dial queue. Invalid and duplicate rows are discarded; valid_count on Retrieve a Campaign contact import is how many this queues.

Separate from creating the import, on purpose. This is the step that queues real calls to real people, and there is no undo once dialling starts. Review GET .../rows?status=invalid first if you want to catch problems before committing.

Asynchronous - this enqueues the work and returns immediately. Poll Retrieve a Campaign contact import until status reports promoted or failed.

Idempotent for the same import: calling this again while promotion is already in flight, or after it has already completed, returns the same 202 state rather than queueing the contacts twice.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).
• import_id

  String
  Unique identifier for the import (UUID).

Body params
• insertion_point

  String
  Where the imported contacts land in the existing queue.
  Optional. One of start, end. Defaults to end. start jumps them ahead of everyone already waiting.

Choose the Users and Teams assigned to a Campaign. List Campaign agents resolves those settings into the people who will dial.

The Users directly assigned to a Campaign: list them, assign more, or remove one. This is the assignment setting, not the resolved set of agents who will actually be called - see List Campaign agents for that.

Fetch the Users directly assigned to a Campaign - the assignment setting, not the resolved set of agents who will actually be called.

This is a setting, and its POST/DELETE counterparts round-trip against it: assigning a User makes them appear here, removing them makes them disappear (unless a Team assignment also places them - see the note on Remove a user from a Campaign). If you want everyone who will actually be called, including agents held only through a Team, use List Campaign agents instead.

Returns the Aircall user_id only - name, email and availability belong to User and are not duplicated here.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Query params
• per_page

  Integer
  Number of results per page.
  Default is 20. Maximum is 50, clamped rather than rejected.
• cursor

  String
  Opaque value from a previous response's next_cursor.
  Same forward-only cursor mechanism as List all Campaigns - not interchangeable with a cursor from another endpoint.

Attributes
• id

  String
  Unique identifier for this assignment (UUID). Identifies the assignment, not the User.
• user_id

  Integer
  Aircall user id - see User.
• created_at

  String
  When this assignment was created, in UTC.
• updated_at

  String
  When this assignment was last updated, in UTC.

Assign one or more Users to a Campaign.

Additive and idempotent: Users already on the Campaign stay on it, and re-posting an already-assigned user_id is a no-op. The whole request succeeds or none of it does - a single unresolvable id rejects the request before anything is written.

A caller who wants the resulting membership re-reads List Campaign users.

Path params
• id

  String
  Unique identifier for the Campaign (UUID).

Body params
• user_ids

  Array<Integer>
  Aircall user ids, as returned by GET /v1/users or List Campaign users.
  Mandatory field. At least 1, at most 100 ids per request - submit larger assignments in batches. Duplicates are tolerated.

Remove one User's individual assignment from a Campaign. user_id is the value returned by List Campaign users, not that endpoint's own id.

A User who is on the Campaign only through an assigned Team answers 204 here while staying on the Campaign: this endpoint only rewrites the directly-assigned set, which never held them in the first place. Their Team membership is what keeps them there - removing that is a change to the Team, via Remove a team from a Campaign. Check assigned_directly and team_ids on List Campaign agents beforehand to know which case you are in.