Jump to guide

Verifying Your First Customer

Learn how to build a signup flow which requires only a name and phone number to get started while still maintaining a high level of identity assurance.

Table of Contents


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:

Request

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"
  }
}

Response

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.


A basic identity search can be created with with just a phone trait or with a phone and name trait. We also support additional 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.

Request

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

Response

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": "+16508007985"
      }
    },
    "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": 2017,
            "month": 2
          },
          "latest": {
            "year": 2012,
            "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": "+16508007985"
      }
    },
    {
      "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:

Searches 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
    }
  }
}

Request

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

Response

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 your first customer! Now that you’ve completed a basic integration here are a few additional recommended resources: