Advanced Analytica Advanced Analytica: IBOM
← All connectors
Aircall logo

Source connector

Aircall

Set up Aircall as a source and move its data into your chosen destination.

Version 1.1.0 community alpha

Aircall

Use this page to set up the Aircall source connector and check its reference information. The connector reads calls, contacts, users, numbers, teams, conversations, campaigns and other company data from the Aircall Public API.

Prerequisites

  • An Aircall account with the Admin role. Only Admins can open the Aircall Dashboard and create API keys (Users).
  • An Aircall API key, comprising an API ID and an API token. The connector authenticates each request with Basic authentication. It uses the API ID as the username and the API token as the password.

Setup guide

Step 1: Set up Aircall

Create an Aircall API key:

  1. Log in to the Aircall Dashboard as an Admin.
  2. Go to Integrations & API > API Keys. Aircall’s reference calls this the API Keys section of your company’s settings.
  3. Click Add a new API key.
  4. Copy the API ID and the API token. Aircall doesn’t store the token in plain text, so it can’t show it again. Keep it somewhere safe. If you lose it, create a new key (Basic authentication).

Step 2: Set up the Aircall connector in Airbyte

Airbyte Cloud

  1. Log in to your Airbyte Cloud account.
  2. In the left navigation bar, click Sources, then click New source.
  3. Select Aircall from the source list.
  4. Enter a name for the source.
  5. Enter your API ID and API Token.
  6. Optionally, set Window size (days), Contacts window size (days), Concurrent workers and Sync conversation intelligence (AI Assist). See Configuration options.
  7. Click Set up source.

Airbyte Open Source

  1. Open your Airbyte Open Source dashboard.
  2. In the left navigation bar, click Sources, then click New source.
  3. Select Aircall from the source list.
  4. Enter a name for the source.
  5. Enter your API ID and API Token.
  6. Optionally, set Window size (days), Contacts window size (days), Concurrent workers and Sync conversation intelligence (AI Assist). See Configuration options.
  7. Click Set up source.

Configuration options

FieldRequiredDescription
API IDYesThe API ID of your Aircall API key.
API TokenYesThe API token shown with the API ID when you created the key.
Window size (days)NoDays of calls requested at a time, from 1 to 365. The default is 1. A window that holds more than 10,000 calls is split and partly read again, so a larger window only saves requests for companies with few calls. If a sync fails with could not split its request window, lower this setting. See 10,000-result limit.
Contacts window size (days)NoDays of newly created contacts requested at a time, from 1 to 365. The default is 30. Lower it if a sync fails with the 10,000-results error for contacts.
Concurrent workersNoNumber of parallel requests, from 1 to 4. The default is 2. All workers share one rate limit.
Sync conversation intelligence (AI Assist)NoAdds the six conversation intelligence streams. Off by default. They need the AI Assist or AI Assist Pro package and cost one request per call for each selected stream on every sync.

Connections created before version 0.5.0 also have a Start date. The connector no longer uses this date, and the form hides it.

Supported sync modes

The Aircall source connector supports these sync modes:

FeatureSupported?
Full Refresh SyncYes
Incremental SyncYes
Replicate Incremental DeletesNo
SSL connectionYes
NamespacesNo

calls, conversations, conversation_engagements and the six conversation intelligence streams support incremental sync. Each incremental sync re-reads the previous three days. Use Incremental | Append + Deduped to keep one row per record.

  • calls uses started_at. Calls in progress and edits made soon after a call reach the destination. Later edits to older calls only arrive with a Refresh and Retain Records sync. This includes a tag added weeks later. Clearing calls, using Refresh and Remove Records, or using Overwrite permanently deletes calls older than six months. See Six months of call history.
  • conversations uses the time of the last call or message. Closing, reopening or assigning a conversation without new activity doesn’t change that time. Those changes arrive with the next activity or a full refresh.
  • conversation_engagements reads engagements from the conversations returned by conversations. Incremental syncs only read conversations active since three days before the previous sync.
  • The conversation intelligence streams read results from the calls returned by calls. Incremental syncs only read calls started since three days before the previous sync. Their cursor is call_started_at, the call’s started_at.

Every other stream supports full refresh only. Aircall filters some lists, including contacts, numbers and users, by creation date. It doesn’t filter them by update date, so incremental sync would miss edits to existing records (List all Contacts, List all Numbers).

Supported streams

StreamSync modesPrimary keyPlan or add-on
call_action_itemsFull refresh, incrementalcall_id, idAI Assist or AI Assist Pro, opt-in
call_playbook_resultsFull refresh, incrementalidAI Assist Pro, opt-in
call_sentimentsFull refresh, incrementalidAI Assist or AI Assist Pro, opt-in
call_summariesFull refresh, incrementalidAI Assist or AI Assist Pro, opt-in
call_topicsFull refresh, incrementalidAI Assist or AI Assist Pro, opt-in
call_transcriptionsFull refresh, incrementalidAI Assist or AI Assist Pro, opt-in
callsFull refresh, incrementalidAll plans
campaign_outcomesFull refreshidOutbound Campaigns
campaignsFull refreshidOutbound Campaigns
companyFull refreshNoneAll plans
contactsFull refreshidAll plans
conversation_engagementsFull refresh, incrementalidConversations API
conversationsFull refresh, incrementalidConversations API
numbersFull refreshidAll plans
sms_templatesFull refreshidAll plans
tagsFull refreshidAll plans
teamsFull refreshidAll plans
trackersFull refreshidAI Assist or AI Assist Pro
user_availabilityFull refreshidAll plans
user_numbersFull refreshuser_id, idAll plans
usersFull refreshidAll plans
webhooksFull refreshwebhook_idAll plans
whatsapp_templatesFull refreshnumber_id, idNumbers registered for WhatsApp

Notes:

  • calls includes ivr_options_selected, the IVR options selected by the caller (List all Calls). Aircall returns it only for calls from the last two months. Calls synced before version 1.1.0 receive it only through a Refresh and Retain Records sync. This also applies only to calls from the last two months. A refresh immediately after upgrading loses nothing because earlier versions never synced the field. A later refresh re-reads calls from two to six months ago without it. In Incremental | Append + Deduped, this empties values synced while those calls were recent.
  • company has no primary key. Aircall returns one company object without an identifier (Retrieve Company information).
  • contacts returns only shared contacts (List all Contacts).
  • users reads the User V2 API.
  • user_numbers returns the numbers assigned to each user, with user_id identifying the user. It makes at least one request for each user.
  • webhooks uses webhook_id, the UUID that identifies a webhook. Aircall treats the integer id as the old identifier (List all Webhooks).
  • conversation_engagements returns each conversation’s calls, messages, WhatsApp messages, assignments, unassignments, closes and reopens. The first sync and every full refresh make at least one request for each conversation. Each incremental sync re-reads engagements for every conversation active since three days before the previous sync. Syncing more often than daily therefore repeats most of that work.
  • whatsapp_templates returns each number’s templates, with number_id identifying the number.

Limitations and troubleshooting

10,000-result limit

Aircall returns up to 10,000 calls, contacts, conversations or engagements for one query, including paginated queries (Pagination, List all Conversations). The connector handles this limit for each stream:

  • By default, calls are requested one day at a time (Window size (days)). The connector splits windows containing over 10,000 calls into smaller time ranges and reads them again. Some calls are therefore sent more than once, while Incremental | Append + Deduped keeps one row per call.
  • contacts are requested in 30-day creation-date periods (Contacts window size (days)). If a sync fails with Aircall returns at most 10,000 contacts per request window, lower that setting. The connector can’t read a single day containing over 10,000 new contacts.
  • conversations continue from the last record’s time after every 10,000 records.
  • conversation_engagements returns up to the newest 10,000 engagements in a conversation. Older engagements aren’t synced.

Conversation intelligence

The call_transcriptions, call_sentiments, call_topics, call_summaries, call_action_items and call_playbook_results streams exist only when Sync conversation intelligence (AI Assist) is on. They require the AI Assist or AI Assist Pro package. Playbook results require AI Assist Pro (Conversation Intelligence). Without the package, a sync selecting these streams fails with Conversation intelligence needs the AI Assist or AI Assist Pro package. For call_playbook_results, it fails with Playbook results need the AI Assist Pro package. Add the package or deselect streams excluded from your plan. If you turn off the option, refresh the source schema or deselect all six streams. A sync that still selects them reports them as incomplete.

Each selected stream reads the calls included in the sync. It reuses call responses already fetched during that sync when the request matches. It then makes one request for each call. The first sync and every full refresh request all six months of calls kept by Aircall. Each incremental sync requests calls started since three days before the previous sync. Daily syncs therefore request about four days of calls each time. All selected streams share the connector’s rate limit of 100 requests per minute, so their durations add together. Each stream takes about one hour for every 6,000 calls. For a company with 1,000 daily calls, each stream adds about 40 minutes to each daily sync. It also adds about 30 hours to the first sync. All six streams take about four hours per sync. Their first sync takes about 180 hours, or seven and a half days. In incremental modes, an interrupted first sync resumes from its last checkpoint during the next sync. Interruptions include failures and the platform’s sync time limit. The resumed sync re-reads the three preceding days of calls. In full refresh modes, the next sync restarts with all six months of calls. Select only the streams you need. For the first incremental sync, select one or two, then add the others to later syncs. Calls without a result, including missed calls, are skipped with a log message.

Results changed after a call only reach incremental sync while that call remains within the three-day lookback. This includes edited action items. Later changes arrive only through a Refresh and Retain Records sync, as they do for calls.

Six months of call history

Aircall keeps only six months of call history in the API (List all Calls). The connector reads calls from 365 days ago during every full refresh and the first incremental sync. This covers all history kept by Aircall. Older calls aren’t returned. Syncing calls in Overwrite mode, clearing it, or running Refresh and Remove Records permanently deletes older calls from the destination. Keep calls in Incremental | Append + Deduped, then use Refresh and Retain Records to re-read the last six months. In Incremental | Append + Deduped, that refresh empties ivr_options_selected for calls from two to six months ago. Aircall only returns it for calls from the last two months. Copy the calls table before clearing it or changing its sync mode.

Rate limit

Aircall allows 120 requests per minute for each company (Rate limiting). Every API key and integration on your Aircall account shares this limit. Each sync uses up to 100 requests per minute. When Aircall rejects a request for exceeding the limit, the connector waits for Aircall to reset the counter. Raising Concurrent workers doesn’t increase this limit. Aircall Support can increase the limit for your API keys. A higher limit reduces waits when your syncs and other integrations exceed the limit together. However, one sync still sends no more than 100 requests per minute.

Streams that sync no records

Some streams require an Aircall add-on or a specific number setup. Without it, Aircall refuses the requests. The connector logs each refused request instead of failing the sync:

StreamRequirement
conversations, conversation_engagementsThe Conversations API must be enabled for your company (List all Conversations). Without it, each sync still spends one request per 30 days since January 2014 on each of the two streams, about 157 each, so deselect both streams.
trackersThe AI Assist or AI Assist Pro package (List all Trackers).
whatsapp_templatesOnly numbers registered for WhatsApp return templates (List WhatsApp Templates).

A sync failing with Aircall rejected the API ID and API token or Aircall returned HTTP 403 indicates an incorrect or deleted API key. It can also mean your Aircall plan excludes that data. Create a new API key and update the source, or check your plan. For conversation intelligence streams, see Conversation intelligence.

Upgrade to 1.0.0

Version 1.0.0 adds primary keys to calls and contacts. It changes the webhooks primary key to webhook_id. It also makes numbers and teams full refresh only and changes several column types. Some destinations require a step before upgrading or running the first 1.0.0 sync. This applies to ClickHouse for Full Refresh | Append users (Before you upgrade) and Snowflake for append-mode calls (If you keep an append-mode calls table). After upgrading, refresh the source schema. Switch numbers and teams from an Incremental mode to Full Refresh | Overwrite. Clearing calls or switching it to Overwrite mode permanently deletes calls older than six months. Follow the migration guide.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
1.1.02026-11-1192012Add user_numbers, IVR options on calls and opt-in conversation intelligence streams
1.0.02026-11-1190838Add primary keys to calls and contacts, key webhooks on webhook_id, make numbers and teams full refresh only, and declare the column types the Aircall API documents
0.6.12026-11-1091341Update dependencies
0.6.02026-11-0990837Add conversations, conversation_engagements, campaigns, campaign_outcomes, trackers, sms_templates and whatsapp_templates streams
0.5.02026-11-0990835Read calls incrementally in daily windows that split at Aircall’s 10,000-result limit, read contacts in date windows, honour Aircall’s rate limit, declare user_availability id and availability, and read numbers and teams once per sync
0.4.272026-10-1388524Update dependencies
0.4.262026-10-0687742Update dependencies
0.4.252026-09-2987057Update dependencies
0.4.242026-09-2385909Migrate the users stream to the Aircall User V2 API ahead of the V1 sunset and add pagination
0.4.232026-09-2286517Update dependencies
0.4.222026-09-1585956Update dependencies
0.4.212026-09-0885381Update dependencies
0.4.202026-08-1884505Update dependencies
0.4.192026-08-1183832Update dependencies
0.4.182026-08-0483374Update dependencies
0.4.172026-07-2882810Update dependencies
0.4.162026-07-2182307Update dependencies
0.4.152026-07-1481718Update dependencies
0.4.142026-06-3080992Update dependencies
0.4.132026-06-2380364Update dependencies
0.4.122026-06-1679750Update dependencies
0.4.112026-06-0979207Update dependencies
0.4.102026-06-0278574Update dependencies
0.4.92026-04-2877183Update dependencies
0.4.82026-04-2176490Update dependencies
0.4.72026-03-1774979Update dependencies
0.4.62026-02-1073001Update dependencies
0.4.52026-01-2772373Update dependencies
0.4.42026-01-1471503Update dependencies
0.4.32025-12-0270282Update dependencies
0.4.22025-10-2965055Update dependencies
0.4.12025-09-1266197Update to CDK v7
0.4.02024-08-2344597Refactor connector to manifest-only format
0.3.02024-08-1944437Fix pagination
0.2.122024-08-1743879Update dependencies
0.2.112024-08-1043482Update dependencies
0.2.102024-08-0343101Update dependencies
0.2.92024-07-2742743Update dependencies
0.2.82024-07-2042357Update dependencies
0.2.72024-07-1341708Update dependencies
0.2.62024-07-1041448Update dependencies
0.2.52024-07-0941156Update dependencies
0.2.42024-07-0640801Update dependencies
0.2.32024-06-2540503Update dependencies
0.2.22024-06-2139920Update dependencies
0.2.22024-06-2039681Update dependencies
0.2.12024-06-0638454[autopull] base image + poetry + up_to_date
0.2.02023-06-20Correcting availablity typoCorrecting availablity typo
0.1.02023-04-19InitInitial commit
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.