Identity Match Request

Access Endpoint URL: https://rest.everyware.com/api/v1/identity-score/identity-match [POST]

Summary

You can use the IdentityMatch method to pass a phone number (mobile/landline) and other personal information via API call to national census and credit bureau databases for verification.

The response to this method includes detailed information related to the passed phone number, as well as one of the following "Identity Match" statuses:

Full match - Indicates the first name, last name, address, city, state, and zip code provided in the request fully match a record found within the databases.
Partial match - Indicates the first name, last name, address, city, state, and zip code provided in the request partially match a record found within the databases. Partial match can occur in two scenarios:
- Matches on last name, city, state, and zip code
- Matches on first name, address, state, and zip code
No match - Indicates that the requirements for a Full or Partial Match were not met by the provided information.

🚧 Contacts Must Be Created

A valid contact will be created when the Identity Match Request API is used. You can also create a contact with the CreateCustomer method or CreateInvoice method.

🚧 Optional Contact Information

If the optional fields are not provided in the request, the information in the existing contact record will be used.

Inbound Parameters

Parameters should be passed in a single JSON-body object.

Parameter Name Description Optional/Required

phoneNumber

Phone number of payee (10-digits max, no formatting). Accepts both mobile/landline numbers.

    Example: 3055551212
  </td><td>
    Required
  </td></tr><tr><td>
    firstName
  </td><td>
    The first name of the identity match target.
  </td><td>
    Optional
  </td></tr><tr><td>
    lastName
  </td><td>
    The last name of the identity match target.
  </td><td>
    Optional
  </td></tr><tr><td>
    address1
  </td><td>
    The address of the identity match target.
  </td><td>
    Optional
  </td></tr><tr><td>
    city
  </td><td>
    The city of the identity match target.
  </td><td>
    Optional
  </td></tr><tr><td>
    state
  </td><td>
    The state of the identity match target.
  </td><td>
    Optional
  </td></tr><tr><td>
    zipCode
  </td><td>
    The zip code of the identity match target (5-digit format).
  </td><td>
    Optional
  </td></tr><tr><td>
    IncludeAllSearchResults
  </td><td>
    True/False value that determines whether all search results will be included within the response.
  </td><td>
    Optional
  </td></tr></tbody></table>

Response Parameters

Parameter Name Description

id The unique ID of the identity match request.

matchType

A value indicating the type of match.

    * 0 (No Match)  
    * 1 (Partial Match)  
    * 2 (Full Match)
  </td></tr><tr><td>
    matchedCriteria
  </td><td>
    This returns the components of the request that were matched. If the address was not confirmed, for example, the response will exclude it.  

    Example:\
    \{\
                "firstName": "SALT",\
                "lastName": "PEPPER",\
                "city": "AUSTIN",\
                "state": "TX",\
                "zipCode": "78704",\
                "phoneNumber": "512-555-1234"\
    }
  </td></tr><tr><td>
    matchComponents
  </td><td>
    This provides a full breakdown of the parameters that were matched including the name, friendly name, and match properties. See sample response for example.
  </td></tr></tbody></table>

Sample Code

{
  "phoneNumber": "3055551212",
  "firstName": "JOHN",
  "lastName": "SMITH",
  "address1": "444 SAN MARIA DRIVE",
  "city": "AUSTIN",
  "state": "TX",
  "zipCode": "78702",
  "includeAllSearchResults": false
}

curl --location 'https://rest.everyware.com/api/v1/identity-score/identity-match' \
--header 'Authorization: Basic [xxx]' \
--header 'Content-Type: application/json' \
--data-raw ' {
  "phoneNumber": "3055551212",
  "firstName": "JOHN",
  "lastName": "SMITH",
  "address1": "444 SAN MARIA DRIVE",
  "city": "AUSTIN",
  "state": "TX",
  "zipCode": "78702",
  "IncludeAllSearchResults": false
}'

{
  "Data": {
    "id": "fwt4rew2-grd3-2wer-9403-123fdsre2341",
    "matchType": 2,
    "matchedCriteria": {
    	"firstName": "JOHN",
      "lastName": "SMITH",
      "address1": "444 SAN MARIA DRIVE",
      "city": "AUSTIN",
      "state": "TX",
      "zipCode": "78702 ",
      "phoneNumber": "305-555-1212"
    },
    "matchComponents": [
      {
        "name": "firstName",
        "friendlyName": "first name",
        "matchProperties": {
       		 "resultType": "name",
       		 "lastSeen": "20240101",
       		 "rank": "0",
       		 "matchedOnProperty": "first",
       		 "data": "JOHN JACOB SMITH",
       		 "first": "JOHN",
       		 "last": "SMITH",
       		 "middle": "JACOB"
       	}
      },
      {
        "name": "lastName",
        "friendlyName": "last name",
        "matchProperties": {
          "resultType": "name",
          "lastSeen": "20240101",
          "rank": "0",
          "matchedOnProperty": "last",
          "data": "JOHN JACOB SMITH",
          "first":  "JOHN",
          "last": "SMITH",
          "middle": "JACOB"
        }
      },
      {
        "name": "address1",
        "friendlyName": "address",
        "matchProperties": {
          "resultType": "address",
          "lastSeen": "20240228",
          "rank": "0",
          "matchedOnProperty": "complete",
          "data": "444 SAN MARIA DRIVE, AUSTIN, TX 78702",
          "complete": "444 SAN MARIA DRIVE",
          "county": "HAYS"
        }
      },
      {
        "name": "city",
        "friendlyName": "city",
        "matchProperties": {
          "resultType": "address",
          "lastSeen": "20240215",
          "rank": "0",
          "matchedOnProperty": "city",
          "data": "444 SAN MARIA DRIVE",
          "city": "AUSTIN",
          "county": "HAYS"
        }
      },
      {
        "name": "state",
        "friendlyName": "state",
        "matchProperties": {
          "resultType": "address",
          "lastSeen": "20240215",
          "rank": "0",
          "matchedOnProperty": "state",
          "data": "444 SAN MARIA DRIVE",
          "state": "TX",
          "county": "HAYS"
        }
      },
      {
        "name": "zipCode",
        "friendlyName": "zip code",
        "matchProperties": {
          "resultType": "address",
          "lastSeen": "20240215",
          "rank": "0",
          "matchedOnProperty": "zip",
          "data": "444 SAN MARIA DRIVE",
          "zip": "78702",
          "county": "HAYS"
        }
      },
      {
        "name": "phoneNumber",
        "friendlyName": "mobile phone number",
        "matchProperties": {
          "resultType": "phone",
          "lastSeen": "20230404",
          "rank": "0",
          "matchedOnProperty": "number",
          "type": "Mobile",
          "number": "305-555-1212",
          "fake": "False",
          "disconnected": "False",
          "providerName": "NEW CINGULAR WRLS GA"
        }
      }
    ],
    "result": []
  },
  "IsSuccess": true,
  "Message": "The requested identity match has completed with a full match on all properties.",
}