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

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
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
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.	✔

email

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!