How to Install the IPQualityScore Phone Validation Integration

Validate phone numbers at the edge and detect fraudulent activity in real-time with the IPQualityScore Phone Validation integration.

View as Markdown

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.
Obtain your API Key from the IPQualityScore dashboard after account creation.

Getting the integration

To install this integration:

Access Azion Console > Marketplace.
On the Marketplace homepage, select the Phone Validation card.
On the integration page, click the Install button.

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

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:

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

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

Attention — If a product or module is activated, it may generate usage-related costs. Check the pricing page for more information.

Setting up the Firewall function

While still on the Firewall page:

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

{

"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

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.

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:

Select the Rules Engine tab.
Click the + Rule Engine button.
Give an easy-to-remember name to the rule.
Select a criteria to define which requests trigger the phone validation check.
- Example: if Host matches yourdomain.com.
Below, select Run Function as the behavior and choose the Phone Validation function instance you created earlier.
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.

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

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