Integrating Studio for customers already using Classic

Introduction

Onfido Studio is the recommended integration path for designing, building and implementing your customer verification journeys.

This guide is designed for customers who are currently using a Classic Onfido identity verification integration with our Checks and Reports API endpoints, but are looking to integrate into Studio using Workflows and (preferably) our Smart Capture SDKs.

The guide explains the key differences and similarities between the integrations to help you identify the changes you need to make to start using Studio.

Changing your account settings

When integrating with Studio, we recommend you keep using your existing Onfido account as all of your historical verification data will still be available to take advantage of products such as Known Faces and Repeat Attempts. At the same time, all of your existing Applicant IDs will remain accessible for re-use.

Note: Studio Workflows and Classic Checks are entirely separate and independent of one another. If required, you can continue to run API-based Checks in the same account as you run Workflows, even against the same Applicant.

Once Studio has been activated for your account, your Dashboard should then include both your Classic Check-related pages, as well as Studio pages (see image below). Reach out to Support or your Customer Success Manager to set this up for you.

Classic Checks and Studio Workflows can be managed on your existing Dashboard account.

Moving from a Classic+SDK to Studio+SDK integration

Summary of changes

The table below offers a summary of the differences and similarities between Classic Check-based integrations and Workflow-based integrations using Studio. Each of these integration steps is described in more detail in the paragraphs below.

Action	Classic	Studio
Create an Applicant	Create an Applicant using the Create Applicant endpoint	Create an Applicant using the Create Applicant endpoint
Generate SDK Token	Generate an SDK Token using the SDK Token endpoint	Generate an SDK Token using the SDK Token endpoint
Initialise SDK	Each of our SDKs (iOS, Android, Web) have their own methods for configuration and initialisation in a Classic integration	In Studio, iOS, Android and Web maintain their own method of configuration, the key difference being a Workflow Run ID is passed in when the SDK is initialised
SDK callbacks	Our iOS, Android and Web SDKs have their own methods for configuring callbacks	Callbacks and error handling are handled similarly. There are some differences highlighted in the paragraphs below (iOS, Android, Web)
Customising the SDK	Each of our SDKs (iOS, Android, Web) have their own methods for customisation	There are some differences in customisations available in Studio. Reach out to Support or your Customer Success Manager for more details
Create a verification	Initiate a verification journey using the Create Check endpoint	In Studio, verification journeys are managed through workflows, initiated using the Create Workflow Run endpoint. Do not create Checks as these are not applicable or relevant in Studio
Receive webhook	Onfido offers a number of Check and Report webhook events for Classic integrations	Create a new webhook in the Dashboard and use the workflow_run.completed event. Other Workflow and Task webhook events are also available
Retrieving verification results	The results of a verification check are obtained by using the Retrieve Check endpoint and are returned in the result attribute	We recommend you use the workflow_run.completed webhook event, which contains the Workflow Run object, including the Workflow result. If you are unable to use webhooks, then use the Retrieve Workflow Run endpoint, results are returned in the status attribute
Retrieving report results and properties (such as result, sub-Result and breakdowns)	Use the Retrieve Report endpoint, results are found in the result, sub-result and breakdown attributes	The recommended guidance is dependent on the use case of Report results and properties. Find more details in the paragraphs below
Downloading media (such as Document photo, Live photos or Live videos)	Document: Make a call to the List Documents endpoint to obtain the Document IDs for a given Applicant, then use the Document ID in a call to the Download Document endpoint. The same pattern applies for the other media types: Live Photos, Live Videos and Motion Captures	Document: In Studio the Workflow Output feature can be used to obtain the Document ID for a given Workflow. This can then be used in a call to the Download Document endpoint. The same pattern applies for the other media types

The two flow charts below outline the main differences when creating identity verfication checks in Classic and Studio.

Versioning

API Versioning
In order to use Studio, you must be using API v3.4 or later. We recommend you switch to the most recent possible version when making integration changes.

SDK Versioning
The SDK version required for Studio is dependent on the Workflow you create. This is because different capture tasks can be used inside the Workflow. The Workflow Builder tool will display the required SDK versions on the right-hand side.

Onfido always recommends being on the latest version of the SDK to allow you to take full advantage of Studio's capabilities, as well as benefit from the best SDK user experience and performance.

Create an Applicant

Creating a verification capture journey begins by creating an API token and an Applicant ID. The process for doing this is identical for both Classic and Studio integrations, and documentation can be found on our API reference.

Changes to the SDK in Studio

Generate SDK Token

Studio uses the same SDK token endpoint to generate the SDK token as with Classic integration and requires the Applicant ID.

Initialising the SDK

Under a Classic integration, each SDK has its own method of initialisation, using the SDK token generated in the previous step. Once initialised, the SDK can then capture the end-user's (Applicant) document, live photos or videos, based on the steps defined in the flow configuration. For example, running the document capture step followed by a selfie video capture step. Once complete, you can then create a Check with Reports that use the captured images or videos to run any required verifications. Documentation for initialising the SDK using a Classic integration can be found here: iOS, Android, Web, React Native and Flutter.

With Studio, the key difference when initialising each SDK is that you must pass the Workflow Run ID into the initialisation code, together with the SDK token. The SDK communicates directly and dynamically with any active Studio workflows 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). This removes the need to configure any flow steps directly in the SDK as these will be included when the workflowRunId attribute is passed into the SDK initialisation code. Once the SDK steps are complete, the captured media will then be automatically passed to the relevant Reports as specified in the workflow. Documentation for initialising the SDK using a Studio integration can be found here: iOS, Android, Web, React Native and Flutter.

Note: You must never include both the Classic steps attribute and the Studio workflowRunId attribute in the same initialisation code. Classic will override Studio, resulting in an abandoned workflow status, with any captured documents and images ending up in the Classic environment.

Callbacks

Callbacks and error types are handled in largely the same way in Classic and Studio, however there are some differences.

You can access callbacks documentation for the Classic integration here: iOS, Android and Web, and likewise for the Studio integration here: iOS, Android and Web.

Note: In a Classic integration, the complete or success callback can be used to help the customer trigger the creation of a Check. In Studio, this action is no longer relevant as the Workflow will automatically handle the creation of the appropriate Reports.

Customising the SDK

Flow Customisation: Onfido Classic customers can customise the flow of an end-user's verification journey (skipping the welcome screen, for example). Many of the customisations available are described in our documentation: iOS, Android, Web. In Studio, the flow is handled by the design and configurations of the workflow. There are some differences between the flow customisations available between Classic and Studio. Please reach out to Support or your Customer Success Manager for specific details.

UI Customisation: Onfido Classic customers can customise the UI of an end-user's verification journey (such as colour and font). The customisations available are described in our documentation (iOS, Android, Web) and are also applicable for Studio integrations.

Language Localisation: Onfido Classic customers can localise the language used in the SDK experience. The customisations available are described in our documentation (iOS, Android, Web) and are also applicable for Studio integrations.

Creating a verification and retrieving verification results

Creating a verification

With a Classic integration, customers can implement verification journeys using the Checks endpoint to Create Checks.

In Studio, Checks must not be used and are not applicable. Instead, everything revolves around designing workflows and using the Workflow Runs endpoints. The process begins by making a call to Create Workflow Runs, providing the ID of the workflow in question, as well as an Applicant ID.

Retrieving verification results

Onfido Classic customers use the Retrieve Check endpoint to get the Check result.

In Studio, this is replaced by the Retrieve Workflow Run endpoint, with results found in the status attribute. Many customers use webhooks to trigger the retrieval of results, and therefore in Studio we recommend you use the workflow_run.completed webhook event to retrieve the Workflow result. In this webhook event, the resource attribute contains the Workflow Run object described above. More details on webhooks can be found in our documentation.

Getting report results and properties

In a Classic integration, the Report results, breakdowns and properties of a verification check can be obtained using the Retrieve Report endpoint. In a Studio integration, how these results are retrieved depends on how you as a customer wish to consume the data:

Building backend logic
Some customers may use the Report results, breakdowns and/or properties to build logic and orchestrate their identity verification flows in their backend. In a Classic integration, this is done using the Retrieve Report endpoint. In Studio, however, this logic is now handled within the workflow. Therefore, it is recommended to stop consuming data from the Reports endpoint as it is no longer needed.

Retrieving report data
Some customers require attributes from the Reports endpoint in order to feed into their internal systems (such as passing the extracted Document properties and sub-results into a case management system). With Studio, this can be done in the Workflow Builder by configuring Workflow output (see image below). This allows you to define any required output properties and then retrieve data via the Output object returned by the Retrieve Workflow Run endpoint.

A workflow can be configured to output specific report attributes or all attributes from the full report in a single output property. Please refer to our Studio product guide for more detailed information.

Results of a Studio workflow can be defined as Workflow Output data.

Other uses
If the recommendations above do not satisfy your retrieval needs, please reach out to Support or your Customer Success Manager.

Receiving webhooks

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

With a Classic integration, this was done by configuring Check or Report webhook events (such as check.completed or report.completed).

In Studio, the workflow_run.completed webhook event should be created from the Dashboard and used (see image below). This webhook event also contains the Workflow Run object within it and can therefore be used to retrieve the results of the workflow.

The Webhook object is documented here, and the full list of webhook events is listed here.

Studio has its own set of webhook events that can be defined in your Dashboard.

Downloading media

For customers who need to download media (such as images of captured documents or selfie photos and videos), the Classic integration offers a range of API endpoints. Using a Document ID obtained via the List Documents endpoint, a call to the Download Document endpoint will return an image of a captured document. The same pattern applies for all other Media types: Live Photos, Live Videos and Motion Captures.

For Studio, the same process can also be utilised. However, in order to retrieve the Media ID (Document ID, for example) for a given Workflow Run ID, it is recommended to use the 'Workflow Output' feature. In the image below, you can see how the document photo ID and selfie photo ID have been defined in the Workflow output. These properties will then be available to retrieve from the Retrieve Workflow Run endpoint in the output attribute. By doing so, you will be able to:

• establish which media was uploaded for each specific flow for that applicant (each applicant may go through different flows)
• differentiate between multiple media when you, for example, require different document types to be captured in the same flow (such as driving licence and passport)