Identity Claim Verification

This section provides you with the information to use the IDEMIA Identity and Verification (ID&V) API API for verifying a US citizen’s identity claims containing a Social Security number, phone number, or credit card number.

Requirements

To enable identity claims verification as part of an identity proofing process, you will need the following:

API Keys and URLs to access the identity proofing service
GIPS-RS key for back-end to back-end communication
GIPS-UA key for the user-facing application to the identity proofing back end communication

Before sending the user identity claim to the ID&V service, the client application must notify that it has obtained the consent from the individual whose identity claims are being verified.

For a successful identity claim verification, the user must present the one or more of the following items:

Identity attributes: first name, last name, date of birth
Social Security number (SSN) issued in US
US mailing address
Phone number registered in their name
Credit card number registered in their name

Note: Identity claim verification results are hidden in the API responses. Contact the IDEMIA support team to remove these restrictions.

Scenarios

Below are three different scenarios involving US citizens during identity claims verification:

Scenario	Requirements
Identity claim verification only	Social Security number (SSN) and a phone number
Document authentication and Identity claim verification	Social Security number (SSN) and phone number
Document authentication with selfie check, and identity claim verification	Social Security number (SSN), credit card, and phone number.

Identity claim verification only

Steps overview

Create the identity.
Submit the consent.
Submit the user's identity claim.
Retrievethe identity claim verification and identity proof results.

Steps

Step 1: Create the identity.

Create an identity on the identity proofing server that will receive all of the data and gather the verification results related to this credential.

Step 2: Submit the consent.

Notify the identity proofing service of the different verifications the user has consented to.

Step 3: Submit the user's identity claim.

When submitting an identity claim for verification, the user must provide their identity attributes — first name, last name, and date of birth, a Social Security number issued in the US, a US address — streetLines, postcode, state and country — and a phone number, credit card number, or both registered in the name of the user.

In order to be VERIFIED, the SSN and at least either the phone number or the credit card number must match the records held by the authoritative source.

Step 4: Get the identity status and retrieve proof.

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

The user can submit additional pieces of evidence to increase the level of assurance in the identity. Once the client application has reached the end of the process, it can close the transaction by retrieving the proof file that contains all of the identity verification details.

Document authentication and identity claim verification

Steps Overview

Create the identity.
Submit the consent.
Submit an identity document capture.
Submit the user's identity claims.
Retrieve the proofing results and identity proof.

In the example below, the identity document is a driver's license.

Steps

Step 1: Create the identity.

Create an identity on the identity proofing server that will receive all of the data and gather the verification results related to this identity.

Step 2: Submit the consent.

Notify the identity proofing service of the different verifications the user has consented to.

Step 3: Submit the identity document capture.

The client application sends the identity document images for verification.

ID&V performs the document authentication and extracts the user’s personally identifiable information (PII) and document information.

If the identity document is valid, it status becomes VERIFIED and the identity document is assigned a score depending on the number and quality of verifications that have been performed (for example, LEVEL2).

Step 4: Submit the user's identity claim.

When submitting an identity claim for verification, the user's identity attributes — first name, last name, and date of birth — and the user's address data — streetLines, postcode, state and country — are not mandatory because these attributes are extracted from the identity document, but the SSN is mandatory and must be provided along with a phone number or credit card number or both registered in the name of the user.

In order to be VERIFIED, the SSN and at least either the phone number or the credit card number must match the records held by the authoritative source.

Step 5: Get the identity claim verification results and retrieve the proof.

The client application can retrieve the results of the identity claim verification.

The user can submit additional pieces of evidence to increase the level of assurance of the identity claim presented. Once the client application has reached the end of the process, it can close the transaction by retrieving the proof file that contains all of the identity verification details.

Document authentication + selfie check + identity claim verification

Steps Overview

Create the identity.
Submit the consent.
Submit an identity document capture.
Submit the user's self-portrait image
Submit the user's identity claim.
Retreive the proofing results and identity proof.

In the example below, a driver's license is used as the identity document.

Steps

Step 1: Create the identity.

Create an identity on the identity proofing server that will receive all of the data and gather the verification results related to this identity.

Step 2: Submit the consent.

Notify the identity proofing service of the different verifications the user has consented to.

Step 3: Submit the identity document capture.

The client application sends the identity document images for verification.

ID&V performs the document authentication and extracts the user’s personally identifiable information (PII) and document information;

If the identity document is valid, it status becomes VERIFIED and the identity document is assigned a score depending on the number and quality of verifications that have been performed (for example, LEVEL2).

Step 4: Submit the self-portrait image (selfie).

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

Step 5: Submit the user's identity claim.

In order to be VERIFIED, the SSN and at least either the phone number or the credit card number must match the records held the authoritative source.

Step 6: Get the identity claim verification results and retrieve the proof.

The client application can retrieve the results of the identity claim verification.

The user can submit additional pieces of evidences to increase the level of assurance in the identity claim being presented. Once the client application has reached the end of the process, it can close the transaction by retrieving the proof file that contains all of the identity verification details.

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:

Variable	Meaning
URL_MAIN_PART	The ID&V domain.
APIKEY_VALUE	Client application API key as provided by portal administrator.
IDENTITY_ID	The value obtained after performing step 1 below. This should be the `id` value from the Create Identity response message.

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": "gips-cd46a451-60d2-4c25-a466-7af6518aad0b",
3  "status": "EXPECTING_INPUT",
4  "levelOfAssurance": "LOA0",
5  "creationDateTime": "2020-11-17T21:28:47.991249",
6  "evaluationDateTime": "2020-11-17T21:28:50.3901804",
7  "upgradePaths": {}
8}

Variable	Description
id	The identity identifier that will be used to identify the current transaction in subsequent requests.
status	Status of the transaction
levelOfAssurance (LOA)	The current level of assurance for that identity
creationDateTime	Identity creation date
evaluationDateTime	The date at which the identity was last evaluated
upgradePaths	List of possible submissions that would increase LOA

Consent is a notification from the client application to ID&V that the user consents to their personal information (in this case, their identity attributes) 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 identity attributes verification.

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

Sample response:

JSON
1[
2   {
3      "consentId": "6fb21d2b-d97e-487e-8a96-d4d22af1ad2e",
4      "approved": true,
5      "type": "ID_CLAIM",
6      "validityPeriod": {
7          "from": "2018-01-01",
8          "to": "2022-01-01"
9      }
10   }
11]

Variable	Description
consentId	The consent identifier that might be used to identify the submitted consent.
approved	Boolean indicating status of the consent: `true` or `false`.
type	Type of consent submitted (possible values may be: `PORTRAIT`, `GIV`, `ID_CLAIM`)
validityPeriod	The period for which the consent is considered valid.
to	The date at which the consent will expire and will not be considered valid anymore.

Submit a document capture

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

Passport
Identity card
Driver's license
Resident card

This request can be used in the scenario Document authentication and Selfie check and Identity claim verification (SSN and Credit card + Phone number)

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

Variable	Description
URL_MAIN_PART	The ID&V domain.
APIKEY_VALUE	Client application API key as provided by your Administrator(s).
IDENTITY_ID	Value retrieved after performing Step 1. This should be the `id` value from the Create Identity response message.
ABSOLUTE_LOCAL_PATH_TO_IDDOCUMENT_FRONT	Value of the absolute path to the document front image. For instance: "C:\mydocumentfront.jpg".
ABSOLUTE_LOCAL_PATH_TO_IDDOCUMENT_BACK	Value of the absolute path to the document back image. For instance: "C:\mydocumentback.jpg."
ABSOLUTE_LOCAL_PATH_TO_ DOCUMENTCAPTUREDETAILS	`DocumentCaptureDetails` is used to attach a JSON file containing specific information regarding the document. This is optional, but providing this information can greatly improve the quality of the ID&V response.

DocumentCaptureDetails is a JSON file with the following format:

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

Variable	Description
COUNTRY_CODE	Alpha-3 code from ISO 3166-1 (for example, USA for the United States, DEU for Germany)
DOCUMENT_TYPE	One of the supported document types, accepted values are: `PASSPORT`, `DRIVING_LICENSE`, `RESIDENT_CARD`, `IDENTITY_CARD`, `TAX_CARD`, `VOTER_CARD`)
IMAGE_SOURCE	Information about how the image was captured: `LIVE_CAPTURE_IMAGE` if the identity document image has been taken live with a Document Capture SDK, `LIVE_CAPTURE_VIDEO` if the identity document image was extracted during a video session. `SCAN` if the photo of the identity document is captured with a flat scanner, or `OTHER` for other source.

Sample response:

JSON
1{
2  "status": "PROCESSING",
3  "type": "DRIVING_LICENSE",
4  "id": "4ede416f-57e8-4bb6-9a14-fa8bde84f957"
5}

Variable	Description
id	The document identifier that will be used in all future requests related to this document.
status	Document status
type	The document type.

Check document status

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

This request can be use in the scenario Document authentication and Selfie check and Identity claim verification (SSN and Credit card + Phone number)

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

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

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": "4ede416f-57e8-4bb6-9a14-fa8bde84f957"
5}

Variable	Description
id	Document identifier
status	Document status
type	Document type

Values for status can be:

VERIFIED - document or face has successfully been verified. When VERIFIED, a document or face is scored on a scale of 1 to 4.
- LEVEL1: low confidence
- LEVEL2: medium confidence
- LEVEL3: high confidence
- LEVEL4: very high confidence
INVALID - document or face is considered invalid after the checks performed
NOT_VERIFIED - document or face was processed, but not enough checks were performed to take a decision, most of the time due to bad image quality, or an unsupported document type
PROCESSING - evidence is currently being processed by the service
ADJUDICATION - evidence is currently reviewed by a human expert

Verification of the user's identity claim

With this request, the client application can verify the user's identity claim.

The request looks like this:

Shell
1curl -X POST \
2  https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/claim \
3  -H 'Content-Type: application/json' \
4  -H 'apikey: [APIKEY_VALUE]' \
5  -d '{
6      "attributesData": {
7              "givenNames": [{
8                      "value": "CHRISTOPHE"
9                  }, {
10                      "value": "JEAN"
11                  }
12              ],     
13              "surname": {
14                  "value": "ULYSSE"
15              },
16              "dateOfBirth": {
17                  "value": "1968-10-18"
18              },
19              "personalNumber": {
20                  "value": "666436878",
21                  "issuingCountry": "USA"
22  
23              }
24          },
25      "addressesData": {
26              "streetDetails": {
27                  "streetLines": [
28                      "1 MAIN STREET"
29                  ]
30              },
31              "postcode": "111110000",
32              "city": "ANYTOWN",
33              "state": "MA",
34              "country": "USA"
35      },
36      "contactDetails": {
37          "mobile": {
38               "value": "123456789"
39              }
40      },
41      "creditCardDetails": {
42          "cardNumber": "1654A354C",
43          "cardType": "CREDIT",
44          "expiryDate": "2022-02-18"
45      }
46  }'

Description of JSON fields in the payload:

Variable	Description
attributesData	Contains all identity attributes claimed by the user
givenNames	Contains a list of the user's given names
surname	Contains the surname of the user
dateOfBirth	Contains the date of birth of the user
gender	Contains the gender of the user
nationality	Contains the nationality of the user
personalNumber	Unique number by which the person could be identified within a country.
issuingCountry	Country where the personal number (SSN) is issued. This field is required if the `personalNumber` is provided. The `issuingCountry` contains the ISO 3166-1 alpha-3 code referring of the SSN issuing country
addressesData	Contains all address related data
streetDetails	Contains address details at street level
streetLines	Contains the different lines of the address
houseNumber	House number relative to the street
flatNumber	Flat, apartment, or suite identifier in the building
houseName	House name relative to the street
district	Name of the district of the address
locality	Locality information of the address
postcode	Postcode or ZIP code of the address
city	City name of the address
state	If country is USA the state uses USPS two letter abbreviations. Otherwise, contains the state name in full
county	County name of the address
country	Contains the ISO 3166-1 alpha-3 code referring to the country of the address
fullAddress	Contains full unstructured address if captured as such
contactDetails	Contains contact information associated to that identity
mobile	Mobile phone number that is registered in the name of the user
creditCardDetails	Contains the credit card details in the name of the user
cardNumber	Contains the credit card number
cardType	Contains the model/type of the card (optional)
expiryDate	Contains the card expiry date (optional)

Sample response:

JSON
1{
2  "status": "PROCESSING",
3  "type": "ID_CLAIM",
4  "id": "440d8c98-f1f4-4c05-a3d8-6025faa3b967"
5}

Variable	Description
id	The evidence identifier
status	Evidence status
type	The evidence type

Check the status of the user's identity claim

With this request, the client application can check the processing status of the user's claim identity and see 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]/claim \
3  -H 'Content-Type: application/json' \
4  -H 'apikey: [APIKEY_VALUE]'

Sample response: When claim data are not hidden

JSON
1{
2  "globalStatus": {
3    "id": "gips-cd46a451-60d2-4c25-a466-7af6518aad0b",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA2",
6    "creationDateTime": "2020-11-17T21:28:47.991249",
7    "evaluationDateTime": "2020-11-17T21:38:54.7148765",
8    "nameReferenceEvidenceId": "440d8c98-f1f4-4c05-a3d8-6025faa3b967",
9    "upgradePaths": {},
10    "Claim": {
11      "evidenceId": "440d8c98-f1f4-4c05-a3d8-6025faa3b967",
12      "submitDateTime": "2020-11-17T21:38:51.8796052",
13      "type": "ID_CLAIM",
14      "evidenceStatus": {
15        "evaluationDateTime": "2020-11-17T21:38:54.7148765",
16        "status": "VERIFIED",
17        "strength": "LEVEL3",
18        "score": "LEVEL3",
19        "isAdjudicable": false
20      },
21      "claimData": {
22        "attributesData": {
23          "givenNames": [
24            {
25              "value": "CHRISTOPHE",
26              "verified": true
27            },
28            {
29              "value": "JEAN",
30              "verified": true
31            }
32          ],
33          "surname": {
34            "value": "ULYSSE",
35            "verified": true
36          },
37          "dateOfBirth": {
38            "value": "1968-10-18",
39            "verified": true
40          },
41          "personalNumber": {
42            "value": "666436878",
43            "verified": true,
44            "issuingCountry": "USA"
45          }
46        },
47        "addressesData": {
48          "streetDetails": {
49            "streetLines": [
50              "1 MAIN STREET"
51            ],
52            "verified": true
53          },
54          "postcode": "111110000",
55          "city": "ANYTOWN",
56          "state": "MA",
57          "country": "USA",
58          "verified": true
59        },
60        "contactDetails": {
61          "mobile": {
62            "value": "123456789",
63            "verified": true
64          }
65        },
66        "creditCardDetails": {
67          "verified": true
68        }
69      }
70    }
71  }
72}

Sample response

config

JSON
1{
2  "globalStatus": {
3    "id": "gips-cd46a451-60d2-4c25-a466-7af6518aad0b",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA2",
6    "creationDateTime": "2020-11-17T21:28:47.991249",
7    "evaluationDateTime": "2020-11-17T21:38:54.7148765",
8    "nameReferenceEvidenceId": "440d8c98-f1f4-4c05-a3d8-6025faa3b967",
9    "upgradePaths": {},
10    "Claim": {
11      "evidenceId": "440d8c98-f1f4-4c05-a3d8-6025faa3b967",
12      "submitDateTime": "2020-11-17T21:38:51.8796052",
13      "type": "ID_CLAIM"
14    }
15  }
16}

Values for status can be:

VERIFIED - evidence has successfully been verified. When VERIFIED, Identity claim is scored on LEVEL 3.
INVALID - evidence is considered invalid after the checks performed.
NOT_VERIFIED - evidence was processed, but not enough checks were performed to take a decision.
PROCESSING - evidence is currently being processed by the service.

Check the status of the identity

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

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: when claim data is not hidden

JSON
1{
2  "globalStatus": {
3    "id": "gips-cd46a451-60d2-4c25-a466-7af6518aad0b",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA2",
6    "creationDateTime": "2020-11-17T21:28:47.991249",
7    "evaluationDateTime": "2020-11-17T21:38:54.7148765",
8    "nameReferenceEvidenceId": "440d8c98-f1f4-4c05-a3d8-6025faa3b967",
9    "upgradePaths": {},
10    "consents": [
11      {
12        "consentId": "f651fa39-6d33-4500-946e-a68a03e07002",
13        "approved": true,
14        "type": "PORTRAIT",
15        "validityPeriod": {
16          "from": "2018-01-01",
17          "to": "2021-05-17"
18        }
19      },
20      {
21        "consentId": "cd5b68e5-baf2-4a35-9197-0662f9953f18",
22        "approved": true,
23        "type": "GIV",
24        "validityPeriod": {
25          "from": "2018-01-01",
26          "to": "2022-01-01"
27        }
28      },
29      {
30        "consentId": "6fb21d2b-d97e-487e-8a96-d4d22af1ad2e",
31        "approved": true,
32        "type": "ID_CLAIM",
33        "validityPeriod": {
34          "from": "2018-01-01",
35          "to": "2022-01-01"
36        }
37      }
38    ],
39    "attributes": [
40      {
41        "evidenceId": "05890881-d2c1-434f-b7b9-4f887d67f9b8",
42        "submitDateTime": "2020-11-17T21:38:54.6999172",
43        "type": "ATTRIBUTES",
44        "evidenceStatus": {
45          "evaluationDateTime": "2020-11-17T21:38:54.7148765",
46          "status": "VERIFIED",
47          "strength": "LEVEL5",
48          "score": "LEVEL3",
49          "isAdjudicable": false
50        },
51        "attributesData": {
52          "givenNames": [
53            {
54              "value": "CHRISTOPHE",
55              "verified": true
56            },
57            {
58              "value": "JEAN",
59              "verified": true
60            }
61          ],
62          "surname": {
63            "value": "ULYSSE",
64            "verified": true
65          },
66          "dateOfBirth": {
67            "value": "1968-10-18",
68            "verified": true
69          },
70          "gender": {
71            "value": "M",
72            "verified": true
73          },
74          "eyeColor": {
75            "value": "GRAY",
76            "verified": true
77          },
78          "height": {
79            "value": "6' 6",
80            "verified": true
81          },
82          "personalNumber": {
83            "value": "666436878",
84            "verified": true,
85            "issuingCountry": "USA"
86          }
87        }
88      }
89    ],
90    "contactDetails": {
91      "mobile": {
92        "value": "123456789",
93        "verified": true
94      }
95    },
96    "addresses": [
97      {
98        "evidenceId": "40bc0d6d-2af2-4d81-8f3b-6e1974f5113f",
99        "submitDateTime": "2020-11-17T21:29:33.4046754",
100        "type": "ADDRESS",
101        "evidenceStatus": {
102          "evaluationDateTime": "2020-11-17T21:38:54.7148765",
103          "status": "VERIFIED",
104          "strength": "LEVEL5",
105          "score": "LEVEL2",
106          "isAdjudicable": false
107        },
108        "referenceIds": [
109          "4ede416f-57e8-4bb6-9a14-fa8bde84f957"
110        ],
111        "addressData": {
112          "streetDetails": {
113            "streetLines": [
114              "12 COTTONWOOD RD",
115              "SUITE 1001"
116            ],
117            "verified": true
118          },
119          "postcode": "12345",
120          "city": "EMPIRE",
121          "state": "NV",
122          "country": "USA",
123          "verified": true
124        }
125      },
126      {
127        "evidenceId": "8603a99f-f97d-408c-a353-3e5303bc752a",
128        "submitDateTime": "2020-11-17T21:38:51.8796062",
129        "type": "ADDRESS",
130        "evidenceStatus": {
131          "evaluationDateTime": "2020-11-17T21:38:54.7148765",
132          "status": "VERIFIED",
133          "strength": "LEVEL5",
134          "score": "LEVEL3",
135          "isAdjudicable": false
136        },
137        "referenceIds": [
138          "440d8c98-f1f4-4c05-a3d8-6025faa3b967"
139        ],
140        "addressData": {
141          "streetDetails": {
142            "streetLines": [
143              "1 MAIN STREET"
144            ],
145            "verified": true
146          },
147          "postcode": "111110000",
148          "city": "ANYTOWN",
149          "state": "MA",
150          "country": "USA",
151          "verified": true
152        }
153      }
154    ],
155    "idDocuments": [
156      {
157        "evidenceId": "4ede416f-57e8-4bb6-9a14-fa8bde84f957",
158        "submitDateTime": "2020-11-17T21:29:33.4046744",
159        "type": "DRIVING_LICENSE",
160        "evidenceStatus": {
161          "evaluationDateTime": "2020-11-17T21:38:54.7148765",
162          "status": "VERIFIED",
163          "strength": "LEVEL3",
164          "score": "LEVEL2",
165          "isAdjudicable": false,
166          "positiveIndicators": [
167            "DOC_EXPIRATION_DATE_OK",
168            "MODEL_RECOGNIZED_OK",
169            "VISUAL_SECURITY_OK",
170            "DOC_ISSUING_COUNTRY_OK",
171            "DOC_NATIONALITY_OK",
172            "GLARE_IMAGE_QUALITY_FRONT_OK",
173            "OCR_SEX_OK",
174            "IMAGE_FRONT_DPI_CHECK_OK",
175            "PHOTO_LOCATION_OK",
176            "ISSUING_DATE_VALIDITY_OK",
177            "BIRTHDATE_VALID_OK",
178            "OCRX_OK",
179            "DOCUMENT_BARCODE_PARSING_OK",
180            "OCR_DOCNUM_OK",
181            "OCR_BIRTHDATE_OK",
182            "OCR_FIRSTNAMES_OK",
183            "OCR_EXPIRATION_DATE_OK",
184            "PAPER_COPY_OK",
185            "EXPIRATION_DATE_CONSISTENCY_OK",
186            "BLUR_IMAGE_QUALITY_FRONT_OK",
187            "OCR_FULLNAME_OK",
188            "OCR_ISSUING_DATE_OK",
189            "MODEL_COLOR_MATCHING_OK",
190            "HIGH_TEMPLATE_OK",
191            "CB2D_FIELDS_SYNTAX_OK",
192            "LOW_TEMPLATE_OK",
193            "PHOTOCOPY_DETECTION_OK",
194            "PERSONAL_NUMBER_CHECKSUMS_OK",
195            "PORTRAIT_OK",
196            "LCD_DETECTION_OK",
197            "ESFX_OK",
198            "SIDES_DATA_CONSISTENCY_OK"
199          ],
200          "warningIndicators": [
201            "LOW_IMAGE_QUALITY_FRONT_WARNING",
202            "KEYSTONE_IMAGE_QUALITY_FRONT_WARNING",
203            "BLUR_IMAGE_QUALITY_BACK_WARNING",
204            "GLARE_IMAGE_QUALITY_BACK_WARNING"
205          ],
206          "unverifiedIndicators": [
207            "MRZ_CHECKSUMS_UNVERIFIED",
208            "DOCUMENT_NUMBER_VALIDITY_UNVERIFIED",
209            "COMPROMISED_DOCUMENT_CHECK_UNVERIFIED",
210            "TEXTURE_ANALYSIS_UNVERIFIED",
211            "MRZ_BARCODE_CROSSCHECK_UNVERIFIED"
212          ]
213        },
214        "idDocumentData": {
215          "idDocumentType": "DRIVING_LICENSE",
216          "idDocumentNumber": "000000000016",
217          "issuingCountry": "USA",
218          "issuingState": "WA",
219          "issuingDate": "2015-04-01",
220          "expiryDate": "2021-04-01",
221          "personalAttributes": {
222            "givenNames": [
223              {
224                "value": "CHRISTOPHE",
225                "verified": true
226              },
227              {
228                "value": "JEAN",
229                "verified": true
230              }
231            ],
232            "surname": {
233              "value": "ULYSSE",
234              "verified": true
235            },
236            "dateOfBirth": {
237              "value": "1968-10-18",
238              "verified": true
239            },
240            "gender": {
241              "value": "M",
242              "verified": true
243            },
244            "eyeColor": {
245              "value": "GRAY",
246              "verified": true
247            },
248            "height": {
249              "value": "6' 6",
250              "verified": true
251            }
252          },
253          "address": {
254            "streetDetails": {
255              "streetLines": [
256                "12 COTTONWOOD RD",
257                "SUITE 1001"
258              ],
259              "verified": true
260            },
261            "postcode": "12345",
262            "city": "EMPIRE",
263            "state": "NV",
264            "country": "USA",
265            "verified": true
266          }
267        }
268      }
269    ],
270    "Claim": {
271      "evidenceId": "440d8c98-f1f4-4c05-a3d8-6025faa3b967",
272      "submitDateTime": "2020-11-17T21:38:51.8796052",
273      "type": "ID_CLAIM",
274      "evidenceStatus": {
275        "evaluationDateTime": "2020-11-17T21:38:54.7148765",
276        "status": "VERIFIED",
277        "strength": "LEVEL3",
278        "score": "LEVEL3",
279        "isAdjudicable": false,
280        "positiveIndicators": [
281          "CLAIM_VERIFICATION_OK"
282        ]
283      },
284      "claimData": {
285        "attributesData": {
286          "givenNames": [
287            {
288              "value": "CHRISTOPHE",
289              "verified": true
290            },
291            {
292              "value": "JEAN",
293              "verified": true
294            }
295          ],
296          "surname": {
297            "value": "ULYSSE",
298            "verified": true
299          },
300          "dateOfBirth": {
301            "value": "1968-10-18",
302            "verified": true
303          },
304          "gender": {
305            "value": "M",
306            "verified": true
307          },
308          "eyeColor": {
309            "value": "GRAY",
310            "verified": true
311          },
312          "height": {
313            "value": "6' 6",
314            "verified": true
315          },
316          "personalNumber": {
317            "value": "666436878",
318            "verified": true,
319            "issuingCountry": "USA"
320          }
321        },
322        "addressesData": {
323          "streetDetails": {
324            "streetLines": [
325              "1 MAIN STREET"
326            ],
327            "verified": true
328          },
329          "postcode": "111110000",
330          "city": "ANYTOWN",
331          "state": "MA",
332          "country": "USA",
333          "verified": true
334        },
335        "contactDetails": {
336          "mobile": {
337            "value": "123456789",
338            "verified": true
339          }
340        },
341        "creditCardDetails": {
342          "verified": true
343        }
344      }
345    }
346  }
347}

Sample response: default configuration (Claim data his hidden)

JSON
1{
2  "globalStatus": {
3    "id": "gips-cd46a451-60d2-4c25-a466-7af6518aad0b",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA2",
6    "creationDateTime": "2020-11-17T21:28:47.991249",
7    "evaluationDateTime": "2020-11-17T21:38:54.7148765",
8    "nameReferenceEvidenceId": "440d8c98-f1f4-4c05-a3d8-6025faa3b967",
9    "upgradePaths": {}
10  },
11  "consents": [
12    {
13      "consentId": "f651fa39-6d33-4500-946e-a68a03e07002",
14      "approved": true,
15      "type": "PORTRAIT",
16      "validityPeriod": {
17        "from": "2018-01-01",
18        "to": "2021-05-17"
19      }
20    },
21    {
22      "consentId": "cd5b68e5-baf2-4a35-9197-0662f9953f18",
23      "approved": true,
24      "type": "GIV",
25      "validityPeriod": {
26        "from": "2018-01-01",
27        "to": "2022-01-01"
28      }
29    },
30    {
31      "consentId": "6fb21d2b-d97e-487e-8a96-d4d22af1ad2e",
32      "approved": true,
33      "type": "ID_CLAIM",
34      "validityPeriod": {
35        "from": "2018-01-01",
36        "to": "2022-01-01"
37      }
38    }
39  ],
40  "attributes": [
41    {
42      "evidenceId": "05890881-d2c1-434f-b7b9-4f887d67f9b8",
43      "submitDateTime": "2020-11-17T21:38:54.6999172",
44      "type": "ATTRIBUTES",
45      "evidenceStatus": {
46        "evaluationDateTime": "2020-11-17T21:38:54.7148765",
47        "status": "VERIFIED",
48        "strength": "LEVEL5",
49        "score": "LEVEL3",
50        "isAdjudicable": false
51      },
52      "attributesData": {}
53    }
54  ],
55  "addresses": [
56    {
57      "evidenceId": "40bc0d6d-2af2-4d81-8f3b-6e1974f5113f",
58      "submitDateTime": "2020-11-17T21:29:33.4046754",
59      "type": "ADDRESS",
60      "evidenceStatus": {
61        "evaluationDateTime": "2020-11-17T21:38:54.7148765",
62        "status": "VERIFIED",
63        "strength": "LEVEL5",
64        "score": "LEVEL2",
65        "isAdjudicable": false
66      },
67      "referenceIds": [
68        "4ede416f-57e8-4bb6-9a14-fa8bde84f957"
69      ],
70      "addressData": {
71        "streetDetails": {
72          "streetLines": [
73            "12 COTTONWOOD RD",
74            "SUITE 1001"
75          ],
76          "verified": true
77        },
78        "postcode": "12345",
79        "city": "EMPIRE",
80        "state": "NV",
81        "country": "USA",
82        "verified": true
83      }
84    },
85    {
86      "evidenceId": "8603a99f-f97d-408c-a353-3e5303bc752a",
87      "submitDateTime": "2020-11-17T21:38:51.8796062",
88      "type": "ADDRESS",
89      "evidenceStatus": {
90        "evaluationDateTime": "2020-11-17T21:38:54.7148765",
91        "status": "VERIFIED",
92        "strength": "LEVEL5",
93        "score": "LEVEL3",
94        "isAdjudicable": false
95      },
96      "referenceIds": [
97        "440d8c98-f1f4-4c05-a3d8-6025faa3b967"
98      ]
99    }
100  ],
101  "idDocuments": [
102    {
103      "evidenceId": "4ede416f-57e8-4bb6-9a14-fa8bde84f957",
104      "submitDateTime": "2020-11-17T21:29:33.4046744",
105      "type": "DRIVING_LICENSE",
106      "evidenceStatus": {
107        "evaluationDateTime": "2020-11-17T21:38:54.7148765",
108        "status": "VERIFIED",
109        "strength": "LEVEL3",
110        "score": "LEVEL2",
111        "isAdjudicable": false,
112        "positiveIndicators": [
113          "DOC_EXPIRATION_DATE_OK",
114          "MODEL_RECOGNIZED_OK",
115          "VISUAL_SECURITY_OK",
116          "DOC_ISSUING_COUNTRY_OK",
117          "DOC_NATIONALITY_OK",
118          "GLARE_IMAGE_QUALITY_FRONT_OK",
119          "OCR_SEX_OK",
120          "IMAGE_FRONT_DPI_CHECK_OK",
121          "PHOTO_LOCATION_OK",
122          "ISSUING_DATE_VALIDITY_OK",
123          "BIRTHDATE_VALID_OK",
124          "OCRX_OK",
125          "DOCUMENT_BARCODE_PARSING_OK",
126          "OCR_DOCNUM_OK",
127          "OCR_BIRTHDATE_OK",
128          "OCR_FIRSTNAMES_OK",
129          "OCR_EXPIRATION_DATE_OK",
130          "PAPER_COPY_OK",
131          "EXPIRATION_DATE_CONSISTENCY_OK",
132          "BLUR_IMAGE_QUALITY_FRONT_OK",
133          "OCR_FULLNAME_OK",
134          "OCR_ISSUING_DATE_OK",
135          "MODEL_COLOR_MATCHING_OK",
136          "HIGH_TEMPLATE_OK",
137          "CB2D_FIELDS_SYNTAX_OK",
138          "LOW_TEMPLATE_OK",
139          "PHOTOCOPY_DETECTION_OK",
140          "PERSONAL_NUMBER_CHECKSUMS_OK",
141          "PORTRAIT_OK",
142          "LCD_DETECTION_OK",
143          "ESFX_OK",
144          "SIDES_DATA_CONSISTENCY_OK"
145        ],
146        "warningIndicators": [
147          "LOW_IMAGE_QUALITY_FRONT_WARNING",
148          "KEYSTONE_IMAGE_QUALITY_FRONT_WARNING",
149          "BLUR_IMAGE_QUALITY_BACK_WARNING",
150          "GLARE_IMAGE_QUALITY_BACK_WARNING"
151        ],
152        "unverifiedIndicators": [
153          "MRZ_CHECKSUMS_UNVERIFIED",
154          "DOCUMENT_NUMBER_VALIDITY_UNVERIFIED",
155          "COMPROMISED_DOCUMENT_CHECK_UNVERIFIED",
156          "TEXTURE_ANALYSIS_UNVERIFIED",
157          "MRZ_BARCODE_CROSSCHECK_UNVERIFIED"
158        ]
159      },
160      "idDocumentData": {
161        "idDocumentType": "DRIVING_LICENSE",
162        "idDocumentNumber": "000000000016",
163        "issuingCountry": "USA",
164        "issuingState": "WA",
165        "issuingDate": "2015-04-01",
166        "expiryDate": "2021-04-01",
167        "personalAttributes": {
168          "givenNames": [
169            {
170              "value": "CHRISTOPHE",
171              "verified": true
172            },
173            {
174              "value": "JEAN",
175              "verified": true
176            }
177          ],
178          "surname": {
179            "value": "ULYSSE",
180            "verified": true
181          },
182          "dateOfBirth": {
183            "value": "1968-10-18",
184            "verified": true
185          },
186          "gender": {
187            "value": "M",
188            "verified": true
189          },
190          "eyeColor": {
191            "value": "GRAY",
192            "verified": true
193          },
194          "height": {
195            "value": "6' 6",
196            "verified": true
197          }
198        },
199        "address": {
200          "streetDetails": {
201            "streetLines": [
202              "12 COTTONWOOD RD",
203              "SUITE 1001"
204            ],
205            "verified": true
206          },
207          "postcode": "12345",
208          "city": "EMPIRE",
209          "state": "NV",
210          "country": "USA",
211          "verified": true
212        }
213      }
214    }
215  ],
216  "Claim": {
217    "evidenceId": "440d8c98-f1f4-4c05-a3d8-6025faa3b967",
218    "submitDateTime": "2020-11-17T21:38:51.8796052",
219    "type": "ID_CLAIM"
220  }
221}

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 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 \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/proof \
3-H 'apikey: [APIKEY_VALUE]' -o proof

	Description
URL_MAIN_PART	The service domain.
APIKEY_VALUE	Client application API key as provided by your administrator(s).
IDENTITY_ID	Value obtained after performing Step 1. This value should be the `id` value from the Create Identity response message.

API feedback

This section contains error codes and indicators raised when verifying the user's identity claim.

Error codes

Error codes in relation to the user's identity claim:

Error Code	Description
1052	The claim verification service has failed.
1139	Invalid card number (less than 7 digits).
1507	The document owner age is not authorized.

Indicators

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

Indicator name	Description
ADDRESS_CONSISTENCY_CHECK	Checks to see if addresses associated with this identity are consistent with the identity claim.
CLAIM_VERIFICATION	Checks the user's identity claim.
NAME_CONSISTENCY_CHECK	Checks if the names associated with this identity are consistent with the identity claim
ATTRIBUTES_SSN_VALIDITY	Checks to see if the SSN is valid.
HOLDER_AGE	Checks the user's age against the configured age limit.
DATE_OF_BIRTH_VALIDITY	Checks birth date validity.

Scoring

Once a user's identity claim has been submitted, results of the checks are combined by the identity proofing service to increase the level of assurance in the presented credential.

The table summarizes identity claim scoring.

Evidence Type	Status	Score	Description
ID_CLAIM	NOT_VERIFIED	LEVEL0	The evidence was processed, but not enough checks were performed to make a decision.
	INVALID	LEVEL0	The evidence is considered invalid after the checks have been performed.
	VERIFIED	LEVEL3	At least two pieces of evidences (SSN + Phone, or SSN + Credit Card) have successfully been verified.

Identity Claim Verification

Requirements

Scenarios

Identity claim verification only

Document authentication and identity claim verification

Document authentication + selfie check + identity claim verification

Web service calls

Create an identity

Submit consent

Submit a document capture

Check document status

Verification of the user's identity claim

Check the status of the user's identity claim

Check the status of the identity

Ending the process and retrieving the proof file

API feedback

Error codes

Indicators

Scoring