Developers

Start here

Smart Capture Link is a low- to no-code frontend solution complementing Onfido Studio, allowing you to verify individuals with or without engineering effort.

Rather than integrating the end-user experience into your system or application using our SDKs, Onfido hosts the verification journey on your behalf, either directly on onfido.app, or on a custom subdomain (e.g. mycompany.region.onfido.app). The Smart Capture Link is then sent to your customers, redirecting them towards the interactive steps of a workflow. All SDK operations are taken care of by Onfido, meaning you only integrate once, with no need to update to new SDK versions.

There are two ways to use Smart Capture Link:

• No-code
• Light integration

Your choice of approach will depend on a range of factors including engineering resources, user volume or the decision whether to generate a unique or generic URL. This guide will help you understand how to integrate Onfido Studio with Smart Capture Link for light and no-code integrations.

No-code integration

Overview

This approach is completely no-code. You can generate a generic, reusable Smart Capture Link for a given Workflow in Onfido Studio, send it to your users, and all workflow run outcomes will be available in your Onfido Dashboard. Anytime you want to stop end users from using the link, you can simply deactivate the currently active version of the workflow.

This approach works well for low volume use cases where you have the operational resources to manually review each workflow run result and then update your own CRM or database. The generic Smart Capture Link is not unique, so there is no automatic way for you to identify users and match them against your system.

1. Create a workflow

The process of generating a generic Smart Capture Link begins by creating a workflow using the Workflow Builder available on your Onfido Dashboard.

After you have created your workflow, copy and save the workflow_id that can be found in the Workflow Builder, as you will need it in the next steps. You must ensure the workflow is valid and activated.

Note: Unlike the light integration method, you will not be able to pass applicant or custom data into your workflow, because there is no API interaction creating a workflow run. If your workflow requires input data, you cannot generate a generic Smart Capture Link

2. Obtain a generic Smart Capture Link

Obtaining a generic link in your Onfido Dashboard is a matter of following a few simple steps:

1. Contact support to set your (custom) subdomain name
2. Navigate to Studio in your Onfido Dashboard
3. Select the workflow for which you intend to generate a Smart Capture Link
4. Click the Share Smart Capture Link button in the top right hand corner
5. Click the Copy link button

The link is generic, so you’ll only need one per workflow and it can be sent to any customer. Please ensure the workflow in question has been activated.

You can set the language of the user interface by appending the language parameter to the URL. It supports 2 character language codes (e.g. en) and 5 character locale codes (e.g. en_US). Workflow runs will default to US English if this is not specified. See here for the list of supported languages. Example: ?language=en

3. Send generic Smart Capture Link to end users

Once you have generated the generic Smart Capture Link, you can send the URL to your end users. A workflow run will start as soon as the user opens the link. The Onfido UI will load and the user completes all interactive tasks until none remain. At the same time, the Onfido backend will complete any non-interactive tasks contained in the workflow.

4. Retrieve results

To determine the outcome of workflow runs, you can do a manual check in the Results section of the Onfido Dashboard. Here, you will find a list of all completed workflow runs.

If you’re using a 3rd party integration tool, you may want to use it to receive the webhook notifications described below in the light integration approach and act accordingly. You may also want to use it to get result information from the API described below in the light integration approach, and post it in your ticketing system.

Multiple workflows

Smart Capture Links are designed so that the individual end users (applicants) receiving them can save their progress and return to complete a particular workflow at a later time.

However, no-code integrations of a generic Smart Capture Link will support multiple workflow runs when opened in separate incognito browser tabs. Each new workflow run will be treated as a separate end user, and will be subject to rate limiting.

Light integration

Overview

Our light integration approach is our low-code, scalable solution to get you off the ground quickly. It only requires a small amount of backend engineering development and allows you to generate and send a unique Smart Capture Link to each individual end user.

With the low-code integration, you can trigger the Onfido API to create a Workflow Run using a specific Applicant ID and a Workflow ID. You can then generate a unique Smart Capture URL to send to the user associated with the Applicant ID. The user will simply click this link, where they will be taken to the Onfido hosted web SDK to complete their verification journey.

Once the user has completed the workflow, your system can be configured to receive a notification using a webhook. Your system can then automatically determine the outcome of the workflow run and update the user accordingly.

If you decide to customize your UX later by integrating the end-user verification journey directly into your web or mobile apps using our SDKs, the result-handling steps will remain the same and will not need to be reimplemented.

1. Create a workflow

As with the no-code integration approach, the process begins by creating a workflow using the Workflow Builder available on your Onfido Dashboard.

Workflows are the end-user verification journeys designed in the Workflow Builder. Workflows allow you to define required end-user actions, which verifications are triggered as well as logic conditions to create fully customized verification journeys. You can use the same workflow for any number of verifications and can create multiple different workflows on your Dashboard.

After you have created your workflow, copy and save the workflow_id that can be found in the Workflow Builder, as you will need it in the following steps. You must ensure the workflow is valid and activated.

2. Create a Workflow Run and generate the Smart Capture Link

Next, create a Workflow Run using the Onfido API. At a minimum, you will need to provide the workflow ID that was saved from the previous step, as well as an applicant ID. With this applicant ID, you can pass information regarding the user to the Workflow Run by granting it access to the data stored in an Applicant object. At the same time, any business-specific data that you may have configured using the Workflow Builder can be passed to the workflow in the optional custom data object.

To configure the Smart Capture Link, you may provide data in the optional link object when making the Create Workflow Run call. This includes defining redirect URLs for when a workflow run has completed or expired, when the link will expire and what language will be used for the user’s verification journey (all attributes are optional). More detailed information regarding the links object can be found in our API reference.

Example API request using an applicant ID and the link object:

1curl -X POST https://api.eu.onfido.com/v3.5/workflow_runs \
2  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
3  -H 'Content-Type: application/json' \
4  -d '{
5  "workflow_id": "<WORKFLOW_ID>",
6  "applicant_id": "<APPLICANT_ID>",
7  "link": {
8      "completed_redirect_url": "https://example.onfido.com",
9      "expired_redirect_url": "https://example.onfido.com",
10      "expires_at": "2022-10-17T14:40:50Z",
11      "language": "en_US"
12  }
13}'

The server response returns the created Workflow Run object:

1HTTP/1.1 201 Created
2Content-Type: application/json
3
4{
5  "id": "<WORKFLOW_RUN_ID>",
6  "applicant_id": "<APPLICANT_ID>",
7  "workflow_id": "<WORKFLOW_ID>",
8  "workflow_version_id": 11,
9  "status": "approved",
10  "dashboard_url":"https://dashboard.onfido.com/results/<WORKFLOW_RUN_ID>"
11  "output": {"prop1": "val_1", "prop2": 10},
12  "reasons": ["reason_1", "reason_2"],
13  "error": null,
14  "created_at": "2022-06-28T15:39:42Z",
15  "updated_at": "2022-07-28T15:40:42Z",
16  "link": {
17      "completed_redirect_url": "https://example.onfido.com",
18      "expired_redirect_url": "https://example.onfido.com",
19      "expires_at": "2022-10-17T14:40:50Z",
20      "language": "en_US",
21      "url": "https://eu.onfido.app/l/<WORKFLOW_RUN_ID>"
22  },
23}

The url attribute of the link object in the server response is the generated Smart Capture Link, which you will need in the next step.

Note: Regardless of whether data is passed to the link object when calling the endpoint, a link object will be returned by the server in the Workflow Run object.

3. Send the Smart Capture Link to the end user

Once you have generated the Smart Capture Link, you can send the URL to your end user. As soon as they open the link, the Onfido UI will load and the user can complete all interactive tasks (such as document and selfie uploads) until none remain. At the same time, the Onfido backend will complete any non-interactive tasks contained in the workflow (such as database checks and fraud signals).

4. Get notified of completion

You can set up a webhook to send a notification to your backend upon the completion of a workflow run.

The webhook event workflow_run.completed is fired upon completion of a workflow run.

Example webhook event object payload:

1{
2  "payload": {
3    "resource_type": "workflow_run",
4    "action": "workflow_run.completed",
5    "object": {
6      "id": "<WORKFLOW_RUN_ID>",
7      "completed_at_iso8601": "2022-02-10T15:48:37.389407",
8      "href": "https://api.onfido.com/v3.5/workflow_runs/<WORKFLOW_RUN_ID>"
9    }
10  }
11}

5. Retrieve results

You can retrieve the outcome of a workflow run via the API by making a Retrieve Workflow Run call, or view the results on your Onfido Dashboard.

Example API request:

1curl -X GET https://api.eu.onfido.com/v3.5/workflow_runs/<WORkFLOW_RUN_ID> \
2  -H 'Authorization: Token token=<YOUR_API_TOKEN>'

Further details on how to retrieve workflow runs via the API can be found in our API reference.

Theme Customization

The look and feel of identity verification flows hosted using a Smart Capture Link can be customized in your Dashboard. In particular, you can customize the fonts, buttons, containers and colors of an end user's verification journey.

Theme customizations can be made using a toolbar accessible in your Dashboard. In the left hand toolbar menu, you have free reign to adjust the size, color and font family of text, as well as the background and border color of buttons and containers.

You also have the ability to co-brand the verification flow combining your logo or company name (via text) with the Onfido logo, or hide logos altogether. Logos must be provided via URL, should be in SVG or PNG format, and equal to or greater than 144px by 32px.

Please be aware that the logo/co-branding feature for the Smart Capture Link must first be enabled for your account. You can do this by reaching out to your CSM or emailing Onfido's Customer Support.

The Smart Capture Link theme toolbar on your Dashboard

The Dashboard toolbar also allows you to preview your customizations, or reset all parameters to their default values.

If there is a theming element that you intend to change beyond what is available, get in touch with your account manager.

Please note: The toolbar preview is merely an example of the Welcome and Document Review screens of the verification flow, not an exact replica of the SDK user interface. If you want to see the real changes, click Publish in the toolbar to save the configuration, then preview with a specific workflow.

Scope of theme customizations

The tables below outline the specific areas that can be customized for Smart Capture Link workflows:

Typography

*If you're using a scalable font size unit such as em/rem, the SDK's base font size is 16px. This is currently not customizable.

Container

Buttons

Logos

Smart Capture Link theming offers a co-branding feature, where you can include your company name (via text) or logo, together with the Onfido logo. Alternatively, you can remove all logos completely from the UI. There is no option available to display your company name or logo only.

As previously stated, the logo/co-branding feature for the Smart Capture Link must first be enabled for your account. You can do this by reaching out to your CSM or emailing Onfido's Customer Support.

Logos must be provided via URL, should be in SVG or PNG format, and equal to or greater than 144px by 32px.

In the Smart Capture Link theming toolbar, you will be presented with two logo variations; Logo URL and Logo URL (camera screens). The former is for displaying logos in a standard format, while the latter requires a logo with inverted colors for better display on the black background of the camera image capture screen (see screenshot examples below).

A standard logo display

An inverted logo display on the camera capture screen

Accessibility requirements

Onfido's default SDK settings are compliant with the World Wide Web Consortium's Web Content Accessibility Guidelines (WCAG) 2.1 AA standards.

If your Smart Capture Link customizations make changes to any default colors or contrast, please ensure they adhere to WCAG guidelines.

Rate Limiting

Generic Smart Capture Links have a rate limit of 100 requests per 5 minutes per IP address. This helps mitigate the risks associated with an end user sharing the generic link.