# Integrate Cloud Voice with Microsoft SQL

Linking Cloud Voice to a Microsoft SQL database lets the system look up incoming callers in your own contact records. When a number on an inbound call matches a row in the database, Cloud Voice shows the caller's name instead of a bare number. This page walks you through connecting the database, defining the lookup query, and mapping the fields used for caller display.

## Requirements

| Item | Requirement |
| --- | --- |
| Cloud Voice | Enterprise Plan (EP) or Ultimate Plan (UP), running firmware `84.16.0.70` or later. |
| Microsoft SQL | Any version of Microsoft SQL Server works. There are no version restrictions. |

## Step 1. Turn on the Microsoft SQL integration

1. Open the integration settings.
   1. Sign in to the Cloud Voice management portal and go to **Contacts > Company Contacts**.
   2. Click **Synchronize Contacts** at the top of the page.

      ![Company Contacts page with the option to synchronize contacts from a third-party source](/images/pbx/sync-contacts-from-thirdparty.png)

2. Switch on **Enable Microsoft SQL Integration** and fill in the connection details described below.

   ![Microsoft SQL integration settings with connection fields and the auto-match filter](/images/pbx/ms-sql-integration-pce.png)

   | Field | What to enter |
   | --- | --- |
   | Server Address | The address of your SQL server. If the server listens on the default port `1433`, enter only its IP address or domain name (for example, `112.48.21.123`). If it listens on a different port, append the port (for example, `112.48.21.123:20001`). |
   | Database Name | The name of the database to query. |
   | Timeout(s) | How long, in seconds, Cloud Voice waits when connecting to the server before giving up. |
   | User | The account name used to connect to the database. |
   | Password | The password for that account. |
   | Auto-match Contact Filter | A `SELECT` statement that tells Cloud Voice how to find a caller in your data (see below). |

   :::caution
   The SQL server must be reachable from Cloud Voice at the address and port you enter here. If it is not (for example, a firewall blocks the port or the address is wrong), saving fails once the connection attempt runs out of time. The **Timeout(s)** value sets how many seconds Cloud Voice waits before reporting that failure.
   :::

   :::tip
   Create a dedicated database login for this integration and give it read-only access. Cloud Voice only reads contact rows (for caller lookup and, optionally, one-way synchronization into the PBX), so it never needs permission to change your data.
   :::

### Write the auto-match filter

The **Auto-match Contact Filter** is a `SELECT` statement in the form:

```
select ${MAP} from {schema_name}.{table_name} where {condition_to_filter_number}
```

For example:

```
select ${MAP} from testpbx.contacts where businumber like CONCAT('%', ${NUMBER}, '%')
```

Each part does the following:

- **`select ${MAP}`**, the column whose value becomes the caller ID name. At runtime, `${MAP}` is replaced by the field or fields (First Name, Last Name, or both) you turn on in the [Map section](#step-2-map-fields-between-cloud-voice-and-microsoft-sql).
- **`from testpbx.contacts`**, the source table, written as a two-part name (`{schema_name}.{table_name}`).
- **`where businumber like CONCAT('%', ${NUMBER}, '%')`**, the match condition. Here it returns any row whose `businumber` value contains the incoming number (`${NUMBER}`) anywhere in the string.

## Step 2. Map fields between Cloud Voice and Microsoft SQL

1. Scroll down to the **Map** section.
2. Map the fields needed to show the caller's name.

   
   ![Cloud Voice, field mapping between Cloud Voice contact fields and Microsoft SQL columns](/images/pbx/sql-caller-id-map.png)

   1. For **Contacts ID**, **First Name**, and **Business Number**, enter the matching column name from your Microsoft SQL contacts table.

      :::note
      In the example filter, **Business Number** is mapped because it is the field used to match the number. Map whichever number field applies to your own data.
      :::

      Once a call matches a contact, the contact's first name is shown.
   2. **Optional:** To display the last name too, select the **Last Name** checkbox and enter its corresponding Microsoft SQL column name.
3. To also copy Microsoft SQL contacts into Cloud Voice, enable the fields you want to synchronize and map each one to a column.

   ![Additional field mappings used when synchronizing Microsoft SQL contacts into Cloud Voice](/images/pbx/sql-map-contacts-sync.png)

4. Click **Save**.

## Result

- Cloud Voice connects to your Microsoft SQL server.

  ![Confirmation that the Microsoft SQL connection succeeded](/images/pbx/ms-sql-integration-success.png)

- When an inbound call matches a record in the database, the caller's name appears on the call.

## What to do next

To let extension users place calls to your Microsoft SQL contacts directly from the Cloud Voice App, set up contact synchronization from the SQL server. See [Set up Contact Synchronization from Microsoft SQL](/pbx/integrations/microsoft-sql/set-up-contact-synchronization-from-microsoft-sql/).