# WebSDK

# Introduction

The easiest way to start with our solution is to use our WebSDK. We put lots of efforts to improve conversion of your users and we thought about little details that make a difference. You will love WebSDK because:

• It is highly customizable (choose any steps you want, change styles or copy)
• Feature a face liveness module that improves conversion and minimizes fraud
• Adaptive design and mobile friendly
• Gives hints to users about how to better pass the flow
• Ability to continue on mobile
• Automatically refreshes when status is changed

# Integration overview

Integrating WebSDK is super easy. Here is an overview of what you should do:

• [Backend] Create an Applicant request that describes what documents your user needs to submit
• [Backend] Generate an Access token to pass it later on to WebSDK init function
• [Frontend] Include our JS script and call an init function.

Play around with WebSDK demo to get a feel of what it looks like.

# Getting started

• Test environment (used for integration and testing): https://test-api.sumsub.com
• Production environment: https://api.sumsub.com

In this guide we will not go into the details of all configuration options. See the full WebSDK demo, where you can play with different configuration options. The demo will show the full cycle of WebSDK integration, including preliminary applicant requests.

# Authentication for requests from your backend

Authentication methods to access our API with requests from your backend are described in this section.

# Generating access token

To initialize a WebSDK you must generate a temporary access token, which is also passed to the WebSDK initialization. This action must be performed on the server side. Please also pass a userId parameter, that is unique and meaningful. It can be an external user ID in your system, or an email address. Although they may be used for testing, please do not randomly generate these IDs.

# Applicant request

You should make this request from your backend to control which applicants, with which documents, you need. You should also provide your internal user ID (externalUserId) to guarantee that no more than one applicant will be created for your user.

POST /resources/accounts/-/applicantRequests

Example request:

curl -X POST \
  'https://test-api.sumsub.com/resources/accounts/-/applicantRequests' \
  -H 'Authorization: Bearer 5sV7LOpJReqUKaZNy1bC2NpZXhm+rmg4J+6Rq/cSavI8I2fdBTuOWw==' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
	"applicant": {
		"email": "",
		"requiredIdDocs": {
			"docSets": [{
				"idDocSetType": "IDENTITY",
				"types": ["ID_CARD", "PASSPORT", "DRIVERS", "RESIDENCE_PERMIT"]
			}, {
				"idDocSetType": "SELFIE",
				"types": ["SELFIE"]
			}]
		},
        // An applicant ID on the client side should be unique
		"externalUserId": "684f2102-aaeb-450e-8e4f-97898f7d7025"
	}
}'

fetch('https://test-api.sumsub.com/resources/accounts/-/applicantRequests', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer 5sV7LOpJReqUKaZNy1bC2NpZXhm+rmg4J+6Rq/cSavI8I2fdBTuOWw==',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "applicant": {
      "email": "",
      "requiredIdDocs": {
        "docSets": [{
          "idDocSetType": "IDENTITY",
          "types": ["ID_CARD", "PASSPORT", "DRIVERS", "RESIDENCE_PERMIT"]
        }, {
          "idDocSetType": "SELFIE",
          "types": ["SELFIE"]
        }]
      },
      // An applicant ID on the client side should be unique
      "externalUserId": "684f2102-aaeb-450e-8e4f-97898f7d7025"
    }
  })
});

# REQUEST HEADERS

# REQUEST ARGUMENTS

# RESPONSE

Returns the resulting JSON structure.

# Frontend integration

Include in your webpage a JS script:

<script src="{$baseUrl}/idensic/static/sumsub-kyc.js"></script>
e.g.
<!-- don't forget to change this URL when switching to the prod environment -->
<script src="https://test-api.sumsub.com/idensic/static/sumsub-kyc.js"></script>

Create a container for the WebSDK on your page, e.g.:

<!-- iframe will be inserted as a child element -->
<div id="idensic"></div>

Initialize a WebSDK:

<!-- See our demo to see which parameters are -->
<!-- passed to the iframe when selecting different options -->
<script>
  // ...
  var id = idensic.init(
    // selector of the WebSDK container (see above)
    '#idensic',
    // configuration object (see settings in the demo)
    {
      // provide your clientId (can be seen in the demo)
      clientId: 'yourClientId',
      // access token for specific externalUserId
      accessToken: 'accessToken',
      // may be some additional parameters, see the Demo to see which ones, e.g.
      externalUserId: 'someUserIdInYourSystem'
    },
    // function for the WebSDK callbacks
    function(messageType, payload) {
      // e.g. just logging the incoming messages
      console.log('[IDENSIC DEMO] Idensic message:', messageType, payload)
    }
  )
  // ...
</script>

The following parameters are passed upon initialization:

You can also find all the steps outlined in the WebSDK demo log. The WebSDK customization is pretty flexible, please, play around with the demo to get a sense of what’s possible.

# Standalone working example

Below is a fully working example. Just substitute $YOUR_CLIENT_ID, $ACCESS_TOKEN and $YOUR_USER_ID with the appropriate values (see steps above), save it to an HTML file and open it in your browser.

<html>
	<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- replace with https://api.sumsub.com/idensic/static/sumsub-kyc.js when going live -->
    <script src="https://test-api.sumsub.com/idensic/static/sumsub-kyc.js"></script>
    <title>SumSub WebSDK integration example</title>
  </head>
	<body>
    <div id="idensic"></div>
	</body>
</html>
<script>
  var id = idensic.init(
    // selector of the WebSDK container (see above)
    '#idensic',
    // configuration object (see the settings in the demo)
    {
      // provide your clientId (shown in the demo in the top left corner)
      clientId: '$YOUR_CLIENT_ID',
      // access token generated for $YOUR_USER_ID
      accessToken: '$ACCESS_TOKEN',
      // your user id for which you generated $ACCESS_TOKEN
      externalUserId: '$YOUR_USER_ID'
    },
    // function for the WebSDK callbacks
    function(messageType, payload) {
      // e.g. just logging the incoming messages
      console.log('[IDENSIC DEMO] Idensic message:', messageType, payload)
    }
  )
</script>

# WebSDK messages

# Receiving verification results

Your backend receives results via a web-hook mechanism. You can get the results via email, Slack or Telegram. But for production use we recommend setting up a web-hook endpoint that we would call when necessary:

• We need a webhook URL from you to send your results to. You can set up webhooks in developer's space at test and production environments.
• We may send several types of webhooks, but the one that is of interest to you is the one described in the "Getting verification results" section. We encourage you to carefully get accustomed to this section, since there are quite a few options for what the results may look like.
• If you want to manually check the applicant status you can always do it by this method. However, we don't recommend using polling as base method for getting verification results and rather strongly encourage the webhook mechanism. If for some reason you missed the webhooks, don't worry: we make a note of everything that was attempted to be sent, and can resend failed webhooks at any point in time. If webhook request fails we attempt to resend it four times: after 5 minutes, 1 hour, 5 and 18 hours until request succeeds. Check createdAt field of webhook payload to make sure that you're getting relevant applicant status.
• Also you can monitor webhook statuses and resend them manually on the API Health page of dashboard on test and production.

# Customization

WebSDK is flexible from the point of view of customization, you can add or change almost any text, use css, so that the webSDK was in the style of your service design.

# init

# navConf

# uiConf

# steps

Initialize a WebSDK (no effort):

<script>
  var id = idensic.init(
    '#idensic',
    {
           "clientId": "YourClientId",
           "requiredIdDocs": {
             "docSets": [
               {
                 "idDocSetType": "IDENTITY",
                 "types": [
                   "ID_CARD",
                   "PASSPORT",
                   "DRIVERS"
                 ]
               },
               {
                 "idDocSetType": "SELFIE",
                 "types": [
                   "SELFIE"
                 ]
               },
               {
                 "idDocSetType": "PROOF_OF_RESIDENCE",
                 "types": [
                   "UTILITY_BILL"
                 ]
               }
             ]
           },
           "navConf": {
             "showWelcomeScreen": true
           },
           "uiConf": {
             "customCss": "",
             "documentExamples": {
               "SELFIE":['YOUR_URL','YOUR_URL','YOUR_URL']
              },
             "steps": {
               "CREATE_APPLICANT": {
                 "instructions": "To get your account verified, please prepare your identity documents – Passport, National ID card or Driving license. Please make sure that your document is valid. To get detailed information on how to pass KYC, please read the complete guide.\n\n**Note**. Do not try to use fake documents. It will lead to the final blocking of the account.",
                 "title": "Please follow the steps after agreeing to our conditions.",
                 "agreements": [
                   "By clicking the “I Agree” button I accept [General Terms and Conditions](https://sumsub.ru/privacy-policy/)",
                   "I give my consent to process my personal data for the purposes and conditions set out in the Privacy Policy."
                 ]
               },
               "IDENTITY": {
                 "title": "Custom title for the identity step"
               },
               "SELFIE": {
                 "videoRequired": "liveness"
               },
             }
           }
        })
</script>

# Errors

# Getting the production key

# How can we get the production key?

In order to ensure the best experience for you and your users, before giving you the production key for the integration, we would like to test the flow and pass the verification as your end-user. To do so, we would kindly ask you to provide us with a link to your server.

Ensure that:

• Integration on the test environment is completed, works and meets your requirements:
  • There are no dev console errors or warnings
  • You saved our applicantIds to your database and matched your users
  • You received and successfully processed test webhooks from our side
  • You know how to correlate results received in the webhook payload with your users

# What information should be provided to obtain the production key?

Please provide us with:

• An email where we can send the production key
• A webhook URL for the production environment
• A list of countries to be excluded (Example: USA, RUS, IRL)
• From which domains you will load our WebSDK (we will whitelist them)

# Twilio integration

If you want to allow your users to send verification links via SMS to their mobile devices, you have to set it up at dashboard on production and test and make sure that target regions are enabled in your twilio account here.

# FAQ

# How can we get the applicantId?

• When a user completes a first page an applicant is created. At this moment we send webhook to your endpoint with type applicantCreated. Its payload will contain the applicantId
• GET /resources/applicants/-;externalUserId=${externalUserId}

This endpoint will return a single element list if such an applicant with a given ${externalUserId} exists and is unique. An empty list is returned if a user did not fill out the initial form. Read the id field from the returned entity to get the applicantId.

# How to enable liveness check?

To enable liveness check you should pass videoRequired:liveness setting at SELFIE step of Applicant request's requiredIdDocs.docSets.

Liveness enable example:

             "requiredIdDocs": {
               "docSets": [
                 {
                   "idDocSetType": "IDENTITY",
                   "types": [
                     "ID_CARD",
                     "PASSPORT",
                     "DRIVERS",
                     "RESIDENCE_PERMIT"
                   ]
                 },
                 {
                   "idDocSetType": "SELFIE",
                   "types": [
                     "SELFIE"
                   ],
                   "videoRequired": "liveness"
                 }
               ]
             },

# Where can I find my clientId?

Client Id is your identifier to use while initializing WebSDK. You can find at dashboard: production and test at the Client Id field.

# Migration guide from old WebSDK

We tried to make the migration process as simple as possible, but there are some differences from the previous version.

• [Backend] First of all, you need to perform an Applicant request.
• [Backend] Next, you need to generate an access token.
• [Frontend] Now you can initialize the webSDK.

We kindly ask that you generate a new access token every time you show webSDK to the end user.