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 80 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

• 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. You must include the date_of_birth parameter in your request to get this in the response. This is only available for phone numbers from certain markets. Please contact our Customer Support Team for more information.
• status - An object containing details about the status of your request.

Consent

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.

Email ID feature

The Email ID feature of the Contact Match identity attribute taps into mobile and email digital identity datasets, increasing the accuracy of the match score that is returned with Contact Match because it uses a dual-layered approach to digital identification.

📘

NOTE:

The Email ID feature of Contact 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 Match

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_match": {
            "first_name": "SHERLOCK",
            "last_name": "HOLMES",
            "address": "42 BAKER STREET",
            "city": "SEATTLE",
            "postal_code": "98101",
            "state": "WA",
            "country": "US",
            "date_of_birth":"1954-01-06T00:00:00Z"
        }
    }
}

Response 1 - success

{
  "contact_match": {
    "address_score": 53,
    "first_name_score": 43,
    "last_name_score": 66,
    "date_of_birth_score": null,
    "status": {
      "code": 2800,
      "description": "Request successfully completed."
    }
  }
}

Response 2 - error

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

Response 3 - no match

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

Response 4 - out of coverage error

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

Example: Contact Match with Email ID feature enabled

Request

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_match": {
      "first_name": "SHERLOCK",
      "email": "[email protected]",
      "last_name": "HOLMES",
      "address": "42 BAKER STREET",
      "city": "SEATTLE",
      "postal_code": "98101",
      "state": "WA",
      "country": "US",
      "date_of_birth": "1954-01-06T00:00:00Z"
    }
  }
}

Response - Success

{
  "contact_match": {
    "status": {
      "code": 2800,
      "description": "Request successfully completed."
    },
    "first_name_score": 43,
    "last_name_score": 66,
    "address_score": 53,
    "date_of_birth_score": 58,
    "input_used": "email" 
  }
}

Contact Match schema

Request

Response