Onfido logo home page
Watch a demo
Get in touch
Arrow back Back to guides

Web SDK quick start

Start here

You may find our "General Introduction" guide useful.

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.

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

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 -X POST 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_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();
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 -X POST 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/**",
     "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);
Parameter Notes
applicant_id (required) Specifies the applicant for the SDK instance
referrer (required) The referrer URL pattern
cross_device_url (optional enterprise feature) Specifies the URL to be used for the cross device flow (Max 24 characters)

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.

The cross device flow of the Web SDK allows users to continue the identity verification process from their phone where they can take pictures of their document and themselves rather than uploading images from their desktop. The cross_device_url argument specifies the URL of the web page that the Web SDK should direct to instead of the Onfido default. This argument has a limit of 24 characters including https:// and is an 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.

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 -X POST 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;
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/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.check.find(check_id)
$apiInstance->findCheck($checkId);
import com.onfido.models.Check;

Check check = onfido.check.find(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.report.all(check_id)
apiInstance->listReports($checkId);
import com.onfido.models.Report;

List<Report> reports = onfido.report.list(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 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);

Customising the Web SDK

Read about customising the Onfido Web SDK on GitHub.