When using the Aircall Salesforce integration, you may notice that some call tasks are not linked to the correct records in Salesforce, especially when there are duplicate phone numbers or when your team uses custom phone fields. This article explains how matching works so you can better control and improve task association.

Common symptoms

Users often report issues such as:

  • Call tasks being attached to the wrong Contact, Lead, Account, or Person Account
  • Records with populated custom phone fields not receiving call tasks
  • Confusion about which phone fields are used for matching

Typical questions include:

  • Which phone number fields are used to match tasks in Salesforce?
  • Are custom phone fields included in the matching criteria?

How task matching works

The Aircall integration primarily uses standard Salesforce phone fields to match call tasks to records. In particular:

  • The integration focuses on the main phone number and mobile phone fields.
  • It does not natively use custom phone fields as part of its matching logic.

If a record has empty standard phone fields, but populated custom phone fields, then the integration may fail to associate call tasks with that record, even though the number exists in Salesforce.

The integration searches for a match in the following priority order:

  1. Contact
  2. Lead
  3. Account
  4. Person Account

Steps to improve task matching accuracy

Follow these steps to help ensure that call tasks are matched to the correct Salesforce records.

Steps

  1. Use E.164 format for phone numbers
    Make sure that phone numbers are saved in the main phone and mobile phone fields using the E.164 format (for example, +14155552671).
    This format helps the integration recognize and match numbers consistently.
  2. Populate standard phone fields, even if you use custom fields
    If your organization relies on custom phone fields:
    • Manually copy the phone numbers from the custom phone fields into the standard phone and mobile phone fields.
    • Ensure that these standard fields contain the same values your agents dial, formatted in E.164.

  3. Align data with the matching priority order
    Keep in mind the integration matches in this order:

    1. Contact
    2. Lead
    3. Account
    4. Person Account

    If the same number is used in multiple records, the first match in this sequence may receive the task, which can cause unexpected associations.

  4. Reduce duplicate phone numbers across records
    Review your Salesforce data and reduce or eliminate duplicate phone numbers used across multiple Contacts, Leads, Accounts, and Person Accounts.
Important: The Aircall Salesforce integration can read custom fields, but its core matching logic relies mainly on standard fields such as main phone and mobile phone. Relying solely on custom phone fields can result in missed or incorrect task matches.

Additional considerations and limitations

  • Custom phone fields are not part of the native task matching logic.
  • Standard phone and mobile fields should always be considered the primary source of truth for numbers used by the integration.
  • Duplicate numbers spread across multiple records increase the risk of mismatched tasks.

Related resources

For more information on configuring your Salesforce integration and managing fields, you may find the following articles helpful: