# How to Install the IPQualityScore Phone Validation Integration

**IPQualityScore Phone Validation** is a Firewall integration that validates phone numbers in real-time, analyzing risk score, country of origin, carrier, line type, and connection status. It helps your application detect fraudulent phone numbers, inactive lines, and high-risk VOIPs before they reach your origin.

When a request arrives at the edge, the function extracts the phone number from the configured source (query string, request body, or header), queries the IPQualityScore API, and either blocks the request, drops it, or adds a header to signal the result — depending on the action you configure.

---

## Requirements

To start using this integration, you need to:

- Create an [IPQualityScore account](https://www.ipqualityscore.com/create-account).
- Obtain your **API Key** from the IPQualityScore dashboard after account creation.

---

## Getting the integration

To install this integration:

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Marketplace**.
2. On the Marketplace homepage, select the **Phone Validation** card.
3. On the integration page, click the **Install** button.

You'll see a message indicating that your integration was successfully installed.

:::tip
You can search for any integration by browsing through the cards, using the filters, or typing a keyword in the search bar.
:::

---

## Configuring the integration

Once you've installed the **IPQualityScore Phone Validation** integration, complete the steps below to configure it.

### Setting up a Firewall

Follow the steps:

1. On the upper-left corner, open the **Products menu** and select **Firewall** in the **Secure** section.
2. Click the **+ Firewall** button.
3. Give an easy-to-remember name to your firewall.
4. Enable the **Functions** option in the **Modules** section.
   - This action gives access to functions in the firewall.
5. Click the **Save** button.

Done. Now you've instantiated the firewall for your function and have access to functions in your firewall.

:::caution[Attention]
If a product or module is activated, it may generate usage-related costs. Check the [pricing page](/en/documentation/products/pricing/) for more information.
:::

### Setting up the Firewall function

While still on the **Firewall** page:

1. Select the **Functions Instances** tab.
2. Click the **+ Function Instance** button.
3. Give an easy-to-remember name to your instance.
4. On the dropdown menu, select the **IPQualityScore Phone Validation** function.
5. In the **Arguments** box, pass your variables:

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

Where:

| Variable | Mandatory | Description |
| ---- | ---- | ---- |
| `api_key` | Yes | Your IPQualityScore API Key |
| `fast` | No | Enables fast validation mode. When `true`, some forensic checks are skipped for lower latency. Recommended: `true`. Default: `false` |
| `get_data_from` | Yes | Defines where the phone number is extracted from. Accepted values: `querystring`, `body`, `header` |
| `data_name` | Yes | The name of the query string parameter, body field, or header that contains the phone number |
| `when_score_above` | No | Score threshold (0–100) that triggers the action defined in `execute`. Fraud scores ≥ 90 are considered high risk. If not set, no action is taken |
| `execute` | No | Action to take when the score exceeds `when_score_above`. Accepted values: `deny`, `drop`, `add_header` |

The `execute` values behave as follows:

| Value | Behavior |
| ---- | ---- |
| `deny` | Executes the **Deny** behavior, returning a `403 Forbidden` response |
| `drop` | Executes the **Drop** behavior, closing the connection without a response |
| `add_header` | Adds the `ipqs-limit-score-reached` header to the request and lets it continue. Use this when you want to handle the result in the Rules Engine or at the origin |

:::note
The key data points returned by the IPQualityScore API are: `valid`, `risky`, `active`, `line_type`, `carrier`, `VOIP`, `fraud_score`, and `recent_abuse`. For the full list of fields and their descriptions, see the [IPQualityScore Phone Number Validation API documentation](https://www.ipqualityscore.com/documentation/phone-number-validation-api/overview).
:::

6. Click the **Save** button.

### Setting up the Rules Engine

To finish, you must set up a rule in **Rules Engine** to configure the **criteria** and the **behavior** to run the function.

Still on the **Firewall** page:

1. Select the **Rules Engine** tab.
2. Click the **+ Rule Engine** button.
3. Give an easy-to-remember name to the rule.
4. Select a *criteria* to define which requests trigger the phone validation check.
   - Example: if `Host` *matches* `yourdomain.com`.
5. Below, select **Run Function** as the *behavior* and choose the Phone Validation function instance you created earlier.
6. Click the **Save** button.

### Associating the Firewall with your domain

On the Console, you must now configure your domain so it is protected by your Firewall.

1. On the **Products menu**, select **Workloads**.
2. Click on the workload that contains the domain you want to protect with your **Phone Validation** function.
3. In the **Deployment Settings** section, click on the `Firewall` selector and choose the Firewall you've just created.
4. Click the **Save** button.

Done. Now the **IPQualityScore Phone Validation** integration is running and validating phone numbers at the edge.

---

## Related documentation

- [Azion Integrations reference](/en/documentation/products/marketplace/integrations/)
- [How to install an integration](/en/documentation/products/marketplace/install-an-integration/)
- [How to update an integration](/en/documentation/products/marketplace/update-an-integration/)
- [IPQualityScore Phone Number Validation API documentation](https://www.ipqualityscore.com/documentation/phone-number-validation-api/overview)