Prevalidating an identity document enables you to know if it is valid before and independently from a signature transaction.
Identity prevalidation is a two-step process during which data is extracted from the identity document and then matched with the data expected on your side. Both steps must be completed successfully to return a valid identity validation ID (to be used in the transaction).
An identity validation ID provides a guarantee that the electronic certificate associated to the ID will be issued successfully and immediately, within a future signature transaction or a standalone operation.
Note that identity validation is used for level2
(advanced signature), level3
(advanced signature with a qualified certificate) and level4
(qualified signature).
To use an identity validation ID in a transaction:
- Request an identity prevalidation.
- Update the participant within the transaction.
1.Request an identity prevalidation
Prerequisite
Before you send an identity document for prevalidation, you must ensure that it complies with the following prerequisites:
- Format: the identity document must be provided as an image (JPEG or PNG) or a PDF file. Note that only colored imports are accepted for certificate issuance (no black and white scans).
- Passports must be uploaded as a single file in your request. You only need to provide the photo page.
- Identity cards can be uploaded as a single file (front and back sides in the same file) or as two separate files (front side in one file and back side in another file).
- Size: the file must not exceed 4MB (4MB max per side in case you import 2 separate files), as explained in the following examples:
- 4MB for a passport (1 side -> 1 file),
- 4MB for a 2 pages PDF (2 sides on the same file),
- 4MB for each file (1 side per file).
Once you ensured the identity document complies with the prerequistes, you must send it to Universign using a multipart/form-data
request type. To do so, send a request to POST /v1/id-validations
and set the required arguments, as shown in the example below:
curl
https://api.universign.com/v1/id-validations \
-d document=@test_cin_recto.png \
-d document=@test_cin_verso.png \
-d email=john@company.com \
-d full_name="John DOE" \
-d birthdate="2000-04-06"
Note that you can also pass optional arguments:
expires_after
: The date after which the identity document is allowed to be expired. Expected format is YYYY-MM-DD.allow_manual_validation
: Set to true if you want the identity document to be manually prevalidated in case the automatic prevalidation process fails.
Before you request a manual validation, ensure with us that this option is activated on your account.
If prevalidation succeeded
You are returned a 200
response with a prevalidation ID. Please note that the prevalidation ID will expire 7 days after issuance. Also, note that a successful prevalidation may lead to a failed certificate issuance if the identity document expires between the prevalidation date and the certificate issuance date. To avoid such occurrence, you can require an identity document to be valid beyond the current date through the expires_after
parameter.
{
"object": "id-validation",
"id": "idval_JxYxqqrdZOrn",
"status": "success",
"verification": {
"successful_checks": [
"color",
"expires_after",
"name",
"age",
"birth_date"
],
"failed_checks": []
}
}
If prevalidation fails due to an extraction problem
You are returned a 200
response with a prevalidation ID as well as the first reason for failure that was encountered during the extraction process.
{
"object": "id-validation",
"id": "idval_w9Jb930GbwGP",
"status": "extraction_failure",
"verification": {
"extraction_failure_reason": "inconsistent_data",
"extraction_failure_fields": [
"optical_lines"
],
"successful_checks": [],
"failed_checks": []
}
}
In general, to avoid failed extraction occurrences, check that the uploaded document complies with our prerequisites. Possible extraction failure reasons are listed in the table below:
Reason | Definition | Troubleshooting |
---|---|---|
missing_side |
A side of the document is missing. | Make sure you provide all expected sides of the identity document in your request. |
unidentified_side |
A side of the document is not recognized by the system. | The document quality or the image quality may be the cause. Alternatively, check that the document you provided is an accepted type of ID. |
too_many_sides |
You sent too many sides in the request. | Make sure you upload only one identity document per request. |
incompatible_sides |
You sent a document that contains incompatible sides. | To be compatible, two sides must belong to the same document type (French identity card for example) and be a different side (front and back). |
missing_data |
One or more expected fields cannot be extracted. | The document quality or the image quality may be the cause. |
inconsistent_data |
Some of the extracted data is inconsistent. Alternatively, front and back sides are inconsistent with each other. | The document or image quality might be the cause, or you submitted two files belonging to two different identity documents. Alternatively, the document may be fraudulent. |
If the extraction_failure_reason
is inconsistent_data
or missing_data
, extraction_failure_fields
specifies which data led to the ID validation failure. Possible values are:
optical_lines
,family_names
,given_names
,identity_number
,birthdate
,birth_place
,expiry_date
,delivery_date
.
If prevalidation fails because the data extracted does not match the constraints you specified
You are returned a 200
response with a prevalidation ID, as well as a detailed list of failed and successful constraints checks. Please check and update your ID owner’s data accordingly before you send the document for prevalidation again.
{
"object": "id-validation",
"id": "idval_D9y9X913vQBA",
"status": "constraints_failure",
"verification": {
"successful_checks": [
"color",
"expires_after",
"age"
],
"failed_checks": [
"name",
"birth_date"
]
}
}
If automatic prevalidation fails and manual validation is allowed
If you set allow_manual_validation
to true
, and the automatic prevalidation fails, you are returned a 200
response with a pending_manual_validation
status.
{
"object": "id-validation",
"id": "idval_D9y9X913vQBC",
"status": "pending_manual_validation"
}
To be notified when the manual validation is done and get the result, you need to subscribe to the identity-validation.processed
event.
2.Update the participant
Now that you have the identity validation ID, send a request to POST /v1/transactions/{transaction_id}/participants
and pass the participant identity validation id
in the prevalidation_id
argument:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/participants \
-d email=john@company.com \
-d min_signature_level=level2 \
-d prevalidation_id=idval_JxYxqqrdZOrn