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

API v3 quick start

Start here

You may find our "General Introduction", and our guidance about going live for the first time. If you have any questions, please email our Client Support team.

If you're looking for quick start guides for earlier versions of our API, please email our Client Support team.

You'll find more detailed information on all the steps involved in this guide in our API v3 reference.

Follow this guide to create a check composed of a Document report and a Facial Similarity Photo report in v3 of our API.

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

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

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.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_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();


$address = new \Onfido\Model\Address();
$address->setStreet('Main Street');
$address->setPostcode('SW4 6EH');


$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")
        .postcode("SW4 6EH")

Applicant.Request applicantRequest = Applicant.request()

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/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.onfido.com/v3/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({
  file: fs.createReadStream("path/to/passport.png"),
  type: "passport"
request_body = {"applicant_id": applicant_id, "type": "passport"}
sample_file = open("/path/to/passport.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()

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/documents/<DOCUMENT_ID>",
  "download_href": "/v3/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.onfido.com/v3/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("/path/to/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()

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/live_photos/<LIVE_PHOTO_ID>",
  "download_href": "/v3/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.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({
  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->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()
  .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": [
  "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:


If any reports have failed to pass verification, the check result is consider:


Report results

If an individual report has passed, the result is clear:


If the report has failed to pass verification, the result is 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'
const check = await onfido.check.find(checkId);
import com.onfido.models.Check;

Check check = onfido.check.find(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'
const reports = await onfido.report.list(checkId);
import com.onfido.models.Report;

List<Report> reports = onfido.report.list(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>'

const reportId = "<REPORT_ID>";

const report = await onfido.report.find(reportId);
report_id = "<REPORT_ID>"

$reportId = '<REPORT_ID>';

import com.onfido.models.Report;

String reportId = "<REPORT_ID>";

Report report = onfido.report.find(reportId);