Biometric Verification 

This document describes how to use the ID&V API for verifying an individual’s claimed identity by using biometric matching between the user portrait (selfie) and the portrait extracted from a reference Identity Document.

Requirements 

To enable face-matching as part of an ID proofing process, a client application needs an API key and a URL to access the ID proofing service.

Additionally, the client application must notify the ID&V service that it has obtained the user’s consent for processing their self-portrait image.

Scenarios 

There are two main scenarios for verifying a self-portrait image (“selfie”) of an individual:

• Comparing a submitted self-portrait image capture against a single identity document provided by the user

• Comparing a submitted self-portrait image capture against multiple identity documents provided by the user

Scenario 1: Comparing a self-portrait against a single identity document 

In the example below, we use a passport as the ID document.

Step 1: Create Identity: This request initiates the verification process with ID&V.

Step 2: Submit Consent: Consent is a notification from the client application to ID&V that the end-user consents to his/her personal information (in this case, their portrait image) being processed by ID&V for a given period.

Step 3: Submit ID Document

1. ID&V performs the document authentication.

2. If the ID document is valid:

   1. ID&V crops the portrait image from the ID document.
   2. ID&V performs the biometric coding of the cropped image to verify the quality of the portrait.
   3. ID&V selects the cropped image as the face reference image.
   4. ID document status becomes VERIFIED and ID document is assigned a score (LEVEL2, for example).

Step 4: Submit Self-portrait Image

ID&V performs the face biometric matching between the reference image cropped from the ID document and the submitted self-portrait image.

• If the portrait images match, the portrait status is VERIFIED and portrait is assigned a score equal to the score of the document from which the reference image was extracted (if ID document score is LEVEL2, then portrait score after successful matching will also be LEVEL2).

• If the portrait images do not match, the portrait status is INVALID and portrait is assigned a LEVEL0 score and an error code.

The status and score of the ID document does not change.

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

Scenario 2: Comparing a self-portrait against multiple identity documents 

In the example below, we use an ID card as ID document #1 and a passport as ID document #2.

Step 1: Create Identity: This request initiates the verification process with ID&V.

Step 2: Submit Consent: Consent is a notification from the client application to ID&V that the end user consents to his/her personal information (in this case, their portrait image) being processed by ID&V for a given period.

Step 3: Submit Identity Card

ID&V performs the document authentication. If the ID Card is valid:

1. ID&V crops the portrait image from the ID document.
2. ID&V performs the biometric coding of the cropped image.
3. ID card status is verified and the ID card assigned a score (LEVEL2, for example).

Step 4: Submit Passport

ID&V performs the document authentication. If the passport is found to be valid:

1. ID&V crops the portrait image from the passport.
2. ID&V performs the biometric coding of the cropped image.
3. Passport status is verified and the passport assigned a score (also LEVEL2, for example).

Step 5: Submit Self-portrait Image

ID&V performs the face biometric matching between the submitted self-portrait and the images cropped from the ID documents. ID&V then selects one reference portrait based on the rule defined later in this document.

• If the portrait images match with the elected reference, portrait status is VERIFIED with a score equal the score of the document the reference image was extracted from (If ID Document score is LEVEL2, then Portrait score after successful matching will be LEVEL2 also).

• If the portrait images do not match, portrait status is INVALID with a LEVEL0 score and an error code.

Note: If the submitted live self-portrait does not match a portrait extracted from a document that is not the reference document, this document’s status will remain valid, but a BIOMETRIC_MATCHING_CHECK_FAILED indicator will be raised in the warning indicators to highlight that this document did not match the portrait submitted by the user, and may be considered for a document capture retry, or manual review.

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

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 Consent 

Consent is a notification from the client application to ID&V that the end-user consents to his/her personal information (in this case, their portrait image) being processed by ID&V for a given period.

With this request, the client application notifies ID&V that the user has consented to the biometric processing of his/her portrait image.

The request looks like this:

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

Sample response:

JSON
1[
2  {
3    "consentId": "05248dc7-5687-4a95-a127-514829e9b68c",
4    "approved": true,
5    "type": "PORTRAIT",
6    "validityPeriod": {
7      "to": "2019-11-13",
8    }
9  }
10]

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

Verify a Selfie Against an ID Document 

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

The request looks like this:

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

Sample response:

JSON
1{
2  "status": "PROCESSING",
3  "type": "PORTRAIT",
4  "id": "2d5e81c6-a600-47ed-aa22-2101b940fed6"
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 Status of the Portrait 

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

The request looks like this:

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

Sample response:

JSON
1{
2  "status": "INVALID",
3  "type": "PORTRAIT",
4  "id": "97d8354e-7297-4eba-be39-1569d4c6342b"
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 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, indicators, and scoring.

Error Codes 

These are the error codes in relation to face matching:

Indicators 

By default, ID&V is configured with the following blocking indicators:

Scoring 

Once a portrait has been submitted, results of the biometric matching are combined by the ID proofing service to increase the score of the portrait evidence.

Here is the summary of the portrait image scoring:

Example:

Evidence references and their scoring and level indications:

• PASSPORT, Document Authentication only: Passport status is VERIFIED at LEVEL2 then Portrait status is also VERIFIED at LEVEL2
• Driver's License (US), Document Authentication + Issuing Source Verification: If Driver's License status is VERIFIED at LEVEL3, then the Portrait status is also VERIFIED at LEVEL3
• PASSPORT, Document Authentication only: if Passport status is VERIFIED at LEVEL2, then Portrait status is also VERIFIED at LEVEL2
• Driver's License (US), Document Authentication + Issuing Source Verification: if Driver's License status is VERIFIED at LEVEL3, then Portrait status is also VERIFIED at LEVEL3

Decision Rules and Reference Portrait Election 

In order to check that the user is the same person as the person on the ID document, ID&V performs a biometric comparison between the submitted self-portrait image and all the submitted evidences that contain a portrait image (such as passport, ID card, driver’s license):

• If the biometric matching score is above the configured tolerance threshold, then the portrait images are considered to match.

• If not, portrait images are considered not to match.

ID&V then selects the reference portrait image where multiple evidences are submitted. This is done as follows:

• ID&V selects the evidence with the highest verification score.

• If multiple evidences have the same verification score, then ID&V selects the one with the highest coding quality score.

• If the evidences have the same quality score too, then ID&V selects the one with the highest matching score.

• Finally, if no single evidence has been elected at this stage, ID&V selects the most recently received evidence.

ID&V’s face matching process

Face Matching Configuration 

ID&V is configured with a tolerance threshold for biometric matching that determines whether a biometric comparison matches or not; and it will incur a false acceptance rate (FAR) and a false rejection rate (FRR).

Depending on use case constraints, an acceptable balance between FAR and FRR is determined using the tolerance threshold. The tolerance threshold can be configured, but should take into account the following trade-off:

• Low FAR implies high FRR
• Low FRR implies high FAR

FRR and FAR defined:

Face Matching trade-off Graphical representation