Identity Verification

Welcome to Identity Verification, an offering within YooniK Services.

Identity verification is typically used as a robust registration mechanism to verify users' identity using a personal identity document, face verification between a live picture and the identity document, and anti-spoofing/liveness checks to detect a real user performing the registration.

The Identity Verification was design to be integrated into any application in a developer friendly fashion by abstracting all the complexity of document OCR, document validation and face biometric verification to build great UX.

Use cases

{primary} Identity Verification to your User Onboarding Flow

Enable strong user onboarding to your flow to avoid bots and scammers on your platform. Identity verification enables scanning documents from 138 languages spanning 248 countries and territories.

{primary} Authentication with identity

Enable subsequent user authentication based on the identity verification performed during onboarding. Be sure that only the rightful owner is accessing their assets or services.

{primary} Privacy-preserving identity verification

We don't store any data from your customer on our servers. Once the identity verification is completed all data is sent to your server unless you request otherwise. Your customers, your rules!

Image requirements

Image formats

The recommended resolution for optimal results is at least 1080p (1920×1080 pixels). Smaller resolutions are accepted but might not provide optimal results. Larger resolutions are also accepted but might slow down the processing times.

Identity verification is recommended to be done on mobile devices with pictures taken from rear cameras of mobile devices for the document scanning and front camera for the selfie pictures. Images acquired with laptops or web cameras usually have lower resolution and image noise arising from compression; therefore, they might not perform well. Nevertheless, both solutions are supported in our solution to comply with usage from Kiosk Apps or other desktop-like scenarios.

Image quality

Document verification algorithms are developed to allow variances in the capture process related to subject-device integration. Keep in mind that the developed intelligent system cannot overcome the laws of physics and works exclusively within its capabilities. Please see the expected acquisition conditions to obtain optimal performance:

Good lightning

Good lighting helps to achieve better OCR results. If the image is too dark or too bright, the document might not be processed successfully.

Bad lightning conditions.

Avoid reflections

Glares and reflections interfere with processing and reduce data extraction accuracy. We recommend not to use the flash of your mobile device when capturing document images.

Visa Evaluation

Focus and sharpness

Make sure the image is clear and there are no blurred areas.

Visa Evaluation

Angle

The tilt angle of the document should not exceed 10 degrees in any direction (horizontal or vertical).

Visa Evaluation

Margins (too small)

Make sure there is minimal space around the document. It is recommended that the document takes up 70-80% of the image.

Visa Evaluation

Margins (too big)

Make sure the space around the document does not take up more than 20-30% of the image. It is recommended that the document takes up 70-80% of the image.

Visa Evaluation

Contrast

The document should be in clear contrast to the background. A light-colored document on a light background, as well as a dark-colored document on a dark background, might not be recognized.

Visa Evaluation

Resolution of the image

To achieve a good quality of recognition of identification documents, we recommend that you provide images captured by a camera with a resolution of at least Full HD (1920×1080) and autofocus.

Visa Evaluation

Extraneous objects

Make sure your hands or other objects do not cover document data.

Visa Evaluation

Configurations

After a subscription is done successfully, you need to set up your environment by filling the following fields in your dashboard:

  • Allow Origins: A set of URLs that will be allowed to make requests to our API/Services. All URLs will be allowed if this field is left empty.

  • Webhook Url: URL on your server that we will use to send the identity verification results (as a POST request).

You can also find your Client ID (client_id), base endpoint (base_url), and API Key (x-api-key) in the dashboard.

Integration

The Identity Verification can be integrated as an iFrame into any existing web apps, covering a full range of use cases such as hotel check-in apps, loyalty registration, or opening banking accounts). With the integration via an iFrame, the identity verification process is displayed directly on your website without redirecting.

Alternatively, we also support redirecting to our service to perform the Id verification process, and then calling back your application/website.

Generate the JSON Web Token (JWT)

For each identity verification flow, a JWT should be generated by calling the following endpoint:

POST | base_url/token

Accepts: Token request

{success} Success

Status Meaning Schema
200 OK Token response

{danger} Error responses

Status Meaning Schema
400 Bad Request N/A
403 Forbidden N/A
422 Unprocessable Entity Token error response
500 Internal Server Error N/A
502 Bad Gateway N/A
503 Service Unavailable N/A
504 Gateway timeout N/A

Embedding the iFrame

The iFrame can be embedded into the HTML code using the following snippet:

<iframe src="<base_url>?token=<token>" style=”width: 100%; height: 90vh;” frameBorder="0" allow="camera"></iframe>

The base_url parameter can be found in your dashboard and the token parameter is the previously generated JWT.

Using a redirect

Alternatively to an iFrame, we also support redirecting the user to our service directly (you can perform a redirect to the same URL used in the iFrame: <base_url>?token=<token>).

In this case, the redirect_url parameter in the Token request is required in order to redirect back the user to your application/website after the identity verification process is complete.

Getting the results in the Webhook

Webhooks are one of a few ways web applications can communicate with each other. They allow sending real-time data from one application to another whenever a given event occurs.

YooniK will send a POST request to the Webhook URL you defined in the dashboard with the results of the process. This request will also have your x-api-key in its header so you can confirm it came from YooniK.

Schemas

Token request

Request to generate the JWT.

Schema
{
    "client_id":"string",
    "user_id":"string",
    "location_id":"string",
    "expire_date":"YYYY-MM-DDThh:mm",
    "redirect_url":"https://example.com",
    "id_card_option": "front_back_side"
}

Properties

Name Type Required Restrictions Description
client_id string True None You can find your Client ID in your dashboard.
user_id string True None Unique identifier for the user doing identity verification.
location_id string False None Unique identifier for the location where the user will be staying, in case you want to use their identity for authentication.
expire_date datetime False None Expire date for the user data (usually the duration in which the data is needed, so the user data can be used for authentication). If not set, all data is deleted after the process.
redirect_url string False None URL to redirect the user after finishing the identity verification process.
id_card_option string False None Identity card scan type (front and back sides vs front side only). If not set, the user will be able to select which option to use.

Enumerable types

Property Value Description
id_card_option front_side For id cards, scan front side only.
id_card_option front_back_side For id cards, scan front and back sides.
id_card_option null User will be able to chose which id card sides to scan.

Token response

Response with the generated JWT.

Schema
{
    "token": "string"
}

Properties

Name Type Required Restrictions Description
token string True None Generated JWT.

Token error response

Error response when generating JWT.

Schema
{
    "message": "string"
}

Properties

Name Type Required Restrictions Description
message string True None Error message.

Webhook request

Object with the identity verification process results.

The document field will be present only if the user is validated by passing the face matching score and liveness checks.

Schema
{
    "user_id": "string",
    "status": "VALIDATED",
    "document": "Document"
}

Properties

Name Type Required Restrictions Description
user_id string True None Unique identifier for the user doing registration.
status string True None Process status.
document string False None Validated document.

Enumerable Types

Property Value Description
status VALIDATED Document was successfully validated.
status CANCELED The process was canceled by the user.
status INVALID_DOCUMENT Document scan and validation failed multiple times.

Document response

Object with all the document information. Status check is performed based on the available document visible light features and data sources.

Schema

{
    "type": "string",
    "status":  "string",
    "fields": [firstdocumentFieldSchema, secondDocumentFieldSchema, ...],
    "images": [firstDocumentImageSchema, secondDocumentImageSchema, ...]
}

Properties

Name Type Required Restrictions Description
type string True None Document type.
status string True None Document validity status.
fields array True None Array of Document text fields.
images array True None Array of Document images.

Enumerable Types

Property Value Description
type IDENTITY_CARD Identity card.
type DRIVING_LICENSE Driving license.
type PASSPORT Passport.
type UNKNOWN Unknown document type.
status VALID Valid / consistency check.
status INVALID Invalid / inconsistency check.
status UNVERIFIED Not verified / not applicable.

Document image

Images from document.

Schema
{
    "source": "string",
    "image": "string"
}

Enumerable Types

Name Type Required Restrictions Description
source string True None Type of document image.
image string True None Base64 image.

Enumerable Types

Property Value Description
source PORTRAIT Portrait picture from document page.
source CHIP_IMAGE Portrait picture from document chip.
source GHOST_PORTRAIT Ghost portrait from document page.
source SIGNATURE Signature picture if present.
source FRONT_PAGE Document front page cropped.
source REAR_PAGE Document back page cropped.

Validation field

Validation information and their corresponding validation sources. Validation sources can come from MRZ string, Visual OCR, Chip information or others.

{
  "status": "VALID",
  "source": ["MRZ", "VISUAL"]
}

Properties

Name Type Required Restrictions Description
status string True None Validation status.
source array True None Array with different cross validation data sources.

Enumerable Types

Property Value Description
status VALID Valid / consistency check
status INVALID Invalid / inconsistency check
status UNVERIFIED Not verified / not applicable
source MRZ Field obtained from MRZ info
source VISUAL Field obtained from Visual OCR info
source CHIP Field obtained from Chip information
source OTHER Field obtained from other source

Document field

Description of the document text fields using Visual (when available), MRZ (when available) and Chip (when available).

{
    "name": "string",
    "value": "string",
    "cross_validation": "string",
    "status": "string",
    "cross_validation_list": [
      firstvalidationFieldSchema,
      secondValidationFieldSchema,
      ...]
}

Properties

Name Type Required Restrictions Description
name string True None Document field name.
value string True None Document field value.
status string True None Validation status.
cross_validation string False None Correlation status.
cross_validation_list array False None Array of validation fields

Enumerable Types

Property Value Description
status VALID Valid / consistency check.
status INVALID Invalid / inconsistency check.
status UNVERIFIED Not verified / not applicable.
cross_validation VALID Valid / consistency check.
cross_validation INVALID Invalid / inconsistency check.
cross_validation UNVERIFIED Not verified / not applicable.
name REMAINDER_TERM Months to expire.
name ISSUING_STATE_CODE issuing state code in compliance with ISO3166-1 standard.
name DOCUMENT_NUMBER Document number.
name DATE_OF_EXPIRY Date of document expiration
name DATE_OF_ISSUE Date of document issuing.
name DATE_OF_BIRTH Date of birth.
name PLACE_OF_BIRTH Place of birth.
name PERSONAL_NUMBER Personal number.
name SURNAME Surname.
name GIVEN_NAME Given name.
name NATIONALITY Nationality.
name SEX Sex.
name ADDRESS Address.
name SOCIAL_SECURITY_NUMBER Social security number.
name DL_CLASS Driving license class code.
name AUTHORITY issuing authority.
name SURNAME_AND_GIVEN_NAMES Surname and given name(s).
name NATIONALITY_CODE nationality code in compliance with ISO3166-1 standard.
name PASSPORT_NUMBER Passport number.
name MRZ_TYPE MRZ type (ID-1 – 0, ID-2 – 1, ID-3 – 2).
name OPTIONAL_DATA Optional data.
name DOCUMENT_CLASS_NAME Document class name
name ISSUING_STATE_NAME Issuing state name.
name PLACE_OF_ISSUE Place in which the document was issued.
name DOCUMENT_NUMBER_CHECKSUM Document number checksum.
name DATE_OF_BIRTH_CHECKSUM Date of birth checksum.
name DATE_OF_EXPIRY_CHECKSUM Date of expiration checksum.
name PERSONAL_NUMBER_CHECKSUM Personal number checksum.
name FINAL_CHECKSUM Final checksum.
name PASSPORT_NUMBER_CHECKSUM Passport number checksum. (for visas)
name SURNAME_AND_GIVEN_NAME_CHECKSUM Surname and given names checksum.
name MRZ_STRINGS MRZ parsed strings.
name DATE_OF_ISSUE_CHECKSUM Issuing date checksum.
name DATE_OF_ISSUE_CHECK_DIGIT Issuing date check digit.
name PLACE_OF_REGISTRATION Place of registration.
name DATE_OF_REGISTRATION Date of registration.
name AUTHORITY_CODE Authority code (Russian Federation passports).
name PLACE_OF_BIRTH_AREA Place of birth area.
name PLACE_OF_BIRTH_STATE_CODE Place of birth state code.
name DOCUMENT_NUMBER_CHECK_DIGIT Document number check digit.
name DATE_OF_BIRTH_CHECK_DIGIT Date of birth check digit.
name DATE_OF_EXPIRY_CHECK_DIGIT Date of expiration number check digit.
name PERSONAL_NUMBER_CHECK_DIGIT Personal number check digit.
name FINAL_CHECK_DIGIT Final check digit.
name PASSPORT_NUMBER_CHECK_DIGIT Passport number check digit (for visas).
name SURNAME_AND_GIVEN_NAMES_CHECK_DIGIT Surname and given names check digit.
name FAMILY_NAME Family name.
name ISSUING_STATE_CODE_NUMERIC numeric issuing state code in compliance with ISO 3166-1 standard.
name NATIONALITY_CODE_NUMERIC numeric nationality code in compliance with ISO 3166-1 standard.
name IDENTITY_CARD_NUMBER Identity card number.
name LINE_1_CHECK_DIGIT Line 1 check digit.
name LINE_2_CHECK_DIGIT Line 2 check digit.
name LINE_3_CHECK_DIGIT Line 3 check digit.
name LINE_1_CHECKSUM Line 1 checksum.
name LINE_2_CHECKSUM Line 2 checksum.
name LINE_3_CHECKSUM Line 3 checksum.
name AGE Age.
name OPTIONAL_DATA_CHECKSUM Optional data checksum.
name OPTIONAL_DATA_CHECK_DIGIT Optional data check digit.
name STATUS_DATE_OF_EXPIRY Status of expiration date.
name LINE_1_OPTIONAL_DATA Line 1 optional data.
name LINE_2_OPTIONAL_DATA Line 2 optional data.
name LINE_3_OPTIONAL_DATA Line 3 optional data.
name DATE_OF_CREATION Date of creation.
name IDENTITY_CARD_NUMBER_CHECKSUM Identity card number checksum.
name IDENTITY_CARD_NUMBER_CHECK_DIGIT Identity card number check digit.
name TAX_NUMBER Tax authority number.
name HEALTH_NUMBER Health insurance number.
name AGE_AT_ISSUE Age at issue.
name YEARS_SINCE_ISSUE Years since issue.

Troubleshooting

If you find any issues or need help with the setup please contact us or join us at our discord community.