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