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
• Understanding the anatomy of an identity assessment
• Creating an identity assessment
• How to interpret the scores

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.

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.

Phone comparison scores

SSN comparison scores

Birth comparison scores

Address comparison scores