Contact Match

Contact Match is an optional add-on offered as part of the PhoneID API. It allows you to compare a name and address for a submitted phone number in your request with a name and address on file with the carrier and return a score referred to as a match score that tells you how close a match was found.

Match Score

A match score is a value ranging from 0-100 that tells you how close a match you have between the name and address you provide and what is on file with the carrier for submitted phone numbers. It is recommended that scores greater than or equal to 90 be considered a ‘pass’ meaning it is enough of a match for validation. If you receive a score of -1 it means the match was not available.

Info Returned by Contact Match

Contact Match is an add-on to the PhoneID API. When you use this add-on, you get back all the information you would get back from a standard PhoneID request, all the information for any other add-ons you may be using, and for Contact Match, you get back the following information:

  • first_name_score - an integer representing the match score for the first name of the contact you are looking up
  • last_name_score - an integer representing the match score for the last name of the contact you are looking up
  • address_score - an integer representing the match score for the address of the contact you are looking up
  • date_of_birth_score - an integer representing the match score for the date of birth of the person you are looking up. This is only available for phone numbers from Brazil and the UK. If you do not include the date_of_birth parameter in your request this will not come back in the results
  • status - an object containing details about the status of your request

Consent for Contact Match

In order to use the Contact Match add-on, you must obtain implicit consent from your end users. In your application/property (online platform), create a message informing your end users that by signing up for this service they accept your Terms of Service and Privacy Policy. Make it clear in the Personal Data section of your Privacy Policy that their personal data is shared with third parties including but not limited to identity verification services, service providers, government entities, utilities, public records, credit bureaus, telecomm providers, property files and watch lists. Include a statement like “By signing up for this service you acknowledge that we may disclose your name, address, email, and mobile number to third parties in connection with the processing of identity or account verification, fraud detection or as may otherwise be required by applicable law”.

Your app should include a way to present this request for consent alongside the details of what personal data you may share.

Example Request and Response for Contact Match

POST Request for Contact Match
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_match": {
            "first_name": "Peter",
            "last_name": "Petersen",
            "address": "1444 S. Alameda Street Los Angeles",
            "city": "San Jose",
            "postal_code": "95120",
            "state": "CA",
            "country": "USA",
            "date_of_birth":"1978-08-22"
        }
    }
}
Contact Match Response Body
    'contact_match': {
        'address_score': 100,
        'first_name_score': 100,
        'last_name_score': 100,
        'date_of_birth_score': 100,
        'status': {
            'code': 2800,
            'description': 'Request successfully completed.'
        }
    }
Contact Match Error Response
    "contact_match": {
        "status": {
            "code": 2806,
            "description": "contact_match add-on is not enabled.",
        }
    }
Contact Match Add-on No Match Response
    "contact_match": {
        "status": {
            "code": 2805,
            "description": "No contact_match add-on information for phone number."
        }
    }
Contact Match Add-on Out of Coverage Error Response
    "contact_match": {
        "status": {
            "code": 2803,
            "description": "Phone number out of contact_match add-on coverage."
        }
    }
Contact Match Request Parameters
object
addons
object

You must have you Technical Account Manager enable this feature for use. The addons 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.

Contact Match Response
object
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.

description
string

Text describing the phone type.

contact_match
object

You will only see this in your response if you used the contact match add-on.

Contact Match for Brazil

If you are using Contact Match for Brazil, the following rules apply:

  • You can validate first name, last name, address, and date of birth for a submitted phone number. Matching is done for the address including street name, street number, block number, apartment number, and neighborhood (bairro).
  • It is not possible to validate zip code, city, state and country.
  • The match score can come back from 0-100 to tell you how close a match you have between the name and address you provide and what is on file with the carrier for submitted phone numbers.
  • When you submit a name for the first_name parameter, it should contain only one name.
  • When you submit a name for the last_name parameter, you can include multiple names.

For example, say you want a match for someone whose full name is “LUIS CARLOS TEIXEIRA BRITO JUNIOR” and address “RUA COSTA ESMERALDA 50 BL 14 APT 22 CENTRO”.

Example for Multiple Names
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_match": {
            "first_name": "Luis",
            "last_name": "Carlos Teixeira Brito Junior",
            "address": "RUA COSTA ESMERALDA 50 BL 14 APT 22 CENTRO"
        }
    }
}
  • For address parameters, you must format the address like: “streetName[space]streetNumber[space]BL[space]blNumber[space]APT[space]aptNumber[space]neighborhoodName”

Contact Match for China

If you are using Contact Match for China, the following rules apply:

  • You can validate first name and last name for a submitted phone number and it is not possible to validate address.
  • You must provide name matching information for first_name and last_name parameters using Chinese characters.
  • You cannot match for anything besides first name, last name, and phone number, so do not provide other information in your match request.
  • The score is either all or nothing. If there is a match between the first and last name you provide and what is on file with the carrier, the score returned is 100. Otherwise, the score returned is 0.

Contact Match for Switzerland

If you are using Contact Match for Switzerland, the following rules apply:

  • You can validate for first name, last name, and address for submitted phone number.
  • When you send information for the address parameter, you should include street name and the city.
  • You cannot validate zip code and state.

Contact Match for the UK

If you are using Contact Match for the UK (Telefonica only), the following rules apply:

  • You can validate for first name, last name, date of birth, and address for a submitted phone number.
  • When you send information for the address parameter, your information should include the house name or house number.
  • For the postal_code parameter you should include the UK post code.
  • You do not need to provide other information such as city and country in your match request, it is optional.
  • The score is either all or nothing. If there is a match between first name, last name and the address you provide and what is on file with the carrier, the score returned is 100. Otherwise, the score returned is 0.