Phone Intelligence API
Overview and Purpose
The API offers an advanced solution for assessing the risk profile of phone numbers. By submitting a phone number, businesses can receive a comprehensive analysis of each identifier's risk level. This service evaluates the provided information and generates a risk score, indicating the potential risk associated with the current transaction.
This API is designed to empower organizations with vital insights into transactional risks. It not only provides a numeric risk score but also delivers a set of detailed insights and reason codes. These elements offer granular and contextual intelligence, shedding light on the digital behavior that influences the risk score. The primary goal of the Phone Number Intelligence API is to enable businesses to make more informed decisions regarding transaction security. By understanding the risk profiles of phone numbers, IP addresses, and email addresses, companies can effectively prevent fraudulent activities, verify user identities, and enhance the overall trustworthiness and security of their transactions.
Use Cases
The Phone Number Intelligence API serves a wide range of applications, each focused on enhancing security, managing risk, and fostering trust in different scenarios. Its versatility is evident in various sectors and operations:
- Fraud Prevention: It plays a crucial role in detecting and preventing fraudulent activities like account takeovers, identity theft, or fake account creation by analyzing the risk associated with phone numbers during registration or transactions.
- Identity Verification: The API assists in verifying the authenticity of a user's phone number, aligning it with the provided identity to diminish identity fraud risks.
- Transaction Risk Assessment: In financial contexts, it evaluates the risk level of phone numbers involved in transactions, such as money transfers, helping to pinpoint potentially dubious activities.
- User Onboarding: During new user registration processes, the API assesses the risk of the provided phone number, aiding in decision-making for account creation approval or further scrutiny.
API Details
Endpoints
curl --location 'https://api-preproduction.signzy.app/api/v3/global/tele-intelligence' \
--header 'Authorization:<Auth-Token>' \
--header 'Content-Type: application/json' \
--data '{ "phoneNumber": "",
"originatingIp": "",
"emailAddress":"",
"deviceId":""
}'Request Body Parameters
Parameter | Data Type | Description | Required |
|---|---|---|---|
phoneNumber | String | The phone number to be analyzed. For best accuracy and coverage, provide the number with country code | Mandatory |
originatingIp | String | IP address from which the request originated. Used for additional risk and contextual analysis. | Optional |
emailAddress | String | Email address associated with the request, if available. Used only for correlation and enrichment purposes. | Optional |
deviceId | String | Unique identifier of the user’s device initiating the request. Used for device-level risk analysis. | Optional |
{ "phoneNumber": "",
"originatingIp": "",
"emailAddress":"",
"deviceId":""
}Response Body Parameters
{
"result": {
"referenceId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": {
"code": 300,
"description": "Transaction successfully completed",
"updatedOn": "2026-01-01"
},
"location": {
"city": "SampleCity",
"county": "SampleCounty",
"state": "XX",
"zip": "00000",
"country": {
"name": "Sample Country",
"iso2": "SC",
"iso3": "SMP"
},
"timeZone": {
"name": "Region/City",
"utcOffsetMin": "0",
"utcOffsetMax": "0"
},
"coordinates": {
"latitude": 0.0,
"longitude": 0.0
},
"metroCode": "0000"
},
"numbering": {
"original": {
"completePhoneNumber": "10000000000",
"countryCode": "1",
"phoneNumber": "0000000000"
},
"cleansing": {
"call": {
"countryCode": "1",
"phoneNumber": "0000000000",
"cleansedCode": 100,
"minLength": 10,
"maxLength": 10
},
"sms": {
"countryCode": "1",
"phoneNumber": "0000000000",
"cleansedCode": 100,
"minLength": 10,
"maxLength": 10
}
}
},
"phoneType": {
"code": "2",
"description": "MOBILE"
},
"blocklisting": {
"blockCode": 0,
"blockDescription": "Not blocked",
"blocked": false
},
"carrier": {
"name": "Sample Carrier",
"mcc": " ",
"mnc": " "
},
"risk": {
"level": "medium",
"recommendation": "flag",
"score": 500
},
"riskInsights": {
"status": 800,
"category": [
10000
],
"a2p": [
20000
],
"p2p": [],
"numberType": [],
"ip": [],
"email": []
}
},
"reason": "Request Successful",
"code": "S001"
}
Parameter | Description | Data Type |
|---|---|---|
result | Contains the phone intelligence and verification details returned by the API | Object |
result.referenceId | A 32-digit hex value used to uniquely identify the web service request | String |
result.externalId | Customer-generated ID for the transaction; null if not provided in request | String | Null |
result.status | Contains details about the request status | Object |
result.status.code | Transaction status code (300 = successful, 301 = partially successful) | Integer |
result.status.description | Text describing the transaction status | String |
result.status.updatedOn | RFC 3339 timestamp when the transaction status was updated | String |
result.location | Geographical location associated with the phone number’s rate center | Object |
result.location.city | City associated with the rate center of the phone number | String |
result.location.county | County or parish associated with the rate center (US only) | String |
result.location.state | Two-letter state or province code | String |
result.location.zip | Five-digit USPS ZIP code (US only) | String |
result.location.country | Country associated with the rate center | Object |
result.location.country.name | Country name | String |
result.location.country.iso2 | ISO-2 country code | String |
result.location.country.iso3 | ISO-3 country code | String |
result.location.timeZone | Time zone associated with the rate center | Object |
result.location.timeZone.name | IANA time zone name | String |
result.location.timeZone.utcOffsetMin | Minimum UTC offset in hours | String |
result.location.timeZone.utcOffsetMax | Maximum UTC offset in hours | String |
result.location.coordinates | Geographical coordinates of the phone number location | Object |
result.location.coordinates.latitude | Latitude of the registered location | Number |
result.location.coordinates.longitude | Longitude of the registered location | Number |
result.location.metroCode | Primary Metropolitan Statistical Area (PMSA) code (US only) | String |
result.numbering | Numbering attributes of the phone number | Object |
result.numbering.original | Original phone number details from the request | Object |
result.numbering.original.completePhoneNumber | Full phone number including country code | String |
result.numbering.original.countryCode | Country dialing code | String |
result.numbering.original.phoneNumber | National significant number | String |
result.numbering.cleansing | Phone number cleansing details | Object |
result.numbering.cleansing.call | Cleansed phone number for voice calls | Object |
result.numbering.cleansing.sms | Cleansed phone number for SMS | Object |
result.phoneType | Type of phone service based on dial plan data | Object |
result.phoneType.code | Phone type code (e.g., 2 = Mobile) | String |
result.phoneType.description | Human-readable description of phone type | String |
result.blocklisting | Block status details for the phone number | Object |
result.blocklisting.blockCode | Indicates whether the number is blocked and by whom | Integer |
result.blocklisting.blockDescription | Text explaining the block status | String |
result.blocklisting.blocked | Indicates whether the number is blocked | Boolean |
result.carrier | Telecom carrier details for the phone number | Object |
result.carrier.name | Name of the telecom service provider | String |
result.carrier.mcc | Mobile Country Code (if available) | String |
result.carrier.mnc | Mobile Network Code (if available) | String |
result.risk | Risk recommendation for the phone number | Object |
result.risk.level | Severity level of the risk | String |
result.risk.recommendation | Recommended action (allow / flag / block) | String |
result.risk.score | Risk score ranging from 0 to 1000 | Integer |
result.riskInsights | Additional intelligence and reason codes related to risk | Object |
result.riskInsights.status | Processing status of the risk insights package (800, 801, 803) | Integer |
result.riskInsights.category | Reason codes related to phone number category | Array<Integer> |
result.riskInsights.a2p | Reason codes related to application-to-person traffic | Array<Integer> |
result.riskInsights.p2p | Reason codes related to person-to-person traffic | Array<Integer> |
result.riskInsights.numberType | Reason codes related to phone number type | Array<Integer> |
result.riskInsights.ip | Reason codes related to IP activity | Array<Integer> |
result.riskInsights.email | Reason codes related to email activity | Array<Integer> |
reason | Overall message describing the request outcome | String |
code | API response code indicating request result | String |
Refrences for Codes in Respone Body
category
Reason codes that provide an overall conclusion on the relative risk presented by the transaction, by placing the transaction in a risk category. This is determined based on weighting the risk and trust signals indicated by the other reason codes.
Code | Name | Meaning |
|---|---|---|
10010 | low activity | Not enough activity or attributes to classify the transaction as either risky or trustworthy. |
10020 | low regular activity | Trustworthy category, based on past behavior. |
10021 | regular activity | Most trustworthy category, based on past behavior. |
10030 | low-risk irregular activity | Risky category, based on past behavior. |
10031 | medium-risk irregular activity | High-risk category, based on past behavior. |
10032 | high-risk irregular activity | Highest-risk category, based on past behavior. |
10040 | irregular number type | This number has risky static attributes (like VOIP phone type or being on a blocklist). |
a2p
Reason codes specific to application-to-person messaging (a2p). These are automated messages sent to a human, like verification codes, appointment reminders, etc. These reason codes are organized into multiple sub-categories.
activity
Reason codes related to how much activity was observed for this number, compared to what would be expected for a good user. This takes into account the number of communications transactions (calls, SMS, etc.) to or from this number, the quantity of unique numbers communicated with, and the number of accounts communicated with.
Code | Name | Meaning | Risk signal | Trust signal |
|---|---|---|---|---|
20001 | no long-term activity | Much less than expected activity, or none at all, for this number over the past 90 days. Cannot classify. | | |
20002 | high long-term activity | More than expected activity for this number over the past 90 days. | ✔ | |
20003 | high short-term activity | More than expected activity for this number over the last 24 hours. | ✔ | |
20004 | moderate long-term activity | Expected activity for this number over the past 90 days. | | ✔ |
20005 | moderate short-term activity | Expected activity for this number over the last 24 hours. | | ✔ |
20006 | sparse long-term activity | Sparse, regular volume of verification traffic on this number over the past 90 days. | | ✔ |
20007 | continuous long-term activity | Continuous, regular volume of verification traffic on this number over the past 90 days. | | ✔ |
20008 | very high long-term activity | Very high volume of verification traffic on this number over the past 90 days. | ✔ | |
20009 | very high short-term activity | Very high volume of verification traffic on this number over the past 24 hours. | ✔ | |
20010 | no activity | Very low volume of verification traffic, or none at all, was ever observed on this number. | | |
20011 | low long-term activity | Low volume of verification traffic on this phone number over the past 90 days. | | |
20012 | low short-term activity | Low volume of verification traffic on this phone number over the past 24 hours. Very low volume of verification traffic, or none at all over the past 90 days. | | |
20013 | low activity | Less than expected activity for this number. | | |
20014 | continuous successful long-term activity | Continuous successful regular volume of verification traffic on this number over the past 90 days. | | ✔ |
20015 | high unsuccessful long-term activity | Significant volume of unsuccessfully verified traffic from this number over the past 90 days | ✔ | |
range
Reason codes related to how active a risky range (series of consecutive numbers) that the number belongs to has been, if applicable, compared to a good phone number.
Code | Name | Meaning | Risk signal | Trust signal |
|---|---|---|---|---|
20101 | no range activity | Very little activity, or none at all, for a risky range that this number belongs to over the past 90 days. Also returned if the number does not belong to a risky range. | | ✔ |
20102 | low range activity | Some activity for a risky range that this number belongs to over the past 90 days. | ✔ | |
20103 | moderate short-term range activity | Significant activity for a risky range that this number belongs to over the last 24 hours. | ✔ | |
20104 | moderate long-term range activity | Significant activity for a risky range that this number belongs to over the past 90 days. | ✔ | |
20105 | high short-term range activity | Very significant activity for a risky range that this number belongs to over the last 24 hours. | ✔ | |
20106 | high long-term range activity | Very significant activity for a risky range that this number belongs to over the past 90 days. | ✔ | |
20107 | very high long-term range activity | Extremely significant activity for a risky range that this number belongs to over the past 90 days. | ✔ | |
20108 | very high short-term range activity | Extremely significant activity for a risky range that this number belongs to over the last 24 hours. | ✔ | |
20109 | continuous successful long-term range activity | Continuous successful regular volume of verification traffic from a range this number belongs to over the past 90 days | | ✔ |
20110 | high unsuccessful long-term range activity | Significant volume of unsuccessfully verified traffic from a range this number belongs to over the past 90 days | ✔ | |
risky services
Reason codes related to how much the number has communicated with risky services.
Code | Name | Meaning | Risk signal | Trust signal |
|---|---|---|---|---|
21001 | moderate activity on risky services | Significant activity on this number to or from risky services over the past 90 days. | ✔ | |
21002 | high activity on risky services | Very significant activity on this number to or from risky services over the past 90 days. | ✔ | |
21004 | long-term activity on risky services | Verification traffic on risky services on this number over the past 90 days. | ✔ | |
21005 | short-term activity on risky services | Verification traffic on risky services on this number over the past 24 hours. | ✔ | |
21006 | high long-term activity on risky services | High volume of verification traffic on risky services on this number over the past 90 days. | ✔ | |
21007 | high short-term activity on risky services | High volume of verification traffic on risky services on this number over the past 24 hours. | ✔ | |
21008 | long-term range activity on risky services | Verification traffic on risky services on the range this number belongs to over the past 90 days. | ✔ | |
21009 | short-term range activity on risky services | Verification traffic on risky services on the range this number belongs to over the past 24 hours. | ✔ | |
21010 | high long-term range activity on risky services | High volume of verification traffic on risky services on the range this number belongs to over the past 90 days. | ✔ | |
21011 | high short-term range activity on risky services | High volume of verification traffic on risky services on the range this number belongs to over the past 24 hours. | ✔ | |
21012 | very high short-term activity on risky services | Very high volume of verification traffic on risky services on this number over the past 90 days. | ✔ | |
21013 | very high long-term activity on risky services | Very high volume of verification traffic on risky services on this number over the past 24 hours. | ✔ | |
21014 | very high short-term range activity on risky services | Very high volume of verification traffic on risky services on the range this number belongs to over the past 90 days. | ✔ | |
21015 | very high long-term range activity on risky services | Very high volume of verification traffic on risky services on the range this number belongs to over the past 24 hours. | ✔ | |
other
Other A2P reason codes that do not fall into the sub-categories above.
Code | Name | Meaning | Risk signal | Trust signal |
|---|---|---|---|---|
21003 | machine-like activity | Behavior pattern that suggests this number is being used by a bot. Although we expect a submitted number engaged in A2P traffic to communicate with automated systems, we don’t expect the user of that number to be an automated system. | ✔ | |
21016 | machine-like range activity | Extremely high volume of verification traffic in a very short period (less than 1 hour) on the range this number belongs to. | ✔ | |
recency
Reason codes related to how recently the number was active.
Code | Name | Meaning | Risk signal | Trust signal |
|---|---|---|---|---|
22001 | seen in the last 1 day | This number was seen in verification traffic in the last 1 day. | | |
22007 | seen in the last 7 days | This number was seen in verification traffic in the last 7 days. | | |
22015 | seen in the last 15 days | This number was seen in verification traffic in the last 15 days. | | |
22101 | seen in the last 1 month | This number was seen in verification traffic in the last 1 month. | | |
22102 | seen in the last 2 months | This number was seen in verification traffic in the last 2 months. | | |
22103 | seen in the last 3 months | This number was seen in verification traffic in the last 3 months. | | |
22203 | seen more than 3 months ago | This number was not seen in verification traffic in the last 3 months. | | |
p2p
Reason codes specific to person-to-person messaging (p2p). Two-way messaging between two humans, like one friend texting another.
Code | Name | Meaning |
|---|---|---|
30201 | No P2P data analyzed. | P2P data was not analyzed. Cannot classify. |
number_type
Reason codes related to the number’s type. These are static attributes rather than measurements of behavior.
Code | Name | Meaning | Risk signal | Trust signal |
|---|---|---|---|---|
40001 | premium number | This is a premium number. | ✔ | |
40002 | VOIP number | This is a VOIP number. | ✔ | |
40003 | toll-free number | This is a toll-free number. | ✔ | |
40004 | invalid number | This is an invalid number. | ✔ | |
40005 | payphone number | This number is associated with a payphone. | ✔ | |
40006 | voicemail number | This is a voicemail number. | ✔ | |
40007 | pager number | This number is associated with a pager. | ✔ | |
40008 | high-risk phone type | This number has another phone type that is risky, and that is not covered by any of the other number_type reason codes. | ✔ | |
40009 | high-risk carrier | This number is associated with a very risky carrier. | ✔ | |
40010 | medium-risk carrier | This number is associated with a risky carrier. | ✔ | |
40011 | high-risk prefix | This number has a risky prefix. | ✔ | |
40012 | phone too long | This number is invalid because it is too long, even after the application of cleansing rules. | ✔ | |
40013 | blacklisted number | This number has been flagged as a source of fraud. | ✔ | |
40014 | high-risk country | The country code of this number is for a risky country, one that originates a disproportionate share of fraud attacks. | ✔ | |
40015 | technical number | This number is used for special technical purposes by telecom companies, such as for roaming. | | |
40016 | number used by application | reserved this number for use by customers with our applications (for example to send verification messages), but it appears that it is being used for a different purpose. | ✔ | |
40017 | number whitelisted by customer | The number has flagged as safe. | | ✔ |
40018 | phone too short | This number is too short to be a valid phone number. | ✔ | |
40019 | prepaid number | This is a prepaid number. | ✔ | ✔ |
40020 | fixed line number | This is a fixed line number. | ✔ | ✔ |
40021 | personal number | Phone type is personal. | ✔ | ✔ |
ip
Reason codes related to activity of the IP address you provided for this number (and its associated geolocation IDs), as compared to a good user.
Code | Name | Meaning | Risk signal | Trust signal |
|---|---|---|---|---|
50001 | moderate short-term activity | Expected level of activity for this IP address over the last 24 hours. | | ✔ |
50002 | moderate long-term activity | Expected level of activity for this IP address over the past 90 days. | | ✔ |
50003 | moderate short-term activity on risky services | Significant activity for this IP address to or from risky services over the last 24 hours. | ✔ | |
50004 | moderate long-term activity on risky services | Significant activity on this IP address to or from risky services over the last 90 days. | ✔ | |
50005 | high short-term activity | More than expected activity for this IP address over the last 24 hours. | ✔ | |
50006 | high long-term activity | More than expected activity for this IP address over the past 90 days. | ✔ | |
50007 | high short-term activity on risky services | Very significant activity for this IP address to or from risky services over the last 24 hours. | ✔ | |
50008 | high long-term activity on risky services | Very significant activity on this IP address to or from risky services over the last 90 days. | ✔ | |
50009 | very high short-term activity | Very frequent changes of IP address attributes in verification traffic on this number over the past 24 hours. | ✔ | |
50010 | very high long-term activity | Very frequent changes of IP address attributes in verification traffic on this number over the past 90 days. | ✔ | |
50011 | short-term activity on risky services | Changes of IP address attributes in verification traffic on risky services on this number over the past 24 hours. | ✔ | |
50012 | long-term activity on risky services | Changes of IP address attributes in verification traffic on risky services on this number over the past 90 days. | ✔ | |
50013 | very high short-term activity on risky services | Very frequent changes of IP address attributes in verification traffic on risky services on this number over the past 24 hours. | ✔ | |
50014 | very high long-term activity on risky services | Very frequent changes of IP address attributes in verification traffic on risky services on this number over the past 90 days. | ✔ | |
50015 | anonymous proxy | This IP address is associated with anonymous proxies, which can help conceal the true origins of online traffic. | ✔ | |
50016 | VPN | This IP address is associated with virtual private networks (VPNs), which can help conceal the true origins of online traffic. | ✔ | |
50017 | hosting provider | This IP address is associated with web hosting servers, which have a pattern of activity different than genuine end users. | ✔ | |
50018 | TOR exit node | This IP address is associated with Tor anonymous browsers, which can help conceal the true origins of online traffic. | ✔ | |
50019 | whitelisted ip | The IP has been flagged as safe. | | ✔ |
50020 | blacklisted ip | The IP has been flagged as a source of fraud. | ✔ | |
Reason codes related to activity of the email address you provided for this phone number.
Code | Name | Meaning | Risk signal | Trust signal |
|---|---|---|---|---|
60001 | moderate short-term activity | Expected level of activity for this email address over the last 24-hours. | | ✔ |
60002 | moderate long-term activity | Expected level of activity for this email address over the past 90 days. | | ✔ |
60003 | moderate short-term activity on risky services | Significant activity for this email address to or from risky services over the last 24 hours. | ✔ | |
60004 | moderate long-term activity on risky services | Significant activity on this email address to or from risky services over the last 90 days. | ✔ | |
60005 | high short-term activity | More than expected activity for this email address over the last 24-hours. | ✔ | |
60006 | high long-term activity | More than expected activity for this email address over the past 90 days. | ✔ | |
60007 | high short-term activity on risky services | Very significant activity for this email address to or from risky services over the last 24 hours. | ✔ | |
60008 | high long-term activity on risky services | Very significant activity on this email address to or from risky services over the last 90 days. | ✔ | |
60009 | very high short-term activity | Very high volume of verification traffic on this email address over the past 24 hours. | ✔ | |
60010 | very high long-term activity | Very high volume of verification traffic on this email address over the past 90 days. | ✔ | |
60011 | machine-generated email | Behavior pattern that suggests this email address is being used by a software program. | ✔ | |
60012 | invalid email | This email address is invalid and could not have been used by a genuine end user. | ✔ | |
60013 | disposable email domain | This email address may have originated from a service providing temporary email addresses; these temporary addresses can be used to conceal the identity of the end user. | ✔ | |
60014 | whitelisted email | The email has been flagged as safe. | | ✔ |
60015 | blacklisted email | The email has been flagged as a source of fraud. | ✔ | |
Error Code and Response Mapping
{
"result": {},
"reason": "Bad Request: phoneNumber is required",
"code": "E001"
}
__________________________________________________________________
{
"result": {},
"reason": "Bad Request: originatingIp must be a valid IP address",
"code": "E001"
}
____________________________________________________________________
{
"result": {},
"reason": "Bad Request: emailAddress must be a valid email address",
"code": "E001"
}
Contact Us for Any Assistance
If you have any questions or need assistance, please reach out to our customer support team. You can contact us via email at [email protected]. We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.
We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!