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.

usecase-steps

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.

Variable
Description
URL_MAIN_PARTThe Service domain
APIKEY_VALUEClient application API key as provided by portal administrator(s)
IDENTITY_IDThe value obtained after performing Step 1 is below. This should be the id value from the Create Identity response message.

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]/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.

Variable
Description
URL_MAIN_PARTThe Service domain
APIKEY_VALUEThe client application API key as provided by your administrator(s)
IDENTITY_IDThe value obtained after performing Step 1 that should be the id value from the Create Identity response message

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.

Variable
Description
idThe identity ID that will be used to identify the current transaction in other requests.
statusStatus of the transaction
levelOfAssurance (LOA)Level of trust of current identity
creationDateTimeIdentity creation date
evaluationDateTimeLast date on which the identity was evaluated
upgradePathsList of possible submissions that would increase LOA

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.

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

Shell
1curl -X POST \
2 https://[URL_MAIN_PART]/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.

Variable
Description
URL_MAIN_PARTThe Web service domain
APIKEY_VALUEClient application API key as provided by your administrator(s)
IDENTITY_IDValue obtained after performing Step 1. This value should be the id value from the Create Identity response message.

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.

Variable
Description
consentIdThe consent ID that might be used to identify the submitted consent.
approvedBoolean indicating status of the consent (true/false)
typeType of consent submitted (possible values may be: PORTRAIT, GIV). The enumerated value can be found under the API Docs section in the Portal.
creationDateTimeIdentity creation date
validityPeriodThe period for which the consent is considered valid.
toThe date at which the consent will expire and will not be considered valid anymore.

Step 3: Verify an ID Document 

With this request, the client application submits an ID document to the web service 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]/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.

Variable
Description
URL_MAIN_PARTThe Service domain
APIKEY_VALUEClient application API key as provided by your Administrator(s)
IDENTITY_IDValue retrieved after performing Step 1. This should be the id value from the Create Identity response message.
ABSOLUTE_LOCAL_PATH_TO_IDDOCUMENT_FRONTValue of the absolute path to the local file for use in identifying document front. For instance: "C:\mydocumentfront.jpg"
ABSOLUTE_LOCAL_PATH_TO_IDDOCUMENT_BACKValue of the absolute path towards the local file to use to identify document back/reverse side. For instance: "C:\mydocumentback.jpg." This field is only mandatory in some use cases. See FAQ for more details.
ABSOLUTE_LOCAL_PATH_TO_ DOCUMENTCAPTUREDETAILSDocumentCaptureDetails is used to attach a JSON file containing specific information regarding the document being tested. This field is optional, but attaching this file can greatly improve the quality of the Service response.

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.

Variable
Description
COUNTRY_CODEAlpha-3 code from ISO 3166-1 (e.g., USA for the United States, DEU for Germany)
DOCUMENT_TYPEOne of the supported document types (excepted values are PASSPORT, DRIVING_LICENSE, RESIDENT_CARD, IDENTITY_CARD, TAX_CARD, VOTER_CARD.)
IMAGE_SOURCEInformation about how the image was captured: LIVE_CAPTURE_IMAGE if the identity document image has been taken live with the Document Capture SDK at the time of the transaction; LIVE_CAPTURE_VIDEO if the identity document image was extracted from a video; SCAN if the photo of the identity document is captured with a flat scanner; or OTHER for other source.

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.

Variable
Description
idThe document identifier that will be used in all future requests (Step 4)
statusDocument status
typeThe document type

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]/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.

Variable
Description
IDDOCUMENT_IDThe value retrieved after performing the previous step. The content of this value should be taken from the id value of Evaluate an ID Document response message.

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
Description
IDThe document identifier.
StatusProcessing status of the ID document.
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]/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]/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.

Variable
Description
URL_MAIN_PARTThe Service domain
APIKEY_VALUEClient application API key as provided by your administrators
IDENTITY_IDValue obtained after performing Step 1. This value should be the id value from the Create Identity response message.
ABSOLUTE_LOCAL_PATH_TO_SELFIEValue of the absolute path towards the local file to use for portrait verification. For instance: "C:\myselfie.jpg".

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.

Variable
Description
idThe user portrait identifier that will be used in future requests (Step 7).
statusStatus of the portrait.

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]/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.

Variable
Description
URL_MAIN_PARTThe Service domain.
APIKEY_VALUEClient application API key as provided by your administrator(s).
IDENTITY_IDValue obtained after performing Step 1. This value should be the id value from the Create Identity response message.
PORTRAIT_IDValue obtained after performing Step 6. The content of this value should be taken from the id value of the Evaluate a Portrait response message. The client application can use this API to implement polling and go to the next steps only when certain that the portrait's status is VERIFIED, otherwise it will prompt the user to retry with another portrait capture.

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.

Variable
Description
idThe portrait's ID.
typeType of the evidence (here PORTRAIT).
statusStatus of the portrait processing.
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]/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.

Variable
Description
URL_MAIN_PARTThe Service domain
APIKEY_VALUEClient application API key as provided by your administrator(s)
IDENTITY_IDValue obtained after performing Step 1. This value should be the id value from the Create Identity response message.