Skip to main content

How to Configure IPQS Integration in LeadExec

IPQualityScore (IPQS) integrates with LeadExec to analyze incoming leads for potential fraud or suspicious activity.

Written by Gabriel Buck

Overview

IPQualityScore (IPQS) is a fraud prevention service that analyzes phone numbers to detect risk indicators such as fraud activity, VoIP usage, prepaid lines, and abuse history.

By integrating IPQS with LeadExec, you can automatically evaluate phone numbers during lead submission and take action based on the results. This helps improve lead quality and prevents fraudulent or low-quality leads from entering your workflows.


Key Functionality

The IPQS integration in LeadExec provides several tools to help validate phone numbers and automate lead quality control.

1. Phone Fraud Detection

  • Analyze phone numbers using Fraud Score to determine the likelihood of fraudulent activity.

  • Identify numbers linked to recent abuse, spam activity, or known fraud patterns.

2. Phone Line Intelligence

  • Detect whether a number is VoIP, prepaid, or a standard carrier line.

  • Retrieve carrier details such as Carrier Name, Line Type, Country, Region, and City.

3. Automated Lead Filtering

  • Create criteria rules based on returned data such as Fraud Score, VoIP status, or Do Not Call flags.

  • Automatically reject leads, route them to quality control.


Before You Begin

Before configuring the integration in LeadExec, ensure the following requirements are completed:

  • Obtain the API Key
    Make sure you have an active API key from the third-party service (IPQS). This key is required for LeadExec to authenticate and send validation requests.

  • Create Required Lead Fields
    Any response fields you plan to store (such as Fraud Score, VoIP status, or other returned values) should be created in the Lead Type configuration before setting up the integration. Creating these fields ensures that the returned validation data can be stored and viewed within LeadExec.

How to Set Up IPQS in LeadExec


Step 1: Enable the IPQS Integration

Before configuring the integration, you will need your IPQS API Key from your IPQS account.

To enable the integration:

  1. Navigate to Integrations in the left toolbar within LeadExec.

  2. Locate the IPQS integration.

  3. Click Details.

  4. Toggle the integration On.

  5. Enter your API Key in the required field.

  6. Click Save.

Once saved, the integration will be available for configuration.


Step 2: Configure Settings by Lead Type

After enabling the integration, click Details to open the system-wide settings.

These settings are configured per Lead Type.

To add a configuration:

  1. Navigate to Lead Type Configuration.

  2. Click New.

  3. Select the desired Lead Type / Industry.

Once the Lead Type has been added, you will be prompted to the Request and Response fields window.


Step 3: Configure Request Fields

Request fields determine the data that LeadExec sends to IPQS for validation.

Phone Number (Required)

The phone number that IPQS will evaluate.

Map this parameter to the corresponding phone number field in your Lead Type.

Make sure the submitted number is properly formatted and includes enough

information for IPQS to identify the country.

Strictness Level

Determines how aggressively IPQS evaluates the phone number for potential fraud.

Available values:

Value

Level

Description

0

Loose

Less aggressive fraud evaluation

1

Normal

Moderate fraud evaluation

2

Strict

More aggressive evaluation that may increase false positives

Higher strictness settings may increase fraud scores or apply additional scrutiny to suspicious numbers.

Choose the level that best matches your validation requirements.

Country Code(s)

Specifies the expected countries associated with the phone number.

Examples:

Value

Country

US

United States

CA

Canada

GB

United Kingdom

You can specify multiple supported country codes when necessary, such as US,CA.

This parameter is particularly important when submitting phone numbers with fewer than 10 digits.

Important: Use country codes rather than full country names.

Enhanced Line Check

Enables an enhanced active-line validation using IPQS's HLR lookup and carrier information, where supported.

Available values:

  • true — Enable enhanced checking.

  • false — Disable enhanced checking.

This feature can provide additional information about whether a phone number is active or disconnected.

Note: Enhanced line validation may require an additional IPQS service or subscription feature. Confirm availability and pricing with IPQS before enabling it.

Enhanced Name Check

Enables additional name lookup functionality when supported by your IPQS account.

Available values:

  • true — Enable enhanced name checking.

  • false — Disable enhanced name checking.

Additional name data availability depends on the phone number, region, and IPQS subscription.


Step 4: Configure Response Fields

Response fields determine which values returned by IPQS are stored in LeadExec.

Before mapping these fields, make sure the corresponding fields exist in your Lead Type configuration.

Phone Validation and Fraud Detection Fields

Response Field

Description

Possible Values

Success

Indicates whether the API request completed successfully

True, False

Valid

Indicates whether the phone number is considered valid

True, False

Fraud Score

Numerical indicator of potential fraud risk

0–100

Recent Abuse

Indicates association with recent or ongoing abusive activity

True, False, null

VoIP

Identifies Voice over IP or digital phone numbers

True, False, null

Prepaid

Indicates a prepaid phone service

True, False, null

Risky

Indicates association with suspicious or potentially fraudulent activity

True, False, null

Active

Indicates whether the phone line is active, when status information is available

True, False, null

Do Not Call

Indicates whether the number appears on supported DNC lists

True, False, null

Leaked

Indicates whether the phone number has appeared in a data breach

True, False

Spammer

Indicates whether the number has been associated with spam activity

True, False

Important: Some response values may be unavailable depending on the API request, country, or IPQS subscription.

In particular, the Active field may return null if enhanced subscriber-status validation is not enabled.

Understanding Fraud Score

IPQS uses a numerical Fraud Score from 0 to 100.

Higher values indicate greater potential risk.

Fraud Score

General Risk Interpretation

0–74

Below IPQS's suspicious-score threshold

75–84

Suspicious activity indicators

85–89

High-risk activity

90–100

Very high risk, including stronger indicators of abusive behavior

IPQS identifies scores of 85 or higher as risky, while scores of 90 or higher indicate particularly high risk.

For example:

  • Fraud Score = 0: Very low indicated fraud risk.

  • Fraud Score = 45: Below the typical high-risk threshold.

  • Fraud Score = 85: High risk.

  • Fraud Score = 95: Very high risk.

Recommended Criteria Example

If your goal is to reject higher-risk phone numbers:

Setting

Value

Field

Fraud Score

Operator

Greater Than or Equal To

Value

85

Action

Reject Lead

This configuration rejects leads with a Fraud Score of 85 or higher.

Important: Do not configure Fraud Score Less Than or Equal To 50 → Reject Lead when your intention is to reject fraudulent numbers.

That condition would reject lower-risk phone numbers rather than higher-risk ones.

A threshold of 80 can also be configured if your business requires more aggressive filtering, but it may reject additional legitimate leads.

Phone Line and Location Fields

IPQS also returns details about the phone number's carrier, line type, and geographic association.

Response Field

Description

Example

Line Type

Classification of the phone service

Wireless

Country

Two-letter country code

US

Region

State or region associated with the number

California

City

City associated with the phone number

Los Angeles

Carrier

Associated telecommunications provider

Carrier name

Active Status

More detailed subscriber connection status

Active Line

User Activity

Estimated level of legitimate phone usage

high

Understanding Country Values

The IPQS Country response returns a two-letter country code, not the full country name.

Examples:

Country

IPQS Response

United States

US

Canada

CA

United Kingdom

GB

Singapore

SG

Luxembourg

LU

Unknown

N/A

Recommended Criteria Example

To reject phone numbers that are not associated with the United States:

Setting

Value

Field

Country

Operator

Does Not Equal

Value

US

Action

Reject Lead

Using United States instead of US can cause legitimate US phone numbers to incorrectly match the rejection criteria.

Understanding Line Type Values

The Line Type field identifies the type of telephone service associated with the number.

IPQS documents the following values:

Line Type

Description

Wireless

Mobile or cellular phone number

Landline

Traditional landline service

VOIP

Voice over Internet Protocol service

Toll-Free

Toll-free telephone number

Satellite

Satellite telephone service

Premium Rate

Premium-rate telephone service

Pager

Pager service

N/A

Line type unavailable or unknown

LeadExec may also display Unknown when the response does not contain a recognizable line type.

Recommended Criteria Example: Accept Wireless Numbers Only

Setting

Value

Field

Line Type

Operator

Does Not Equal

Value

Wireless

Action

Reject Lead

This configuration rejects landlines, VoIP numbers, toll-free numbers, and any other line type that does not match Wireless.

Important: This rule should only be used when your campaign accepts wireless phone numbers exclusively.

If your campaign accepts both wireless and landline numbers, avoid using this condition. Instead, create individual rules to reject unwanted line types.

Also, do not use Standard carrier line as a comparison value, since it is not a documented IPQS line type.

Understanding Active Status

The Active Status field provides additional subscriber connection information when enhanced line validation is available.

Possible values include:

  • Active Line

  • Active Line - High Confidence

  • Active Line - Medium Confidence

  • Active Line - Low Confidence

  • Disconnected Line

  • Phone Turned Off

  • Inconclusive Status

  • N/A

This field is different from the basic Active response.

For example:

Active Equals False → Reject Lead

This condition can reject phone numbers identified as inactive.

However, the status may be unavailable when the relevant IPQS feature is not enabled. Always verify that your account is returning usable active-line results before relying on this criterion.

Understanding User Activity

The User Activity field estimates how frequently a phone number is associated with legitimate online activity, such as purchases or account registrations.

Possible values:

Value

Description

high

Frequent legitimate activity

medium

Moderate legitimate activity

low

Limited legitimate activity

none

No established history of legitimate activity

Values of high and medium are generally positive indicators.

A value of none does not necessarily indicate fraud. For example, recently activated phone numbers may not have enough activity history to receive a higher classification.

Note: This field is restricted to higher IPQS subscription tiers.

If your subscription does not support it, LeadExec may display a message such as Enterprise L4+ required. rather than an activity value.

Avoid creating rejection criteria based on this field unless your IPQS account provides the required data.


Step 5: Create Criteria Rules

After configuring the Request and Response fields, you can create criteria that determine how LeadExec processes leads based on the returned IPQS results.

To configure criteria:

  1. Open the Criteria section within your IPQS configuration.

  2. Click Add.

  3. Select the response field you want to evaluate.

  4. Choose the comparison operator.

  5. Enter the expected value.

  6. Select the appropriate action.

  7. Save your configuration.

Example: US Wireless Phone Validation

The following configuration is an example for a campaign that accepts only US wireless numbers and rejects phone numbers with significant fraud indicators.

Response Field

Condition

Value

Action

Fraud Score

Greater Than or Equal To

85

Reject

Valid

Equal To

False

Reject

Active

Equal To

False

Reject

VoIP

Equal To

True

Reject

Prepaid

Equal To

True

Reject

Country

Does Not Equal

US

Reject

Line Type

Does Not Equal

Wireless

Reject

These rules are examples and should be adjusted to match your business requirements and available IPQS response data.

For example, if your campaign accepts both wireless and landline phone numbers, the Line Type rule shown above would be too restrictive.

How Criteria Are Evaluated

When IPQS returns validation results, LeadExec compares those results against the configured criteria.

If a rejection condition is matched, the integration can reject the lead.

Multiple rejection criteria can match the same lead.

For example, IPQS may return:

Field

Value

Success

True

Valid

True

Fraud Score

0

Active

True

Country

SG

Line Type

Landline

In this example:

  • The Fraud Score rule does not trigger because the score is below 85.

  • The Active rule does not trigger because the number is active.

  • The Country rule triggers because SG does not equal US.

  • The Line Type rule triggers because Landline does not equal Wireless.

The lead would be rejected based on the Country and Line Type criteria, not because the phone number was identified as fraudulent.

Important: A lead rejected by an IPQS criterion is not necessarily a fraudulent lead. It may simply fail one of the eligibility requirements configured in LeadExec.

This allows LeadExec to automatically filter or route leads based on fraud risk indicators.


Step 6: Enable the Integration at the Campaign Level

After configuring the global integration settings, the integration must also be enabled at the campaign level.

To do this:

  1. Navigate to either the Lead Source List or Campaign List.

  2. Locate the desired campaign.

  3. Open the Integrations tab then Manage

  4. Add the IPQS integration to the campaign.

Once enabled, the integration will run automatically whenever leads are submitted through that campaign.

Note: Campaign-level integration settings are optional and are intended to override the global integration settings when configured. This allows each campaign to apply different validation rules, fraud thresholds, or data requirements depending on its specific needs, providing greater control over how leads are evaluated and routed through that particular campaign.


Step 7: Checking integration results.

Once the integration is set up, and lead start flowing into the system, you can filter results within the main Leads list view by adding the relevant columns and filters to your screen.

You can also review the integration results by opening the lead and navigating to the Integrations tab. From this window, you’ll be able to see the result and status of the integration for that specific lead.


Conclusion

By configuring the IPQS integration in LeadExec, you can automatically evaluate phone numbers and detect potential fraud before leads enter your workflows. This helps maintain higher lead quality, reduce risk, and improve overall lead management efficiency.

Troubleshooting

If the IPQS integration is not behaving as expected, use the following troubleshooting steps.

How to Test the Integration

  1. Navigate to the campaign where IPQS is enabled.

  2. Open the Integration Manager.

  3. Locate the IPQS integration.

  4. Click Edit.

  5. Select Test.

  6. Enter the appropriate phone number and request values in the JSON test prompt.

  7. Submit the request.

  8. Review the returned response and criteria evaluation.

This allows you to verify the connection, response mapping, and rejection rules before processing live leads.

Issue: IPQS Is Not Returning Validation Results

Possible Causes

  • The API key is missing or incorrect.

  • The IPQS account has reached its credit or daily usage limit.

  • The phone number is invalid or incorrectly formatted.

  • The IPQS service returned an error.

  • The integration is not enabled on the campaign.

Recommended Actions

  • Verify the API key in the global integration settings.

  • Confirm the IPQS account has available credits.

  • Check the phone number format and country code.

  • Confirm the integration is enabled on the campaign.

  • Run a test and review the API response.

Issue: Valid Phone Numbers Are Being Rejected

Possible Causes

  • Fraud Score criteria are configured with the wrong comparison operator.

  • Country values use full country names instead of two-letter codes.

  • Line Type criteria use unsupported values.

  • The campaign is configured to reject phone types that should be accepted.

Recommended Actions

Review each rejection rule and compare its value against the actual IPQS response.

For example:

Incorrect: Fraud Score Less Than or Equal To 50 → Reject

Correct for high-risk filtering: Fraud Score Greater Than or Equal To 85 → Reject

Similarly, use US instead of United States for the Country response.

Issue: IPQS Returns Success = False

When IPQS cannot successfully process a validation request, it may return Success = False.

Possible causes include:

  • Insufficient API credits.

  • Reaching an account usage limit.

  • Invalid phone number information.

  • Missing country information.

  • Other API errors.

In some unsuccessful integration executions, LeadExec may display response values such as:

Field

Displayed Value

Success

False

Valid

False

Fraud Score

0

Active

False

Country

N/A

Line Type

Unknown

These values should not automatically be interpreted as a successful determination that the phone number is fraudulent or inactive.

Important: Depending on the displayed response values and configured criteria, an unsuccessful validation can still trigger rejection rules.

For example:

  • Active Equals False → Reject

  • Country Does Not Equal US → Reject

  • Line Type Does Not Equal Wireless → Reject

If the unsuccessful integration response contains False, N/A, or Unknown for those fields, the rejection criteria may match.

When troubleshooting this behavior, check the original IPQS error response and the lead's Integrations tab to determine why validation failed.

Issue: Leads Are Being Rejected After IPQS Credits Are Exhausted

If your IPQS account reaches its available credit limit, additional validation requests may fail.

When this happens, review the lead's integration results to determine whether an unsuccessful request is causing configured rejection criteria to match.

Recommended Actions

  1. Confirm the available IPQS credit balance.

  2. Review the affected lead's Integrations tab.

  3. Check whether the IPQS request completed successfully.

  4. Identify any rejection criteria triggered by unavailable or defaulted response values.

  5. Restore the available IPQS credits or contact IPQS regarding the account limit.

If unsuccessful validations are causing unexpected lead rejections, consider temporarily disabling the integration on affected campaigns until the issue is resolved.

Note: Disabling IPQS allows leads to proceed without those IPQS validation rules, subject to the remaining LeadExec processing requirements. Evaluate the impact on lead quality before doing so.

Issue: IPQS Usage Is Higher Than Expected

IPQS validation requests may occur on leads that are not ultimately accepted or delivered.

For example, a lead can:

  1. Pass initial validation.

  2. Trigger IPQS.

  3. Pass IPQS criteria.

  4. Fail a subsequent coverage check.

  5. Receive a final No Coverage response.

In this scenario, the IPQS lookup has already occurred, even though the lead was not ultimately delivered.

Additionally, multiple validation requests for the same phone number or testing activity can contribute to overall API usage.

Recommended Actions

  • Compare IPQS usage against POST submissions for the same reporting period.

  • Review integration execution records.

  • Check whether testing or repeated submissions contributed to usage.

  • Confirm whether other applications are using the same IPQS account.

  • Contact IPQS for clarification regarding account-specific credit usage and dashboard statistics.

Remember that total API hits and successful LeadExec deliveries are different measurements.

Best Practices

When configuring the IPQS integration in LeadExec, consider the following best practices to ensure accurate validation and optimal lead quality.

  • Start with a balanced fraud score threshold
    A rule such as Fraud Score < 50 is a good starting point. This helps filter high-risk numbers while still allowing legitimate leads to pass.

  • Ensure response fields exist in your Lead Type
    Fields such as Fraud Score, VoIP, Carrier, and Line Type should exist in your Lead Type configuration so the data returned by IPQS can be stored and used for filtering or reporting.

  • Test the integration before enabling it on live campaigns
    Use the Test feature within the Integration Manager to verify that request values, response fields, and criteria rules are working correctly before processing real leads.

​

Related articles

Did this answer your question?