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

Required

firstName

The first name of the identity match target.

Optional

lastName

The last name of the identity match target.

Optional

address1

The address of the identity match target.

Optional

city

The city of the identity match target.

Optional

state

The state of the identity match target.

Optional

zipCode

The zip code of the identity match target (5-digit format).

Optional

IncludeAllSearchResults

True/False value that determines whether all search results will be included within the response.

Optional

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)

matchedCriteria

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

matchComponents

This provides a full breakdown of the parameters that were matched including the name, friendly name, and match properties. See sample response for example.

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.",
}