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



Read these guides to get started with:

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

You can also read the Onfido API reference and about integrating with our identity verification SDKs.

If you're looking for quick start guides for earlier versions of our API, 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 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

configuration = onfido.Configuration()
configuration.api_key['Authorization'] = 'token=' + '<YOUR_API_TOKEN>'
configuration.api_key_prefix['Authorization'] = 'Token'

api_instance = onfido.DefaultApi(onfido.ApiClient(configuration))
$config = Onfido\Configuration::getDefaultConfiguration();
$config->setApiKey('Authorization', 'token=' . '<YOUR_API_TOKEN>');
$config->setApiKeyPrefix('Authorization', 'Token');

$apiInstance = new Onfido\Api\DefaultApi(
package com.onfidodemo.app;

import com.onfido.*;
import com.onfido.auth.*;
import com.onfido.models.*;
import com.onfido.api.DefaultApi;
import com.onfido.ApiException;
import com.onfido.models.Applicant;

import java.time.LocalDate;
import java.io.File;
import java.util.*;

String apiKey = "<YOUR_API_TOKEN>";
ApiClient defaultClient = Configuration.getDefaultApiClient();
ApiKeyAuth tokenAuth = (ApiKeyAuth) defaultClient.getAuthentication("Token");
tokenAuth.setApiKey("token=" + apiKey);

DefaultApi apiInstance = new DefaultApi();


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.

Read more about selecting your region in our API reference.

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"]
webhook = onfido.Webhook(url='https://<URL>', events=['report.completed', 'check.completed'])

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

Webhook webhook = new Webhook();

List<String> events = new ArrayList<String>();


Webhook result = apiInstance.createWebhook(webhook);
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": [