Create a check (API)

Start here

You may find our glossary, and our guidance about getting started useful. If you're looking for quick-start guides for earlier versions of our API, please email our Client Support team.

With this guide, you'll create a check containing a Document report and a Facial Similarity Photo report.

Overview of steps

The following diagram illustrates the overall flow for a check containing a Document report and a Facial Similarity report, in an API-only integration with Onfido:

Face Check Doc Photo Diagram

This workflow will:

make sure an applicant's identity document is genuine
compare the photo on the identity document with an recent photo of the applicant to make sure it's the same person
verify that the photo is genuine and not, for example, a photo of another photo or a screen

You'll find more detailed information on all the steps involved in this guide in our API reference and specific Developer Hub guides.

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

api.applicant.create(applicant_details)
$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();

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

Upload an ID document

Get a sample document to upload

For this step, you can copy and save our sample document.

Example document upload request

Use your API token to make a request to the 'upload document' endpoint.

curl -X POST https://api.eu.onfido.com/v3.4/documents \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F 'type=passport' \
  -F 'file=@path/to/passport.png;type=image/png' \
  -F 'applicant_id=<APPLICANT_ID>' \
file = File.new('path/to/passport.png')
type = 'passport'

api_instance.document.create(applicant_id: applicant_id, file: file, type: type)
const document = await onfido.document.upload({
  applicantId,
  file: fs.createReadStream("path/to/passport.png"),
  type: "passport"
});
request_body = {"applicant_id": applicant_id, "type": "passport"}
sample_file = open("sample_document.png", "rb")

api.document.upload(sample_file, request_body)   # => Uploads a document
$type = 'passport';
$file = 'path/to/passport.png';
$side = null;

$apiInstance->uploadDocument($applicantId, $type, $file, $side);
import java.io.FileInputStream;
import java.io.InputStream;
import java.io.IOException;
import com.onfido.models.Document;

Document.Request documentRequest = Document.request()
  .applicantId(applicantId)
  .type("passport");

InputStream is = new FileInputStream("path/to/passport.png");
Document document = onfido.document.upload(is, "passport.png", documentRequest);

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<DOCUMENT_ID>",
  "created_at": "2019-02-11T13:49:20Z",
  "file_name": "sample_driving_licence.png",
  "file_type": "png",
  "file_size": 490408,
  "type": "driving_licence",
  "side": "front",
  "issuing_country": null,
  "href": "/v3.4/documents/<DOCUMENT_ID>",
  "download_href": "/v3.4/documents/<DOCUMENT_ID>/download"
}

Upload a photo

Get a sample photo to upload

For this step, you can copy and save our sample photo.

Example photo upload request

Use your API token to make a request to the 'upload photo' endpoint.

curl -X POST https://api.eu.onfido.com/v3.4/live_photos/ \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F 'applicant_id=<APPLICANT_ID>' \
  -F 'file=@path/to/sample_photo.png;type=image/png'
file = File.new('path/to/sample_photo.png')

api_instance.live_photo.create(applicant_id: applicant_id, file: file)
const livePhoto = await onfido.livePhoto.upload({
  applicantId: "<APPLICANT_ID>",
  file: fs.createReadStream("/path/to/sample_photo.png")
});
request_body = {"applicant_id": applicant_id}
sample_file = open("sample_photo.png", "rb")

api.live_photo.upload(sample_file, request_body)
$file = 'path/to/sample_photo.png';

$api_instance->uploadLivePhoto($applicantId, $file);
import com.onfido.models.LivePhoto;

LivePhoto.Request livePhotoRequest = LivePhoto.request()
  .applicantId(applicantId);

InputStream is = new FileInputStream("sample_photo.png");
LivePhoto livePhoto = onfido.livePhoto.upload(is, "sample_photo.png", livePhotoRequest);

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<LIVE_PHOTO_ID>",
  "created_at": "2019-10-09T16:59:06Z",
  "file_name": "<FILE_NAME>.png",
  "file_type": "image/png",
  "file_size": 536630,
  "href": "/v3.4/live_photos/<LIVE_PHOTO_ID>",
  "download_href": "/v3.4/live_photos/<LIVE_PHOTO_ID>/download"
}

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"]}

api.check.create(request_body)
$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.4",
  "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.

Further details on how to retrieve checks can be found in our API reference.

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