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

Mobile SDK create a check diagram

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