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:


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.

TraitAttributeRequired?Notes
ssnareaYes if group is providedThe length should be 3
ssngroupYes if area is providedThe length should be 2
ssnserialYesThe 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": "+19876543212"
      },
      "name": {
        "first": "Leslie",
        "last": "Knope"
      },
      "ssn": {
        "area": "123",
        "group": "45",
        "serial": "6789"
      }
    },
    "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.

TraitAttributeRequired?Notes
birthdayYesInteger between 1 and 31 (depending on the month)
birthmonthYesInteger between 1 and 12
birthyearYesInteger 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": "+19876543212"
      },
      "name": {
        "first": "Leslie",
        "last": "Knope"
      },
      "birth": {
        "day": 18,
        "month": 1,
        "year": 1975
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "prf_3s527AoQo6Dw62"
        }
      }
    }
  }
}

Using an Address

TraitAttributeRequired?Notes
us_addressstreetYesString less than 100 characters
us_addresscityYesString less than 100 characters
us_addresssubdivisionYesString in the USPS Standard
us_addresspostal_codeYesString 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": "+19876543212"
      },
      "name": {
        "first": "Leslie",
        "last": "Knope"
      },
      "us_address": {
        "street": "123 Main St",
        "city": "Pawnee",
        "subdivision": "IN",
        "postal_code": "46001"
      }
    },
    "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.