Phone ID - Identity attributes: Contact

The Contact identity attribute allows you to retrieve the name, address, and other contact info associated with the subscriber for the phone number you submit. This identity attribute offers fast identity verification with minimal user interaction.

Information returned

The information returned by this identity attribute includes:

• First Name
• Last Name
• Street Address
• City
• State (or Province)
• Country
• ZIP Code
• Email Address
• Input used (Only returned when Email ID is enabled.)

Email ID feature

The Email ID feature of the Contact identity attribute taps into mobile and email digital identity datasets, increasing its accuracy. Email ID allows you to compare the email provided by an end user during an activity like an onboarding flow with the email associated with the phone number.

📘

NOTE:

While the Contact identity attribute is available for both Full-service and Self-service customers, the Email ID feature is available for Full-service accounts only. It is only available in limited markets. Contact our Customer Support Team to obtain the latest information on supported markets and to enable Email ID for your account.

Example: Contact identity attribute

This is an example of using Phone ID with the Contact identity attribute.

Request

HTTP

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": {}
        }
}

Response (body only)

JSON

{
  "contact": {
    "address1": "42 BAKER STREET",
    "address2": "",
    "address3": "",
    "address4": "",
    "city": "SEATTLE",
    "country": "",
    "first_name": "SHERLOCK",
    "last_name": "HOLMES",
    "state_province": "WA",
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    },
    "zip_postal_code": "98101",
    "email_address": "[email protected]"
  }
}

Example: Contact with Email ID feature enabled

This is an example of using Phone ID with the Contact identity attribute and Email ID enabled.

Request

HTTP

POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 25 Jan 2024 14:11:09 GMT
Content-Type: application/json 
{
  "addons": {
    "contact": {
      "email": "[email protected]"
    }
  }
}

Response (body only)

JSON

{
  "contact": {
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    },
    "first_name": "SHERLOCK",
    "last_name": "HOLMES",
    "address1": "42 BAKER STREET",
    "address2": "",
    "address3": "",
    "address4": "",
    "city": "SEATTLE",
    "state_province": "WA",
    "country": "",
    "zip_postal_code": "98101",
    "email_address": "[email protected]",
    "input_used": "email"
  }
}

Request and response for the Contact identity attribute

Contact request parameters

Parameter	Type	Description
addons	object	This parameter allows you to receive information returned from your enabled identity attributes. Contact our Customer Support Team to add this feature.
addons.contact	object	The Contact identity attribute allows you to retrieve the name and address associated with the phone number you submit, without requesting explicit consent from your end user. Information included in the response is the first name, last name, street address, city, state (or province), country, and ZIP code.
addons.contact.email	string	The email address you want to use with Email ID. This is only available when Email ID is enabled. Contact our Customer Support Team to enable Email ID for your account and obtain the latest information on supported markets.

Contact response

Property	Type	Description	Example
reference_id	string	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.
phone_type	string	One of the phone type codes.
description	string	Text describing the phone type.
contact	object	You will only see this in your response if you used the Contact identity attribute.
contact.address1	string	The name of the street in the address of the subscriber.
contact.address2	string	Unit or suite number in the address of the subscriber.
contact.address3	string	Town, city, or state in the address of the subscriber.
contact.address4	string	Postal code in the address of the subscriber.
contact.city	string	The city in the address of the subscriber.
contact.country	string	The country in the address of the subscriber.
contact.date_of_birth	string	The date of birth of the subscriber, in {YYYY}-{MM}-{DD} format. This property is not returned by default and is only available in limited markets. Contact our Customer Support Team to obtain the latest information on supported markets and to add this property to your account.	1958-01-01
contact.first_name	string	The first name of the subscriber.
contact.id	string	The unique government-issued ID for this subscriber. This property is not returned by default and is only available in limited markets. Contact our Customer Support Team to obtain the latest information on supported markets and to add this property to your account.	300206845
contact.last_name	string	The last name of the subscriber.
contact.email_address	string	The email address of the subscriber.
contact.state_province	string	State or province in the address of the subscriber.
contact.status	object	Contains details about the delivery status of this package.
contact.status.code	string	A status or error code describing what happened after your request.
contact.status.description	string	A brief description of what the error or status code means.
contact.zip_postal_code	string	Postal code in the address of the subscriber.
contact.input_used	string	Lists whether the information retrieved is based on only a phone number or only an email or both a phone number and email. This is only returned when Email ID is enabled. Contact our Customer Support Team to enable Email ID for your account and obtain the latest information on supported markets.	phone_number and email