Getting started

This section will describe how to get set up and running as quickly as possible with the Verifai Web SDK.

Prerequisites

There are a few things you need. We will help you with all

• A web application to integrate the Verifai front-end with.
• Basic knowledge about JavaScript and/or React.
• Knowledge about implementing endpoints in your web applications.
• Your Verifai API key from the Verifai Dashboard.
• Optionally: a handover URL.
• Optionally: a webhook URL. (We will go into detail about both later.)

Installation

Getting and setting the license

We assume you already have an account at our dashboard. If not, please create an account.

To subscribe to our SaaS solution you will need to follow the next steps:

1. Click on "Your solutions" in the top bar.
2. Manage the solution you want to group the Web SDK in or create a new solution.
3. Click the "Add implementation" button and select the Web SDK.
4. Now you can reveal your API key.

tip

Please handle your API key responsibly, as that is what will allow you to start new Verifai processes for your customers.

Obtain the OTP

To initialize your Verifai frontend you need an OTP endpoint in your back-end. The OTP can only be retrieved with the API token obtained from the Verifai Dashboard.

Below, an example is shown on how you could retrieve the OTP from the Verifai back-end. From your back-end, you need to supply your front-end with the Verifai OTP.

You can find more detailed information on the public endpoints here.

cURL

curl -X POST -H "Authorization: Bearer <API_TOKEN>" -H "Content-Type: application/json" -d '{
  "document_type_whitelist": ["P", "I"],
  "handover_base_url": "<HANDOVER_URL>?s=",
  "locale": "en_US"
}' "https://websdk.verifai.com/v1/auth/token"

Python

import json
import requests

api_token = '<YOUR API KEY>'
endpoint = 'https://websdk.verifai.com/v1/auth/token'
handover_base_url = '<YOUR HANDOVER URL>'

data = {
  'document_type_whitelist': ['P', 'I'],
  'handover_base_url': f'{handover_base_url}?s=',
  'locale': 'en_US'
}

headers = {
  'Authorization': f'Bearer {api_token}'
}

response = requests.post(endpoint, json=data, headers=headers)

note

Notice the '?s=' suffix of the handover_base_url

danger

Do not expose your API key to your front-end. This token is a secret and should not be exposed on a public channel.

Implementing the SDK

note

Currently the Web SDK does not support server-side rendering (SSR). To get it working with a framework (e.g. Next.js) that offers such a feature you might have to disable SSR.

With the OTP we can start implementing the front-end. The Verifai front-end consists of two flows.

1. The main flow, to be implemented on your main web page.
2. An optional handover flow, to be implemented on a separate web page.

More information about the flows is explained here.

The main flow is the part that should be implemented in your web application.

Javascript

Install the Verifai WebSDK

# Npm
npm install @verifai/websdk --save

# Yarn
yarn add @verifai/websdk

HTML

<div id="verifai-mount"></div>

Javascript (Module)

import WebSDK from '@verifai/websdk'

const config  = {
  // For more information on the token look at: https://docs.verifai.com/api/web-api/auth/token
  token: '<OTP_TOKEN>',

  onSuccess: (sessionID) => {
    // Handle the successful scan any way you want, e.g. redirect the user.
  },

  onCanceled: (sessionID) => {
    // Here your customer canceled the Verifai flow
  }
}

// Get the element Verifai should be mounted on
const verifaiElement = document.getElementById('verifai-mount')

// Create a WebSDK object
const webSDK = new WebSDK(config, verifaiElement)

// Start the SDK
webSDK.start()

React

Install the Verifai WebSDK

# NPM
npm install @verifai/websdk-react --save

# Yarn
yarn add @verifai/websdk-react

import React, { useState } from 'react'
import WebSDK from '@verifai/websdk-react'

export default function MyComponent() {
  const [show, setShow] = useState(true)

  return <WebSDK
    // For more information on the token look at: https://docs.verifai.com/api/web-api/auth/token
    token="<OTP_TOKEN>"

    // You can manipulate the show prop to show and hide the modal.
    show={show}

    onSuccess={sessionID => {
      // Set show prop to false in order to close the modal
      setShow(false)

      // Handle the successful scan any way you want, e.g. redirect the user.
    }}

    onCanceled={sessionID => {
      // Set show prop to false in order to close the modal
      setShow(false)

      // Here your customer canceled the Verifai flow.
    }}
  />
}

Configuration

We define multiple configuration possibilities for the Web SDK, however only one property is required:

Key	Type	Description
token	str	The OTP token

All other configuration properties can be found in the customization section.

Implement the Verifai Handover Flow

The handover flow is only available when you set phone as the uploadType in the SDK.

As mentioned here you need a separate web page for the handover flow. If you already implemented the Verifai main flow the handover is more of the same.

The only difference is that the handover flow does not need an OTP because authorization is handled through the URL. Other than that the config/props are the same for the Handover as for the WebSDK.

Javascript

HTML

<div id="verifai-mount"></div>

Javascript (Module)

import { Handover } from '@verifai/websdk'

// See the code above for an example config
const config = {...}

// Get the element Verifai should be mounted on
const verifaiElement = document.getElementById('verifai-mount')

// Create a Handover object
const handover = new Handover(config, verifaiElement)

// Start the Handover
handover.start()

React

import { Handover } from '@verifai/websdk-react'

export default function MyComponent() {
  return <Handover />
}

Processing the result

Verifai Result API using Webhooks

info

This is the newer method of retrieving the Verifai result. If are already using the Web SDK with the old API, please continue with the Old Web SDK API below.

Retrieving the result object via our API requires you to provide us with a webhook that we can call in order to notify you when the result object has been generated. To get started, please read the docs on the Verifai API.

Action	Endpoint	Method
Get Result	api.verifai.com/v1/profile/<profile_uuid>/result	GET

Old Web SDK API

danger

This section covers the old way of retrieving the Verifai result. It will continue to be supported for the foreseeable future. New customer? Proceed to Verifai API.

The Verifai result can be retrieved as soon as the onSuccess callback is triggered once the user successfully passes through the process. If the user cancels the process early, then the onCanceled callback is called.

onSuccess callback

The onSuccess callback is triggered when the user successfully ends the Verifai flow. At this point, the Verifai flow is closed and the callback is called with a sessionId. Important is to set the show value to false to close the flow correctly.

With the returned sessionId you need to do two things:

1. Get the Verifai result.
2. Clear the session data stored at Verifai.

You can achieve these by calling the Verifai back-end from your back-end with the following endpoints:

Action	Endpoint	Method	API Link
Get Result	v1/session/<session_id>/verifai-result?image_result=	GET	link
Delete Session Data	v1/session/<session_id>	DELETE	link

Do not forget to delete the session data as well. Due to our data retention policy, we limit the amount of time the verification result is stored on our servers. After deleting the session data, you are responsible for storing the data on your servers.

onCanceled callback

The onCanceled callback is called when the user has canceled the Verifai flow. At this point, the Verifai flow is closed and the callback is called with a sessionId. You need to remove this session from the Verifai back-end equivalent to the onSuccess callback. However, there is no Verifai result to handle in this case.

You can achieve this removal with the same call in the onSuccess callback to the Verifai back-end:

Action	Endpoint	Method	API Link
Delete Session Data	v1/session/<session_id>	DELETE	link

info

More information about the processing the result can be found in the results section.

onError callback

The onError callback is called whenever an error occurs in the Web SDK. In general only application errors trigger this function (e.g. expired JWT). The type of the error can be read from the error's type property. Below is a list of the currently defined error types and their description.

Type	Description
jwtExpired	Access token (JWT) is expired. New one should be generated
cropFailed	Something went wrong while posting the (cropped) image

Data retention

Our goal is to minimize the data retention period. Therefore, we request that you delete the session data immediately after retrieving it. If the session data is not deleted, it will be automatically deleted after 7 days. Please note that this cannot be undone.

Next steps

With the handover in place, you have reached the end of the getting started section. If everything went well you should have a functioning Web SDK. If you have any questions you can always contact our support.

We recommend the following next steps if you want to get to know our Web SDK in more detail:

• Components
• Customization
• Web SDK Backend API

info

For the old version of the API, please have a look here