Phone ID - Get started with identity attributes
NOTE:
To enable any identity attributes other than Contact, contact a Telesign expert.
Phone ID identity signals allow you to find out many kinds of information associated with a phone number. Choices include:
- Age Verify - Test whether or not the subscriber of a phone number meets a certain age threshold.
- Call Forwarding - Get information about the call forwarding status of a phone number.
- Contact - Get basic contact information about any phone number.
- Contact Plus - Get high quality contact information about any phone number by tapping into additional data sources. (Consent required.)
- Contact Match - Get a score indicating how closely your name and address for a submitted phone number match the name and address on file with the carrier.
- Number Deactivation - Find out if and when a phone number was deactivated, and by which carrier.
- Subscriber Status - Find out whether the phone is prepaid, post paid, who the primary account holder is, and how long the particular status has been maintained.
- Porting History - Find out when a phone number was ported, where it was ported to, and by who.
- Porting Status - Find out the current MCC (mobile country code) and the current MNC (mobile network code).
- SIM Swap - Find out whether or not the SIM card for the phone has been swapped or not, and when.
Enable an identity attribute
To enable any identity attribute, speak with our Customer Support Team.
Use an identity attribute
Use an identity attribute by including its associated key as a sub-property of the addons
object in the payload:
Example
Request
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 12 Oct 2017 14:11:09 GMT
Content-Type: application/json
{
"addons": {
"contact": {}
}
}
See the table below for the required key and an example value (including sub-properties) for each identity attribute:
Identity attribute | Key | Example value |
---|---|---|
Age Verify | age_verify | |
Call Forward | Detection | call_forward_detection |
Contact | contact | {} |
Contact Plus | contact_plus | {"billing_postal_code": "40509"} |
Contact Match | contact_match | { "first_name": "Peter", "last_name": "Petersen", "address": "1444 S. Alameda Street Los Angeles", "city": "San Jose", "postal_code": "95120", "state": "CA", "country": "USA" } |
Number Deactivation | number_deactivation | {"last_verified": "2018-04-05T00:00:00Z"} |
Subscriber Status | subscriber_status | {} |
Porting History | porting_history | {} |
Porting Status | porting_status | {} |
SIM Swap | sim_swap | {} |
NOTE:
Most identity attributes require only an empty object as the value of the associated property.
Try It
If you have been granted access and credentials for Telesign Phone ID and have at least one identity attribute enabled, you can try a test request in the API Explorer. You can also get a code snippet for the request.
- Click the Auth tab and for Username add your Customer ID. For Password add your API key.
- In the Settings tab, for the complete_phone_number field, enter the complete phone number that you want to request information about (include the country code).
- Click Send.
- Click the Code Generation tab and use the Language and Library menus to choose the language you want your code snippet in.
Try It with cURL
To try Telesign Phone ID with identity attributes using cURL:
- Copy one of the commands below into a text editor
- Replace
$COMPLETE_NUMBER
in the command with the phone number you want information for. - Replace
$CUSTOMER_ID
with your Customer ID from TelePortal - Replace
$API_KEY
with your API key from TelePortal. - If you are trying out the Call Forward Detection identity signal, replace the following parameters with the appropriate values:
- Replace
$METHOD
with the way you collected the consent record - Replace
$TIMESTAMP
with the date and time you collected the consent record
- Paste the edited command onto the command line and run it.
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{ "addons":{ "age_verify":{} } }' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"call_forward_detection":{}},"consent":{"method":"$METHOD","timestamp":"$TIMESTAMP"}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"contact":{}}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons": {"contact_match":{"first_name": "User First Name", "last_name":"User Last Name", "address": "123 Main St", "city": "Marina Del Rey"}}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"contact_plus":{"zip_code": "90292"}}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"number_deactivation":{}}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"porting_history":{}}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"porting_status":{}}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"sim_swap":{}}}' --user "$CUSTOMER_ID":"$API_KEY"
curl --request POST https://rest-ww.telesign.com/v1/phoneid/$COMPLETE_NUMBER --header "Content-Type: application/json" --data '{"addons":{"subscriber_status":{}}}' --user "$CUSTOMER_ID":"$API_KEY"
Status codes
Status code | Description |
---|---|
2800 | Request successfully completed |
2801 | Invalid request add-ons parameter: {parameter_name}. |
2802 | {name of identity signal} identity signal temporarily unavailable. |
2803 | Phone number out of {name of identity signal} identity signal coverage. |
2804 | Phone number not applicable in {name of identity signal} identity signal. |
2805 | No {name of identity signal} identity signal information for phone number. |
2806 | {name of identity signal} identity signal is not enabled. |
2807 | Some parameters submitted in the request are not valid. |
2808 | Invalid Request: {parameter_name} parameter is missing or empty. |
2809 | Billing Postal Code does not match contact_plus identity signal information for phone number. |
2810 | Request process failed during data collection. |
2811 | Request processing timeout. |
2812 | {name of identity signal} exceeded transaction hard cap. Request denied. |
Updated 4 days ago