Pause resume identity 

This document describes how to use the pause/resume identity feature while document being in adjudication process or and transaction lifetime has expired.

Requirements 

To enable pause/resume feature the tenant should be configured to use webhook notification and request an api key for tenant configured to support Pause/Resume feature

Scenarios 

Pause/Resume feature can be used in two-way:

• Adjudication use case where paused transaction is resumed by adjudication response.

• Client controlled use case where paused transaction is resumed by invoking the resume endpoint.

Scenario 1: Adjudication use case 

In the example below a document is submitted for verification and adjudication is required. While waiting for adjudication response the transaction expires and then is paused. upon receiving adjudication response

Scenario 2: Expired transaction paused and resumed with explicit api call 

In the example below we are verifying 2 documents on a relatively long period of time which cause transaction to be paused

Web Service Calls 

There are many ways to implement the appropriate Web Service requests depending on your programming language. For the sake of clarity, the request examples use the cURL tool syntax.

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: multipart/form-data' \
3-H 'apikey: [APIKEY_VALUE]'

When this request is sent, the ID&V response contains an id field. The value of that field replaces IDENTITY_ID in subsequent requests.

Sample response:

JSON
1{
2  "id": "d4eee197-69e9-43a9-be07-16cc600d04e8",
3  "status": "EXPECTING_INPUT",
4  "levelOfAssurance": "LOA0",
5  "creationDateTime": "2018-11-20T13:41:00.869",
6  "evaluationDateTime": "2018-11-20T13:41:00.883",
7  "upgradePaths": {}
8}

Submit a Document Capture 

With this request, the client application submits an ID document to ID&V for processing. The supported ID document types are:

• Passport

• Identity card

• Driver's license

• Resident card

The request looks like this:

Shell
1curl -X POST \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/id-documents/capture \
3-H 'Content-Type: multipart/form-data' \
4-H 'apikey: [APIKEY_VALUE]' \
5-F 'DocumentFront=@[ABSOLUTE_LOCAL_PATH_TO_IDDOCUMENT_FRONT]'
6-F 'DocumentBack=@[ABSOLUTE_LOCAL_PATH_TO_IDDOCUMENT_BACK]'
7-F 'DocumentCaptureDetails=@[ABSOLUTE_LOCAL_PATH_TO_DOCUMENTCAPTUREDETAILS]'

DocumentCaptureDetails is a JSON file with the following format:

JSON
1{
2  "jurisdiction": "[COUNTRY_CODE]",
3  "documentType": "[DOCUMENT_TYPE]",
4  "source": "[IMAGE_SOURCE]"
5}

Sample response:

JSON
1{
2  "status": "PROCESSING",
3  "type": "PASSPORT",
4  "id": "96541141-c44b-4606-9423-5e0486395b60"
5}

Check Document Status 

With this request, the client application checks the processing status of the submitted ID 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: [APIKEY_VALUE]'

The client application can use this API to implement polling and proceed to the next steps only when it's certain that the document’s status is VERIFIED, or it will prompt the user to retry with another document capture.

Sample response:

JSON
1{
2  "status": "VERIFIED",
3  "type": "DRIVING_LICENSE",
4  "id": "afe08d37-5f4d-4c07-ab77-d8041e0dcd3a"
5}

Values for status can be:

• VERIFIED - means that document/face has successfully been verified. When VERIFIED, a Document/Face 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/face is considered invalid after the checks performed

• NOT_VERIFIED - means that the document/face was processed, but not enough checks were performed to take a decision, most of the time due to bad quality of the image, or an unsupported document type

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

• ADJUDICATION - means that the evidence is currently reviewed by a human expert

Check Identity status 

With this request, the client application can check the status of the identity

The request looks like this:

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

Sample response:

JSON
1{
2  "globalStatus": {
3    "id": "gips-ec79288a-9cce-4e78-a6db-bc4e901d086d",
4    "status": "PAUSED",
5    "levelOfAssurance": "LOA0",
6    "creationDateTime": "2024-03-28T12:45:23.8886699",
7    "evaluationDateTime": "2024-03-28T12:44:49.9885224",
8    "upgradePaths": {}
9    }
10  }

Resume identity 

With this request, the client application request resume auf previously paused transaction.

The request looks like this:

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

response sent is the same as the one when getting identity: GET https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]

Get Identity 

With this request, the client application can check the status of the identity and sees what level of assurance (LOA) has been reached.

The request looks like this:

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

Sample response:

JSON
1{
2  "globalStatus": {
3    "id": "string",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA2",
6    "creationDateTime": "2018-11-20T16:00:19.537Z",
7    "evaluationDateTime": "2018-11-20T16:00:19.537Z",
8    "nameReferenceEvidenceId": "96541141-c44b-4606-9423-5e0486395b60",
9    "portraitReferenceEvidenceId": "2d5e81c6-a600-47ed-aa22-2101b940fed6",
10    "upgradePaths": {
11    }
12  },
13  "consents": [
14    {
15      "consentId": "be5d9a77-5706-41ff-b8d6-e14a555cb0a7",
16      "approved": true,
17      "type": "PORTRAIT",
18      "validityPeriod": {
19        "to": "2018-11-20T16:00:19.538Z"
20      }
21    }
22  ],
23  "attributes": [
24    {
25     "evidenceId": "71603983-dfd4-40cf-8ce0-a451597adc81",
26     "submitDateTime": "2019-06-24T16:13:20.445",
27     "type": "ATTRIBUTES",
28     "evidenceStatus": {
29     "evaluationDateTime": "2019-06-24T16:13:49.599",
30     "status": "VERIFIED",
31     "strength": "LEVEL5",
32     "score": "LEVEL2"
33    }
34   }
35  ],
36    "idDocuments": [
37    {
38        "evidenceId": "8c6240fd-6b48-4a97-a847-1ae7e8e96ccb",
39        "submitDateTime": "2019-05-13T16:59:20.15",
40        "type": "DRIVING_LICENSE",
41        "evidenceStatus": {
42        "evaluationDateTime": "2019-05-13T17:01:21.036",
43        "status": "VERIFIED",
44        "strength": "LEVEL3",
45        "score": "LEVEL2"
46        },
47        "idDocumentData": {
48        "idDocumentType": "DRIVING_LICENSE",
49        ...
50      }
51    }
52  ],
53  "portrait": {
54    "evidenceId": "1a5a4509-97fc-427f-ae00-60d958e0d382",
55    "submitDateTime": "2019-07-01T14:50:44.006",
56    "type": "PORTRAIT",
57    "evidenceStatus": {
58    "evaluationDateTime": "2019-07-01T14:50:44.087",
59    "status": "VERIFIED",
60    "strength": "LEVEL4",
61    "score": "LEVEL2"
62  }
63  }
64}

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

The client application can also check the status of all submitted data:

• Portrait is summarized in the “portrait” structure

• Identity document is summarized in the “idDocuments” structure

The rest of the response contains various information like the upgrade path to improve LOA, or attributes (personal information extracted from documents, or submitted by the user).

Ending the Process and Retrieving the Proof File 

With this request, the client application terminates the ID&V process and retrieves all the information that ID&V has gathered and generated.

In response to this request, the client application receives an archive file and ID&V discards all personally identifiable information related to the ID proofing use case.

The client application is supposed to store this archive file and use it as a reference for the user’s identity.

The request looks like this:

Shell
1curl -X GET \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/proof \
3  -H 'apikey: [APIKEY_VALUE]' -o proof

API Feedback 

This section describes error codes.

Error Codes 

These are the error codes related to pause/resume identity feature