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

iOS and Android SDK Quick Start

Start here

You may find our "General Introduction" guide useful.

This guide assumes you've already integrated with one of our mobile SDKs. If you haven't done this yet but want to read about how, read our documentation on GitHub for iOS and for Android.

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 mobile SDKs. You'll also learn about SDK tokens, which you need to use any of our SDKs (Android version 4.11.0 or later and iOS version 12.2.0 or later).

Onfido SDK tokens 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

Face Check Doc Video 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 your unique application ID (or "application bundle ID"):

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>",
     "application_id": "<YOUR_APPLICATION_ID>"
   }' \
  -X POST
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>"
});
sdk_token_request = onfido.SdkToken(
    applicant_id=applicant_id,
    application_id='<YOUR_APPLICATION_ID>'
)

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

$sdkTokenRequest->setApplicantId($applicantId);
$sdkTokenRequest->setApplicationID('<YOUR_APPLICATION_ID>');

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

sdkTokenRequest.setApplicantId(applicantId);
sdkTokenRequest.setApplicationId("<YOUR_APPLICATION_ID>");

SdkToken sdkToken = apiInstance.generateSdkToken(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.

SDK configuration

1. Configure the SDK

On GitHub, read about configuring the mobile SDKs:

2. Start the SDK flow

On GitHub, read about capturing image and video on the mobile SDKs:

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

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

Read more about sub results in all Facial Similarity reports and the Document report 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 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);