# Contact match

> Route calls differently depending on whether the caller is saved in one of your phonebooks.

- URL: https://kb.voipcloud.online/pbx/conditions/contact-match/
- Section: PBX › Conditions
- Type: reference
- Applies to: All countries
- PBX object: contact_match
- Last reviewed: 2026-11-09

**Contact match** checks whether the caller's number is saved in the phonebooks you choose. Calls from a saved contact take the **Matches** path, all others take **Doesn't match**.

For example, send calls from existing customers straight to their account team, and play a welcome menu to everyone else.

## Add it to your call flow

1. Create a [phonebook](https://kb.voipcloud.online/pbx/settings/phonebooks/) with the numbers you want to match, if you don't have one yet.
2. Drag **Contact match** from the **Conditions** group onto the canvas and click the gear icon.
3. Enter a **Name**.
4. Under **Phonebooks**, click **Add**, choose one or more phonebooks (or **Select all**) and click **Add**.
5. Click **Save**, connect the paths, and click **Apply configuration**.

## Settings

| Setting | What it does | Default/notes |
| --- | --- | --- |
| Name | Label on the canvas. | |
| Phonebooks | The phonebooks searched for the caller's number. A match in any of them counts. | Required: add at least one phonebook. |

## Call paths

| Path | When it's used |
| --- | --- |
| **Matches** | The caller's number is saved as a contact in at least one of the chosen phonebooks. |
| **Doesn't match** | The number isn't in any of them, or the caller's number is hidden. |

If a path isn't connected, the call ends.

## How numbers are matched

- The caller's number is compared in both local and international format, so a contact saved as 0412 345 678 or +61 412 345 678 in the PBX matches the same caller.
- Only the phone number counts. The contact's name doesn't matter.
- Callers with a hidden number always take **Doesn't match**.
- If the phonebook lookup can't be completed in time, the call takes **Doesn't match**.
- When you import contacts from a file, save the numbers without a leading **+** (for example 61412345678 or 0412345678). Imported numbers keep the **+**, and the lookup compares digits only, so a number imported with a **+** doesn't match.

## Tips and limits

- **Contacts take effect straight away.** The phonebooks are searched while the call is coming in, so contacts you add or remove change the result on the next call, even before you apply the configuration.
- **Changing which phonebooks are searched does need Apply configuration.** Until you apply, the object keeps searching the phonebooks it had before.
- To route by area or state instead of by contact, use [GEO routing](https://kb.voipcloud.online/pbx/conditions/geo-routing/). To refuse calls from certain numbers, use a [Blocklist](https://kb.voipcloud.online/pbx/protection/blocklist/).

## Related

- [Phonebooks](https://kb.voipcloud.online/pbx/settings/phonebooks/)
- [GEO routing](https://kb.voipcloud.online/pbx/conditions/geo-routing/)
- [Time conditions](https://kb.voipcloud.online/pbx/conditions/time-conditions/)