PhoneID API - Add-ons: Contact

The Contact add-on allows you to retrieve the name, address, and other contact info associated with the subscriber for the phone number you submit, without requesting explicit consent from your end user. The information returned by this add-on includes:

  • First Name
  • Last Name
  • Street Address
  • City
  • State (or Province)
  • Country
  • ZIP Code
  • Email Address

Example

This is an example of using the PhoneID API with the Contact add-on.

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

Response (body only)

{
  "contact": {
    "address1": "2432 CHIMNEY POINT LN",
    "address2": "",
    "address3": "",
    "address4": "",
    "city": "LEXINGTON",
    "country": "",
    "first_name": "MYLA",
    "last_name": "JONES",
    "state_province": "KY",
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    },
    "zip_postal_code": "40509",
    "email_address": "[email protected]"
  }
}

Request and Response for the Contact Add-on

Contact Request Parameters

Parameter

Type

Description

addons

object

You must have your Technical Account Manager enable this feature for use. This parameter allows you to receive information returned from Contact, Contact Plus, Contact Match, or Number Deactivation, depending on which add-ons you enable. You receive add-on information back along with standard PhoneID information.

addons.contact

object

The Contact add-on 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.

Contact Response

Property

Type

Description

Example

reference_id

string

A 32-digit hex value used to identify the web service requests. 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](/docs/codes-languages-and-time-zones#section-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 add-on.

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

(Vietnam-phone numbers only). The date of birth of the subscriber, in {YYYY}-{MM}-{DD} format. This property is not returned by default; to request addition of this property contact our Customer Support Team.

1958-01-01

contact.first_name

string

The first name of the subscriber.

contact.id

string

(Vietnam-phone numbers only). The unique Vietnamese government-issued ID for this subscriber. This property is not returned by default; to request addition of this property contact our Customer Support Team.

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.


Did this page help you?