Jump to guide

Assessing Your Identity Search Results

Identity assessments help you understand and evaluate identity search results. This section helps you understand and get the most out of that evaluation.

Table of Contents


How to maximize your result quality

In order you receive the best results, there are two main concepts you need to fully understand: the identity search and the identity assessment. These two concepts can be used in concert to create very powerful integrations, but understanding the separation is imperative.

  1. An identity search will populate a set of identity records associated with your search term(s).
  2. A identity assessment will take an identity search and assess the similarity of arbitrary data points you have on file with the identity search results.

Let’s say you perform an identity search for a phone number alone, Cognito will return all identities associated with that phone number. If you search for both a name and a phone number, you may only get results with both a matching phone number and name. If your use case benefits from knowing whether a name you have on file mismatches what we have on record for that phone number, then including the name in the search can be counter-productive as it will filter those results.

On the other hand, we do not charge for identity searches which return no results. Thus if you’re only interested in the case where the name and the phone match, then including a name in your identity search is preferable.

Identity assessment

The identity assessment helps you determine the relevance of each result returned by the identity search. If you initiated an identity search with only a phone number, then you can use our identity assessment to determine the most likely match with your customer, if any. The identity assessment is completely free so you can theoretically compare the names of multiple customers with the same phone number without incurring any additional cost.

Consider your use case to determine which data attributes associated with your customer should be sent to which endpoint.


Understanding the anatomy of an identity assessment

The goal of an identity assessment is to give you a granular understanding of how each piece of data you submit matches the available identity records. To achieve this we return an evaluation for every identity record in your identity search. If you get back 3 identity records, there will be 3 corresponding evaluations.

Each of these evaluations in turn has a comparison object for each field you input. So assuming you submitted a phone number and a name, then each evaluation will contain a phone_comparison and a name_comparison, respectively.

Each Identity Search maps to one Identity Assessment
Each Identity Record maps to one Evaluation
Each Name maps to one Name Comparison
Each Phone Number maps to one Phone Comparison
Each SSN maps to one SSN Comparison
Each Birth maps to one Birth Comparison
Each US Address maps to one US Address Comparison

Creating an identity assessment

To create an identity assessment, all you have to do is take your identity search from the previous guide and pass it to the identity assessment endpoint. By default, the identity assessment will take the attributes you searched with when creating an identity search and will compare them to the identity records that were returned.

You can optionally submit new attributes to the identity assessment. This will replace any and all attributes used when creating the identity search and will instead compare these new attributes with the identity records. This is useful if you created your identity search using only a phone number and would like to find the most likely match with a name.

NOTE - In the following example we override the attributes which would have otherwise been inherited from our identity search so that we can add a name, address, date of birth and last 4 of SSN to our identity assessment.

Request

POST https://sandbox.cognitohq.com/identity_assessments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Cognito-Version: 2016-09-01

{
  "data": {
    "type": "identity_assessment",
    "attributes": {
      "phone": {
        "number": "+16508007985"
      },
      "name": {
        "first": "John",
        "last": "Doe"
      },
      "birth": {
        "day": 23,
        "month": 8,
        "year": 1993
      },
      "ssn": {
        "serial": "6789"
      },
      "us_address": {
        "street": "123 Place Pl",
        "city": "St. Petersburg",
        "subdivision": "FL",
        "postal_code": "12345"
      }
    },
    "relationships": {
      "identity_search": {
        "data": {
          "type": "identity_search",
          "id": "idnsch_9cLibuU8CGL5Tw"
        }
      }
    }
  }
}

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "identity_assessment",
    "id": "idnasm_duWTbHxT7bPm8m",
    "attributes": {
      "created_at": "2017-02-14T20:28:40Z",
      "birth": {
        "year": 1993,
        "month": 8,
        "day": 23
      },
      "name": {
        "first": "John",
        "middle": "Smith",
        "last": "Doe"
      },
      "phone": {
        "number": "+16508007985"
      },
      "ssn": {
        "area": null,
        "group": null,
        "serial": "6789"
      },
      "us_address": {
        "street": "123 Place Pl",
        "city": "St. Petersburg",
        "subdivision": "FL",
        "postal_code": "12345"
      }
    },
    "relationships": {
      "identity_search": {
        "data": {
          "type": "identity_search",
          "id": "idnsch_9cLibuU8CGL5Tw"
        }
      },
      "identity_record_comparisons": {
        "data": [
          {
            "type": "identity_record_comparison",
            "id": "idrcmp_crDJME2KdzXnRp"
          },
          {
            "type": "identity_record_comparison",
            "id": "idrcmp_9k6qQmsWyQhJwV"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "identity_record_comparison",
      "id": "idrcmp_crDJME2KdzXnRp",
      "attributes": {
        "score": 25
      },
      "relationships": {
        "identity_record": {
          "data": {
            "type": "identity_record",
            "id": "idnrcd_8N6u3CVrEkXjej"
          }
        },
        "address_comparisons": {
          "data": [
            {
              "type": "us_address_comparison",
              "id":   "usacmp_bean4GxKjRXJUj"
            }
          ]
        },
        "birth_comparisons": {
          "data": [
            {
              "type": "birth_comparison",
              "id": "bthcmp_1TLzoa9oxkskjF"
            },
            {
              "type": "birth_comparison",
              "id": "bthcmp_eg575zPknRSaeF"
            },
            {
              "type": "birth_comparison",
              "id": "bthcmp_cQjp79o9xpRuhm"
            }
          ]
        },
        "phone_comparisons": {
          "data": [
            {
              "type": "phone_comparison",
              "id": "phncmp_crKB9jYr4uqwZw"
            },
            {
              "type": "phone_comparison",
              "id": "phncmp_dMS6MexxtjVrPs"
            }
          ]
        },
        "name_comparisons": {
          "data": [
            {
              "type": "name_comparison",
              "id": "namcmp_2gm1fNeajJMzCf"
            },
            {
              "type": "name_comparison",
              "id": "namcmp_9kYbPK13AW4zMW"
            }
          ]
        },
        "ssn_comparisons": {
          "data": [
            {
              "type": "ssn_comparison",
              "id": "ssncmp_baxRmyMtVYsTq2"
            },
            {
              "type": "ssn_comparison",
              "id": "ssncmp_dnM4UR61m9FBaS"
            }
          ]
        }
      }
    },
    {
      "type": "identity_record_comparison",
      "id": "idrcmp_9k6qQmsWyQhJwV",
      "attributes": {
        "score": 0
      },
      "relationships": {
        "identity_record": {
          "data": {
            "type": "identity_record",
            "id": "idnrcd_88ofL2nx3YsFgT"
          }
        },
        "birth_comparisons": {
          "data": [
            {
              "type": "birth_comparison",
              "id": "bthcmp_3UY4r5MXZfueKS"
            }
          ]
        },
        "phone_comparisons": {
          "data": [
            {
              "type": "phone_comparison",
              "id": "phncmp_d6MFXLzEWsZT58"
            }
          ]
        },
        "name_comparisons": {
          "data": [
            {
              "type": "name_comparison",
              "id": "namcmp_6HgqdkoopfCnbC"
            }
          ]
        },
        "ssn_comparisons": {
          "data": [
            {
              "type": "ssn_comparison",
              "id": "ssncmp_91vvjzPsnjtH68"
            }
          ]
        }
      }
    },
    {
      "type": "birth_comparison",
      "id": "bthcmp_1TLzoa9oxkskjF",
      "attributes": {
        "score": 0,
        "components": {
          "year": {
            "input": 1993,
            "source": 1975,
            "score": 0
          },
          "month": {
            "input": 8,
            "source": 1,
            "score": 0
          },
          "day": {
            "input": 23,
            "source": 18,
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "birth",
            "id": "bth_6uCLrmVo7K6tJA"
          }
        }
      }
    },
    {
      "type": "birth_comparison",
      "id": "bthcmp_eg575zPknRSaeF",
      "attributes": {
        "score": 0,
        "components": {
          "year": {
            "input": 1993,
            "source": 1975,
            "score": 0
          },
          "month": {
            "input": 8,
            "source": null,
            "score": null
          },
          "day": {
            "input": 23,
            "source": null,
            "score": null
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "birth",
            "id": "bth_cvTAFLuWoCawju"
          }
        }
      }
    },
    {
      "type": "birth_comparison",
      "id": "bthcmp_cQjp79o9xpRuhm",
      "attributes": {
        "score": 0,
        "components": {
          "year": {
            "input": 1993,
            "source": 1976,
            "score": 0
          },
          "month": {
            "input": 8,
            "source": 1,
            "score": 0
          },
          "day": {
            "input": 23,
            "source": 18,
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "birth",
            "id": "bth_aVrJneUNk4mEkJ"
          }
        }
      }
    },
    {
      "type": "birth_comparison",
      "id": "bthcmp_3UY4r5MXZfueKS",
      "attributes": {
        "score": 0,
        "components": {
          "year": {
            "input": 1993,
            "source": 1974,
            "score": 0
          },
          "month": {
            "input": 8,
            "source": 11,
            "score": 0
          },
          "day": {
            "input": 23,
            "source": 14,
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "birth",
            "id": "bth_4Johvbanc6wxKm"
          }
        }
      }
    },
    {
      "type": "phone_comparison",
      "id": "phncmp_crKB9jYr4uqwZw",
      "attributes": {
        "score": 0,
        "components": {
          "number": {
            "input": "+16508007985",
            "source": "+11236547890",
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "phone",
            "id": "phn_8bTXfgQYQ6Y5Ua"
          }
        }
      }
    },
    {
      "type": "phone_comparison",
      "id": "phncmp_dMS6MexxtjVrPs",
      "attributes": {
        "score": 0,
        "components": {
          "number": {
            "input": "+16508007985",
            "source": "+19876543212",
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "phone",
            "id": "phn_fciTkF4p9gJNi1"
          }
        }
      }
    },
    {
      "type": "phone_comparison",
      "id": "phncmp_d6MFXLzEWsZT58",
      "attributes": {
        "score": 0,
        "components": {
          "number": {
            "input": "+16508007985",
            "source": "+11122334455",
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "phone",
            "id": "phn_3tT13naeuXNYM9"
          }
        }
      }
    },
    {
      "type": "name_comparison",
      "id": "namcmp_2gm1fNeajJMzCf",
      "attributes": {
        "score": 0,
        "components": {
          "first": {
            "input": "John",
            "source": "LESLIE",
            "score": 0
          },
          "middle": {
            "input": "Smith",
            "source": "BARBARA",
            "score": 0
          },
          "last": {
            "input": "Doe",
            "source": "KNOPE",
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "name",
            "id": "nam_crtk1qPyAbTYmX"
          }
        }
      }
    },
    {
      "type": "name_comparison",
      "id": "namcmp_9kYbPK13AW4zMW",
      "attributes": {
        "score": 0,
        "components": {
          "first": {
            "input": "John",
            "source": "LESLIE",
            "score": 0
          },
          "middle": {
            "input": "Smith",
            "source": null,
            "score": null
          },
          "last": {
            "input": "Doe",
            "source": "KNOPE-WYATT",
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "name",
            "id": "nam_5UCYY5d9y9Nyr2"
          }
        }
      }
    },
    {
      "type": "name_comparison",
      "id": "namcmp_6HgqdkoopfCnbC",
      "attributes": {
        "score": 0,
        "components": {
          "first": {
            "input": "John",
            "source": "BEN",
            "score": 0
          },
          "middle": {
            "input": "Smith",
            "source": null,
            "score": null
          },
          "last": {
            "input": "Doe",
            "source": "WYATT",
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "name",
            "id": "nam_e94dpcsZ1xwyx3"
          }
        }
      }
    },
    {
      "type": "ssn_comparison",
      "id": "ssncmp_baxRmyMtVYsTq2",
      "attributes": {
        "score": 0,
        "components": {
          "area": {
            "input": null,
            "source": "123",
            "score": null
          },
          "group": {
            "input": null,
            "source": "45",
            "score": null
          },
          "serial": {
            "input": "6789",
            "source": "6788",
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "ssn",
            "id": "ssn_6ZBagXndCJv13R"
          }
        }
      }
    },
    {
      "type": "ssn_comparison",
      "id": "ssncmp_dnM4UR61m9FBaS",
      "attributes": {
        "score": 100,
        "components": {
          "area": {
            "input": null,
            "source": "123",
            "score": null
          },
          "group": {
            "input": null,
            "source": "45",
            "score": null
          },
          "serial": {
            "input": "6789",
            "source": "6789",
            "score": 100
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "ssn",
            "id": "ssn_5xqi9EQJ2hp56V"
          }
        }
      }
    },
    {
      "type": "ssn_comparison",
      "id": "ssncmp_91vvjzPsnjtH68",
      "attributes": {
        "score": 0,
        "components": {
          "area": {
            "input": null,
            "source": "987",
            "score": null
          },
          "group": {
            "input": null,
            "source": "65",
            "score": null
          },
          "serial": {
            "input": "6789",
            "source": "4321",
            "score": 0
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "ssn",
            "id": "ssn_4pLst9cqXuXZDH"
          }
        }
      }
    },
    {
      "type": "us_address_comparison",
      "id":   "usacmp_bean4GxKjRXJUj",
      "attributes": {
        "score": 100,
        "components": {
          "street": {
            "input": "123 Place Pl",
            "source": "123 Place Pl",
            "score": 100
          },
          "city": {
            "input": "St. Petersburg",
            "source": "St. Petersburg",
            "score": 100
          },
          "subdivision": {
            "input": "FL",
            "source": "FL",
            "score": 100
          },
          "postal_code": {
            "input": "12345",
            "source": "12345",
            "score": 100
          }
        }
      },
      "relationships": {
        "source_record": {
          "data": {
            "type": "us_address",
            "id":   "usaddr_11111111111111"
          }
        }
      }
    }
  ]
}

Notice that no middle name was included in the attributes. Because of this, the middle name’s corresponding name comparison contains a null score value as there was nothing to compare against. Additionally the input is shown as null.

Similarly, if the middle name was provided in the search but not provided by a data provider then the source value would be null along with the score.


How to interpret the scores

Name comparison scores

Name scores are determined using a significantly modified Damerau–Levenshtein edit distance algorithm with additional handling for cases such as double-barrelled names. Below is a basic interpretation of the top level score of a name comparison.

Range Meaning Example
100 Exact match Andrew Smith and Andrew Smith
85 - 99 Strong match, likely transposition Andrew Smith and Andrew Smtih
70 - 84 Possible match, likely alias or nickname Andrew Smith and Andy Smith
50 - 69 Unlikely match, likely relative Andrew Smith and Betty Smith
0 - 49 Unlikely match Andrew Smith and Ray Charles

Phone comparison scores

Range Meaning Example
100 Exact match 555-666-7777 and 555-666-7777
67 - 99 Possible match, usually off by one 555-666-7777 and 555-668-7777
0 - 66 Unlikely match 555-666-7777 and 555-888-7777

SSN comparison scores

Range Meaning Example
100 Exact match 111-22-3333 and 111-22-3333
67 - 99 Possible match, usually off by one 111-22-3333 and 111-24-3333
0 - 66 Unlikely match 111-22-3333 and 111-24-3336

Birth comparison scores

Value Meaning Example
100 Exact match 1990-08-23 and 1990-08-23
50 Birth was off by 1 day, month or year 1990-08-23 and 1989-08-23
0 More than one part of the birth was off by >= 1 1990-08-23 and 1993-07-23

Address comparison scores

Value Meaning Example
100 Exact match 123 Main St, New York NY 10001 and 123 Main St, New York NY 10001
80 - 99 Likely match, likely missing unit number 123 Main St, New York NY 10001 Apt 5 and 123 Main St, New York NY 10001
67 - 79 Possible match, different house or street number 123 Main St, New York NY 10001 and 5 Main St, New York NY 10001
0 - 66 Unlikely match 123 Main St, New York NY 10001 and 4 South St, Mountain View CA 94041