Live Document Capture 

Purpose 

This section describes how to capture an Identity Document with the ID&V service and the user's Web Browser. This process requires the IDEMIA Web Capture SDK.

Processing 

ID&V offers a service for capturing front and back identity document (ID) images via a web browser and then process those images.

The process includes:

• Automatic capture of the document
• Optical Character Recognition to extract document data
• Checking the genuineness of the document

For additional details regarding the web capture process, see the documentation dedicated to the Document Web Capture SDK.

Requirements 

To execute the scenarios, the client application needs:

• API Keys and URLs to access the ID proofing service

• GIPS-RS key for Back-end to Back-end communication

• GIPS-UA key for the end-user-facing application to ID Proofing Back-end communication

• The Document Capture Web SDK

Details about the Document Web Capture SDK are available here.

Scenario 

Steps Overview 

1. Create the identity.

2. Submit a request for a live document capture.

3. Use the IDEMIA Document Web Capture SDK.

4. Check document details.

The example below uses an Identity card as reference identity document.

Steps to capture a live document 

Step 1: Create the identity.

Create an identity on the ID proofing server that will receive all of the data and gather the verification results related to this identity.

Step 2: Create live document capture session.

Send the request to create a live capture session.

• ID&V creates a document capture session and returns the sessionId, evidenceId and sidesToCapture .

  Note : The document status becomes PROCESSING and will remain so until the document is fully processed, or the session times out

Step 3: Capture the document with IDEMIA Document Web Capture SDK.

Create a web video stream using the IDEMIA Document Web Capture SDK.

The user then captures the document images images with the help of the Web Capture SDK.

Once the document images are captured, the service extracts information from the images and checks the genuineness of the document.

Step 4: Retrieve verification results

The Front End application can check the document status and retrieve the extracted data details and images of the document.

The User Agent application can continue with other evidence submissions to improve the Level of Assurance (LOA) or notify the back end service that the proofing journey is done, so the back end application can retrieve the proof.

Web Service Calls 

There are several ways to make the appropriate web service calls. The rest of this document focuses on the use of cURL requests.

The variables used in the request URLs are:

Create an Identity 

This request initiates the verification process with ID&V.

The request looks like this:

Shell
1curl -X POST https://[URL_MAIN_PART]/gips/v1/identities  \
2  -H 'Content-Type: application' \
3  -H 'apikey: [GIPS_RS_APIKEY_VALUE]'

The ID&V response to this request contains an id field. The value of that field replaces IDENTITY_ID in subsequent requests.

Sample response:

JSON
1{
2  "id": "gips-f10d3496-50c4-438e-9db2-1a385601fb5b",
3  "status": "EXPECTING_INPUT",
4  "levelOfAssurance": "LOA0",
5  "creationDateTime": "2020-12-11T13:50:37.1327604",
6  "evaluationDateTime": "2020-12-11T13:50:37.3472003",
7  "upgradePaths": {}
8}

Create live document capture video session 

With this request, the client application starts a live capture video session of the document in order to capture the best quality images of the document.

This web service call is synchronous.

The service response provides a WebDoc Server session identifier to be used by the client application to initialize the session using the IDEMIA Document Web Capture SDK.

The request looks like this:

Shell
1curl -X POST \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/id-documents/live-capture-session \
3-H 'Content-Type: application/json' \
4-H 'apikey: [GIPS_RS_APIKEY_VALUE]'
5  -d '{
6    "issuingCountry": "USA",
7    "idDocumentType": "DRIVING_LICENSE",
8    "sidesToCapture": [
9        "FRONT","BACK"
10    ]
11}'

Where:

Sample response:

JSON
1{
2  "status": "PROCESSING",
3  "type": "DRIVING_LICENSE",
4  "id": "82a93866-36cb-4ccd-9e16-b9c20f18df99",
5  "sessionId": "1324a525-f519-4698-99fc-2f1dbcad0223",
6  "sidesToCapture": ["FRONT", "BACK"]
7}

Check Document Status 

With this request, the client application checks the processing status of the captured document.

The request looks like this:

Shell
1curl -X GET \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/status/[IDDOCUMENT_ID] \
3	-H 'apikey: [GIPS_UA_APIKEY_VALUE]'

The client application can use this API to implement polling and proceeds to the next steps when the document status is not PROCESSING, ADJUDICATION anymore . In case the document final status is different from VERIFIED , the client application may prompt the different error codes to the user and start another capture attempt.

Sample response:

JSON
1{
2  "status": "PROCESSING",
3  "type": "DRIVING_LICENSE",
4  "id": "106ee381-72b6-4301-baf6-a8cd5c8e9491"
5}

Values for status can be:

• VERIFIED - means that document has successfully been verified. When VERIFIED, a document is scored on a scale of 1 to 4.

  • LEVEL1: low confidence
  • LEVEL2: medium confidence
  • LEVEL3: high confidence
  • LEVEL4: very high confidence

• INVALID - means that the document is considered invalid after the checks are performed.

• NOT_VERIFIED - means that the document was processed, but not enough checks were performed to make a decision. Most of the time, this is due to a bad quality of the image or an unsupported document type.

• PROCESSING - means that the document is currently being processed by the service.

• ADJUDICATION - means that the document is currently being reviewed by a human expert.

Retrieve verification results 

With this request, the client application can check the status of the identity and see what Level of Assurance (LOA) has been reached.

The request looks like this:

Shell
1curl -X GET \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID] \
3	-H 'Content-Type: application/json' \
4	-H 'apikey: [GIPS_UA_APIKEY_VALUE]'

Sample response:

JSON
1{
2  "globalStatus": {
3    "id": "gips-f10d3496-50c4-438e-9db2-1a385601fb5b",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA1",
6    "creationDateTime": "2020-12-11T13:50:37.1327604",
7    "evaluationDateTime": "2020-12-11T13:53:30.1821823",
8    "nameReferenceEvidenceId": "106ee381-72b6-4301-baf6-a8cd5c8e9491",
9    "portraitReferenceEvidenceId": "106ee381-72b6-4301-baf6-a8cd5c8e9491",
10    "upgradePaths": {}
11  },
12  "attributes": [
13    {
14      "evidenceId": "3925e807-dc04-40b4-b2b5-ad9aac3e985b",
15      "submitDateTime": "2020-12-11T13:53:30.1712103",
16      "type": "ATTRIBUTES",
17      "evidenceStatus": {
18        "evaluationDateTime": "2020-12-11T13:53:30.1821823",
19        "status": "VERIFIED",
20        "strength": "LEVEL5",
21        "score": "LEVEL2",
22        "isAdjudicable": false
23      },
24      "attributesData": {
25        "givenNames": [
26          {
27            "value": "CHRISTOPHE",
28            "verified": true
29          }
30        ],
31        "surname": {
32          "value": "ULYSSE",
33          "verified": true
34        },
35        "fullname": {
36          "value": "CHRISTOPHE ULYSSE",
37          "verified": true
38        },
39        "dateOfBirth": {
40          "value": "1968-10-18",
41          "verified": true
42        },
43        "gender": {
44          "value": "M",
45          "verified": true
46        },
47        "eyeColor": {
48          "value": "GRAY",
49          "verified": true
50        },
51        "height": {
52          "value": "6' 6",
53          "verified": true
54        }
55      }
56    }
57  ],
58  "addresses": [
59    {
60      "evidenceId": "f59d1a75-6bbd-4622-a7f4-548280e8b0ad",
61      "submitDateTime": "2020-12-11T13:52:12.1730538",
62      "type": "ADDRESS",
63      "evidenceStatus": {
64        "evaluationDateTime": "2020-12-11T13:53:30.1821823",
65        "status": "VERIFIED",
66        "strength": "LEVEL5",
67        "score": "LEVEL2",
68        "isAdjudicable": false
69      },
70      "referenceIds": ["106ee381-72b6-4301-baf6-a8cd5c8e9491"],
71      "addressData": {
72        "streetDetails": {
73          "streetLines": ["12 COTTONWOOD RD", "SUITE 1001"],
74          "verified": true
75        },
76        "postcode": "12345",
77        "city": "EMPIRE",
78        "state": "NV",
79        "country": "USA",
80        "verified": true
81      }
82    }
83  ],
84  "idDocuments": [
85    {
86      "evidenceId": "106ee381-72b6-4301-baf6-a8cd5c8e9491",
87      "submitDateTime": "2020-12-11T13:52:12.1730528",
88      "type": "DRIVING_LICENSE",
89      "evidenceStatus": {
90        "evaluationDateTime": "2020-12-11T13:53:30.1821823",
91        "status": "VERIFIED",
92        "strength": "LEVEL3",
93        "score": "LEVEL2",
94        "isAdjudicable": false,
95        "positiveIndicators": [
96          "MODEL_RECOGNIZED_OK",
97          "HIGH_TEMPLATE_OK",
98          "CB2D_FIELDS_SYNTAX_OK",
99          "DOCUMENT_BARCODE_PARSING_OK",
100          "LOW_TEMPLATE_OK",
101          "VISUAL_SECURITY_OK",
102          "PHOTOCOPY_DETECTION_OK",
103          "PERSONAL_NUMBER_CHECKSUMS_OK",
104          "MODEL_COLOR_MATCHING_OK",
105          "PORTRAIT_OK",
106          "LCD_DETECTION_OK",
107          "ESFX_OK",
108          "OCRX_OK",
109          "SIDES_DATA_CONSISTENCY_OK",
110          "DOC_EXPIRATION_DATE_OK",
111          "BIRTHDATE_VALID_OK",
112          "DOC_ISSUING_COUNTRY_OK",
113          "GLARE_IMAGE_QUALITY_FRONT_OK",
114          "OCR_ISSUING_DATE_OK",
115          "IMAGE_FRONT_DPI_CHECK_OK",
116          "PAPER_COPY_OK",
117          "DOC_NATIONALITY_OK",
118          "ISSUING_DATE_VALIDITY_OK",
119          "EXPIRATION_DATE_CONSISTENCY_OK",
120          "OCR_SEX_OK",
121          "OCR_EXPIRATION_DATE_OK",
122          "PHOTO_LOCATION_OK",
123          "BLUR_IMAGE_QUALITY_FRONT_OK",
124          "OCR_FIRSTNAMES_OK",
125          "OCR_BIRTHDATE_OK",
126          "OCR_DOCNUM_OK",
127          "OCR_FULLNAME_OK"
128        ],
129        "warningIndicators": [
130          "LOW_IMAGE_QUALITY_FRONT_WARNING",
131          "KEYSTONE_IMAGE_QUALITY_FRONT_WARNING",
132          "BLUR_IMAGE_QUALITY_BACK_WARNING",
133          "GLARE_IMAGE_QUALITY_BACK_WARNING"
134        ],
135        "unverifiedIndicators": [
136          "MRZ_CHECKSUMS_UNVERIFIED",
137          "DOCUMENT_NUMBER_VALIDITY_UNVERIFIED",
138          "COMPROMISED_DOCUMENT_CHECK_UNVERIFIED",
139          "TEXTURE_ANALYSIS_UNVERIFIED",
140          "MRZ_BARCODE_CROSSCHECK_UNVERIFIED"
141        ]
142      },
143      "idDocumentData": {
144        "idDocumentType": "DRIVING_LICENSE",
145        "idDocumentNumber": "000000000016",
146        "issuingCountry": "USA",
147        "issuingState": "WA",
148        "issuingDate": "2015-04-01",
149        "expiryDate": "2021-04-01",
150        "personalAttributes": {
151          "givenNames": [
152            {
153              "value": "CHRISTOPHE",
154              "verified": true
155            }
156          ],
157          "surname": {
158            "value": "ULYSSE",
159            "verified": true
160          },
161          "fullname": {
162            "value": "CHRISTOPHE ULYSSE",
163            "verified": true
164          },
165          "dateOfBirth": {
166            "value": "1968-10-18",
167            "verified": true
168          },
169          "gender": {
170            "value": "M",
171            "verified": true
172          },
173          "eyeColor": {
174            "value": "GRAY",
175            "verified": true
176          },
177          "height": {
178            "value": "6' 6",
179            "verified": true
180          }
181        },
182        "address": {
183          "streetDetails": {
184            "streetLines": ["12 COTTONWOOD RD", "SUITE 1001"],
185            "verified": true
186          },
187          "postcode": "12345",
188          "city": "EMPIRE",
189          "state": "NV",
190          "country": "USA",
191          "verified": true
192        }
193      }
194    }
195  ]
196}

Check the levelOfAssurance value to see the current score of the identity created.

The client application has the capability to check the status of all the submitted data. The identity document details and verification results are in the “idDocuments” structure.

API Feedback 

This section contains error codes and indicators in relation to the live document capture.

Note: If the live capture was successful, document authentication is performed automatically. Other indicators or errors related to document authentication may still appear.

Error Codes 

Error codes in relation to document live capture:

Indicators 

The following indicators can be raised by the document live capture.