Introduction

Before you use this guide: This is currently the API reference exclusively for our Flow and Screening products. We have not yet added our Identity product to this reference. If you're looking for our Identity product docs, you can find them here: https://cognitohq.com/docs.

The Cognito API is a comprehensive set of systems for verifying and screening customers for KYC, compliance, anti-fraud, and more.

For your convenience, we generate language-specific API wrappers that make integration easier. We also provide a test mode which lets you run as many test API calls as you'd like while integrating without incurring any costs.

If you ever have any trouble while integrating, please visit our support page or send an email to our support. Good luck!

OpenAPI specification:Download

Just getting started?

Check out our development quick start guide.

Base Url
https://api.cognitohq.com
Sandbox Url
https://sandbox.cognitohq.com

Authentication

All requests to the Cognito servers must be authenticated. Cognito uses a request signature system that is formed according to Section 3 in “Signing HTTP Messages. This authentication method provides a multitude of benefits including only requiring you to transmit one of your two secrets over the wire.

You can learn about how to authenticate using our Authentication Guide.


Identity

The identity product is not in the API reference, please see the API guides for integration instructions.


Screenings

To check your human customer against various sanction and PEP lists, create a screening. This set of endpoints allows you to update previously created screenings for use with ongoing screening, see past versions of a screening profile, view any hits associated with the screening, and create and view reviews regarding past hits.

List Screenings

List all screenings belonging to a particular Program, optionally filtering by customer_reference or assignee and status.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Query Parameters

program_idrequiredstring

Filters the results by the ID of the program the screenings belong to.

statusoptionalstring

Filters the results by the review status of the screening. When present, customer_reference is not allowed.

Possible enum values

rejectedpending_reviewcleared

assigneeoptionalstring

Filters the results by the user ID of the user assigned to this screening. May only be provided when status is present.

customer_referenceoptionalstring

Filters the results by the customer reference. When present, status and assignee are not allowed.

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of individual watchlist screenings

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated screening.

search_termsalways presentobject

View in sample
JSON

Search terms for creating an individual watchlist screening

Hide child attributes

program_idalways presentstring

View in sample
JSON

ID of the associated program.

namealways presentstring

View in sample
JSON

The legal name of the individual being screened.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

documentalways presentstringNULLABLE

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

locationalways presentstringNULLABLE

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

GET

/screenings

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "scr_52xR9LKo77r1Np",
5      "search_terms": {
6        "program_id": "prg_2eRPsDnL66rZ7H",
7        "name": "Aleksey Potemkin",
8        "date_of_birth": "1990-05-29",
9        "document": "C31195855",
10        "location": "US",
11        "version": 1
12      },
13      "assignee": "usr_1SUuwqBdK75GKi",
14      "status": "cleared",
15      "customer_reference": "your-db-id-3b24110",
16      "audit_trail": {
17        "source": "dashboard",
18        "user_id": "usr_1SUuwqBdK75GKi",
19        "timestamp": "2020-07-24T03:26:02Z"
20      }
21    }
22  ],
23  "links": {
24    "previous": "http://cognitohq.com",
25    "next": "http://cognitohq.com"
26  }
27}

Create Screening

Create a new screening to check your customer against watchlists defined in the associated Program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Request Body

search_termsrequiredobject

View in sample
JSON

Search inputs for creating a watchlist screening

Hide child attributes

search_terms.program_idrequiredstring

View in sample
JSON

ID of the associated program.

search_terms.namerequiredstring

View in sample
JSON

The legal name of the individual being screened.

search_terms.date_of_birthoptionalstring

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

search_terms.documentoptionalstring

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

search_terms.locationoptionalstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

customer_referenceoptionalstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated screening.

search_termsalways presentobject

View in sample
JSON

Search terms for creating an individual watchlist screening

Hide child attributes

program_idalways presentstring

View in sample
JSON

ID of the associated program.

namealways presentstring

View in sample
JSON

The legal name of the individual being screened.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

documentalways presentstringNULLABLE

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

locationalways presentstringNULLABLE

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

POST

/screenings

1{
2  "search_terms": {
3    "program_id": "prg_2eRPsDnL66rZ7H",
4    "name": "Aleksey Potemkin",
5    "date_of_birth": "1990-05-29",
6    "document": "C31195855",
7    "location": "US"
8  },
9  "customer_reference": "your-db-id-3b24110"
10}
Response Sample
Copy JSON
1{
2  "id": "scr_52xR9LKo77r1Np",
3  "search_terms": {
4    "program_id": "prg_2eRPsDnL66rZ7H",
5    "name": "Aleksey Potemkin",
6    "date_of_birth": "1990-05-29",
7    "document": "C31195855",
8    "location": "US",
9    "version": 1
10  },
11  "assignee": "usr_1SUuwqBdK75GKi",
12  "status": "cleared",
13  "customer_reference": "your-db-id-3b24110",
14  "audit_trail": {
15    "source": "dashboard",
16    "user_id": "usr_1SUuwqBdK75GKi",
17    "timestamp": "2020-07-24T03:26:02Z"
18  }
19}

Retrieve Screening

Get the current state of a specific screening.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the screening to retrieve.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated screening.

search_termsalways presentobject

View in sample
JSON

Search terms for creating an individual watchlist screening

Hide child attributes

program_idalways presentstring

View in sample
JSON

ID of the associated program.

namealways presentstring

View in sample
JSON

The legal name of the individual being screened.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

documentalways presentstringNULLABLE

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

locationalways presentstringNULLABLE

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

GET

/screenings/{id}

Response Sample
Copy JSON
1{
2  "id": "scr_52xR9LKo77r1Np",
3  "search_terms": {
4    "program_id": "prg_2eRPsDnL66rZ7H",
5    "name": "Aleksey Potemkin",
6    "date_of_birth": "1990-05-29",
7    "document": "C31195855",
8    "location": "US",
9    "version": 1
10  },
11  "assignee": "usr_1SUuwqBdK75GKi",
12  "status": "cleared",
13  "customer_reference": "your-db-id-3b24110",
14  "audit_trail": {
15    "source": "dashboard",
16    "user_id": "usr_1SUuwqBdK75GKi",
17    "timestamp": "2020-07-24T03:26:02Z"
18  }
19}

Update Screening

Update a specific screening. This endpoint can be used to add additional customer information, correct outdated information, add a reference id, assign the individual to a reviewer, and update which Program it is associated with. Please note that you may not update search_terms and status at the same time since editing search_terms may trigger an automatic status change.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the screening to retrieve.

Request Body

watchlist_screening_idrequiredstring

View in sample
JSON

ID of the associated screening.

search_termsoptionalobject

View in sample
JSON

Search terms for editing an individual watchlist screening

Hide child attributes

search_terms.program_idoptionalstring

View in sample
JSON

ID of the associated program.

search_terms.nameoptionalstring

View in sample
JSON

The legal name of the individual being screened.

search_terms.date_of_birthoptionalstring

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

search_terms.documentoptionalstring

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

search_terms.locationoptionalstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

assigneeoptionalstringNULLABLE

View in sample
JSON

statusoptionalstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referenceoptionalstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated screening.

search_termsalways presentobject

View in sample
JSON

Search terms for creating an individual watchlist screening

Hide child attributes

program_idalways presentstring

View in sample
JSON

ID of the associated program.

namealways presentstring

View in sample
JSON

The legal name of the individual being screened.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

documentalways presentstringNULLABLE

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

locationalways presentstringNULLABLE

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

Webhooks
POSTscreening.status.updated

Receive a webhook whenever a screening status changes, such as done manually via the dashboard or during ongoing monitoring. Contact support to try this feature.

idalways presentstring

ID of the associated webhook event.

timestampalways presentstring

The time that the event happened.

eventalways presentstring

The type of event this webhook describes.

dataalways presentobject

environmentalways presentstring

Environment from which the webhook was sent.

Possible enum values

sandboxlive
PATCH

/screenings/{id}

1{
2  "watchlist_screening_id": "scr_52xR9LKo77r1Np",
3  "search_terms": {
4    "program_id": "prg_2eRPsDnL66rZ7H",
5    "name": "Aleksey Potemkin",
6    "date_of_birth": "1990-05-29",
7    "document": "C31195855",
8    "location": "US"
9  },
10  "assignee": "usr_1SUuwqBdK75GKi",
11  "status": "cleared",
12  "customer_reference": "your-db-id-3b24110"
13}
Response Sample
Copy JSON
1{
2  "id": "scr_52xR9LKo77r1Np",
3  "search_terms": {
4    "program_id": "prg_2eRPsDnL66rZ7H",
5    "name": "Aleksey Potemkin",
6    "date_of_birth": "1990-05-29",
7    "document": "C31195855",
8    "location": "US",
9    "version": 1
10  },
11  "assignee": "usr_1SUuwqBdK75GKi",
12  "status": "cleared",
13  "customer_reference": "your-db-id-3b24110",
14  "audit_trail": {
15    "source": "dashboard",
16    "user_id": "usr_1SUuwqBdK75GKi",
17    "timestamp": "2020-07-24T03:26:02Z"
18  }
19}

List Screening History

List all changes to the screening in reverse-chronological order. If the screening has not been edited, no history will be returned.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the screening to retrieve past versions of.

Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of individual watchlist screenings

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated screening.

search_termsalways presentobject

View in sample
JSON

Search terms for creating an individual watchlist screening

Hide child attributes

program_idalways presentstring

View in sample
JSON

ID of the associated program.

namealways presentstring

View in sample
JSON

The legal name of the individual being screened.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

documentalways presentstringNULLABLE

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

locationalways presentstringNULLABLE

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

GET

/screenings/{id}/history

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "scr_52xR9LKo77r1Np",
5      "search_terms": {
6        "program_id": "prg_2eRPsDnL66rZ7H",
7        "name": "Aleksey Potemkin",
8        "date_of_birth": "1990-05-29",
9        "document": "C31195855",
10        "location": "US",
11        "version": 1
12      },
13      "assignee": "usr_1SUuwqBdK75GKi",
14      "status": "cleared",
15      "customer_reference": "your-db-id-3b24110",
16      "audit_trail": {
17        "source": "dashboard",
18        "user_id": "usr_1SUuwqBdK75GKi",
19        "timestamp": "2020-07-24T03:26:02Z"
20      }
21    }
22  ],
23  "links": {
24    "previous": "http://cognitohq.com",
25    "next": "http://cognitohq.com"
26  }
27}

List Reviews

List all Reviews belonging to a particular screening.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the screening being reviewed.

Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of screening reviews

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated review.

confirmed_hitsalways presentarray of strings

View in sample
JSON

Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

dismissed_hitsalways presentarray of strings

View in sample
JSON

Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

commentalways presentstringNULLABLE

View in sample
JSON

A comment submitted by a team member as part of reviewing a watchlist screening.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

GET

/screenings/{id}/reviews

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "rev_aCLNRxK3UVzn2r",
5      "confirmed_hits": [
6        "scrhit_52xR9LKo77r1Np"
7      ],
8      "dismissed_hits": [
9        "scrhit_52xR9LKo77r1Np"
10      ],
11      "comment": "These look like legitimate matches, rejecting the customer.",
12      "audit_trail": {
13        "source": "dashboard",
14        "user_id": "usr_1SUuwqBdK75GKi",
15        "timestamp": "2020-07-24T03:26:02Z"
16      }
17    }
18  ],
19  "links": {
20    "previous": "http://cognitohq.com",
21    "next": "http://cognitohq.com"
22  }
23}

Create Review

Create a new Review of a particular screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by the Cognito system.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the screening being reviewed.

Request Body

confirmed_hitsrequiredarray of strings

View in sample
JSON

Hits to mark as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

dismissed_hitsrequiredarray of strings

View in sample
JSON

Hits to mark as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

commentoptionalstring

View in sample
JSON

A comment submitted by a team member as part of reviewing a watchlist screening.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated review.

confirmed_hitsalways presentarray of strings

View in sample
JSON

Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

dismissed_hitsalways presentarray of strings

View in sample
JSON

Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

commentalways presentstringNULLABLE

View in sample
JSON

A comment submitted by a team member as part of reviewing a watchlist screening.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

POST

/screenings/{id}/reviews

1{
2  "confirmed_hits": [
3    "scrhit_52xR9LKo77r1Np"
4  ],
5  "dismissed_hits": [
6    "scrhit_52xR9LKo77r1Np"
7  ],
8  "comment": "These look like legitimate matches, rejecting the customer."
9}
Response Sample
Copy JSON
1{
2  "id": "rev_aCLNRxK3UVzn2r",
3  "confirmed_hits": [
4    "scrhit_52xR9LKo77r1Np"
5  ],
6  "dismissed_hits": [
7    "scrhit_52xR9LKo77r1Np"
8  ],
9  "comment": "These look like legitimate matches, rejecting the customer.",
10  "audit_trail": {
11    "source": "dashboard",
12    "user_id": "usr_1SUuwqBdK75GKi",
13    "timestamp": "2020-07-24T03:26:02Z"
14  }
15}

List Screening Hits

Retrieve a list of all screening hits associated with this screening. screening hits are potential watchlist matches found by the Cognito system based on the profile information entered on the associated screening.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the screening to retrieve hits for.

Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of individual watchlist screening hits

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated screening hit.

review_statusalways presentstring

View in sample
JSON

The current state of review. All screening hits and entity screening hits begin in a pending_review state but can be changed by creating a Review/EntityReview. When a hit is in the pending_review state, it will always show the latest version of the watchlist data Cognito has available and be compared against the latest customer information saved in the screening/entity screening. Once a hit has been marked as confirmed or dismissed it will no longer be updated so that the state is as it was when the review was first conducted.

Possible enum values

confirmedpending_reviewdismissed

first_activealways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

inactive_sincealways presentstringNULLABLE

View in sample
JSON

If a hit no longer matches current Program thresholds due to changes in program configuration or updates to the source data, this timestamp will be set to when it was discovered to no longer match. NOTE: This timestamp will be updated even after a hit has been confirmed or dismissed.

An ISO8601 formatted timestamp.

historical_sincealways presentstringNULLABLE

View in sample
JSON

If a hit is not currently part of a source list, this timestamp will show when the removal was discovered. NOTE: This timestamp will be updated even after a hit has been confirmed or dismissed.

An ISO8601 formatted timestamp.

list_codealways presentstring

View in sample
JSON

Shorthand identifier for a specific screening list for individuals.

Possible enum values

AU_CONCA_CONEU_CONIZ_CIAIZ_IPLIZ_PEPIZ_UNCIZ_WBKUK_HMCUS_DPLUS_DTCUS_FBIUS_FSEUS_ISNUS_MBSUS_PLCUS_SDNUS_SSISG_SOFTR_TWLTR_DFDTR_FORTR_WMDTR_CMB

cognito_uidalways presentstring

View in sample
JSON

A universal identifier for a watchlist individual that is stable across searches and updates.

source_uidalways presentstringNULLABLE

View in sample
JSON

The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is null.

The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is null.

analysismight be omittedobject

View in sample
JSON

Analysis information describing why a screening hit matched the provided user information

Hide child attributes

dates_of_birthmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

documentsmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

locationsmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

namesmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

search_terms_versionalways presentnumber

View in sample
JSON

The version of the screening's search_terms that were compared when the screening hit was added. screening hits are immutable once they have been reviewed. If changes are detected due to updates to the screening's search_terms, the associated program, or the list's source data prior to review, the screening hit will be updated to reflect those changes.

datamight be omittedobject

View in sample
JSON

Information associated with the watchlist hit

Hide child attributes

dates_of_birthmight be omittedarray of objects

View in sample
JSON

Dates of birth associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

A date range with a start and end date

Hide child attributes

beginningalways presentstring

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

endingalways presentstring

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

documentsmight be omittedarray of objects

View in sample
JSON

Documents associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

An official document, usually issued by a governing body or institution, with an associated identifier.

Hide child attributes

typealways presentstring

View in sample
JSON

The kind of official document represented by this object.

  • birth_certificate - A certificate of birth
  • drivers_license - A license to operate a motor vehicle
  • immigration_number - Immigration or residence documents
  • military_id - Identification issued by a military group
  • other - Any document not covered by other categories
  • passport - An official passport issue by a government
  • personal_identification - Any generic personal identification that is not covered by other categories
  • ration_card - Identification that entitles the holder to rations
  • ssn - United States Social Security Number
  • student_id - Identification issued by an educational institution
  • tax_id - Identification issued for the purpose of collecting taxes
  • travel_document - Visas, entry permits, refugee documents, etc.
  • voter_id - Identification issued for the purpose of voting

Possible enum values

birth_certificatedrivers_licenseimmigration_numbermilitary_idotherpassportpersonal_identificationration_cardssnstudent_idtax_idtravel_documentvoter_id

valuealways presentstring

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

locationsmight be omittedarray of objects

View in sample
JSON

Locations associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

Location information for the associated individual watchlist hit

Hide child attributes

fullalways presentstring

View in sample
JSON

The full location string, potentially including elements like street, city, postal codes and country codes. Note that this is not necessarily a complete or well-formatted address.

country_codealways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

namesmight be omittedarray of objects

View in sample
JSON

Names associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

Name information for the associated individual watchlist hit

Hide child attributes

fullalways presentstring

View in sample
JSON

The full name of the individual, including all parts.

primaryalways presentboolean

View in sample
JSON

Primary names are those most commonly used to refer to this person. Only one name will ever be marked as primary.

weak_alias_determinationalways presentstring

View in sample
JSON

Names that are explicitly marked as low quality either by their source list, or by cognito by a series of additional checks done by Cognito. Cognito does not ever surface a hit as a result of a weak name alone. If a name has no quality issues, this value will be none.

Possible enum values

nonesourcecognito
GET

/screenings/{id}/hits

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "scrhit_52xR9LKo77r1Np",
5      "review_status": "pending_review",
6      "first_active": "2020-07-24T03:26:02Z",
7      "inactive_since": "2020-07-24T03:26:02Z",
8      "historical_since": "2020-07-24T03:26:02Z",
9      "list_code": "US_SDN",
10      "cognito_uid": "uid_3NggckTimGSJHS",
11      "source_uid": "26192ABC",
12      "analysis": {
13        "dates_of_birth": "match",
14        "documents": "match",
15        "locations": "match",
16        "names": "match",
17        "search_terms_version": 1
18      },
19      "data": {
20        "dates_of_birth": [
21          {
22            "analysis": {
23              "summary": "match"
24            },
25            "data": {
26              "beginning": "1990-05-29",
27              "ending": "1990-05-29"
28            }
29          }
30        ],
31        "documents": [
32          {
33            "analysis": {
34              "summary": "match"
35            },
36            "data": {
37              "type": "passport",
38              "value": "C31195855"
39            }
40          }
41        ],
42        "locations": [
43          {
44            "analysis": {
45              "summary": "match"
46            },
47            "data": {
48              "full": "Florida, US",
49              "country_code": "US"
50            }
51          }
52        ],
53        "names": [
54          {
55            "analysis": {
56              "summary": "match"
57            },
58            "data": {
59              "full": "Aleksey Potemkin",
60              "primary": true,
61              "weak_alias_determination": "none"
62            }
63          }
64        ]
65      }
66    }
67  ],
68  "links": {
69    "previous": "http://cognitohq.com",
70    "next": "http://cognitohq.com"
71  }
72}

Programs

Programs help you to define the settings and workflows for conducting screenings in your organization. For example, you can define match sensitivities, which lists are being screened, and the behavior of ongoing re-scans.

List Programs

List all Programs associated with your account. As a note, programs may only be created via the dashboard.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of individual watchlist screening programs

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated program.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

enabledalways presentboolean

View in sample
JSON

Indicator specifying whether the program is enabled and will perform daily rescans.

lists_enabledalways presentarray of strings

View in sample
JSON

Watchlists enabled for the associated program

Possible enum values

AU_CONCA_CONEU_CONIZ_CIAIZ_IPLIZ_PEPIZ_UNCIZ_WBKUK_HMCUS_DPLUS_DTCUS_FBIUS_FSEUS_ISNUS_MBSUS_PLCUS_SDNUS_SSISG_SOFTR_TWLTR_DFDTR_FORTR_WMDTR_CMB

namealways presentstring

View in sample
JSON

A name for the program to define its purpose. For example, "High Risk Individuals", "US Cardholders", or "Applicants".

name_sensitivityalways presentstring

View in sample
JSON

The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity.

  • coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review.
  • balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise.
  • strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations.
  • exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case.

Possible enum values

coarsebalancedstrictexact

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

archivedalways presentboolean

View in sample
JSON

Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.

date_of_birth_filtermight be omittedobject

View in sample
JSON
Hide child attributes

date_of_birth_filter_enabledalways presentboolean

View in sample
JSON

date_of_birth_filter_approximatealways presentboolean

View in sample
JSON

date_of_birth_filter_typo_correctionalways presentboolean

View in sample
JSON

requirementsmight be omittedobject

View in sample
JSON
Hide child attributes

review_all_hitsmight be omittedboolean

View in sample
JSON

secondary_review_requiredalways presentstring

View in sample
JSON

Possible enum values

neverwhen_clearingwhen_rejectingalways

prefer_escalationalways presentboolean

View in sample
JSON

assignment_strategymight be omittedstring

View in sample
JSON

Possible enum values

randomdisabled
GET

/programs

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "prg_2eRPsDnL66rZ7H",
5      "created_at": "2020-07-24T03:26:02Z",
6      "enabled": true,
7      "lists_enabled": [
8        "US_SDN"
9      ],
10      "name": "Sample Program",
11      "name_sensitivity": "balanced",
12      "audit_trail": {
13        "source": "dashboard",
14        "user_id": "usr_1SUuwqBdK75GKi",
15        "timestamp": "2020-07-24T03:26:02Z"
16      },
17      "archived": true,
18      "date_of_birth_filter": {
19        "date_of_birth_filter_enabled": true,
20        "date_of_birth_filter_approximate": true,
21        "date_of_birth_filter_typo_correction": true
22      },
23      "requirements": {
24        "review_all_hits": true,
25        "secondary_review_required": "never",
26        "prefer_escalation": true
27      },
28      "assignment_strategy": "random"
29    }
30  ],
31  "links": {
32    "previous": "http://cognitohq.com",
33    "next": "http://cognitohq.com"
34  }
35}

Retrieve Program

Retrieve a specific Program for review.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the Program to retrieve.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated program.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

enabledalways presentboolean

View in sample
JSON

Indicator specifying whether the program is enabled and will perform daily rescans.

lists_enabledalways presentarray of strings

View in sample
JSON

Watchlists enabled for the associated program

Possible enum values

AU_CONCA_CONEU_CONIZ_CIAIZ_IPLIZ_PEPIZ_UNCIZ_WBKUK_HMCUS_DPLUS_DTCUS_FBIUS_FSEUS_ISNUS_MBSUS_PLCUS_SDNUS_SSISG_SOFTR_TWLTR_DFDTR_FORTR_WMDTR_CMB

namealways presentstring

View in sample
JSON

A name for the program to define its purpose. For example, "High Risk Individuals", "US Cardholders", or "Applicants".

name_sensitivityalways presentstring

View in sample
JSON

The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity.

  • coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review.
  • balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise.
  • strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations.
  • exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case.

Possible enum values

coarsebalancedstrictexact

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

archivedalways presentboolean

View in sample
JSON

Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.

date_of_birth_filtermight be omittedobject

View in sample
JSON
Hide child attributes

date_of_birth_filter_enabledalways presentboolean

View in sample
JSON

date_of_birth_filter_approximatealways presentboolean

View in sample
JSON

date_of_birth_filter_typo_correctionalways presentboolean

View in sample
JSON

requirementsmight be omittedobject

View in sample
JSON
Hide child attributes

review_all_hitsmight be omittedboolean

View in sample
JSON

secondary_review_requiredalways presentstring

View in sample
JSON

Possible enum values

neverwhen_clearingwhen_rejectingalways

prefer_escalationalways presentboolean

View in sample
JSON

assignment_strategymight be omittedstring

View in sample
JSON

Possible enum values

randomdisabled
GET

/programs/{id}

Response Sample
Copy JSON
1{
2  "id": "prg_2eRPsDnL66rZ7H",
3  "created_at": "2020-07-24T03:26:02Z",
4  "enabled": true,
5  "lists_enabled": [
6    "US_SDN"
7  ],
8  "name": "Sample Program",
9  "name_sensitivity": "balanced",
10  "audit_trail": {
11    "source": "dashboard",
12    "user_id": "usr_1SUuwqBdK75GKi",
13    "timestamp": "2020-07-24T03:26:02Z"
14  },
15  "archived": true,
16  "date_of_birth_filter": {
17    "date_of_birth_filter_enabled": true,
18    "date_of_birth_filter_approximate": true,
19    "date_of_birth_filter_typo_correction": true
20  },
21  "requirements": {
22    "review_all_hits": true,
23    "secondary_review_required": "never",
24    "prefer_escalation": true
25  },
26  "assignment_strategy": "random"
27}

Entity Screenings

To check your organization customer against various sanction and PEP lists, create an entity screening. This set of endpoints allows you to update previously created screenings for use with ongoing screening, see past versions of a screening profile, view any hits associated with the screening, and create and view reviews regarding past hits.

List Entity Screenings

List all entity screenings belonging to a particular entity program, optionally filtering by customer_reference or assignee and status.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Query Parameters

entity_program_idrequiredstring

Filters the results by the ID of the entity program the EntityScreenings belong to.

statusoptionalstring

Filters the results by the review status of the entity screening. When present, customer_reference is not allowed.

Possible enum values

rejectedpending_reviewcleared

assigneeoptionalstring

Filters the results by the user ID of the user assigned to the entity screening. May only be provided when status is present.

customer_referenceoptionalstring

Filters the results by the customer reference. When present, status and assignee are not allowed.

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of entity watchlist screening

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated entity screening.

search_termsalways presentobject

View in sample
JSON

Search terms associated with an entity used for searching against watchlists

Hide child attributes

entity_program_idalways presentstring

View in sample
JSON

ID of the associated entity program.

namealways presentstring

View in sample
JSON

The name of the organization being screened.

documentalways presentstringNULLABLE

View in sample
JSON

An optional identity document number for filtering the watchlist screening

The numeric or alphanumeric identifier associated with this document.

emailalways presentstringNULLABLE

View in sample
JSON

An optional email for filtering the watchlist screening

A valid email address.

locationalways presentstringNULLABLE

View in sample
JSON

An optional location for filtering the watchlist screening

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

phone_numberalways presentstringNULLABLE

View in sample
JSON

An optional phone number for filtering the watchlist screening

A phone number in E.164 format.

urlalways presentstringNULLABLE

View in sample
JSON

An optional URL for filtering the watchlist screening

An 'http' or 'https' URL (must begin with either of those).

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

GET

/entity_screenings

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "entscr_52xR9LKo77r1Np",
5      "search_terms": {
6        "entity_program_id": "entprg_2eRPsDnL66rZ7H",
7        "name": "Al-Qaida",
8        "document": "C31195855",
9        "email": "user@example.com",
10        "location": "US",
11        "phone_number": "+14025671234",
12        "url": "http://cognitohq.com",
13        "version": 1
14      },
15      "assignee": "usr_1SUuwqBdK75GKi",
16      "status": "cleared",
17      "customer_reference": "your-db-id-3b24110",
18      "audit_trail": {
19        "source": "dashboard",
20        "user_id": "usr_1SUuwqBdK75GKi",
21        "timestamp": "2020-07-24T03:26:02Z"
22      }
23    }
24  ],
25  "links": {
26    "previous": "http://cognitohq.com",
27    "next": "http://cognitohq.com"
28  }
29}

Create Entity Screening

Create a new entity screening to check your customer against watchlists defined in the associated entity program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Request Body

search_termsrequiredobject

View in sample
JSON

Search inputs for creating an entity watchlist screening

Hide child attributes

search_terms.entity_program_idrequiredstring

View in sample
JSON

ID of the associated entity program.

search_terms.namerequiredstring

View in sample
JSON

The name of the organization being screened.

search_terms.documentoptionalstring

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

search_terms.emailoptionalstring

View in sample
JSON

A valid email address.

search_terms.locationoptionalstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

search_terms.phone_numberoptionalstring

View in sample
JSON

A phone number in E.164 format.

search_terms.urloptionalstring

View in sample
JSON

An 'http' or 'https' URL (must begin with either of those).

customer_referenceoptionalstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated entity screening.

search_termsalways presentobject

View in sample
JSON

Search terms associated with an entity used for searching against watchlists

Hide child attributes

entity_program_idalways presentstring

View in sample
JSON

ID of the associated entity program.

namealways presentstring

View in sample
JSON

The name of the organization being screened.

documentalways presentstringNULLABLE

View in sample
JSON

An optional identity document number for filtering the watchlist screening

The numeric or alphanumeric identifier associated with this document.

emailalways presentstringNULLABLE

View in sample
JSON

An optional email for filtering the watchlist screening

A valid email address.

locationalways presentstringNULLABLE

View in sample
JSON

An optional location for filtering the watchlist screening

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

phone_numberalways presentstringNULLABLE

View in sample
JSON

An optional phone number for filtering the watchlist screening

A phone number in E.164 format.

urlalways presentstringNULLABLE

View in sample
JSON

An optional URL for filtering the watchlist screening

An 'http' or 'https' URL (must begin with either of those).

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

POST

/entity_screenings

1{
2  "search_terms": {
3    "entity_program_id": "entprg_2eRPsDnL66rZ7H",
4    "name": "Al-Qaida",
5    "document": "C31195855",
6    "email": "user@example.com",
7    "location": "US",
8    "phone_number": "+14025671234",
9    "url": "http://cognitohq.com"
10  },
11  "customer_reference": "your-db-id-3b24110"
12}
Response Sample
Copy JSON
1{
2  "id": "entscr_52xR9LKo77r1Np",
3  "search_terms": {
4    "entity_program_id": "entprg_2eRPsDnL66rZ7H",
5    "name": "Al-Qaida",
6    "document": "C31195855",
7    "email": "user@example.com",
8    "location": "US",
9    "phone_number": "+14025671234",
10    "url": "http://cognitohq.com",
11    "version": 1
12  },
13  "assignee": "usr_1SUuwqBdK75GKi",
14  "status": "cleared",
15  "customer_reference": "your-db-id-3b24110",
16  "audit_trail": {
17    "source": "dashboard",
18    "user_id": "usr_1SUuwqBdK75GKi",
19    "timestamp": "2020-07-24T03:26:02Z"
20  }
21}

Retrieve Entity Screening

Get the current state of a specific entity screening.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the entity screening to retrieve.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated entity screening.

search_termsalways presentobject

View in sample
JSON

Search terms associated with an entity used for searching against watchlists

Hide child attributes

entity_program_idalways presentstring

View in sample
JSON

ID of the associated entity program.

namealways presentstring

View in sample
JSON

The name of the organization being screened.

documentalways presentstringNULLABLE

View in sample
JSON

An optional identity document number for filtering the watchlist screening

The numeric or alphanumeric identifier associated with this document.

emailalways presentstringNULLABLE

View in sample
JSON

An optional email for filtering the watchlist screening

A valid email address.

locationalways presentstringNULLABLE

View in sample
JSON

An optional location for filtering the watchlist screening

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

phone_numberalways presentstringNULLABLE

View in sample
JSON

An optional phone number for filtering the watchlist screening

A phone number in E.164 format.

urlalways presentstringNULLABLE

View in sample
JSON

An optional URL for filtering the watchlist screening

An 'http' or 'https' URL (must begin with either of those).

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

GET

/entity_screenings/{id}

Response Sample
Copy JSON
1{
2  "id": "entscr_52xR9LKo77r1Np",
3  "search_terms": {
4    "entity_program_id": "entprg_2eRPsDnL66rZ7H",
5    "name": "Al-Qaida",
6    "document": "C31195855",
7    "email": "user@example.com",
8    "location": "US",
9    "phone_number": "+14025671234",
10    "url": "http://cognitohq.com",
11    "version": 1
12  },
13  "assignee": "usr_1SUuwqBdK75GKi",
14  "status": "cleared",
15  "customer_reference": "your-db-id-3b24110",
16  "audit_trail": {
17    "source": "dashboard",
18    "user_id": "usr_1SUuwqBdK75GKi",
19    "timestamp": "2020-07-24T03:26:02Z"
20  }
21}

Update Entity Screening

Update a specific entity screening. This endpoint can be used to add additional customer information, correct outdated information, add a reference id, assign the entity to a reviewer, and update which entity program it is associated with. Please note that you may not update search_terms and status at the same time since editing search_terms may trigger an automatic status change.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the entity screening to retrieve.

Request Body

entity_watchlist_screening_idrequiredstring

View in sample
JSON

ID of the associated entity screening.

search_termsoptionalobject

View in sample
JSON

Search terms for editing an entity watchlist screening

Hide child attributes

search_terms.entity_program_idrequiredstring

View in sample
JSON

ID of the associated entity program.

search_terms.nameoptionalstring

View in sample
JSON

The name of the organization being screened.

search_terms.documentoptionalstring

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

search_terms.emailoptionalstring

View in sample
JSON

A valid email address.

search_terms.locationoptionalstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

search_terms.phone_numberoptionalstring

View in sample
JSON

A phone number in E.164 format.

search_terms.urloptionalstring

View in sample
JSON

An 'http' or 'https' URL (must begin with either of those).

assigneeoptionalstringNULLABLE

View in sample
JSON

statusoptionalstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referenceoptionalstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated entity screening.

search_termsalways presentobject

View in sample
JSON

Search terms associated with an entity used for searching against watchlists

Hide child attributes

entity_program_idalways presentstring

View in sample
JSON

ID of the associated entity program.

namealways presentstring

View in sample
JSON

The name of the organization being screened.

documentalways presentstringNULLABLE

View in sample
JSON

An optional identity document number for filtering the watchlist screening

The numeric or alphanumeric identifier associated with this document.

emailalways presentstringNULLABLE

View in sample
JSON

An optional email for filtering the watchlist screening

A valid email address.

locationalways presentstringNULLABLE

View in sample
JSON

An optional location for filtering the watchlist screening

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

phone_numberalways presentstringNULLABLE

View in sample
JSON

An optional phone number for filtering the watchlist screening

A phone number in E.164 format.

urlalways presentstringNULLABLE

View in sample
JSON

An optional URL for filtering the watchlist screening

An 'http' or 'https' URL (must begin with either of those).

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

Webhooks
POSTentity_screening.status.updated

Receive a webhook whenever an entity screening status changes, such as done manually via the dashboard or during ongoing monitoring. Contact support to try this feature.

idalways presentstring

ID of the associated webhook event.

timestampalways presentstring

The time that the event happened.

eventalways presentstring

The type of event this webhook describes.

dataalways presentobject

environmentalways presentstring

Environment from which the webhook was sent.

Possible enum values

sandboxlive
PATCH

/entity_screenings/{id}

1{
2  "entity_watchlist_screening_id": "entscr_52xR9LKo77r1Np",
3  "search_terms": {
4    "entity_program_id": "entprg_2eRPsDnL66rZ7H",
5    "name": "Al-Qaida",
6    "document": "C31195855",
7    "email": "user@example.com",
8    "location": "US",
9    "phone_number": "+14025671234",
10    "url": "http://cognitohq.com"
11  },
12  "assignee": "usr_1SUuwqBdK75GKi",
13  "status": "cleared",
14  "customer_reference": "your-db-id-3b24110"
15}
Response Sample
Copy JSON
1{
2  "id": "entscr_52xR9LKo77r1Np",
3  "search_terms": {
4    "entity_program_id": "entprg_2eRPsDnL66rZ7H",
5    "name": "Al-Qaida",
6    "document": "C31195855",
7    "email": "user@example.com",
8    "location": "US",
9    "phone_number": "+14025671234",
10    "url": "http://cognitohq.com",
11    "version": 1
12  },
13  "assignee": "usr_1SUuwqBdK75GKi",
14  "status": "cleared",
15  "customer_reference": "your-db-id-3b24110",
16  "audit_trail": {
17    "source": "dashboard",
18    "user_id": "usr_1SUuwqBdK75GKi",
19    "timestamp": "2020-07-24T03:26:02Z"
20  }
21}

List Entity Screening History

List all changes to the entity screening in reverse-chronological order. If the entity screening has not been edited, no history will be returned.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the entity screening to retrieve past versions of.

Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of entity watchlist screening

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated entity screening.

search_termsalways presentobject

View in sample
JSON

Search terms associated with an entity used for searching against watchlists

Hide child attributes

entity_program_idalways presentstring

View in sample
JSON

ID of the associated entity program.

namealways presentstring

View in sample
JSON

The name of the organization being screened.

documentalways presentstringNULLABLE

View in sample
JSON

An optional identity document number for filtering the watchlist screening

The numeric or alphanumeric identifier associated with this document.

emailalways presentstringNULLABLE

View in sample
JSON

An optional email for filtering the watchlist screening

A valid email address.

locationalways presentstringNULLABLE

View in sample
JSON

An optional location for filtering the watchlist screening

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

phone_numberalways presentstringNULLABLE

View in sample
JSON

An optional phone number for filtering the watchlist screening

A phone number in E.164 format.

urlalways presentstringNULLABLE

View in sample
JSON

An optional URL for filtering the watchlist screening

An 'http' or 'https' URL (must begin with either of those).

versionalways presentnumber

View in sample
JSON

The current version of the search terms. Starts at 1 and increments with each edit to search_terms.

assigneealways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

statusalways presentstring

View in sample
JSON

A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.

Possible enum values

rejectedpending_reviewcleared

customer_referencealways presentstringNULLABLE

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

GET

/entity_screenings/{id}/history

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "entscr_52xR9LKo77r1Np",
5      "search_terms": {
6        "entity_program_id": "entprg_2eRPsDnL66rZ7H",
7        "name": "Al-Qaida",
8        "document": "C31195855",
9        "email": "user@example.com",
10        "location": "US",
11        "phone_number": "+14025671234",
12        "url": "http://cognitohq.com",
13        "version": 1
14      },
15      "assignee": "usr_1SUuwqBdK75GKi",
16      "status": "cleared",
17      "customer_reference": "your-db-id-3b24110",
18      "audit_trail": {
19        "source": "dashboard",
20        "user_id": "usr_1SUuwqBdK75GKi",
21        "timestamp": "2020-07-24T03:26:02Z"
22      }
23    }
24  ],
25  "links": {
26    "previous": "http://cognitohq.com",
27    "next": "http://cognitohq.com"
28  }
29}

List Entity Screening Hits

Retrieve a list of all entity screening hits associated with this entity screening. entity screening hits are potential watchlist matches found by the Cognito system based on the profile information entered on the associated entity screening.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the entity screening to retrieve hits for.

Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of entity watchlist screening hits

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated entity screening hit.

review_statusalways presentstring

View in sample
JSON

The current state of review. All screening hits and entity screening hits begin in a pending_review state but can be changed by creating a Review/EntityReview. When a hit is in the pending_review state, it will always show the latest version of the watchlist data Cognito has available and be compared against the latest customer information saved in the screening/entity screening. Once a hit has been marked as confirmed or dismissed it will no longer be updated so that the state is as it was when the review was first conducted.

Possible enum values

confirmedpending_reviewdismissed

first_activealways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

inactive_sincealways presentstringNULLABLE

View in sample
JSON

If a hit no longer matches current entity program thresholds due to changes in program configuration or updates to the source data, this timestamp will be set to when it was discovered to no longer match. NOTE: This timestamp will be updated even after a hit has been confirmed or dismissed.

An ISO8601 formatted timestamp.

historical_sincealways presentstringNULLABLE

View in sample
JSON

If a hit is not currently part of a source list, this timestamp will show when the removal was discovered. NOTE: This timestamp will be updated even after a hit has been confirmed or dismissed.

An ISO8601 formatted timestamp.

list_codealways presentstring

View in sample
JSON

Shorthand identifier for a specific screening list for entities.

Possible enum values

CA_CONEU_CONIZ_SOEIZ_UNCIZ_WBKUS_CAPUS_FSEUS_MBSUS_SDNUS_SSIUS_CMCUS_UVLAU_CONUK_HMC

cognito_uidalways presentstring

View in sample
JSON

A universal identifier for a watchlist individual that is stable across searches and updates.

source_uidalways presentstringNULLABLE

View in sample
JSON

The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is null.

The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is null.

analysismight be omittedobject

View in sample
JSON

Analysis information describing why a screening hit matched the provided entity information

Hide child attributes

documentsmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

emailsmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

locationsmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

namesmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

phone_numbersmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

urlsmight be omittedstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

search_terms_versionalways presentnumber

View in sample
JSON

The version of the entity screening's search_terms that were compared when the entity screening hit was added. entity screening hits are immutable once they have been reviewed. If changes are detected due to updates to the entity screening's search_terms, the associated entity program, or the list's source data prior to review, the entity screening hit will be updated to reflect those changes.

datamight be omittedobject

View in sample
JSON

Information associated with the entity watchlist hit

Hide child attributes

documentsmight be omittedarray of objects

View in sample
JSON

Documents associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

An official document, usually issued by a governing body or institution, with an associated identifier.

Hide child attributes

typealways presentstring

View in sample
JSON

The kind of official document represented by this object.

  • bik - Russian bank code
  • business_number - A number that uniquely identifies the business within a category of businesses
  • imo - Number assigned to the entity by the International Maritime Organization
  • other - Any document not covered by other categories
  • swift - Number identifying a bank and branch.
  • tax_id - Identification issued for the purpose of collecting taxes

Possible enum values

bikbusiness_numberimootherswifttax_id

valuealways presentstring

View in sample
JSON

The numeric or alphanumeric identifier associated with this document.

emailsmight be omittedarray of objects

View in sample
JSON

Email addresses associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

Email address information for the associated entity watchlist hit

Hide child attributes

emailalways presentstring

View in sample
JSON

A valid email address.

locationsmight be omittedarray of objects

View in sample
JSON

Locations associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

Location information for the associated individual watchlist hit

Hide child attributes

fullalways presentstring

View in sample
JSON

The full location string, potentially including elements like street, city, postal codes and country codes. Note that this is not necessarily a complete or well-formatted address.

country_codealways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

namesmight be omittedarray of objects

View in sample
JSON

Names associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

Name information for the associated entity watchlist hit

Hide child attributes

fullalways presentstring

View in sample
JSON

The full name of the entity.

primaryalways presentboolean

View in sample
JSON

Primary names are those most commonly used to refer to this entity. Only one name will ever be marked as primary.

weak_alias_determinationalways presentstring

View in sample
JSON

Names that are explicitly marked as low quality either by their source list, or by cognito by a series of additional checks done by Cognito. Cognito does not ever surface a hit as a result of a weak name alone. If a name has no quality issues, this value will be none.

Possible enum values

nonesourcecognito

phone_numbersmight be omittedarray of objects

View in sample
JSON

Phone numbers associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

Phone number information associated with the entity screening hit

Hide child attributes

typealways presentstring

View in sample
JSON

An enum indicating whether a phone number is a phone line or a fax line.

Possible enum values

phonefax

numberalways presentstring

View in sample
JSON

A phone number in E.164 format.

urlsmight be omittedarray of objects

View in sample
JSON

URLs associated with the watchlist hit

Hide child attributes

analysismight be omittedobject

View in sample
JSON

Summary object reflecting the match result of the associated data

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

datamight be omittedobject

View in sample
JSON

URLs associated with the entity screening hit

Hide child attributes

urlalways presentstring

View in sample
JSON

An 'http' or 'https' URL (must begin with either of those).

GET

/entity_screenings/{id}/hits

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "enthit_52xR9LKo77r1Np",
5      "review_status": "pending_review",
6      "first_active": "2020-07-24T03:26:02Z",
7      "inactive_since": "2020-07-24T03:26:02Z",
8      "historical_since": "2020-07-24T03:26:02Z",
9      "list_code": "EU_CON",
10      "cognito_uid": "uid_3NggckTimGSJHS",
11      "source_uid": "26192ABC",
12      "analysis": {
13        "documents": "match",
14        "emails": "match",
15        "locations": "match",
16        "names": "match",
17        "phone_numbers": "match",
18        "urls": "match",
19        "search_terms_version": 1
20      },
21      "data": {
22        "documents": [
23          {
24            "analysis": {
25              "summary": "match"
26            },
27            "data": {
28              "type": "swift",
29              "value": "C31195855"
30            }
31          }
32        ],
33        "emails": [
34          {
35            "analysis": {
36              "summary": "match"
37            },
38            "data": {
39              "email": "user@example.com"
40            }
41          }
42        ],
43        "locations": [
44          {
45            "analysis": {
46              "summary": "match"
47            },
48            "data": {
49              "full": "Florida, US",
50              "country_code": "US"
51            }
52          }
53        ],
54        "names": [
55          {
56            "analysis": {
57              "summary": "match"
58            },
59            "data": {
60              "full": "Al Qaida",
61              "primary": true,
62              "weak_alias_determination": "none"
63            }
64          }
65        ],
66        "phone_numbers": [
67          {
68            "analysis": {
69              "summary": "match"
70            },
71            "data": {
72              "type": "phone",
73              "number": "+14025671234"
74            }
75          }
76        ],
77        "urls": [
78          {
79            "analysis": {
80              "summary": "match"
81            },
82            "data": {
83              "url": "http://cognitohq.com"
84            }
85          }
86        ]
87      }
88    }
89  ],
90  "links": {
91    "previous": "http://cognitohq.com",
92    "next": "http://cognitohq.com"
93  }
94}

List Entity Reviews

List all EntityReviews belonging to a particular entity screening.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the entity screening being reviewed.

Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of entity watchlist screening reviews

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated entity review.

confirmed_hitsalways presentarray of strings

View in sample
JSON

Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

dismissed_hitsalways presentarray of strings

View in sample
JSON

Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

commentalways presentstringNULLABLE

View in sample
JSON

A comment submitted by a team member as part of reviewing a watchlist screening.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

GET

/entity_screenings/{id}/reviews

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "entrev_aCLNRxK3UVzn2r",
5      "confirmed_hits": [
6        "enthit_52xR9LKo77r1Np"
7      ],
8      "dismissed_hits": [
9        "enthit_52xR9LKo77r1Np"
10      ],
11      "comment": "These look like legitimate matches, rejecting the customer.",
12      "audit_trail": {
13        "source": "dashboard",
14        "user_id": "usr_1SUuwqBdK75GKi",
15        "timestamp": "2020-07-24T03:26:02Z"
16      }
17    }
18  ],
19  "links": {
20    "previous": "http://cognitohq.com",
21    "next": "http://cognitohq.com"
22  }
23}

Create Entity Review

Create a new EntityReview of a particular entity screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by the Cognito system.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the entity screening being reviewed.

Request Body

confirmed_hitsrequiredarray of strings

View in sample
JSON

Hits to mark as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

dismissed_hitsrequiredarray of strings

View in sample
JSON

Hits to mark as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

commentoptionalstring

View in sample
JSON

A comment submitted by a team member as part of reviewing a watchlist screening.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated entity review.

confirmed_hitsalways presentarray of strings

View in sample
JSON

Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected.

dismissed_hitsalways presentarray of strings

View in sample
JSON

Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed.

commentalways presentstringNULLABLE

View in sample
JSON

A comment submitted by a team member as part of reviewing a watchlist screening.

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

POST

/entity_screenings/{id}/reviews

1{
2  "confirmed_hits": [
3    "enthit_52xR9LKo77r1Np"
4  ],
5  "dismissed_hits": [
6    "enthit_52xR9LKo77r1Np"
7  ],
8  "comment": "These look like legitimate matches, rejecting the customer."
9}
Response Sample
Copy JSON
1{
2  "id": "entrev_aCLNRxK3UVzn2r",
3  "confirmed_hits": [
4    "enthit_52xR9LKo77r1Np"
5  ],
6  "dismissed_hits": [
7    "enthit_52xR9LKo77r1Np"
8  ],
9  "comment": "These look like legitimate matches, rejecting the customer.",
10  "audit_trail": {
11    "source": "dashboard",
12    "user_id": "usr_1SUuwqBdK75GKi",
13    "timestamp": "2020-07-24T03:26:02Z"
14  }
15}

Entity Programs

Entity Programs help you to define the settings and workflows for conducting entity screenings in your organization. For example, you can define which lists are being screened, and the behavior of ongoing re-scans.

List Entity Programs

List all entity programs associated with your account. As a note, entity programs may only be created via the dashboard.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of entity watchlist screening programs

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated entity program.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

enabledalways presentboolean

View in sample
JSON

Indicator specifying whether the program is enabled and will perform daily rescans.

lists_enabledalways presentarray of strings

View in sample
JSON

Watchlists enabled for the associated program

Possible enum values

CA_CONEU_CONIZ_SOEIZ_UNCIZ_WBKUS_CAPUS_FSEUS_MBSUS_SDNUS_SSIUS_CMCUS_UVLAU_CONUK_HMC

namealways presentstring

View in sample
JSON

A name for the entity program to define its purpose. For example, "High Risk Organizations" or "Applicants".

name_sensitivityalways presentstring

View in sample
JSON

The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity.

  • coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review.
  • balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise.
  • strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations.
  • exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case.

Possible enum values

coarsebalancedstrictexact

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

archivedalways presentboolean

View in sample
JSON

Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.

date_of_birth_filtermight be omittedobject

View in sample
JSON
Hide child attributes

date_of_birth_filter_enabledalways presentboolean

View in sample
JSON

date_of_birth_filter_approximatealways presentboolean

View in sample
JSON

date_of_birth_filter_typo_correctionalways presentboolean

View in sample
JSON

requirementsmight be omittedobject

View in sample
JSON
Hide child attributes

review_all_hitsmight be omittedboolean

View in sample
JSON

secondary_review_requiredalways presentstring

View in sample
JSON

Possible enum values

neverwhen_clearingwhen_rejectingalways

prefer_escalationalways presentboolean

View in sample
JSON

assignment_strategymight be omittedstring

View in sample
JSON

Possible enum values

randomdisabled
GET

/entity_programs

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "entprg_2eRPsDnL66rZ7H",
5      "created_at": "2020-07-24T03:26:02Z",
6      "enabled": true,
7      "lists_enabled": [
8        "EU_CON"
9      ],
10      "name": "Sample Program",
11      "name_sensitivity": "balanced",
12      "audit_trail": {
13        "source": "dashboard",
14        "user_id": "usr_1SUuwqBdK75GKi",
15        "timestamp": "2020-07-24T03:26:02Z"
16      },
17      "archived": true,
18      "date_of_birth_filter": {
19        "date_of_birth_filter_enabled": true,
20        "date_of_birth_filter_approximate": true,
21        "date_of_birth_filter_typo_correction": true
22      },
23      "requirements": {
24        "review_all_hits": true,
25        "secondary_review_required": "never",
26        "prefer_escalation": true
27      },
28      "assignment_strategy": "random"
29    }
30  ],
31  "links": {
32    "previous": "http://cognitohq.com",
33    "next": "http://cognitohq.com"
34  }
35}

Retrieve Entity Program

Retrieve a specific entity program for review.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the entity program to retrieve.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated entity program.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

enabledalways presentboolean

View in sample
JSON

Indicator specifying whether the program is enabled and will perform daily rescans.

lists_enabledalways presentarray of strings

View in sample
JSON

Watchlists enabled for the associated program

Possible enum values

CA_CONEU_CONIZ_SOEIZ_UNCIZ_WBKUS_CAPUS_FSEUS_MBSUS_SDNUS_SSIUS_CMCUS_UVLAU_CONUK_HMC

namealways presentstring

View in sample
JSON

A name for the entity program to define its purpose. For example, "High Risk Organizations" or "Applicants".

name_sensitivityalways presentstring

View in sample
JSON

The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity.

  • coarse - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review.
  • balanced - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise.
  • strict - Aggressive false positive reduction. This sensitivity will require names to be more similar than coarse and balanced settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations.
  • exact - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case.

Possible enum values

coarsebalancedstrictexact

audit_trailalways presentobject

View in sample
JSON

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

Hide child attributes

sourcealways presentstring

View in sample
JSON

A type indicating whether a dashboard user, an API-based user, or the Cognito system last touched this object.

Possible enum values

dashboardflowapisystem

user_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated user.

timestampalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

archivedalways presentboolean

View in sample
JSON

Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring.

date_of_birth_filtermight be omittedobject

View in sample
JSON
Hide child attributes

date_of_birth_filter_enabledalways presentboolean

View in sample
JSON

date_of_birth_filter_approximatealways presentboolean

View in sample
JSON

date_of_birth_filter_typo_correctionalways presentboolean

View in sample
JSON

requirementsmight be omittedobject

View in sample
JSON
Hide child attributes

review_all_hitsmight be omittedboolean

View in sample
JSON

secondary_review_requiredalways presentstring

View in sample
JSON

Possible enum values

neverwhen_clearingwhen_rejectingalways

prefer_escalationalways presentboolean

View in sample
JSON

assignment_strategymight be omittedstring

View in sample
JSON

Possible enum values

randomdisabled
GET

/entity_programs/{id}

Response Sample
Copy JSON
1{
2  "id": "entprg_2eRPsDnL66rZ7H",
3  "created_at": "2020-07-24T03:26:02Z",
4  "enabled": true,
5  "lists_enabled": [
6    "EU_CON"
7  ],
8  "name": "Sample Program",
9  "name_sensitivity": "balanced",
10  "audit_trail": {
11    "source": "dashboard",
12    "user_id": "usr_1SUuwqBdK75GKi",
13    "timestamp": "2020-07-24T03:26:02Z"
14  },
15  "archived": true,
16  "date_of_birth_filter": {
17    "date_of_birth_filter_enabled": true,
18    "date_of_birth_filter_approximate": true,
19    "date_of_birth_filter_typo_correction": true
20  },
21  "requirements": {
22    "review_all_hits": true,
23    "secondary_review_required": "never",
24    "prefer_escalation": true
25  },
26  "assignment_strategy": "random"
27}

Users

To accomplish other actions on the API such as assigning screening reviews to parties in your organization, you will need to get information about the users on your account. User objects help you get that information and audit access within your organization.

List Users

List all users associated with your organization.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of users

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated user.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

emailalways presentstring

View in sample
JSON

A valid email address.

statusalways presentstring

View in sample
JSON

The current status of the user.

Possible enum values

invitedactivedeactivated
GET

/users

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "usr_1SUuwqBdK75GKi",
5      "created_at": "2020-07-24T03:26:02Z",
6      "email": "user@example.com",
7      "status": "active"
8    }
9  ],
10  "links": {
11    "previous": "http://cognitohq.com",
12    "next": "http://cognitohq.com"
13  }
14}

Retrieve User

Retrieve a specific User.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the User to retrieve.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated user.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

emailalways presentstring

View in sample
JSON

A valid email address.

statusalways presentstring

View in sample
JSON

The current status of the user.

Possible enum values

invitedactivedeactivated
GET

/users/{id}

Response Sample
Copy JSON
1{
2  "id": "usr_1SUuwqBdK75GKi",
3  "created_at": "2020-07-24T03:26:02Z",
4  "email": "user@example.com",
5  "status": "active"
6}

Flow

Flow lets you build a custom identity verification and watchlist screening experience via our dashboard and embed it within your application. Flow's API lets you check the status and progression of your customers' Flow sessions and collect the data they submitted.

List Flow Sessions

Filter and list FlowSessions created by your account.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Query Parameters

cursoroptionalstring

An identifier that determines which page of results you receive. Cursors are automatically generated and provided to you as part of the next and previous links in the links section.

customer_referencerequiredstring

The identifier you associated with one of your customer's FlowSessions.

template_idrequiredstring

The identifier associated with the FlowTemplate you want to filter by.

Response Schema

dataalways presentarray of objects

View in sample
JSON

List of flow sessions

Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated Flow session.

customer_referencealways presentstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

completed_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the Flow Session terminated

An ISO8601 formatted timestamp.

previous_session_idalways presentstringNULLABLE

View in sample
JSON

The ID of the previous Flow Session, if any.

The ID for the Flow Session preceding this session. This field will only be filled if the current Flow Session is a retry of a previous session.

shareable_urlalways presentstringNULLABLE

View in sample
JSON

A shareable URL that can be sent directly to the user to complete verification

templatealways presentobject

View in sample
JSON
Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated Flow template.

versionalways presentnumber

View in sample
JSON

Version of the associated Flow template.

useralways presentobject

View in sample
JSON
Hide child attributes

phonealways presentstringNULLABLE

View in sample
JSON

A phone number in E.164 format.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

ip_addressalways presentstringNULLABLE

View in sample
JSON

IP Address collected from the user's Flow Session. Can be either an IPv4 or IPv6 address. If the address is representable as IPv4, it will be returned as IPv4.


Note: This field can be null if the user has not yet interacted with Flow's frontend, either because they haven't started their session yet or because their session was created via API using Flow hybrid.

An IPv4 or IPV6 address.

emailalways presentstringNULLABLE

View in sample
JSON

The user email you programmatically provided to your Flow integration.

A valid email address.

namealways presentobjectNULLABLE

View in sample
JSON

The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

Hide child attributes

firstalways presentstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

lastalways presentstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

addressalways presentobjectNULLABLE

View in sample
JSON

The address data submitted by the user. If the user has not submitted their address, this field will be null. Otherwise, it will be an object and street, city, and country_code are guaranteed to be filled. The remaining fields differ based the region's addressing system. For example:

  • Addresses from the United Kingdom will not include a subdivision
  • Addresses from Hong Kong will not include postal code

Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: * Addresses from the United Kingdom will not include a region * Addresses from Hong Kong will not include postal code

Hide child attributes

streetalways presentstringNULLABLE

View in sample
JSON

The primary street portion of an address. If the user has submitted their address, this field will always be filled.

street2always presentstringNULLABLE

View in sample
JSON

Extra street information, like an apartment or suite number.

cityalways presentstringNULLABLE

View in sample
JSON

City from the end user's address

subdivisionalways presentstringNULLABLE

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

postal_codealways presentstringNULLABLE

View in sample
JSON

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

country_codealways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

id_numberalways presentobjectNULLABLE

View in sample
JSON

ID Number submitted by the user. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

Type and value of ID number provided

Hide child attributes

valuealways presentstring

View in sample
JSON

Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.

categoryalways presentstring

View in sample
JSON

The category of identity document provided

Possible enum values

drivers_licensepassportpersonal_identificationtax_idvoter_id

typealways presentstring

View in sample
JSON

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Flow Hybrid Input Validation](https://cognitohq.com/docs/flow/flow-hybrid-input-validation)

Possible enum values

ar_dniau_drivers_licenseau_passportbr_cpfca_sincl_runcn_resident_cardco_nitdk_cpreg_national_ides_dnies_niehk_hkidin_panit_cfjo_civil_idjp_my_numberke_huduma_nambakw_civil_idmx_curpmx_rfcmy_nricng_ninnz_drivers_licenseom_civil_idph_psnpl_peselro_cnpsa_national_idse_pinsg_nrictr_tc_kimlikus_ssnus_ssn_last_4za_smart_id

statusalways presentstring

View in sample
JSON

The status of this Flow session.

  • active - The Flow session is incomplete. The user may have completed part of the session, but has neither failed or passed.
  • success - The Flow session has completed, passing all steps defined to the associated Flow template
  • failed - The user failed one or more steps in the session and was told to contact support.
  • expired - The Flow session was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.
  • canceled - The Flow session was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.
  • pending_review - The Flow session template was configured to perform a screening that had one or more hits needing review.

Possible enum values

activesuccessfailedexpiredcanceledpending_review

stepsalways presentobject

View in sample
JSON

Each step will be one of the following values:

  • active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Flow session while in the middle of this step. Only one step will be marked as active at any given point.
  • success - The Flow session has completed this step.
  • failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Flow template is configured. A failed step does not imply a failed session.
  • waiting_for_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback.
  • not_applicable - This step will not be run for this session.
  • skipped - The retry instructions that created this Flow session specified that this step should be skipped.
  • expired - This step had not yet been completed when the Flow session as a whole expired.
  • canceled - The Flow session was canceled before the user completed this step.
  • pending_review - The Flow session template was configured to perform a screening that had one or more hits needing review.
  • manually_approved - The step was manually overridden to pass by a team member in the dashboard.
  • manually_rejected - The step was manually overridden to fail by a team member in the dashboard.
Hide child attributes

accept_tosalways presentstring

View in sample
JSON

The status of the accept_tos step. This step will always come first.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

verify_smsalways presentstring

View in sample
JSON

The status of the SMS verification step. Failing this step means the user either entered an incorrect code twice or the verification code has expired.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

kyc_screenalways presentstring

View in sample
JSON

Deprecated.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

kyc_checkalways presentstring

View in sample
JSON

The status of the full KYC check step (referred to as the "Know your Customer" use case in the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

documentary_verificationalways presentstring

View in sample
JSON

The status of the documentary verification check step (configured via "Fallback Settings" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

selfie_checkalways presentstring

View in sample
JSON

The status of the selfie check step (configured via "Selfie Check Behavior" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

screeningalways presentstring

View in sample
JSON

The status of the watchlist screening step, always run last. No user input is prompted for this step. The status will be pending_review when there are unreviewed hits. Once hits are reviewed, the status will be changed to manually_approved or manually_rejected, as appropriate.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

risk_checkalways presentstring

View in sample
JSON

The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

documentary_verificationalways presentobjectNULLABLE

View in sample
JSON

Data, images, analysis, and results from the documentary_verification step. This field will be null unless steps.documentary_verification has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's documentary_verification step. This field will always have the same value as steps.documentary_verification.

documentsalways presentarray of objects

View in sample
JSON

An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.


Note: Flow will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.

Hide child attributes

statusalways presentstring

View in sample
JSON

An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible enum values

successfailedmanually_approved

attemptalways presentnumber

View in sample
JSON

The attempt field begins with 1 and increments with each subsequent document upload.

imagesalways presentobject

View in sample
JSON

URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Flow session. A new expiring URL is generated with each request, so you can always rerequest the Flow session if one of your URLs expires.

Hide child attributes

original_frontalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.

original_backalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.

cropped_frontalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.

cropped_backalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.

facealways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.

extracted_dataalways presentobjectNULLABLE

View in sample
JSON

Information extracted from the document images provided.


Note: This field might be null in the case where a document could not be detected in the image provided (either due to the image not containing a document or due to poor image quality)

Data extracted from a user-submitted document.

Hide child attributes

id_numberalways presentstringNULLABLE

View in sample
JSON

Alpha-numeric ID number extracted via OCR from the user's document image.

categoryalways presentstring

View in sample
JSON

The type of identity document detected in the images provided. Will always be one of the following values:

  • drivers_license - A driver's license for the associated country

  • id_card - A general national identification card, distinct from driver's licenses

  • passport - A passport for the associated country

  • residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country

  • resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country


Note: This value may be different from the ID type that the user selects within Flow's UI. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible enum values

drivers_licenseid_cardpassportresidence_permit_cardresident_card

expiration_datealways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

issuing_countryalways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

issuing_subdivisionalways presentstringNULLABLE

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

analysisalways presentobject

View in sample
JSON

High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.

Hide child attributes

authenticityalways presentstring

View in sample
JSON

High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.


For example, most identity documents have formatting rules like the following:

  • The image of the person's face must have a certain contrast in order to highlight skin tone

  • The subject in the document's image must remove eye glasses and pose in a certain way

  • The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules

  • Security features like watermarks and background patterns must be present

So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible enum values

matchpartial_matchno_matchno_data

image_qualityalways presentstring

View in sample
JSON

A high level description of the quality of the image the user submitted.


For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.


Note: By default, Flow will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible enum values

highmediumlow

extracted_dataalways presentobjectNULLABLE

View in sample
JSON

This section summarizes checks Cognito performed against the data that was extracted from the document image.

Analysis of the data extracted from the submitted document.

Hide child attributes

namealways presentstring

View in sample
JSON

A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to flow session.

Possible enum values

matchpartial_matchno_match

date_of_birthalways presentstring

View in sample
JSON

A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the flow session.

Possible enum values

matchpartial_matchno_match

expiration_datealways presentstring

View in sample
JSON

A description of whether the associated document was expired when the verification was performed.


Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible enum values

not_expiredexpiredno_data

issuing_countryalways presentstring

View in sample
JSON

A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Flow.


Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Flow Template.

Possible enum values

matchno_match

redacted_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the document was redacted

An ISO8601 formatted timestamp.

selfie_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the selfie_check step. This field will be null unless steps.selfie_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's selfie_check step. This field will always have the same value as steps.selfie_check.

Possible enum values

successfailed

selfiesalways presentarray of objects

View in sample
JSON

An array of selfies submitted to the selfie_check step. Each entry represents one user submission.

Hide child attributes

statusalways presentstring

View in sample
JSON

An outcome status for this specific selfie. Distinct from the overall selfie_check.status that summarizes the verification outcome from one or more selfies.

Possible enum values

successfailed

attemptalways presentinteger

View in sample
JSON

The attempt field begins with 1 and increments with each subsequent selfie upload.

capturealways presentobject

View in sample
JSON

The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.

Hide child attributes

image_urlmight be omittedstringNULLABLE

View in sample
JSON

Temporary URL for downloading an image selfie capture.

video_urlmight be omittedstringNULLABLE

View in sample
JSON

Temporary URL for downloading a video selfie capture.

analysisalways presentobject

View in sample
JSON

High level descriptions of how the associated selfie was processed. If a seflfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.

Hide child attributes

document_comparisonalways presentstring

View in sample
JSON

Information about the comparison between the selfie and the document (if documentary verification also ran).

Possible enum values

matchno_matchno_input

kyc_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's kyc_check step. This field will always have the same value as steps.kyc_check.

addressalways presentobject

View in sample
JSON

Result summary object specifying how the address field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

po_boxalways presentstring

View in sample
JSON

Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Cognito confirmed the address is not a P.O. box, and no_data when Cognito was not able to determine if the address is a P.O. box.

Possible enum values

yesnono_data

typealways presentstring

View in sample
JSON

Field describing whether the associated address is being used for commercial or residential purposes.


Note: This value will be no_data when Cognito does not have sufficient data to determine the address's use.

Possible enum values

residentialcommercialno_data

namealways presentobject

View in sample
JSON

Result summary object specifying how the name field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

date_of_birthalways presentobject

View in sample
JSON

Result summary object specifying how the date_of_birth field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

id_numberalways presentobject

View in sample
JSON

Result summary object specifying how the id_number field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

phonealways presentobject

View in sample
JSON

Result summary object specifying how the phone field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

risk_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the risk_check step. This field will be null unless steps.risk_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

behavioralways presentobjectNULLABLE

View in sample
JSON

The attributes from the behavior risk check, when available.

Result summary object specifying values for behavior attributes of risk check, when available.

Hide child attributes

user_interactionsalways presentstring

View in sample
JSON

Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session.

  • genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.
  • neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome.
  • risky indicates the user has low familiarity with the data they are providing, and that fraud is likely.
  • no_data indicates there is not sufficient information to give an accurate signal.

Possible enum values

genuineneutralriskyno_data

fraud_ring_detectedalways presentstring

View in sample
JSON

Field describing the outcome of a fraud ring behavior risk check.

  • yes indicates that fraud ring activity was detected.
  • no indicates that fraud ring activity was not detected.
  • no_data indicates there was not enough information available to give an accurate signal.

Possible enum values

yesnono_data

bot_detectedalways presentstring

View in sample
JSON

Field describing the outcome of a bot detection behavior risk check.

  • yes indicates that automated activity was detected.
  • no indicates that automated activity was not detected.
  • no_data indicates there was not enough information available to give an accurate signal.

Possible enum values

yesnono_data

emailalways presentobjectNULLABLE

View in sample
JSON

The attributes from the email risk check, when available.

Result summary object specifying values for email attributes of risk check.

Hide child attributes

is_deliverablealways presentstring

View in sample
JSON

SMTP-MX check to confirm the email address exists if known.

Possible enum values

yesnono_data

breach_countalways presentinteger

View in sample
JSON

Count of all known breaches of this email address if known.

first_breached_atalways presentstringNULLABLE

View in sample
JSON

First known date this email address was breached if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

last_breached_atalways presentstringNULLABLE

View in sample
JSON

Last known date this email address was breached if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

domain_registered_atalways presentstringNULLABLE

View in sample
JSON

Timestamp domain was registered at if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

domain_is_free_provideralways presentstring

View in sample
JSON

Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known.

Possible enum values

yesnono_data

domain_is_customalways presentstring

View in sample
JSON

Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable.

Possible enum values

yesnono_data

domain_is_disposablealways presentstring

View in sample
JSON

Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details.

Possible enum values

yesnono_data

top_level_domain_is_suspiciousalways presentstring

View in sample
JSON

Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain.

Possible enum values

yesnono_data

linked_servicesalways presentarray of strings

View in sample
JSON

Possible enum values

appleebayfacebookflickrfoursquaregithubgooglegravatarinstagramlastfmlinkedinmicrosoftmyspacepinterestskypespotifytelegramtumblrtwittervibervimeoweibowhatsappyahooairbnbamazonbookingdiscordkakaookqzonelinesnapchatzalo

phonealways presentobjectNULLABLE

View in sample
JSON

The attributes from the phone risk check, when available.

Result summary object specifying values for phone attributes of risk check.

Hide child attributes

linked_servicesalways presentarray of strings

View in sample
JSON

Possible enum values

appleebayfacebookflickrfoursquaregithubgooglegravatarinstagramlastfmlinkedinmicrosoftmyspacepinterestskypespotifytelegramtumblrtwittervibervimeoweibowhatsappyahooairbnbamazonbookingdiscordkakaookqzonelinesnapchatzalo

devicesalways presentarray of objects

View in sample
JSON

Array of result summary objects specifying values for device attributes of risk check.

Hide child attributes

ip_proxy_typealways presentstringNULLABLE

View in sample
JSON

An enum indicating whether a network proxy is present and if so what type it is. * none_detected indicates the user is not on a detectable proxy network. * tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). * vpn indicates the user is on a VPN (Virtual Private Network) * web_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. * public_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.

ip_spam_list_countalways presentinteger

View in sample
JSON

Count of spam lists the IP address is associated with if known.

ip_timezone_offsetalways presentstringNULLABLE

View in sample
JSON

UTC offset of the timezone associated with the IP address if known.

UTC offset of the timezone associated with the IP address.

screening_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated screening.

redacted_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the Flow Session was redacted

An ISO8601 formatted timestamp.

_metamight be omittedstring

View in sample
JSON

A friendly reminder that this API is still being developed and might change in the future. If we do choose to make a backwards incompatible change before this API hits 1.0, we will notify you by email with details and a deprecation timeline.

GET

/flow_sessions

Response Sample
Copy JSON
1{
2  "data": [
3    {
4      "id": "flwses_52xR9LKo77r1Np",
5      "customer_reference": "your-db-id-3b24110",
6      "created_at": "2020-07-24T03:26:02Z",
7      "completed_at": "2020-07-24T03:26:02Z",
8      "previous_session_id": "flwses_42cF1MNo42r9Xj",
9      "shareable_url": "https://flow.cognitohq.com/verify/flwtmp_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
10      "template": {
11        "id": "flwtmp_4FrXJvfQU3zGUR",
12        "version": 2
13      },
14      "user": {
15        "phone": "+19876543212",
16        "date_of_birth": "1975-01-18",
17        "ip_address": "192.0.2.42",
18        "email": "user@example.com",
19        "name": {
20          "first": "Leslie",
21          "last": "Knope"
22        },
23        "address": {
24          "street": "123 Main St.",
25          "street2": "Unit 42",
26          "city": "Pawnee",
27          "subdivision": "IN",
28          "postal_code": "46001",
29          "country_code": "US"
30        },
31        "id_number": {
32          "value": "123456789",
33          "category": "tax_id",
34          "type": "us_ssn"
35        }
36      },
37      "status": "success",
38      "steps": {
39        "accept_tos": "success",
40        "verify_sms": "success",
41        "kyc_screen": "not_applicable",
42        "kyc_check": "active",
43        "documentary_verification": "waiting_for_prerequisite",
44        "selfie_check": "waiting_for_prerequisite",
45        "screening": "waiting_for_prerequisite",
46        "risk_check": "waiting_for_prerequisite"
47      },
48      "documentary_verification": {
49        "status": "success",
50        "documents": [
51          {
52            "status": "success",
53            "attempt": 1,
54            "images": {
55              "original_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_front.jpeg",
56              "original_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_back.jpeg",
57              "cropped_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
58              "cropped_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
59              "face": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/face.jpeg"
60            },
61            "extracted_data": {
62              "id_number": "AB123456",
63              "category": "drivers_license",
64              "expiration_date": "1990-05-29",
65              "issuing_country": "US",
66              "issuing_subdivision": "IN"
67            },
68            "analysis": {
69              "authenticity": "match",
70              "image_quality": "high",
71              "extracted_data": {
72                "name": "match",
73                "date_of_birth": "match",
74                "expiration_date": "not_expired",
75                "issuing_country": "match"
76              }
77            },
78            "redacted_at": "2020-07-24T03:26:02Z"
79          }
80        ]
81      },
82      "selfie_check": {
83        "status": "success",
84        "selfies": [
85          {
86            "status": "success",
87            "attempt": 1,
88            "capture": {
89              "image_url": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/selfie/liveness.jpeg",
90              "video_url": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/selfie/liveness.webm"
91            },
92            "analysis": {
93              "document_comparison": "match"
94            }
95          }
96        ]
97      },
98      "kyc_check": {
99        "status": "success",
100        "address": {
101          "summary": "match",
102          "po_box": "yes",
103          "type": "residential"
104        },
105        "name": {
106          "summary": "match"
107        },
108        "date_of_birth": {
109          "summary": "match"
110        },
111        "id_number": {
112          "summary": "match"
113        },
114        "phone": {
115          "summary": "match"
116        }
117      },
118      "risk_check": {
119        "status": "waiting_for_prerequisite",
120        "behavior": {
121          "user_interactions": "risky",
122          "fraud_ring_detected": "yes",
123          "bot_detected": "yes"
124        },
125        "email": {
126          "is_deliverable": "yes",
127          "breach_count": 1,
128          "first_breached_at": "1990-05-29",
129          "last_breached_at": "1990-05-29",
130          "domain_registered_at": "1990-05-29",
131          "domain_is_free_provider": "yes",
132          "domain_is_custom": "yes",
133          "domain_is_disposable": "yes",
134          "top_level_domain_is_suspicious": "yes",
135          "linked_services": [
136            "apple"
137          ]
138        },
139        "phone": {
140          "linked_services": [
141            "apple"
142          ]
143        },
144        "devices": [
145          {
146            "ip_spam_list_count": 1
147          }
148        ]
149      },
150      "screening_id": "scr_52xR9LKo77r1Np",
151      "redacted_at": "2020-07-24T03:26:02Z",
152      "_meta": "This API format is not v1.0 and is subject to change."
153    }
154  ],
155  "links": {
156    "previous": "http://cognitohq.com",
157    "next": "http://cognitohq.com"
158  }
159}

Create Flow Session

Create a new FlowSession, linked to the provided template_id and customer_reference. If you don't know whether the associated user already has a FlowSession, you can provide the query parameter ?idempotent=true. With idempotency enabled, a new FlowSession will be created if one does not already exist for the associated customer_reference and template_id. If a FlowSession is found, it will be returned unmodified with an 200 OK HTTP status code.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Query Parameters

idempotentoptionalboolean

An optional flag specifying how you would like Cognito to handle attempts to create a FlowSession when a FlowSession already exists for the provided customer_reference and template_id.

If idempotency is enabled, Cognito will return existing FlowSessions with an HTTP status code of 200 OK. If idempotency is disabled, Cognito will reject the request if a FlowSession already exists for the supplied customer_reference and template_id.

Idempotency defaults to false when omitted.

Request Body

shareablerequiredboolean

View in sample
JSON

A flag specifying whether you would like Cognito to expose a shareable URL for the session being created.

template_idrequiredstring

View in sample
JSON

ID of the associated Flow template.

View in sample
JSON

A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Cognito for verification purposes.


If consent is set to true, the accept_tos step will be marked as skipped and the end user's session

will start at the next step requirement.


If omitted, this field will default to false.

userrequiredobject

View in sample
JSON

User information collected outside of Flow, most likely via your own onboarding process.


Each of the following identity fields are optional:

  • email
  • phone
  • date_of_birth
  • name
  • address
  • id_number


Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema)

or omitted from the request entirely by not providing the key or value.


Providing these fields via the API will result in the Flow UI skipping the data collection process for the associated user. All verification steps enabled in the associated Flow Template will still be run. Verification steps will either be run immediately, or once the user completes the accept_tos step, depending on the value provided to the consent field.

Hide child attributes

user.customer_referencerequiredstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

user.emailoptionalstring

View in sample
JSON

A valid email address.

user.phoneoptionalstring

View in sample
JSON

A phone number in E.164 format.

user.date_of_birthoptionalstring

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

user.nameoptionalobject

View in sample
JSON

You can use this field to pre-populate the user's legal name; if it is provided here, they will not be prompted to enter their name in the flow session.

Hide child attributes

user.name.firstrequiredstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

user.name.lastrequiredstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

user.addressoptionalobject

View in sample
JSON
Hide child attributes

user.address.streetrequiredstring

View in sample
JSON

The primary street portion of an address. If the user has submitted their address, this field will always be filled.

user.address.street2optionalstring

View in sample
JSON

Extra street information, like an apartment or suite number.

user.address.cityrequiredstring

View in sample
JSON

City from the end user's address

user.address.subdivisionrequiredstring

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

user.address.postal_coderequiredstring

View in sample
JSON

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

user.address.country_coderequiredstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

user.id_numberoptionalobject

View in sample
JSON

ID number submitted by the user. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

Hide child attributes

user.id_number.valuerequiredstring

View in sample
JSON

Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.

user.id_number.typerequiredstring

View in sample
JSON

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Flow Hybrid Input Validation](https://cognitohq.com/docs/flow/flow-hybrid-input-validation)

Possible enum values

ar_dniau_drivers_licenseau_passportbr_cpfca_sincl_runcn_resident_cardco_nitdk_cpreg_national_ides_dnies_niehk_hkidin_panit_cfjo_civil_idjp_my_numberke_huduma_nambakw_civil_idmx_curpmx_rfcmy_nricng_ninnz_drivers_licenseom_civil_idph_psnpl_peselro_cnpsa_national_idse_pinsg_nrictr_tc_kimlikus_ssnus_ssn_last_4za_smart_id
Response Schema

idalways presentstring

View in sample
JSON

ID of the associated Flow session.

customer_referencealways presentstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

completed_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the Flow Session terminated

An ISO8601 formatted timestamp.

previous_session_idalways presentstringNULLABLE

View in sample
JSON

The ID of the previous Flow Session, if any.

The ID for the Flow Session preceding this session. This field will only be filled if the current Flow Session is a retry of a previous session.

shareable_urlalways presentstringNULLABLE

View in sample
JSON

A shareable URL that can be sent directly to the user to complete verification

templatealways presentobject

View in sample
JSON
Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated Flow template.

versionalways presentnumber

View in sample
JSON

Version of the associated Flow template.

useralways presentobject

View in sample
JSON
Hide child attributes

phonealways presentstringNULLABLE

View in sample
JSON

A phone number in E.164 format.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

ip_addressalways presentstringNULLABLE

View in sample
JSON

IP Address collected from the user's Flow Session. Can be either an IPv4 or IPv6 address. If the address is representable as IPv4, it will be returned as IPv4.


Note: This field can be null if the user has not yet interacted with Flow's frontend, either because they haven't started their session yet or because their session was created via API using Flow hybrid.

An IPv4 or IPV6 address.

emailalways presentstringNULLABLE

View in sample
JSON

The user email you programmatically provided to your Flow integration.

A valid email address.

namealways presentobjectNULLABLE

View in sample
JSON

The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

Hide child attributes

firstalways presentstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

lastalways presentstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

addressalways presentobjectNULLABLE

View in sample
JSON

The address data submitted by the user. If the user has not submitted their address, this field will be null. Otherwise, it will be an object and street, city, and country_code are guaranteed to be filled. The remaining fields differ based the region's addressing system. For example:

  • Addresses from the United Kingdom will not include a subdivision
  • Addresses from Hong Kong will not include postal code

Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: * Addresses from the United Kingdom will not include a region * Addresses from Hong Kong will not include postal code

Hide child attributes

streetalways presentstringNULLABLE

View in sample
JSON

The primary street portion of an address. If the user has submitted their address, this field will always be filled.

street2always presentstringNULLABLE

View in sample
JSON

Extra street information, like an apartment or suite number.

cityalways presentstringNULLABLE

View in sample
JSON

City from the end user's address

subdivisionalways presentstringNULLABLE

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

postal_codealways presentstringNULLABLE

View in sample
JSON

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

country_codealways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

id_numberalways presentobjectNULLABLE

View in sample
JSON

ID Number submitted by the user. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

Type and value of ID number provided

Hide child attributes

valuealways presentstring

View in sample
JSON

Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.

categoryalways presentstring

View in sample
JSON

The category of identity document provided

Possible enum values

drivers_licensepassportpersonal_identificationtax_idvoter_id

typealways presentstring

View in sample
JSON

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Flow Hybrid Input Validation](https://cognitohq.com/docs/flow/flow-hybrid-input-validation)

Possible enum values

ar_dniau_drivers_licenseau_passportbr_cpfca_sincl_runcn_resident_cardco_nitdk_cpreg_national_ides_dnies_niehk_hkidin_panit_cfjo_civil_idjp_my_numberke_huduma_nambakw_civil_idmx_curpmx_rfcmy_nricng_ninnz_drivers_licenseom_civil_idph_psnpl_peselro_cnpsa_national_idse_pinsg_nrictr_tc_kimlikus_ssnus_ssn_last_4za_smart_id

statusalways presentstring

View in sample
JSON

The status of this Flow session.

  • active - The Flow session is incomplete. The user may have completed part of the session, but has neither failed or passed.
  • success - The Flow session has completed, passing all steps defined to the associated Flow template
  • failed - The user failed one or more steps in the session and was told to contact support.
  • expired - The Flow session was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.
  • canceled - The Flow session was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.
  • pending_review - The Flow session template was configured to perform a screening that had one or more hits needing review.

Possible enum values

activesuccessfailedexpiredcanceledpending_review

stepsalways presentobject

View in sample
JSON

Each step will be one of the following values:

  • active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Flow session while in the middle of this step. Only one step will be marked as active at any given point.
  • success - The Flow session has completed this step.
  • failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Flow template is configured. A failed step does not imply a failed session.
  • waiting_for_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback.
  • not_applicable - This step will not be run for this session.
  • skipped - The retry instructions that created this Flow session specified that this step should be skipped.
  • expired - This step had not yet been completed when the Flow session as a whole expired.
  • canceled - The Flow session was canceled before the user completed this step.
  • pending_review - The Flow session template was configured to perform a screening that had one or more hits needing review.
  • manually_approved - The step was manually overridden to pass by a team member in the dashboard.
  • manually_rejected - The step was manually overridden to fail by a team member in the dashboard.
Hide child attributes

accept_tosalways presentstring

View in sample
JSON

The status of the accept_tos step. This step will always come first.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

verify_smsalways presentstring

View in sample
JSON

The status of the SMS verification step. Failing this step means the user either entered an incorrect code twice or the verification code has expired.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

kyc_screenalways presentstring

View in sample
JSON

Deprecated.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

kyc_checkalways presentstring

View in sample
JSON

The status of the full KYC check step (referred to as the "Know your Customer" use case in the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

documentary_verificationalways presentstring

View in sample
JSON

The status of the documentary verification check step (configured via "Fallback Settings" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

selfie_checkalways presentstring

View in sample
JSON

The status of the selfie check step (configured via "Selfie Check Behavior" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

screeningalways presentstring

View in sample
JSON

The status of the watchlist screening step, always run last. No user input is prompted for this step. The status will be pending_review when there are unreviewed hits. Once hits are reviewed, the status will be changed to manually_approved or manually_rejected, as appropriate.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

risk_checkalways presentstring

View in sample
JSON

The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

documentary_verificationalways presentobjectNULLABLE

View in sample
JSON

Data, images, analysis, and results from the documentary_verification step. This field will be null unless steps.documentary_verification has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's documentary_verification step. This field will always have the same value as steps.documentary_verification.

documentsalways presentarray of objects

View in sample
JSON

An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.


Note: Flow will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.

Hide child attributes

statusalways presentstring

View in sample
JSON

An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible enum values

successfailedmanually_approved

attemptalways presentnumber

View in sample
JSON

The attempt field begins with 1 and increments with each subsequent document upload.

imagesalways presentobject

View in sample
JSON

URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Flow session. A new expiring URL is generated with each request, so you can always rerequest the Flow session if one of your URLs expires.

Hide child attributes

original_frontalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.

original_backalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.

cropped_frontalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.

cropped_backalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.

facealways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.

extracted_dataalways presentobjectNULLABLE

View in sample
JSON

Information extracted from the document images provided.


Note: This field might be null in the case where a document could not be detected in the image provided (either due to the image not containing a document or due to poor image quality)

Data extracted from a user-submitted document.

Hide child attributes

id_numberalways presentstringNULLABLE

View in sample
JSON

Alpha-numeric ID number extracted via OCR from the user's document image.

categoryalways presentstring

View in sample
JSON

The type of identity document detected in the images provided. Will always be one of the following values:

  • drivers_license - A driver's license for the associated country

  • id_card - A general national identification card, distinct from driver's licenses

  • passport - A passport for the associated country

  • residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country

  • resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country


Note: This value may be different from the ID type that the user selects within Flow's UI. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible enum values

drivers_licenseid_cardpassportresidence_permit_cardresident_card

expiration_datealways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

issuing_countryalways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

issuing_subdivisionalways presentstringNULLABLE

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

analysisalways presentobject

View in sample
JSON

High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.

Hide child attributes

authenticityalways presentstring

View in sample
JSON

High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.


For example, most identity documents have formatting rules like the following:

  • The image of the person's face must have a certain contrast in order to highlight skin tone

  • The subject in the document's image must remove eye glasses and pose in a certain way

  • The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules

  • Security features like watermarks and background patterns must be present

So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible enum values

matchpartial_matchno_matchno_data

image_qualityalways presentstring

View in sample
JSON

A high level description of the quality of the image the user submitted.


For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.


Note: By default, Flow will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible enum values

highmediumlow

extracted_dataalways presentobjectNULLABLE

View in sample
JSON

This section summarizes checks Cognito performed against the data that was extracted from the document image.

Analysis of the data extracted from the submitted document.

Hide child attributes

namealways presentstring

View in sample
JSON

A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to flow session.

Possible enum values

matchpartial_matchno_match

date_of_birthalways presentstring

View in sample
JSON

A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the flow session.

Possible enum values

matchpartial_matchno_match

expiration_datealways presentstring

View in sample
JSON

A description of whether the associated document was expired when the verification was performed.


Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible enum values

not_expiredexpiredno_data

issuing_countryalways presentstring

View in sample
JSON

A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Flow.


Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Flow Template.

Possible enum values

matchno_match

redacted_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the document was redacted

An ISO8601 formatted timestamp.

selfie_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the selfie_check step. This field will be null unless steps.selfie_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's selfie_check step. This field will always have the same value as steps.selfie_check.

Possible enum values

successfailed

selfiesalways presentarray of objects

View in sample
JSON

An array of selfies submitted to the selfie_check step. Each entry represents one user submission.

Hide child attributes

statusalways presentstring

View in sample
JSON

An outcome status for this specific selfie. Distinct from the overall selfie_check.status that summarizes the verification outcome from one or more selfies.

Possible enum values

successfailed

attemptalways presentinteger

View in sample
JSON

The attempt field begins with 1 and increments with each subsequent selfie upload.

capturealways presentobject

View in sample
JSON

The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.

Hide child attributes

image_urlmight be omittedstringNULLABLE

View in sample
JSON

Temporary URL for downloading an image selfie capture.

video_urlmight be omittedstringNULLABLE

View in sample
JSON

Temporary URL for downloading a video selfie capture.

analysisalways presentobject

View in sample
JSON

High level descriptions of how the associated selfie was processed. If a seflfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.

Hide child attributes

document_comparisonalways presentstring

View in sample
JSON

Information about the comparison between the selfie and the document (if documentary verification also ran).

Possible enum values

matchno_matchno_input

kyc_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's kyc_check step. This field will always have the same value as steps.kyc_check.

addressalways presentobject

View in sample
JSON

Result summary object specifying how the address field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

po_boxalways presentstring

View in sample
JSON

Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Cognito confirmed the address is not a P.O. box, and no_data when Cognito was not able to determine if the address is a P.O. box.

Possible enum values

yesnono_data

typealways presentstring

View in sample
JSON

Field describing whether the associated address is being used for commercial or residential purposes.


Note: This value will be no_data when Cognito does not have sufficient data to determine the address's use.

Possible enum values

residentialcommercialno_data

namealways presentobject

View in sample
JSON

Result summary object specifying how the name field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

date_of_birthalways presentobject

View in sample
JSON

Result summary object specifying how the date_of_birth field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

id_numberalways presentobject

View in sample
JSON

Result summary object specifying how the id_number field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

phonealways presentobject

View in sample
JSON

Result summary object specifying how the phone field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

risk_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the risk_check step. This field will be null unless steps.risk_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

behavioralways presentobjectNULLABLE

View in sample
JSON

The attributes from the behavior risk check, when available.

Result summary object specifying values for behavior attributes of risk check, when available.

Hide child attributes

user_interactionsalways presentstring

View in sample
JSON

Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session.

  • genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.
  • neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome.
  • risky indicates the user has low familiarity with the data they are providing, and that fraud is likely.
  • no_data indicates there is not sufficient information to give an accurate signal.

Possible enum values

genuineneutralriskyno_data

fraud_ring_detectedalways presentstring

View in sample
JSON

Field describing the outcome of a fraud ring behavior risk check.

  • yes indicates that fraud ring activity was detected.
  • no indicates that fraud ring activity was not detected.
  • no_data indicates there was not enough information available to give an accurate signal.

Possible enum values

yesnono_data

bot_detectedalways presentstring

View in sample
JSON

Field describing the outcome of a bot detection behavior risk check.

  • yes indicates that automated activity was detected.
  • no indicates that automated activity was not detected.
  • no_data indicates there was not enough information available to give an accurate signal.

Possible enum values

yesnono_data

emailalways presentobjectNULLABLE

View in sample
JSON

The attributes from the email risk check, when available.

Result summary object specifying values for email attributes of risk check.

Hide child attributes

is_deliverablealways presentstring

View in sample
JSON

SMTP-MX check to confirm the email address exists if known.

Possible enum values

yesnono_data

breach_countalways presentinteger

View in sample
JSON

Count of all known breaches of this email address if known.

first_breached_atalways presentstringNULLABLE

View in sample
JSON

First known date this email address was breached if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

last_breached_atalways presentstringNULLABLE

View in sample
JSON

Last known date this email address was breached if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

domain_registered_atalways presentstringNULLABLE

View in sample
JSON

Timestamp domain was registered at if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

domain_is_free_provideralways presentstring

View in sample
JSON

Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known.

Possible enum values

yesnono_data

domain_is_customalways presentstring

View in sample
JSON

Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable.

Possible enum values

yesnono_data

domain_is_disposablealways presentstring

View in sample
JSON

Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details.

Possible enum values

yesnono_data

top_level_domain_is_suspiciousalways presentstring

View in sample
JSON

Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain.

Possible enum values

yesnono_data

linked_servicesalways presentarray of strings

View in sample
JSON

Possible enum values

appleebayfacebookflickrfoursquaregithubgooglegravatarinstagramlastfmlinkedinmicrosoftmyspacepinterestskypespotifytelegramtumblrtwittervibervimeoweibowhatsappyahooairbnbamazonbookingdiscordkakaookqzonelinesnapchatzalo

phonealways presentobjectNULLABLE

View in sample
JSON

The attributes from the phone risk check, when available.

Result summary object specifying values for phone attributes of risk check.

Hide child attributes

linked_servicesalways presentarray of strings

View in sample
JSON

Possible enum values

appleebayfacebookflickrfoursquaregithubgooglegravatarinstagramlastfmlinkedinmicrosoftmyspacepinterestskypespotifytelegramtumblrtwittervibervimeoweibowhatsappyahooairbnbamazonbookingdiscordkakaookqzonelinesnapchatzalo

devicesalways presentarray of objects

View in sample
JSON

Array of result summary objects specifying values for device attributes of risk check.

Hide child attributes

ip_proxy_typealways presentstringNULLABLE

View in sample
JSON

An enum indicating whether a network proxy is present and if so what type it is. * none_detected indicates the user is not on a detectable proxy network. * tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). * vpn indicates the user is on a VPN (Virtual Private Network) * web_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. * public_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.

ip_spam_list_countalways presentinteger

View in sample
JSON

Count of spam lists the IP address is associated with if known.

ip_timezone_offsetalways presentstringNULLABLE

View in sample
JSON

UTC offset of the timezone associated with the IP address if known.

UTC offset of the timezone associated with the IP address.

screening_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated screening.

redacted_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the Flow Session was redacted

An ISO8601 formatted timestamp.

_metamight be omittedstring

View in sample
JSON

A friendly reminder that this API is still being developed and might change in the future. If we do choose to make a backwards incompatible change before this API hits 1.0, we will notify you by email with details and a deprecation timeline.

POST

/flow_sessions

1{
2  "shareable": true,
3  "template_id": "flwtmp_4FrXJvfQU3zGUR",
4  "consent": true,
5  "user": {
6    "customer_reference": "your-db-id-3b24110",
7    "email": "user@example.com",
8    "phone": "+19876543212",
9    "date_of_birth": "1975-01-18",
10    "name": {
11      "first": "Leslie",
12      "last": "Knope"
13    },
14    "address": {
15      "street": "123 Main St.",
16      "street2": "Unit 42",
17      "city": "Pawnee",
18      "subdivision": "IN",
19      "postal_code": "46001",
20      "country_code": "US"
21    },
22    "id_number": {
23      "value": "123456789",
24      "type": "us_ssn"
25    }
26  }
27}
Response Sample
Copy JSON
1{
2  "id": "flwses_52xR9LKo77r1Np",
3  "customer_reference": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_session_id": "flwses_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.cognitohq.com/verify/flwtmp_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "flwtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone": "+19876543212",
14    "date_of_birth": "1975-01-18",
15    "ip_address": "192.0.2.42",
16    "email": "user@example.com",
17    "name": {
18      "first": "Leslie",
19      "last": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "subdivision": "IN",
26      "postal_code": "46001",
27      "country_code": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "category": "tax_id",
32      "type": "us_ssn"
33    }
34  },
35  "status": "success",
36  "steps": {
37    "accept_tos": "success",
38    "verify_sms": "success",
39    "kyc_screen": "not_applicable",
40    "kyc_check": "active",
41    "documentary_verification": "waiting_for_prerequisite",
42    "selfie_check": "waiting_for_prerequisite",
43    "screening": "waiting_for_prerequisite",
44    "risk_check": "waiting_for_prerequisite"
45  },
46  "documentary_verification": {
47    "status": "success",
48    "documents": [
49      {
50        "status": "success",
51        "attempt": 1,
52        "images": {
53          "original_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_front.jpeg",
54          "original_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_back.jpeg",
55          "cropped_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
56          "cropped_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
57          "face": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/face.jpeg"
58        },
59        "extracted_data": {
60          "id_number": "AB123456",
61          "category": "drivers_license",
62          "expiration_date": "1990-05-29",
63          "issuing_country": "US",
64          "issuing_subdivision": "IN"
65        },
66        "analysis": {
67          "authenticity": "match",
68          "image_quality": "high",
69          "extracted_data": {
70            "name": "match",
71            "date_of_birth": "match",
72            "expiration_date": "not_expired",
73            "issuing_country": "match"
74          }
75        },
76        "redacted_at": "2020-07-24T03:26:02Z"
77      }
78    ]
79  },
80  "selfie_check": {
81    "status": "success",
82    "selfies": [
83      {
84        "status": "success",
85        "attempt": 1,
86        "capture": {
87          "image_url": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/selfie/liveness.jpeg",
88          "video_url": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/selfie/liveness.webm"
89        },
90        "analysis": {
91          "document_comparison": "match"
92        }
93      }
94    ]
95  },
96  "kyc_check": {
97    "status": "success",
98    "address": {
99      "summary": "match",
100      "po_box": "yes",
101      "type": "residential"
102    },
103    "name": {
104      "summary": "match"
105    },
106    "date_of_birth": {
107      "summary": "match"
108    },
109    "id_number": {
110      "summary": "match"
111    },
112    "phone": {
113      "summary": "match"
114    }
115  },
116  "risk_check": {
117    "status": "waiting_for_prerequisite",
118    "behavior": {
119      "user_interactions": "risky",
120      "fraud_ring_detected": "yes",
121      "bot_detected": "yes"
122    },
123    "email": {
124      "is_deliverable": "yes",
125      "breach_count": 1,
126      "first_breached_at": "1990-05-29",
127      "last_breached_at": "1990-05-29",
128      "domain_registered_at": "1990-05-29",
129      "domain_is_free_provider": "yes",
130      "domain_is_custom": "yes",
131      "domain_is_disposable": "yes",
132      "top_level_domain_is_suspicious": "yes",
133      "linked_services": [
134        "apple"
135      ]
136    },
137    "phone": {
138      "linked_services": [
139        "apple"
140      ]
141    },
142    "devices": [
143      {
144        "ip_spam_list_count": 1
145      }
146    ]
147  },
148  "screening_id": "scr_52xR9LKo77r1Np",
149  "redacted_at": "2020-07-24T03:26:02Z",
150  "_meta": "This API format is not v1.0 and is subject to change."
151}

Retrieve Flow Session

Get the current state of a specific FlowSession.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Path Parameters

idrequiredstring

The ID of the FlowSession to retrieve.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated Flow session.

customer_referencealways presentstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

completed_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the Flow Session terminated

An ISO8601 formatted timestamp.

previous_session_idalways presentstringNULLABLE

View in sample
JSON

The ID of the previous Flow Session, if any.

The ID for the Flow Session preceding this session. This field will only be filled if the current Flow Session is a retry of a previous session.

shareable_urlalways presentstringNULLABLE

View in sample
JSON

A shareable URL that can be sent directly to the user to complete verification

templatealways presentobject

View in sample
JSON
Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated Flow template.

versionalways presentnumber

View in sample
JSON

Version of the associated Flow template.

useralways presentobject

View in sample
JSON
Hide child attributes

phonealways presentstringNULLABLE

View in sample
JSON

A phone number in E.164 format.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

ip_addressalways presentstringNULLABLE

View in sample
JSON

IP Address collected from the user's Flow Session. Can be either an IPv4 or IPv6 address. If the address is representable as IPv4, it will be returned as IPv4.


Note: This field can be null if the user has not yet interacted with Flow's frontend, either because they haven't started their session yet or because their session was created via API using Flow hybrid.

An IPv4 or IPV6 address.

emailalways presentstringNULLABLE

View in sample
JSON

The user email you programmatically provided to your Flow integration.

A valid email address.

namealways presentobjectNULLABLE

View in sample
JSON

The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

Hide child attributes

firstalways presentstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

lastalways presentstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

addressalways presentobjectNULLABLE

View in sample
JSON

The address data submitted by the user. If the user has not submitted their address, this field will be null. Otherwise, it will be an object and street, city, and country_code are guaranteed to be filled. The remaining fields differ based the region's addressing system. For example:

  • Addresses from the United Kingdom will not include a subdivision
  • Addresses from Hong Kong will not include postal code

Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: * Addresses from the United Kingdom will not include a region * Addresses from Hong Kong will not include postal code

Hide child attributes

streetalways presentstringNULLABLE

View in sample
JSON

The primary street portion of an address. If the user has submitted their address, this field will always be filled.

street2always presentstringNULLABLE

View in sample
JSON

Extra street information, like an apartment or suite number.

cityalways presentstringNULLABLE

View in sample
JSON

City from the end user's address

subdivisionalways presentstringNULLABLE

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

postal_codealways presentstringNULLABLE

View in sample
JSON

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

country_codealways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

id_numberalways presentobjectNULLABLE

View in sample
JSON

ID Number submitted by the user. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

Type and value of ID number provided

Hide child attributes

valuealways presentstring

View in sample
JSON

Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.

categoryalways presentstring

View in sample
JSON

The category of identity document provided

Possible enum values

drivers_licensepassportpersonal_identificationtax_idvoter_id

typealways presentstring

View in sample
JSON

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Flow Hybrid Input Validation](https://cognitohq.com/docs/flow/flow-hybrid-input-validation)

Possible enum values

ar_dniau_drivers_licenseau_passportbr_cpfca_sincl_runcn_resident_cardco_nitdk_cpreg_national_ides_dnies_niehk_hkidin_panit_cfjo_civil_idjp_my_numberke_huduma_nambakw_civil_idmx_curpmx_rfcmy_nricng_ninnz_drivers_licenseom_civil_idph_psnpl_peselro_cnpsa_national_idse_pinsg_nrictr_tc_kimlikus_ssnus_ssn_last_4za_smart_id

statusalways presentstring

View in sample
JSON

The status of this Flow session.

  • active - The Flow session is incomplete. The user may have completed part of the session, but has neither failed or passed.
  • success - The Flow session has completed, passing all steps defined to the associated Flow template
  • failed - The user failed one or more steps in the session and was told to contact support.
  • expired - The Flow session was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.
  • canceled - The Flow session was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.
  • pending_review - The Flow session template was configured to perform a screening that had one or more hits needing review.

Possible enum values

activesuccessfailedexpiredcanceledpending_review

stepsalways presentobject

View in sample
JSON

Each step will be one of the following values:

  • active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Flow session while in the middle of this step. Only one step will be marked as active at any given point.
  • success - The Flow session has completed this step.
  • failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Flow template is configured. A failed step does not imply a failed session.
  • waiting_for_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback.
  • not_applicable - This step will not be run for this session.
  • skipped - The retry instructions that created this Flow session specified that this step should be skipped.
  • expired - This step had not yet been completed when the Flow session as a whole expired.
  • canceled - The Flow session was canceled before the user completed this step.
  • pending_review - The Flow session template was configured to perform a screening that had one or more hits needing review.
  • manually_approved - The step was manually overridden to pass by a team member in the dashboard.
  • manually_rejected - The step was manually overridden to fail by a team member in the dashboard.
Hide child attributes

accept_tosalways presentstring

View in sample
JSON

The status of the accept_tos step. This step will always come first.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

verify_smsalways presentstring

View in sample
JSON

The status of the SMS verification step. Failing this step means the user either entered an incorrect code twice or the verification code has expired.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

kyc_screenalways presentstring

View in sample
JSON

Deprecated.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

kyc_checkalways presentstring

View in sample
JSON

The status of the full KYC check step (referred to as the "Know your Customer" use case in the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

documentary_verificationalways presentstring

View in sample
JSON

The status of the documentary verification check step (configured via "Fallback Settings" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

selfie_checkalways presentstring

View in sample
JSON

The status of the selfie check step (configured via "Selfie Check Behavior" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

screeningalways presentstring

View in sample
JSON

The status of the watchlist screening step, always run last. No user input is prompted for this step. The status will be pending_review when there are unreviewed hits. Once hits are reviewed, the status will be changed to manually_approved or manually_rejected, as appropriate.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

risk_checkalways presentstring

View in sample
JSON

The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

documentary_verificationalways presentobjectNULLABLE

View in sample
JSON

Data, images, analysis, and results from the documentary_verification step. This field will be null unless steps.documentary_verification has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's documentary_verification step. This field will always have the same value as steps.documentary_verification.

documentsalways presentarray of objects

View in sample
JSON

An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.


Note: Flow will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.

Hide child attributes

statusalways presentstring

View in sample
JSON

An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible enum values

successfailedmanually_approved

attemptalways presentnumber

View in sample
JSON

The attempt field begins with 1 and increments with each subsequent document upload.

imagesalways presentobject

View in sample
JSON

URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Flow session. A new expiring URL is generated with each request, so you can always rerequest the Flow session if one of your URLs expires.

Hide child attributes

original_frontalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.

original_backalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.

cropped_frontalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.

cropped_backalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.

facealways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.

extracted_dataalways presentobjectNULLABLE

View in sample
JSON

Information extracted from the document images provided.


Note: This field might be null in the case where a document could not be detected in the image provided (either due to the image not containing a document or due to poor image quality)

Data extracted from a user-submitted document.

Hide child attributes

id_numberalways presentstringNULLABLE

View in sample
JSON

Alpha-numeric ID number extracted via OCR from the user's document image.

categoryalways presentstring

View in sample
JSON

The type of identity document detected in the images provided. Will always be one of the following values:

  • drivers_license - A driver's license for the associated country

  • id_card - A general national identification card, distinct from driver's licenses

  • passport - A passport for the associated country

  • residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country

  • resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country


Note: This value may be different from the ID type that the user selects within Flow's UI. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible enum values

drivers_licenseid_cardpassportresidence_permit_cardresident_card

expiration_datealways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

issuing_countryalways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

issuing_subdivisionalways presentstringNULLABLE

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

analysisalways presentobject

View in sample
JSON

High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.

Hide child attributes

authenticityalways presentstring

View in sample
JSON

High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.


For example, most identity documents have formatting rules like the following:

  • The image of the person's face must have a certain contrast in order to highlight skin tone

  • The subject in the document's image must remove eye glasses and pose in a certain way

  • The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules

  • Security features like watermarks and background patterns must be present

So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible enum values

matchpartial_matchno_matchno_data

image_qualityalways presentstring

View in sample
JSON

A high level description of the quality of the image the user submitted.


For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.


Note: By default, Flow will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible enum values

highmediumlow

extracted_dataalways presentobjectNULLABLE

View in sample
JSON

This section summarizes checks Cognito performed against the data that was extracted from the document image.

Analysis of the data extracted from the submitted document.

Hide child attributes

namealways presentstring

View in sample
JSON

A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to flow session.

Possible enum values

matchpartial_matchno_match

date_of_birthalways presentstring

View in sample
JSON

A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the flow session.

Possible enum values

matchpartial_matchno_match

expiration_datealways presentstring

View in sample
JSON

A description of whether the associated document was expired when the verification was performed.


Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible enum values

not_expiredexpiredno_data

issuing_countryalways presentstring

View in sample
JSON

A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Flow.


Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Flow Template.

Possible enum values

matchno_match

redacted_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the document was redacted

An ISO8601 formatted timestamp.

selfie_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the selfie_check step. This field will be null unless steps.selfie_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's selfie_check step. This field will always have the same value as steps.selfie_check.

Possible enum values

successfailed

selfiesalways presentarray of objects

View in sample
JSON

An array of selfies submitted to the selfie_check step. Each entry represents one user submission.

Hide child attributes

statusalways presentstring

View in sample
JSON

An outcome status for this specific selfie. Distinct from the overall selfie_check.status that summarizes the verification outcome from one or more selfies.

Possible enum values

successfailed

attemptalways presentinteger

View in sample
JSON

The attempt field begins with 1 and increments with each subsequent selfie upload.

capturealways presentobject

View in sample
JSON

The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.

Hide child attributes

image_urlmight be omittedstringNULLABLE

View in sample
JSON

Temporary URL for downloading an image selfie capture.

video_urlmight be omittedstringNULLABLE

View in sample
JSON

Temporary URL for downloading a video selfie capture.

analysisalways presentobject

View in sample
JSON

High level descriptions of how the associated selfie was processed. If a seflfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.

Hide child attributes

document_comparisonalways presentstring

View in sample
JSON

Information about the comparison between the selfie and the document (if documentary verification also ran).

Possible enum values

matchno_matchno_input

kyc_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's kyc_check step. This field will always have the same value as steps.kyc_check.

addressalways presentobject

View in sample
JSON

Result summary object specifying how the address field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

po_boxalways presentstring

View in sample
JSON

Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Cognito confirmed the address is not a P.O. box, and no_data when Cognito was not able to determine if the address is a P.O. box.

Possible enum values

yesnono_data

typealways presentstring

View in sample
JSON

Field describing whether the associated address is being used for commercial or residential purposes.


Note: This value will be no_data when Cognito does not have sufficient data to determine the address's use.

Possible enum values

residentialcommercialno_data

namealways presentobject

View in sample
JSON

Result summary object specifying how the name field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

date_of_birthalways presentobject

View in sample
JSON

Result summary object specifying how the date_of_birth field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

id_numberalways presentobject

View in sample
JSON

Result summary object specifying how the id_number field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

phonealways presentobject

View in sample
JSON

Result summary object specifying how the phone field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

risk_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the risk_check step. This field will be null unless steps.risk_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

behavioralways presentobjectNULLABLE

View in sample
JSON

The attributes from the behavior risk check, when available.

Result summary object specifying values for behavior attributes of risk check, when available.

Hide child attributes

user_interactionsalways presentstring

View in sample
JSON

Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session.

  • genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.
  • neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome.
  • risky indicates the user has low familiarity with the data they are providing, and that fraud is likely.
  • no_data indicates there is not sufficient information to give an accurate signal.

Possible enum values

genuineneutralriskyno_data

fraud_ring_detectedalways presentstring

View in sample
JSON

Field describing the outcome of a fraud ring behavior risk check.

  • yes indicates that fraud ring activity was detected.
  • no indicates that fraud ring activity was not detected.
  • no_data indicates there was not enough information available to give an accurate signal.

Possible enum values

yesnono_data

bot_detectedalways presentstring

View in sample
JSON

Field describing the outcome of a bot detection behavior risk check.

  • yes indicates that automated activity was detected.
  • no indicates that automated activity was not detected.
  • no_data indicates there was not enough information available to give an accurate signal.

Possible enum values

yesnono_data

emailalways presentobjectNULLABLE

View in sample
JSON

The attributes from the email risk check, when available.

Result summary object specifying values for email attributes of risk check.

Hide child attributes

is_deliverablealways presentstring

View in sample
JSON

SMTP-MX check to confirm the email address exists if known.

Possible enum values

yesnono_data

breach_countalways presentinteger

View in sample
JSON

Count of all known breaches of this email address if known.

first_breached_atalways presentstringNULLABLE

View in sample
JSON

First known date this email address was breached if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

last_breached_atalways presentstringNULLABLE

View in sample
JSON

Last known date this email address was breached if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

domain_registered_atalways presentstringNULLABLE

View in sample
JSON

Timestamp domain was registered at if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

domain_is_free_provideralways presentstring

View in sample
JSON

Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known.

Possible enum values

yesnono_data

domain_is_customalways presentstring

View in sample
JSON

Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable.

Possible enum values

yesnono_data

domain_is_disposablealways presentstring

View in sample
JSON

Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details.

Possible enum values

yesnono_data

top_level_domain_is_suspiciousalways presentstring

View in sample
JSON

Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain.

Possible enum values

yesnono_data

linked_servicesalways presentarray of strings

View in sample
JSON

Possible enum values

appleebayfacebookflickrfoursquaregithubgooglegravatarinstagramlastfmlinkedinmicrosoftmyspacepinterestskypespotifytelegramtumblrtwittervibervimeoweibowhatsappyahooairbnbamazonbookingdiscordkakaookqzonelinesnapchatzalo

phonealways presentobjectNULLABLE

View in sample
JSON

The attributes from the phone risk check, when available.

Result summary object specifying values for phone attributes of risk check.

Hide child attributes

linked_servicesalways presentarray of strings

View in sample
JSON

Possible enum values

appleebayfacebookflickrfoursquaregithubgooglegravatarinstagramlastfmlinkedinmicrosoftmyspacepinterestskypespotifytelegramtumblrtwittervibervimeoweibowhatsappyahooairbnbamazonbookingdiscordkakaookqzonelinesnapchatzalo

devicesalways presentarray of objects

View in sample
JSON

Array of result summary objects specifying values for device attributes of risk check.

Hide child attributes

ip_proxy_typealways presentstringNULLABLE

View in sample
JSON

An enum indicating whether a network proxy is present and if so what type it is. * none_detected indicates the user is not on a detectable proxy network. * tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). * vpn indicates the user is on a VPN (Virtual Private Network) * web_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. * public_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.

ip_spam_list_countalways presentinteger

View in sample
JSON

Count of spam lists the IP address is associated with if known.

ip_timezone_offsetalways presentstringNULLABLE

View in sample
JSON

UTC offset of the timezone associated with the IP address if known.

UTC offset of the timezone associated with the IP address.

screening_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated screening.

redacted_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the Flow Session was redacted

An ISO8601 formatted timestamp.

_metamight be omittedstring

View in sample
JSON

A friendly reminder that this API is still being developed and might change in the future. If we do choose to make a backwards incompatible change before this API hits 1.0, we will notify you by email with details and a deprecation timeline.

GET

/flow_sessions/{id}

Response Sample
Copy JSON
1{
2  "id": "flwses_52xR9LKo77r1Np",
3  "customer_reference": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_session_id": "flwses_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.cognitohq.com/verify/flwtmp_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "flwtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone": "+19876543212",
14    "date_of_birth": "1975-01-18",
15    "ip_address": "192.0.2.42",
16    "email": "user@example.com",
17    "name": {
18      "first": "Leslie",
19      "last": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "subdivision": "IN",
26      "postal_code": "46001",
27      "country_code": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "category": "tax_id",
32      "type": "us_ssn"
33    }
34  },
35  "status": "success",
36  "steps": {
37    "accept_tos": "success",
38    "verify_sms": "success",
39    "kyc_screen": "not_applicable",
40    "kyc_check": "active",
41    "documentary_verification": "waiting_for_prerequisite",
42    "selfie_check": "waiting_for_prerequisite",
43    "screening": "waiting_for_prerequisite",
44    "risk_check": "waiting_for_prerequisite"
45  },
46  "documentary_verification": {
47    "status": "success",
48    "documents": [
49      {
50        "status": "success",
51        "attempt": 1,
52        "images": {
53          "original_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_front.jpeg",
54          "original_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_back.jpeg",
55          "cropped_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
56          "cropped_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
57          "face": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/face.jpeg"
58        },
59        "extracted_data": {
60          "id_number": "AB123456",
61          "category": "drivers_license",
62          "expiration_date": "1990-05-29",
63          "issuing_country": "US",
64          "issuing_subdivision": "IN"
65        },
66        "analysis": {
67          "authenticity": "match",
68          "image_quality": "high",
69          "extracted_data": {
70            "name": "match",
71            "date_of_birth": "match",
72            "expiration_date": "not_expired",
73            "issuing_country": "match"
74          }
75        },
76        "redacted_at": "2020-07-24T03:26:02Z"
77      }
78    ]
79  },
80  "selfie_check": {
81    "status": "success",
82    "selfies": [
83      {
84        "status": "success",
85        "attempt": 1,
86        "capture": {
87          "image_url": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/selfie/liveness.jpeg",
88          "video_url": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/selfie/liveness.webm"
89        },
90        "analysis": {
91          "document_comparison": "match"
92        }
93      }
94    ]
95  },
96  "kyc_check": {
97    "status": "success",
98    "address": {
99      "summary": "match",
100      "po_box": "yes",
101      "type": "residential"
102    },
103    "name": {
104      "summary": "match"
105    },
106    "date_of_birth": {
107      "summary": "match"
108    },
109    "id_number": {
110      "summary": "match"
111    },
112    "phone": {
113      "summary": "match"
114    }
115  },
116  "risk_check": {
117    "status": "waiting_for_prerequisite",
118    "behavior": {
119      "user_interactions": "risky",
120      "fraud_ring_detected": "yes",
121      "bot_detected": "yes"
122    },
123    "email": {
124      "is_deliverable": "yes",
125      "breach_count": 1,
126      "first_breached_at": "1990-05-29",
127      "last_breached_at": "1990-05-29",
128      "domain_registered_at": "1990-05-29",
129      "domain_is_free_provider": "yes",
130      "domain_is_custom": "yes",
131      "domain_is_disposable": "yes",
132      "top_level_domain_is_suspicious": "yes",
133      "linked_services": [
134        "apple"
135      ]
136    },
137    "phone": {
138      "linked_services": [
139        "apple"
140      ]
141    },
142    "devices": [
143      {
144        "ip_spam_list_count": 1
145      }
146    ]
147  },
148  "screening_id": "scr_52xR9LKo77r1Np",
149  "redacted_at": "2020-07-24T03:26:02Z",
150  "_meta": "This API format is not v1.0 and is subject to change."
151}

Retry a Flow Session

Allow a customer to retry verification by creating a new FlowSession.

Parameters
Header Parameters

Cognito-Versionrequiredstring

The version of the Cognito API that you want to consume.

Possible enum values

2020-08-14
Request Body

customer_referencerequiredstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

template_idrequiredstring

View in sample
JSON

ID of the associated Flow template.

strategyrequiredstring

View in sample
JSON

An instruction specifying what steps the new Flow Session should require the user to complete:

  • reset - Restart the user at the beginning of the session, regardless of whether they successfully completed part of their previous session.
  • incomplete - Start the new session at the step that the user failed in the previous session, skipping steps that have already been successfully completed.
  • infer - If the most recent Flow Session associated with the given customer_reference has a status of failed or expired, retry using the incomplete strategy. Otherwise, use the reset strategy.
  • custom - Start the new session with a custom configuration, specified by the value of the steps field

Note:

  • The incomplete strategy cannot be applied if the session's failing step is screening or risk_check.
  • The infer strategy cannot be applied if the session's status is still active

Possible enum values

resetincompleteinfercustom

stepsoptionalobject

View in sample
JSON

Instructions for the custom retry strategy specifying which steps should be required or skipped.


Note:

  • This field must be provided when the retry strategy is custom and must be omitted otherwise.
  • Custom retries override settings in your Flow Template. For example, if your Flow Template has verify_sms disabled, a custom retry with verify_sms enabled will still require the step.
  • The selfie_check step is currently not supported on the sandbox server. Sandbox requests will silently disable the selfie_check step when provided.
Hide child attributes

steps.verify_smsrequiredboolean

View in sample
JSON

A boolean field specifying whether the new session should require or skip the verify_sms step.

steps.kyc_checkrequiredboolean

View in sample
JSON

A boolean field specifying whether the new session should require or skip the kyc_check step.

steps.documentary_verificationrequiredboolean

View in sample
JSON

A boolean field specifying whether the new session should require or skip the documentary_verification step.

steps.selfie_checkrequiredboolean

View in sample
JSON

A boolean field specifying whether the new session should require or skip the selfie_check step.

Response Schema

idalways presentstring

View in sample
JSON

ID of the associated Flow session.

customer_referencealways presentstring

View in sample
JSON

An identifier to help you connect this object to your internal systems. For example, your database ID corresponding to this object.

created_atalways presentstring

View in sample
JSON

An ISO8601 formatted timestamp.

completed_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the Flow Session terminated

An ISO8601 formatted timestamp.

previous_session_idalways presentstringNULLABLE

View in sample
JSON

The ID of the previous Flow Session, if any.

The ID for the Flow Session preceding this session. This field will only be filled if the current Flow Session is a retry of a previous session.

shareable_urlalways presentstringNULLABLE

View in sample
JSON

A shareable URL that can be sent directly to the user to complete verification

templatealways presentobject

View in sample
JSON
Hide child attributes

idalways presentstring

View in sample
JSON

ID of the associated Flow template.

versionalways presentnumber

View in sample
JSON

Version of the associated Flow template.

useralways presentobject

View in sample
JSON
Hide child attributes

phonealways presentstringNULLABLE

View in sample
JSON

A phone number in E.164 format.

date_of_birthalways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

ip_addressalways presentstringNULLABLE

View in sample
JSON

IP Address collected from the user's Flow Session. Can be either an IPv4 or IPv6 address. If the address is representable as IPv4, it will be returned as IPv4.


Note: This field can be null if the user has not yet interacted with Flow's frontend, either because they haven't started their session yet or because their session was created via API using Flow hybrid.

An IPv4 or IPV6 address.

emailalways presentstringNULLABLE

View in sample
JSON

The user email you programmatically provided to your Flow integration.

A valid email address.

namealways presentobjectNULLABLE

View in sample
JSON

The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled.

Hide child attributes

firstalways presentstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

lastalways presentstring

View in sample
JSON

A string with at least one non-whitespace character, with a max length of 100 characters.

addressalways presentobjectNULLABLE

View in sample
JSON

The address data submitted by the user. If the user has not submitted their address, this field will be null. Otherwise, it will be an object and street, city, and country_code are guaranteed to be filled. The remaining fields differ based the region's addressing system. For example:

  • Addresses from the United Kingdom will not include a subdivision
  • Addresses from Hong Kong will not include postal code

Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: * Addresses from the United Kingdom will not include a region * Addresses from Hong Kong will not include postal code

Hide child attributes

streetalways presentstringNULLABLE

View in sample
JSON

The primary street portion of an address. If the user has submitted their address, this field will always be filled.

street2always presentstringNULLABLE

View in sample
JSON

Extra street information, like an apartment or suite number.

cityalways presentstringNULLABLE

View in sample
JSON

City from the end user's address

subdivisionalways presentstringNULLABLE

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

postal_codealways presentstringNULLABLE

View in sample
JSON

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

country_codealways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

id_numberalways presentobjectNULLABLE

View in sample
JSON

ID Number submitted by the user. If the user has not submitted this data yet, this field will be null. Otherwise, both fields are guaranteed to be filled.

Type and value of ID number provided

Hide child attributes

valuealways presentstring

View in sample
JSON

Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.

categoryalways presentstring

View in sample
JSON

The category of identity document provided

Possible enum values

drivers_licensepassportpersonal_identificationtax_idvoter_id

typealways presentstring

View in sample
JSON

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Flow Hybrid Input Validation](https://cognitohq.com/docs/flow/flow-hybrid-input-validation)

Possible enum values

ar_dniau_drivers_licenseau_passportbr_cpfca_sincl_runcn_resident_cardco_nitdk_cpreg_national_ides_dnies_niehk_hkidin_panit_cfjo_civil_idjp_my_numberke_huduma_nambakw_civil_idmx_curpmx_rfcmy_nricng_ninnz_drivers_licenseom_civil_idph_psnpl_peselro_cnpsa_national_idse_pinsg_nrictr_tc_kimlikus_ssnus_ssn_last_4za_smart_id

statusalways presentstring

View in sample
JSON

The status of this Flow session.

  • active - The Flow session is incomplete. The user may have completed part of the session, but has neither failed or passed.
  • success - The Flow session has completed, passing all steps defined to the associated Flow template
  • failed - The user failed one or more steps in the session and was told to contact support.
  • expired - The Flow session was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future.
  • canceled - The Flow session was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed.
  • pending_review - The Flow session template was configured to perform a screening that had one or more hits needing review.

Possible enum values

activesuccessfailedexpiredcanceledpending_review

stepsalways presentobject

View in sample
JSON

Each step will be one of the following values:

  • active - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Flow session while in the middle of this step. Only one step will be marked as active at any given point.
  • success - The Flow session has completed this step.
  • failed - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Flow template is configured. A failed step does not imply a failed session.
  • waiting_for_prerequisite - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback.
  • not_applicable - This step will not be run for this session.
  • skipped - The retry instructions that created this Flow session specified that this step should be skipped.
  • expired - This step had not yet been completed when the Flow session as a whole expired.
  • canceled - The Flow session was canceled before the user completed this step.
  • pending_review - The Flow session template was configured to perform a screening that had one or more hits needing review.
  • manually_approved - The step was manually overridden to pass by a team member in the dashboard.
  • manually_rejected - The step was manually overridden to fail by a team member in the dashboard.
Hide child attributes

accept_tosalways presentstring

View in sample
JSON

The status of the accept_tos step. This step will always come first.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

verify_smsalways presentstring

View in sample
JSON

The status of the SMS verification step. Failing this step means the user either entered an incorrect code twice or the verification code has expired.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

kyc_screenalways presentstring

View in sample
JSON

Deprecated.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

kyc_checkalways presentstring

View in sample
JSON

The status of the full KYC check step (referred to as the "Know your Customer" use case in the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

documentary_verificationalways presentstring

View in sample
JSON

The status of the documentary verification check step (configured via "Fallback Settings" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

selfie_checkalways presentstring

View in sample
JSON

The status of the selfie check step (configured via "Selfie Check Behavior" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

screeningalways presentstring

View in sample
JSON

The status of the watchlist screening step, always run last. No user input is prompted for this step. The status will be pending_review when there are unreviewed hits. Once hits are reviewed, the status will be changed to manually_approved or manually_rejected, as appropriate.

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

risk_checkalways presentstring

View in sample
JSON

The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

documentary_verificationalways presentobjectNULLABLE

View in sample
JSON

Data, images, analysis, and results from the documentary_verification step. This field will be null unless steps.documentary_verification has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's documentary_verification step. This field will always have the same value as steps.documentary_verification.

documentsalways presentarray of objects

View in sample
JSON

An array of documents submitted to the documentary_verification step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type.


Note: Flow will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within documents. If the overall documentary_verification is failed, the user has exhausted their retry attempts.

Hide child attributes

statusalways presentstring

View in sample
JSON

An outcome status for this specific document submission. Distinct from the overall documentary_verification.status that summarizes the verification outcome from one or more documents.

Possible enum values

successfailedmanually_approved

attemptalways presentnumber

View in sample
JSON

The attempt field begins with 1 and increments with each subsequent document upload.

imagesalways presentobject

View in sample
JSON

URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the GET request for the associated Flow session. A new expiring URL is generated with each request, so you can always rerequest the Flow session if one of your URLs expires.

Hide child attributes

original_frontalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document.

original_backalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected.

cropped_frontalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document.

cropped_backalways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected.

facealways presentstringNULLABLE

View in sample
JSON

Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo.

extracted_dataalways presentobjectNULLABLE

View in sample
JSON

Information extracted from the document images provided.


Note: This field might be null in the case where a document could not be detected in the image provided (either due to the image not containing a document or due to poor image quality)

Data extracted from a user-submitted document.

Hide child attributes

id_numberalways presentstringNULLABLE

View in sample
JSON

Alpha-numeric ID number extracted via OCR from the user's document image.

categoryalways presentstring

View in sample
JSON

The type of identity document detected in the images provided. Will always be one of the following values:

  • drivers_license - A driver's license for the associated country

  • id_card - A general national identification card, distinct from driver's licenses

  • passport - A passport for the associated country

  • residence_permit_card - An identity document permitting a foreign citizen to temporarily reside in the associated country

  • resident_card - An identity document permitting a foreign citizen to permanently reside in the associated country


Note: This value may be different from the ID type that the user selects within Flow's UI. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say passport

Possible enum values

drivers_licenseid_cardpassportresidence_permit_cardresident_card

expiration_datealways presentstringNULLABLE

View in sample
JSON

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

issuing_countryalways presentstring

View in sample
JSON

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

issuing_subdivisionalways presentstringNULLABLE

View in sample
JSON

An ISO 3166-2 subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc.

analysisalways presentobject

View in sample
JSON

High level descriptions of how the associated document was processed. If a document fails verification, the details in the analysis object should help clarify why the document was rejected.

Hide child attributes

authenticityalways presentstring

View in sample
JSON

High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction.


For example, most identity documents have formatting rules like the following:

  • The image of the person's face must have a certain contrast in order to highlight skin tone

  • The subject in the document's image must remove eye glasses and pose in a certain way

  • The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules

  • Security features like watermarks and background patterns must be present

So a match status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document.

Possible enum values

matchpartial_matchno_matchno_data

image_qualityalways presentstring

View in sample
JSON

A high level description of the quality of the image the user submitted.


For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks.


Note: By default, Flow will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality.

Possible enum values

highmediumlow

extracted_dataalways presentobjectNULLABLE

View in sample
JSON

This section summarizes checks Cognito performed against the data that was extracted from the document image.

Analysis of the data extracted from the submitted document.

Hide child attributes

namealways presentstring

View in sample
JSON

A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to flow session.

Possible enum values

matchpartial_matchno_match

date_of_birthalways presentstring

View in sample
JSON

A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the flow session.

Possible enum values

matchpartial_matchno_match

expiration_datealways presentstring

View in sample
JSON

A description of whether the associated document was expired when the verification was performed.


Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be no_data.

Possible enum values

not_expiredexpiredno_data

issuing_countryalways presentstring

View in sample
JSON

A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Flow.


Note: You can configure whether a no_match on issuing_country fails the documentary_verification by editing your Flow Template.

Possible enum values

matchno_match

redacted_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the document was redacted

An ISO8601 formatted timestamp.

selfie_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the selfie_check step. This field will be null unless steps.selfie_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's selfie_check step. This field will always have the same value as steps.selfie_check.

Possible enum values

successfailed

selfiesalways presentarray of objects

View in sample
JSON

An array of selfies submitted to the selfie_check step. Each entry represents one user submission.

Hide child attributes

statusalways presentstring

View in sample
JSON

An outcome status for this specific selfie. Distinct from the overall selfie_check.status that summarizes the verification outcome from one or more selfies.

Possible enum values

successfailed

attemptalways presentinteger

View in sample
JSON

The attempt field begins with 1 and increments with each subsequent selfie upload.

capturealways presentobject

View in sample
JSON

The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.

Hide child attributes

image_urlmight be omittedstringNULLABLE

View in sample
JSON

Temporary URL for downloading an image selfie capture.

video_urlmight be omittedstringNULLABLE

View in sample
JSON

Temporary URL for downloading a video selfie capture.

analysisalways presentobject

View in sample
JSON

High level descriptions of how the associated selfie was processed. If a seflfie fails verification, the details in the analysis object should help clarify why the selfie was rejected.

Hide child attributes

document_comparisonalways presentstring

View in sample
JSON

Information about the comparison between the selfie and the document (if documentary verification also ran).

Possible enum values

matchno_matchno_input

kyc_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the kyc_check step. This field will be null unless steps.kyc_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The outcome status for the associated Flow session's kyc_check step. This field will always have the same value as steps.kyc_check.

addressalways presentobject

View in sample
JSON

Result summary object specifying how the address field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

po_boxalways presentstring

View in sample
JSON

Field describing whether the associated address is a post office box. Will be yes when a P.O. box is detected, no when Cognito confirmed the address is not a P.O. box, and no_data when Cognito was not able to determine if the address is a P.O. box.

Possible enum values

yesnono_data

typealways presentstring

View in sample
JSON

Field describing whether the associated address is being used for commercial or residential purposes.


Note: This value will be no_data when Cognito does not have sufficient data to determine the address's use.

Possible enum values

residentialcommercialno_data

namealways presentobject

View in sample
JSON

Result summary object specifying how the name field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

date_of_birthalways presentobject

View in sample
JSON

Result summary object specifying how the date_of_birth field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

id_numberalways presentobject

View in sample
JSON

Result summary object specifying how the id_number field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

phonealways presentobject

View in sample
JSON

Result summary object specifying how the phone field matched.

Hide child attributes

summaryalways presentstring

View in sample
JSON

An enum indicating the match type between data provided by user and data checked against an external data source.

  • match indicates that the provided input data was a strong match against external data.
  • partial_match indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name.
  • no_match indicates that Cognito was able to perform a check against an external data source and it did not match the provided input data.
  • no_data indicates that Cognito was unable to find external data to compare against the provided input data.
  • no_input indicates that Cognito was unable to perform a check because no information was provided for this field by the end user.

Possible enum values

matchpartial_matchno_matchno_datano_input

risk_checkalways presentobjectNULLABLE

View in sample
JSON

Additional information for the risk_check step. This field will be null unless steps.risk_check has reached a terminal state of either success or failed.

Hide child attributes

statusalways presentstring

View in sample
JSON

The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)

Possible enum values

successactivefailedwaiting_for_prerequisitenot_applicableskippedexpiredcanceledpending_reviewmanually_approvedmanually_rejected

behavioralways presentobjectNULLABLE

View in sample
JSON

The attributes from the behavior risk check, when available.

Result summary object specifying values for behavior attributes of risk check, when available.

Hide child attributes

user_interactionsalways presentstring

View in sample
JSON

Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session.

  • genuine indicates the user has high familiarity with the data they are providing, and that fraud is unlikely.
  • neutral indicates some signals are present in between risky and genuine, but there are not enough clear signals to determine an outcome.
  • risky indicates the user has low familiarity with the data they are providing, and that fraud is likely.
  • no_data indicates there is not sufficient information to give an accurate signal.

Possible enum values

genuineneutralriskyno_data

fraud_ring_detectedalways presentstring

View in sample
JSON

Field describing the outcome of a fraud ring behavior risk check.

  • yes indicates that fraud ring activity was detected.
  • no indicates that fraud ring activity was not detected.
  • no_data indicates there was not enough information available to give an accurate signal.

Possible enum values

yesnono_data

bot_detectedalways presentstring

View in sample
JSON

Field describing the outcome of a bot detection behavior risk check.

  • yes indicates that automated activity was detected.
  • no indicates that automated activity was not detected.
  • no_data indicates there was not enough information available to give an accurate signal.

Possible enum values

yesnono_data

emailalways presentobjectNULLABLE

View in sample
JSON

The attributes from the email risk check, when available.

Result summary object specifying values for email attributes of risk check.

Hide child attributes

is_deliverablealways presentstring

View in sample
JSON

SMTP-MX check to confirm the email address exists if known.

Possible enum values

yesnono_data

breach_countalways presentinteger

View in sample
JSON

Count of all known breaches of this email address if known.

first_breached_atalways presentstringNULLABLE

View in sample
JSON

First known date this email address was breached if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

last_breached_atalways presentstringNULLABLE

View in sample
JSON

Last known date this email address was breached if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

domain_registered_atalways presentstringNULLABLE

View in sample
JSON

Timestamp domain was registered at if known.

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

domain_is_free_provideralways presentstring

View in sample
JSON

Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known.

Possible enum values

yesnono_data

domain_is_customalways presentstring

View in sample
JSON

Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable.

Possible enum values

yesnono_data

domain_is_disposablealways presentstring

View in sample
JSON

Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details.

Possible enum values

yesnono_data

top_level_domain_is_suspiciousalways presentstring

View in sample
JSON

Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain.

Possible enum values

yesnono_data

linked_servicesalways presentarray of strings

View in sample
JSON

Possible enum values

appleebayfacebookflickrfoursquaregithubgooglegravatarinstagramlastfmlinkedinmicrosoftmyspacepinterestskypespotifytelegramtumblrtwittervibervimeoweibowhatsappyahooairbnbamazonbookingdiscordkakaookqzonelinesnapchatzalo

phonealways presentobjectNULLABLE

View in sample
JSON

The attributes from the phone risk check, when available.

Result summary object specifying values for phone attributes of risk check.

Hide child attributes

linked_servicesalways presentarray of strings

View in sample
JSON

Possible enum values

appleebayfacebookflickrfoursquaregithubgooglegravatarinstagramlastfmlinkedinmicrosoftmyspacepinterestskypespotifytelegramtumblrtwittervibervimeoweibowhatsappyahooairbnbamazonbookingdiscordkakaookqzonelinesnapchatzalo

devicesalways presentarray of objects

View in sample
JSON

Array of result summary objects specifying values for device attributes of risk check.

Hide child attributes

ip_proxy_typealways presentstringNULLABLE

View in sample
JSON

An enum indicating whether a network proxy is present and if so what type it is. * none_detected indicates the user is not on a detectable proxy network. * tor indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). * vpn indicates the user is on a VPN (Virtual Private Network) * web_proxy indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. * public_proxy indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance.

ip_spam_list_countalways presentinteger

View in sample
JSON

Count of spam lists the IP address is associated with if known.

ip_timezone_offsetalways presentstringNULLABLE

View in sample
JSON

UTC offset of the timezone associated with the IP address if known.

UTC offset of the timezone associated with the IP address.

screening_idalways presentstringNULLABLE

View in sample
JSON

ID of the associated screening.

redacted_atalways presentstringNULLABLE

View in sample
JSON

Timestamp reflecting when the Flow Session was redacted

An ISO8601 formatted timestamp.

_metamight be omittedstring

View in sample
JSON

A friendly reminder that this API is still being developed and might change in the future. If we do choose to make a backwards incompatible change before this API hits 1.0, we will notify you by email with details and a deprecation timeline.

Webhooks
POSTflow_session.retried

Receive a webhook whenever a FlowSession has been retried, which can be triggered via the dashboard or the API.

idalways presentstring

ID of the associated webhook event.

timestampalways presentstring

The time that the event happened.

eventalways presentstring

The type of event this webhook describes.

Possible enum values

flow_session.retried

dataalways presentobject

environmentalways presentstring

Environment from which the webhook was sent.

Possible enum values

sandboxlive
POST

/flow_sessions/retry

1{
2  "customer_reference": "your-db-id-3b24110",
3  "template_id": "flwtmp_4FrXJvfQU3zGUR",
4  "strategy": "reset"
5}
Response Sample
Copy JSON
1{
2  "id": "flwses_52xR9LKo77r1Np",
3  "customer_reference": "your-db-id-3b24110",
4  "created_at": "2020-07-24T03:26:02Z",
5  "completed_at": "2020-07-24T03:26:02Z",
6  "previous_session_id": "flwses_42cF1MNo42r9Xj",
7  "shareable_url": "https://flow.cognitohq.com/verify/flwtmp_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
8  "template": {
9    "id": "flwtmp_4FrXJvfQU3zGUR",
10    "version": 2
11  },
12  "user": {
13    "phone": "+19876543212",
14    "date_of_birth": "1975-01-18",
15    "ip_address": "192.0.2.42",
16    "email": "user@example.com",
17    "name": {
18      "first": "Leslie",
19      "last": "Knope"
20    },
21    "address": {
22      "street": "123 Main St.",
23      "street2": "Unit 42",
24      "city": "Pawnee",
25      "subdivision": "IN",
26      "postal_code": "46001",
27      "country_code": "US"
28    },
29    "id_number": {
30      "value": "123456789",
31      "category": "tax_id",
32      "type": "us_ssn"
33    }
34  },
35  "status": "success",
36  "steps": {
37    "accept_tos": "success",
38    "verify_sms": "success",
39    "kyc_screen": "not_applicable",
40    "kyc_check": "active",
41    "documentary_verification": "waiting_for_prerequisite",
42    "selfie_check": "waiting_for_prerequisite",
43    "screening": "waiting_for_prerequisite",
44    "risk_check": "waiting_for_prerequisite"
45  },
46  "documentary_verification": {
47    "status": "success",
48    "documents": [
49      {
50        "status": "success",
51        "attempt": 1,
52        "images": {
53          "original_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_front.jpeg",
54          "original_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_back.jpeg",
55          "cropped_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
56          "cropped_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
57          "face": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/face.jpeg"
58        },
59        "extracted_data": {
60          "id_number": "AB123456",
61          "category": "drivers_license",
62          "expiration_date": "1990-05-29",
63          "issuing_country": "US",
64          "issuing_subdivision": "IN"
65        },
66        "analysis": {
67          "authenticity": "match",
68          "image_quality": "high",
69          "extracted_data": {
70            "name": "match",
71            "date_of_birth": "match",
72            "expiration_date": "not_expired",
73            "issuing_country": "match"
74          }
75        },
76        "redacted_at": "2020-07-24T03:26:02Z"
77      }
78    ]
79  },
80  "selfie_check": {
81    "status": "success",
82    "selfies": [
83      {
84        "status": "success",
85        "attempt": 1,
86        "capture": {
87          "image_url": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/selfie/liveness.jpeg",
88          "video_url": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/selfie/liveness.webm"
89        },
90        "analysis": {
91          "document_comparison": "match"
92        }
93      }
94    ]
95  },
96  "kyc_check": {
97    "status": "success",
98    "address": {
99      "summary": "match",
100      "po_box": "yes",
101      "type": "residential"
102    },
103    "name": {
104      "summary": "match"
105    },
106    "date_of_birth": {
107      "summary": "match"
108    },
109    "id_number": {
110      "summary": "match"
111    },
112    "phone": {
113      "summary": "match"
114    }
115  },
116  "risk_check": {
117    "status": "waiting_for_prerequisite",
118    "behavior": {
119      "user_interactions": "risky",
120      "fraud_ring_detected": "yes",
121      "bot_detected": "yes"
122    },
123    "email": {
124      "is_deliverable": "yes",
125      "breach_count": 1,
126      "first_breached_at": "1990-05-29",
127      "last_breached_at": "1990-05-29",
128      "domain_registered_at": "1990-05-29",
129      "domain_is_free_provider": "yes",
130      "domain_is_custom": "yes",
131      "domain_is_disposable": "yes",
132      "top_level_domain_is_suspicious": "yes",
133      "linked_services": [
134        "apple"
135      ]
136    },
137    "phone": {
138      "linked_services": [
139        "apple"
140      ]
141    },
142    "devices": [
143      {
144        "ip_spam_list_count": 1
145      }
146    ]
147  },
148  "screening_id": "scr_52xR9LKo77r1Np",
149  "redacted_at": "2020-07-24T03:26:02Z",
150  "_meta": "This API format is not v1.0 and is subject to change."
151}
Back to top