Getting Started 

This guide will allow you to create an example ID proofing scenario using the ID&V API. You will learn to validate an identity document (ID) and verify a user's face against the ID's portrait.

ID Proofing Use Case Steps 

The steps of the example use case are:

• Step 1: Create an identity to be processed by ID&V
• Step 2: Send user consents
• Step 3: Verify an ID document
• Step 4: Check the status of the ID document
• Step 5: Check the status of the identity
• Step 6: Verify a selfie against the previously verified ID document
• Step 7: Check the status of the portrait
• Step 8: Check the status of the identity
• Step 9: End the process and retrieve the proof file (transaction result)

UML Diagram for Web Service Calls 

The UML diagram below explains all the steps for Web service calls to ID&V.

Process Steps for Web Service Calls

These Web service calls processes are shown in the UML diagram above.

Step 1: Create the Identity

• The GIPS-UA API Key from the User Agent and the GPIS-RS API Key from the Relying Service to start the registration process.
• The identity is created.
• The User Agent uses a POST command to send the URL identity request to ID&V
• The identityID is returned and the identity is created

Step 2: Submit Consent on Portrait

• The User Agent uses a POST command to send the identityID request consent to ID&V.

Step 3: Capture Identity Document

• The POST command is used to submit the identity document capture (IDENTITY_CARD) request to ID&V.
• The HTTP 200 response for Identity document PROCESSING is returned to the User Agent.

Step 4: Polling on Identity Document Status while PROCESSING

• The User Agent uses a GET command to make a request for an identity document status check to ID&V.
• The identity document status response is returned to the User Agent.

Step 5: Retrieve Identity Status

• The User Agent uses a GET command to make a request to retrieve the identity status from ID&V.
• The HTTP 200 response for identity status LOA and identity document & attributes status is returned to the User Agent.

Step 6: Capture Selfie

• The User Agent uses a POST command to submit the user's portrait selfie capture to ID&V.
• The HTTP 200 response for portrait status PROCESSING is returned to the User Agent.

Step 7: Polling on Portrait Status while PROCESSING

• The User Agent uses a POST command to request the Portrait Status from the ID&V.
• The HTTP 200 response for portrait status is returned to the User Agent.

Step 8: Retrieve Identity

• The User Agent uses a GET command to request retrieval of the identity ID from ID&V.
• The HTTP 200 response for identity status LOA and identity document & attributes status is returned to the User Agent.

Step 9: Retrieve Proof

• The User Agent confirms that the process is done.
• The User Agent uses a GET command to request the identity proof from ID&V.
• GET Proof request is forbidden if the status of transaction is PROCESSING, GIPS will returned HTTP 403 to the Relying Service.
• The HTTP 200 proof response is returned to the Relying Service.
• The Relying Service processes and stores the proof
• The User Agent is notified that the end of the process has been reached.

Web Services Calls 

There are many ways to implement the appropriate web service requests, depending upon your programming language.

A Web service is an application designed to communicate with other programs. It can be accessed using a standard Web protocol (HTTP or HTTPS).

The request examples in this section use the cURL tool syntax.

Request URL Variables 

The variables used in the request URLs are are shown below.

Step 1: Create an Identity 

This request creates the identity for the provided user documents to initiate the verification process.

Example Identity Request

The sample identity request is shown in the snippet:

Shell
1curl -X POST https://[URL_MAIN_PART]/gips/v1/identities  \
2  -H 'Content-Type: multipart/form-data' \
3  -H 'apikey: [APIKEY_VALUE]'

Request Variables

The variables for the identity request are shown below.

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

Example Identity Response

An example identity response is shown in the snippet:

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}

Response Variables

The variables used for the identity response as shown below.

Step 2: Send Consent 

Consent is a notification from the client application to the Web service that the end-user consents to their identity evidence being processed by the service.

With this request, the client application notifies the Web service that the user consented to the use of their portrait for biometrics processing.

It allows the web service to extract biometric data from the selfie and match it against the picture in the ID document that will be provided.

Example Consent Request

An example consent notification request notification to the ID&V is shown in the snippet:

Shell
1curl -X POST \
2  https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/consents \
3  -H 'Content-Type: application/json' \
4  -H 'apikey: [APIKEY_VALUE]' \
5  -d '[{
6    	"approved": true,
7    	"type": "PORTRAIT"
8      }]'

Request Variables

The variables used in the consent request are shown below.

Example Consent Response

An example consent response is shown in the snippet:

JSON
1[
2  {
3    "consentId": "be5d9a77-5706-41ff-b8d6-e14a555cb0a7",
4    "approved": true,
5    "type": "PORTRAIT",
6    "validityPeriod": {
7      "to": "2019-05-20"
8    }
9  }
10]

Response Variables

The variables used in the consent response are shown below.

Step 3: Verify an ID Document 

There are 2 ways to provide an ID document for verification:

• Direct upload : that requires the ID document upload using ID&V API. Refer to the example below.
• Live document capture : that requires a live document capture session to be created with ID&V. Refer to Live Document Capture

With these requests, 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

Example ID Verification Request

An example request to submit an ID document to the Web service for processing is shown in the snippet:

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]'

Request Variables

The variables used in the document verification request are shown below.

DocumentCaptureDetails is a JSON file with the format shown in the snippet:

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

DocumentCaptureDetails Variables

The variables used in the DocumentCaptureDetails file are shown below.

Example ID Verification Request

An example document verification request is shown in the snippet:

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

Request Variables

The variables used in the document verification request are shown below.

Step 4: Check Document Status 

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

Example Document Status Request

An example request to check the processing status of the submitted ID document is shown in the snippet:

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

Request Variable

The request variable to check the document status is shown below.

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

Example Document Status Response

An example to check the document processing status is shown in the snippet:

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

Response Variables

The response variables to check the document status are shown below.

Variable Values

The possible values for the status variable are shown below:

• VERIFIED - This value indicates 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 - This value indicates that the document/face is considered invalid after the checks are performed.

• NOT_VERIFIED - This value indicates that the document/face was processed, but not enough checks were performed to make a verification decision. Most of the time this occurs due to the bad quality of the image or an unsupported document type.

• PROCESSING - This value indicates that the evidence is currently being processed by the service.

• ADJUDICATION - This value indicates that the evidence is currently reviewed by a human expert.

Step 5: Check Identity Status 

With this request, the client application can check the status of the identity and see which level of assurance (LOA) has been achieved.

Example Identity Status Request

An example request to check the status of the identity and the LOA is shown in the snippet:

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

Example Identity Status Response

An example response to the identity status request and the LOA is shown in the snippet:

JSON
1{
2  "globalStatus": {
3    "id": "afc85bca-d46c-4653-8053-1f4790f1a582",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA1"
6  },
7  "consents": [],
8  "attributes": [],
9  "addresses": [],
10  "idDocuments": [
11    {
12      "evidenceId": "8c6240fd-6b48-4a97-a847-1ae7e8e96ccb",
13      "submitDateTime": "2019-05-13T16:59:20.15",
14      "type": "DRIVING_LICENSE",
15      "evidenceStatus": {
16        "evaluationDateTime": "2019-05-13T17:01:21.036",
17        "status": "VERIFIED",
18        "strength": "LEVEL3",
19        "score": "LEVEL3"
20      },
21      "idDocumentData": {
22        "idDocumentType": "DRIVING_LICENSE"
23        // ...
24      }
25    }
26  ]
27}

LOA Values

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

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

• Step 2: Summarized in the consents structure
• Step 3: Summarized in the idDocuments structure

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

Step 6: Verify a Selfie Against an ID Document 

With this request, the client application can submit a portrait picture of the user for processing.

Example Request for Selfie Verification

An example request to verify a selfie against an ID document is shown in the snippet:

Shell
1curl -X POST \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/attributes/portrait/capture \
3-H 'Content-Type: multipart/form-data' \
4-H 'apikey: [APIKEY_VALUE]' \
5-F 'Portrait=@[ABSOLUTE_LOCAL_PATH_TO_SELFIE]'

Request Variables

The request variables to verify the selfie are shown below.

Example Response for Selfie Verification

An example response to verify a selfie against an ID document is shown in the snippet:

JSON
1{
2  "status": "PROCESSING",
3  "type": "PORTRAIT",
4  "id": "2d5e81c6-a600-47ed-aa22-2101b940fed6"
5}

Response Variables

The response variables for selfie verification are shown below.

To learn more about this web service, see the Documentation section in the API Explorer section of the Developer Portal.

Step 7: Check the Status of the Portrait 

With this request, the client application checks the status of the submitted portrait.

Example Request to Check Portrait Status

An example request to check the status of the submitted user portrait is shown in the snippet:

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

Request Variables

The request variables to check the status of the user portrait are shown below.

Example Response to Check Portrait Status

An example response to checking the status of the submitted user portrait is shown in the snippet:

JSON
1{
2  "status": "INVALID",
3  "type": "PORTRAIT",
4  "id": "97d8354e-7297-4eba-be39-1569d4c6342b"
5}

Response Variables

The response variables to check the portrait status are shown below.

Values for Status Variable

The values for the status variable include the following:

• 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

Step 8: Check the Status of the Identity 

This is the same request as in Step 5, but the result is slightly different, as portrait verification has taken place since then.

Example Identity Status Response

An example status response for the identity check is shown in the snippet:

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  "consents": [
13    {
14      "consentId": "be5d9a77-5706-41ff-b8d6-e14a555cb0a7",
15      "approved": true,
16      "type": "PORTRAIT",
17      "validityPeriod": {
18        "to": "2018-11-20T16:00:19.538Z"
19      }
20    }
21  ],
22  "attributes": [
23    {
24		...
25    }
26  ],
27  "idDocuments": [
28    {
29		...
30    }
31  ],
32  "portrait": {
33	...
34  }
35}

Note: The current LOA should have a value of 2, increased since Step 5 because of portrait verification portrait > evidenceStatus > status = VERIFIED (as in Step 6). A new element was included that was not in Step 5, namely "portrait."

For more details on the response content, see the corresponding Swagger documentation in the API Docs section of the Portal.

Step 9: Ending the Process and Retrieving the Proof 

With this request, the client application terminates the proofing process and retrieves all information that the Service has gathered and generated.

GET Proof request is forbidden if the status of transaction is PROCESSING, GIPS will returned HTTP 403 to the Relying Service.

In response to this request, the client application receives an archive file. The client application may archive this file for audit purpose and use its content as a reference for the user's identity.

Getting the proof terminates the transaction and the Service applies the deletion policy to the personal information gathered during the session.

Example Request for Identity Proofing File

An example request for the identity proofing file that references the user's identity is shown in the snippet:

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

Request Variables

The request variables for the identity proofing file are shown below.