---
name: azion-install-the-phone-validation-integration
description: >-
  Install Phone Validation from Azion Marketplace and run it on a firewall to check phone numbers against IPQualityScore before requests reach your origin.
---

# Install the Phone Validation integration

You install the Phone Validation integration from Azion Marketplace and run it on a [Firewall](/en/documentation/platform/firewall/), from Azion Console. The integration checks phone numbers with the IPQualityScore API: risk score, country of origin, carrier, line type, and connection status. On each request, the function reads the phone number from the query string, the request body, or a header, queries IPQualityScore, and then blocks the request, drops it, or adds a header to signal the result. This stops fraudulent numbers, inactive lines, and high-risk VOIPs before they reach your origin.

Five objects have to exist before a request is checked: the installed function, a firewall carrying the **Functions** module, a function instance holding the arguments, a Rules Engine rule with the **Run Function** behavior, and a workload deployment bound to the firewall. Each section below creates one of them.

---

## Prerequisites

- An Azion account. To sign in, refer to [How to access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/).
- An application served by a [workload](/en/documentation/platform/workloads/), whose deployment you bind to the firewall in the last section.
- An [IPQualityScore account](https://www.ipqualityscore.com/create-account). After you create it, get your API key from the IPQualityScore dashboard.
- The [Azion CLI](/en/documentation/devtools/cli/) installed and authorized, for the last section.
- Turning on a product or a module can generate usage costs. For more information, refer to [Pricing](/en/documentation/fundamentals/pricing/).

---

## Install the integration

The function is installed once per account. To install it:

1. **Open Marketplace**

   Access [Azion Console](https://console.azion.com/) > **Marketplace**.

2. **Find the integration**

   Enter `Phone Validation` in the **Search on Marketplace** field, then select the integration's card. Browsing the cards and the categories reaches the same page.

3. **Select Install**

The card shows `Successfully installed!` and `Latest version installed!`, and the function appears in the **Function** list of the **Create Instance** drawer.

---

## Create the firewall

The firewall is where the function is instanced and where the rule that runs it lives. To create one:

1. **Open the Firewalls page**

   Access [Azion Console](https://console.azion.com/) > **Firewalls**, then create a firewall.

2. **Name the firewall**

   In the **General** section, enter a **Name**. For example: `phone-validation-firewall`.

3. **Turn on the Functions module**

   In the **Modules** section, turn on the **Functions** switch.

4. **Save the firewall**

The firewall shows a **Functions Instances** tab while the **Functions** module stays on. To use an existing firewall instead, turn on its **Functions** module and save it. For every setting on this form, refer to [Set a firewall's main settings](/en/documentation/guides/application-security/firewall-and-waf/firewall-configure-main-settings/).

---

## Create the function instance

The instance holds your IPQualityScore API key, where the phone number comes from, and what to do with a risky one. To create it:

1. **Open the Functions Instances tab**

   In **Firewalls**, select your firewall, then select the **Functions Instances** tab.

2. **Select + Function**

   A firewall that has no instance shows the same action as **Function Instance**. The **Create Instance** drawer opens.

3. **Name the instance**

   In **Name**, enter a name. For example: `phone-validation`.

4. **Select the installed function**

   In **Function**, select the Phone Validation function. The list holds only the functions that run on a firewall.

5. **Enter the arguments**

   In **Arguments**, the editor is prefilled with the integration's default arguments in JSON. Enter your values, as the next section describes.

6. **Select Save**

The instance is listed in the **Functions Instances** tab.

### Arguments

The instance takes your API key, the source of the phone number, and the action:

```json
{
  "api_key": "YourIPQSAPIKey",
  "fast": true,
  "get_data_from": "querystring",
  "data_name": "phone",
  "when_score_above": 80,
  "execute": "deny"
}
```

| Variable           | Required | Description                                                                                                                                            |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api_key`          | Yes      | Your IPQualityScore API key                                                                                                                            |
| `fast`             | No       | Turns on fast validation mode. When `true`, the API skips some forensic checks for lower latency. Recommended: `true`. Default: `false`                |
| `get_data_from`    | Yes      | Where the function reads the phone number. Accepted values: `querystring`, `body`, `header`                                                            |
| `data_name`        | Yes      | The name of the query string parameter, body field, or header that holds the phone number                                                              |
| `when_score_above` | No       | The score threshold (0–100) that triggers the action in `execute`. A fraud score ≥ 90 is high risk. If you do not set it, the function takes no action |
| `execute`          | No       | The action when the score exceeds `when_score_above`. Accepted values: `deny`, `drop`, `add_header`                                                    |

Each `execute` value does the following:

| Value        | Behavior                                                                                                                                              |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deny`       | Runs the **Deny** behavior, which returns a `403 Forbidden` response                                                                                  |
| `drop`       | Runs the **Drop** behavior, which closes the connection without a response                                                                            |
| `add_header` | Adds the `ipqs-limit-score-reached` header to the request and lets the request continue. Use it to handle the result in Rules Engine or at the origin |

> **Note**
>
> The key data points the IPQualityScore API returns are `valid`, `risky`, `active`, `line_type`, `carrier`, `VOIP`, `fraud_score`, and `recent_abuse`. For every field, refer to the [IPQualityScore Phone Number Validation API documentation](https://www.ipqualityscore.com/documentation/phone-number-validation-api/overview).

---

## Create the rule

The instance checks nothing until a rule runs it. A [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine/) rule selects the requests that reach the instance, through a **Run Function** behavior. To create the rule:

1. **Open the Rules Engine tab**

   In **Firewalls**, select your firewall, then select the **Rules Engine** tab.

2. **Select + Rule**

3. **Name the rule**

   In **Name**, enter a name. For example: `Run Phone Validation`.

4. **Set the criterion**

   In the **Criteria** section, select the requests that trigger the phone validation check. For example: if `Host` *matches* `yourdomain.com`.

5. **Add the Run Function behavior**

   In the **Behaviors** section, select **Run Function**, then select the instance by the name you gave it.

6. **Select Save**

The firewall runs the instance on every request that matches the criterion.

---

## Bind the firewall to the workload

The binding is on the workload's deployment, so create a deployment that names both the application and the firewall:

```bash
azion create workload-deployment --workload-id <workload-id> --name <deployment-name> \
  --application-id <application-id> --firewall-id <firewall-id> --strategy-type default \
  --active true --current true
```

The command prints the id of the new deployment:

```text
Created Workload Deployment with ID 123456
```

Requests to the workload's domain reach the firewall, and the rule runs the Phone Validation instance on each one that matches.

---

## Next steps

- [Marketplace integrations](/en/documentation/platform/marketplace/integrations.md): Every integration Azion Marketplace offers, and where each one runs.
- [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine.md): Every criterion and behavior a firewall rule accepts.
- [Install the URL Validation integration](/en/documentation/guides/application-development/integrations/ipqs-url-validation.md): Scan the URLs in requests with IPQualityScore.
- [Update an integration](/en/documentation/guides/application-development/integrations/update-an-integration.md): Move an installed integration to its latest version.