Phone Status Check - Detailed Documentation

Use this action to get insights about a phone number such as whether it is active or disconnected, whether its associated device is reachable or unreachable, and its associated device’s roaming status.

API Playground:

You can try the phoneStatus endpoint here.

Endpoints Overview

Phone Status Check: Retrieve the status and details of a phone number.
Phone ID: Retrieve the ID and details of a phone number.
Phone Risk Score: Retrieve the risk score of a phone number.
Verification: Verify a phone number.
- Verification: Send a verification code to a phone number.
- Verification Match: Match the verification code.
Full Phone Intelligence: Retrieve the full intelligence of a phone number.

Authentication

To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.

Tokens are valid for 60 minutes and must be refreshed after expiration.
Refer to the Authentication for detailed steps on obtaining a token.
Include the token in the Authorization header as follows:

Authorization: Bearer YOUR_ACCESS_TOKEN

API Base URL

https://api-umbrella.io/api/services

1. Phone Status Check

Endpoint

POST /phone-service/phoneStatus

Description

Use this action to get insights about a phone number, such as its activity status, device reachability, and roaming status.

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Response Structure

Field	Type	Description
`referenceId`	string	Unique reference ID for the transaction.
`subResource`	string	Sub-resource type (e.g., `live`).
`status`	object	Transaction status details.
`status.code`	number	Status code (e.g., `300` for success).
`status.description`	string	Status description (e.g., “Transaction successfully completed”).
`status.updatedOn`	string	Timestamp of the last update (ISO 8601 format).
`errors`	array	List of errors, if any.
`phoneType`	object	Type of phone number.
`phoneType.code`	string	Phone type code (e.g., `2` for mobile).
`phoneType.description`	string	Phone type description (e.g., “MOBILE”).
`blocklisting`	object	Blocklisting status of the phone number.
`blocklisting.blocked`	boolean	Whether the number is blocked.
`blocklisting.blockCode`	number	Block code (e.g., `0` for not blocked).
`blocklisting.blockDescription`	string	Block description (e.g., “Not blocked”).
`numbering`	object	Phone number details.
`numbering.cleansing`	object	Cleansed phone number details.
`numbering.cleansing.call`	object	Call-specific cleansing details.
`numbering.cleansing.call.countryCode`	string	Country code.
`numbering.cleansing.call.phoneNumber`	string	Phone number.
`numbering.cleansing.call.cleansedCode`	number	Cleansing status code.
`numbering.cleansing.call.minLength`	number	Minimum allowed length.
`numbering.cleansing.call.maxLength`	number	Maximum allowed length.
`numbering.cleansing.sms`	object	SMS-specific cleansing details.
`numbering.cleansing.sms.countryCode`	string	Country code.
`numbering.cleansing.sms.phoneNumber`	string	Phone number.
`numbering.cleansing.sms.cleansedCode`	number	Cleansing status code.
`numbering.cleansing.sms.minLength`	number	Minimum allowed length.
`numbering.cleansing.sms.maxLength`	number	Maximum allowed length.
`numbering.original`	object	Original phone number details.
`numbering.original.completePhoneNumber`	string	Complete phone number with country code.
`numbering.original.countryCode`	string	Country code.
`numbering.original.phoneNumber`	string	Phone number.
`location`	object	Location details of the phone number.
`location.city`	string	City associated with the phone number.
`location.state`	string	State associated with the phone number.
`location.zip`	string	ZIP code associated with the phone number.
`location.metroCode`	string	Metro code associated with the phone number.
`location.county`	string	County associated with the phone number.
`location.country`	object	Country details.
`location.country.name`	string	Country name.
`location.country.iso2`	string	ISO 2-letter country code.
`location.country.iso3`	string	ISO 3-letter country code.
`location.coordinates`	object	Geographic coordinates.
`location.coordinates.latitude`	string	Latitude.
`location.coordinates.longitude`	string	Longitude.
`location.timeZone`	object	Time zone details.
`location.timeZone.name`	string	Time zone name.
`location.timeZone.utcOffsetMax`	string	Maximum UTC offset.
`location.timeZone.utcOffsetMin`	string	Minimum UTC offset.
`carrier`	object	Carrier details.
`carrier.name`	string	Name of the carrier.
`live`	object	Live status details.
`live.subscriberStatus`	string	Subscriber status (e.g., `ACTIVE`).
`live.deviceStatus`	string	Device status (e.g., `REACHABLE`).
`live.roaming`	string	Roaming status (e.g., `UNAVAILABLE`).
`live.roamingCountry`	string	Roaming country name.
`live.roamingCountryIso2`	string	ISO 2-letter roaming country code.

Example Request

{
    "phoneNumber": "+486504142304"
}

Example Response

{
  "reference_id": "ABC123XYZ789",
  "sub_resource": "live",
  "status": {
    "code": 300,
    "description": "Transaction successfully completed",
    "updated_on": "2025-08-01T14:32:10Z"
  },
  "errors": [],
  "phone_type": {
    "code": "2",
    "description": "MOBILE"
  },
  "blocklisting": {
    "blocked": false,
    "block_code": 0,
    "block_description": "Not blocked"
  },
  "numbering": {
    "cleansing": {
      "call": {
        "country_code": "49",
        "phone_number": "15123456789",
        "cleansed_code": 100,
        "min_length": 7,
        "max_length": 13
      },
      "sms": {
        "country_code": "49",
        "phone_number": "15123456789",
        "cleansed_code": 100,
        "min_length": 7,
        "max_length": 13
      }
    },
    "original": {
      "complete_phone_number": "+4915123456789",
      "country_code": "49",
      "phone_number": "15123456789"
    }
  },
  "location": {
    "city": "Berlin",
    "state": "Berlin",
    "zip": "10115",
    "metro_code": null,
    "county": "Berlin County",
    "country": {
      "name": "Germany",
      "iso2": "DE",
      "iso3": "DEU"
    },
    "coordinates": {
      "latitude": 52.5200,
      "longitude": 13.4050
    },
    "time_zone": {
      "name": "Europe/Berlin",
      "utc_offset_max": "+2",
      "utc_offset_min": "+1"
    }
  },
  "carrier": {
    "name": "Generic Mobile GmbH"
  },
  "live": {
    "subscriber_status": "ACTIVE",
    "device_status": "REACHABLE",
    "roaming": "UNAVAILABLE",
    "roaming_country": null,
    "roaming_country_iso2": null
  }
}

2. Phone ID (Upcoming)

Endpoint

POST /phone-service/phoneid

Description

The Phone ID service provides identity checks and enriched data linked to a phone number. It includes several optional modules:

Age Verification – Verifies whether the subscriber meets a specified age threshold. Only available in the US and UK and requires address input via Contact Match.
Breached Data – Checks whether the phone number has appeared in known data breaches.
Call Forwarding Detection – Detects whether call forwarding is active and under what conditions.
Contact Information – Returns known contact details such as name, address, and email.
Contact Match – Compares submitted contact data against the carrier’s data and returns a match score.
Number Deactivation – Provides information on if and when the number was deactivated.
Subscriber Status – Indicates the subscriber’s account state, including type, tenure, and contract status.
Porting History – Displays the number’s history of being ported between carriers.
Porting Status – Returns the current carrier and whether the number has been recently ported.
SIM Swap – Detects SIM card swaps and evaluates the associated risk.

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Field	Type	Required	Description
`phoneNumber`	string	Yes	Phone number to query, including country code (no spaces or symbols).
`accountLifecycleEvent`	string	No	Stage of the user journey. One of: `create`, `sign-in`, `transact`, `update`, `delete`.
`externalId`	string	No	Customer-defined ID echoed in the response.
`originatingIp`	string	No	End user’s IP address (IPv4 or IPv6).
`addons`	object	No	Add-on services to enrich the phone lookup (see table below).
`consent`	object	No*	Consent record for querying the number — required for certain add-ons.

Add-ons Object Fields

Add-on	Key	Type	Description	Example Value
Age Verification	`ageVerify`	object	Verifies subscriber’s age (US/UK only). Requires address information.	`{"ageThreshold": "21"}`
Breached Data	`breachedData`	object	Checks whether the phone number has appeared in a data breach.	`{}`
Call Forwarding	`callForwardDetection`	object	Detects if call forwarding is enabled and under what conditions.	`{}`
Contact Info	`contact`	object	Returns known contact details such as name, address, and email.	`{"email": "test@example.com"}`
Contact Match	`contactMatch`	object	Compares provided contact info with carrier records and returns a match.	`{ "firstName": "Jane", "lastName": "Doe", "address": "123 Main St", "city": "Springfield", "postalCode": "12345", "state": "IL", "country": "USA", "inputUsed": "phoneNumber and email" }`
Number Deactivation	`numberDeactivation`	object	Indicates if/when the number was deactivated.	`{"status": { "code": 2800, "description": "Request successfully completed" }, "carrierName": "Verizon", "lastDeactivated": "2016-04-05T00:00:00Z", "trackingSince": "2014-10-06T00:00:00Z", "recycledSinceLastVerification": "notRecycled" }`
Subscriber Status	`subscriberStatus`	object	Provides subscriber account details like type, tenure, and activation.	`{}`
Porting History	`portingHistory`	object	Shows porting history of the number across carriers.	`{"pastXDays": "10"}`
Porting Status	`portingStatus`	object	Displays current carrier and whether the number was recently ported.	`{}`
SIM Swap	`simSwap`	object	Detects recent SIM changes and evaluates risk.	`{}`

Consent Object Fields

Field	Type	Description
`method`	integer	Numeric code for how consent was collected. Defaults to `4` if not set. Accepted values: `1` = Terms and Conditions (TCO) `2` = Mobile App (MA) `3` = SMS `4` = Other
`timestamp`	string	ISO 8601 timestamp of when consent was collected. If not set, the current timestamp is used.

Response Structure

Field	Type	Description	Source
`status`	boolean	Indicates if the API request itself was successful.	basic
`data.referenceId`	string	Unique 32-character hex ID for the transaction (provider-generated).	basic
`data.externalId`	string \| null	Custom ID echoed back if provided in the request.	basic
`data.status.code`	integer	Processing status code (e.g., 300 for success).	basic
`data.status.description`	string	Human-readable description of the transaction status.	basic
`data.status.updatedOn`	string	ISO 8601/RFC 3339 timestamp of last update.	basic
`data.phoneType.code`	string	Phone type code.	phoneType
`data.phoneType.description`	string	Description of the phone type.	phoneType
`data.blocklisting.blocked`	boolean	Whether the number is blocklisted.	blocklisting
`data.blocklisting.blockCode`	integer	Block status code.	blocklisting
`data.blocklisting.blockDescription`	string	Description of the block reason.	blocklisting
`data.carrier.name`	string	Carrier name.	carrier
`data.numbering.original`	object	Original number as received (completePhoneNumber/countryCode/phoneNumber).	numbering
`data.numbering.cleansing`	object	Cleansed number details for `call` and `sms` (countryCode/phoneNumber/minLength/maxLength/cleansedCode).	numbering
`data.location.city`	string \| null	City (may be null).	location
`data.location.state`	string \| null	State/region (may be null).	location
`data.location.zip`	string \| null	Postal/ZIP code (may be null).	location
`data.location.county`	string \| null	County (may be null).	location
`data.location.metroCode`	string \| null	Metro/PMSA code (U.S.; may be null).	location
`data.location.country.name`	string \| null	Country name.	location
`data.location.country.iso2`	string \| null	ISO-3166-1 alpha-2 code.	location
`data.location.country.iso3`	string \| null	ISO-3166-1 alpha-3 code.	location
`data.location.coordinates.latitude`	number \| null	Latitude (may be null).	location
`data.location.coordinates.longitude`	number \| null	Longitude (may be null).	location
`data.location.timeZone.name`	string \| null	IANA time zone name (may be null).	location
`data.location.timeZone.utcOffsetMax`	string \| null	Max UTC offset (e.g., “+1”).	location
`data.location.timeZone.utcOffsetMin`	string \| null	Min UTC offset (e.g., “+1”).	location

Example Request

{
  "phoneNumber": "11234567890",
  "accountLifecycleEvent": "create",
  "externalId": "CustomExternalID7349",
  "originatingIp": "203.0.113.45",
  "addons": {
    "ageVerify": {
      "ageThreshold": 21
    },
    "contact": {
      "email": "test@example.com"
    },
    "contactMatch": {
      "firstName": "string",
      "lastName": "string",
      "address": "string",
      "city": "string",
      "postalCode": "string",
      "state": "string",
      "country": "string",
      "inputUsed": "email"
    },
    "contactPlus": {
      "billingPostalCode": "95110"
    },
    "numberDeactivation": {
      "carrierName": "Verizon",
      "lastDeactivated": "2016-04-05T00:00:00Z",
      "trackingSince": "2014-10-06T00:00:00Z",
      "status": {
        "code": 2800,
        "description": "Request successfully completed"
      },
      "recycledSinceLastVerification": "notRecycled"
    },
    "portingHistory": {
      "pastXDays": 10
    }
  },
  "consent": {
    "method": 1,
    "timestamp": "2018-05-05T00:00:00Z"
  }
}

Example Response

{
  "status": true,
  "data": {
    "referenceId": "0123456789ABCDEF0123456789ABCDEF",
    "externalId": null,
    "status": {
      "code": 300,
      "description": "Transaction successfully completed",
      "updatedOn": "2025-01-01T00:00:00Z"
    },
    "location": {
      "city": "Countrywide",
      "state": null,
      "zip": null,
      "metroCode": null,
      "county": null,
      "country": {
        "name": "Exampleland",
        "iso2": "EX",
        "iso3": "EXL"
      },
      "coordinates": {
        "latitude": null,
        "longitude": null
      },
      "timeZone": {
        "name": null,
        "utcOffsetMax": "+0",
        "utcOffsetMin": "+0"
      }
    },
    "blocklisting": {
      "blocked": false,
      "blockCode": 0,
      "blockDescription": "Not blocked"
    },
    "numbering": {
      "cleansing": {
        "call": {
          "countryCode": "99",
          "phoneNumber": "5550123456",
          "cleansedCode": 100,
          "minLength": 7,
          "maxLength": 13
        },
        "sms": {
          "countryCode": "99",
          "phoneNumber": "5550123456",
          "cleansedCode": 100,
          "minLength": 7,
          "maxLength": 13
        }
      },
      "original": {
        "completePhoneNumber": "+995550123456",
        "countryCode": "99",
        "phoneNumber": "5550123456"
      }
    },
    "phoneType": {
      "code": "2",
      "description": "MOBILE"
    },
    "carrier": {
      "name": "Example Mobile Ltd"
    }
  }
}

3. Phone Risk Score

Endpoint

POST /phone-service/phoneRiskScore

Description

Phone Risk Score helps detect potentially fraudulent activity by analyzing the transaction risk associated with a phone number. You send a phone number (optionally with an email and/or IP address), and the service evaluates static attributes and behavioral patterns to return a risk.score, a risk.level, and a recommendation — helping you decide whether to allow, flag, or block the transaction. What’s evaluated:

Static attributes: phone type, carrier, device ID, VPN/proxy usage, domains, etc.
Behavioral signals: unusual usage patterns like high velocity or multiple locations/languages.

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Field	Type	Required	Description
`phoneNumber`	string	Yes	The phone number to check, including country code.
`accountLifecycleEvent`	string	Yes	The action being evaluated. Accepted values: `create`, `sign-in`, `transact`, `update`, `delete`.
`externalId`	string	No	A customer-generated ID for this transaction. The response echoes this value.
`originatingIp`	string	No	End user’s IP address (IPv4 or IPv6). Do not send your own IP.
`deviceId`	string	No	Case-sensitive device ID.
`accountId`	string	No	Case-sensitive account ID.
`emailAddress`	string	No	Case-sensitive email address.

Response Structure

Field	Type	Description
`status`	boolean	Indicates if the API request was successful.
`data`	object	Contains the transaction result details.
`data.referenceId`	string	Unique reference ID for the transaction.
`data.externalId`	string	External reference ID (nullable).
`data.status`	object	Transaction status details.
`data.status.updatedOn`	string	Timestamp of the last update (ISO 8601 format).
`data.status.code`	number	Status code (e.g., `300` for success).
`data.status.description`	string	Status description message.
`data.numbering`	object	Original and cleansed phone number details.
`data.numbering.original`	object	Original phone number information.
`data.numbering.original.completePhoneNumber`	string	Complete phone number in international format.
`data.numbering.original.countryCode`	string	Country dialing code.
`data.numbering.original.phoneNumber`	string	Local phone number.
`data.numbering.cleansing`	object	Cleansed phone number details for call and SMS.
`data.numbering.cleansing.call`	object	Cleansed phone number details for calling.
`data.numbering.cleansing.call.countryCode`	string	Country dialing code after cleansing.
`data.numbering.cleansing.call.phoneNumber`	string	Cleansed local phone number for calling.
`data.numbering.cleansing.call.cleansedCode`	number	Result code of cleansing (e.g., `100` = valid).
`data.numbering.cleansing.call.minLength`	number	Minimum valid length of phone number.
`data.numbering.cleansing.call.maxLength`	number	Maximum valid length of phone number.
`data.numbering.cleansing.sms`	object	Cleansed phone number details for SMS.
`data.numbering.cleansing.sms.countryCode`	string	Country dialing code after cleansing.
`data.numbering.cleansing.sms.phoneNumber`	string	Cleansed local phone number for SMS.
`data.numbering.cleansing.sms.cleansedCode`	number	Result code of cleansing (e.g., `100` = valid).
`data.numbering.cleansing.sms.minLength`	number	Minimum valid length of phone number.
`data.numbering.cleansing.sms.maxLength`	number	Maximum valid length of phone number.
`data.riskInsights`	object	Risk assessment details.
`data.riskInsights.status`	number	Risk status code.
`data.riskInsights.category`	array	Risk category codes.
`data.riskInsights.a2P`	array	Application-to-Person (A2P) risk indicators.
`data.riskInsights.p2P`	array	Person-to-Person (P2P) risk indicators.
`data.riskInsights.numberType`	array	Number type risk indicators (if any).
`data.riskInsights.ip`	array	IP-related risk indicators (if any).
`data.riskInsights.email`	array	Email-related risk indicators (if any).
`data.phoneType`	object	Phone type information.
`data.phoneType.code`	string	Phone type code (e.g., `2`).
`data.phoneType.description`	string	Phone type description (e.g., “MOBILE”).
`data.location`	object	Location details associated with the phone number.
`data.location.city`	string	City of the number (if available).
`data.location.state`	string	State or region (nullable).
`data.location.zip`	string	ZIP or postal code (nullable).
`data.location.metroCode`	string	Metro code (nullable).
`data.location.county`	string	County (nullable).
`data.location.country`	object	Country details.
`data.location.country.name`	string	Country name.
`data.location.country.iso2`	string	ISO 2-letter country code.
`data.location.country.iso3`	string	ISO 3-letter country code.
`data.location.coordinates`	object	Geographic coordinates.
`data.location.coordinates.latitude`	number	Latitude (nullable).
`data.location.coordinates.longitude`	number	Longitude (nullable).
`data.location.timeZone`	object	Time zone information.
`data.location.timeZone.name`	string	Time zone name (nullable).
`data.location.timeZone.utcOffsetMin`	string	Minimum UTC offset.
`data.location.timeZone.utcOffsetMax`	string	Maximum UTC offset.
`data.carrier`	object	Carrier (telecom provider) details.
`data.carrier.name`	string	Carrier name.
`data.blocklisting`	object	Blocklisting details.
`data.blocklisting.blocked`	boolean	Indicates if the number is blocklisted.
`data.blocklisting.blockCode`	number	Blocklisting code (e.g., `0` = not blocked).
`data.blocklisting.blockDescription`	string	Blocklisting description.
`data.risk`	object	Overall risk score and recommendation.
`data.risk.level`	string	Risk level (e.g., `medium-low`).
`data.risk.recommendation`	string	Risk handling recommendation (e.g., `allow`).
`data.risk.score`	number	Risk score (numerical value).

Example Request

{
  "phoneNumber": "+436501234567",
  "accountLifecycleEvent": "create",
  "externalId": "1234567890",   
  "originatingIp": "192.168.1.1",
  "deviceId": "1234567890",
  "accountId": "1234567890",
  "emailAddress": "test@example.com" 
}

Example Response

{
    "status": true,
    "data": {
        "referenceId": "3661FDC7EAA8111C93048FA6FB8C300C",
        "externalId": null,
        "status": {
            "updatedOn": "2025-08-06T12:53:53.082687Z",
            "code": 300,
            "description": "Transaction successfully completed"
        },
        "numbering": {
            "original": {
                "completePhoneNumber": "+436501234567",
                "countryCode": "43",
                "phoneNumber": "6501234567"
            },
            "cleansing": {
                "call": {
                    "countryCode": "43",
                    "phoneNumber": "6501234567",
                    "cleansedCode": 100,
                    "minLength": 7,
                    "maxLength": 13
                },
                "sms": {
                    "countryCode": "43",
                    "phoneNumber": "6501234567",
                    "cleansedCode": 100,
                    "minLength": 7,
                    "maxLength": 13
                }
            }
        },
        "riskInsights": {
            "status": 800,
            "category": [
                10010
            ],
            "a2P": [
                22001,
                20011,
                20101
            ],
            "p2P": [
                30201
            ],
            "numberType": [],
            "ip": [],
            "email": []
        },
        "phoneType": {
            "code": "2",
            "description": "MOBILE"
        },
        "location": {
            "city": "Countrywide",
            "state": null,
            "zip": null,
            "metroCode": null,
            "county": null,
            "country": {
                "name": "Austria",
                "iso2": "AT",
                "iso3": "AUT"
            },
            "coordinates": {
                "latitude": null,
                "longitude": null
            },
            "timeZone": {
                "name": null,
                "utcOffsetMin": "+1",
                "utcOffsetMax": "+1"
            }
        },
        "carrier": {
            "name": "T-Mobile Austria GmbH"
        },
        "blocklisting": {
            "blocked": false,
            "blockCode": 0,
            "blockDescription": "Not blocked"
        },
        "risk": {
            "level": "medium-low",
            "recommendation": "allow",
            "score": 301
        }
    }
}

Risk Recommendation Scales

Use the appropriate scale below for interpreting the risk recommendation provided to you, based on which version of Intelligence you used to make your request.

Risk Score Table

`risk.score` Range	Risk Level	Recommendation	Comments
0-80	low	allow	transaction with insufficient risk indicators^*
81-450	very-low	allow	transaction with significant confidence-building behavior on-network^**
451-500	medium-low	flag	suspicious transaction
501-600	medium	flag	suspicious transaction
601-800	high	block	risky transaction
801-1000	very-high	block	risky transaction

^* There isn’t enough data yet to confirm that there is a high likelihood that the transaction belongs to a genuine user. However, the transaction also doesn’t have any indicators that it is a suspicious or risky transaction. ^** The transaction is assigned the “very-low” risk level because it has enough activity to suggest it likely does belong to a genuine user. This activity means there’s more data to use as the basis for the risk.score.

Reason Codes

These reason codes provide an overall risk assessment for a transaction, based on a combination of weighted trust and risk signals.

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 (e.g., VOIP phone type or being on a blocklist).

A2P

Reason codes specific to application-to-person messaging (a2p).

Activity

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 number over the past 24 hours.
20013	low activity	Less than expected activity for this number.

Range

Code	Name	Meaning	Risk Signal	Trust Signal
20101	no range activity	Very little or no activity for a risky range this number belongs to (or not in a risky range).		✅
20102	low range activity	Some activity observed for a risky range this number belongs to over the past 90 days.	✅
20103	moderate short-term range activity	Significant risky range activity in the last 24 hours.	✅
20104	moderate long-term range activity	Significant risky range activity over the past 90 days.	✅
20105	high short-term range activity	Very significant activity for a risky range in the last 24 hours.	✅
20106	high long-term range activity	Very significant activity for a risky range over the past 90 days.	✅
20107	very high long-term range activity	Extremely high activity for a risky range over the past 90 days.	✅
20108	very high short-term range activity	Extremely high activity for a risky range in the last 24 hours.	✅

Risky Services

Code	Name	Meaning	Risk Signal
21001	moderate activity on risky services	Significant activity on this number to/from risky services over the past 90 days.	✅
21002	high activity on risky services	Very significant activity on this number to/from risky services over the past 90 days.	✅
21004	long-term activity on risky services	Verification traffic with risky services on this number over the past 90 days.	✅
21005	short-term activity on risky services	Verification traffic with risky services on this number over the past 24 hours.	✅
21006	high long-term activity on risky services	High volume of verification traffic with risky services on this number over the past 90 days.	✅
21007	high short-term activity on risky services	High volume of verification traffic with risky services on this number over the past 24 hours.	✅
21008	long-term range activity on risky services	Risky services verification traffic on the range this number belongs to over the past 90 days.	✅
21009	short-term range activity on risky services	Risky services verification traffic on the range this number belongs to over the past 24 hours.	✅
21010	high long-term range activity on risky services	High traffic volume with risky services on this number range over the past 90 days.	✅
21011	high short-term range activity on risky services	High traffic volume with risky services on this number range over the past 24 hours.	✅
21012	very high short-term activity on risky services	Very high traffic with risky services on this number over the past 90 days.	✅
21013	very high long-term activity on risky services	Very high traffic with risky services on this number over the past 24 hours.	✅
21014	very high short-term range activity on risky services	Very high risky services traffic on the number’s range over the past 90 days.	✅
21015	very high long-term range activity on risky services	Very high risky services traffic on the number’s range over the past 24 hours.	✅

Other

Code	Name	Meaning	Risk Signal	Trust Signal
21003	machine-like activity	Behavior suggests this number is operated by a bot. A2P traffic is expected, but the user shouldn’t be automated.	✅
21016	machine-like range activity	Extremely high verification volume in < 1 hour across the number’s range—indicating potential automation.	✅

Recency

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

P2P

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.

Number Type

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	Risky phone type not covered by other `numberType` 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	Invalid number—too long even after cleansing.	✅
40013	blacklisted number	This number has been flagged as a source of fraud.	✅
40014	high-risk country	Country code is associated with disproportionate fraud attacks.	✅
40015	technical number	Number used for telecom company technical purposes (e.g., roaming).
40016	number used by application	Telesign-reserved number is being used inappropriately.	✅
40017	number whitelisted by customer	You have flagged this number as safe.		✅
40018	phone too short	This number is too short to be valid.	✅

IP

Reason codes related to activity of the IP address you provided for this number.

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 short-term activity with risky services.	✅
50004	moderate long-term activity on risky services	Significant long-term activity with risky services.	✅
50005	high short-term activity	Higher than expected short-term activity on this IP address.	✅
50006	high long-term activity	Higher than expected long-term activity on this IP address.	✅
50007	high short-term activity on risky services	Very significant risky short-term activity on this IP.	✅
50008	high long-term activity on risky services	Very significant risky long-term activity on this IP.	✅
50009	very high short-term activity	Very frequent IP attribute changes on this number in the last 24 hours.	✅
50010	very high long-term activity	Very frequent IP attribute changes on this number in the last 90 days.	✅
50011	short-term activity on risky services	IP attribute changes tied to risky services over the past 24 hours.	✅
50012	long-term activity on risky services	IP attribute changes tied to risky services over the past 90 days.	✅
50013	very high short-term activity on risky services	Very frequent risky service changes on this IP over 24 hours.	✅
50014	very high long-term activity on risky services	Very frequent risky service changes on this IP over 90 days.	✅
50015	anonymous proxy	IP address is linked to anonymous proxies.	✅
50016	VPN	IP address is associated with a VPN.	✅
50017	hosting provider	IP belongs to a hosting provider — atypical behavior for real users.	✅
50018	TOR exit node	IP address is a known Tor exit node — often used to mask traffic origin.	✅

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 on risky services in the last 24 hours.	✅
60004	moderate long-term activity on risky services	Significant activity on risky services over the past 90 days.	✅
60005	high short-term activity	More than expected short-term activity on this email address.	✅
60006	high long-term activity	More than expected long-term activity on this email address.	✅
60007	high short-term activity on risky services	Very significant short-term risky service activity.	✅
60008	high long-term activity on risky services	Very significant long-term risky service activity.	✅
60009	very high short-term activity	Very high verification traffic in the last 24 hours.	✅
60010	very high long-term activity	Very high verification traffic in the past 90 days.	✅
60011	machine-generated email	Behavior suggests the email is automated or bot-controlled.	✅
60012	invalid email	This email is invalid and likely not used by a genuine end user.	✅
60013	disposable email domain	Email from a temporary/disposable email provider.	✅

Phone Type Codes

These codes categorize phone numbers based on their characteristics, such as whether they are fixed lines, mobile, prepaid, or other types.

Phone Type Codes

Code	Name	Risk Level	Action	Description
1	FIXED_LINE	Low	Allow	Traditional landlines and traceable VOIP numbers.
2	MOBILE	Medium-Low	Allow	Contract-based mobile phones, generally traceable.
3	PREPAID	Medium-High	Flag	Anonymous, prepaid mobile phones with less traceability.
4	TOLL_FREE	High	Block	Easily obtained numbers that forward to untraceable destinations.
5	VOIP	High	Block	Non-fixed, disposable, and untraceable internet-based numbers.
6	PAGER	High	Block	Unreachable pager numbers often used by fraudsters.
7	PAYPHONE	High	Block	Untraceable public payphones.
8	INVALID	High	Block	The number is not valid.
9	RESTRICTED_PREMIUM	High	Block	Restricted or premium numbers like 900, 911, or short codes.
10	PERSONAL	Medium-Low	Allow	Forwarding numbers provided by phone companies, typically low-risk.
11	VOICEMAIL	Medium-High	Block	Numbers that ring directly to voicemail, making verification impossible.
20	OTHER	Medium-High	Block	Miscellaneous non-US numbers likely input incorrectly or by fraudsters.

Phone Type Override Reason Codes

These codes specify additional reasons for altering the original phone type classification, based on specific characteristics or risk factors identified.

Phone Type Override Reason Codes

Code	Text String	Description
1	Value Added Services (VAS) Number	Number belongs to a range used for services like virtual numbers, VoIP, or receive-SMS-online.
2	Reported Fraud - High-Risk Number	Number or range was recently involved in telecom fraud, reported by carriers.
5	Premium Rate Number	Number is in a range dedicated to premium rate or special services.
6	Publicly Available Number	Number is published online for disposable use or premium-rate services.
8	Carrier Prefix Analysis	Number matches patterns of non-fixed VoIP, prepaid, or restricted types via prefix analysis.
10	SMS-enabled Carrier	Fixed-line number enabled for SMS, reclassified as Mobile.
11	Non SMS-enabled Phone Number	Fixed-line number not SMS-enabled, even if carrier supports SMS for others.

4. Verification (Upcoming)

4.1 Verification

Endpoint

POST /phone-service/verification

Description

The Messaging API enables you to deliver important verification messages to your users through the channels they use most. For the verification endpoint, supported delivery methods include:

SMS: Fast and globally reliable message delivery via standard text messaging.
Email: A secure and user-friendly fallback or primary channel for sending verification messages.

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Field	Type	Required	Description
`phoneNumber`	string	Yes for SMS	Recipient’s phone number in international format, no spaces or special characters.
`email`	string	Yes for EMAIL	Recipient’s email address.
`method`	string	Yes	The delivery method to use. Only accepted values: `sms` or `email`.
`securityFactor`	string	No	A custom numeric OTP (3–10 digits). If omitted, a 6-digit OTP is auto-generated.
`externalId`	string	No	Customer-defined transaction ID. Max length: 100 characters.
`messageTemplate.name`	string	No	Template name (lowercase letters and underscores only).
`messageTemplate.verificationTemplate`	string	No	Template content to be used for this verification.
`voiceLang`	string	No	Language code for OTP delivery (e.g., `en-US`). Defaults to English if not provided.

Response Structure

Field	Type	Description
`referenceId`	string	A unique 32-character hex string that identifies the verification process.
`status.code`	integer	Numeric code representing the transaction status.
`status.description`	string	Human-readable description of the transaction status.
`recipient.phoneNumber`	string	Recipient’s phone number in international format.
`recipient.email`	string	Recipient’s email address.
`state`	string	Current state of the verification process. One of: `CREATED`, `ONGOING`, `REJECTED`, `FAILED`, `VERIFIED`, `CANCELED`.
`method`	string	The verification method used. One of: `sms`, `email`.

Example Request

Example Response

{
  "referenceId": "0123456789ABCDEF0123456789ABCDEF",
  "status": {
    "code": 3901,
    "description": "Request in progress"
  },
  "recipient": {
    "phoneNumber": "11234567890"
  },
  "method": "sms",
  "state": "CREATED"
}

4.2 Verification Match (Upcoming)

Endpoint

PATCH /verificationMatch/{referenceId}

Description

Use this endpoint to validate the one-time passcode (OTP) provided by the end user and update the state of an active verification process. This action is typically used to finalize a verification by checking whether the user-entered OTP matches the one originally sent via SMS or email. If the OTP is correct, the verification process is marked as VERIFIED. If incorrect, an error is returned and the process may remain ONGOING, FAILED, or another relevant state depending on implementation.

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Field	Type	Required	Description
`action`	string	Yes	Specifies how to change the verification state. Only accepted value: `"finalize"` to complete the verification process.
`securityFactor`	string	Yes	The OTP provided by the end user (3–10 digits). Used to verify whether the entered OTP matches the one previously sent/generated.

Response Structure

Field	Type	Description
`status.code`	integer	A numeric code that indicates the result of the verification match.
`status.description`	string	Human-readable text describing the outcome of the verification match.

Example Request

Example Response

5. Full Phone Intelligence (Upcoming)

Endpoint

POST /phone-service/fullPhoneIntelligence

Description

Full Phone Intelligence delivers a comprehensive risk and identity assessment for a phone number in a single API call. It combines behavioral signals, telecom intelligence, and historical data to help you detect fraud, verify identity, and make confident risk decisions. This service analyzes the phone number using various trust and risk indicators such as:

Activity patterns (short-term and long-term)
Carrier and phone type information
SIM swap detection
Call forwarding status
Deactivation and porting history
Known data breaches
Active call status
Geolocation and time zone data
Contact matching and scoring

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Response Structure

Field	Type	Description
`status`	boolean	Indicates if the API request was successful.
`data`	object	Contains the transaction result details.
`data.referenceId`	string	Unique reference ID for the transaction.
`data.externalId`	string	External reference ID (nullable).
`data.status`	object	Transaction status details.
`data.status.updatedOn`	string	Timestamp of the last update (ISO 8601 format).
`data.status.code`	number	Status code (e.g., `300` for success).
`data.status.description`	string	Status description message.
`data.numbering`	object	Original and cleansed phone number details.
`data.numbering.original`	object	Original phone number information.
`data.numbering.original.completePhoneNumber`	string	Complete phone number in international format.
`data.numbering.original.countryCode`	string	Country dialing code.
`data.numbering.original.phoneNumber`	string	Local phone number.
`data.numbering.cleansing`	object	Cleansed phone number details for call and SMS.
`data.numbering.cleansing.call`	object	Cleansed phone number details for calling.
`data.numbering.cleansing.call.countryCode`	string	Country dialing code after cleansing.
`data.numbering.cleansing.call.phoneNumber`	string	Cleansed local phone number for calling.
`data.numbering.cleansing.call.cleansedCode`	number	Result code of cleansing (e.g., `100` = valid).
`data.numbering.cleansing.call.minLength`	number	Minimum valid length of phone number.
`data.numbering.cleansing.call.maxLength`	number	Maximum valid length of phone number.
`data.numbering.cleansing.sms`	object	Cleansed phone number details for SMS.
`data.numbering.cleansing.sms.countryCode`	string	Country dialing code after cleansing.
`data.numbering.cleansing.sms.phoneNumber`	string	Cleansed local phone number for SMS.
`data.numbering.cleansing.sms.cleansedCode`	number	Result code of cleansing (e.g., `100` = valid).
`data.numbering.cleansing.sms.minLength`	number	Minimum valid length of phone number.
`data.numbering.cleansing.sms.maxLength`	number	Maximum valid length of phone number.
`data.riskInsights`	object	Risk assessment details.
`data.riskInsights.status`	number	Risk status code.
`data.riskInsights.category`	array	Risk category codes.
`data.riskInsights.a2P`	array	Application-to-Person (A2P) risk indicators.
`data.riskInsights.p2P`	array	Person-to-Person (P2P) risk indicators.
`data.riskInsights.numberType`	array	Number type risk indicators (if any).
`data.riskInsights.ip`	array	IP-related risk indicators (if any).
`data.riskInsights.email`	array	Email-related risk indicators (if any).
`data.phoneType`	object	Phone type information.
`data.phoneType.code`	string	Phone type code (e.g., `2`).
`data.phoneType.description`	string	Phone type description (e.g., “MOBILE”).
`data.location`	object	Location details associated with the phone number.
`data.location.city`	string	City of the number (if available).
`data.location.state`	string	State or region (nullable).
`data.location.zip`	string	ZIP or postal code (nullable).
`data.location.metroCode`	string	Metro code (nullable).
`data.location.county`	string	County (nullable).
`data.location.country`	object	Country details.
`data.location.country.name`	string	Country name.
`data.location.country.iso2`	string	ISO 2-letter country code.
`data.location.country.iso3`	string	ISO 3-letter country code.
`data.location.coordinates`	object	Geographic coordinates.
`data.location.coordinates.latitude`	number	Latitude (nullable).
`data.location.coordinates.longitude`	number	Longitude (nullable).
`data.location.timeZone`	object	Time zone information.
`data.location.timeZone.name`	string	Time zone name (nullable).
`data.location.timeZone.utcOffsetMin`	string	Minimum UTC offset.
`data.location.timeZone.utcOffsetMax`	string	Maximum UTC offset.
`data.carrier`	object	Carrier (telecom provider) details.
`data.carrier.name`	string	Carrier name.
`data.blocklisting`	object	Blocklisting details.
`data.blocklisting.blocked`	boolean	Indicates if the number is blocklisted.
`data.blocklisting.blockCode`	number	Blocklisting code (e.g., `0` = not blocked).
`data.blocklisting.blockDescription`	string	Blocklisting description.
`data.risk`	object	Overall risk score and recommendation.
`data.risk.level`	string	Risk level (e.g., `medium-low`).
`data.risk.recommendation`	string	Risk handling recommendation (e.g., `allow`).
`data.risk.score`	number	Risk score (numerical value).

Example Request

Example Response

{
    "status": true,
    "data": {
        "referenceId": "3661FDC54750091C93078058241C3036",
        "externalId": null,
        "status": {
            "updatedOn": "2025-08-06T12:53:09.929413Z",
            "code": 300,
            "description": "Transaction successfully completed"
        },
        "numbering": {
            "original": {
                "completePhoneNumber": "+436501234567",
                "countryCode": "43",
                "phoneNumber": "6501234567"
            },
            "cleansing": {
                "call": {
                    "countryCode": "43",
                    "phoneNumber": "6501234567",
                    "cleansedCode": 100,
                    "minLength": 7,
                    "maxLength": 13
                },
                "sms": {
                    "countryCode": "43",
                    "phoneNumber": "6501234567",
                    "cleansedCode": 100,
                    "minLength": 7,
                    "maxLength": 13
                }
            }
        },
        "riskInsights": {
            "status": 800,
            "category": [
                10010
            ],
            "a2P": [
                22007,
                20011,
                20101
            ],
            "p2P": [
                30201
            ],
            "numberType": [],
            "ip": [],
            "email": []
        },
        "phoneType": {
            "code": "2",
            "description": "MOBILE"
        },
        "location": {
            "city": "Countrywide",
            "state": null,
            "zip": null,
            "metroCode": null,
            "county": null,
            "country": {
                "name": "Austria",
                "iso2": "AT",
                "iso3": "AUT"
            },
            "coordinates": {
                "latitude": null,
                "longitude": null
            },
            "timeZone": {
                "name": null,
                "utcOffsetMin": "+1",
                "utcOffsetMax": "+1"
            }
        },
        "carrier": {
            "name": "T-Mobile Austria GmbH"
        },
        "blocklisting": {
            "blocked": false,
            "blockCode": 0,
            "blockDescription": "Not blocked"
        },
        "risk": {
            "level": "medium-low",
            "recommendation": "allow",
            "score": 301
        }
    }
}

Status Codes

Status Code	Associated Text String	Description
300	Transaction successfully completed	The system was able to obtain all of the requested data.
301	Transaction partially completed	The system was able to obtain some of the data, but not all of it.
400	Bad Request	Malformed syntax in the request. See error code for specifics.
401	Unauthorized	Authentication failed. See error code for details.
404	Not Found	The server could not find the requested resource.
429	Too Many Requests	Rate limit exceeded. Too many requests sent in a short period of time.
500	Invalid Transaction	Transaction not attempted due to a system issue.
503	Service Unavailable	System is temporarily unavailable. Try again later.

Getting Started

Essentials

​Phone Status Check - Detailed Documentation

​API Playground:

​Endpoints Overview

​Authentication

​API Base URL

​1. Phone Status Check

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Example Request

​Example Response

​2. Phone ID (Upcoming)

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Add-ons Object Fields

​Consent Object Fields

​Response Structure

​Example Request

​Example Response

​3. Phone Risk Score

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Example Request

​Example Response

​Risk Recommendation Scales

​Risk Score Table

​Reason Codes

​A2P

​P2P

​Number Type

​IP

​Email

​Phone Type Codes

​Phone Type Override Reason Codes

​4. Verification (Upcoming)

​4.1 Verification

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Example Request

​Example Response

​4.2 Verification Match (Upcoming)

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Example Request

​Example Response

​5. Full Phone Intelligence (Upcoming)

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Example Request

​Example Response

​Status Codes

Phone Status Check - Detailed Documentation

API Playground:

Endpoints Overview

Authentication

API Base URL

1. Phone Status Check

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response

2. Phone ID (Upcoming)

Endpoint

Description

Required Headers

Request Body Parameters

Add-ons Object Fields

Consent Object Fields

Response Structure

Example Request

Example Response

3. Phone Risk Score

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response

Risk Recommendation Scales

Risk Score Table

Reason Codes

A2P

P2P

Number Type

IP

Email

Phone Type Codes

Phone Type Override Reason Codes

4. Verification (Upcoming)

4.1 Verification

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response

4.2 Verification Match (Upcoming)

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response

5. Full Phone Intelligence (Upcoming)

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response

Status Codes