Create a check (Web SDK)

Start here

You may find our "General Introduction" guide useful.

This guide assumes you're using our API v3 for the backend calls. If you're looking for quick-start guides for earlier versions of our API, please email our Client Support team.

Follow this guide to:

• integrate with our Web SDK
• create a check composed of a Document report and a Facial Similarity Photo report using our Web SDK

The Onfido Web SDK provides a set of components for JavaScript applications to capture identity documents and selfie photos or videos for the purpose of identity verification. The SDKs do not perform the check.

You'll find more detailed information on the steps involved in our guides: Web SDK reference and API reference.

Subscribing to updates

You can subscribe to updates about new features and releases for the Web SDK via GitHub.

You may wish to read more about viewing your GitHub subscriptions.

Overview of steps

Obtain an API token

In order to start integration, you will need an API token. You can use our sandbox environment to test your integration, and you will find the sandbox token inside your Onfido Dashboard.

Onfido offers region-specific environments. Read more about region settings in the API documentation.

Create an applicant

The first step in creating any check is to create an applicant from your backend server, using a valid API token.

For Document and Facial Similarity Photo reports, you must at least specify the applicant's first and last names in the body of the request.

Example applicant creation request

curl -X POST https://api.eu.onfido.com/v3.4/applicants/ \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1990-01-31",
  "address": {
    "building_number": "100",
    "street": "Main Street",
    "town": "London",
    "postcode": "SW4 6EH",
    "country": "GBR"
  }
}'

applicant_details = {
  first_name: "Jane",
  last_name: "Doe",
  dob: "1990-01-01",
  address: {
    building_number: "100",
    street: "Second Street",
    town: "London",
    postcode: "S2 2DF",
    country: "GBR"
  }
}

applicant = api_instance.applicant.create(applicant_details)
applicant_id = applicant['id']

const newApplicant = await onfido.applicant.create({
  firstName: "Jane",
  lastName: "Doe",
  dob: "1990-01-31",
  address: {
    postcode: "S2 2DF",
    country: "GBR"
  }
});

const applicantId = newApplicant.id;

applicant_details = {
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1984-01-01",
  "address": {
    "street": "Second Street",
    "town": "London",
    "postcode": "S2 2DF",
    "country": "GBR"
  }
}

applicant = api.applicant.create(applicant_details)

applicant_id = applicant['id']

$applicantDetails = new Onfido\Model\Applicant();

$applicantDetails->setFirstName('Jane');
$applicantDetails->setLastName('Doe');
$applicantDetails->setDob('1990-01-31');

$address = new \Onfido\Model\Address();
$address->setBuildingNumber('100');
$address->setStreet('Main Street');
$address->setTown('London');
$address->setPostcode('SW4 6EH');
$address->setCountry('GBR');

$applicantDetails->setAddress($address);

$applicant = $apiInstance->createApplicant($applicantDetails);
$applicantId = ($applicant)->getId();

import java.time.LocalDate;
import com.onfido.models.Address;
import com.onfido.models.Applicant;

Address.Request addressRequest = Address.request()
        .street("Main Street")
        .town("London")
        .postcode("SW4 6EH")
        .country("GBR");

Applicant.Request applicantRequest = Applicant.request()
        .firstName("Jane")
        .lastName("Doe")
        .dob(LocalDate.parse("1990-01-31"))
        .address(addressRequest);

Applicant applicant = onfido.applicant.create(applicantRequest);

String applicantId = applicant.getId();

Example response

The response will contain an id (the applicant ID). You'll use this in the next steps.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<APPLICANT_ID>",
  "created_at": "2019-10-09T16:52:42Z",
  "sandbox": true,
  "first_name": "Jane",
  "last_name": "Doe",
  "email": null,
  "dob": "1990-01-01",
  "delete_at": null,
  "href": "/v3.4/applicants/<APPLICANT_ID>",
  "id_numbers": [],
  "address": {
    "flat_number": null,
    "building_number": null,
    "building_name": null,
    "street": "Second Street",
    "sub_street": null,
    "town": "London",
    "state": null,
    "postcode": "S2 2DF",
    "country": "GBR",
    "line1": null,
    "line2": null,
    "line3": null
  }
}

Generate an SDK token

Use your API token to make a request to the 'generate SDK token' endpoint, including the applicant ID you created in the previous step and a valid referrer (see below):

curl -X POST https://api.eu.onfido.com/v3.4/sdk_token \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
     "applicant_id": "<APPLICANT_ID>",
     "referrer": "https://*.example.com/example_page/**",
     "cross_device_url": "https://example.com"
   }'

referrer = 'https://*.example.com/example_page/**'
cross\_device\_url = 'https://example.com'

api_instance.sdk_token.create(applicant_id: applicant_id, referrer: referrer, cross_device_url: cross_device_url)

const sdkToken = await onfido.sdkToken.generate({
  applicantId,
  referrer: "https://*.example.com/example_page/**",
  crossDeviceUrl: "https://example.com"
});

request_body = {"applicant_id": applicant_id, "referrer": "https://*.example.com/example_page/**"}

api.sdk_token.create(request_body)

$sdkTokenRequest = new Onfido\Model\SdkToken();

$sdkTokenRequest->setApplicantId($applicantId);
$sdkTokenRequest->setReferrer('https://*.example.com/example_page/*');

$apiInstance->generateSdkToken($sdkTokenRequest);

SdkToken.Request sdkTokenRequest = SdkToken.request()
    .applicantId(applicantId)
    .referrer("https://*.example.com/example_page/*")
    .crossDeviceUrl("https://example.com");

String sdkToken = onfido.sdkToken.generate(sdkTokenRequest);

Each authenticated instance of the SDK will correspond to a single Onfido applicant. You’ll need to generate and include a new token each time you initialize the Web SDK. SDK tokens expire after 90 minutes.

The referrer argument specifies the URL of the web page where the Web SDK will be used. It guarantees that other malicious websites cannot reuse the SDK token in case it is lost.

The referrer sent by the browser must match the referrer URL pattern in the SDK token for the SDK to successfully authenticate.

You must use a site referrer policy that lets the Referer header be sent. If your policy does not allow this (e.g. Referrer-Policy: no-referrer), then you'll receive a 401 bad_referrer error when trying to use the Web SDK.

Read more about referrer policy in Mozilla's documentation.

An example of a valid referrer is https://*.example.com/example_page/*. You can read about valid referrer patterns in our API reference.

The cross device flow of the Web SDK allows users to continue the identity verification process from their phone. They can then take pictures with their phone, rather than having to upload images from their desktop. This feature is available to all customers and uses the URL id.onfido.com as the default.

The cross_device_url argument is used to white-label the default Onfido cross-device URL to one of your choosing with a maximum character length of 24 including https://. This also requires additional setup to map back to the Onfido hosted cross-device address. While the cross-device flow is available to all, white-labeling the URL using this argument is a premium enterprise feature that must be activated for your account before it may be used. Please talk to your account executive for more information about purchasing this feature.

Import the library and CSS

You can either:

• import directly into your HTML page
• use npm

HTML import

Include the library as a regular <script> tag on your page:

<script src='dist/onfido.min.js'></script>

Include the standard CSS:

<link rel='stylesheet' href='dist/style.css'>

npm import

$ npm install --save onfido-sdk-ui

// ES6 module import
import {init} from 'onfido-sdk-ui'

// commonjs style require
var Onfido = require('onfido-sdk-ui')

If you import the library using npm, the CSS will be included inline within the JavaScript.

You should only use the Web SDK as part of the frontend of your application. We do not provide server-side (Node.js) application support with the Web SDK.

Add basic HTML markup

At the bottom of your page, you need an empty HTML element where the verification component will be mounted:

<div id='onfido-mount'></div>

Initialize the SDK

Next, with the SDK token you generated earlier, initialize the SDK.

Read more detailed instructions about this process in our Web SDK reference.

Use the following code snippet for running a check with the example Document and Facial Similarity Photo reports:

Onfido.init({
  token: '<YOUR_WEB_SDK_TOKEN>',
  containerId: 'onfido-mount',
  onComplete: function(data) {
    console.log("A completion message")
  },
 steps: [
        'welcome',
        'document',
        'face',
        'complete'
      ]
});

* For example, you could have a function which triggers a check creation on your backend server. Read more in our API reference.

The steps parameter contains a list of the steps the user will be presented with during the SDK flow. You can specify steps:

• as a string when customization is not required
• as an object when customization is required

Read more about the different steps and their custom options in our Web SDK reference.

Submit the check

Use your API token to make a request to the 'create check' endpoint from your backend server, using the applicant ID you generated earlier, and specifying the reports.

Example check submission request

curl -X POST https://api.eu.onfido.com/v3.4/checks \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "applicant_id": "<APPLICANT_ID>",
  "report_names": ["document", "facial_similarity_photo"]
}'

check = api_instance.check.create(applicant_id: applicant_id, report_names: ['document', 'facial_similarity_photo'])
check_id = check['id']
report_ids = check['report_ids']

const applicantId = "<APPLICANT_ID>";

const newCheck = await onfido.check.create({
  applicantId,
  reportNames: ["document", "facial_similarity_photo"]
});

const checkId = check.id;
const reportIds = check.reportIds;

request_body = {"applicant_id": applicant_id, "report_names": ["document", "facial_similarity_photo"]}

check = api.check.create(request_body)

check_id = check['id']
report_ids = check['report_ids']

$checkData = new Onfido\Model\Check();
$checkData->setApplicantId($applicantId);
$checkData->setReportNames(array('document', 'facial_similarity_photo'));

$check = $apiInstance->createCheck($check_data);
$checkId = ($check)->getId();
$reportIds = ($check)->getReportIds();

import com.onfido.models.Check;

Check.Request checkRequest = Check.request()
  .applicantId(applicantId)
  .reportNames("document", "facial_similarity_photo");

Check check = onfido.check.create(checkRequest);

Example response

{
  "id": "<CHECK_ID>",
  "created_at": "2019-10-09T17:01:59Z",
  "status": "in_progress",
  "redirect_uri": null,
  "result": null,
  "sandbox": true,
  "tags": [],
  "results_uri": "<RESULTS_URI>",
  "form_uri": null,
  "paused": false,
  "version": "3.0",
  "report_ids": [
    "<REPORT_IDs>"
  ],
  "href": "/v3.4/checks/<CHECK_ID>",
  "applicant_id": "<APPLICANT_ID>",
  "applicant_provides_data": false
}

Result breakdown

Successful responses contain an overall result for the check as well as individual results for each report. The result of a check is derived from the results of the individual reports that it contains.

Check result

If all the reports have passed verification, the check result is clear:

result:clear

If one or some reports have failed to pass verification, the check result is consider:

result:consider

Report results

If an individual report has passed, the result is clear:

result:clear

If the report has failed to pass verification, the result is consider:

result:consider

Report sub results

Note that if a Document report has been conducted, sub-results will also be provided to give a more detailed description of the report result.

You can read about sub-results in our API reference.

Retrieve checks or reports

You can retrieve an individual check or report's status and result via the API.

If you have set up webhooks as described in our 'Get started integrating' guide, a notification is sent upon completion of a check or report, or both.

Example request to find a check

You can return the object for a check using the check ID (the object will contain all associated report IDs as an array of strings in the report_ids field):

curl https://api.eu.onfido.com/v3.4/checks/<CHECK_ID> \
  -H 'Authorization: Token token=YOUR_API_TOKEN'

api_instance.check.find(check_id)

const check = await onfido.check.find(checkId);

api.check.find(check_id)

$apiInstance->findCheck($checkId);

import com.onfido.models.Check;

Check check = onfido.check.find(checkId);

Example request to list reports

You can list all the reports associated with specific check IDs:

curl https://api.eu.onfido.com/v3.4/reports?check_id=<CHECK_ID> \
  -H 'Authorization: Token token=YOUR_API_TOKEN'

api_instance.report.all(check_id)

const reports = await onfido.report.list(checkId);

api.report.all(check_id)

apiInstance->listReports($checkId);

import com.onfido.models.Report;

List<Report> reports = onfido.report.list(checkId);

Example request to find a report

You can return details of specific reports using their IDs:

curl https://api.eu.onfido.com/v3.4/reports/<REPORT_ID> \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>'

report_id = '<REPORT_ID>'

api_instance.report.find(report_id)

const reportId = "<REPORT_ID>";

const report = await onfido.report.find(reportId);

report_id = "<REPORT_ID>"

api.report.find(report_id)

$reportId = '<REPORT_ID>';

$apiInstance->findReport($reportId);

import com.onfido.models.Report;

String reportId = "<REPORT_ID>";

Report report = onfido.report.find(reportId);