Obtain a score for this phone number, as well as other relevant information.
Looking for the general requirements for this API? Go to Get Started.
- Authentication: Basic (easiest to implement) or Digest
- Encoding: Accepts only UTF-8 unicode characters as inputs.
- MIME Type:
- Required Headers:
Content-Type - application/x-www-form-urlencoded
- MIME Type:
The account lifecycle event parameter allows you to send information about what stage an end user was in when you retrieved information about their phone number. Acceptable values for this parameter are -
- create - For the creation of a new account.
- sign-in - For when an end user signs in to their account.
- transact - For when an end user completes a transaction within their account.
- update - For when an update is performed, such as an update of account information or similar.
- delete - For when an account is deleted.
Your end user’s IP address (do not send your own Ip address). IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft doucment titled Internet Protocol. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled IP Version 6 Addressing Architecture.
Your end user’s device ID. This value is case sensitive.
Your end user’s account ID. This value is case sensitive.
Your end user’s email address. This value is case sensitive.
"true" value to receive Score 2.0 results from the API, instead of Score 1.0 results. The additional response property
risk_insights is also returned when including a
"true" value here. Do not include this parameter unless you have the Score 2.0 feature enabled by our Customer Support Team, as it will cause an error. If you do have the Score 2.0 feature enabled, this parameter is required.
Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status code property in the response object and use that, rather than the HTTP status code. Individual packages within the response may have their own status codes as well.
|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.|
A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly-generated by TeleSign, and is returned in the response message immediately following the web service request.
The customer-generated ID for this transaction that was provided in the request. If the
external_id parameter was not included in the request, the value here is
An object containing details about the request status.
An object containing details about the numbering attributes of the specified phone number.
An object containing details about whether the number was blocked and who requested the block. To see this information, speak with our Customer Support Team to have blocklisting information enabled.
An object containing information about the company that provides telecommunications servoces for the phone number.
An object that describes the risk score for the phone number specified in the request
Contains reason code properties with additional info related to the risk score.
Insights Reason Code Mappings provides the meaning of these reason codes.
Only returned when the
request_risk_insights parameter is passed as
"true" in the request.