Validation Flow

Validation Process Service Modes

The system allows to choose between three modes of operation called service modes.

The client (or the calling application) can choose which service mode to use per request by including the parameter "serviceMode" with values "ocr" or "validation". If this parameter isn’t present, the "validation" service mode will be used for that ID document.

• The "ocr" mode is meant to be used in applications that only require to read and extract the information contained in the ID document (OCR and NFC). This service mode requires to upload an image of the document’s obverse and also allows to upload an image of the reverse (except the passport, that only accepts an obverse image) which is optional and in case of being sent, strengthens the OCR process. This mode could be used when the photos of the ID document are taken using Veridas Document Capture SDKs (iOS, Android or HTML). In addition, this mode could be used with photos not taken by Veridas Document Capture SDKs.
• The "validation" mode extracts the OCR of the ID document and analyzes the security measures present in the ID document. This mode could be used when the photos of the ID document are taken using Veridas Document Capture SDKs (iOS, Android or HTML). In addition, this mode could be used with photos not taken by Veridas Document Capture SDKs.

Note

Each one of these service modes has specific usage and billing conditions which can be requested to Veridas

Service mode	"ocr"	"validation"
SDK iOS Document Capture	X	X
SDK Android Document Capture	X	X
SDK HTML Document Capture	X	X
Without Veridas SDK	X (under certain conditions)	X (under certain conditions)

Validation Process Init

The onboarding process flow performed by vali-Das can be initiated in two possible ways:

1) Initializing the validation object by doing a POST /validation call and then uploading each document image using PUT /document endpoint, or

2) Initializing the validation object and uploading one or more document images by using a single POST /validation/document call (introduced in release 2020Q3)

Validations may exist for a given period of time and then deleted to avoid having a huge amount of database records and/or images stored on disk. The client will get a 404 error when trying to access a non-existent validation.

Validation initialization

This is done by sending a POST /validation request and the result is the creation of a new validation object by vali-Das returning to the user its Id.

Once the Id has been returned, the validation process can be continued by following the section "Single Document Image Validation".

Note

It is highly recommended to make this request once (and not before) the document obverse image was captured and is ready to be sent to vali-Das, that is, the PUT document should be sent right after the POST validation. Otherwise, if there was any issue after the POST validation, and therefore the PUT document never took place, it would result in empty validations that could have an impact on performance.

Validation initialization + document images upload

This is the recommended way of initiating a validation process. By doing this way, the first request to vali-Das is a POST /validation/document. It is mandatory to send the document obverse photo alongside this request, while the document reverse photo is optional. This request initializes the validation object and analyzes the provided images, returning the validation Id to the user in case that the analysis process goes well and an error otherwise.

In this request, the user has to specify the document’s type or work with the IDentidas classification engine, as detailed in section "Document obverse upload". Also it is possible to activate or deactivate some score modifiers that act on the document global score modifying it, as detailed in section "Common Document analysis Step Information".

If all the document images (obverse and reverse) are uploaded, the order of the vali-Das processing is: obverse and reverse. If one of the image analysis processes is not successfully done, the rest of the images are not analyzed and an error is returned.

If not all the document images are uploaded alongside this request, the rest of the images shall be uploaded as it is indicated in the section "Single Document Image Validation". However, if all the images have been uploaded, the validation process can be continued by following the section "NFC data upload" or "Face Biometry analysis", depending if NFC data upload is wanted or not.

For more detailed information regarding the document images analysis step, please refer to sections "Started with Document Images upload" and "Document obverse upload" and "Common Document analysis Step Information".

Document Image Validation

As explained above, the validation process can be started by two different ways, just initializing the validation object and also uploading one or more document images. The current step also differs depending on the starting way. vali-Das also offers validation with multiple documents. For more detailed information regarding the multiple onboarding, click here.

Started with Validation Initialization

After initiating the validation, the client shall upload the document’s obverse image by doing a PUT /validation/{id}/document request by setting the analysisType to obverse. The reverse is not mandatory to satisfactorily finalize the validation.

Started with Document Images upload

If the POST /validation/document request was used to initiate the validation process and not all the wanted document images were uploaded to vali-Das, the rest of the images shall be uploaded by using this PUT /validation/{id}/document request.

Common Document analysis Step Information

The ID document validation process requires at least to process a photo of the obverse of the document to be finalised by doing the confirmation step. However, most document types require an image of the reverse to complete the analysis. These images can be uploaded after the initial request by using this same endpoint and the required parameter configuration allowing to strengthen the document security analysis process and also to improve the extracted OCR data.

scoresConfiguration

In addition, it is possible to activate or deactivate some score modifiers that act on the document global score modifying it, by sending their names in the PUT /document request (section "API: Put document"). The documents that allow this configuration and its corresponding modifiers are listed in section "Resources: Documents and modifiers list to send in scores Configuration".

This parameter is a json which allows to configure:

• The minimum age (years)
• The days after the document expiration date allowed to take the document as valid
• The status of some modifiers (See section "Resources: Documents and modifiers list to send in scores Configuration".for the list of modifiers available for each document type)

In the case of the minimum age (years) or The days after the document expiration date allowed to take the document as valid.

{
    "minimumAcceptableAge": 16,
    "maximumAcceptableTimeSinceExpiration": 30
}

vali-Das API supports sending just one of these parameters related to age and time elapsed, or sending both of them together. If no configuration is sent, the default one is applied, which corresponds to:

• The age of majority of the document country, which usually is 18 (years) for minimumAcceptableAge. The valid range is [0, 100].
• 1 (days) for maximumAcceptableTimeSinceExpiration. The valid range is [1, 36500].

For each one of the two fields passed to the POST /document, "minimumAcceptableAge" and "maximumTimeElapsedSinceExpiration", a new score is created. The names for these scores are ScoreVal-PD_AcceptableAge-Value and ScoreVal-DD_AcceptableExpirationDate-Value respectively.

To change the status of some modifiers, the field "modifiers" needs to be included in the scoresConfiguration json. I.e.:

{
    "minimumAcceptableAge": 16,
    "modifiers":{
        "Default": 0,
        "ScoreGroup-PrintAttackTest": 1,
        "ScoreGroup-ReplayAttackTest": 1,
        "ScoreGroup-PhotoAuthenticity": 1
    }
}

As shown in the above example, the field "modifiers" contains the name of the score modifiers with a value "1" or "0". Value "1" means that the modifier will be applied and "0" means that the modifier will not be applied. In this example, only a modifier for "ScoreGroup-MaterialAuthenticity" will be applied.

A global variable named "Default" can be sent with value "1" or "0". If "Default" = "1", all the modifiers will be applied except those modifiers sent after the "Default" variable with value "0" that will not be applied. If variable "Default" = "0", no modifier will be applied except those modifiers sent after the "Default" variable with value "1" that will be applied.

The accuracy of the analysis process also depends on the quality of the images sent to vali-Das, which requires to comply with minimum requirements to work properly. This compliance as well as other advantages can be obtained by using the SDK provided by Veridas.

A document analysis request which has returned a 4XY or 2XY HTTP status code, can be done again if desired. Just in case of receiving a 5XY HTTP status code, the process must be started again from the POST /validation. In the particular case of a retry for the obverse document image analysis, even the request body parameters like the serviceMode can be changed. Also note that if the same image is re-uploaded, the same results are get, so the system is deterministic.

The analysis of the I.D. document obverse image is the minimum step required for vali-Das to do the confirmation step.

NFC data upload

Optionally, and just by using documents like the ES_IDCard_2015 and XX_Passport_YYYY, which include an NFC chip, and also using an Android NFC-compatible device, the ID document information contained in that chip can be uploaded by using the PUT /validation/{id}/nfc endpoint. The proper way for obtaining and sending this NFC data to vali-Das is by using the SDK provided by Veridas.

When vali-Das receives the NFC data, it is merged with the information extracted using OCR techniques, and is also prioritized over the OCR data.

Face Biometry analysis

Once the document analysis is done, the face biometry validation processes can be started.

The biometry analysis is an optional step and comprises two processes, selfie photo verification and selfie video verification. Both of them can be done isolated (just the selfie photo analysis or just the video selfie analysis) or together, by sending the selfie photo and after that the video selfie, which generates additional similarity values.

In the selfie photo biometry analysis, vali-Das does many analysis processes. The main one compares the selfie photo that the user has taken at the moment, with the face photo printed in the I.D. document, or with the one retrieved from the NFC chip (if this has been previously sent).

This process requires the user to take a selfie photo with good enough quality and to send it to vali-Das by using the PUT /validation/{id}/selfie endpoint. This photo capture can be properly done with the SDK provided by Veridas.

If the selfie anti-spoofing feature is available, another verification can be ordered to be done, corresponding to the selfie photo spoofing detection. To do this, the antispoofing parameter has to be sent, indicating that this type of analysis is desired.

Note

This feature -selfie antispoofing- is disabled by default and has specific billing conditions,so it has to be enabled by Veridas upon explicit request from the customer

Alongside the selfie image, a photo of the user smiling can also be uploaded, initiating an analysis process called "alive selfie analysis". This provides the proof of life functionality without the necessity of sending a selfie video.

Note

This feature -selfie alive- is disabled by default and has specific billing conditions, so it has to be enabled by Veridas upon explicit request from the customer

The other step of the face biometry analysis process requires the user to record a video selfie -unless the selfie alive image has been already provided-. Then, vali-Das performs a series of biometric checks and analyses. These analyses depend whether the user has previously uploaded a selfie photo or not.

If this selfie photo has been uploaded, a comparison between the person on the selfie and the one on the video which verifies that both are the same.

If the selfie photo has not been uploaded, some frames are automatically selected by the cloud engine for face processing and the corresponding comparisons are performed.

Finally, a video proof of life analysis is done, generating another score.

Using Veridas SDKs is highly recommended to achieve optimum performance and accurate results when performing biometry analysis.

Face biometry process with Selfie Alive Pro

This use-case is based on a challenge-response design. vali-Das will generate a challenge that should be reproduced using VERIDAS SDKs. Then, the captured evidences will be sent to vali-Das for its final analysis.

Selfie-Alive Pro functionality is a form of face liveness detection implemented following a challenge-response schema.

• In a first stage, the client must operate a request POST /validation/{id}/challenges/generation to generate a new challenge token. The response of this request is a JWS string with application/jose mime type.
• In a second stage, the client needs to record an interaction with a user face, following the indications of the challenge. This second stage is implemented completely by Veridas SDKs.
• In a third stage, the client must request POST /validation/{id}/challenges/video-photo with all the evidences returned by the SDK (among them, a video recording of the face).

The system will reply with a confidence metric in range [0.0, 1.0] in the ValidasScoreLifeProof score, calibrated as indicated in the curve of Selfie-Alive Pro in the "Face Biometry Performance Report" section "selfie vs ID Document" (das-Face)

Notice that Selfie-Alive Pro is optional and may require a specific agreement.

Data retrieval

Once all the required I.D. document images, and optionally the face biometry images, have been uploaded and analysed correctly, the vali-Das user can proceed to retrieve the extracted I.D. document OCR data and the validation scores, which contains the information about the I.D. document and biometric verification. This can be accomplished by sending a GET /validation/{id}/ocr and GET /validation/{id}/scores requests.

The user can also retrieve the image cuts obtained from the I.D. document images, by using the dedicated endpoints (GET /validation/{id}/document/image/{image_type}). These cuts include -but are not limited to- the face of the person contained in the I.D. document, the signature or the person contained in the I.D. document, and the I.D. document images itself among others, depending on the document type and the chosen analysis process.

At any point of the validation, the entire validation data up to that moment may be retrieved by doing a GET /validation/{id} request.

The "environment" section will be generated and provided by vali-Das for each one of the uploaded images. This new section will contain Veridas sdk version metadata of the uploaded images in the onboarding process. This feature requires using SDKs release 2020Q4 or newer, otherwise, the section will not be shown.

The following information will be displayed:

• user-agent: custom fields with the string sent by the browser in the User-Agent header.
• class: information about the platform: web-desktop, web-mobile, native-ios or native-android.
• platform: Android/iOS.

• sdk_information: list with names and versions of the sdk. The possible values of the name field are:

  • sdk-document-capture: SDK of documental capture.
  • sdk-photo-selfie-capture: SDK of photo selfie capture.
  • sdk-selfie-alive-capture: SDK of selfie alive capture.
  • sdk-video-selfie-capture: SDK of video selfie capture.
  • sdk-nfc: SDK of NFC data capture.

If the fields from different images do not match, the field value will be inconclusive.

If the fields from different images do not exist, the field value will be undefined.

Additional validation information and contextual data

vali-Das offers an optional step for the validation process in which the user can upload additional information such as the client application OS and geolocation data that will be saved within the validation.

There are no restrictions about the kind of data which can be sent and saved with the rest of the validation data. It is just needed to comply the key-value contract. So, this can be chosen by each user and customer depending on its usefulness for its business needs and use cases.

By default, Veridas SaaS platform never stores logs of any the data sent as contextual data. However, some customers have found useful that Veridas logs some specific contextual data for further statistical analysis. Ie: dashboards showing validations splitted by use-case, or billing details segregated by use-case or end customer, etc. The way to achieve this is by using contextual data keys starting with prefix stats_.

By using the "stats" prefix, the customers are telling Veridas that the information is relevant for its business, billing, statistical or troubleshooting purposes, so they want it to be logged.

If this contextual data information wants to be displayed in the production Dashboard that Veridas offers, the following values must be used:

• stats_userid: anonymous value to identify a user (i.e: hash of the id) that in combination with the validation id, be able to identify retries of the user.
• stats_usecase: value to identify the use case if you are planning to include several of them (i.e.: onboarding, documentation update,…).
• stats_tenant: anonymous value to identify a third party or end customer (a must for platforms).
• stats_processid: unique id to identify an onboarding process.
• stats_duration_video: duration of the video in seconds.
• stats_duration_sap: duration of the sap in seconds.

• stats_flow: indicates the onboarding use case. The accepted values are:

  • document
  • document_selfie
  • document_selfie_video
  • document_selfiealive
  • document_selfiealive_video
  • document_selfiealivepro
  • document_selfiealivepro_video
  • document_video
  • document_nfc
  • document_nfc_selfie
  • document_nfc_selfie_video
  • document_nfc_selfiealive
  • document_nfc_selfiealive_video
  • document_nfc_selfiealivepro
  • document_nfc_selfiealivepro_video
  • document_nfc_video

Check that the parameters must always have the “stats_” prefix and be case sensitive.

Validation data timestamping

Once all the validation steps have been carried out, there is the possibility to timestamp the data used on the validation process and the results obtained. The purpose of this, is to provide a mean to verify the integrity of the process and ensure that the data of a validation process corresponds to a specific validation, time after the process has been carried out.

To do this timestamping process, the endpoint PUT /validation/{id}/timestamp has to be called, indicating the Timestamp Authority (TSA) which wants to be used to do the process, or let the default option to be used, "standard". The non default options are "fnmt", which uses the timestamping service of the Spanish entity FNMT (Fábrica Nacional de Moneda y Timbre), and "izenpe" which uses the service of the Vasque Government Certification Authority.

It is important to note that the "standard" TSA does not provide any service level agreement (SLA) and its availability is not guaranteed. For these reasons, it should only be used in testing and pre-production environments.

The API user has the option to timestamp the process data at any time during the validation process by calling this endpoint. However, we recommend doing it at the end of the process, just before confirming or canceling the validation. At that moment, all the evidences and results are present, so the timestamp is more useful.

If the user requests to timestamp more than once in the same validation process, only the last one will be saved because it is understood that this one will be the most complete, but both of them will be charged.

It may happen that the timestamp service fails for some reason beyond our control. In this case, vali-Das will try to timestamp twice and will return an error if both attempts fail.

After the timestamp process, the user can obtain a zip that includes two components: a zip with the data and results available at the time of the timestamp request, and another zip with timestamp request and response files sent to the TSA service.

Confirmation or cancellation

As a final step, the on-course validation process should be "closed" or finalized by sending a PUT /validation/{id}/confirmation or PUT /validation/{id}/cancellation cancel request.

The confirmation of a validation is done by sending a confirmation request using the PUT /validation/{id}/confirmation. This makes the current validation state to be changed from "on course" to "confirmed". Optionally, this same endpoint allows sending the OCR data which has been previously retrieved corrected by the API client. This corrected OCR data can include all the fields with their correct values, or just the ones that need to be corrected (updated). If no OCR data is re-sent, it is considered that the data is correct.

Another way for properly finalizing a validation process is by calling the cancellation endpoint. This request sets the validation to "cancelled" state, and has to be used when the validation process does not want to be continued or completed because of an error has happened, the validation is not useful, an unwanted image has been sent to the system or the validation wants to be started from the beginning.

Deletion

Finally, after cancelling or confirming and retrieving all the validation data, the validation should be deleted to prevent data to remain unnecessarily stored on the vali-Das database.

It is important to mention that vali-Das is designed to strictly follow the flow described before, and therefore, ideally, none of the calls should be reissued or duplicated during the course of a validation. If an error occurs or a certain analysis wants to be repeated, the validation on course should be cancelled and a new one started. Repeating a certain analysis or calling twice a method could lead to a malfunctioning of the process for the "on-course" validation.

An entire sequence diagram with the more common flows is included in the "Resources: Sequence diagram"

Note

The personal data is not stored in the cloud once the process has ended. Veridas has undertaken special efforts to guarantee that the personal data collected remains in the solution only during the minimum period needed to process it. A third party has verified that once the personal data is processed, the solution makes it available to the client, who deletes it, or is automatically deleted in an effective manner after a short period of time, without leaving any data in the system. The recurrence of this automatic clean-up process is agreed between the client and Veridas, establishing Veridas that the recurrence period could be reduced if it is considered to be inadequate.