Identity Verification

Welcome to Identity Verification, an offering within Youverse 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.

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.

Focus and sharpness

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

Angle

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

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.

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.

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.

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.

Extraneous objects

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

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.

Youverse 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 Youverse.

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",
    "web_verification":"boolean",
    "expiration":"numeric",
    "document_options":"array",
    "change_camera":"boolean",
    "disable_selfie":"boolean",
    "multipage_processing":"boolean",
    "mobile_flow":"boolean"
}

Properties

Name	Type	Required	Default	Description
client_id	string	True	null	You can find your Client ID in your dashboard.
user_id	string	True	null	Unique identifier for the user doing identity verification.
location_id	string	False	null	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	null	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	null	URL to redirect the user after finishing the identity verification process.
web_verification	boolean	False	false	Boolean flag for enabling web-based verification. Setting to `true` enables the web desktop flow.
expiration	numeric	False	1	Numeric value indicating the token expiration time in hours. Allowed values: 1, 24 and 168.
document_options	array	False	null	Array representing document options. Allowed values: PASSPORT, IDENTITY_CARD, DRIVING_LICENSE, VISA, VOTING_CARD, ADDRESS_CARD, RESIDENT_CARD and AUTO.
change_camera	boolean	False	false	Boolean flag indicating whether users can change the camera during the verification process.
disable_selfie	boolean	False	false	Boolean flag indicating whether selfie capture is disabled.
multipage_processing	boolean	False	false	Boolean flag indicating whether multipage document processing is enabled.
mobile_flow	boolean	False	false	Boolean flag indicating whether the mobile flow is enabled.

Enumerable types

Property	Value	Description
document_options	PASSPORT	Passport.
document_options	IDENTITY_CARD	Identity card.
document_options	DRIVING_LICENSE	Driving license.
document_options	VISA	Visa.
document_options	VOTING_CARD	Voting card.
document_options	ADDRESS_CARD	Address card.
document_options	RESIDENT_CARD	Resident card.
document_options	AUTO	When using "AUTO," explicit definition of the document type is not required. The system will automatically identify and process the document type during the verification process.

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.
status	MAX_RETRIES_EXCEEDED	The validation attempt limit has been exceeded.

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.

Get started

Products

IAM Integrations

Identity Verification

Use cases

Image requirements

Image formats

Image quality

Good lightning

Avoid reflections

Focus and sharpness

Angle

Margins (too small)

Margins (too big)

Contrast

Resolution of the image

Extraneous objects

Configurations

Integration

Generate the JSON Web Token (JWT)

Embedding the iFrame

Using a redirect

Getting the results in the Webhook

Schemas

Token request

Schema

Token response

Schema

Token error response

Schema

Webhook request

Schema

Document response

Schema

Document image

Schema

Validation field

Document field

Troubleshooting