Identity prevalidation

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 signatures and above.

To use an identity validation ID in a transaction:

1. Request an identity prevalidation
2. 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:

• Size: the file must not exceed 20MB.
• Format: the identity document must be provided as an image (JPEG, PNG and GIF) or a PDF file.
• 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).

Note that we currently support only European IDs and passports.

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 document_type="id_card:fra" \
-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 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 holer’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

---

Retrieve requester attestation

← Previous

Retrieve certificate matching

Next →