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 /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

{
"phone": "+436504142107"
}

Example Response

{
    "reference_id": "36475B3EB1DC0C2492E2889F4EACF2CC",
    "sub_resource": "live",
    "status": {
        "code": 300,
        "description": "Transaction successfully completed",
        "updatedOn": "2024/09/09T12:43:42.701105Z"
    },
    "errors": [],
    "phoneType": {
        "code": "2",
        "description": "MOBILE"
    },
    "blocklisting": {
        "blocked": false,
        "blockCode": 0,
        "blockDescription": "Not blocked"
    },
    "numbering": {
        "cleansing": {
            "call": {
                "countryCode": "43",
                "phoneNumber": "6504142107",
                "cleansedCode": 100,
                "minLength": 7,
                "maxLength": 13
            },
            "sms": {
                "countryCode": "43",
                "phoneNumber": "6504142107",
                "cleansedCode": 100,
                "minLength": 7,
                "maxLength": 13
            }
        },
        "original": {
            "completePhoneNumber": "+436504142107",
            "countryCode": "43",
            "phoneNumber": "6504142107"
        }
    },
    "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,
            "utcOffsetMax": "+1",
            "utcOffsetMin": "+1"
        }
    },
    "carrier": {
        "name": "Mass Response Service GmbH"
    },
    "live": {
        "subscriberStatus": "ACTIVE",
        "deviceStatus": "REACHABLE",
        "roaming": "UNAVAILABLE",
        "roamingCountry": null,
        "roamingCountryIso2": null
    }
}

2. Phone ID (Upcoming)

Endpoint

POST /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	Yes	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
`referenceId`	string	Unique 32-digit hex ID for the request, generated by Telesign.	basic
`externalId`	string \| null	Custom ID provided in the request. Returned if included.	basic
`status.code`	integer	Status code for the request processing.	basic
`status.description`	string	Human-readable description of the transaction status.	basic
`status.updatedOn`	string	RFC 3339 timestamp of last update.	basic
`phoneType.code`	string	Phone type code.	basic
`phoneType.description`	string	Description of the phone type.	basic
`phoneType.overrideReason`	string	Description of phone type override (if applicable).	basic
`phoneType.overrideReasonId`	integer	Code indicating the reason for phone type override.	basic
`blocklisting.blockCode`	integer	Block status code.	basic
`blocklisting.blockDescription`	string	Description of the block reason.	basic
`blocklisting.blocked`	boolean	Indicates if the number is blocked.	basic
`carrier.name`	string	Name of the carrier.	basic
`carrier.carrierId`	integer	Internal carrier ID.	basic
`carrier.mcc`	string	Mobile Country Code.	basic
`carrier.mnc`	string	Mobile Network Code.	basic
`numbering.original`	object	Original phone number submitted.	basic
`numbering.cleansing`	object	Cleansed/standardized phone number data.	basic
`location.city`	string	City where the number was activated.	basic
`location.state`	string	State or province where the number was activated.	basic
`location.zip`	string	ZIP code associated with the rate center.	basic
`location.country`	object	Country info for the number.	basic
`location.timeZone`	object	Time zone information for the phone number.	basic
`location.coordinates`	object	Latitude and longitude.	basic
`location.metroCode`	string	PMSA code for U.S. metro regions.	basic
`ageVerify.ageVerified`	boolean	Whether age threshold was met.	ageVerify
`ageVerify.status`	object	Status object for the age verification check.	ageVerify
`activeCallStatus.isCallActive`	boolean	Indicates if the number is currently in a call.	activeCallStatus
`activeCallStatus.callDuration`	integer	Duration of the active call in seconds.	activeCallStatus
`activeCallStatus.callDirection`	string	Direction of the call (called/calling).	activeCallStatus
`activeCallStatus.status`	object	Status object for the call activity.	activeCallStatus
`breachedNumberCheck.phoneNumberBreached`	boolean	Indicates if the number was part of a breach.	breachedData
`breachedNumberCheck.breachDate`	string	Date of the breach if known.	breachedData
`breachedNumberCheck.breachedData`	array	List of breached data types.	breachedData
`breachedNumberCheck.status`	object	Status object for breach check.	breachedData
`callForwardDetection.callForwardEnabled`	string	Whether call forwarding is enabled.	callForwardDetection
`callForwardDetection.callForwardType`	string	Type of call forwarding (conditional, unconditional).	callForwardDetection
`callForwardDetection.callForwardCondition`	string	Forwarding condition (busy, unanswered, etc.).	callForwardDetection
`callForwardDetection.status`	object	Status object for call forwarding check.	callForwardDetection
`contact.firstName`	string	Subscriber’s first name.	contact
`contact.lastName`	string	Subscriber’s last name.	contact
`contact.emailAddress`	string	Email address linked to the number.	contact
`contact.city`	string	City from subscriber’s address.	contact
`contact.country`	string	Country of subscriber.	contact
`contact.dateOfBirth`	string	Date of birth (if available).	contact
`contact.status`	object	Status object for the contact package.	contact
`contactMatch.firstNameScore`	integer	Match score for first name (0–100).	contactMatch
`contactMatch.lastNameScore`	integer	Match score for last name (0–100).	contactMatch
`contactMatch.addressScore`	integer	Match score for address (0–100).	contactMatch
`contactMatch.status`	object	Status object for contact match.	contactMatch
`numberDeactivation.carrierName`	string	Last associated carrier.	numberDeactivation
`numberDeactivation.lastDeactivated`	string	When the number was last deactivated.	numberDeactivation
`numberDeactivation.trackingSince`	string	When the number started being tracked.	numberDeactivation
`numberDeactivation.recycledSinceLastVerification`	string	Recycling status.	numberDeactivation
`numberDeactivation.status`	object	Status of the number deactivation check.	numberDeactivation
`subscriberStatus.accountActivationDate`	string	When the account was activated.	subscriberStatus
`subscriberStatus.accountStatus`	string	Whether account is active, suspended, or deactivated.	subscriberStatus
`subscriberStatus.accountType`	string	Type of account (prepaid/postpaid).	subscriberStatus
`subscriberStatus.contractType`	string	Subscriber’s contract type.	subscriberStatus
`subscriberStatus.accountTenureMin`	integer	Minimum months the account has been active.	subscriberStatus
`subscriberStatus.accountTenureMax`	integer	Maximum months the account has been active.	subscriberStatus
`subscriberStatus.primaryAccountHolder`	boolean	Whether it’s the primary phone number for the account.	subscriberStatus
`subscriberStatus.status`	object	Status object for the subscriber check.	subscriberStatus
`portingHistory.portDate`	string	Date the number was last ported.	portingHistory
`portingHistory.carrierCurrent`	string	Current carrier.	portingHistory
`portingHistory.carrierPrevious`	string	Previous carrier.	portingHistory
`portingHistory.status`	object	Status of porting history check.	portingHistory
`portingStatus.ported`	boolean	Whether the number was ported.	portingStatus
`portingStatus.mccCurrent`	string	Mobile Country Code of current carrier.	portingStatus
`portingStatus.mncCurrent`	string	Mobile Network Code of current carrier.	portingStatus
`portingStatus.status`	object	Status of porting status check.	portingStatus
`simSwap.swapDate`	string	Date the SIM was last swapped.	simSwap
`simSwap.swapTime`	string	Time the SIM was swapped.	simSwap
`simSwap.riskIndicator`	string	Fraud risk level (1–4).	simSwap
`simSwap.status`	object	Status of SIM swap detection.	simSwap

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

{
  "referenceId": "f0123456789abcdef0123456789abcde",
  "phoneType": {
    "code": "1",
    "overrideReason": "NonSmsEnabledPhoneNumber",
    "description": "FIXED_LINE",
    "overrideReasonId": 11
  },
  "blocklisting": {
    "blockCode": 0,
    "blockDescription": "Not blocked",
    "blocked": true
  },
  "status": {
    "code": 300,
    "description": "Transaction successfully completed",
    "updatedOn": "2023-10-03T14:51:28.709Z"
  },
  "numbering": {
    "original": {
      "phoneNumber": "9876543210",
      "completePhoneNumber": "19876543210",
      "countryCode": "1"
    },
    "cleansing": {
      "call": {
        "cleansedCode": 100,
        "countryCode": "1",
        "maxLength": 10,
        "minLength": 10,
        "phoneNumber": "9876543210"
      },
      "sms": {
        "cleansedCode": 100,
        "countryCode": "1",
        "maxLength": 10,
        "minLength": 10,
        "phoneNumber": "9876543210"
      }
    }
  },
  "location": {
    "city": "New York",
    "county": "Kings",
    "state": "NY",
    "zip": "11201",
    "country": {
      "iso2": "US",
      "iso3": "USA",
      "name": "United States"
    },
    "timeZone": {
      "name": "America/New_York",
      "utcOffsetMax": "-5",
      "utcOffsetMin": "-5"
    },
    "coordinates": {
      "latitude": 40.7128,
      "longitude": -74.006
    },
    "metroCode": "56000"
  },
  "carrier": {
    "carrierId": 101,
    "name": "AT&T Wireless",
    "mcc": "310",
    "mnc": "410"
  },
  "ageVerify": {
    "ageVerified": true,
    "status": {
      "code": 2800,
      "description": "Age verification successful"
    }
  },
  "activeCallStatus": {
    "isCallActive": true,
    "callDuration": 180,
    "callDirection": "called",
    "status": {
      "code": 2800,
      "description": "Active call status retrieved"
    }
  },
  "breachedNumberCheck": {
    "phoneNumberBreached": true,
    "breachDate": "2021-11-18T00:00:00Z",
    "breachedData": ["email", "password"],
    "status": {
      "code": 2800,
      "description": "Breach data found"
    }
  },
  "callForwardDetection": {
    "callForwardEnabled": "true",
    "callForwardType": "unconditional",
    "callForwardCondition": "unanswered",
    "status": {
      "code": 2800,
      "description": "Call forwarding detected"
    }
  },
  "contact": {
    "address1": "456 Elm Street",
    "address2": "Apt 2B",
    "address3": "Brooklyn",
    "address4": "11201",
    "city": "New York",
    "country": "US",
    "dateOfBirth": "1985-06-15T00:00:00Z",
    "emailAddress": "jdoe@example.com",
    "firstName": "John",
    "id": "ID123456789",
    "lastName": "Doe",
    "stateProvince": "NY",
    "zipPostalCode": "11201",
    "status": {
      "code": 2800,
      "description": "Contact data retrieved"
    }
  },
  "contactMatch": {
    "addressScore": 92,
    "firstNameScore": 100,
    "lastNameScore": 98,
    "status": {
      "code": 2800,
      "description": "Contact match success"
    }
  },
  "contactPlus": {
    "address1": "456 Elm Street",
    "address2": "Apt 2B",
    "address3": "Brooklyn",
    "address4": "11201",
    "city": "New York",
    "country": "US",
    "dateOfBirth": "1985-06-15T00:00:00Z",
    "emailAddress": "jdoe@example.com",
    "firstName": "John",
    "id": "ID123456789",
    "lastName": "Doe",
    "stateProvince": "NY",
    "zipPostalCode": "11201",
    "status": {
      "code": 2800,
      "description": "Contact+ data retrieved"
    }
  },
  "numberDeactivation": {
    "carrierName": "T-Mobile",
    "lastDeactivated": "2022-07-01T00:00:00Z",
    "status": {
      "code": 2800,
      "description": "Deactivation check passed"
    },
    "trackingSince": "2020-01-01T00:00:00Z",
    "recycledSinceLastVerification": "notRecycled"
  },
  "subscriberStatus": {
    "status": {
      "code": 2800,
      "description": "Subscriber status retrieved"
    },
    "accountActivationDate": "2021-05-15T00:00:00Z",
    "accountType": "individual",
    "accountTenureMax": 12,
    "accountTenureMin": 6,
    "primaryAccountHolder": true,
    "accountStatus": "active",
    "contractType": "postpaid"
  },
  "portingHistory": {
    "carrierCurrent": "T-Mobile USA",
    "carrierPrevious": "Verizon Wireless",
    "mccCarrierCurrent": "310",
    "mccCarrierPrevious": "310",
    "mncCarrierCurrent": "260",
    "mncCarrierPrevious": "012",
    "phoneTypeCurrent": "MOBILE",
    "phoneTypePrevious": "MOBILE",
    "portDate": "2023-01-10T09:00:00Z",
    "numberOfPortings": "2",
    "status": {
      "code": 2800,
      "description": "Porting history retrieved"
    }
  },
  "portingStatus": {
    "mccCurrent": "310",
    "mncCurrent": "260",
    "ported": true,
    "status": {
      "code": 2800,
      "description": "Porting status confirmed"
    }
  },
  "simSwap": {
    "swapDate": "2023-07-15T00:00:00Z",
    "swapTime": "14:32:00",
    "riskIndicator": "2",
    "status": {
      "code": 2800,
      "description": "SIM swap risk evaluated"
    }
  },
  "externalId": "customExternalId123"
}

3. Phone Risk Score (Upcoming)

Endpoint

POST /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
`phone`	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
`referenceId`	string	Unique ID for the web service request.
`externalId`	string \| null	Echo of the custom ID you provided in the request.
`status.code`	integer	Internal status code of the transaction.
`status.description`	string	Description of the transaction status.
`status.updatedOn`	string	RFC 3339 timestamp of last update.
`location.city`	string	City associated with the phone number’s rate center.
`location.county`	string	County or parish (U.S. only).
`location.state`	string	Two-letter state or province abbreviation.
`location.zip`	string	5-digit U.S. ZIP code.
`location.country`	object	Country information (ISO codes, name).
`location.timeZone`	object	Time zone data including UTC offset.
`location.coordinates`	object	Latitude and longitude of the number’s location.
`location.metroCode`	string	PMSA code for large U.S. metro areas.
`numbering.original`	object	The original submitted phone number and details.
`numbering.cleansing`	object	Cleaned version of the phone number for calling and SMS.
`phoneType.code`	string	Phone type code.
`phoneType.description`	string	Description of the phone type (e.g., `FIXED_LINE`).
`phoneType.overrideReason`	string	Why the phone type was overridden (if applicable).
`phoneType.overrideReasonId`	integer	Override reason ID code.
`blocklisting.blocked`	boolean	Whether the phone number is currently blocked.
`blocklisting.blockCode`	integer	Reason code for the block.
`blocklisting.blockDescription`	string	Explanation for the block status.
`carrier.carrierId`	integer	Carrier ID (if provided).
`carrier.name`	string	Carrier name (e.g., `AT&T Wireless`).
`risk.level`	string	Severity of the risk (e.g., `low`, `high`).
`risk.recommendation`	string	Recommended action: `allow`, `flag`, or `block`.
`risk.score`	integer	Risk score from 0 to 1000, higher = riskier.
`riskInsights.status`	integer	Status of the insights package.
`riskInsights.category`	array of integers	Reason codes related to the phone number’s category.
`riskInsights.a2p`	array of integers	A2P-specific reason codes (e.g., automated messages).
`riskInsights.p2p`	array of integers	P2P-specific reason codes (e.g., human-to-human messages).
`riskInsights.numberType`	array of integers	Reason codes related to the phone number type.
`riskInsights.ip`	array of integers	Reason codes related to IP address activity.
`riskInsights.email`	array of integers	Reason codes related to email address activity.

Example Request

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

Example Response

{ 

  "referenceId": "B567DC5D1180011C8952823CF6B40773", 

  "status": { 

    "updatedOn": "2022-02-01T00:33:34.860418Z", 

    "code": 300, 

    "description": "Transaction successfully completed" 

  }, 

  "numbering": { 

    "original": { 

      "completePhoneNumber": "15555551212", 

      "countryCode": "1", 

      "phoneNumber": "5555551212" 

    }, 

    "cleansing": { 

      "call": { 

        "countryCode": "1", 

        "phoneNumber": "5555551212", 

        "cleansedCode": 105, 

        "minLength": 10, 

        "maxLength": 10 

      }, 

      "sms": { 

        "countryCode": "1", 

        "phoneNumber": "5555551212", 

        "cleansedCode": 105, 

        "minLength": 10, 

        "maxLength": 10 

      } 

    } 

  }, 

  "phoneType": { 

    "code": "8", 

    "description": "INVALID" 

  }, 

  "location": { 

    "city": "Countrywide", 

    "state": null, 

    "zip": null, 

    "metroCode": null, 

    "county": null, 

    "country": { 

      "name": "United Kingdom", 

      "iso2": "GB", 

      "iso3": "GBR" 

    }, 

    "coordinates": { 

      "latitude": null, 

      "longitude": null 

    }, 

    "timeZone": { 

      "name": null, 

      "utcOffsetMin": "0", 

      "utcOffsetMax": "0" 

    } 

  }, 

  "carrier": { 

    "name": "Telefonica UK Limited" 

  }, 

  "risk": { 

    "level": "high", 

    "recommendation": "block", 

    "score": 959 

  }, 

  "riskInsights": { 

    "status": 800, 

    "category": [ 

      10002 

    ], 

    "a2p": [ 

      20001, 

      20101, 

      21002 

    ], 

    "p2p": [ 

      30201 

    ], 

    "numberType": [ 

      40005, 

      40011 

    ], 

    "ip": [ 

      50001, 

      50004 

    ], 

    "email": [ 

      60003, 

      60006 

    ] 

  } 

}

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 /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
`recipient.phoneNumber`	string	Yes for SMS	Recipient’s phone number in international format, no spaces or special characters.
`recipient.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

{
  "recipient": {
    "phoneNumber": "14155550123"
  },
  "method": "sms",
  "securityFactor": "123456",
  "externalId": "verifyRequest123",
  "messageTemplate": {
    "name": "welcome_otp",
    "verificationTemplate": "Your code is {{code}}. It expires in 5 minutes."
  },
  "voiceLang": "en-US"
}

Example Response

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

4.2 Verification Match

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 /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

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 (Upcoming)

​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

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Example Request

​Example Response

​5. Full Phone Intelligence (Upcoming)

​Endpoint

​Description

​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 (Upcoming)

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

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response

5. Full Phone Intelligence (Upcoming)

Endpoint

Description

Status Codes