Quick start guide: create an identity verification

Start here

This quick start guide walks you through the steps required to create a simple identity verification, running a Document report and a Facial Similarity Photo report on an applicant. The processes described below are foundational to any identity verification using Onfido and can be adapted to construct more complex verification flows at scale.

Please note: This guide assumes you're using API v3.4 or higher.

Overview of steps

The following flowchart offers a high-level illustration of the steps required to create a verification check using Onfido Studio and our SDKs, running a Document report and a Facial Similarity Photo report.

Step one: Generate an API token

To start your integration, you will need an API token. Onfido makes use of two types of token: sandbox tokens and live tokens.

Sandbox tokens are used to test your technical integration and simulate API requests before promoting your integration to production. Sandbox requests return templated responses and won't be charged to your account.

Live tokens are used to generate live requests in your production environment.

To generate API tokens:

1. Go to your Dashboard
2. Select Developers
3. Select Tokens
4. Select Generate API Token
5. Select Sandbox or Live from the popup modal
6. Click Generate

Make sure you are using the correct API token. Sandbox tokens start with the prefix "apisandbox", while live tokens have the prefix "apilive".

Please note: You should never upload confidential information, including personal data, to the sandbox environment.

You can read more about API tokens in our API reference.

Billing information

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

You can read more about token security and rotation in our API documentation.

Rate limits

Onfido's API enforces a maximum volume of requests per second for all clients, with different rate limits applied to our sandbox and live environments. You can read more about rate limits in our API documentation.

Step two: Build a Studio workflow

The next step in creating an identity verification is to construct a Studio workflow in the Workflow Builder.

A basic example workflow, including a Document Capture task, a Document Report task, a Face Capture: Photo task and a Facial Similarity Report (photo) task, is illustrated below:

Once constructed, copy and store the workflow ID of the valid and active workflow, as you will need it in a later step.

You can read more about using the Workflow Builder and workflow tasks in our Studio product guide.

Step three: Create an applicant

Now you're ready to create an applicant from your backend server, using a valid API token. You only need to do this once per user.

You may wish to provide user attributes that you have already collected in the body of the Create applicant API request. For example, Document and Facial Similarity Photo reports require first and last name.

An example applicant creation request is provided below:

curl -X POST https://api.eu.onfido.com/v3.6/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"
  }
}'

The server's response will contain an id attribute (the applicant ID), which you'll need in the following steps. Store this ID against your user for future use.

An example of the server response is provided below:

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.6/applicants/<APPLICANT_ID>",
  "id_numbers": [],
  "phone_number": "+44 7911 123456",
  "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
  },
  "location": {
    "ip_address": "127.0.0.1",
    "country_of_residence": "GBR"
  }
}

You can read more about applicants and their creation in our API reference documentation.

Step four: Create a workflow run

With a valid and active workflow in place, you will then need to create a workflow run by making a call to the Onfido API. At a minimum, you will need to provide a workflow ID (which you copied and stored from your Studio Dashboard), as well as the applicant ID created in the previous step.

The server will return a workflow run object, with a workflow run ID contained in the response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "<WORKFLOW_RUN_ID>",
  "applicant_id": "<APPLICANT_ID>",
  "workflow_id": "<WORKFLOW_ID>",
  "workflow_version_id": 11,
  "status": "approved",
  "dashboard_url":"https://dashboard.onfido.com/results/<WORKFLOW_RUN_ID>"
  "output": {"prop1": "val_1", "prop2": 10},
  "reasons": ["reason_1", "reason_2"],
  "error": null,
  "created_at": "2022-06-28T15:39:42Z",
  "updated_at": "2022-07-28T15:40:42Z",
  "link": {
      "completed_redirect_url": "https://example.onfido.com",
      "expired_redirect_url": "https://example.onfido.com",
      "expires_at": "2022-10-17T14:40:50Z",
      "language": "en_US",
      "url": "https://eu.onfido.app/l/<WORKFLOW_RUN_ID>"
  },
}

Once again, you'll need to store the workflow run ID as you will need it later to configure and initialize the SDK.

You can read more about Studio workflows and creating a workflow run in our API reference documentation and Studio product guide.

Step five: Generate an SDK token

At this stage, you can generate an SDK token by making a call to the Onfido API, providing the applicant ID you created in a previous step, together with either your application_id (for iOS and Android SDKs) or a referrer (for the Web SDK).

curl -X POST https://api.eu.onfido.com/v3.6/sdk_token \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
     "applicant_id": "<APPLICANT_ID>",
     "referrer": "https://*.example.com/example_page/*",
     "cross_device_url": "https://example.com"
   }'

Each authenticated instance of the SDK will correspond to a single Onfido applicant. You'll need to generate and include a new SDK token each time you initialize the SDK. SDK tokens expire after 90 minutes. If creating a new SDK token for a returning applicant, for example to resume an incomplete verification journey, then use their existing applicant ID.

Step six: Configure and initialize the SDK

The method required to configure and initialize the SDK will depend on which SDK you are using (iOS, Android, Web, React Native or Flutter), as each one works in a slightly different way.

After adding the platform-specific SDK dependencies, you initialize the SDK by passing a workflow run ID into the configuration code, together with an SDK token. The SDK communicates directly and dynamically with any active Studio workflow you have built for your verification flows, displaying the relevant screens to ensure the correct capture and upload of end-user information (such as identity documents, live photos and videos).

If you need to re-initialize the SDK for an applicant who has left the flow and returned later, use the same workflow run ID to allow them to continue where they left off, providing it has not timed out into an abandoned status.

Once all capture steps are complete, the captured media will then be automatically passed to the relevant Reports as specified in the workflow. In our example, a Document report and a Facial Similarity Photo report.

Documentation for configuring, initializing and customizing the SDK for each platform can be found here: iOS, Android, Web, React Native and Flutter.

Step seven: Receiving webhooks

Onfido provides webhooks to alert you of changes in the status of your verifications.

From your Dashboard, first click on Developers, then click on the Webhooks tab, then press the Create webhook button. In the popup, you can choose which webhook events you wish to use (including workflow_run.started, workflow_run.completed, and workflow_task.completed), specify the URL the webhook events should be sent to and which environment you intend to use (sandbox, live or both).

You can also register webhooks programmatically using the Onfido API.

More detailed documentation about webhooks can be found in our API reference.

Step eight: Retrieving verification results

The status and results of the identity verification check can be found in the Results tab of your Studio Dashboard.

Alternatively, the results can be obtained programmatically by retrieving the workflow run, making a call to the Onfido API. The server returns a workflow run object, with results found in the status attribute. Possible status values include:

• awaiting_input
• processing
• abandoned
• error
• approved
• review
• declined

Any reasons that have been defined for specific workflow outcomes can also be found in the workflow run object.

Specific attributes from any reports contained in a workflow run (such as Document report properties, results and sub-results) can be defined as workflow output data when constructing the workflow. All output properties can be found in the output object returned in the workflow run object.

Results breakdown

Successful responses contain an overall result for the verification check as well as individual results for each report. The result of a verification check is derived from the results of the individual reports that it contains.

Verification check result

If all the reports have passed verification, the check result is clear.

If any reports have failed to pass verification, the check result is consider.

Report results

If an individual report has passed, its result is clear.

If the report has failed to pass verification, the result is consider.

Document Report sub results

Note that if a Document report has been conducted sub-results will also be provided to give a more detailed description of the report result.

You can read about results and sub-results in our API reference.

Uploading media directly to Studio via API

Onfido highly recommends integration using our Smart Capture SDKs for the capture and uploading of document photos and live selfies of applicants. Our advanced image detection technology ensures the quality of the captured images meets the requirement of Onfido's identity verification process, guaranteeing the best success rate.

However, Onfido can facilitate the upload of document photos and live selfies via API as an alternative.

To upload a photo of a document, make a call to the Upload document endpoint, including the applicant ID, the file path and document type (such as passport). The server returns a document object. You will need to maintain a record of the array of document IDs for a given applicant as you will need to specify this on workflow creation - see below for further details.

To upload a live photo of an applicant, make a call to the Upload live photo endpoint, including the applicant ID and the file path. The server returns a live photo object. You will need to maintain a record of the photo ID for a given applicant as you will need to specify this on workflow creation - see below for further details.

Valid file formats for documents and live photos are jpg, png and pdf. The file size must be between 32KB and 10MB. Maximum supported resolution is 64MPx.

In Studio, you need to define the document or live photo IDs in the Workflow Input modal. This can be found via the kebab button in the top right hand corner of the Studio canvas. Give the property a name and in the format drop down select the appropriate photo ID from the Media group. On Workflow Run creation you will need to then pass the specific array of Document IDs into the property you have defined using the ‘customer data’ parameter. You can apply the same approach if you have also defined a property for the photo ID.

This property can then be used as an input into your Document Report task or Facial Similarity Report task.

Please note: Live videos and motion captures can only be uploaded via one of Onfido's Smart Capture SDKs, not via the API directly. As a result, Onfido does not provide an upload live video or upload motion capture endpoint.

A few things to consider before 'production'

Privacy best practices

We've marked in our guides and 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 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.6/
• US (US): https://api.us.onfido.com/v3.6/
• Canada (CA): https://api.ca.onfido.com/v3.6/

You can read more about regions in our API reference.

Status page

Onfido manages a status page to keep customers updated on any ongoing incidents affecting our service.

We recommend you subscribe to status updates when 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