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

General introduction

Start here

If you haven't signed up with us yet, get in touch to get the right account for you.

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

Service updates

We manage a status page for providing service updates in real time. Read our guidance about subscribing to this.

We recommend you subscribe to updates as you first integrate with Onfido. If you have any questions, please email our Client Support team.


Here's a very brief and non-exhaustive introduction to some key terms in Onfido's identity verification technology.


An applicant is the individual a check is performed on.


A check is a request to carry out one or more reports on an applicant.


A report is a single verification request, such as a Document Report or Facial Similarity Photo report. A report cannot exist without a check to contain it.


Diagrammatic Overview

The Onfido API allows you to submit verification checks programmatically, and is based on REST principles. It uses standard HTTP response codes and verbs, and token-based authentication.

By default, checks have the following basic workflow:

  1. An applicant is created.
  2. Documents and images are uploaded to the applicant object (if required).
  3. A check is constructed consisting of one or more reports.

Get API tokens

There are 2 types of token: sandbox tokens for testing and live tokens to generate live requests.

Sandbox tokens

You can use the sandbox to test your technical integration with Onfido's software and to simulate API requests. You should never upload confidential information, including personal data, to the sandbox.

You should test with a sandbox token before going live. Sandbox requests return dummy responses and you won't be charged. To generate sandbox tokens:

  1. Go to your Dashboard
  2. Select Developers
  3. Select Tokens
  4. Select Generate Sandbox Tokens

Make sure you are using the correct token. All sandbox tokens start with the prefix "api_sandbox"

Read more about sandbox testing in our API reference.

Rate limits

Sandbox requests have a rate limit of 30 requests per minute. When you hit the limit, you will see an HTTP 429 - too many requests error. You cannot make further sandbox requests within the one-minute time period.

Read more about rate limits in our API reference.

Live tokens

Typically, live tokens are issued after completion and verification of integration testing.

Make sure you are using the correct token. Live tokens start with the prefix "api_live"

Read more about going live in our API reference.

Code initialization

Use the following code for initializing our API v3 Ruby, Python, PHP, Node.js or Java client libraries:

require 'onfido'

Onfido.configure do |config|
  config.api_key = <YOUR_API_TOKEN>

api_instance  = Onfido::API.new
const { Onfido, Region } = require("@onfido/api");

const onfido = new Onfido({
  apiToken: "<YOUR_API_TOKEN>",
import onfido

api = onfido.Api("<YOUR_API_TOKEN>")
$config = Onfido\Configuration::getDefaultConfiguration();
$config->setApiKey('Authorization', 'token=' . '<YOUR_API_TOKEN>');
$config->setApiKeyPrefix('Authorization', 'Token');

$apiInstance = new Onfido\Api\DefaultApi(
import com.onfido.Onfido;
import java.time.LocalDate;

import com.onfido.exceptions.ApiException;
import com.onfido.exceptions.OnfidoException;

Onfido onfido = Onfido.builder()


Throughout our documentation, the API base URL used is https://api.onfido.com/.

If you want your check data to be stored at rest exclusively in a particular region, you must use a region-specific base URL (see examples below).

Read more about regions in our API reference.

Change region to US

$ curl https://api.us.onfido.com/v3/
Onfido.configure do |config|
  config.region = 'us'
const onfido = new Onfido({
  apiToken: "<YOUR_API_TOKEN>",
  region: Region.US
$config->setHost($config->getHostFromSettings(1, array("region" => "us")));
configuration.host = configuration.get_host_from_settings(1, {'region': 'us'})
Onfido onfido = Onfido.builder()

Change region to CA

$ curl https://api.ca.onfido.com/v3/
Onfido.configure do |config|
  config.region = 'ca'
const onfido = new Onfido({
  apiToken: "<YOUR_API_TOKEN>",
  region: Region.CA
Onfido onfido = Onfido.builder()

Set up a webhook

You can set up a webhook URL to test check and report progress when following these guides. Create a temporary endpoint URL using free hosted services, such as https://webhook.site.

Read more about webhooks in our API reference.

Example webhook registration request

curl -X POST https://api.onfido.com/v3/webhooks \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F url='<URL>' \
  -F 'events[]=report.completed' \
  -F 'events[]=check.completed'
url = 'https://<URL>'

api_instance.webhook.create(url: url, events: ['report.completed', 'check.completed'])
const webhook = await onfido.webhook.create({
  url: "https://<URL>",
  events: ["report.completed", "check.completed"]
request_body = {
  "url": "https://<URL>",
  "events": [

$webhook = new \Onfido\Model\Webhook();
$webhook->setEvents(['report.completed', 'check.completed']);

import com.onfido.models.Webhook;

Webhook.Request webhookRequest = Webhook.request()
        .events("report.completed", "check.completed");

Webhook webhook = onfido.webhook.create(webhookRequest);
Parameters Value Notes
url e.g. https://webhookendpoint.url The URL that will listen to notifications (must be HTTPS)

After receiving a webhook notification, you should acknowledge success by responding with an HTTP 20x response. Otherwise, a notification will be resent several times over the next 12 hours.

Example response

HTTP/1.1 200 OK
Content-Type: application/json

  "webhooks": [
      "id": "<WEBHOOK_ID>",
      "url": "<URL>",
      "enabled": false,
      "href": "/v3/webhooks/<WEBHOOK_ID>",
      "token": "<WEBHOOK_TOKEN>",
      "environments": [
      "events": [