Jump to guide

Expanding Your Identity Search

Verify your customers with additional data like the SSN and date of birth allowing you to maximize automated verification rates.

Table of Contents


Bird’s-Eye View of the Flow

Sometimes Cognito can’t find the person you’re looking for when verifying with just a phone number. If that is the case, we also allow you to add the user’s full or last 4 Social Security Number or date of birth to your verification giving you the best match rates possible.

We don’t charge you if we can’t return results which allows you to progressively search for different user information until you find a match. You can alternatively also include as much information as possible when making your first request and we will automatically attempt to search by your different provided parameters to maximize match rates.

Here is an example of a standard flow that uses additional customer information as a fallback for a phone number based lookup:

General flow

Using a Social Security Number

We split the SSN into the same sections as the Social Security Administration, area, group and serial, which represent the first three, middle two and last four of the SSN, respectively. You can send us all three of area, group, and serial for the full SSN or just the serial.

Though it is not required, we highly recommend also including a name if you want to search using the SSN.

Trait Attribute Required? Notes
ssn area Yes if group is provided The length should be 3
ssn group Yes if area is provided The length should be 2
ssn serial Yes The length should be 4
POST https://sandbox.cognitohq.com/identity_searches HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Cognito-Version: 2016-09-01

{
  "data": {
    "type": "identity_search",
    "attributes": {
      "phone": {
        "number": "+16508007985"
      },
      "name": {
        "first": "Leslie",
        "last": "Knope"
      },
      "ssn": {
        "area": "111",
        "group": "22",
        "serial": "3333"
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "prf_3s527AoQo6Dw62"
        }
      }
    }
  }
}

Using a Date of Birth and Name

If you would like to search by date of birth you will need to also include the customer’s first and last name.

Trait Attribute Required? Notes
birth day Yes Integer between 1 and 31 (depending on the month)
birth month Yes Integer between 1 and 12
birth year Yes Integer between 1850 and the current year
POST https://sandbox.cognitohq.com/identity_searches HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Cognito-Version: 2016-09-01

{
  "data": {
    "type": "identity_search",
    "attributes": {
      "phone": {
        "number": "+16508007985"
      },
      "name": {
        "first": "Leslie",
        "last": "Knope"
      },
      "birth": {
        "day": 14,
        "month": 2,
        "year": 1989
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "prf_3s527AoQo6Dw62"
        }
      }
    }
  }
}

Using an Address

Trait Attribute Required? Notes
us_address street Yes String less than 100 characters
us_address city Yes String less than 100 characters
us_address subdivision Yes String in the USPS Standard.
us_address postal_code Yes String of 5 digits
POST https://sandbox.cognitohq.com/identity_searches HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Cognito-Version: 2016-09-01

{
  "data": {
    "type": "identity_search",
    "attributes": {
      "phone": {
        "number": "+16508007985"
      },
      "name": {
        "first": "Leslie",
        "last": "Knope"
      },
      "us_address": {
        "street": "123 Main St",
        "city": "New York",
        "subdivision": "NY",
        "postal_code": "10001"
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "prf_3s527AoQo6Dw62"
        }
      }
    }
  }
}

Next steps

Now that you have maximized the breadth of your verification you can read about extending your integration to help analyze and test the data.