Phone ID - Get started with identity attributes

πŸ“˜

NOTE:

To enable any identity attributes other than Contact, contact a Telesign expert.

Phone ID identity attributes 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.
  • Breached Data - Check if a phone number or any associated Personal Identifiable Information (PII) was compromised in a recent data breach.
  • Call Forwarding - Get information about the call forwarding status of a phone number.
  • Contact - Get basic contact information about any phone number.
  • 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 attributeKeyExample value
Age Verifyage_verify{}
Breached Databreached_data{}
Call Forwardcall_forward_detection{}
Contactcontact{}
Contact Matchcontact_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 Deactivationnumber_deactivation{"last_verified": "2018-04-05T00:00:00Z"}
Subscriber Statussubscriber_status{}
Porting Historyporting_history{}
Porting Statusporting_status{}
SIM Swapsim_swap{}

πŸ“˜

NOTE:

Most identity attributes require only an empty object as the value of the associated property.

Try it with curl

While you can use Try it for Phone ID to test Phone ID by itself, to test a specific identity attribute with Phone ID, you need to use curl. The commands you need to test each identity attribute can found in this Try it with curl procedure.

Before you begin

Ensure that you have the following:

Steps

🚧

CAUTION:

Using your account credentials to test products (or using the API Explorer to make a request) results in your account being charged for the transaction.

You are subject to all compliance rules as appropriate for your transaction.

  1. Copy one of the commands below into a text editor. (Use the tabs at the top of the code snippet to select the Phone ID identity attribute you want to test. A copy icon is located on the right side of the snippet.)

  2. Replace $COMPLETE_NUMBER in the command with the phone number you want information for.

  3. Replace $CUSTOMER_ID with your Customer ID.

  4. Replace $API_KEY with your API key.

  5. If you are trying out the Call Forward Detection identity attribute, 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
  1. Paste the edited command onto the command line and run it.

Commands

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":{"breached_number_check":{}}}' --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":{"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 codeDescription
2800Request successfully completed
2801Invalid request add-ons parameter: {parameter_name}.
2802name of add-on add-on temporarily unavailable.
2803Phone number out of name of add-on add-on coverage.
2804Phone number not applicable in name of add-on add-on.
2805No name of add-on add-on information for phone number.
2806Name of add-on add-on is not enabled.
2807Some parameters submitted in the request are not valid.
2808Invalid Request: {parameter_name} parameter is missing or empty.
2809Billing Postal Code does not match contact_plus add-on information for phone number.
2810Request process failed during data collection.
2811Request processing timeout.
2812name of add-on exceeded transaction hard cap. Request denied.