Document Verification

Overview

The Document Verification product lets you verify the authenticity of Identity documents submitted by your users and confirm that the document actually belongs to the user by comparing the user's selfie to the photo on the document. To run a document verification job, we require:

A selfie of the user
An image of the document
The country of issuance (this must be one of our supported document type and country, all supported documents and countries is listed in the next section)

Key Features:

Document Authentication: Verify the authenticity of identity documents by checking security features, MRZ and barcodes.
User Authentication: Confirm that the submitted document belongs to the user by comparing their selfie with the photo on the document. This step ensures that the person presenting the document is indeed its rightful owner.
Global Coverage: Document Verification supports a wide range of document types and countries. You can rely on our extensive database of supported documents and countries to ensure comprehensive coverage.

Supported Documents

For the full list of supported documents, please refer to the supported continents in our documentation.

Integration Options

Available via the Rest API, Mobile, Server to Server and Web SDK.

We highly recommend using document verification product via the mobile SDKs or Web SDK (on a mobile device). This is because we require high image resolutions in order for our machine to check the authenticity of the document. You can still use document verification via the other integration options but you will be responsible for capturing the images to the required specification.

Image Specifications

Please ensure that the orientation of your document images matches the way information is printed on the document. For example, if the document is meant to be read vertically(portrait) like a passport, do not rotate the image to a horizontal (landscape) orientation.

To check the authenticity of the document, we require high-resolution images. The image should be cropped to include the entire document with minimal background.

The following are the minimum specifications we require for the document image:

The minimum resolution on the horizontal (longer) side of credit card-sized ID cards should be 1500 pixels.
Minimum resolution on the horizontal (longer) side of passports should be 2200 pixels.
The total Image size should be at least 600KB but no more than 10MB.

To get the best results on document verification, we recommend the document image meets the following criteria:

Ensure the image is not tightly cropped. All edges of the ID document should be visible.
The face in the ID photo should be visible.
The document should be placed on a flat, non-white surface for the capture.
If the document contains an MRZ code, ensure no part of the code is covered by a finger or is cut off in the image.
Avoid fingers covering any part of the document.
Ensure no glare or bright light (flash) obstructs information on the document.
All text on the document must be readable after capture.

Request Values

You need to perform two steps to use this product:

Make a request to Smile ID for a job to be performed
Upload the job payload

NOTE: The value of the job_type for this product is 6

Making a Job Request

Request Type: POST

At the end of the request, you will receive a job number for tracking and a url where you will be uploading your images.

Example Request

{
  "callback_url": "https://<partner side callback URL>/",
  "model_parameters": {},
  "partner_params": {
    "job_id": "job_09876",
    "job_type": 6,
    "user_id": "user_12345"
  },
  "signature": "<calculated signature>",
  "smile_client_id": "<partner id>",
  "source_sdk": "rest_api",
  "source_sdk_version": "1.0.0",
  "timestamp": "<timestamp e.g. 2021-08-12T17:57:00.614879>"
}

In the response body to the prep upload request, you will receive an AWS s3 bucket link. You will upload the images for face and identity document verification to this link. The URL is structured like:

"https://smile-uploads-test.s3.us-west-2.amazonaws.com/videos/ <partner_id>/<partner_id>-<smile_job_id>-<random hash>/attachments.zip ?AWSAccessKeyId=<> &Content-Type=application%2Fzip &Expires=1598449184&Signature=<> &x-amz-security-token=<>&x-amz-server-side-encryption=AES256"

Example Response

200: OK

A record has now been created waiting for the job to be processed once the required data has been uploaded

{
    "upload_url": "https://smile-uploads-test.s3.us-west-2.amazonaws.com/videos/<partner_id>/<partner_id>-<smile_job_id>-<random hash>/selfie.zip?AWSAccessKeyId=<>&Content-Type=application%2Fzip&Expires=1598449184&Signature=<>&x-amz-security-token=<>&x-amz-server-side-encryption=AES256",
    "ref_id": "<partner_id>-<smile_job_id>-<random hash>",
    "smile_job_id": "0000000001",
    "camera_config": "null", ---sdk specific---
    "code": "2202"
}

400: Bad Request

Trying to use a job_id in partner_params that has already been used

{
  "error": "Job already exists. Did you mean to set the retry flag to true?",
  "code": "2215"
}

Uploading the Job Payload

To perform a job, Smile ID requires a Zip file that contains the following information:

images - images are ID document photo (bearer's face must be visible), selfie and liveness images (optional)
Info.json file - the structure of the info.json file is detailed below

The Zip file must have the same name as the file_name specified while making a job request (prep upload). In the case of the example request above, the filename will be attachments.zip.

Request Type: PUT

The request body will be of type binary (the zip file)

Info.json file

The info.json file contains the selfie and ID card images required to process the document verification job. The images can either be parsed inline as a base64 encoded string or the image files themselves can be zipped with the info.json file. Only .jpg file type is supported.

The structure of the info.json file is detailed below

Info.json Example

The zip file contains the info.json file only (if images are inline i.e. supplied as base64 encoded strings) or both an info.json file and image files (if the image files themselves are uploaded).

Example zip file and info.json when images are inline (i.e. base64 encoded strings)

The content of the info.json file below:

{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "id_info":
  {
    "country":"<country code e.g. NG>",
    "id_type":"<smile ID type keyword e.g. PASSPORT>"
  },
  "images": [
    {
      <Use this for the selfie>
      "image_type_id": 2,
      "image": "iVBORw0KGgoAAAANSUhEUgAAArgWElmTU0A- - -truncated base64 string",
      "file_name": ""
    },
    {
      <Use this for the ID card>
      "image_type_id": 3,
      "image": "iVBORw0KGlDQ1BJQ0MgUHJvZmlsZQAASImVVw- - -truncated base64 string",
      "file_name": ""
    }
  ]
}

Example zip file and info.json when images are uploaded as files

The content of the info.json file below:

{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "id_info":
  {
    "country":"<country code e.g. NG>",
    "id_type":"<smile ID type keyword e.g. PASSPORT>"
  },
  "images": [
    {
      <Use this for the selfie>
      "image_type_id": 0,
      "image": "",
      "file_name": "Selfie.jpeg"
    },
    {
      <Use this for the ID card>
      "Image_type_id": 1,
      "image": "",
      "file_name": "ID.jpg"
    }
  ]
}

How Smile ID Processes the Job

Return Values

The full list of keys and possible return values are highlighted below:

*Only returned if information is on the physical ID card

** If a single selfie image is provided, the system will only perform a photo of photo check

Example JSON Response

{
  "Actions": {
    "Human_Review_Compare": "Passed",
    "Human_Review_Liveness_Check": "Passed",
    "Liveness_Check": "Passed",
    "Register_Selfie": "Approved",
    "Return_Personal_Info": "Returned",
    "Selfie_To_ID_Card_Compare": "Completed",
    "Verify_Document": "Passed"
  },
  "Country": "NG",
  "DOB": "1989-01-20",
  "Document": "----base64 encoded string----",
  "ExpirationDate": "2025-11-26",
  "IssuanceDate": "2000-01-01",
  "FullName": "John Joe Doe",
  "Gender": "M",
  "IDNumber": "B00123456",
  "IDType": "PASSPORT",
  "PartnerParams": {
    "job_id": "Testing_0036",
    "job_type": 6,
    "user_id": "Test_0036"
  },
  "ResultCode": "0810",
  "ResultText": "Document Verified After Human Review",
  "SmileJobID": "0000000046",
  "signature": "---signature---",
  "timestamp": "2021-12-14T20:07:56.829Z"
}

Evaluating the Results

Actions performed on the product are not completed at the same time, so we send results to your callback endpoint when they are ready. Also, if the Smile ID system can not automatically make a decision on an action it is passed to our human reviewers, the system decision is sent via callback once the reviewers make a final decision.

The Document Verification can fail for multiple reasons:

A spoof was detected on the submitted selfie - if we believe the selfie has been tampered with or is a picture of a picture, the document verification will fail.
The submitted selfie does not match the face on the document - if the selfie and face on the document do not match, the document verification job will fail.
The OCR extracted information and the decoded MRZ or barcode information do not match e.g. name encoded in the MRZ does not match the name that can be seen on the document.
The document image or selfie is blurry.
Some known visible security features on the document are missing e.g. the coat of arms on a Nigerian driver’s license.
The id type specified by the user does not match our system’s classification of the document type.

Result Codes and Result Texts

Result codes details what the current (or final) result of a job is. Result Codes for all jobs fall into one of two categories:

Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.
Rejected (or Fail) This means that one or more of the applicable Actions for job failed, and thus, the overall job was rejected according to Smile ID standards.

General Failures Result Codes and Texts

This means no further processing is possible on the job. General failures occur when a job could not be submitted due to a logical/technical issue. These jobs do not show up in the portal and do not have a Smile Job ID.

* Read more on how to troubleshoot this error here

Product Specific Result Codes and Texts

For documents that go through human review and are failed after the review, the result message details the reason for the failure:

* If a job is approved with attention, we suggest that you determine the appropriate course of action in your system by considering the reason for the attention.

Running in Sandbox

Document verification can be tested in our sandbox environment. However, you will get a simulated response. In sandbox, the document verification job is processed as described below:

The selfie is compared to the photo on the identity document, if both images do not match the document verification job fails
The authenticity of the document is not confirmed and we will always return the document as been valid
The values you parse in id_type and country are not checked with the supported countries and ids

Performing Document Verification with a Registered User’s Selfie

Document verification can be performed on users that have been previously enrolled successfully through an Biometric KYC or SmartSelfie™ Authentication - User Registration.

When performing document verification for an already enrolled user, you do not need to submit a selfie in the info.json file. You only send the user_id of the user, the image of the document ID, and set the flag use_enrolled_image to true during prep upload.

Request Values

You need to perform two steps to use this product:

Make a request to Smile ID for a job to be performed
Upload the job payload

Making a Job Request

Request Type: POST

At the end of the request, you will receive a job number for tracking and a url where you will be uploading your images

Example Request

{
  "callback_url": "https://<partner side callback URL>/",
  "model_parameters": {},
  "partner_params": {
    "job_id": "job_09876",
    "job_type": 6,
    "user_id": "user_12345"
  },
  "signature": "<calculated signature>",
  "smile_client_id": "<partner id>",
  "timestamp": "<timestamp e.g. 2021-08-12T17:57:00.614879>",
  "use_enrolled_image": true
}

Example Response

200: OK

A record has now been created waiting for the job to be processed once the required data has been uploaded

{
    "upload_url": "https://smile-uploads-test.s3.us-west-2.amazonaws.com/videos/<partner_id>/<partner_id>-<smile_job_id>-<random hash>/selfie.zip?AWSAccessKeyId=<>&Content-Type=application%2Fzip&Expires=1598449184&Signature=<>&x-amz-security-token=<>&x-amz-server-side-encryption=AES256",
    "ref_id": "<partner_id>-<smile_job_id>-<random hash>",
    "smile_job_id": "0000000001",
    "camera_config": "null", ---sdk specific---
    "code": "2202"
}

400: Bad Request

Trying to use a job_id in partner_params that has already been used

{
  "error": "Job already exists. Did you mean to set the retry flag to true?",
  "code": "2215"
}

Uploading the Job Payload

To perform a job, Smile ID requires a Zip file that contains the following information:

ID card image
Info.json file - the structure of the info.json file is detailed below

The Zip file must have the same name as the file_name specified while making a job request (prep upload). In the case of the example request above, the filename will be attachments.zip.

Request Type: PUT

The request body will be of type binary (the zip file)

Info.json file

The info.json file contains the ID card image required to process the document verification job. The image can either be parsed inline as a base64 encoded string or the image files themselves can be zipped with the info.json file. Only .jpg file type is supported.

The structure of the info.json file is detailed below

Info.json Example

The zip file contains the info.json file only (if images are inline i.e. supplied as base64 encoded strings) or both an info.json file and image files (if the image files themselves are uploaded).

Example zip file and info.json when images are inline (i.e. base64 encoded strings)

The content of the info.json file below:

{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "id_info":
  {
    "country":"<country code e.g. NG>",
    "id_type":"<smile ID type keyword e.g. PASSPORT>"
  },
  "images": [
    {
      <Use this for the ID card>
      "Image_type_id": 3,
      "image": "iVBORw0KGlDQ1BJQ0MgUHJvZmlsZQAASImVVw- - -truncated base64 string",
      "file_name": ""
    }
  ]
}

Example zip file and info.json when images are uploaded as files

The content of the info.json file below:

{
  "package_information":
  {
    "apiVersion": {
      "buildNumber": 0,
      "majorVersion": 2,
      "minorVersion": 0
    }
  },
  "id_info":
  {
    "country":"<country code e.g. NG>",
    "id_type":"<smile ID type keyword e.g. PASSPORT>"
  },
  "images": [
    {
      <Use this for the ID card>
      "Image_type_id": 1,
      "image": "",
      "file_name": "ID.jpg"
    }
  ]
}

The return values, result codes and texts all remain the same as submitting the job with a selfie

PreviousDocument Verification NextEnhanced Document Verification

Last updated 2 months ago