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

API v3 Quick Start

Start here

You may find our "General Introduction" guide useful.

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

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

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 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({
  applicantId,
  file: fs.createReadStream("path/to/passport.png"),
  type: "passport"
});
sample_file = 'path/to/passport.png'
document_type = 'passport'

api_instance.upload_document(applicant_id, document_type, sample_file)
$type = 'passport';
$file = 'path/to/passport.png';
$side = null;

$apiInstance->uploadDocument($applicantId, $type, $file, $side);
String type = "passport";
String side = null;
String issuing_country = null;
File file = new File("/path/to/passport.png");

Document result = apiInstance.uploadDocument(applicantId, type, file, side, issuing_country);

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 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")
});
sample_photo = 'path/to/sample_photo.png'

api_instance.upload_live_photo(applicant_id, sample_photo)
$file = 'path/to/sample_photo.png';

$api_instance->uploadLivePhoto($applicantId, $file);
File file = new File("/path/to/sample_photo.png"); 
Boolean advancedValidation = true; 

/* advancedValidation is a required argument of #uploadLivePhoto */

LivePhoto result = apiInstance.uploadLivePhoto(applicantId, file, advancedValidation);

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