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

Identity search

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 Searchmaps to oneIdentity Assessment
Each Identity Recordmaps to oneEvaluation
Each Namemaps to oneName Comparison
Each Phone Numbermaps to onePhone Comparison
Each SSNmaps to oneSSN Comparison
Each Birthmaps to oneBirth Comparison
Each US Addressmaps to oneUS 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.

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

RangeMeaningExample
100Exact matchAndrew Smith and Andrew Smith
85 – 99Strong match, likely transpositionAndrew Smith and Andrew Smtih
70 – 84Possible match, likely alias or nicknameAndrew Smith and Andy Smith
50 – 69Unlikely match, likely relativeAndrew Smith and Betty Smith
0 – 49Unlikely matchAndrew Smith and Ray Charles

Phone comparison scores

RangeMeaningExample
100Exact match555-666-7777 and 555-666-7777
67 – 99Possible match, usually off by one555-666-7777 and 555-668-7777
0 – 66Unlikely match555-666-7777 and 555-888-7777

SSN comparison scores

RangeMeaningExample
100Exact match111-22-3333 and 111-22-3333
67 – 99Possible match, usually off by one111-22-3333 and 111-24-3333
0 – 66Unlikely match111-22-3333 and 111-24-3336

Birth comparison scores

ValueMeaningExample
100Exact match1990-08-23 and 1990-08-23
50Birth was off by 1 day, month or year1990-08-23 and 1989-08-23
0More than one part of the birth was off by >= 11990-08-23 and 1993-07-23

Address comparison scores

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