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

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  = {

  token: "<OTP_TOKEN>",

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

  // Deprecated flow:
  // Here you can get the Verifai Result
  // and clear the temporary storage using the sessionID
},
  onCanceled: (sessionID) => {
    // Here your customer canceled the Verifai flow

    // Deprecated flow:
    // Clear the session using the sessionID
  }
}
// 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.

      // Deprecated flow:
      // Here you can get the Verifai Result
      // and clear the temporary storage using the sessionID.
    }}
    onCanceled={sessionID => {
      // set show prop to false in order to close the modal
      setShow(false)

      // Here your customer canceled the Verifai flow.

      // Deprecated flow:
      // Clear the session using the sessionID.
    }}
  />
}

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"

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

New API using Webhooks

info

This version of the API is not live yet, but you can already use the documentation on it to get started with implementing the Web SDK. If are already using the Web SDK, please continue with the Old API below.

Retrieving the result object via our new Verifai 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.

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

Old API (soon-to-be deprecated)

danger

This section describes the old way of getting the result and is only relevant if you already implemented the Web SDK in this way. Retrieving the result via the session ID will soon be deprecated. If you are just getting started, please refer to the section above.

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.

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