Document Validation Against a System of Record 

This section describes how to use the ID&V API for verifying an individual’s identity by validating identity documents' data against their issuers' databases, the System of Record (SoR).

Issuing Source Validation 

Supported Issuing Sources 

The process of Issuing Source Validation compares documents data found on different type of ID Documents against the issuer database.

As of now, ID&V supports the following issuing sources :

• Australian Document Verification System (DVS)
• USA Motor Vehicle Administrations (MVAs)

The access to the Issuing Source Validation is disabled by default. To activate it, contact your Idemia sales representative.

Australian Issuer Verification 

The supported document for the Australian issuer verification are :

• Passport
• Driving License
• Resident Card
• Visa
• Medicare Card

Applicable states for Australia are:

USA Issuer Verification 

The supported documents for US issuer verification are :

• Driving License
• Driving Permit
• Identity Cards

However, the service does not support all US jurisdictions for all documents. Additionally, some jurisdictions specify restrictions on which categories of users can conduct an identity check.

Motor vehicle agencies in most jurisdictions support the verification of driver licenses and identity cards.

A few jurisdictions only support the verification of licenses or a limited set of their identity cards. (See table below.)

Requirements 

To enable issuing source validation as part of an ID proofing process, a client application needs:

• An API key and URL to access the ID proofing service

• A tenant configured to have issuing source validation activated.

• Consent from the user to perform verification of the provided identity evidence against its issuing source. This needs to be provided to ID&V Service before submitting the document data. Consent is notified using another API (see Webservice Calls), using the value "GIV".

Scenarios 

Issuing Source Validation Results 

The result of the Issuing Source Validation process is indicated by the value of the indicator "GIV_VERIFICATION" at the evidence level.

• GIV_VERIFICATION_VERIFIED: indicates an Issuing Source Validation was performed and found a match in the appropriate database
• GIV_VERIFICATION_UNVERIFIED: indicates an Issuing Source Validation was performed but result is inconclusive
• GIV_VERIFICATION_FAILED: indicates an Issuing Source Validation was performed but didn't found a match in the appropriate database

Another indicator to watch is "GIV_ELIGIBILITY", this indicator indicates if the document is compatible with any available Issuing Source.

Impact on scoring is detailed here

Scenarios Description 

The issuing source validation service can be used in two ways:

1. Document-image-based Submission: Document genuineness is checked. The document and identity details are then extracted from the document using OCR and provided to the issuing source for verification. Results of the document authentication checks and issuing source checks are combined by the service to increase the score of the document verification.
2. Text-Based Submission Document and identity details are submitted as text in the web service request payload.

Sequence Diagram 

Each step corresponds to a web service call to ID&V.

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.

Note: A POSTMAN project is available from the IDEMIA Developer Portal.

The main variables used in the request URLs are:

• URL_MAIN_PART = the ID&V domain

• APIKEY_VALUE = client application API key as provided by portal administrator(s)

• IDENTITY_ID = the value obtained after performing Step 1 below. This should be the ‘id’ value from the Create Identity response message

Step 1: 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]'

Sample response:

JSON
1{
2  "id": "gips-4b96cb4a-9b8e-44b2-b49d-ced4e5838a93",
3  "status": "EXPECTING_INPUT",
4  "levelOfAssurance": "LOA0",
5  "creationDateTime": "2020-12-08T22:32:57.1837056",
6  "evaluationDateTime": "2020-12-08T22:32:57.6990367",
7  "upgradePaths": {}
8}

Step 2: Send Consent 

Consent is a notification from the client application to ID&V that the end-user consents to their personal information (identity evidence) being processed by ID&V.

With this request, the client application notifies ID&V that the user consented to have the provided Identity Document verified against the record held by the issuer of that document. The value submitted for this consent has to be : "GIV"

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": "GIV"
8}]'

Sample response:

JSON
1[
2  {
3    "consentId": "e8dcf1bb-1ac1-44bc-9d05-33c7c799b454",
4    "approved": true,
5    "type": "GIV",
6    "validityPeriod": {
7      "from": "2018-01-01",
8      "to": "2022-01-01"
9    }
10  }
11]

Step 3: Submit a Document for Verification 

There are two ways to verify a Identity Document against its issuing source :

• Submit the document images, or
• Submit the document details as text

Step 3a: Submit Document Images 

With this request, the client application submits an ID document images to ID&V for processing. The supported ID document types that enable Issuing source verification are:

• Identity card
• Driver's license

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": "DRIVING_LICENSE",
4  "id": "c3d57428-5939-4300-b17d-d8473ab5b9c3"
5}

Step 3b: Document Text-based Submission 

With this request, the client application submits all the details on the driver’s license as text to ID&V for processing. This is an alternative to document image submission.

It is not necessary to submit the document text details if the document images were previously provided as part of the verification against the issuing source and if the service has been notified of user consent.

The request looks like this:

Shell
1curl -X POST \
2  https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/id-documents \
3  -H 'Content-Type: application/json' \
4  -H 'apikey: [APIKEY_VALUE]' \
5  -d '{
6    "idDocumentType": "DRIVING_LICENSE",
7    "idDocumentNumber": "48101004",
8    "issuingCountry": "USA",
9    "issuingState": "AZ",
10    "issuingDate": "2010-01-01",
11    "expiryDate": "2030-01-01",
12    "personalAttributes": {
13        "givenNames": [{
14                "value": "CHRISTOPHE"
15            }
16        ],
17        "surname": {
18            "value": "ULYSSE"
19        },
20        "fullname": {
21            "value": "CHRISTOPHE ULYSSE"
22        },
23        "gender": {
24            "value": "M"
25        },
26        "dateOfBirth": {
27            "value": "1968-10-18"
28        },
29        "height": {
30            "value": "6"
31        },
32        "eyeColor": {
33                    "value": "GRAY"
34                }
35    },
36    "address": {
37        "streetDetails": {
38            "streetLines": [
39                "12 COTTONWOOD RD",
40                "SUITE 1001"
41            ]
42        },
43        "city": "EMPIRE",
44        "postcode": "12345",
45        "state": "NV"
46    }
47}'

Description of possible JSON fields in the payload:

• Expressed as a JSON object with a field value, e.g., {"name":"John"}

Step 3c: Medicare Card Submission 

With this request, the client application submits all the details on the Medicare Card as text to ID&V for processing.

The request looks like this:

Shell
1curl -X POST \
2  https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/id-document/aus/medicare \
3  -H 'Content-Type: application/json' \
4  -H 'apikey: [APIKEY_VALUE]' \
5  -d '{
6	"cardNumber": "1234567819",
7	"cardType": "B",
8	"issuingCountry": "AUS",
9	"expiryDate": "2030-01-01",
10	"individualReferenceNumber": 1,
11	"fullname2": "fullname Two",
12	"personalAttributes": {
13		"fullname": {
14			"value": "John Doe"
15		},
16		"dateOfBirth": {
17			"value": "1970-04-19"
18		}
19	}
20}'

Description of possible JSON fields in the payload:

Step 4: 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 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.

Sample response:

JSON
1{
2  "status": "VERIFIED",
3  "type": "DRIVING_LICENSE",
4  "id": "c3d57428-5939-4300-b17d-d8473ab5b9c3"
5}

status | Processing status of the ID document.|

Status

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

Indicators

See details in this dedicated section

Error Codes

See details in this dedicated section

Fuzzy Matching

Some issuing sources have a fuzzy matching capabilities for user names.

FIRSTNAME_COMPARE_FAILED and FIRSTNAME_COMPARE_UNVERIFIED does not block if the fuzzy first name comparison is OK. Likewise, with SURNAME_COMPARE_FAILED and SURNAME_COMPARE_UNVERIFIED do not block if the fuzzy surname (last name) comparison is OK.

When an exact match indicator for the first, middle, or last name components of the name indicates a mismatch, then additional fuzzy match indicators are returned to show if the supplied name is similar to the name on record. Users who enter data manually may make typos, so these fuzzy match indicators can assist users in spotting typographical errors, e.g., if the first name match indicator is "false" and the first name fuzzy primary match is "true," this indicates that the first name was a close match.

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.

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: [APIKEY_VALUE]'

Sample response:

JSON
1{
2  "globalStatus": {
3    "id": "gips-4b96cb4a-9b8e-44b2-b49d-ced4e5838a93",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA1",
6    "creationDateTime": "2020-12-08T22:32:57.1837056",
7    "evaluationDateTime": "2020-12-08T22:35:25.1472014",
8    "nameReferenceEvidenceId": "c3d57428-5939-4300-b17d-d8473ab5b9c3",
9    "portraitReferenceEvidenceId": "c3d57428-5939-4300-b17d-d8473ab5b9c3",
10    "upgradePaths": {}
11  },
12  "consents": [
13    {
14      "consentId": "e8dcf1bb-1ac1-44bc-9d05-33c7c799b454",
15      "approved": true,
16      "type": "GIV",
17      "validityPeriod": {
18        "from": "2018-01-01",
19        "to": "2022-01-01"
20      }
21    }
22  ],
23  "attributes": [
24    {
25      "evidenceId": "68fcaca4-030d-4769-8d68-edbc65134041",
26      "submitDateTime": "2020-12-08T22:35:25.1432065",
27      "type": "ATTRIBUTES",
28      "evidenceStatus": {
29        "evaluationDateTime": "2020-12-08T22:35:25.1472014",
30        "status": "VERIFIED",
31        "strength": "LEVEL5",
32        "score": "LEVEL3",
33        "isAdjudicable": false
34      },
35      "attributesData": {
36        "givenNames": [
37          {
38            "value": "CHRISTOPHE",
39            "verified": true
40          }
41        ],
42        "surname": {
43          "value": "ULYSSE",
44          "verified": true
45        },
46        "fullname": {
47          "value": "CHRISTOPHE ULYSSE",
48          "verified": true
49        },
50        "dateOfBirth": {
51          "value": "1968-10-18",
52          "verified": true
53        },
54        "gender": {
55          "value": "M",
56          "verified": true
57        },
58        "eyeColor": {
59          "value": "GRAY",
60          "verified": true
61        },
62        "height": {
63          "value": "6' 6",
64          "verified": true
65        }
66      }
67    }
68  ],
69  "addresses": [
70    {
71      "evidenceId": "38e40e32-64a9-4012-a9b9-051918eb79fb",
72      "submitDateTime": "2020-12-08T22:35:23.0464901",
73      "type": "ADDRESS",
74      "evidenceStatus": {
75        "evaluationDateTime": "2020-12-08T22:35:25.1472014",
76        "status": "VERIFIED",
77        "strength": "LEVEL5",
78        "score": "LEVEL3",
79        "isAdjudicable": false
80      },
81      "referenceIds": ["c3d57428-5939-4300-b17d-d8473ab5b9c3"],
82      "addressData": {
83        "streetDetails": {
84          "streetLines": ["12 COTTONWOOD RD", "SUITE 1001"],
85          "verified": true
86        },
87        "postcode": "12345",
88        "city": "EMPIRE",
89        "state": "NV",
90        "country": "USA",
91        "verified": true
92      }
93    }
94  ],
95  "idDocuments": [
96    {
97      "evidenceId": "c3d57428-5939-4300-b17d-d8473ab5b9c3",
98      "submitDateTime": "2020-12-08T22:35:23.0464891",
99      "type": "DRIVING_LICENSE",
100      "evidenceStatus": {
101        "evaluationDateTime": "2020-12-08T22:35:25.1472014",
102        "status": "VERIFIED",
103        "strength": "LEVEL3",
104        "score": "LEVEL3",
105        "isAdjudicable": false,
106        "positiveIndicators": [
107          "GIV_ELIGIBILITY_OK",
108          "ADDRESS_CITY_COMPARE_OK",
109          "EXPIRYDATE_COMPARE_OK",
110          "IDDOCUMENT_TYPE_COMPARE_OK",
111          "ADDRESS_POSTCODE_COMPARE_OK",
112          "MIDDLENAME_COMPARE_OK",
113          "SURNAME_COMPARE_OK",
114          "BIRTHDATE_COMPARE_OK",
115          "ADDRESS_STREET_COMPARE_OK",
116          "FIRSTNAME_FUZZY_COMPARE_OK",
117          "SURNAME_FUZZY_COMPARE_OK",
118          "HEIGHT_COMPARE_OK",
119          "FIRSTNAME_COMPARE_OK",
120          "IDDOCUMENT_NUMBER_COMPARE_OK",
121          "ADDRESS_STATE_COMPARE_OK",
122          "GENDER_COMPARE_OK",
123          "WEIGHT_COMPARE_OK",
124          "EYECOLOR_COMPARE_OK",
125          "NAMESUFFIX_COMPARE_OK",
126          "ISSUINGDATE_COMPARE_OK",
127          "MIDDLENAME_INITIAL_COMPARE_OK",
128          "MIDDLENAME_FUZZY_COMPARE_OK",
129          "BIOMETRIC_QUALITY_CHECK_OK",
130          "MODEL_RECOGNIZED_OK",
131          "HIGH_TEMPLATE_OK",
132          "CB2D_FIELDS_SYNTAX_OK",
133          "DOCUMENT_BARCODE_PARSING_OK",
134          "LOW_TEMPLATE_OK",
135          "VISUAL_SECURITY_OK",
136          "PHOTOCOPY_DETECTION_OK",
137          "PERSONAL_NUMBER_CHECKSUMS_OK",
138          "MODEL_COLOR_MATCHING_OK",
139          "PORTRAIT_OK",
140          "LCD_DETECTION_OK",
141          "ESFX_OK",
142          "OCRX_OK",
143          "SIDES_DATA_CONSISTENCY_OK",
144          "DOC_EXPIRATION_DATE_OK",
145          "BIRTHDATE_VALID_OK",
146          "DOC_ISSUING_COUNTRY_OK",
147          "OCR_ISSUING_DATE_OK",
148          "BLUR_IMAGE_QUALITY_FRONT_OK",
149          "EXPIRATION_DATE_CONSISTENCY_OK",
150          "PAPER_COPY_OK",
151          "OCR_EXPIRATION_DATE_OK",
152          "DOC_NATIONALITY_OK",
153          "ISSUING_DATE_VALIDITY_OK",
154          "GLARE_IMAGE_QUALITY_FRONT_OK",
155          "IMAGE_FRONT_DPI_CHECK_OK",
156          "PHOTO_LOCATION_OK",
157          "OCR_FIRSTNAMES_OK",
158          "OCR_BIRTHDATE_OK",
159          "OCR_DOCNUM_OK",
160          "OCR_SEX_OK",
161          "OCR_FULLNAME_OK"
162        ],
163        "warningIndicators": [
164          "LOW_IMAGE_QUALITY_FRONT_WARNING",
165          "KEYSTONE_IMAGE_QUALITY_FRONT_WARNING",
166          "BLUR_IMAGE_QUALITY_BACK_WARNING",
167          "GLARE_IMAGE_QUALITY_BACK_WARNING"
168        ],
169        "unverifiedIndicators": [
170          "MRZ_CHECKSUMS_UNVERIFIED",
171          "DOCUMENT_NUMBER_VALIDITY_UNVERIFIED",
172          "COMPROMISED_DOCUMENT_CHECK_UNVERIFIED",
173          "TEXTURE_ANALYSIS_UNVERIFIED",
174          "MRZ_BARCODE_CROSSCHECK_UNVERIFIED"
175        ]
176      },
177      "idDocumentData": {
178        "idDocumentType": "DRIVING_LICENSE",
179        "idDocumentNumber": "000000000016",
180        "issuingCountry": "USA",
181        "issuingState": "WA",
182        "issuingDate": "2015-04-01",
183        "expiryDate": "2021-04-01",
184        "personalAttributes": {
185          "givenNames": [
186            {
187              "value": "CHRISTOPHE",
188              "verified": true
189            }
190          ],
191          "surname": {
192            "value": "ULYSSE",
193            "verified": true
194          },
195          "fullname": {
196            "value": "CHRISTOPHE ULYSSE",
197            "verified": true
198          },
199          "dateOfBirth": {
200            "value": "1968-10-18",
201            "verified": true
202          },
203          "gender": {
204            "value": "M",
205            "verified": true
206          },
207          "eyeColor": {
208            "value": "GRAY",
209            "verified": true
210          },
211          "height": {
212            "value": "6' 6",
213            "verified": true
214          }
215        },
216        "address": {
217          "streetDetails": {
218            "streetLines": ["12 COTTONWOOD RD", "SUITE 1001"],
219            "verified": true
220          },
221          "postcode": "12345",
222          "city": "EMPIRE",
223          "state": "NV",
224          "country": "USA",
225          "verified": true
226        }
227      }
228    }
229  ]
230}

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

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

The rest of the answer carries the identity attributes (personal information extracted from documents) as well as various information like the upgrade path to improve LOA.

Step 6: Ending the Process and Retrieving the Proof File 

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

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.

The request looks like this:

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