Web SDK Quick Start

Get Started

Please read our introduction guide before starting here.

This guide assumes you've already integrated with our Web SDK. If you haven't done this yet but want to read about how, read our documentation on GitHub.

This guide also 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.

The Onfido SDKs capture images or videos from applicants. For video capture, applicants must complete challenges such as reading random digits aloud and performing simple head movements. The SDKs do not perform the check.

Follow this guide to create a check composed of a Document report and a Facial Similarity Photo report using our Web SDK. You'll also learn about SDK tokens, which are JSON Web Tokens (JWTs) that are restricted to individual applicants. SDK tokens expire after 90 minutes.

You'll find more detailed information on many of the steps involved in this guide in our API reference.

Overview of steps

Web SDK Diagram

Create an applicant

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

At a minimum for Document and Facial Similarity Photo reports, you must specify the applicant's first and last names in the body of the request:

Example applicant creation request

curl https://api.onfido.com/v3/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_address = onfido.Address(
    building_number=100,
    street='Main Street',
    town='London',
    postcode='SW4 6EH',
    country='GBR'
)

applicant_details = onfido.Applicant(
    first_name='Jane',
    last_name='Doe',
    address=applicant_address
)

applicant = api_instance.create_applicant(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();
Applicant applicantDetails = new Applicant();
applicantDetails.setFirstName("Jane");
applicantDetails.setLastName("Doe");
applicantDetails.setDob(LocalDate.parse("1990-01-31"));

Address address = new Address();
address.setStreet("Main Street");
address.setTown("London");
address.setPostcode("SW4 6EH");
address.setCountry("GBR");

applicant.setAddress(address);
Applicant newApplicant = apiInstance.createApplicant(applicantDetails);
String applicantId = newApplicant.getId();

Parameters	Value
first_name	applicant's forename
last_name	applicant's surname

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/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
  }
}

Get an SDK token

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

curl https://api.onfido.com/v3/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/**"
   }' \
  -X POST
referrer = 'https://*.example.com/example_page/**'

api_instance.sdk_token.create(applicant_id: applicant_id, referrer: referrer)
const sdkToken = await onfido.sdkToken.generate({
  applicantId,
  referrer: "https://*.example.com/example_page/**"
});
sdk_token_request = onfido.SdkToken(
    applicant_id=applicant_id,
    referrer='https://*.example.com/example_page/**'
)

api_instance.generate_sdk_token(sdk_token_request)
$sdkTokenRequest = new Onfido\Model\SdkToken();

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

$apiInstance->generateSdkToken($sdkTokenRequest);
SdkToken sdkTokenRequest = new SdkToken();

sdkTokenRequest.setApplicantId(applicantId);
sdkTokenRequest.setReferrer("https://*.example.com/example_page/*");

SdkToken sdkToken = apiInstance.generateSdkToken(sdkTokenRequest);

Parameter	Notes
applicant_id (required)	Specifies the applicant for the SDK instance
referrer (required)	The referrer URL pattern

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 initialise the Web SDK.

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 JWT in case it is lost.

The referrer sent by the browser must match the referrer URL pattern in the JWT 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.

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.

Initialize the SDK

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

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

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

Read more detailed instructions about this process on GitHub.

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'
      ]
});

token (string, required) - Using the SDK token you created earlier, initialize the SDK.

containerId (string, optional) - A string containing the ID of the container element that the UI will mount to. This must be an empty element. The default is onfido-mount.

onComplete - The value of onComplete is an (optional) callback function that executes after the applicant's document and face have both been captured and uploaded successfully. For example, you could have a function which triggers a check creation on your backend server. Read about that in the following section, or in our API reference.

steps - List of different steps corresponding to parts of the process the user will be presented with. You can specify steps:

as a string (no customisation required)
as an object (when customisation is required)

welcome - Presents the introduction screen to the user.

document - The document capture step. Users will be aksed to select the document type and provide images of their selected documents, and have chance to check the image quality before confirming.

face - The face capture step. Users will be asked to capture their face in the form of a photo or a video, and have chance to check the quality of the photos or video before confirming. Defaults to the facial_similarity_photo report.

Submit the check

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

Example check submission request

curl https://api.onfido.com/v3/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;
check_data = onfido.Check()
check_data.applicant_id = applicant_id
check_data.report_names = ['document', 'facial_similarity_photo']

check = api_instance.create_check(check_data)
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();
Check checkData = new Check();

List<String> reportNames = new ArrayList<String>();
reportNames.add("document");
reportNames.add("facial_similarity{_photo}");
checkData.setReportNames(reportNames);

check.setApplicantId(applicantId);

Check newCheck = apiInstance.createCheck(check);
String checkId = newCheck.getId();
List<String> reportIds = newCheck.getReportIds();

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

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

Read more about sub results in all Facial Similarity reports and the Document report in the 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 introduction guide, a notification is sent upon completion of a check or report, or both.

Example check retrieval request

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.onfido.com/v3/checks/<CHECK_ID> \
  -H 'Authorization: Token token=YOUR_API_TOKEN'
api_instance.check.find(check_id)
const check = await onfido.check.find(checkId);
api_instance.find_check(check_id)
$apiInstance->findCheck($checkId);
Check result = apiInstance.findCheck(checkId);

Example 'list reports' request

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

curl https://api.onfido.com/v3/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_instance.list_reports(check_id)
apiInstance->listReports($checkId);
listReports result = apiInstance.listReports(checkId);

Example report retrieval request

You can return details of specific reports using their IDs:

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

api_instance.report.find(report_id)
const report = await onfido.report.find(reportId);
report_id = '<REPORT_ID>'

api_instance.find_report(report_id)
$reportId = '<REPORT_ID>';

$apiInstance->findReport($reportId);
String reportId = "<REPORT_ID>";

Report result = apiInstance.findReport(reportId);

Customising the Web SDK

Read about customising the Onfido Web SDK on GitHub.