VDID SDK WEB

Welcome to VDID! 🎉 By implementing Suma's service, you’ve just saved yourself hours of work. This guide will help you get started and show you how to make the most out of the tool. Let’s dive in!

Note 🚨

Starting from version 2.0.1, the default design version will be v2. If you prefer to use the previous design, you can explicitly select version v1. View more

Starting with version 2.1.3, you can configure which view the SDK will start from. This hides previous views and starts at a specific point to accommodate integrations. View more

Installation

To install vdid-sdk-web, simply run this command in your terminal:

npm install vdid-sdk-web

That’s it! You’re ready to go.

Getting Started

Setting up VDID for web verification is quick and easy. Below, you'll find step-by-step instructions and code snippets to integrate VDID into your JavaScript or TypeScript project effectively.

1. Initialize the SDK

Import and configure the SDK in your project:

import { WebVerification } from 'vdid-sdk-web'

const vdid = new WebVerification('<<public-api-key>>')

Note: The api-key must be provided by Suma México's support team. Make sure you have your unique key ready before initializing the SDK.

2. Create verification

Before starting the verification process, you must first create a verification. This step generates a uuid, which is essential for integrating with our SDK methods. The uuid allows you to begin the process to upload files and send it.

3. Start process

Once you’ve created the verification and obtained the uuid, you can use the SDK’s methods to manage the verification process. Below are examples of the available methods and their use cases:

• Start the Verification Process

  To begin the process of uploading files and sending data, use the following method:

  vdid.verifyIdentity(uuid)

  If you prefer to open a popup instead of redirecting the user, you can specify the method like this:

  vdid.verifyIdentity(uuid, { method: 'popup' })

• Sending the Verification URL by email

  To send the verification URL by email, you need to use the following method with the specified parameters, including the user's email address to which the email will be sent:

  vdid.verifyIdentityMobile(uuid, { method: 'email', email: '<<user-email>>' })

  Note: The method verifyIdentity is not required to use this method verifyIdentityMobile. This prevents users from continuing on any desktop device, displaying a message on the screen indicating that they must continue on a mobile device.

4. Additional settings

• Get the Verification URL

  To get the URL, simply use the following method as shown below:

  const url = vdid.getUrl({ uuid })

  Note: The method verifyIdentity is not required to use this method getUrl.

• Capture only images and get the URL without using the UUID

  If you want to generate a URL specifically for capturing images, use:

  const url = vdid.getUrlToOnlyCaptureImages({})

  You can also specify the type of ID being captured:

  // For two photos (e.g., front and back of an ID)
  const url = vdid.getUrlToOnlyCaptureImages({ typeId: 'id' })
  
  // For one photo (e.g., a passport)
  const url = vdid.getUrlToOnlyCaptureImages({ typeId: 'passport' });

  If you need to use the screen that allows users to select between an ID and a passport, without specifying the type of ID, you can set the typeId parameter to 'first':

  const url = vdid.getUrlToOnlyCaptureImages({ typeId: 'first' })

  If you need to customize the height of the image capture, you can specify the minHeight or maxHeight parameters:

  // Set a minimum height
  const url = vdid.getUrlToOnlyCaptureImages({ minHeight: '100vh' });
  
  // Set a maximum height
  const url = vdid.getUrlToOnlyCaptureImages({ maxHeight: '100vh' });

  Note: The method verifyIdentity is not required to use this method getUrlToOnlyCaptureImages.

• Start at a specific view

If the view to start with is not specified, the SDK will start with the welcome screen by default. It can only be configured in the verifyIdentity, verifyIdentityMobile, and getUrl methods.

The following options can be configured:

• select-document starts in the credential or passport selection view.
• capture-passport starts the view in the passport capture view.
• capture-id starts the view in the credential capture view.

# Verification
vdid.verifyIdentity(uuid, { initAt: "select-document" })

# Send Email
vdid.verifyIdentityMobile(uuid, { method: 'email', email: '<<user-email>>', initAt: "capture-passport" })

# URL
const url = vdid.getUrl({ uuid, initAt: "capture-id" })

Design version

Starting from version 2.0.1, the default design version is v2. If you need to use the previous version (v1), you must explicitly specify it.

To use a specific design version, include the version parameter:

vdid.verifyIdentity(uuid, { version: 'v1' })

For popups:

vdid.verifyIdentity(uuid, { method: 'popup', version: 'v1' })

For getting the verification URL:

const url = vdid.getUrl({ uuid, version: 'v1'})

For sending the verification URL by email:

vdid.verifyIdentityMobile(uuid, { method: 'email', email: '<<user-email>>', version: 'v1'})

For capturing images:

const url = vdid.getUrlToOnlyCaptureImages({version: 'v1'})

If you want to specify the type of ID and select the design version, you would use the following:

// For two photos
const url = vdid.getUrlToOnlyCaptureImages({ typeId: 'id', version: 'v1' })

// For one photo
const url = vdid.getUrlToOnlyCaptureImages({ typeId: 'passport', version: 'v1' });

Note: If the version parameter is not provided, the SDK will use the v2 design by default.

🚨 In version 2, customizing the height is not supported, so specifying the minHeight or maxHeight parameters will only affect version 1.

Changelog

2.1.4 - 2026-01-20

• Improved module compatibility for legacy and modern bundlers
• Added proper ESM / CommonJS resolution using exports
• Fixed Webpack 4 parsing issues with ES module syntax
• Ensured compatibility with Webpack 5, Node.js (CJS & ESM), and CRA-based projects

2.1.3 - 2025-12-01

• New optional setting to specify the initial view
• Performance and documentation optimization
• Package updates and interface improvements

2.0.1 - 2025-03-25

• Performance and documentation optimization
• Default design change from v1 to v2

2.0.0 - 2025-01-02

• Performance and documentation optimization
• Optimization in packaging construction
• A new parameter to allow selection of the design version (default v1)