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

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

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.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": [
    "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/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.

Region

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'
end
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()
                .apiToken(<YOUR_API_TOKEN_HERE>)
                .regionUS()
                .build();

Change region to CA

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

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

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(
  null,
  $config
);
import com.onfido.Onfido;
import java.time.LocalDate;

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

Onfido onfido = Onfido.builder()
        .apiToken("<YOUR_API_TOKEN>")
        .build();
Onfido

Our Solutions

Onfido uses 256-bit SSL encryption 100% of the time on every device.

BSI ISO/IEC27001

Onfido has been certified by BSI to ISO 27001 under certificate number IS 660122.

© Onfido™, 2020. All rights reserved.
Company Registration Number: 07479524.