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.
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
.
List of individual watchlist screenings
Search terms for creating an individual watchlist screening
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
Links to the next and previous page of results, if applicable.
/screenings
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.
Search terms for creating an individual watchlist screening
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
/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}
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.
Search terms for creating an individual watchlist screening
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
/screenings/{id}
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.
Search terms for creating an individual watchlist screening
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
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.
/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}
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.
List of individual watchlist screenings
Search terms for creating an individual watchlist screening
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
Links to the next and previous page of results, if applicable.
/screenings/{id}/history
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 Review
s belonging to a particular screening.
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
Links to the next and previous page of results, if applicable.
/screenings/{id}/reviews
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.
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
/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}
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.
List of individual watchlist screening hits
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
confirmed
pending_review
dismissed
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.
Analysis information describing why a screening hit matched the provided user information
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
match
partial_match
no_match
no_data
no_input
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
match
partial_match
no_match
no_data
no_input
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
match
partial_match
no_match
no_data
no_input
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
match
partial_match
no_match
no_data
no_input
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.
Dates of birth associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
Documents associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
An official document, usually issued by a governing body or institution, with an associated identifier.
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_certificate
drivers_license
immigration_number
military_id
other
passport
personal_identification
ration_card
ssn
student_id
tax_id
travel_document
voter_id
Locations associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
Location information for the associated individual watchlist hit
Names associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
Name information for the associated individual watchlist hit
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
none
source
cognito
Links to the next and previous page of results, if applicable.
/screenings/{id}/hits
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 Program
s associated with your account. As a note, programs may only be created via the dashboard.
List of individual watchlist screening programs
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 thancoarse
andbalanced
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
coarse
balanced
strict
exact
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
Links to the next and previous page of results, if applicable.
/programs
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.
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 thancoarse
andbalanced
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
coarse
balanced
strict
exact
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
/programs/{id}
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
.
Search terms associated with an entity used for searching against watchlists
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
Links to the next and previous page of results, if applicable.
/entity_screenings
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.
Search terms associated with an entity used for searching against watchlists
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
/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}
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.
Search terms associated with an entity used for searching against watchlists
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
/entity_screenings/{id}
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.
Search terms associated with an entity used for searching against watchlists
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
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.
/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}
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.
Search terms associated with an entity used for searching against watchlists
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
Links to the next and previous page of results, if applicable.
/entity_screenings/{id}/history
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.
List of entity watchlist screening hits
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
confirmed
pending_review
dismissed
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.
Analysis information describing why a screening hit matched the provided entity information
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
match
partial_match
no_match
no_data
no_input
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
match
partial_match
no_match
no_data
no_input
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
match
partial_match
no_match
no_data
no_input
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
match
partial_match
no_match
no_data
no_input
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
match
partial_match
no_match
no_data
no_input
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
match
partial_match
no_match
no_data
no_input
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.
Information associated with the entity watchlist hit
Documents associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
An official document, usually issued by a governing body or institution, with an associated identifier.
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
bik
business_number
imo
other
swift
tax_id
Email addresses associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
Locations associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
Location information for the associated individual watchlist hit
Names associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
Name information for the associated entity watchlist hit
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
none
source
cognito
Phone numbers associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
Phone number information associated with the entity screening hit
URLs associated with the watchlist hit
Summary object reflecting the match result of the associated data
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
match
partial_match
no_match
no_data
no_input
Links to the next and previous page of results, if applicable.
/entity_screenings/{id}/hits
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 EntityReview
s belonging to a particular entity screening.
List of entity watchlist screening reviews
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
Links to the next and previous page of results, if applicable.
/entity_screenings/{id}/reviews
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.
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
/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}
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.
List of entity watchlist screening programs
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 thancoarse
andbalanced
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
coarse
balanced
strict
exact
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
Links to the next and previous page of results, if applicable.
/entity_programs
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.
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 thancoarse
andbalanced
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
coarse
balanced
strict
exact
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
/entity_programs/{id}
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.
Links to the next and previous page of results, if applicable.
/users
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
.
/users/{id}
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 FlowSession
s created by your account.
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.
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.
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
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
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_dni
au_drivers_license
au_passport
br_cpf
ca_sin
cl_run
cn_resident_card
co_nit
dk_cpr
eg_national_id
es_dni
es_nie
hk_hkid
in_pan
it_cf
jo_civil_id
jp_my_number
ke_huduma_namba
kw_civil_id
mx_curp
mx_rfc
my_nric
ng_nin
nz_drivers_license
om_civil_id
ph_psn
pl_pesel
ro_cnp
sa_national_id
se_pin
sg_nric
tr_tc_kimlik
us_ssn
us_ssn_last_4
za_smart_id
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
active
success
failed
expired
canceled
pending_review
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 asactive
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.
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
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the full KYC check step (referred to as the "Know your Customer" use case in the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the documentary verification check step (configured via "Fallback Settings" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the selfie check step (configured via "Selfie Check Behavior" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
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
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
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
.
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.
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.
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.
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_license
id_card
passport
residence_permit_card
resident_card
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.
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
match
partial_match
no_match
no_data
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
high
medium
low
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.
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_expired
expired
no_data
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
match
no_match
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
.
An array of selfies submitted to the selfie_check
step. Each entry represents one user submission.
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.
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.
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
.
Result summary object specifying how the address
field matched.
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
match
partial_match
no_match
no_data
no_input
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
yes
no
no_data
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
residential
commercial
no_data
Result summary object specifying how the name
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the date_of_birth
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the id_number
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the phone
field matched.
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
match
partial_match
no_match
no_data
no_input
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
.
The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The attributes from the behavior risk check, when available.
Result summary object specifying values for behavior
attributes of risk check, when available.
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 betweenrisky
andgenuine
, 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
genuine
neutral
risky
no_data
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
yes
no
no_data
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
yes
no
no_data
The attributes from the email risk check, when available.
Result summary object specifying values for email
attributes of risk check.
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
yes
no
no_data
Possible enum values
apple
ebay
facebook
flickr
foursquare
github
google
gravatar
instagram
lastfm
linkedin
microsoft
myspace
pinterest
skype
spotify
telegram
tumblr
twitter
viber
vimeo
weibo
whatsapp
yahoo
airbnb
amazon
booking
discord
kakao
ok
qzone
line
snapchat
zalo
The attributes from the phone risk check, when available.
Result summary object specifying values for phone
attributes of risk check.
Possible enum values
apple
ebay
facebook
flickr
foursquare
github
google
gravatar
instagram
lastfm
linkedin
microsoft
myspace
pinterest
skype
spotify
telegram
tumblr
twitter
viber
vimeo
weibo
whatsapp
yahoo
airbnb
amazon
booking
discord
kakao
ok
qzone
line
snapchat
zalo
Array of result summary objects specifying values for device
attributes of risk check.
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.
Links to the next and previous page of results, if applicable.
/flow_sessions
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.
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 FlowSession
s 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.
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
.
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.
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_dni
au_drivers_license
au_passport
br_cpf
ca_sin
cl_run
cn_resident_card
co_nit
dk_cpr
eg_national_id
es_dni
es_nie
hk_hkid
in_pan
it_cf
jo_civil_id
jp_my_number
ke_huduma_namba
kw_civil_id
mx_curp
mx_rfc
my_nric
ng_nin
nz_drivers_license
om_civil_id
ph_psn
pl_pesel
ro_cnp
sa_national_id
se_pin
sg_nric
tr_tc_kimlik
us_ssn
us_ssn_last_4
za_smart_id
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.
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.
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
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
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_dni
au_drivers_license
au_passport
br_cpf
ca_sin
cl_run
cn_resident_card
co_nit
dk_cpr
eg_national_id
es_dni
es_nie
hk_hkid
in_pan
it_cf
jo_civil_id
jp_my_number
ke_huduma_namba
kw_civil_id
mx_curp
mx_rfc
my_nric
ng_nin
nz_drivers_license
om_civil_id
ph_psn
pl_pesel
ro_cnp
sa_national_id
se_pin
sg_nric
tr_tc_kimlik
us_ssn
us_ssn_last_4
za_smart_id
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
active
success
failed
expired
canceled
pending_review
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 asactive
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.
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
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the full KYC check step (referred to as the "Know your Customer" use case in the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the documentary verification check step (configured via "Fallback Settings" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the selfie check step (configured via "Selfie Check Behavior" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
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
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
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
.
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.
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.
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.
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_license
id_card
passport
residence_permit_card
resident_card
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.
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
match
partial_match
no_match
no_data
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
high
medium
low
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.
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_expired
expired
no_data
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
match
no_match
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
.
An array of selfies submitted to the selfie_check
step. Each entry represents one user submission.
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.
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.
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
.
Result summary object specifying how the address
field matched.
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
match
partial_match
no_match
no_data
no_input
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
yes
no
no_data
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
residential
commercial
no_data
Result summary object specifying how the name
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the date_of_birth
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the id_number
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the phone
field matched.
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
match
partial_match
no_match
no_data
no_input
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
.
The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The attributes from the behavior risk check, when available.
Result summary object specifying values for behavior
attributes of risk check, when available.
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 betweenrisky
andgenuine
, 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
genuine
neutral
risky
no_data
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
yes
no
no_data
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
yes
no
no_data
The attributes from the email risk check, when available.
Result summary object specifying values for email
attributes of risk check.
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
yes
no
no_data
Possible enum values
apple
ebay
facebook
flickr
foursquare
github
google
gravatar
instagram
lastfm
linkedin
microsoft
myspace
pinterest
skype
spotify
telegram
tumblr
twitter
viber
vimeo
weibo
whatsapp
yahoo
airbnb
amazon
booking
discord
kakao
ok
qzone
line
snapchat
zalo
The attributes from the phone risk check, when available.
Result summary object specifying values for phone
attributes of risk check.
Possible enum values
apple
ebay
facebook
flickr
foursquare
github
google
gravatar
instagram
lastfm
linkedin
microsoft
myspace
pinterest
skype
spotify
telegram
tumblr
twitter
viber
vimeo
weibo
whatsapp
yahoo
airbnb
amazon
booking
discord
kakao
ok
qzone
line
snapchat
zalo
Array of result summary objects specifying values for device
attributes of risk check.
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.
/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}
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
.
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.
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.
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
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
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_dni
au_drivers_license
au_passport
br_cpf
ca_sin
cl_run
cn_resident_card
co_nit
dk_cpr
eg_national_id
es_dni
es_nie
hk_hkid
in_pan
it_cf
jo_civil_id
jp_my_number
ke_huduma_namba
kw_civil_id
mx_curp
mx_rfc
my_nric
ng_nin
nz_drivers_license
om_civil_id
ph_psn
pl_pesel
ro_cnp
sa_national_id
se_pin
sg_nric
tr_tc_kimlik
us_ssn
us_ssn_last_4
za_smart_id
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
active
success
failed
expired
canceled
pending_review
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 asactive
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.
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
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the full KYC check step (referred to as the "Know your Customer" use case in the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the documentary verification check step (configured via "Fallback Settings" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the selfie check step (configured via "Selfie Check Behavior" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
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
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
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
.
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.
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.
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.
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_license
id_card
passport
residence_permit_card
resident_card
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.
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
match
partial_match
no_match
no_data
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
high
medium
low
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.
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_expired
expired
no_data
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
match
no_match
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
.
An array of selfies submitted to the selfie_check
step. Each entry represents one user submission.
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.
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.
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
.
Result summary object specifying how the address
field matched.
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
match
partial_match
no_match
no_data
no_input
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
yes
no
no_data
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
residential
commercial
no_data
Result summary object specifying how the name
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the date_of_birth
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the id_number
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the phone
field matched.
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
match
partial_match
no_match
no_data
no_input
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
.
The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The attributes from the behavior risk check, when available.
Result summary object specifying values for behavior
attributes of risk check, when available.
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 betweenrisky
andgenuine
, 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
genuine
neutral
risky
no_data
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
yes
no
no_data
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
yes
no
no_data
The attributes from the email risk check, when available.
Result summary object specifying values for email
attributes of risk check.
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
yes
no
no_data
Possible enum values
apple
ebay
facebook
flickr
foursquare
github
google
gravatar
instagram
lastfm
linkedin
microsoft
myspace
pinterest
skype
spotify
telegram
tumblr
twitter
viber
vimeo
weibo
whatsapp
yahoo
airbnb
amazon
booking
discord
kakao
ok
qzone
line
snapchat
zalo
The attributes from the phone risk check, when available.
Result summary object specifying values for phone
attributes of risk check.
Possible enum values
apple
ebay
facebook
flickr
foursquare
github
google
gravatar
instagram
lastfm
linkedin
microsoft
myspace
pinterest
skype
spotify
telegram
tumblr
twitter
viber
vimeo
weibo
whatsapp
yahoo
airbnb
amazon
booking
discord
kakao
ok
qzone
line
snapchat
zalo
Array of result summary objects specifying values for device
attributes of risk check.
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.
/flow_sessions/{id}
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
.
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 givencustomer_reference
has a status offailed
orexpired
, retry using theincomplete
strategy. Otherwise, use thereset
strategy.
-
custom
- Start the new session with a custom configuration, specified by the value of thesteps
field
Note:
- The
incomplete
strategy cannot be applied if the session's failing step isscreening
orrisk_check
.
- The
infer
strategy cannot be applied if the session's status is stillactive
Possible enum values
reset
incomplete
infer
custom
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 withverify_sms
enabled will still require the step.
- The
selfie_check
step is currently not supported on the sandbox server. Sandbox requests will silently disable theselfie_check
step when provided.
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.
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.
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
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
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_dni
au_drivers_license
au_passport
br_cpf
ca_sin
cl_run
cn_resident_card
co_nit
dk_cpr
eg_national_id
es_dni
es_nie
hk_hkid
in_pan
it_cf
jo_civil_id
jp_my_number
ke_huduma_namba
kw_civil_id
mx_curp
mx_rfc
my_nric
ng_nin
nz_drivers_license
om_civil_id
ph_psn
pl_pesel
ro_cnp
sa_national_id
se_pin
sg_nric
tr_tc_kimlik
us_ssn
us_ssn_last_4
za_smart_id
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
active
success
failed
expired
canceled
pending_review
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 asactive
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.
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
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the full KYC check step (referred to as the "Know your Customer" use case in the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the documentary verification check step (configured via "Fallback Settings" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the selfie check step (configured via "Selfie Check Behavior" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
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
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
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
.
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.
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.
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.
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_license
id_card
passport
residence_permit_card
resident_card
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.
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
match
partial_match
no_match
no_data
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
high
medium
low
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.
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_expired
expired
no_data
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
match
no_match
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
.
An array of selfies submitted to the selfie_check
step. Each entry represents one user submission.
The image or video capture of a selfie. Only one of image or video URL will be populated per selfie.
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.
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
.
Result summary object specifying how the address
field matched.
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
match
partial_match
no_match
no_data
no_input
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
yes
no
no_data
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
residential
commercial
no_data
Result summary object specifying how the name
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the date_of_birth
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the id_number
field matched.
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
match
partial_match
no_match
no_data
no_input
Result summary object specifying how the phone
field matched.
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
match
partial_match
no_match
no_data
no_input
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
.
The status of the risk check step (configured via "Risk Rules" in the "Rulesets" section of the template editor)
Possible enum values
success
active
failed
waiting_for_prerequisite
not_applicable
skipped
expired
canceled
pending_review
manually_approved
manually_rejected
The attributes from the behavior risk check, when available.
Result summary object specifying values for behavior
attributes of risk check, when available.
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 betweenrisky
andgenuine
, 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
genuine
neutral
risky
no_data
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
yes
no
no_data
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
yes
no
no_data
The attributes from the email risk check, when available.
Result summary object specifying values for email
attributes of risk check.
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
yes
no
no_data
Possible enum values
apple
ebay
facebook
flickr
foursquare
github
google
gravatar
instagram
lastfm
linkedin
microsoft
myspace
pinterest
skype
spotify
telegram
tumblr
twitter
viber
vimeo
weibo
whatsapp
yahoo
airbnb
amazon
booking
discord
kakao
ok
qzone
line
snapchat
zalo
The attributes from the phone risk check, when available.
Result summary object specifying values for phone
attributes of risk check.
Possible enum values
apple
ebay
facebook
flickr
foursquare
github
google
gravatar
instagram
lastfm
linkedin
microsoft
myspace
pinterest
skype
spotify
telegram
tumblr
twitter
viber
vimeo
weibo
whatsapp
yahoo
airbnb
amazon
booking
discord
kakao
ok
qzone
line
snapchat
zalo
Array of result summary objects specifying values for device
attributes of risk check.
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.
Receive a webhook whenever a FlowSession
has been retried, which can be triggered via the dashboard or the API.
/flow_sessions/retry
1{
2 "customer_reference": "your-db-id-3b24110",
3 "template_id": "flwtmp_4FrXJvfQU3zGUR",
4 "strategy": "reset"
5}
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}