Phone ID - Identity attributes: Contact Match

📘

NOTE:

To add this feature to your account, contact a Telesign expert. This feature is available for full-service accounts only.

The Contact Match identity attribute 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 match score that tells you how close a match was found.

Match score

The match score, ranging from 0 to 100, is an integer that tells you how close a match you have between the identity input you provided and what is on file with the carrier for the submitted phone number. We recommend that scores greater than or equal to 90 be considered a 'pass', meaning that it is enough of a match for validation. If you receive a score of None it means the match was not available.

Info returned by Contact Match

  • first_name_score - The match score for the first name of the contact.
  • last_name_score - The match score for the last name of the contact.
  • address_score - The match score for the address of the contact.
  • date_of_birth_score - 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. You must include the date_of_birth parameter in your request to get this in the response.
  • status - An object containing details about the status of your request.

Consent for Contact Match

To use the Contact Match identity attribute, 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 - success

    "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 response - error

    "contact_match": {
        "status": {
            "code": 2806,
            "description": "Contact Match identity attribute is not enabled.",
        }
    }

Contact Match response - no match

    "contact_match": {
        "status": {
            "code": 2805,
            "description": "No Contact Match identity attribute information for phone number."
        }
    }

Contact Match response - out of coverage error

   "contact_match": {
       "status": {
           "code": 2803,
           "description": "Phone number out of Contact Match identity attribute coverage."
       }
   }

Contact Match request parameters

ParameterTypeDescription
addonsobjectYou must have your Technical Account Manager enable this feature for use. Including this parameter allows you to receive information returned from your enabled identity attributes.
addons.contact_matchobjectContains the identity inputs for a contact you want to match.
addons.contact_match.first_namestringThe first name of the person you want to find a match for.
addons.contact_match.last_namestringThe last name of the person you want a match for.
addons.contact_match. addressstringThe home address of the person you want a match for.
addons.contact_match. citystringThe name of the city included in the address of the person you want to match for.
addons.contact_match.postal_codestringThe postal code included in the address of the person you want to match for.
addons.contact_match.statestringThe state included in the address you want a match for.
addons.contact_match.countrystringThe country included in the address you are requesting a match for.
addons.contact_match.date_of_birthstringAn optional parameter available only in Brazil and the UK that allows you to submit a contact’s date of birth (DOB) for a match score. The format is ISO 8601, so {YYYY}-{MM}-{DD}. Example: 1978-08-22.

Contact Match response

PropertyTypeDescription
reference_idstringA 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_typestringOne of the phone type codes.
descriptionstringText describing the phone type.
contact_matchobjectYou will only see this in your response if you used the Contact Match identity attribute.
contact_match.address_scorestringA score from 0-100 showing you how close a match the address information you sent is to what is on file. 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.
contact_match.first_name_scorestringA score from 0-100 showing you how close a match the first name information you sent is to what is on file. 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.
contact_match.last_name_scorestringA score from 0-100 showing you how close a match the last name information you sent is to what is on file. 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.
contact_match.statusobject
contact_match.status.codestringA status or error code describing what happened after your request.
contact_match.status.descriptionstringA brief description of what the error or status code means.
contact_match.date_of_birth_scorestringThis is only available for numbers from Brazil and the UK. If you included a date of birth (DOB) in your Contact Match request, you will get back a DOB score. This is a score from 0-100 showing you how close a match the date of birth information you sent is to what is on file. 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.

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 postal 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.