Get started integrating

Start here

We recommend you read this guide to:

help us make your initial integration and testing experience as smooth as possible
provide guidance on going live for the first time

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 templated responses and you won't be charged. To generate sandbox tokens:

Go to your Dashboard
Select Developers
Select Tokens
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.

Live tokens

Typically, live tokens are issued after completion and verification of integration testing. You can generate live API tokens on the ‘Tokens’ page of your Onfido Dashboard.

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

Make sure to update your production system to use the live token.

Billing information

Live checks cannot be requested without valid billing information, so please add billing information to your account in your Onfido Dashboard.

Token security

You must never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server.

We highly recommend that you rotate live API tokens when staff members with access to those tokens leave your organisation. You could consider creating a leaver’s process which covers this.

Read more about token security and rotation in the API documentation.

Rate limits

Unless contractually agreed otherwise, the maximum rate in production is 400 requests per minute.

To lower the possibility you'll be rate-limited, we recommend:

running non essential or routine batch API jobs outside your peak hours
throttling batch jobs
implementing an exponential back-off approach for requests essential to your verification process, with an initial delay of 30 seconds
prioritising requests that are essential to verify an active user
setting up monitors and alerts for error responses on our API

Sandbox 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.

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.eu.onfido.com/v3.4/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": [
    "report.completed",
    "check.completed"
  ]
}

api.webhook.create(request_body)
$webhook = new \Onfido\Model\Webhook();
$webhook->setUrl('https://<URL>');
$webhook->setEvents(['report.completed', 'check.completed']);

$apiInstance->createWebhook($webhook);
import com.onfido.models.Webhook;

Webhook.Request webhookRequest = Webhook.request()
        .url("https://<URL>")
        .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)

Webhook retry mechanism

Upon receiving a webhook notification, you should acknowledge success by responding with an HTTP 20x response within 10 seconds. Otherwise, we will attempt to resend the notification 5 times according to the following schedule:

30 seconds after the first attempt
2 minutes after the first attempt
15 minutes after the first attempt
2 hours after the first attempt
10 hours after the first attempt

We also use circuit breaking for webhooks: if any 5 requests to the same webhook fail in a row, then that webhook will be disabled for one minute.

Example response

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

{
  "webhooks": [
    {
      "id": "<WEBHOOK_ID>",
      "url": "<URL>",
      "enabled": false,
      "href": "/v3.4/webhooks/<WEBHOOK_ID>",
      "token": "<WEBHOOK_TOKEN>",
      "environments": [
        "sandbox"
      ],
      "events": [
        "report.completed",
        "check.completed
      ]
    }
  ]
}

Update webhook endpoints

Make sure to update webhook endpoints to handle live check/report status update events.

Status page

We manage a status page to keep our customers updated on any ongoing incidents affecting our service.

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

You can select the option to "subscribe to updates" to get real-time updates via:

email
text message (SMS)
webhooks
Atom or RSS feed

Privacy best practices

We've marked in our API documentation the points where you'll either send personal data to Onfido, or process biometric personal data yourself. For example, if you're integrating to use one of our Facial Similarity reports.

Always make sure you inform your users about this, obtain any necessary permissions, and take steps to ensure that you are meeting your other obligations under applicable data privacy laws.

For more information on how Onfido uses personal data, view our Privacy Policy.

Code initialization with regions

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

You must also use a region-specific base URL from API v3.1 onwards. These are:

Europe (EU): https://api.eu.onfido.com/v3.4/
US (US): https://api.us.onfido.com/v3.4/
Canada (CA): https://api.ca.onfido.com/v3.4/

Use the following examples to see how to initialize our official client libraries in the EU region, and read more about regions in our API reference.

Initialization in EU region

$ curl https://api.eu.onfido.com/v3.4/
onfido = Onfido::API.new(
  api_key: ENV['ONFIDO_API_KEY'],
  # Supports :eu, :us and :ca. Previously defaulted to :eu.
  region: :eu
)
const onfido = new Onfido({
  apiToken: "<YOUR_API_TOKEN>",
  // Supports Region.EU, Region.US and Region.CA. Previously defaulted to Region.EU.
  region: Region.EU
});
api = onfido.Api(
  "<YOUR_API_TOKEN>",
  # Supports Region.EU, Region.US and Region.CA. Previously defaulted to Region.EU.
  region=Region.EU
)
Onfido onfido = Onfido.builder()
                .apiToken(<YOUR_API_TOKEN>)
                // Supports regionEU(), regionUS() and regionCA(). Previously defaulted to regionEU().
                .regionEU()
                .build();