Create a check (iOS or Android 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:
- create a check composed of a Document report and a Facial Similarity Photo report using one of our mobile SDKs
Onfido's mobile input-capture SDKs provide a drop-in set of screens and tools for iOS and Android applications to capture identity documents and selfie photos or videos for the purpose of identity verification. The SDKs do not perform the check.
This guide assumes you've already integrated with one of our mobile SDKs. If you haven't done this yet, you'll find more detailed information on the steps involved in our technical reference pages: iOS SDK reference and Android SDK reference.
Subscribing to updates
You can subscribe to updates about new features and releases for the Onfido mobile SDKs via GitHub for Android and iOS.
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 can generate a 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();
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.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, using the applicant ID you created in the previous step and your unique application ID (or "application bundle ID").
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>",
"application_id": "<YOUR_APPLICATION_ID>"
}'
api_instance.sdk_token.create(applicant_id: applicant_id, application_id: <YOUR_APPLICATION_ID>)
const sdkToken = await onfido.sdkToken.generate({
applicantId,
applicationId: "<YOUR_APPLICATION_ID>"
});
request_body = {"applicant_id": applicant_id, "application_id": "<YOUR_APPLICATION_ID>"}
api.sdk_token.create(request_body)
$sdkTokenRequest = new Onfido\Model\SdkToken();
$sdkTokenRequest->setApplicantId($applicantId);
$sdkTokenRequest->setApplicationID('<YOUR_APPLICATION_ID>');
$apiInstance->generateSdkToken($sdkTokenRequest);
SdkToken.Request sdkTokenRequest = SdkToken.request()
.applicantId(applicantId)
.applicationId("<YOUR_APPLICATION_ID>");
String sdkToken = onfido.sdkToken.generate(sdkTokenRequest);
Parameter | Notes |
---|---|
applicant_id (required) | Specifies the applicant for the SDK instance |
application_id (required) | Your application ID (for iOS: "application bundle ID") |
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 SDK.
Configure the SDK
Read about the steps to configure the mobile SDKs in our reference pages:
Start the SDK flow
Read about capturing image and video on the mobile SDKs in our reference pages:
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.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 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
HTTP/1.1 201 Created
Content-Type: application/json
{
"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 any 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 introduction guide, a notification is sent upon completion of either a check or report.
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);