ID Verification API Quickstart

Creating a profile
Creating an identity search
Checking the status of a search

Creating a profile

The first step is to create a profile which is used as a reference when performing other transactions. Each customer on your system should have their own profile. Do not share profile IDs among customers! The profile doesn’t hold any user data and is immutable, so the creation process always looks the same:

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

{
  "data": {
    "type": "profile"
  }
}

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

{
  "data": {
    "type": "profile",
    "id": "prf_3s527AoQo6Dw62",
    "attributes": {
      "created_at": "2016-04-01T13:59:59Z"
    },
    "relationships": {
      "identity_searches": {
        "links": {
          "related": "/profiles/prf_3s527AoQo6Dw62/identity_searches"
        }
      }
    }
  }
}

Make sure to grab the profile’s ID and associate it with your user account in your database for future retrieval.

Creating an identity search

A basic identity verification can be created with with just a phone trait or with a phone and name trait. We also support additional API search fields that are outlined in our Expanding Your Search guide. In this example we’ll start with just the phone trait to get a pool of potential matches and then in the next guide we will determine which of the potential matches is the best result by adding in the customer’s name.

Trait	Attribute	Required?	Notes
`phone`	`number`	Yes	Must be a string in E.164 format
`name`	`first`	Yes, if `name` is provided	Must be a string between 1 and 100 characters
`name`	`middle`	No	Must be a string between 1 and 100 characters
`name`	`last`	Yes, if `name` is provided	Must be a string between 1 and 100 characters

The identity search response will almost always be fulfilled synchronously. If a search takes longer than 5 seconds due to data source delay or failure, it will be handled asynchronously.

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"
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "prf_3s527AoQo6Dw62"
        }
      }
    }
  }
}

If the identity search is created within 5 seconds:

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

{
  "data": {
    "type": "identity_search",
    "id": "idnsch_9cLibuU8CGL5Tw",
    "attributes": {
      "created_at": "2016-04-01T13:59:59Z",
      "phone": {
        "number": "+19876543212"
      }
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profile",
          "id": "prf_3s527AoQo6Dw62"
        }
      },
      "identity_records": {
        "data": [
          {
            "type": "identity_record",
            "id": "idnrcd_4jAKBtpgUYqotf"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "identity_record",
      "id": "idnrcd_4jAKBtpgUYqotf",
      "attributes": {},
      "relationships": {
        "addresses": {
          "data": [
            {
              "type": "us_address",
              "id": "usaddr_6McNRg4HYpisQ4"
            }
          ]
        },
        "names": {
          "data": [
            {
              "type": "name",
              "id": "nam_5wwLicAvxWDyGm"
            }
          ]
        },
        "ssns": {
          "data": [
            {
              "type": "ssn",
              "id": "ssn_a29MVUXXtn1hHU"
            }
          ]
        },
        "phones": {
          "data": [
            {
              "type": "phone",
              "id": "phn_8NhXuWAD1rvYzo"
            }
          ]
        },
        "births": {
          "data": [
            {
              "type": "birth",
              "id": "bth_9SfmTjQWh6DD6n"
            }
          ]
        },
        "deaths": {
          "data": [
            {
              "type": "death",
              "id": "dth_dXzK8dDoqAR96N"
            }
          ]
        }
      }
    },
    {
      "type": "us_address",
      "id": "usaddr_6McNRg4HYpisQ4",
      "attributes": {
        "street": "1 Infinite Loop",
        "city": "Cupertino",
        "subdivision": "CA",
        "postal_code": "95014",
        "country_code": "US",
        "usage": {
          "earliest": {
            "year": 2012,
            "month": 2
          },
          "latest": {
            "year": 2017,
            "month": 9
          }
        }
      }
    },
    {
      "type": "name",
      "id": "nam_5wwLicAvxWDyGm",
      "attributes": {
        "first": "John",
        "middle": "Jacob",
        "last": "Smith"
      }
    },
    {
      "type": "ssn",
      "id": "ssn_a29MVUXXtn1hHU",
      "attributes": {
        "number": "111223333",
        "area": "111",
        "group": "22",
        "serial": "3333"
      }
    },
    {
      "type": "phone",
      "id": "phn_8NhXuWAD1rvYzo",
      "attributes": {
        "number": "+19876543212",
        "usage": {
          "earliest": {
            "year": 2012,
            "month": 2
          },
          "latest": {
            "year": 2017,
            "month": 9
          }
        }
      }
    },
    {
      "type": "birth",
      "id": "bth_9SfmTjQWh6DD6n",
      "attributes": {
        "day": 1,
        "month": 10,
        "year": 1993
      }
    },
    {
      "type": "death",
      "id": "dth_dXzK8dDoqAR96N",
      "attributes": {
        "day": 1,
        "month": 10,
        "year": 1993
      }
    }
  ]
}

If the identity search is still processing after 5 seconds:

ID verifications typically only take one or two seconds but, depending on data provider availability, in certain circumstances it can take longer. To account for this while still being fault-tolerant, if the identity search creation takes longer than 5 seconds, the search will be entered into a search queue which can be retrieved when it is complete.

If the request can not be completed synchronously, we will return a 202 Accepted response with an identity_search_job resource in the response body. The Content-Location header will provide the location where this resource should subsequently be accessed to determine if the search has completed and be redirected to the final search result.

If you would like to always use the asynchronous flow you can optionally pass us an extra header as we outline in the testing guide.

HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
Content-Location: /identity_searches/jobs/idsjob_2HLhnV3hMoaFFf

{
  "data": {
    "type": "identity_search_job",
    "id": "idsjob_2HLhnV3hMoaFFf",
    "attributes": {
      "created_at": "2016-07-18T21:24:18Z",
      "updated_at": "2016-07-18T21:24:18Z",
      "status": "processing"
    },
    "relationships": {
      "identity_search": null
    }
  }
}

Checking the status of a search

GET https://sandbox.cognitohq.com/identity_searches/jobs/idsjob_2HLhnV3hMoaFFf HTTP/1.1
Accept: application/vnd.api+json
Cognito-Version: 2016-09-01

If the identity search has completed successfully:

HTTP/1.1 303 See Other
Content-Type: application/vnd.api+json
Location: /identity_searches/idnsch_9cLibuU8CGL5Tw

{
  "data": {
    "type": "identity_search_job",
    "id": "idsjob_2HLhnV3hMoaFFf",
    "attributes": {
      "created_at": "2016-07-18T21:24:18Z",
      "updated_at": "2016-07-18T21:24:18Z",
      "status": "completed"
    },
    "relationships": {
      "identity_search": {
        "data": {
          "type": "identity_search",
          "id": "idnsch_9cLibuU8CGL5Tw"
        }
      }
    }
  }
}

If the identity search is still processing:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "identity_search_job",
    "id": "idsjob_2HLhnV3hMoaFFf",
    "attributes": {
      "created_at": "2016-07-18T21:24:18Z",
      "updated_at": "2016-07-18T21:24:18Z",
      "status": "processing"
    },
    "relationships": {
      "identity_search": null
    }
  }
}

If the identity search failed and is not scheduled for any further retries:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "identity_search_job",
    "id": "idsjob_2HLhnV3hMoaFFf",
    "attributes": {
      "created_at": "2016-07-18T21:24:18Z",
      "updated_at": "2016-07-18T21:24:18Z",
      "status": "failed"
    },
    "relationships": {
      "identity_search": null
    }
  }
}

Next steps

Congratulations on verifying the identity of your first customer! Now that you’ve completed a basic integration here are a few additional recommended resources:

In addition, if you have been granted live access and are ready to complete your integration, you may direct your requests to https://api.cognitohq.com, the production API server.

ID Verification API Quickstart

Learn how to build a signup flow which requires only a name and phone number with Cognito's real-time ID verification APIs.

Table of Contents

Creating a profile

Creating an identity search

Checking the status of a search

Next steps