NAV

Introduction

Welcome to the Veriff documentation. This documentation will help you get started with Veriff. If you have any questions you can use Intercom on the bottom of the page or support@veriff.com to get in contact with us.

Test the API Collection in Postman

It is possible to test the Veriff API v1.0 Collection in Postman. Click on the button below to get started.

Try in Postman ▸

Getting started with Veriff

Signing up

Fill-in the form at veriff.com [🡕] and a confirmation e-mail with further instructions is sent to you.

Logging in

To log in to Veriff's environment, please use the link sent in the confirmation email and follow instructions.

Once you have logged in and wish to create new users for other members of your team, navigate to the Team page. You must have the Administrator rights to do it.

How to find your API key and the shared secret key

These are stored in the Veriff's environment (aka Veriff Station), please log in via the link sent to you in the sign-up email.

Choose the Integrations page in the top-bar menu. Next, choose the integration you need from the page that opens, and click on the integration name to open it.

Once you open an integration, you'll see the API key and the shared secret key (the latter is your API secret).

There are two types of integrations that can be created in the environment:

Sessions Lifecycle

Sessions Lifecycle

Generating verification with Veriff

Generating sessions manually

To generate a verification:

Generating sessions in code

{
    "verification": {
        "callback": "https://veriff.com",
        "person": {
            "firstName": "John",
            "lastName": "Smith"
        },
        "document": {
            "type": "PASSPORT",
            "country": "EE"
        },
        "vendorData": "unique id of an end-user"
    }
}

The simplest way to get a verification link for web verification flow is to create JSON object containing the end-user's name and the callbackURL (aka redirectURL) to which the end-user will be sent after completing the web verification flow (usually it is "Thank you" or "Waiting" page on your side). Then use HTTP POST to send the object to https://<Base-URL>/v1/sessions, with Content-Type application/json and the X-AUTH-CLIENT header containing your API key.

In response, a JSON session ID and a URL will be sent as follows:

{
    "status": "success",
    "verification":{
        "id":"f04bdb47-d3be-4b28-b028-............",
        "url": "https://alchemy.veriff.com/v/sample-url.................",
        "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJh............",
        "baseUrl": "https://alchemy.veriff.com"
    }
}

The URL of the verification session is where end-user should be redirected on web.

The sessionID should be saved on your end - you can tie back the webhook responses to your end-user record that way.

The sessionToken is a JSON web token that consists of HS256 encrypted session ID and session creation timestamp. It will expire in 7 days. Note that you should always use the variable max length type for the sessionToken and not define it. If absolutely needed, you can set the length to max value: 4096 characters.

Once the end-user completes the verification flow, they will be redirected to the callbackURL. If the callbackURL is not specified for the session, the end-user will be redirected to Integration's default callbackURL, which can be set up in Veriff Station. It is important to note, that the callbackURL does not contain any decision or verification information yet.

Receiving decisions

There are 3 options to fetch decisions for a verification session:

Signing requests with the X-HMAC-SIGNATURE

The X-HMAC-SIGNATURE guarantees to us, that API calls are initiated by you. It is based on the shared secret key that is known only by you and Veriff.

X-HMAC-SIGNATURE is a special header which value is a signature generated using HMAC method.

To generate the value you need to generate a keyed hash value using your shared secret key with the HMAC-SHA256 function.

Try our demos

Web

To try out the end-user facing verification flow, navigate to Veriff Demo [🡕] - this will start the verification flow in your browser.

Mobile SDKs

Our mobile applications can be tested by downloading the demo versions: iOS / Android [🡕]

Review Verifications

To review the submitted verification and its results, visit Veriff Station and open the individual verification session to see the details.

Supported Browsers for verification flow

Desktop

In addition to the listed browsers other Chromium based browsers may work.

iOS

Android

In addition to the listed browsers other Chromium based browsers may work.

Not supported browsers

A list of browsers which are not supported currently and that we can not support unless there are browser side changes implemented by the browser provider:

Android

iOS

Integrations

Before you can launch the verification flow you'll need a sessionUrl.
See our documentation on generating one. sessionUrl should be unique for each call.

Android SDK integration

Android SDK Requirements

Please check the migration guides below if you need any guidance for updating these dependencies.

Adding the Android SDK

Open the root build.gradle file and add a new maven destination to the repositories in the allprojects section:

allprojects {
    repositories {
        maven { url "https://cdn.veriff.me/android/" }
        google()
        mavenCentral()
    }
}

Alternatively, when using Gradle 7+, add the Maven repository to your settings.gradle file:

dependencyResolutionManagement {
    repositories {
        maven { url "https://cdn.veriff.me/android/" }
        google()
        mavenCentral()
    }
}

Add the Veriff SDK dependency to the application build.gradle file:

implementation 'com.veriff:veriff-library:6.+'

Permissions

The SDK will request all the permissions it needs, please make sure that the CAMERA, RECORD_AUDIO permissions are not explicitly removed using tools:node="remove" in your app`s manifest file. Ignore this if you are not explicitly removing any permissions.

Starting the verification flow

The verification flow must be launched from the vendor Activity class with a unique session. A session is valid for 7 days and expires automatically after that.

import com.veriff.Sdk;

Intent intent = Sdk.createLaunchIntent(activity, sessionUrl);
startActivityForResult(intent, REQUEST_CODE);

Parameters are defined as below;

Parameters Description
sessionUrl Required parameter. sessionUrl can be received from your backend implementation. sessionUrl should be unique for each call. Check /sessions endpoint in the API documentation here to learn how to generate one.
REQUEST_CODE Define an integer constant REQUEST_CODE in your activity which can be used to compare in onActivityResult

Customizing the SDK

Setting a theme (Optional)

You can customize the look and feel of the SDK flow by passing a Branding object via Configuration to createLaunchIntent as shown in the example below.

Branding branding = new Branding.Builder()
        .logo(R.drawable.logo)
        // Screen and dialog background color
        .background(getResources().getColor(R.color.background_color))
        // Non-surface content (such as text, icons) displayed on `background`.
        // Accessibility: Must have a contrast ratio of at least 4.5:1 vs `background`
        .onBackground(getResources().getColor(R.color.on_background_color))
        // Secondary non-surface content (such as text) displayed on `background`.
        // Accessibility: Must have a contrast ratio of at least 4.5:1 vs `background`
        .onBackgroundSecondary(getResources().getColor(R.color.on_background_secondary_color))
        // Tertiary non-surface content (such as text) displayed on `background`.
        // Accessibility: Must have a contrast ratio of at least 4.5:1 vs `background`
        .onBackgroundTertiary(getResources().getColor(R.color.on_background_tertiary_color))
        // Primary surfaces (such as buttons) displayed on `background`.
        // Accessibility: Must have a contrast ratio of at least 3:1 vs `background`
        .primary(getResources().getColor(R.color.primary_color))
        // Non-surface content (such as text) displayed on `primary` surfaces.
        // Accessibility: Must have a contrast ratio of at least 4.5:1 vs `primary`
        .onPrimary(getResources().getColor(R.color.on_primary_color))
        // Secondary surfaces (such as bullet points and illustrations) displayed on `background`.
        // Accessibility: Must have a contrast ratio of at least 3:1 vs `background`
        .secondary(getResources().getColor(R.color.secondary_color))
        // Non-surface content (such as text) displayed on `secondary` surfaces.
        // Accessibility: Must have a contrast ratio of at least 4.5:1 vs `secondary`
        .onSecondary(getResources().getColor(R.color.on_secondary_color))
        // Backgroung color of the overlay area on all the screens with camera
        .cameraOverlay(getResources().getColor(R.color.camera_overlay_color))
        // All UI elements on all the screens with camera on top of camera overlay
        // Accessibility: Must have a contrast ratio of at least 4.5:1 vs `cameraOverlay`
        .onCameraOverlay(getResources().getColor(R.color.on_camera_overlay_color))
        // Color used for various outlines and boundaries of UI elements
        .outline(getResources().getColor(R.color.outline_color))
        // Error indicators (such as text, borders, icons) displayed on `background`
        // Accessibility: Must have a contrast ratio of at least 4.5:1 vs `background`
        .success(getResources().getColor(R.color.success_color))
        // Success indicators (such as borders, icons) displayed on `background`
        // Accessibility: Must have a contrast ratio of at least 3:1 vs `background`
        .error(getResources().getColor(R.color.error_color))
        // Button corner radius, in `dp`
        .buttonRadius(48f)
        .build();

Configuration configuration = new Configuration.Builder()
        .branding(branding)
        .build();


Intent intent = Sdk.createLaunchIntent(activity, sessionUrl, configuration);
startActivityForResult(intent, REQUEST_CODE);

All custom values for branding are optional. If a value is not provided for them the default Veriff color or icon will be used.

More customization options

Customizing the font

You can customize the fonts used in the SDK by passing the resource IDs of the fonts you want to use. Make sure that you have added the font files to the font resource folder in your app. A custom font can be set by passing a com.veriff.Font object to the font method of Branding builder. The com.veriff.Font builder accepts 3 types of fonts via the setRegular setMedium and setBold methods.

brandingBuilder.font(
    new com.veriff.Font.Builder()
        .setRegular(R.font.comic_neue_regular)
        .setMedium(R.font.comic_neue_medium)
        .setBold(R.font.comic_neue_bold)
        .build()
);

Custom intro screen

Veriff supports replacing introduction screen with a custom client developed introduction screen for eligible customers. First, please ask about this possibility from your solutions engineer. In case we can offer it for you then removal process is following:

Configuration configuration = new Configuration.Builder()
        .customIntroScreen(true)
        .build();

Note: Adding the configuration alone in your app is not enough to enable the custom intro screen. Make sure to contact your solutions engineer so they can enable the feature for your integration.

Setting a locale for the SDK (Optional)

You can set a locale(java.util.Locale) for the SDK from the app itself.

Locale appLocale = Locale.ENGLISH;
Configuration configuration = new Configuration.Builder()
        .locale(appLocale)
        .build();

Intent intent = Sdk.createLaunchIntent(activity, sessionUrl, configuration);
startActivityForResult(intent, REQUEST_CODE);

Getting the verification status

Veriff SDK sends callbacks to your mobile application. To capture the result override the onActivityResult method in your activity that started the verification flow:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_CODE) {
        Result result = Result.fromResultIntent(data);
        if (result != null) {
            handleResult(result); //see below for handling the result
        }
    }
    super.onActivityResult(requestCode, resultCode, data);
}

public void handleResult(Result result) {
    switch (result.getStatus()) {
    case DONE:
        // Session is completed from the end-user's perspective
        break;
    case CANCELED:
        // End-user cancelled the session
        break;
    case ERROR:
        // An error occurred during the flow, Veriff has already shown UI, no need to display
        // a separate error message here
        Log.w(TAG, "Verification error occurred: " + result.getError());
        break;
    }
}

Adding error logging

To turn on logging, simply add your logging implementation instance (instance of com.veriff.Logger class) to the SDK before launching the SDK as shown.

Sdk.setLogger(myLoggerImplementation);
Intent intent = Sdk.createLaunchIntent(activity, sessionUrl);
startActivityForResult(intent, REQUEST_CODE);

Excluding ML Kit support

Veriff Android SDK uses ML Kit [🡕] for things like face detection, barcode scanning or text recognition to improve the end-user experience. It uses on-device models that are pre-downloaded by play services. If your app cannot use play services at all then you can exclude the transitive mlkit dependency - this will remove any dependencies on ML Kit and disable the use of these ML modules at runtime:

implementation('com.veriff:veriff-library:6.0.0') {
    exclude group: 'com.veriff', module: 'mlkit'
}

Android SDK Changelog

Please refer to release notes [🡕].

Migrating Veriff Android SDK from 5.x.x to 6.0.0

SDK integration

The following APIs were removed:

The following APIs were renamed:

The following APIs were added:

Migrating Veriff Android SDK from 4.x.x to 5.0.0

SDK integration

The following APIs were removed:

The following APIs were added:

Migrating Veriff Android SDK from 3.x.x to 4.0.0

Follow these steps to migrate from SDK 3.x.x to 4.0.0

Android Gradle Plugin Open the root build.gradle file and change the classpath dependency in the buldscript section if that needed. groovy buildscript { repositories { ... } dependencies { classpath 'com.android.tools.build:gradle:3.4.1' // and above ... } }

Kotlin Open the root build.gradle file and change the classpath dependency in the buldscript section if that needed.

buildscript {
    ext.kotlinVersion = '1.4.0' // and above
    repositories {
      ...
    }
    dependencies {
        ...
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion"
        ...
    }
}

Proguard Open the root build.gradle file and add the force update to the buildscript section if that needed. groovy buildscript { ... configurations.all { resolutionStrategy { force 'net.sf.proguard:proguard-gradle:6.2.2' } } }

SDK integration Nothing changed in SDK except the public API types, please update the imports to java import com.veriff.Branding; import com.veriff.Configuration; import com.veriff.Font; import com.veriff.Result; import com.veriff.Sdk; and change types from VeriffBranding to Branding VeriffConfiguration to Configuration VeriffFont to Font VeriffResult to Result

Migrating Veriff Android SDK from 2.x.x to 3.0.0

Follow these steps to migrate from SDK 2.x.x to 3.0.0

Switch to AndroidX

Veriff SDK 3.0.0 requires AndroidX 1.0.0 or later. If you haven't switched to AndroidX in your app yet then follow this guide [🡕].

Enable Java 8

Veriff SDK 3.0.0 requires Java 8 language features to be enabled in your project. If you don't have this enabled already then add this to your app/build.gradle file under the android {} section:

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

See more here [🡕].

Switch from baseUrl and sessionToken to sessionUrl

The new 3.0.0 SDK requires a single sessionUrl parameter instead of baseUrl and sessionToken. See the documentation here. As a backwards compatibility measure, if a sessionToken value is passed into the sessionUrl parameter then it will still work with an assumed baseUrl of magic.veriff.com.

Use com.veriff.* classes instead of mobi.lab.veriff.data.* ones

The name and location of the main SDK entry class has changed from mobi.lab.veriff.data.Veriff to com.veriff.VeriffSdk. The API is largely similar - instead of Veriff.Builder there's a VeriffSdk.createLaunchIntent method that returns an Intent which you can then use to launch veriff. See example here.

If you are using Branding to customize the look and feel of the SDK then it has a new name - VeriffBranding. The builder interface has been streamlined by removing the set* prefixes from all the methods. Read more about customization here.

Use com.veriff.VeriffResult instead of reading return Intent directly

Starting with 3.0.0 there's a new way to handle the result of the verification flow. Instead of reading INTENT_EXTRA_STATUS directly from the returned data intent, use VeriffResult.fromResultIntent(data) to get a result object with a status field and an optional error field. We've reduced status to just three - CANCELED, ERROR, DONE. In case of ERROR the error field contains more information. See the example here.

Remove usage of deprecated types

While the old SDK entrypoints are still present for backwards compatibility they will be removed in the future. Please remove usage of any SDK type marked with @Deprecated - the easiest way to discover these is to look at your Gradle build log with Java/Kotlin compilation warnings turned on.

Here's a list of old deprecated classes due to be removed in a future release:

mobi.lab.veriff.data.Veriff
mobi.lab.veriff.data.Veriff.Builder
mobi.lab.veriff.data.VeriffConstants
mobi.lab.veriff.data.Branding
mobi.lab.veriff.data.Branding.Builder
mobi.lab.veriff.data.DrawableProvider
mobi.lab.veriff.util.LogAccess
mobi.lab.veriff.util.LogAccess.LogLevel
mobi.lab.veriff.util.LogcatLogAccess
mobi.lab.veriff.service.VeriffStatusUpdatesService

iOS SDK integration

iOS SDK Requirements

Integration Veriff iOS SDK requires at least iOS version 11.0

Adding the SDK to the project

VeriffSDK requires the latest stable version of Xcode available at the time the release is made. If you would like to use versions that are independent of Swift versions, please integrate .xcframework.

Using Swift Package Manager

To integrate Veriff SDK with Swift Package Manager, open File > Swift Packages > Add Package Dependency and add the Veriff iOS SDK Swift Package repository url as stated below;

https://github.com/Veriff/veriff-ios-spm/

Using Cocoapods

To integrate Veriff SDK with Cocoapods, please add the line below to your Podfile and run pod install. New to Cocoapods? Learn more here [🡕].

pod 'VeriffSDK'

After installation is done, use the newly created .xcworkspace file of your project.

Using Carthage

To integrate VeriffSDK into your Xcode project using Carthage, specify the required libraries below in your Cartfile.

binary "https://cdn.veriff.me/ios/carthage/VeriffSDK.json"

Run carthage update --use-xcframeworks and then drag and drop Veriff.xcframework from Carthage/Build folder to the Frameworks, Libraries, and Embedded Content section on your app target's General settings tab.

Using XCFramework

To integrate VeriffSDK into your project manually, please download VeriffSDK [⭳].

After the download finishes, drag and drop the unzipped Veriff.xcframework to the Frameworks, Libraries, and Embedded Content section on your app target's General settings tab.

Adding permissions

Add usage descriptions to application Info.plist

Not adding these usage descriptions causes system to kill application when it requests the permissions when needed.

Veriff iOS SDK requires camera, microphone, photo library and optionally NFC reader permissions for capturing photos, video and scanning passport during identification. Your application is responsible to describe the reason why camera, microphone, photo library and NFC reader is used. You must add 3 descriptions listed below to Info.plist of your application with the explanation of the usage.

Add required steps for NFC scanning

  1. Add NFCReaderUsageDescription description to Info.plist.
  2. The application needs to define the list of application IDs or AIDs it can connect to, in the Info.plist file.

  3. The AID is a way of uniquely identifying an application on a ISO 7816 tag, which is usually defined by a standard.

    <key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
  <string>A0000002472001</string>
  <string>00000000000000</string>
</array>

  4. Introduce a new entitlement for NFC scanning, a feature made available from iOS 13 onwards. Xcode automatically adds this entitlement when you activate the Near Field Communication Tag Reading feature in the target Signing & Capabilities. Following the activation of this feature, the *.entitlements file should include the TAG format. If your application is intended to support iOS versions prior to iOS 13, the NDEF format is mandatory. However, for applications targeting iOS 13 and later, there is no need to add the NDEF format to the entitlements.

    <key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>NDEF</string>
    <string>TAG</string>
</array>

Note: due to Apple's policies, you may be required to record and share a proof video of using the NFC. You can download and use this pre-recorded video [⭳]. If this does not solve the issue, please contact our support team.

Starting verification flow

Import Veriff in your code

// Swift
import Veriff

// Objective-C
@import Veriff;

In order to use Veriff SDK, please import it to your class that will use the SDK.

Start the verification flow

In order to start the verification flow please call the method below with the defined parameters.

// SwiftUI
let veriff = VeriffSdk.shared
veriff.startAuthentication(sessionUrl: sessionUrl)

// Swift
let veriff = VeriffSdk.shared
veriff.startAuthentication(sessionUrl: sessionUrl, presentingFrom: yourViewController)

// Objective-C
VeriffSdk *veriff = [VeriffSdk shared];
[veriff startAuthenticationWithSessionUrl:sessionUrl presentingFrom:yourViewController];

Parameters are defined as below;

Parameters Description
sessionUrl Required parameter. sessionUrl can be received from your backend implementation. sessionUrl should be unique for each call. Check /sessions endpoint in the API documentation here to learn how to generate one.
configuration Optional VeriffConfiguration object. Refer to Customize user interface (Optional) for how to use it.
presentingFrom Your app's view controller from which our UI will be presented modally. It's optional and shouldn't be used in SwiftUI projects.

Customize user interface (Optional)

You can customize the Veriff user interface through your own application, by letting the SDK know of your brand's main color, font and logo. The Branding class allows customization of the navigation bar title image, button corner radius, font and following colors:

In order to use customization set the branding property of VeriffConfiguration before you start the verification.

See the Veriff SDK customization guide [🡕] document to see what it looks like.

// Swift
let branding = VeriffSdk.Branding()
branding.logo = UIImage(named: "logo.png")
branding.background = UIColor.background
branding.onBackground = UIColor.onBackground
branding.onBackgroundSecondary = UIColor.onBackgroundSecondary
branding.onBackgroundTertiary = UIColor.onBackgroundTertiary
branding.primary = UIColor.primary
branding.onPrimary = UIColor.onPrimary
branding.secondary = UIColor.secondary
branding.onSecondary = UIColor.onSecondary
branding.cameraOverlay = UIColor.cameraOverlay
branding.onCameraOverlay = UIColor.onCameraOverlay
branding.outline = UIColor.outline
branding.error = UIColor.error
branding.success = UIColor.success
branding.buttonRadius = CGFloat.cornerRadius
branding.font = VeriffSdk.Branding.Font(regular: "Font", medium: "Font-Medium", bold: "Font-Bold")

// Objective-C
VeriffBranding *branding = [[VeriffBranding alloc] init];
branding.logo = [UIImage imageNamed:@"logo.png"];
branding.background = [UIColor background];
branding.onBackground = [UIColor onBackground];
branding.onBackgroundSecondary = [UIColor onBackgroundSecondary];
branding.onBackgroundTertiary = [UIColor onBackgroundTertiary];
branding.primary = [UIColor primary];
branding.onPrimary = [UIColor onPrimary];
branding.secondary = [UIColor secondary];
branding.onSecondary = [UIColor onSecondary];
branding.cameraOverlay = [UIColor cameraOverlay];
branding.onCameraOverlay = [UIColor onCameraOverlay];
branding.outline = [UIColor outline];
branding.error = [UIColor error];
branding.success = [UIColor success];
branding.buttonRadius = 5;
branding.font = [[VeriffBrandingFont alloc] initWithRegular: @"Font" medium: @"Font-Medium" bold: @"Font-Bold"];

For optimal results, we recommend that the height of your custom logo image be kept under 40 points, and the width under 90 points. If your logo exceeds these dimensions, it will be compressed while preserving its original aspect ratio.

Setting the user interface language

The Veriff iOS SDK allows setting the language of the SDK. In order to use this language, please set the languageLocale property of VeriffSdk.Configuration before you start the verification.

// Swift
let locale = Locale(identifier: "et")

// Objective-C
NSLocale *locale = [[NSLocale alloc] initWithLocaleIdentifier:@"et"];

Create the configuration object

// Swift
let configuration = VeriffSdk.Configuration(branding: branding, languageLocale: locale)

// Objective-C
VeriffConfiguration *configuration = [[VeriffConfiguration alloc] initWithBranding:branding languageLocale:locale];

Custom intro screen

Veriff supports replacing introduction screen with a custom client developed introduction screen for eligible customers. First, please ask about this possibility from your Solutions Engineer. In case we can offer it for you then removal process is following:

configuration.customIntroScreen = true

Note: This step alone is not enough to enable the custom intro screen. Make sure to contact your Solutions Engineer so they can enable the feature for your integration.

Vendor data

Veriff supports the option to override vendor data. Please check with your Solutions Engineer to confirm if this feature can be enabled for your integration. If it is possible, follow these steps:

  1. Veriff will enable vendor data overriding from the backend for your integrations.
  2. Modify the configuration option as specified below.
configuration.vendorData = "Vendor Data"

Note: Enabling this feature alone will not be sufficient to override the vendor data. Ensure that you contact your Solutions Engineer to have the feature enabled for your integration.

Start the verification flow by using the configuration

// Swift
let veriff = VeriffSdk.shared
veriff.startAuthentication(sessionUrl: sessionUrl, configuration: configuration, presentingFrom: yourViewController)

// Objective-C
VeriffSdk *veriff = [VeriffSdk shared];
[veriff startAuthenticationWithSessionUrl:sessionUrl configuration:configuration presentingFrom:yourViewController];

Handling result codes from SDK

To receive session results, you must implement the VeriffSdkDelegate protocol and assign a delegate to the VeriffSdk instance.

veriff.delegate = self

The Veriff SDK returns a number of result codes that your application can handle.

// Swift
extension VerificationService: VeriffSdkDelegate {
    func sessionDidEndWithResult(_ result: Veriff.Result) {
        switch result.status {
        case .done:
            // The end-user successfully submitted the session
            break
        case .canceled:
            // The end-user canceled the verification process.
            break
        case .error(let error):
            switch error {
                // ...
            }
        }
    }
}

// Objective-C
- (void)sessionDidEndWithResult:(VeriffResult *)result {
    switch (result.status) {
    case VeriffStatusDone:
        // The end-user successfully submitted the session
        break;
    case VeriffStatusCanceled:
        // The end-user canceled the verification process.
        break;
    case VeriffStatusError:
        if (result.error == nil) { break; }
        switch (result.error.code) {
            // ...
        }
    }
}

You can find the description of status codes below:

Notes

Migrating to Veriff iOS 3.0.0

Switch from baseUrl and sessionToken to sessionUrl

The Veriff object in the SDK 3.0.0 takes a required sessionUrl and an optional VeriffConfiguration instance as parameters into initialisation. The sessionUrl is received from your backend implementation (see the documentation here), it is composed of the baseUrl and sessionToken sent to the VeriffConfiguration object in earlier versions.

Updated VeriffConfiguration object

The VeriffConfiguration struct now takes in branding and languageLocale as initialisation parameters.

The new VeriffDelegate method

You can now receive session results via func sessionDidEndWithResult(_ result: Veriff.Result) instead of the obsolete func onSession(result: VeriffResult, sessionToken: String). The sessionToken is included in the Veriff.Result as an instance variable.

Use Veriff.Result instead of VeriffResult

The new Veriff.Result struct comprises status: Status and sessionToken: String? instance variables. The Status enum can be of three types: done, canceled, error. The description variable on the Veriff.Result returns additional information as a string.

Migrating to Veriff iOS 4.0.0

Rename Veriff instances to VeriffSdk

The name Veriff was used both for our module and public class name. However this blocked us from supporting Swift Package Manager due to Swift compiler bug [🡕]. We renamed our public class name to VeriffSdk.

VeriffConfiguration is now VeriffSdk.Configuration

VeriffConfiguration struct is moved under VeriffSdk. Please replace the occurrences of VeriffConfiguration with VeriffSdk.Configuration.

Branding is now VeriffSdk.Branding

Branding struct is moved under VeriffSdk. Please replace the occurrences of Branding with VeriffSdk.Branding.

Rename VeriffDelegate to VeriffSdkDelegate

Please replace the occurrences of VeriffDelegate with VeriffSdkDelegate.

VeriffSdk.Result.description made non-optional

If you were dealing with unwrapping it, feel free to remove it.

VeriffSdk.Result.sessionToken removed and VeriffSdk.Result.sessionUrl added instead

Please remove the occurrences of sessionToken. You can now use sessionUrl to get the full sessionUrl including token.

Migrating to Veriff iOS 5.0.0

Increased min iOS supported version

Now min version is iOS 11.0.

Updated VeriffSdk.Branding object

Following configurations are removed:

Fonts API changes:

logomark customization is added.

Migrating to Veriff iOS 6.0.0

Updated VeriffSdk.Branding object

Following configurations are added:

Following configurations are removed:

Following configurations are deprecated:

Following configurations are renamed:

iOS SDK Changelog

Please refer to release notes [🡕].

Flutter Plugin integration

Requirements

Integration with Veriff Flutter Plugin requires the project to target at least iOS version 11.0 and Android version 5.0 (api 21) or higher.

Install the plugin to your project

Follow instructions here [🡕] to install the plugin.

iOS specific configuration

Add usage descriptions to application Info.plist

Not adding these usage descriptions causes system to kill application when it requests the permissions when needed.

Veriff requires camera, microphone, photo library and optionally NFC reader permissions for capturing photos, video and scanning passport during identification. Your application is responsible to describe the reason why camera, microphone, photo library and NFC reader is used. You must add 3 descriptions listed below to Info.plist of your application with the explanation of the usage.

Add required steps for NFC scanning

  1. Add NFCReaderUsageDescription description to Info.plist.

  2. The application needs to define the list of application IDs or AIDs it can connect to, in the Info.plist file. The AID is a way of uniquely identifying an application on a ISO 7816 tag, which is usually defined by a standard.

    <key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
  <string>A0000002472001</string>
  <string>00000000000000</string>
</array>

  3. Introduce a new entitlement for NFC scanning, a feature made available from iOS 13 onwards. Xcode automatically adds this entitlement when you activate the Near Field Communication Tag Reading feature in the target Signing & Capabilities. Following the activation of this feature, the *.entitlements file should include the TAG format. If your application is intended to support iOS versions prior to iOS 13, the NDEF format is mandatory. However, for applications targeting iOS 13 and later, there is no need to add the NDEF format to the entitlements.

    <key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>NDEF</string>
    <string>TAG</string>
</array>

Set the iOS target in Xcode

Make sure that the 'iOS Deployment Target' in Xcode (under Project > target > Info > Deployment Target) is set to iOS 11.0 or later.

Launching the verification flow

Import plugin in your code

In order to use Veriff plugin, please import it to your class that will use it. import 'package:veriff_flutter/veriff_flutter.dart'

Start verification flow

In order to start the verification flow please create a configuration with defined parameters below.

Parameters are defined as below;

Parameters Description
sessionUrl Required parameter. sessionUrl can be received from your backend implementation. sessionUrl should be unique for each call. Check /sessions endpoint in the API documentation here to learn how to generate one. 
Configuration config = Configuration(sessionUrl);

Then pass the configuration to Veriff object and start the verification flow;

Veriff veriff = Veriff();

try {
      Result result = await veriff.start(config);
      print(result.status);
      print(result.error);
    } on PlatformException {
      // handle exception
    }

Customize user interface (Optional)

You can customize Veriff SDK user interface in your application by defining your brand's colors, font and logo.

See the Veriff SDK customization guide [🡕] document to see what it looks like.

Veriff Flutter plugin allows the customization of your brand's colors, font and logo in the SDK flow by passing the optional parameters when launching Veriff:

String regularFontPath = "fonts/Regular.otf";
String mediumFontPath = "fonts/Medium.otf";
String boldFontPath = "fonts/Bold.otf";
Fonts fonts = Fonts(
    regularFontPath: regularFontPath, 
    mediumFontPath: mediumFontPath, 
    boldFontPath: boldFontPath
);
Branding branding = Branding(
    logo: AssetImage(path_of_image),
    background: "#f2ff00",
    onBackground: "#ff00ff",
    onBackgroundSecondary: "#52b35c",
    onBackgroundTertiary: "#3a593d",
    primary: "#123abc",
    onPrimary: "#ff00ff",
    secondary: "#f2ff00",
    onSecondary: "#ff7700",
    cameraOverlay: "#59496a",
    onCameraOverlay: "#e27e23",
    outline: "#ff00ff",
    error: "#ff0000",
    success: "#00ff00",
    buttonRadius: 5,
    fonts: fonts
);

And pass the branding object with configuration for starting the verification flow:

Configuration config = Configuration(sessionUrl, branding: branding);

When a color isn't defined, the default Veriff theme color is used.

Setting the user interface language

Veriff Flutter plugin supports setting the language of the UI. In order to use this feature, please pass the locale identifier as in example below;

Configuration config = Configuration(sessionUrl, branding: branding, languageLocale: "et");

Custom intro screen

Veriff supports replacing introduction screen with a custom client developed introduction screen for eligible customers. First, please ask about this possibility from your solutions engineer. In case we can offer it for you then removal process is following:

config.useCustomIntroScreen = true;

Handling the results from plugin

The Result returned by start method will have a status that is one of Status.done, Status.canceled and Status.error. In case Status.error is received, you will also have an error description that is one of the list below;

You can check the statuses and errors using switch-case as in example below;

switch (result.status) {
        case Status.done:
          print("Session is completed.");
          break;
        case Status.canceled:
          print("Session is canceled by the end-user.");
          break;
        case Status.error:
          switch (result.error) {
            case Error.cameraUnavailable:
              print("User did not give permission for the camera");
              break;
            case Error.microphoneUnavailable:
              print("User did not give permission for the microphone.");
              break;
            case Error.networkError:
              print("Network error occurred.");
              break;
            case Error.sessionError:
              print("A local error happened before submitting the session.");
              break;
            case Error.deprecatedSDKVersion:
              print(
                  "Version of Veriff SDK used in plugin has been deprecated. Please update to the latest version.");
              break;
            case Error.unknown:
              print("Uknown error occurred.");
              break;
            case Error.nfcError:
              print("Error with NFC");
              break;
            case Error.setupError:
              print("Error with setup");
              break;
            case Error.none:
              print("No error.");
              break;
            default:
              break;
          }
          break;
        default:
          break;
}

React Native SDK integration

React Native SDK requirements

Integration with Veriff React Native SDK requires the project to target at least iOS version 12.4 and Android version 5.0 (api 21) or higher.

Note: If you have created your react native app using expo, you will have to eject out of expo at this point(if you have not ejected out already) since expo does not support native modules Check the Caveats section here [🡕] for more info on that.

Add the SDK to a project

Add the Veriff React Native SDK to your package.json file:

npx yarn add @veriff/react-native-sdk

Or if using npm:

npm install @veriff/react-native-sdk --save

Update Android build.gradle file

Open the root build.gradle file in the android folder and add a new maven destination to the repositories in the allprojects section. The best place is right after the local node_modules repositories and before the google() repository.

allprojects {
    repositories {
        // ... local react native repos
        maven { url "https://cdn.veriff.me/android/" } //veriff
        google()
        jcenter()
    }
}

iOS Specific setup

Add Swift to the ios module

Veriff SDK requires your ios module to have some Swift code. If you don't have any Swift code yet then add a new empty.swift file in Xcode. If Xcode offers to add a bridging header then add it.

Update iOS Podfile

Open Podfile in the ios folder and make sure that platform is 12.4 or higher:

platform :ios, '12.4'

Also make sure your main target in the Podfile contains use_native_modules! directive:

target 'MyApp' do
  # pod 'foo'...

  config = use_native_modules!
end

Add usage descriptions to application Info.plist

Not adding these usage descriptions causes system to kill application when it requests the permissions when needed.

Veriff requires camera, microphone, photo library and optionally NFC reader permissions for capturing photos, video and scanning passport during identification. Your application is responsible to describe the reason why camera, microphone, photo library and NFC reader is used. You must add 3 descriptions listed below to Info.plist of your application with the explanation of the usage.

Add required steps for NFC scanning

  1. Add NFCReaderUsageDescription description to Info.plist.

  2. The application needs to define the list of application IDs or AIDs it can connect to, in the Info.plist file. The AID is a way of uniquely identifying an application on a ISO 7816 tag, which is usually defined by a standard.

    <key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
  <string>A0000002472001</string>
  <string>00000000000000</string>
</array>

  3. Introduce a new entitlement for NFC scanning, a feature made available from iOS 13 onwards. Xcode automatically adds this entitlement when you activate the Near Field Communication Tag Reading feature in the target Signing & Capabilities. Following the activation of this feature, the *.entitlements file should include the TAG format. If your application is intended to support iOS versions prior to iOS 13, the NDEF format is mandatory. However, for applications targeting iOS 13 and later, there is no need to add the NDEF format to the entitlements.

    <key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>NDEF</string>
    <string>TAG</string>
</array>

Set the iOS target in Xcode

Make sure that the 'iOS Deployment Target' in Xcode (under Project > target > Info > Deployment Target) is set to iOS 12.4 or later.

Using the Veriff React Native SDK

Starting the verification flow

In order to use Veriff SDK, please import it to the file that will use the SDK.

import VeriffSdk from '@veriff/react-native-sdk';

Parameters are defined as below;

Parameters Description
sessionUrl Required parameter. sessionUrl can be received from your backend implementation. sessionUrl should be unique for each call. Check /sessions endpoint in the API documentation here to learn how to generate one.

Once you have the sessionUrl you can launch Veriff using VeriffSdk imported earlier:

var result = await VeriffSdk.launchVeriff({ sessionUrl: SESSION_URL });

User Interface customization

You can customize Veriff SDK user interface in your application by defining your brand's colors, font and logo.

See Veriff SDK customization guide [🡕] document on how it looks.

Veriff React Native SDK allows the customization of your brand's colors, font and logo in the SDK flow by passing in these optional properties when launching Veriff:

var result = await VeriffSdk.launchVeriff({
    sessionUrl: SESSION_URL,
    branding: {
      logo: 'parrot', // see alternative options for logo below
      background: '#ff00ff',
      onBackground: '#ffffff',
      onBackgroundSecondary: '#ff00ff',
      onBackgroundTertiary: '#000000',
      primary: '#333333',
      onPrimary: '#444444',
      secondary: '#333333',
      onSecondary: '#444444',
      outline: '#444444',
      cameraOverlay: '#59496a',
      onCameraOverlay: '#e27e23',
      error: '#333333',
      success: '#444444',
      buttonRadius: 28,
      iOSFont: {
        regular: 'Font-Regular',
        medium: 'Font-Medium',
        bold: 'Font-Bold',
      },
      androidFont: {
        regular: 'font_regular',
        medium: 'font-medium',
        bold: 'font_bold',
      }
    },
  });

When a color or a font isn't defined the default Veriff color or font is used. Same applies to the logo - when it isn't defined the default is used. The image assets need to be added into Xcode assets in the iOS project and into drawable folders in the Android project. In the example above you would need to add an image asset named 'parrot' into Xcode assets and 'parrot.png' to Android drawable folders in android/src/main/res.

Instead of using platform-specific image assets you can provide a URI to an image which will then be used:

var result = await VeriffSdk.launchVeriff({
    sessionUrl: SESSION_URL,
    branding: {
      logo: { uri: 'http://example.com/logo/parrot.jpg' },
    },
  });

React Native assets are also supported through resolveAssetSource:

const resolveAssetSource = require('react-native/Libraries/Image/resolveAssetSource');
const parrot = require('./img/parrot.png');

var result = await VeriffSdk.launchVeriff({
    sessionUrl: SESSION_URL,
    branding: {
      logo: resolveAssetSource(parrot),
    },
  });

Setting the user interface language

The Veriff RN SDK allows setting the language of the SDK. In order to use this language, please pass the locale as in example below;

var result = await VeriffSdk.launchVeriff({
    sessionUrl: SESSION_URL,
    locale: 'et'
  });

Custom intro screen

Veriff supports replacing introduction screen with a custom client developed introduction screen for eligible customers. Please request this from your solutions engineer. The removal process is following:

var result = await VeriffSdk.launchVeriff({
    sessionUrl: SESSION_URL,
    locale: 'et',
    customIntroScreen: true
  });

Handling the result from the SDK

The result returned by launchVeriff will have a status field that is one of either VeriffSdk.statusDone, VeriffSdk.statusCanceled or VeriffSdk.statusError. In case of statusError there will be a error code (not human-readable) in the error field.

var result = await VeriffSdk.launchVeriff({ sessionUrl: SESSION_URL });
switch (result.status) {
  case VeriffSdk.statusDone:
    // end-user submitted the images and completed the flow
    // note that this does not mean a final decision yet
    break;
  case VeriffSdk.statusCanceled:
    // end-user canceled the flow before completing
    break;
  case VeriffSdk.statusError:
    // the flow could not be completed due to an error
    console.log("Veriff verification failed with error=" + result.error);
    break;
}

Migrating to React Native SDK 3.0.0

Follow these steps to migrate to React Native SDK 3.0.0 API

Updated Branding API

Following configurations are added:

Following configurations are removed:

Following configurations are renamed:

buttonCornerRadius -> buttonRadius

Migrating to React Native SDK 2.0.0

Follow these steps to migrate to React Native SDK 2.0.0 API

Use new parameter sessionUrl

New API uses sessionUrl instead of a sessionToken. sessionUrl is a combination of base URL and session token.

We renamed the navigationBarImage parameter in configuration to logo.

React Native SDK Changelog

Below is a summary of changes introduced with each version of the React Native SDK. Expand the list by clicking on "Versions" and then on each release version to see the summary.

Javascript SDK Integration

Veriff JS SDK, is a simple and customisable library which helps to integrate with Veriff Online Identity solution. Use this to simply include Veriff flow. You don't need any backend on your side for this including JS SDK to your website.

Install JS SDK

Include as a script tag:

<script src='https://cdn.veriff.me/sdk/js/1.5/veriff.min.js'></script>

or install it via a package manager

  $ npm install --save @veriff/js-sdk

   // CommonJS
  const Veriff = require('@veriff/js-sdk');

  // ES6 style import
  import { Veriff } from '@veriff/js-sdk';

Adding JS SDK

Veriff JS SDK requires one parent element in HTML:

<div id='veriff-root'></div>

It is possible to set the width of js-sdk form through style attribute:

<div id='veriff-root' style="width:400px"></div>

In order to initialize the library, API Key, parentId and onSession callback function is required. Parameters are defined as below;

Parameters Description
apiKey Required parameter. See how to find your API keys here to learn how to generate one.
parentId Required parameter. 'veriff-root'
onSession Required parameter. The end-user can be redirected either to the verification url or incontext SDK can be triggered 
  const veriff = Veriff({
    apiKey: 'API_KEY',
    parentId: 'veriff-root',
    onSession: function(err, response) {
      // received the response, verification can be started / triggered now

      // redirect
      window.location.href = response.verification.url;

      // incontext sdk
      createVeriffFrame({url: response.verification.url});
    }
  });

  veriff.mount();

Read more about incontext sdk method or redirection.

By default, the following form will be rendered:

JSSDKDEFAULT

onSession function is executed after the response is received from the API, response body contains a verification object with following schema:

    {
      "status": "success",
      "verification": {
          "id": "UUID V4 Identifying the verification",
          "url": "full url to which a person should be redirected in order to proceed with verification flow",
          "host": "hostname",
          "status": "status of the verification",
          "sessionToken": "JWT encoded verification token"
      }
  }

vendorData: string - customer-specific data string, max 1000 characters long, will be sent back unmodified using webhooks. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer's domain). In case the Given name / Last name / Vendor Data or all of them are known, they can be passed to the SDK, therefore text input fields will not be rendered.

  const veriff = Veriff({
    apiKey: 'API_KEY',
    parentId: 'veriff-root',
    onSession: function(err, response) {
      // received the response, verification can be started now
    }
  });
  veriff.setParams({
    person: {
      givenName: 'Foo',
      lastName: 'Bar'
    },
    vendorData: '7eb19312-79d6-11ec-90d6-0242ac120003'
  });
  veriff.mount({
    submitBtnText: 'Get verified'
  });

JSSDKONLYBUTTON

It is possible to disable fields rendering without passing any data by not including anything in corresponding value:

  const veriff = Veriff({
    apiKey: 'API_KEY',
    parentId: 'veriff-root',
    onSession: function(err, response) {
      // received the response, verification can be started now
    }
  });
  veriff.setParams({
    person: {
      givenName: ' ',
      lastName: ' '
    },
    vendorData: ' '
  });
  veriff.mount({
    submitBtnText: 'Get verified'
  });

Additionally the input placeholder and button text value can be customised.

  const veriff = Veriff({
    apiKey: 'API_KEY',
    parentId: 'veriff-root',
    onSession: function(err, response) {
      // received the response, verification can be started now
    }
  });
  veriff.mount({
    formLabel: {
      givenName: 'First name',
      lastName: 'Family name',
      vendorData: 'Unique id of an end-user'
    },
    submitBtnText: 'Get verified',
    loadingText: 'Please wait...'
  });

JSSDKCUSTOM

InContext Javascript SDK Integration

Use this if you would like to use incontext UI.

Install InContext JS SDK

npm install @veriff/incontext-sdk

Adding InContext JS SDK

You need to have a Veriff session URL generated before initializing the SDK. Please, see our documentation to learn how to generate one.

// ES6
import { createVeriffFrame } from '@veriff/incontext-sdk';

// CommonJS
const { createVeriffFrame } = require('@veriff/incontext-sdk');

const veriffFrame = createVeriffFrame({ url: VERIFF_SESSION_URL })

This will render a modal with adapted Veriff application in iframe.

createVeriffFrame() returns an object that controls the modal.

Listening for events

Pass onEvent callback function when initializing SDK

import { createVeriffFrame, MESSAGES } from '@veriff/incontext-sdk';

createVeriffFrame({
  url,
  onEvent: function(msg) {
    switch(msg) {
      case MESSAGES.CANCELED:
        //
        break;
    }
  }
})

Using with inline script

Include a script tag:

<script src='https://cdn.veriff.me/incontext/js/v1/veriff.js'></script>

window.veriffSDK.createVeriffFrame({ url: VERIFF_SESSION_URL });

Options

createVeriffFrame([options])

Close Veriff modal

Normally modal will be closed due to end-user input, but if you want to control it(e.g. timeout), please use this function.

veriffFrame.close();

onReload

This callback can be called on some browsers when the end-user has denied camera access and to re-request access the host page has to be reloaded.

For best UX we recommend reloading the webpage & reopening Veriff InContext SDK automatically.

Example:

const url = sessionStorage.getItem('@veriff-session-url') || getSessionUrl()

veriffSDK.createVeriffFrame({
  url,
  onReload: () => {
    // Logic to re-open Veriff SDK after page reload
    // e.g. sessionStorage.setItem('@veriff-session-url', url);
    window.location.reload();
  },
});

Adding Content Security Policy to InContext SDK

In order to improve the security, add the following CSP directives headers to index.html file, under the <meta> tag:

Content-Security-Policy default-src 'self' *.veriff.me *.veriff.com;
script-src 'self' *.veriff.me *.veriff.com *.hotjar.com *.probity.io;
img-src blob: 'self' *.probity.io;
frame-src 'self' *.hotjar.com;
connect-src 'self' *.veriff.com *.veriff.me *.probity.io;
style-src 'self' *.veriff.com *.veriff.me;

For example:

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="content-security-policy"
 content="default-src 'self' *.veriff.me *.veriff.com;
script-src 'self' *.veriff.me *.veriff.com *.hotjar.com *.probity.io;
img-src blob: 'self' *.probity.io;
frame-src 'self' *.hotjar.com;
connect-src 'self' *.veriff.com *.veriff.me *.probity.io;
style-src 'self' *.veriff.com *.veriff.me;">
</head>

Allow camera requests in your Permissions Policy

To avoid any issues, make sure that you allow Veriff to request camera access. If your Permissions Policy denies camera requests by default, you may encounter issues when using the InContext SDK. For more information, please read the W3C Permissions Policy Explainer [🡕].

Integrate by redirection

In case you would like to opt out of modal based approach by using our incontext sdk you can instead redirect end-users to the verification flow.

Using redirection

You need to have a Veriff session URL generated before redirecting the end-user to the flow. See our documentation to learn how to generate one.

// After receiving the url you could redirect end-users there by using following
window.location.href = url;

Query parameters

Available parameters that can be changed;

Parameters Description
lang Optional parameter. lang can be used to override the end-user interface's language.

API Integration

There are a few scenarios where you may not wish to use Veriff's native SDK or Veriff's web interface to verify your end-users. For example:

In those cases, you can do the whole process using our API, according to the documentation, and not show any Veriff front end to your end-users, or not expect them to be present for the verification.

Test in Postman

It is possible to test the Veriff API v1.0 Collection in Postman. Click on the button below to get started.

Try in Postman ▸

Create a new verification session

Create a new verification session using POST request to #sessions

The goal here is to create a new object (a verification session) that contains the one verification (referred to as 'verification', nested inside the session object in the response).

Send photos

Send photos (face, document front, document back, etc.) by uploading all the pictures one by one using POST request to /sessions/{sessionId} /media

The goal here is to upload the required photos and associate them with the verification created in step 1.

Submit session for review

Submit the verification session using PATCH request to /sessions/{sessionid}

Once all the photos are uploaded, you would then update (PATCH) the verification to mark it into 'submitted' status. This marks the completion of the verification. This step requires all the photos to be submitted prior to triggering this.

After these three steps, you've done your part, and the verification will then be taken care of by us.

Wait for webhook response

Veriff sends you a Decision event via Webhook using POST request. You will have to implement the listener.

This hook will be sent back asynchronously, and it contains more data, including the verified identity information.

The webhook is sent to the URL that is configurable from Veriff Station under Integrations › Webhook Decision / Events URL.

SDK Support Policy

Support Policy for Veriff SDKs

Identity verification software, practices, and regulations move fast. To keep our software user-friendly, and maintain high conversion rates for our customers, our development team needs to be faster. To deliver an increasingly smarter, better and safer product, it's important to drop backward compatibility layers and update SDKs at least once every three months. Our SDKs are updated every two weeks, and downloading new releases will keep your verification process smooth and error-free. All releases are fully tested by our team and before being deployed, and come with the support from our team in the form of:

SDK release versioning To help you keep track of SDK releases, Veriff uses three numbers to represent the scale of the updates. Each release is assigned either X, Y, or Z according to the following descriptions:

Supported languages

Supported languages are as below;

Language Code Name
ar العربية
bg Български
bn বাংলা
ca Català
cs Čeština
da Dansk
de Deutsch
el Ελληνικά
et Eesti
en English
es Español (España)
es-latam Español (Latinoamérica)
es-mx Español (México)
fi Suomi
fil Filipino
fr Français
hi हिंदी
hr Hrvatski
hu Magyar
id Bahasa Indonesia
it Italiano
ja 日本語
ka ქართული
ko 한국어
lv Latviešu
lt Lietuvių
mk Македонски
ms Bahasa Melayu
nb Norsk (Bokmål)
nl Nederlands
pl Polski
pt Português (Brasil)
pt-pt Português (Portugal)
ro Română
ru Русский
si සිංහල
sk Slovenčina
sl Slovenski
so Af-soomaali
sr Srpski
sv Svenska
tr Türkçe
th ไทย
uk Українська
vi Tiếng Việt
zh 简体中文
zh-hant 繁體中文
hy հայերեն

Testing Integrations

You will have 1 Test integration pre-created for you in Veriff Station. You can create more test integrations if needed. The test integration will be used by you to test the communication between Veriff's and your system and to see how the responses are handled. Verification sessions generated for test integrations are not billed and not verified by Veriff.

To check the quality of Veriff's responses, and you are already set up with Veriff, please talk to you solutions engineer. If not, please select plan and subscribe to a free trial on Plans [🡕] page. The free trial will allow to create Live integrations.

Testing verification sessions checklist

Also see our support article for getting the desired test verification result [🡕]

Testing security

Testing responses

Each type of response should be accepted:

Explanations and availability of these have been listed in the session status and decision codes tables > decision codes 9001 to 9121.

Testing process in your app

You should test the handling of best cases as well as edge cases:

Mobile testing

Test our demo app by downloading it in the app store. iOS / Android [🡕]

API Upload testing

Required tools Veriff's integration demo - js-integration-demo-master.zip Node.js - (Download - https://nodejs.org/en/download/) Notepad/TextEdit (default in Windows/Mac) or Notepad++ - (Download - https://notepad-plus-plus.org/)

  1. Download and install Node.js
  2. Download and extract js-integration-demo-master.zip
  3. Open Command (Windows) or Terminal (Mac) on your local computer.
  4. Navigate to js-integration-demo-master folder cd C:\Users\User\Desktop\Veriff API).
  5. Run command >npm install
  6. Open app.js with your text editing app (Notepad/TextEdit) and update 'API-Public-Key' and 'API-Private-Key' to the values in your Backoffice account (Management -> Vendor). Tokens must be in single quotes. Save the file.
const API_TOKEN = process.env.API_TOKEN || 'API-Public-Key';
const API_SECRET = process.env.API_SECRET || 'API-Private-Key';
const API_URL = process.env.API_URL || 'https://api.staging.vrff.io/v1';
const WEBHOOK_PORT = process.env.WEBHOOK_PORT || 3002;
const IMAGE_DIR = process.env.IMAGE_DIR || 'documents'

Run the app.js node app.js

Now the verification session is created and it is being processed. Check your Backoffice dashboard to review the data extracted and decision made by Veriff.

Batch testing

Batch upload tests are sometimes agreed with our onboarding team and are very use case specific. Therefore, below might be not applicable for the majority of customers. For batch tests, customers will need to prepare dataset that will be used for testing. If you have been asked for dataset, please see batch test data preparation guide [🡕].

End-User In The Flow

Flow Diagram

Session Status Diagram

Session Status

API Reference

Prerequisites to create API requests

Log in to Veriff's environment via the link in your sign-up email. Navigate to Integrations page via the top menu and open the Integration you need. From there you need to take:

API URL and Headers

To create the API URL, add v1 to the Base URL value:

https://<Base-URL>/v1/

You'll also need to include Headers info in the request:

X-AUTH-CLIENT: string (required) - API key
CONTENT-TYPE: string (required) - Media type of the resource (application/json)
X-HMAC-SIGNATURE: string (required) - HMAC-SHA256 hex encoded keyed hash using your shared secret key

Backwards compatible changes

Following changes are considered to be backwards compatible by Veriff:

Endpoints

Available endpoints and methods:

Test the requests in Postman

It is possible to test the Veriff API v1.0 Collection in Postman. Click on the button below to get started.

Try in Postman ▸

POST /sessions

Creates a session with the data specified in the request body.

The customer sends end-user's data to Veriff, and in return receives a unique sessionId and a unique sessionToken that are related to the verification session initiated for the specific end-user.

You can find the sample implementation for Javascript at https://github.com/Veriff/js-integration-demo

Request

Request method: POST
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
Content-Type: application/json

Request properties explained
Sample Request
curl
curl -X POST \
  --url '/v1/sessions/' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -d '{
    "verification": {
        "callback": "https://veriff.com",
        "person": {
            "firstName": "John",
            "lastName": "Smith",
            "idNumber": "123456789"
        },
        "document": {
            "number": "B01234567",
            "type": "PASSPORT",
            "country": "EE"
        },
        "address": {
            "fullAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
        },
        "vendorData": "11111111"
    }
}'
Node.js
var request = require('request');

var options = { method: 'POST',
  url: '/v1/sessions/',
  headers:
   { 'Content-Type': 'application/json',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' },
  body:
   { verification:
      { callback: 'https://veriff.com',
        person:
         { firstName: 'John',
           lastName: 'Smith',
           idNumber: '123456789' },
        document: { number: 'B01234567', type: 'PASSPORT', country: 'EE' },
        vendorData: '11111111' } },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3
import requests
import pprint
import json

url = '/v1/sessions/'

payload = json.dumps({
    'verification': {
        'callback': 'https://veriff.com',
        'person': {
          'firstName': 'John',
          'lastName': 'Smith',
          'idNumber': '123456789'
        },
        'document': {
          'number': 'B01234567',
          'type': 'PASSPORT',
          'country': 'EE'
        },
        'vendorData': '11111111',
        'features': [
          'selfid'
        ]
    }
})

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'Content-Type': 'application/json'
}

response = requests.request('POST', url, data=payload, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
{ "status": "success",
  "verification":{
    "id":"f04bdb47-d3be-4b28-b028-a652feb060b5",
    "url": "https://alchemy.veriff.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoX3Rva2VuIjoiOThiYzdjMjEtZTQ0Yy00MTZiLTkxOTMtMTU5ZGZkMzBmMDg4Iiwic2Vzc2lvbl9pZCI6Ijc2ODhmMzYzLTAyZjctNDE1My1iMzM1LWE0ODQ3OTRkMzZmNyIsImlhdCI6MTUwMTIyODI1MSwiZXhwIjoxNTAxODMzMDUxfQ.bMEF37E6-zT2Aa6Q8UXK3B_ZL51w6D_lxnGgQvhj214",
    "vendorData": "11111111",
    "host": "https://alchemy.veriff.com",
    "status": "created",
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoX3Rva2VuIjoiOThiYzdjMjEtZTQ0Yy00MTZiLTkxOTMtMTU5ZGZkMzBmMDg4Iiwic2Vzc2lvbl9pZCI6Ijc2ODhmMzYzLTAyZjctNDE1My1iMzM1LWE0ODQ3OTRkMzZmNyIsImlhdCI6MTUwMTIyODI1MSwiZXhwIjoxNTAxODMzMDUxfQ.bMEF37E6-zT2Aa6Q8UXK3B_ZL51w6D_lxnGgQvhj214"
  }
}

POST /sessions/{sessionId}/media

Uploads an image (and specifies the type of the image that's being uploaded) for a specific sessionId.

Information about PDF support

Veriff supports PDF file uploads for Identity Verification (IDV) documents and Proof of Address (PoA) documents.

Identity Verification Feature

In IDV, document images can be uploaded in following configurations:

Veriff processes first 5 pages of uploaded PDF file. System removes empty pages from the PDF.

Proof of Address Feature

The file that is uploaded for Proof of Address flow must contain only one PoA document. If you need to send several PoA documents, upload them one-by-one in separate PDF files.

For PoA, documents can be uploaded in following configurations:

Veriff processes first 5 pages of uploaded PDF file. System removes empty pages from the PDF.

Request

Request method: POST
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Request properties explained
Sample request
curl
curl -X POST \
  --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \
  -d '{
    "image": {
    "context": "document-front",
      "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII="
    }
}'
Node.js
var request = require('request');

var options = { method: 'POST',
  url: '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' },
  body:
   { image:
      { context: 'document-front',
        content: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII=' } },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url='/v1/sessions/{sessionId}/media'

payload = json.dumps({
    'image': {
    'context': 'document-front',
      'content': 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII='
    }
})


headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53',
    'Content-Type': 'application/json'
}

response = requests.request('POST', url, data=payload, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
{ "status": "success",
  "image":{
     "context": "document-back",
     "id": "39388f8d-c6d6-4e9b-92c6-6978b2e8d664",
     "name": "document-back",
     "timestamp": (Deprecated) null,
     "size": 52268,
     "mimetype": "image/png",
     "url": "/v1/media/39388f8d-c6d6-4e9b-92c6-6978b2e8d664"
   }
}

PATCH /sessions/{sessionId}

Changes the status of the verification to "submitted".

Make sure that you have uploaded all the images with POST/sessions/{sessionId}/media request before setting the status to "submitted".

Request

Request method: PATCH
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Request properties explained
Sample request
curl
curl -X PATCH \
  --url '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: dd994f70b1150ae012f9c1d6d20adf7ed69780044835d39de20b00ffae0660a0' \
  -d '{
    "verification": {
      "status": "submitted"
    }
}'
Node.js
var request = require('request');

var options = { method: 'PATCH',
  url: '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': 'dd994f70b1150ae012f9c1d6d20adf7ed69780044835d39de20b00ffae0660a0',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' },
  body:
   { verification:
      { status: 'submitted' } },
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/sessions/{sessionId}'

payload = json.dumps({
    'verification': {
      'status': 'submitted'
    }
})

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': 'dd994f70b1150ae012f9c1d6d20adf7ed69780044835d39de20b00ffae0660a0',
    'Content-Type': 'application/json'
}

response = requests.request('PATCH', url, data=payload, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
{
    "status": "success",
    "verification": {
        "id": "fd5c1563-1d23-4b1a-ae46-7ba429927ed8",
        "url": "https://alchemy.veriff.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZmQ1YzE1NjMtMWQyMy00YjFhLWFlNDYtN2JhNDI5OTI3ZWQ4IiwiaWF0IjoxNTcyMzM4MDIwfQ.3HbNq0YWKAfFrH-P658_WXMwcUMubyC1aXAMo-umfCU",
        "vendorData": "11111111",
        "host": "https://alchemy.veriff.com",
        "status": "submitted",
        "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZmQ1YzE1NjMtMWQyMy00YjFhLWFlNDYtN2JhNDI5OTI3ZWQ4IiwiaWF0IjoxNTcyMzM4MDIwfQ.3HbNq0YWKAfFrH-P658_WXMwcUMubyC1aXAMo-umfCU"
    }
}

GET /sessions/{sessionId}/attempts

Returns the list of attempt objects with sessionId = {sessionId}

Returns the user-defined statuses data if those have been set in the Veriff environment.

Request

Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/attempts' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14' \
Node.js
var request = require('request');

var options = { method: 'GET',
  url: '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/attempts',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/attempts'

headers = {Response
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample Response (simple)
{
  "status": "success",
  "verifications": [
    {
      "id": "f5c68aea-7f4d-478d-80ab-ca9356074f69",
      "status": "approved"
    },
    {
      "id": "f2270684-8c51-4d03-88eb-dafd43e8b486",
      "status": "resubmission_requested"
    }
  ]
}
Sample Response (user-defined statuses added)

In the sample below the user has added a status for the attempt in the Veriff environment, but has not enabled the "Custom" option for the status.

{
  "status": "success",
  "verifications": [
      {
        "id": "a1c68aea-7f4d-478d-80ab-ca9356074f69",
        "status": "approved",
        "userDefinedData":[
          {
            "status":"Custom status for suspicious attempt",
            "statusCode":"custom_status_for_suspicious_attempt",
            "reason":"Looks like velocity abuse",
            "reasonCode":"looks_like_velocity_abuse",
            "createdAt":"2023-09-18T08:41:41.606636Z"
          }
        ],
        "createdTime":"2023-09-18T08:33:30.047935Z"
      },
      {
        "id": "f2270684-8c51-4d03-88eb-dafd43e8b486",
        "status": "resubmission_requested"
      }
  ]
}

In the sample below the user has added a status for the attempt in the Veriff environment, has enabled the "Custom" option for the status and added an explanation to the text box.

{
  "status": "success",
  "verifications": [
      {
        "id": "a1c68aea-7f4d-478d-80ab-ca9356074f69",
        "status": "approved",
        "userDefinedData":[
          {
            "status":"Custom status for suspicious attempt",
            "statusCode":"custom_status_for_suspicious_attempt",
            "reason":"The document used in this attempt is clearly a cut-out",
            "reasonCode": null,
            "createdAt":"2023-09-18T08:41:41.606636Z"
          }
        ],
        "createdTime":"2023-09-18T08:33:30.047935Z"
      },
      {
        "id": "f2270684-8c51-4d03-88eb-dafd43e8b486",
        "status": "resubmission_requested"
      }
  ]
}

GET /sessions/{sessionId}/decision

Returns the session decision with sessionId = {sessionId}

In order to receive the decision payload from us:

  1. the Integration needs to have the Webhook decisions URL configured
  2. the session related to the sessionId needs to have a status

Test integrations

For test integrations, the Webhook decision URL is added automatically.

But you need to manually set the session's status in Station:

Live integrations

For live integrations, you need to define the Webhook decisions URL:

In live integrations, the session statuses are set automatically.

Request

Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14' \
Node.js
var request = require('request');

var options = { method: 'GET',
  url: 'https://<Base-URL>/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = 'https://<Base-URL>/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a/decision'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
pprint.pprint(response.json())

Response

Headers

X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Response body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample Response
{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "code": 9001,
    "person": {
      "gender": null,
      "idNumber": null,
      "lastName": "MORGAN",
      "addresses": [
        {
          "fullAddress": "1234 Snowy Ridge Road, Indiana, 56789 USA",
          "parsedAddress": {
            "city": null,
            "unit": null,
            "state": "Indiana",
            "street": "1234 Snowy Ridge Road",
            "country": "USA",
            "postcode": "56789",
            "houseNumber": "null"
          }
        }
      ],
      "firstName": "SARAH",
      "citizenship": null,
      "dateOfBirth": "1967-03-30",
      "nationality": null,
      "yearOfBirth": "1967",
      "placeOfBirth": "MADRID",
      "occupation": "Sales Representative",
      "employer": "Any Company LLC",
      "foreignerStatus": "EXTRANJERO",
      "extraName": "NOM D'USAGE",
      "pepSanctionMatch": null
    },
    "reason": null,
    "status": "approved",
    "comments": [],
    "document": {
      "type": "DRIVERS_LICENSE",
      "number": "MORGA753116SM9IJ",
      "country": "GB",
      "validFrom": null,
      "validUntil": "2022-04-20",
      "placeOfIssue": "MADRID",
      "firstIssue": "2015-03-21",
      "issueNumber": "01",
      "issuedBy": "ISSUER",
      "nfcValidated": "true",
      "residencePermitType": "C"
    },
    "reasonCode": null,
    "vendorData": "12345678",
    "decisionTime": "2019-11-06T07:18:36.916Z",
    "acceptanceTime": "2019-11-06T07:15:27.000Z",
    "additionalVerifiedData": {
      "driversLicenseCategory": {
        "B": true
      },
      "driversLicenseCategoryFrom": {
        "B": "2019-10-06"
      },
      "driversLicenseCategoryUntil": {
        "B": "2025-10-05"
      },
      "estimatedAge": 32,
      "estimatedGender": 0.613,
      "processNumber": "12345678912 1234",
      "driversLicenseNumber": "1234569"
    },
    "riskLabels": [
    {
      "label": "document_integration_level_crosslinked_with_fraud",
      "category": "document",
      "sessionIds": ["5a2358e7-fd31-4fcb-a23f-4d76651ba68a"]
    },
    {
      "label": "document_integration_level_crosslinked_with_multiple_declines",
      "category": "document",
      "sessionIds": ["fd5c1563-1d23-4b1a-ae46-7ba429927ed8"],
      "riskScore": 0.97
    }],
    "biometricAuthentication": {
      "matchedSessionId": "d40edb60-6ae6-4475-be72-84b81669cce6",
      "matchedSessionVendorData": "User001"
    }
  },
  "technicalData": {
    "ip": "186.153.67.122"
  }
}

GET /sessions/{sessionId}/person

Returns personal information objects about a person (hereinafter the Person) associated with the specific sessionId.

Request

Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/person' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14' \
Node.js
var request = require('request');

var options = { method: 'GET',
  url: '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/person',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/person'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response from the data provider
{
    "status": "success",
    "person": {
        "id": "b00a203e-2524-4ded-867b-b4e281a2c96b",
        "firstName": "MUAMMAR GADDAFI",
        "lastName": null,
        "idCode": "062.449.269-94",
        "dateOfBirth": "1942-09-22",
        "gender": null,
        "nationality": null,
        "placeOfBirth": null,
        "citizenships": [],
        "pepSanctionMatches": [
          {
            "provider": "Comply Advantage",
            "numberOfMatches": 1,
            "date": "2022-07-12T12:42:30.573Z",
            "matches": [],
            "hits": [
                {
                    "doc": {
                      "id": "4KJL9THDX9ZNV4W",
                      "lastUpdatedUtc": "2022-07-09T12:50:34Z",
                      "createdUtc": "2020-03-17T19:32:58Z",
                      "fields": [
                        {
                          "name": "Original Country Text",
                          "source": "world-bank-star-asset-recovery-watch",
                          "value": "European Union"
                        },
                        {
                          "name": "Nationality",
                          "source": "complyadvantage",
                          "value": "Libya"
                        },
                        {
                          "name": "Original Place of Birth Text",
                          "source": "hong-kong-special-administrative-region-sanctions-issued-under-the-un-sanctions-ordinance",
                          "value": "Sirte"
                        },
                        {
                          "name": "Original Country Text",
                          "source": "complyadvantage",
                          "value": "East Africa"
                        }
                      ],
                      "types": [
                        "adverse-media",
                        "adverse-media-v2-cybercrime",
                        "adverse-media-v2-financial-aml-cft",
                        "adverse-media-v2-financial-difficulty",
                        "adverse-media-v2-fraud-linked",
                        "adverse-media-v2-general-aml-cft",
                        "adverse-media-v2-narcotics-aml-cft",
                        "adverse-media-v2-other-minor",
                        "adverse-media-v2-other-serious",
                        "adverse-media-v2-property",
                        "adverse-media-v2-terrorism",
                        "adverse-media-v2-violence-aml-cft",
                        "adverse-media-v2-violence-non-aml-cft",
                        "pep",
                        "pep-class-1",
                        "pep-class-2",
                        "sanction",
                        "warning"
                      ],
                      "name": "Mouammar Mohammed Abu Minyar Kadhafi",
                      "entityType": "person",
                      "aka": [
                        {
                          "name": "Moamarr Qaddafi"
                        },
                        {
                          "name": "Moammar Kaddafi"
                        },
                        {
                          "name": "Muammer al Gaddafi"
                        },
                        {
                          "name": "মোৱাম্মাৰ গাড্ডাফি"
                        },
                        {
                          "name": "Moammar Khadafi"
                        }
                      ],
                      "associates": [
                        {
                          "association": "spouse",
                          "name": "Fatiha al-Nuri"
                        },
                        {
                          "association": "spouse",
                          "name": "Fatiha al-Nuri Gaddafi"
                        },
                        {
                          "association": "child",
                          "name": "Qadhafi Muammar Mohammed Abu Minyar"
                        },
                        {
                          "association": "spouse",
                          "name": "Safia el-Brasai"
                        },
                        {
                          "association": "spouse",
                          "name": "Safia el-Brasai Gaddafi"
                        }
                      ],
                      "sources": [
                        "argentina-ministerio-de-relaciones-exteriores-y-culto-sanciones-de-la-onu",
                        "belarus-state-security-agency-list-of-organizations-and-individuals-involved-in-terrorist-activities"
                      ],
                      "keywords": [],
                      "media": [
                        {
                          "date": "2021-11-16T00:00:00Z",
                          "snippet": "Sang Tan Judges in the High Court in London have ruled that Saleh Ibrahim Mabrouk, a former aide of Libyan leader Colonel Muammar Gaddafi, was partly to blame for the murder of PC Yvonne Fletcher. The gunman",
                          "title": "'Justice at Last': Former Gaddafi Aide Found Liable for 1984 Police Officer Murder by UK High Court - 16.11.2021, Sputnik International",
                          "url": "https://sputniknews.com/amp/20211116/justice-at-last-former-gaddafi-aide-found-liable-for-1984-police-officer-murder-by-uk-high-court-1090775876.html"
                        }
                      ],
                      "assets": [
                        {
                          "publicUrl": "http://complyadvantage-asset.s3.amazonaws.com/76993a49-2d1e-4397-9e35-1e20f2b7dfa8.pdf",
                          "source": "world-bank-star-asset-recovery-watch",
                          "type": "pdf"
                        }
                      ],
                      "sourceNotes": {
                        "argentinaMinisterioDeRelacionesExterioresYCultoSancionesDeLaOnu": {
                          "amlTypes": [
                            "sanction"
                          ],
                          "listingStartedUtc": "2019-09-26T00:00:00Z",
                          "name": "Argentina Ministerio de Relaciones Exteriores y Culto Sanciones de la ONU",
                          "url": "https://www.cancilleria.gob.ar/es/politica-exterior/seguridad-internacional/comite-de-sanciones"
                        },
                        "belarusStateSecurityAgencyListOfOrganizationsAndIndividualsInvolvedInTerroristActivities": {
                          "amlTypes": [
                            "sanction"
                          ],
                          "listingStartedUtc": "2019-08-28T00:00:00Z",
                          "name": "Belarus State Security Agency List of Organizations and Individuals Involved in Terrorist Activities",
                          "url": "http://kgb.by/ru/perechen-inf-ru/"
                        },
                        "complyadvantageAdverseMedia": {
                          "amlTypes": [
                            "adverse-media",
                            "adverse-media-v2-cybercrime",
                            "adverse-media-v2-financial-aml-cft",
                            "adverse-media-v2-financial-difficulty",
                            "adverse-media-v2-fraud-linked",
                            "adverse-media-v2-general-aml-cft",
                            "adverse-media-v2-narcotics-aml-cft",
                            "adverse-media-v2-other-minor",
                            "adverse-media-v2-other-serious",
                            "adverse-media-v2-property",
                            "adverse-media-v2-terrorism",
                            "adverse-media-v2-violence-aml-cft",
                            "adverse-media-v2-violence-non-aml-cft"
                          ],
                          "countryCodes": [
                            "AE",
                            "AM",
                            "AR"
                          ],
                          "name": "ComplyAdvantage Adverse Media"
                        },
                        "dfatAustraliaList": {
                          "amlTypes": [
                            "sanction"
                          ],
                          "countryCodes": [
                            "LY",
                            "OM"
                          ],
                          "listingStartedUtc": "2011-02-26T00:00:00Z",
                          "name": "DFAT Australia Consolidated Sanctions List",
                          "url": "https://www.dfat.gov.au/international-relations/security/sanctions/Pages/consolidated-list.aspx"
                        }
                      },
                    },
                  "matchTypes": [
                    "aka_exact",
                    "year_of_birth"
                  ],
                  "matchTypesDetails": {
                    "gaddafiMuammar": {
                      "matchTypes": {
                        "gaddafi": [
                          "name_exact"
                        ],
                        "muammar": [
                          "name_exact"
                        ]
                      },
                      "type": "aka"
                    },
                    "muammarGaddafi": {
                      "matchTypes": {
                        "gaddafi": [
                          "name_exact"
                        ],
                        "muammar": [
                          "name_exact"
                        ]
                      },
                      "type": "aka"
                    }
                  },
                  "matchStatus": "potential_match",
                  "isWhitelisted": false,
                  "score": 24.46217
                }
            ]
         }
      ]
   }
}

GET /sessions/{sessionId}/media

Returns a list of media objects with sessionId = {sessionId}

The list of objects are sorted based on their accuracy (e.g., does an image match the required image type) and their quality. The order is determined by the automation system.

Note that the request will return the media objects of the most recent attempt. If you require the media of a certain attempt, you can call the list of attemptId-s with GET session/{sessionId}/attempts and then use the GET attempts/{attemptId}/media to get the media of a specific attempt.

Request

Request method: GET
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14'
Node.js
var request = require('request');

var options = { method: 'GET',
  url: '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/media'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
{
  "status": "success",
  "videos": [
    {
      "context": "{VIDEO_TYPE}",
      "duration": "{DURATION_IN_SECONDS}",
      "id": "{MEDIA_ID}",
      "mimetype": "{MEDIA_MIME_TYPE}",
      "name": "{VIDEO_NAME}",
      "sessionId": "{SESSIOND_ID}",
      "size": "{SIZE_IN_B}",
      "timestamp": (Deprecated) null,
      "url": "{MEDIA_DOWNLOAD_URL}"
    }
  ],
  "images": [
    {
      "context": "{IMAGE_TYPE}",
      "id": "{MEDIA_ID}",
      "name": "{IMAGE_NAME}",
      "url": "{MEDIA_DOWNLOAD_URL}",
      "sessionId": "{SESSIOND_ID}",
      "timestamp": (Deprecated) null,
      "size": "{SIZE_IN_B}",
      "mimetype": "{MEDIA_MIME_TYPE}"
    }
  ]
}

GET /sessions/{sessionId}/watchlist-screening

Returns a list of data objects from PEP and Sanctions services for specific sessionId.

Only available for customers using the Veriff PEP and Sanctions services.

Request

Request method: GET
Media type: application/json
Type: object.
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = session signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/watchlist-screening' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14' \
Node.js
var request = require('request');

var options = { method: 'GET',
  url: '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/watchlist-screening',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/watchlist-screening'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
No match
{
    "status": "success",
     "data": {
         "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
         "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
         "vendorData": null,
         "checkType": "initial_result",
         "matchStatus": "no_match",
         "searchTerm": {
             "name": "Juan Rico"
         },
         "totalHits": 0,
         "createdAt": "2021-06-15T08:27:33.015Z",
         "hits": []
     }
}
Possible match
{
    "status": "success",
    "data": {
        "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
        "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
        "vendorData": null,
        "checkType": "updated_result",
        "matchStatus": "possible_match",
        "searchTerm": {
            "name": "Mirko Kokki",
            "year": "1960"
        },
        "totalHits": 1,
        "createdAt": "2021-07-05T13:23:59.851Z",
        "hits": [{
            "matchedName": "Miro kokkino",
            "countries": [
                "Australia",
                "Brazil"
            ],
            "dateOfBirth": "1963",
            "dateOfDeath": null,
            "matchTypes": [
                "aka_exact",
                "year_of_birth"
            ],
            "aka": [
                "Mirkoni kokki",
                "Mirkor Kokki"
            ],
            "associates": [
                "Desmon Lamela",
                "Fred Austin"
            ],
            "listingsRelatedToMatch": {
                "warnings": [{
                    "sourceName": "FBI Most Wanted",
                    "sourceUrl": "http://www.fbi.gov/wanted",
                    "date": null
                }],
                "sanctions": [{
                    "sourceName": "Argentina Ministerio de Relaciones Exteriores y Culto Sanciones de la ONU",
                    "sourceUrl": "https://www.cancilleria.gob.ar/es/politica-exterior/seguridad-internacional/comite-de-sanciones",
                    "date": null
                }],
                "fitnessProbity": [],
                "pep": [{
                    "sourceName": "United Kingdom Insolvency Service Disqualified Directors",
                    "sourceUrl": "https://www.insolvencydirect.bis.gov.uk/IESdatabase/viewdirectorsummary-new.asp",
                    "date": null
                }],
                "adverseMedia": [{
                    "sourceName": "SNA's Old Salt Award Passed to Adm. Davidson",
                    "sourceUrl": "https://www.marinelink.com/amp/news/snas-old-salt-award-passed-adm-davidson-443093",
                    "date": null
                }]
            }
        }]
    }
}
Failed response
{
    "status": "fail",
    "code": "1818",
    "message": "Signature \"334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14\" does not match the HMAC-SHA256 of query ID and integration API secret."
}

DELETE /sessions/{sessionId}

Method to request deletion of a session, a session is eligible for deletion on created, started, abandoned, expired, approved, resubmission_requested, declined, inflow_completed, review statuses. Attempting to delete the session in other statuses will respond with the Session is not in a completed status. error message. The availability of this feature is optional, depending on integration.

If session status is one of the following created, started or resubmission_requested a decision webhook with expired/abandoned status will be sent. After successful request, session will immediately become unavailable in Station and API. Data will be deleted within 12 hours.

Rate-limit is: 10 sessions per 24 hours and 5 sessions per 1 hour.

Request

Request method: DELETE
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X DELETE \
  --url '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: dd994f70b1150ae012f9c1d6d20adf7ed69780044835d39de20b00ffae0660a0'
Node.js
var request = require('request');

var options = { method: 'DELETE',
  url: '/v1/sessions/fd5c1563-1d23-4b1a-ae46-7ba429927ed8',
  headers: {
     'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': 'dd994f70b1150ae012f9c1d6d20adf7ed69780044835d39de20b00ffae0660a0',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY'
  },
 };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/sessions/{sessionId}'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': 'dd994f70b1150ae012f9c1d6d20adf7ed69780044835d39de20b00ffae0660a0',
    'Content-Type': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Successful response

Response HTTP status code: 202 Accepted
Response body:

{
    "status": "success",
    "verification": {
        "id": "fd5c1563-1d23-4b1a-ae46-7ba429927ed8"
    }
}
Failed responses

Response HTTP status code: 400 Bad Request
Response body:

{
    "status": "fail",
    "code": "1305",
    "message": "Session is not in a completed status."
}

Response HTTP status code: 400 Bad Request
Response body:

{
    "status": "fail",
    "code": "1306",
    "message": "Session in progress."
}
Limited access response

Response HTTP status code: 429 Too Many Requests
Response body:

{
    "status": 429,
    "code": "1004",
    "message": "Too many requests",
}

GET /attempts/{attemptId}/media

Returns a list of media objects with attemptId = {attemptId}

The list of objects are sorted based on their accuracy (e.g., does an image match the required image type) and their quality. The order is determined by the automation system.

Request

Request method: GET
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = attemptId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/attempts/f5c68aea-7f4d-478d-80ab-ca9356074f69/media' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36' \
Node.js
var request = require('request');

var options = { method: 'GET',
  url: '/v1/attempts/f5c68aea-7f4d-478d-80ab-ca9356074f69/media',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': 'acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/attempts/f5c68aea-7f4d-478d-80ab-ca9356074f69/media'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': 'acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
{
  "status": "success",
  "videos": [
    {
      "context": "{VIDEO_TYPE}",
      "id": "{MEDIA_ID}",
      "name": "{VIDEO_NAME}",
      "duration": "{DURATION_IN_SECONDS}",
      "url": "{MEDIA_DOWNLOAD_URL}",
      "timestamp": (Deprecated) null,
      "size": "{SIZE_IN_B}",
      "mimetype": "{MEDIA_MIME_TYPE}"
    }
  ],
  "images": [
    {
      "context": "{IMAGE_TYPE}",
      "id": "{MEDIA_ID}",
      "name": "{IMAGE_NAME}",
      "url": "{MEDIA_DOWNLOAD_URL}",
      "timestamp": (Deprecated) null,
      "size": "{SIZE_IN_B}",
      "mimetype": "{MEDIA_MIME_TYPE}"
    }
  ]
}

GET /media/{mediaId}

Returns media file with mediaId = {mediaId}.
To get the mediaId of a specific media file, request a list of media with GET attempts/{attemptId}/media or session/{sessionId}/media.

Request

Request method: GET
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = mediaId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/media/ebbf6434-3bf1-4020-8ac3-1ef51a25c673' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b' \
Node.js
var request = require('request');

var options = { method: 'GET',
  url: '/v1/media/ebbf6434-3bf1-4020-8ac3-1ef51a25c673',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests

url = '/v1/media/ebbf6434-3bf1-4020-8ac3-1ef51a25c673'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
print(response.content)

Response

Headers

X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Response body signed with the shared secret key
TRANSFER-ENCODING: string (required) Form of encoding used to safely transfer the payload body

Sample response
Transfer-Encoding: chunked
Sample chunked data handling /media/{mediaId}

Sample how to store response data to file (image or video)

Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = mediaId signed with the shared secret key
mediaId: string (required) mediaId To get the mediaId of a specific media file, request a list of media with GET attempts/{attemptId}/media or session/{sessionId}/media

Node.js

Here is a simple example how to download media with Node.js, it is applicable for both video and image files. Just make sure to use correct file extension which can be found from /media api response

const fs = require('fs');
const request = require('request');

var options = { method: 'GET',
  url: '/v1/media/ebbf6434-3bf1-4020-8ac3-1ef51a25c673',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);
}).pipe(fs.createWriteStream(__dirname+'/myMedia.jpeg'));
Video files sample
media_url = '/v1/media/05cfc122-15d8-4838-bbf1-7b26a736b2d2'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'Content-Type': 'application/json',
}

response = requests.get(media_url, headers=headers)

with open('media_filename.webm', 'wb') as media_file:
    for chunk in response.iter_content():
        media_file.write(chunk)
Image files sample
media_url = '/v1/media/2b3b3a9f-d73d-445a-aabe-9b41c1c1a2ac'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'Content-Type': 'application/json',
}

response = requests.get(media_url, headers=headers)
with open('image_file_name.jpg', 'wb') as write_file:
    write_file.write(response.content)

GET /transportation-registry/{attemptId}

Returns a list of transportation registry results with attemptId = {attemptId}

Request

Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Attempt ID signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/transportation-registry/f5c68aea-7f4d-478d-80ab-ca9356074f69' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36' \
Node.js
var request = require('request');

var options = {
  method: 'GET',
  url: '/v1/transportation-registry/f5c68aea-7f4d-478d-80ab-ca9356074f69',
  headers:
   {
     'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': 'acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/transportation-registry/f5c68aea-7f4d-478d-80ab-ca9356074f69'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': 'acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
{
  "rightToDrive": {
    "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
    "reason": "Expired right to drive",
    "status": "invalid",
    "validUntil": "2016-08-31",
  },
}

GET /address/{addressId}/media

Returns a list of media objects with addressId = {addressId} for Proof of Address sessions.

Request

Request method: GET
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = addressId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/address/f087f21f-5282-41b8-9857-6f85c28b8122/media' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36' \
Node.js
var request = require('request');

var options = { method: 'GET',
  url: '/v1/address/f087f21f-5282-41b8-9857-6f85c28b8122/media',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': 'acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests
import json
import pprint

url = '/v1/address/f087f21f-5282-41b8-9857-6f85c28b8122/media'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': 'acfe1cf21c986edf25cc6bc74fd769954443bbb606500019a4bed46645179b36',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
{
  "status": "success",
  "images": [
    {
      "context": "{IMAGE_TYPE}",
      "id": "{MEDIA_ID}",
      "name": "{IMAGE_NAME}",
      "url": "{MEDIA_DOWNLOAD_URL}",
      "timestamp": null,
      "size": "{SIZE_IN_B}",
      "mimetype": "{MEDIA_MIME_TYPE}"
    }
  ]
}

GET /address-media/{mediaId}

Returns the media for Proof of Address with mediaId = {mediaId}

Request

Request method: GET
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = mediaId signed with the shared secret key
Content-Type: application/json

Sample request
curl
curl -X GET \
  --url '/v1/address-media/8d79522f-e3ad-4c1f-8e6a-4248db6935a2' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b' \
Node.js
var request = require('request');

var options = { method: 'GET',
  url: '/v1/address-media/8d79522f-e3ad-4c1f-8e6a-4248db6935a2',
  headers:
   { 'Content-Type': 'application/json',
     'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
     'X-AUTH-CLIENT': 'API-PUBLIC-KEY' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3.py
import requests

url = '/v1/address-media/8d79522f-e3ad-4c1f-8e6a-4248db6935a2'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'Content-Type': 'application/json'
}

response = requests.request('GET', url, headers=headers)
print(response.content)

Response

Headers:
 X-AUTH-CLIENT: string (required) API key
X-HMAC-SIGNATURE: string (required) Response body signed with the shared secret key
TRANSFER-ENCODING: string (required) Form of encoding used to safely transfer the payload body.

Sample response
Transfer-Encoding: chunked
Sample chunked data handling /address-media/{mediaId}

Sample how to store response data to file (image or video)

Headers:
 X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = mediaId signed with the shared secret key

Node.js

Here is a simple example how to download address media with Node.js. Just make sure to use correct file extension, which can be found from /media api response.

const fs = require('fs');
const request = require('request');

var options = {
  method: 'GET',
  url: '/v1/address-media/8d79522f-e3ad-4c1f-8e6a-4248db6935a2',
  headers: {
    'Content-Type': 'application/json',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
}).pipe(fs.createWriteStream(__dirname + '/myMedia.jpeg'));
Image files sample
media_url = '/v1/address-media/8d79522f-e3ad-4c1f-8e6a-4248db6935a2'

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'Content-Type': 'application/json',
}

response = requests.get(media_url, headers=headers)
with open('image_file_name.jpg', 'wb') as write_file:
    write_file.write(response.content)

POST /validate-registry

Validates a national ID number (e.g. social security number (SSN)) with the provided data. A verification session will be automatically created and submitted after which the validation result gets sent via Webhook. Note that media upload is not used for registry verification.

You will need a separate integration to do this verification (i.e., the integration you have for IDV will not suffice.)

In order to perform a social security number (SSN) validation the following fields must be provided:

Request

Request method: POST
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string = Request body signed with the shared secret key
Content-Type: application/json

Request properties explained
Sample request
curl
curl -X POST \
  --url '/v1/validate-registry/' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -d '{
    "verification": {
        "callback": "https://veriff.com",
        "person": {
            "firstName": "John",
            "lastName": "Smith",
            "idNumber": "123456789",
            "dateOfBirth": "1980-03-06"
        },
        "address": {
            "street": "Street 123",
            "houseNumber": "456"
        },
        "vendorData": "11111111"
    }
}'
Node.js
var request = require('request');

var options = { method: 'POST',
    url: '/v1/validate-registry/',
    headers:
            { 'Content-Type': 'application/json',
                'X-AUTH-CLIENT': 'API-PUBLIC-KEY' },
    body:
            { verification:
                        { callback: 'https://veriff.com',
                            person:{
                                firstName: 'John',
                                lastName: 'Smith',
                                idNumber: '123456789',
                                dateOfBirth: "1980-03-06"
                            },
                            address: {
                                street: 'Street 123',
                                houseNumber: '456'
                            },
                            vendorData: '11111111' } },
    json: true };

request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
Python3
import requests
import pprint
import json

url = '/v1/validate-registry/'

payload = json.dumps({
    'verification': {
        'callback': 'https://veriff.com',
        'person': {
            'firstName': 'John',
            'lastName': 'Smith',
            'idNumber': '123456789',
            'dateOfBirth': '1980-03-06'
        },
        'address': {
            'street': 'Street 123',
            'houseNumber': '456',
        },
        'vendorData': '11111111',
        'features': [
          'selfid'
        ]
    }
})

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'Content-Type': 'application/json'
}

response = requests.request('POST', url, data=payload, headers=headers)
pprint.pprint(response.json())

Response

Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample responses
Success, values in the form match
{
    "status": "success",
    "verification": {
        "id":"f04bdb47-d3be-4b28-b028-a652feb060b5",
        "vendorData": "11111111",
        "status": "submitted",
        "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoX3Rva2VuIjoiOThiYzdjMjEtZTQ0Yy00MTZiLTkxOTMtMTU5ZGZkMzBmMDg4Iiwic2Vzc2lvbl9pZCI6Ijc2ODhmMzYzLTAyZjctNDE1My1iMzM1LWE0ODQ3OTRkMzZmNyIsImlhdCI6MTUwMTIyODI1MSwiZXhwIjoxNTAxODMzMDUxfQ.bMEF37E6-zT2Aa6Q8UXK3B_ZL51w6D_lxnGgQvhj214"
    }
}
Status 400 "Bad request", firstName + lastName OR fullName not provided
{
    "status": "fail",
    "code": "1309",
    "message": "SSN validation requires person firstName + lastName OR fullName to be provided"
}
Status 400 "Bad request", idNumber not provided
{
  "status": "fail",
  "code": "1308",
  "message": "ID number is missing."
}
Status 400 "Bad request", dateOfBirth OR address not provided
{
  "status": "fail",
  "code": "1310",
  "message": "SSN validation requires person.dateOfBirth or address data to be provided."
}

POST sync-api.veriff.me/v1/validate-registry

Validates a national ID number (e.g. social security number (SSN)) with the provided data. A verification session will be automatically created and submitted after which the validation result gets sent in the API Response. Note that media upload is not used for registry verification.

You will need a separate integration to do this verification (i.e., the integration you have for IDV will not suffice.)

In order to perform a social security number (SSN) validation the following fields must be provided:

Request

Request method: POST
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-API-KEY: string (required) = API key
X-HMAC-SIGNATURE: string = Request body signed with the shared secret key
Content-Type: application/json

Request properties explained
Sample request
curl
curl -X POST \
  --url '/v1/validate-registry' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
  -H 'X-API-KEY: API-PUBLIC-KEY' \
  -H 'X-HMAC-SIGNATURE: 4776e5fb59795da4856c8176efcdeaf6fe15d0bed6a179e75c86a5f5580a250c' \
  -d '{
    "verification": {
        "person": {
            "firstName": "John",
            "lastName": "Smith",
            "idNumber": "123456789",
            "dateOfBirth": "1980-03-06"
        },
        "address": {
            "street": "Street 123",
            "houseNumber": "456",
            "postcode": "12345"
        },
        "vendorData": "11111111"
    }
}'
Node.js
var request = require('request');

var options = {
  method: 'POST',
  url: '/v1/validate-registry/',
  headers: {
    'Content-Type': 'application/json',
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-API-KEY': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '4776e5fb59795da4856c8176efcdeaf6fe15d0bed6a179e75c86a5f5580a250c',
  },
  body: {
    verification: {
      person: {
        firstName: 'John',
        lastName: 'Smith',
        idNumber: '123456789',
        dateOfBirth: '1980-03-06',
      },
      address: {
        street: 'Street 123',
        houseNumber: '456',
        postcode: '12345',
      },
      vendorData: '11111111',
    },
  },
  json: true,
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
Python3
import requests
import pprint
import json

url = '/v1/validate-registry/'

payload = json.dumps({
    'verification': {,
        'person': {
            'firstName': 'John',
            'lastName': 'Smith',
            'idNumber': '123456789',
            'dateOfBirth': '1980-03-06'
        },
        'address': {
            'street': 'Street 123',
            'houseNumber': '456',
            'postcode': '12345',
        },
        'vendorData': '11111111',
        'features': [
          'selfid'
        ]
    }
})

headers = {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-API-KEY': 'API-PUBLIC-KEY',
    'Content-Type': 'application/json',
    'X-HMAC-SIGNATURE': '4776e5fb59795da4856c8176efcdeaf6fe15d0bed6a179e75c86a5f5580a250c'
}

response = requests.request('POST', url, data=payload, headers=headers)
pprint.pprint(response.json())
Failed request validation scenarios

Two types of validation is done: X-HMAC-SIGNATURE and request payload validation. Below are possible failure scenarios.

X-HMAC-SIGNATURE validation failed

HTTP status code: 401
Message: "MissingAuthentication"

{
status: 'fail',
code: 1812,
message: 'Signature {invalid-hmac-signature value} is not a valid SHA256 hash.'
}

Required field fullName or (firstName + lastName) not provided

HTTP status code: 400
Message: "InvalidRequest"

{
status: 'fail',
code: 1102,
message: 'Request person is missing required field fullName or (firstName + lastName)'
}

Required field dateOfBirth or address not provided

HTTP status code: 400
Message: "InvalidRequest"

{
status: 'fail',
code: 1102,
message: 'Request is missing required field dateOfBirth or address'
}

Required field fullAddress or (street + houseNumber + postcode) not provided

HTTP status code: 400
Message: "InvalidRequest"

{
status: 'fail',
code: 1102,
message: 'Request address is missing required field fullAddress or (street + houseNumber + postcode)'
}

Required field idNumber not provided

HTTP status code: 400
Message: "InvalidRequest"

{
status: 'fail',
code: 1102,
message: 'Request is missing required field idNumber'
}

Response

Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Response body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample Response
Approved decision
{
  "status": "success",
  "verification": {
    "id": "09551b48-4d7c-4a30-8437-5301223953fa",
    "code": 9001,
    "person": {
      "gender": null,
      "idNumber": "123456789",
      "lastName": "Smith",
      "firstName": "John",
      "citizenship": null,
      "dateOfBirth": "1980-03-06",
      "nationality": null,
      "yearOfBirth": null,
      "placeOfBirth": null,
      "pepSanctionMatch": null
    },
    "reason": null,
    "status": "approved",
    "comments": [],
    "document": {
      "type": null,
      "number": null,
      "country": null,
      "validFrom": null,
      "validUntil": null
    },
    "reasonCode": null,
    "vendorData": null,
    "decisionTime": "2019-11-06T07:18:36.916Z",
    "acceptanceTime": "2019-11-06T07:15:27.000Z",
    "additionalVerifiedData": {}
  },
  "technicalData": {
    "ip": null
  }
}
Declined decision
{
    "status": "success",
    "verification": {
        "id": "5ca9d2b6-3708-4540-928e-4b8e82717c3f",
        "code": 9102,
        "person": {
            "gender": null,
            "idNumber": "123456789",
            "lastName": "Smith",
            "firstName": "John",
            "citizenship": null,
            "dateOfBirth": "1980-03-06",
            "nationality": null,
            "yearOfBirth": null,
            "placeOfBirth": null,
            "pepSanctionMatch": null
        },
        "reason": "Unable to validate National Id data",
        "status": "declined",
        "comments": [],
        "document": {
            "type": null,
            "number": null,
            "country": null,
            "validFrom": null,
            "validUntil": null
        },
        "reasonCode": 529,
        "vendorData": null,
        "decisionTime": "2019-11-06T07:18:36.916Z",
        "acceptanceTime": "2019-11-06T07:15:27.000Z",
        "additionalVerifiedData": {
            "failedValidation": "Neither address or date of birth matched"
        }
    },
    "technicalData": {
        "ip": null
    }
}

POST /sessions/{sessionId}/collected-data

Uploads information that has been collected for improved IDV process. The session must be either in created or started status.

Request

Request method: POST
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Request properties explained
Sample Request
curl

curl -X POST \
 --url '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/collected-data' \
  -H 'Content-Type: application/json' \
  -H 'X-AUTH-CLIENT: API key' \
  -H 'X-HMAC-SIGNATURE: 034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53' \ 
  -d '{
        "providerName": "SampleName",
        "person": {
            "email": "firstname.lastname@domain.com",
            "phoneNumber": "+11 222 333 44"
        },
        "network": {
            "mobileCarrier": "RandomTeleCom Inc",
            "ssid": "12345",
            "hostname": "examplehostname.amazonaws.com",
            "location": {
                "countryCode": "US",
                "continentCode": "NA",
                "city": "New York",
                "region": "New York",
                "timezone": "EDT"
            },
            "ip": {
                "addressV4": "192.168.XXX.XXX"
            },
            "asn": {
                "number": "AS12345",
                "organisation": "AWS"
            }
        },
        "device": {
            "fingerprint": "123456asdfg7890hijkl123456asdfg7890hijkl123456asdfg7890hijkl",
            "androidId": "ab1357cd-a1b2-c3d4-f5g6",
            "idfv": "F325G3GB-12FC-352F-C6C3-DZ52F0F690D8",
            "model": "Samsung Galaxy S23 Ultra",
            "vendor": "Samsung",
            "type": "mobile",
            "browser": {
                "languages": ["en-gb"],
                "timezoneOffsetMinutes": -240,
                "isIncognito": false
            },
            "screen": {
                "heightPixels": 3088,
                "widthPixels": 1440,
                "dpi": 500
            },
            "battery": {
                "level": 0.43,
                "charging": true
            },
            "os": {
                "family": "Android",
                "name": "Android",
                "version": "13"
            }
        }
    }'
Node.js
var request = require('request');

var options = {
  url: '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/collected-data',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
    'X-AUTH-CLIENT': 'API key' \
    'X-HMAC-SIGNATURE': '034c6da2bb31fd9e6892516c6d7b90ebe10f79b47cfb3d155d77b4d9b66e1d53'
  },
  body: {
    "providerName": "SampleName",
    "person": {
      "email": "firstname.lastname@domain.com",
      "phoneNumber": "+11 222 333 44"
    },
    "network": {
      "mobileCarrier": "RandomTeleCom Inc",
      "ssid": "12345",
      "hostname": "examplehostname.amazonaws.com",
      "location": {
        "countryCode": "US",
        "continentCode": "NA",
        "city": "New York",
        "region": "New York",
        "timezone": "EDT"
      },
      "ip": {
        "addressV4": "192.168.XXX.XXX"
      },
      "asn": {
        "number": "AS12345",
        "organisation": "AWS"
      }
    },
    "device": {
      "fingerprint": "123456asdfg7890hijkl123456asdfg7890hijkl123456asdfg7890hijkl",
      "androidId": "ab1357cd-a1b2-c3d4-f5g6",
      "idfv": "F325G3GB-12FC-352F-C6C3-DZ52F0F690D8",
      "model": "Samsung Galaxy S23 Ultra",
      "vendor": "Samsung",
      "type": "mobile",
      "browser": {
        "languages": ["en-gb"],
        "timezoneOffsetMinutes": -240,
        "isIncognito": false
      },
      "screen": {
        "heightPixels": 3088,
        "widthPixels": 1440,
        "dpi": 500
      },
      "battery": {
        "level": 0.43,
        "charging": true
      },
      "os": {
        "family": "Android",
        "name": "Android",
        "version": "13"
      }
    }
  }
},
json: true };

request(options, function (error, response, body) {
  if (error) {
    console.error('Error:', error);
  } else {
    console.log('Response:', body);
  }
});

Response

Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = Request body signed with the shared secret key
Content-Type: application/json

Response properties explained
Sample response
{
  "status": "success",
  "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "attemptId": "f5c68aea-7f4d-478d-80ab-ca9356074f69"
}

GET /sessions/{sessionId}/decision/ine-registry

Returns data about the INE identification number.

Request

Request properties explained

Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json (required)
Query parameters:
version: string (required) = the version number of the check

Sample request

Note: the examples below are for illustrative purposes only, and are using mock data for API URL and X-HMAC-SIGNATURE, and a placeholder for API-PUBLIC-KEY. You need to replace these with the actual values that you use.

curl
curl -X GET 'v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/ine-registry?version=1.0.0' \
-H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
-H 'X-HMAC-SIGNATURE: 334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14' \
-H 'Content-Type: application/json' \
Node.js
var request = require('request');
var url = '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/ine-registry?version=1.0.0';
var options = {
    method: 'GET',
    url: url,
    headers: {
        'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
        'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
        'Content-Type': 'application/json'
    }
};
request(options, function (error, response, body) {
    if (error) {
        console.error('Error:', error);
    } else {
        console.log('Response:', body);
    }
});
Python3.py
import requests
import json
import pprint
url = "/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/ine-registry"
headers = {
    "X-AUTH-CLIENT": "API-PUBLIC-KEY",
    "X-HMAC-SIGNATURE": "334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14",
    "Content-Type": "application/json"
}
params = {
    "version": "1.0.0"
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
    data = json.loads(response.text)
    pprint.pprint(data)
else:
    print(f"Error: {response.status_code}")

Response

Headers

X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = payload signed with the shared secret key
Content-Type: application/json

Response properties explained

Note: in the respective jurisdiction, an active = true credential can be used for identification and related activities; an active = false credential could still be in the database, but it cannot be used for identification and related activities.

Sample Response
{
    "active": false,
    "documentState": "No se obtuvieron datos de la consulta con los parámetros seleccionados"
}

GET /sessions/{sessionId}/decision/curp-registry

Returns the check result with CURP identification number and status.

Request

Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json (required)
Query parameters:
version: string (required) = the version number of the check

Sample request

Note: the examples below are for illustrative purposes only, and are using mock data for API URL and X-HMAC-SIGNATURE, and a placeholder for API-PUBLIC-KEY. You need to replace these with the actual values that you use.

curl
curl -X GET 'v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/curp-registry?version=1.0.0' \
-H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
-H 'X-HMAC-SIGNATURE: 334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14' \
-H 'Content-Type: application/json' \
Node.js
var request = require('request');
var url = '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/curp-registry?version=1.0.0';
var options = {
  method: 'GET',
  url: url,
  headers: {
    'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
    'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
    'Content-Type': 'application/json'
    }
};
request(options, function (error, response, body) {
  if (error) {
    console.error('Error:', error);
  } else {
    console.log('Response:', body);
  }
});
Python3.py
import requests
import json
import pprint
url = "/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/curp-registry"
headers = {
    "X-AUTH-CLIENT": "API-PUBLIC-KEY",
    "X-HMAC-SIGNATURE": "334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14",
    "Content-Type": "application/json"
}
params = {
    "version": "1.0.0"
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
    data = json.loads(response.text)
    pprint.pprint(data)
else:
    print(f"Error: {response.status_code}")

Response

Headers

X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = payload signed with the shared secret key
Content-Type: application/json

Response properties explained

Full forms of the statusCurp acronyms

Active CURP: AN (Alta Normal), AH (Alta con Homonimia), CRA CU (CURP Reactivada), RCN (Registro de Cambio no Afectando a CURP), RCC (Registro de Cambio Afectando a CURP)

For inactive CURP: BD (Baja por Defuncion), BDA (Baja por Duplicidad), BCC (Baja por Cambio en CURP), BCN (Baja no Afectando a CURP)

Sample Response
{
    "statusCurp": "RCN",
    "curp": "FOHJ920625HGTLRR06"
}

GET /sessions/{sessionId}/decision/combined-ine-curp-registry

Returns combined result of INE/IFE and CURP.

Request

Request properties explained

Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json (required)
Query parameters:
version: string (required) = the version number of the check

Sample request

Note: the examples below are for illustrative purposes only, and are using mock data for API URL and X-HMAC-SIGNATURE, and a placeholder for API-PUBLIC-KEY. You need to replace these with the actual values that you use.

curl
curl -X GET 'v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/combined-ine-curp-registry?version=1.0.0' \
-H 'X-AUTH-CLIENT: API-PUBLIC-KEY' \
-H 'X-HMAC-SIGNATURE: 334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14' \
-H 'Content-Type: application/json' \
Node.js
var request = require('request');
var url = '/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/combined-ine-curp-registry?version=1.0.0';
var options = {
    method: 'GET',
    url: url,
    headers: {
        'X-AUTH-CLIENT': 'API-PUBLIC-KEY',
        'X-HMAC-SIGNATURE': '334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14',
        'Content-Type': 'application/json'
    }
};
request(options, function (error, response, body) {
    if (error) {
        console.error('Error:', error);
    } else {
        console.log('Response:', body);
    }
});
Python3.py
import requests
import json
import pprint
url = "/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/combined-ine-curp-registry"
headers = {
    "X-AUTH-CLIENT": "API-PUBLIC-KEY",
    "X-HMAC-SIGNATURE": "334141f052e317fde6668de54dc6640b4a5c47582ad86a8bed63afe566f17b14",
    "Content-Type": "application/json"
}
params = {
    "version": "1.0.0"
}
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
    data = json.loads(response.text)
    pprint.pprint(data)
else:
    print(f"Error: {response.status_code}")

Response

Headers

X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = payload signed with the shared secret key
Content-Type: application/json

Response properties explained
Full forms of the statusCurp acronyms

Active CURP: AN (Alta Normal), AH (Alta con Homonimia), CRA CU (CURP Reactivada), RCN (Registro de Cambio no Afectando a CURP), RCC (Registro de Cambio Afectando a CURP)

For inactive CURP: BD (Baja por Defuncion), BDA (Baja por Duplicidad), BCC (Baja por Cambio en CURP), BCN (Baja no Afectando a CURP)

Sample Response
{
  "type": "combined-ine-curp-registry",
  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "vendorData":  "1234567812345678",
  "version": "1.0.0",
  "data": {
      "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
      "name": "combined-ine-curp-registry",
      "status": "found",
      "code": 200,
      "details": {
        "ine": {
            "active": true,
            "status": "La credencial esta vigente",
            "comments": [
                "CIC 000000000\r\nClave de elector JRLGLS00000000H000\r\nNúmero de emisión 1\r\nDistrito Federal 3\r\nDistrito Local 4\r\nNúmero OCR 0000000000000\r\nAño de registro 2009\r\nAño de emisión 2020",
                "Fecha de actualización de la información: 10 de agosto del 2023 19:48",
                "Fecha de consulta: 11 de agosto del 2023",
                "Tus datos se encuentran en el Padrón Electoral, y también en la Lista Nominal de Electores"
            ],
            "information": "CIC 000000000\r\nClave de elector JRLGLS00000000H000\r\nNúmero de emisión 1\r\nDistrito Federal 3\r\nDistrito Local 4\r\nNúmero OCR 0000000000000\r\nAño de registro 2009\r\nAño de emisión 2020\r\nFecha de actualización de la información: 10 de agosto del 2023 19:48\r\nFecha de consulta: 11 de agosto del 2023\r\nEsta vigente como medio de identificación y puedes votar.\r\nTus datos se encuentran en el Padrón Electoral, y también en la Lista Nominal de Electores.\r\nSerá válida hasta el 31 de diciembre de 2030",
            "ifeIdentifier": "",
            "ineIdentifier": "000000000"
        },
        "curp": {
            "curp": "ABCD000000HVZRGS00",
            "names": "LOREM IPSUM",
            "gender": "HOMBRE",
            "regionCode": "VZ",
            "statusCurp": "RCN",
            "birthRegion": "Veracruz",
            "dateOfBirth": "06/04/1991",
            "nationality": "MEX",
            "firstSurname": "JUAREZ",
            "secondSurname": "LAGUNES",
            "docEvidenceData": {
                "book": "",
                "sheet": "",
                "volume": "",
                "actNumber": "00123",
                "registryCity": "",
                "regionRegistry": "30",
                "registrationYear": "1991",
                "registryCityCode": "125",
                "registryRegionCode": "VZ"
            },
            "documentEvidence": 1,
            "descriptionStatusCurp": "Registro de cambio no afectando a curp"
        }
    }
  }
}

Proof of Address Capture feature

Proof of Address Capture (PoA Capture) feature captures the submitted document. No further analysis is performed.

The flow is completed using several IDV endpoints.

Brief overview of the flow

  1. Submit a session using the POST sessions endpoint
  2. Make a POST /sessions/{sessionId}/media request to send image file
  3. Update the session status to "submitted" using the PATCH /sessions/{sessionId}
  4. Now you can now use the following endpoints to query the document info:
    • GET /sessions/{sessionId}/media
    • GET /attempts/{attemptId}/media
    • GET /media/{mediaId}

Step-by-step overview of the flow

Click on the step to expand.

Proof of Address Extraction feature

Proof of Address Extraction (PoA Extraction) feature captures the submitted document and extracts the firstName, fullAddress and document.validFrom data from it.

The flow is completed using several IDV endpoints.

Brief overview of the flow

  1. Submit a session using the POST sessions endpoint
  2. Make a POST /sessions/{sessionId}/media request to send image file
  3. Update the session status to "submitted" using the PATCH /sessions/{sessionId}
  4. Wait for the session to be approved and decision webhook to send response
  5. Now you can now use the following endpoints to query the document info:
    • GET /sessions/{sessionId}/media
    • GET /attempts/{attemptId}/media
    • GET /media/{mediaId}

Step-by-step overview of the flow

Click on the step to expand.

API requests signing with X-HMAC-SIGNATURE

X-HMAC-SIGNATURES are a security measure, which we generate for the API requests and webhook listeners, to make sure that the exchanged data has not been tampered with.

If you are familiar with the signing concept, jump to the Generate X-HMAC-SIGNATURE section. Here you find:

If you want a conceptual overview of the feature, we recommend taking a look at this What is an X-HMAC-SIGNATURE? section.

Generate an X-HMAC-SIGNATURE

Prerequisites for live requests signing

If you want to generate the X-HMAC-SIGNATURE for an actual API request, have the following info at hand and use these in your preferred signature generation tool:

If you are unsure which method you want to use, the Options to generate a X-HMAC-SIGNATURE section lists some options. You can use the mock data here to test them in your local machine.

Mock data for local testing

If you want to test the signature generation options locally, you can use the following mock shared secret key and mock payload.

Mock shared secret key: 

abcdef12-abcd-abcd-abcd-abcdef012345

POST /sessions request mock payload (as .json): 

{"verification":{"callback":"https://veriff.com","person":{"firstName":"John","lastName":"Smith"},"document":{"type":"PASSPORT","country":"EE"},"vendorData":"unique id of the end-user","timestamp":"2016-05-19T08:30:25.597Z"}}

If your preferred method is correct, you should get the following mock X-HMAC-SIGNATURE: 

0dcab73ddd20062616d104231c7439657546a5c24e4691977da93bb854c31e25

Note: to generate an actual signature for your live API requests, the Headers explanation in each API request’s section tells you what to use as payload for encryption.

Options to generate a X-HMAC-SIGNATURE

There are several ways to do that:

Scripts

Command-line tools

Built-in crypto libraries

Online tools

Validate X-HMAC-SIGNATURE locally

Below are few examples how to validate the generated X-HMAC-SIGNATURE.

What is an X-HMAC-SIGNATURE?

This section aims to explain the nature and use of X-HMAC-SIGNATURES and webhook listeners, and describe the reasons why it is important to implement them.

Verification Session lifecycle diagram

Sessions Lifecycle

Webhooks

To handle the response from Veriff services, you will need to implement an endpoint that accepts payloads posted by our services. Please note that Veriff does not allow custom ports to be added to the webhook URLs.

Note about order of delivery: to follow the best practices, we do not guarantee that the webhooks are delivered in the order in which they are generated. Therefore, you should not expect to receive them in that order either, and should implement a logic to handle this accordingly.

Configuring the webhook endpoint

Go to Veriff Station, Integrations -> Find the integration to configure -> Settings, and set one of the webhook URLs to the URL where your endpoint is accepting payloads from Veriff. There are several types of webhooks.
Veriff will post payloads to respective webhook URLs.

If there is a network connectivity issue or technical issue with delivering the notification (any non-200 response code), Veriff will try to resent the failed webhook for up to a week.

Recognizing your end-user

When your server receives a payload from Veriff, you need to be able to reference a end-user.
There are a couple of ways to do this.

Using the Veriff session ID

The easiest way is to track the session ID provided by Veriff during session creation. All future webhooks payloads refer to the attempt ID. The attempt ID is unique for each session, and it can be used to look up sessions in Station interface [🡕].

Using your own end-user ID

To use your own end-user ID you need to provide your internal end-user ID to Veriff, or some other key that uniquely identifies your end-user. You can store your identifier in the vendorData property during the session creation. Please bear in mind that it is technically possible for one end-user to be associated with multiple verification sessions, and this could potentially create ambiguous situations in code, if you are only recognizing end-users by your own identifier, and not Veriff's session ID.

Handling security

It is important to check that the webhook responses do indeed originate from Veriff. For that we use the X-HMAC-SIGNATURE header, which value is an HMAC-SHA256 hex encoded keyed hash using your API private key.

Different webhook types

There are several webhook types to help you to tailor your service specifically to your needs.

Meaning of the various verification responses

Verification status is one of

Verification response code is one of 9001, 9102, 9103, 9104, 9121 All codes and explanations can be found from Verification session decision codes

Explanation of the meaning of the response codes: Meaning of the various event codes

Lifecycle of the verification session

Responses 9001, 9102, 9121 and 9104 are conclusive responses. The session is closed and the URL is not available for the end-user.

Response 9103 is an inconclusive response. The session remains open until you receive one of the above conclusive responses. The session is re-opened for the end-user, accepting a new attempt.

Preconditions for approval decisions

We give a positive conclusive decision (status approved, code 9001) when the end-user has provided us with:

Accessing the KYC session URL again will tell the end-user that nothing more is to be done.

Reasons for negative conclusive decisions

A negative decision means that the person has not been verified. The verification process is complete. Either it was a fraud case or some other severe reason that the person can not be verified. You should investigate the session further and read the "reason". If you decide to give the client another try you need to create a new session.

Reasons for inconclusive decisions

Final decisions

You have the right to make the final decision about verifying an end-user even after they have completed the verification process with Veriff. In order for you to make the final decision, we recommend you create an appropriate functionality in your back-end. This will enable you to either approve or reject applications after the person has completed Veriff’s verification session. When you perform additional checks outside of Veriff’s service, it is necessary to have another layer of decision making. The decision has to be motivated based on further checks or extra information independent of Veriff’s decision. The additional verification details can be determined in accordance with your business needs and the amount of data and background information available to you about the end-user.

Potential use cases:

Veriff provides a more standardized solution where unconventional end-user behavior is not deferred to for the benefit of overall decision quality.

Meaning of the various event codes

{
  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "feature": "selfid",
  "code": 7002,
  "action": "submitted",
  "vendorData": "QWE123"
}

The event webhook informs you about the progress of the verification or proof of address data gathering. However, it does not inform you of the decision.

The event code can be one of:

For verification:

For proof of address:

Storing verification media

For businesses which are regulated by various KYC and AML laws and rules, storing proof of the end-user's verification is often a requirement. While Veriff stores and holds the end-user's media - photos and videos - it might also be mandatory and more convenient for the business to store this media internally.

First, you need to get the sessionId of a session you want to download the media for. This can be found from the decision webhook (parameter "id") which is automatically sent after a decision has been made for a verification session. With the sessionID, make a GET request to /sessions/{sessionId}/media endpoint. From there, you will find a mediaId for every media file we have stored.

With the mediaId-s, you can make a GET request to /media/{mediaId} endpoint to get the media file in .jpeg or .mp4 format. A separate request will have to be made for each media file.

Automating the download of photo and video files associated with completed verifications.

/sessions/{sessionId}/media First, query for a list of files using a GET request to /media/{mediaId} The response to your GET request to /sessions{sessionID}/media will be a list of videos and images related to this sessionID.

Second, the individual media files can be downloaded by using the mediaID returned in the first step with a GET request to /media/{mediaID}

Decision webhook

This is the description of the payload sent to Webhook decisions URL.
The result of the verification is sent back to the client once the verification has been processed.

In most cases we send decision webhook instantly after decision is made, with an exception to "resubmission_requested" status. In case resubmission is required, we allow end-user to resubmit session data instantly without a need to exit the flow. If end-user does not do it within 5 minutes, we'll send out webhook with resubmission_requested decision.

For the Driver License extraction of category 'valid from' and 'valid until' dates, please communicate with your solutions engineer to activate the feature.

Request properties explained:

Sample request

  {
    "status": "success",
    "verification": {
      "id": "12df6045-3846-3e45-946a-14fa6136d78b",
      "code": 9001,
      "person": {
        "gender": null,
        "fullName": "SARAH MORGAN",
        "idNumber": null,
        "firstName": "SARAH",
        "lastName": "MORGAN",
        "addresses": [
          {
            "fullAddress": "1234 Snowy Ridge Road, Indiana, 56789 USA",
            "parsedAddress": {
              "city": null,
              "unit": null,
              "state": "Indiana",
              "street": "1234 Snowy Ridge Road",
              "country": "USA",
              "postcode": "56789",
              "houseNumber": "null"
            }
          }
        ],
        "citizenship": null,
        "dateOfBirth": "1967-03-30",
        "nationality": null,
        "yearOfBirth": "1967",
        "placeOfBirth": "MADRID",
        "occupation": "Engineer",
        "employer": "Any Company LLC",
        "foreignerStatus": "EXTRANJERO",
        "extraName": "NOM D'USAGE",
        "pepSanctionMatch": null
      },
      "reason": null,
      "status": "approved",
      "comments": [],
      "document": {
        "type": "DRIVERS_LICENSE",
        "number": "MORGA753116SM9IJ",
        "country": "GB",
        "specimen": {
          "hasSecurityRisk": false,
          "nistClassification": "weak"
         },      
        "validFrom": null,
        "validUntil": "2022-04-20",
        "placeOfIssue": "MADRID",
        "firstIssue": "2015-03-21",
        "issueNumber": "01",
        "issuedBy": "ISSUER",
        "nfcValidated": true,
        "residencePermitType": "C"
      },
      "reasonCode": null,
      "vendorData": "12345678",
      "decisionTime": "2019-11-06T07:18:36.916Z",
      "acceptanceTime": "2019-11-06T07:15:27.000Z",
      "additionalVerifiedData": {
        "driversLicenseCategory": {
          "B": true
        },
        "driversLicenseCategoryFrom": {
          "B": "2019-10-06"
        },
        "driversLicenseCategoryUntil": {
          "B": "2025-10-05"
        },
        "estimatedAge": 32,
        "estimatedGender": 0.613,
        "processNumber": "12345678912 1234",
        "driversLicenseNumber": "1234569"
      },
      "riskLabels": [
      {
        "label": "document_integration_level_crosslinked_with_fraud",
        "category": "document",
        "sessionIds": ["5a2358e7-fd31-4fcb-a23f-4d76651ba68a"],
        "riskScore": 0.97
      },
      {
        "label": "document_integration_level_crosslinked_with_multiple_declines",
        "category": "document",
        "sessionIds": ["fd5c1563-1d23-4b1a-ae46-7ba429927ed8"]
      }],
      "biometricAuthentication": {
        "matchedSessionId": "d40edb60-6ae6-4475-be72-84b81669cce6",
        "matchedSessionVendorData": "User001"
      }
    },
    "technicalData": {
      "ip": "186.153.67.122"
    }
  }

Event webhook

This is the description of the payload sent to Webhook events URL.

We can get two types of events:

Verification events

To keep the clients up to date with progress during the verification process Veriff allows to subscribe to certain events. Currently two events are triggered:

Request properties explained:

Sample request

{
  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
  "feature": "selfid",
  "code": 7002,
  "action": "submitted",
  "vendorData": "QWE123"
}

Proof of address events

To track the progress of proof of address data gathering, Veriff allows to subscribe to the following events:

Request properties explained:

Sample request

{
  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "addressId": "f087f21f-5282-41b8-9857-6f85c28b8122",
  "feature": "selfid",
  "code": 7005,
  "action": "submitted",
  "vendorData": "QWE123"
}

Watchlist screening webhook

This is the description of the payload sent to Webhook watchlist screening URL.
Only available for customers using the Veriff PEP and Sanctions services.

The response of the check is sent back to the customer once the check is complete or an ongoing monitoring check comes in. This webhook is sent independently of the Decision webhook and the Event webhook.

Request properties explained:

Sample request

{
  "checkType": "updated_result",
  "attemptId": "54233318-f81c-4ec4-8e4c-413168a3f5e6",
  "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "vendorData": "12345678",
  "matchStatus": "possible_match",
  "searchTerm": {
    "name": "Mirko Kokki",
    "year": "1960"
  },
  "totalHits": 5,
  "createdAt": "2021-06-02T11:04:00.287Z",
  "hits": [
    {
      "matchedName": "Miro kokkino",
      "countries": [
        "Australia",
        "Brazil"
      ],
      "dateOfBirth": "1960",
      "dateOfDeath": null,
      "matchTypes": [
        "aka_exact"
      ],
      "aka": [
        "Kokki Mirko",
        "Mirko Kokki"
      ],
      "associates": [
        "Desmon Lamela",
        "Fred Austin"
      ],
      "listingsRelatedToMatch": {
        "warnings": [
          {
            "sourceName": "FBI Most Wanted",
            "sourceUrl": "http://www.fbi.gov/wanted",
            "date": null
          }
        ],
        "sanctions": [
          {
            "sourceName": "Argentina Ministerio de Relaciones Exteriores y Culto Sanciones de la ONU",
            "sourceUrl": "https://www.cancilleria.gob.ar/es/politica-exterior/seguridad-internacional/comite-de-sanciones",
            "date": null
          },
          {
            "sourceName": "Argentina Public Registry of People and Entities linked to acts of Terrorism and Terrorism Financing",
            "sourceUrl": "https://repet.jus.gob.ar/#entidades",
            "date": null
          }
        ],
        "fitnessProbity": [
          {
            "sourceName": "United Kingdom Insolvency Service Disqualified Directors",
            "sourceUrl": "https://www.insolvencydirect.bis.gov.uk/IESdatabase/viewdirectorsummary-new.asp"
          }
        ],
        "pep": [
          {
            "sourceName": "United States Navy Leadership and Senior Military Officials",
            "sourceUrl": "https://www.navy.mil/Leadership/Biographies/"
          }
        ],
        "adverseMedia": [
          {
            "date": "2020-09-23T00:00:00Z",
            "sourceName": "SNA's Old Salt Award Passed to Adm. Davidson",
            "sourceUrl": "https://www.marinelink.com/amp/news/snas-old-salt-award-passed-adm-davidson-443093"
          }
        ]
      }
    }
  ]
}

Transportation registry webhook

This is the description of the payload sent to Webhook transportation registry URL.
The response of the check is sent back to the client once the check is completed.

Request properties explained:

Sample request

{
  "eventType": "transportation_registry_check.verified",
  "eventCode": 7006,
  "details": {
    "rightToDrive": {
      "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
      "reason": "Expired right to drive",
      "status": "invalid",
      "validUntil": "2016-08-31"
    }
  },
  "sessionId": "03c4070b-fb7a-4c8d-8619-bf1145ecaece",
  "vendorData": "Custom vendor provided information"
}

INE registry validation webhook

This is the description of the payload sent to Webhook INE registry URL.
The response of the check is sent back once the check is completed.

Request properties explained
Sample request
{
  "eventType": "ine_registry",
  "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
  "vendorData": "1234567812345678",
  "version": "1.0.0",
  "time": "2021-06-02T11:04:00.287Z",
  "data": {
    "status": "La credencial es válida",
    "code": 200,
    "details": {
      "active": true,
      "documentState": "El documento es válido."
    }
  }
}

CURP registry validation webhook

This is the description of the payload sent to Webhook CURP registry URL.
The response of the check is sent back once the check is completed.

Request properties explained

Full forms of the statusCurp acronyms

Active CURP: AN (Alta Normal), AH (Alta con Homonimia), CRA CU (CURP Reactivada), RCN (Registro de Cambio no Afectando a CURP), RCC (Registro de Cambio Afectando a CURP)

For inactive CURP: BD (Baja por Defuncion), BDA (Baja por Duplicidad), BCC (Baja por Cambio en CURP), BCN (Baja no Afectando a CURP)

Sample request
{
  "type": "curp_registry",
  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "vendorData":  "1234567812345678",
  "version": "1.0.0",
  "data": {
      "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
      "name": "curp_registry",
      "status": "found",
      "code": 200,
      "details": {
          "statusCurp": "RCN",
          "curp": "VISH760905HSRLNN06",
          "description": "Registro de cambio no afectando a curp"
      }
  }
}

Combined INE CURP validation webhook

This is the description of the payload sent to Webhook combined INE CURP registry URL.
The response of the check is sent back once the check is completed.

Request properties explained

Full forms of the statusCurp acronyms

Active CURP: AN (Alta Normal), AH (Alta con Homonimia), CRA CU (CURP Reactivada), RCN (Registro de Cambio no Afectando a CURP), RCC (Registro de Cambio Afectando a CURP)

For inactive CURP: BD (Baja por Defuncion), BDA (Baja por Duplicidad), BCC (Baja por Cambio en CURP), BCN (Baja no Afectando a CURP)

Sample request
{
  "type": "combined-ine-curp-registry",
  "id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "vendorData":  "1234567812345678",
  "version": "1.0.0",
  "data": {
      "attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
      "name": "combined-ine-curp-registry",
      "status": "found",
      "code": 200,
      "details": {
        "ine": {
            "active": true,
            "status": "La credencial esta vigente",
            "comments": [
                "CIC 000000000\r\nClave de elector JRLGLS00000000H000\r\nNúmero de emisión 1\r\nDistrito Federal 3\r\nDistrito Local 4\r\nNúmero OCR 0000000000000\r\nAño de registro 2009\r\nAño de emisión 2020",
                "Fecha de actualización de la información: 10 de agosto del 2023 19:48",
                "Fecha de consulta: 11 de agosto del 2023",
                "Tus datos se encuentran en el Padrón Electoral, y también en la Lista Nominal de Electores"
            ],
            "information": "CIC 000000000\r\nClave de elector JRLGLS00000000H000\r\nNúmero de emisión 1\r\nDistrito Federal 3\r\nDistrito Local 4\r\nNúmero OCR 0000000000000\r\nAño de registro 2009\r\nAño de emisión 2020\r\nFecha de actualización de la información: 10 de agosto del 2023 19:48\r\nFecha de consulta: 11 de agosto del 2023\r\nEsta vigente como medio de identificación y puedes votar.\r\nTus datos se encuentran en el Padrón Electoral, y también en la Lista Nominal de Electores.\r\nSerá válida hasta el 31 de diciembre de 2030",
            "ifeIdentifier": "",
            "ineIdentifier": "000000000"
        },
        "curp": {
            "curp": "ABCD000000HVZRGS00",
            "names": "LOREM IPSUM",
            "gender": "HOMBRE",
            "regionCode": "VZ",
            "statusCurp": "RCN",
            "birthRegion": "Veracruz",
            "dateOfBirth": "06/04/1991",
            "nationality": "MEX",
            "firstSurname": "JUAREZ",
            "secondSurname": "LAGUNES",
            "docEvidenceData": {
                "book": "",
                "sheet": "",
                "volume": "",
                "actNumber": "00123",
                "registryCity": "",
                "regionRegistry": "30",
                "registrationYear": "1991",
                "registryCityCode": "125",
                "registryRegionCode": "VZ"
            },
            "documentEvidence": 1,
            "descriptionStatusCurp": "Registro de cambio no afectando a curp"
        }
    }
  }
}

User-defined session statuses webhook

This is the description of the payload sent to the Webhook URL for sessions statuses set in Station.
This webhook is sent after the user has added a status to an attempt in the Veriff environment.

Properties

Properties explained

{
    "data": {
        "verification": {
            "id": "a1c68aea-7f4d-478d-80ab-ca9356074f69",
            "userDefinedData": {
                "reason": "Looks like velocity abuse",
                "status": "Custom status for suspicious attempt",
                "createdAt": "2023-10-27T09:59:15.090805Z",
                "reasonCode": null,
                "statusCode": "custom_status_for_suspicious_attempt"
            }
        }
    },
    "time": "2023-10-27T10:00:02.998Z",
    "attemptId": "f2270684-8c51-4d03-88eb-dafd43e8b486",
    "eventType": "user-status.created",
    "sessionId": "0b10cb53-4f3b-48af-bd74-60b85354e51f",
    "vendorData": null
}

Webhooks testing

For testing purposes we provide an example payload, so you do not depend on Veriff sending the response. You can use the Curl command below.

Note that the signature will not match your API Public Key and API Private Key. To validate this example signature and payload, use API Private Key 'abcdef12-abcd-abcd-abcd-abcdef012345'.

curl --request POST 'https://your.url' -k \
--header 'accept:application/json' \
--header 'x-auth-client:8e4f7cd8-7a19-4d7d-971f-a076407ee03c' \
--header 'x-hmac-signature:01fa3ded011bfce75672c99877a6cc1cf7aeaeda0ccb6b43fc21b60f595063c2' \
--header 'content-type:application/json' \
--data '{"status":"success","verification":{"id":"12df6045-3846-3e45-946a-14fa6136d78b","code":9001,"person":{"gender":null,"idNumber":null,"lastName":"MORGAN","addresses":[{"fullAddress":"1234 Snowy Ridge Road, Indiana, 56789 USA","parsedAddress":{"city":null,"unit":null,"state":"Indiana","street":"1234 Snowy Ridge Road","country":"USA","postcode":"56789","houseNumber":"null"}}],"firstName":"SARAH","citizenship":null,"dateOfBirth":"1967-03-30","nationality":null,"yearOfBirth":"1967","placeOfBirth":"MADRID","pepSanctionMatch":null},"reason":null,"status":"approved","comments":[],"document":{"type":"DRIVERS_LICENSE","number":"MORGA753116SM9IJ","country":"GB","validFrom":null,"validUntil":"2022-04-20","placeOfIssue":"MADRID","firstIssue":"2015-03-21","issueNumber":"01","issuedBy":"ISSUER"},"reasonCode":null,"vendorData":"12345678","decisionTime":"2019-11-06T07:18:36.916Z","acceptanceTime":"2019-11-06T07:15:27.000Z","additionalVerifiedData":{"driversLicenseCategory":{"B":true},"driversLicenseCategoryFrom":{"B":"2019-10-06"},"driversLicenseCategoryUntil":{"B":"2025-10-05"},"estimatedAge":32,"estimatedGender":0.613},"riskLabels":[{"label":"document_integration_level_crosslinked_with_fraud","category":"document","sessionIds":["5a2358e7-fd31-4fcb-a23f-4d76651ba68a"]},{"label":"document_integration_level_crosslinked_with_multiple_declines","category":"document","sessionIds":["fd5c1563-1d23-4b1a-ae46-7ba429927ed8"]}],"biometricAuthentication":{"matchedSessionId":"d40edb60-6ae6-4475-be72-84b81669cce6","matchedSessionVendorData":"User001"}},"technicalData":{"ip":"186.153.67.122"}}'

Full Auto

This is a fully automated identity verification service, which can be integrated via SDKs and the API.

There are two options for identity verification:

The system analyses the images, verifies the end-user and returns the following info:

All this info is returned via specific Full Auto webhook, and the info can also be viewed in the Veriff environment to make a decision about the end-user. Because all this detailed info is returned, Full Auto sessions do not return reason codes.

Full Auto pre-requisites

If you are a new customer, please see here how to get started with Veriff and how to set up an integration. The instructions to set up the Full Auto webhook are below.

Existing customers do not need to set up a new IDV integration. You need to set up the Full Auto webhook.

Full Auto Webhook setup

  1. Log in to the Veriff environment
  2. Navigate to the Integrations page via the top menu and open the Integration used for Full Auto
  3. On the integration's page, select the Settings tab
  4. Under the title Integration settings you see a list of webhooks
  5. Fill in the Webhook Full Auto URL

Note that because all the data is returned via specific Full Auto webhook, the Webhook decisions URL input field is not available.

Full Auto flow

  1. Create a new session using the keys and the baseURL of the Full Auto integration (see the API Reference how to find these).

  2. Direct the end-user to the verification flow.

  3. The end-user passes through the end-user flow on their device. They are required to capture the front and back of their ID document, and, in case of also face validation, take a selfie.

    a. When using the SDK/Web flow, the session status is automatically updated to submitted as soon as the end-user has submitted the images.

    b. When using the API requests, you need to do this manually. Please see the Full Auto API section below for more information

  4. Receive the results from Veriff via Full Auto webhook, query them using the GET sessions/{sessionId}/decision/fullauto endpoint, or view them in the Veriff environment.

Full Auto over the SDK

If you have integrated with Veriff using the SDKs and you have set up the Full Auto webhook URL in the Veriff environment, you are all set.

Full Auto over the API

Before you start, make sure that you have configured the Full Auto webhook URL.

Sending the end-user data via API

  1. Start a session using the POST /sessions. Make sure to pass the vendorData
  2. Upload the highly recommended device/session data via POST sessions/{sessionid}/collected-data for improved fraud detection
  3. Upload end-user's ID document (and selfie images, if applicable) via POST sessions/{sessionId}/media
  4. Specify the image.context as appropriate for the image (see the context types for more info)
  5. Patch the session status to submitted using the PATCH sessions/{sessionId}

Querying the decision data via API

You can use the GET sessions/{sessionId}/decision/fullauto endpoint to get the decision data (it is exactly the same as the data sent with the Full Auto Webhook).

Request

Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required) = API key
X-HMAC-SIGNATURE: string (required) = sessionId signed with the shared secret key
Content-Type: application/json
Query parameters
version: string (required) = version=1.0.0 Version specification

Response

The GET response body looks exactly the same as the Full Auto Webhook [🡕] payload (requires a log-in to the Veriff environment).

Full Auto webhook

This section gives a more general overview of the contents of the Full Auto webhook. For more detailed info see:

Decision

Parameter data.decision shows system’s suggestion of what to do with the session. Can be either “approved”, “declined” or “resubmission_requested”.

Decision score

Parameter data.decisionScore shows how confident the system is that the session is genuine. Lower number means that the confidence is low, higher number means that the session is more likely to be genuine. The score is shown on two scales:

Extraction details

Objects data.verification.person and data.verification.document contain the data extracted from the document:

If the extraction fails to gather data or the data is missing from the document, the webhook returns null.

Note that the webhook explanation article [🡕] and the webhook sample article [🡕] list the default extractions included in the Full Auto solution. If you need additional extractions, please contact your Solutions Engineer.

Session insights

Array data.insights contains pieces of metadata that help explain the decision. It also contains other useful indicators of fraud and risk. The insights are in the form of “yes / likely yes / no / NA” where applicable.

Note that the webhook explanation article [🡕] and the webhook sample article [🡕] display all the insights. This means that the actual list of insights visible in the webhook depends on your integration. Also, note that this list is flexible and additional insights may be added in the future.

Biometric Authentication

Veriff offers two different possibilities to use biometric authentication.

Broadly explained, the options are:

Prerequisites for Biometric Authentication

  1. An IDV integration and an authentication integration set up, connected to one another (has to be done by your dedicated team at Veriff)
  2. Once the integrations are set up and connected, in order to enroll the end-user to the biometric authentication product, it is required that the end-user has an approved IDV session from the IDV integration, where the vendorData field is populated with a uuid, unique to each end-user that has been verified.

Biometric Authentication process overview

Verify the end-user’s identity

Using your configured IDV integration, verify the end-user’s identity (integrations reference)

vendorData field must be set to the unique end-user UUID (see above).

With the integrations being connected, face images of approved sessions through the IDV integration (identified with vendorData field) will be automatically added to the set of approved faces, which can be used for future authentications.

Authenticate the end-user

This is applicable once the end-user has an approved session containing a populated vendorData with their unique UUID:

  1. Generate an authentication session using the Authentication integration tokens. (Check /sessions endpoint in the API reference here).
      a. Use the vendorData field to pass the same end-user identifier used in the IDV session if you are doing 1:1 biometric match.
      b. Leave vendorData field empty if you are doing 1:n biometric match.
  2. Choose face capture method:
      a. Capturing images with Veriff’s SDKs
      i. Send the end-user through the verification flow to capture the new face image using one of Veriff’s SDKs (iOS, Android, React Native, Flutter, inContext). You will need the session url generated at step 1 to use the SDKs.
      Note: Session will be submitted automatically once the end-user takes necessary images of their face.
      b. Your own face capturing method (not recommended)
      i. Upload the end-user's face image via the POST media endpoint. Specify context parameter as face.
      ii. Patch session status to submitted status using PATCH /sessions/{sessionId} endpoint.
  3. Receive the results from Veriff via webhooks.

Biometric Authentication handling decisions

The verification.status and verification.code can be :

See the verification decision codes table for explanations.

Biometric Authentication handling the decision: reasons

Status Code Description
Declined 105 Suspicious behaviour
Declined 106 Known fraud
Declined 120 Person on the portrait does not appear to match reference photo
Declined 121 User ID missing
Declined 122 No reference found
Declined 605 Face image missing
Expired/Abandoned null null

Biometric Authentication Service Flow Diagram

biometric-authentication-flow

AML Screening

PEP & Sanction screening with IDV

PEP & Sanctions, adverse media screening together with identity verification

Prerequisites

An IDV integration with PEP & Sanctions checks configured together with optional adverse media checks and ongoing monitoring. Turn to your dedicated Solutions Engineer for configuration.

Process overview

  1. Once the integration is set up, generate a verification session using the regular /sessions endpoint.
  2. After the end-user has submitted the verification flow and the session has been verified, the AML result will be sent in a separate webhook. You can also query for the result using the watchlist-screening API endpoint
  3. In case ongoing monitoring is enabled, we will send a new webhook if the PEP & Sanctions status of a verified person has changed.
    a. The Webhook PEP & Sanctions URL can be configured from the “Integrations” menu

PEP & Sanction screening without IDV

PEP & Sanctions, adverse media screening without identity verification

Prerequisites

A non-IDV integration with PEP & Sanctions checks configured together with optional adverse media checks and ongoing monitoring. Turn to your dedicated Solutions Engineer for configuration.

Process overview

  1. Generate a new verification session using the /sessions endpoint and specify the following fields in the request:
    a. First name
    b. Last name
    c. Date of Birth
  2. Change the status of the session to “Submitted” using PATCH /sessions/{sessionId} endpoint
  3. The results will be sent in a separate webhook and are also available using the /watchlist-screening end-point.
    a. The Webhook PEP & Sanctions URL can be configured from the “Integrations” menu

UK DIATF

Veriff is a certified IDSP under the UK Digital Identity and Attributes Trust Framework (UK DIATF), UK Government site[🡕]

Within the framework of UK DIATF, we offer two solutions:

UK DIATF certified IDV (Low profile)

The solution is identical to Veriff’s standard identity verification, however, Veriff’s identity verification flow must be used to capture the document & selfie.

If you are not integrated with us yet, see the Getting started with Veriff for first steps.

UK DIATF certified IDV (Medium profile)

This is a comprehensive solution, which requires that the end-user's address is provided to return info from registries; and the flow must be completed using Veriff's verification flow (cannot be white-labeled).

Below is a step-by-step overview of the flow, click on each step to expand the description.

Webhook response

Age Estimation

This solution estimates end-user's age from the selfie images that they capture. Customers receive the end-user's estimated age and estimated gender.

Process overview

There are two different ways to utiliaze the Age Estimation service: via Veriff's verification flow or trough API.

Age Estimation via Veriff's verification flow

  1. Create a session using the Age Estimation integration's tokens (see POST /sessions for more details about how to create a session)
    • You can use vendorData parameter to pass a unique identifier for the end-user in the flow. We require only non-semantic data to be submitted (e.g. UUID-s that can not be resolved or used outside the customer's environment).
  2. Direct the end-user into the verification flow
  3. The end-user passes through the verification flow on their device, where they are required to capture only a selfie (no ID document is needed)
  4. Session will be automatically set to submitted
  5. Receive the results from Veriff via decision webhook; you can also query them using GET sessions/{sessionId/decision}

Age Estimation over the API

  1. Create a session using the Age Estimation integration's tokens (see POST /sessions for more details about how to create a session)
    • You can use vendorData parameter to pass a unique identifier for the end-user in the flow. We require only non-semantic data to be submitted (e.g. UUID-s that can not be resolved or used outside the customer's environment).
  2. Upload the end users selfie via POST sessions/{sessionId}/media endpoint with image.context as face
  3. Patch the session to submitted using the PATCH sessions/{sessionId}
  4. Receive the results from Veriff via decision webhook; you can also query them using GET sessions/{sessionId/decision}


In the webhook and the endpoint, the data is in:

*Values closer to 0.0 indicate that the end-user is likely to be male, values closer to 1.0 indicate that the end-user is likely to be female.

Age Estimation session decisions

The verification.status and verification.code can be:

End-user in the Age Estimation flow (diagram)

Face Match (Deprecated)

Prerequisites for Face Match

  1. You should have a document-front image of the user that needs re-authentication. This image will be passed to the verification session via API as a reference to compare the newly captured “face” image to.
  2. A Face-match integration should be configured. (Reach out to your contact at Veriff to set it up for you!)

Face Match process overview

  1. Generate a session using the Face-match integration tokens. Check /sessions endpoint in the API reference here.
    Note: You can use vendorData parameter to pass a unique identifier for the user who will be verified. We require only non-semantic data to be submitted (e.g. UUID-s, etc that can not be resolved or used outside of the vendor environment).
  2. Upload the reference image (document-front). Check /sessions/{sessionId}/media POST endpoint here.
    Note: Set context parameter as document-front while using POST media endpoint.
  3. Choose face capture method:
      a. Capturing images with Veriff’s SDKs
      i. Send the end user through the verification flow to capture the new face image using one of Veriff’s SDKs (iOS, Android, React Native, Flutter, inContext). You will need the session url generated at step 1 to use the SDKs.
      Note: Session will be submitted automatically once the user takes necessary images of their face.
      b. Your own face capturing method (not recommended)
      i. Upload the user's face image via the POST media endpoint. Specify context parameter as face.
      ii. Patch session status to submitted status using PATCH /sessions/{sessionId} endpoint.
  4. Receive the results from Veriff via webhooks.

Face Match handling decisions

verification.status verification.code What to do
approved 9001 Positive: Person was verified. The verification process is complete. Accessing the sessionURL again will show the customer that nothing is to be done here.
declined 9102 Negative: Person has not been verified. The verification process is complete. Either it was a fraud case or some other severe reason that the person can not be verified. You should investigate the session further and read the "reason". If you decide to give the end-user another try you need to create a new session.
resubmission_requested 9103 Resubmitted: Resubmission has been requested. The verification process is not completed. Something was missing from the end-user, and they need to go through the flow once more. The same sessionURL can and should be used for this purpose. And the reference image should be uploaded again (same if related to the face, different one if related to the reference image)
expired 9104 Negative: Verification has been expired. The verification process is complete. After the session creation, if the end user has not started the verification in 7 days, the session gets expired.
abandoned Negative: Verification has been abandoned. The verification process is complete. After the session creation, if the end user has started but not completed the verification in 7 days, the session gets abandoned status.

Face Match handling decisions: reasons

verification.status verification.reasonCode verification.reason What to do
declined 509 Person showing the document does not match document photo User’s new face doesn’t match with reference uploaded image
declined 515 Attempted deceit, device screen used for face image Face image shown from a device/screen/printout.
declined 526 Attempted deceit, photos streamed Face images are being presented as a slide show/stream.
Note: This feature comes when using Veriff's end user flow to capture the images
declined 106 Known fraud Suspicious multi/country accesses, previously declined multiple times for fraud
declined 108 Decline - Velocity/abuse duplicated user This feature needs to be enabled for your integration. It is not active by default
declined 109 Decline - Velocity/abuse duplicated device This feature needs to be enabled for your integration. It is not active by default
declined 110 Decline - Velocity/abuse duplicated ID This feature needs to be enabled for your integration. It is not active by default
resubmission_requested 605 Face missing from image
  1. Upload reference image again to the same session uuid
  2. Send the end user to the same url.
resubmission_requested 606 Face is not clearly visible
resubmission_requested 608 Document front missing
  1. Reference image/s not good enough to do face match, try uploading a different document-front image.
  2. Send the user to the same url.
resubmission_requested 619 Document data not visible
expired null null Create a new session for the user
abandoned

Face Match Service Flow Diagram

face-match-flow

Reference Info, Codes, Tables

Verification session status and decision codes

Session status

Session Status Code Sent by Description
Started 7001 Event webhook The end-user has started their session and landed in our verification flow.
No decision is available yet.
Submitted 7002 Event webhook The end-user has submitted the requested data in the verification flow.
No decision is available yet.
Approved 9001 Decision webhook The end-user was verified. The verification process is complete.
Accessing the sessionURL again will show the end-user that nothing is to be done here.
Declined 9102 Decision webhook The end-user has not been verified. The verification process is complete.
Either it was a fraud case or some other severe reason that the end-user could not be verified. You should investigate the session further and read the reason and decision codes. If you decide to give the end-user another try, you need to create a new session..
Resubmission
aka resubmission_requested		 9103 Decision webhook Resubmission has been requested. The verification process has not been completed.
Something was missing from the end-user, and they need to go through the flow once more. The same sessionURL can and should be used for this purpose.
Expired/Abandoned 9104 Decision webhook Verification has been expired (a session will expire 7 days after having been created unless it gets a conclusive decision before that). The verification process is complete.
If the end-user started the verification process, the response shows abandoned. If the end-user has never accessed the verification, the status will be expired. If you decide to give the end-user another try, you need to create a new session.
Review 9121 Decision webhook Note that this status is sent only when you have implemented the fully automated verification flow.
Review status is issued whenever the automation engine could not issue a conclusive decision and the verification session needs to be reviewed by a human on your side.

Responses 9001, 9102, 9121 and 9104 are conclusive responses. The session is closed and the sessionURL is not available for the end-user.

Response 9103 is an inconclusive response. The session remains open until you receive one of the above conclusive responses. The session is re-opened for the end-user, accepting a new attempt.

Additional info can be found in our Knowledge base article [🡕].

Verification decision: declined

This table contains values for verification.reasonCode in case the verfication.status returned declined. If you do not see the reason code you received here, see also granular reason codes

Code Description
102 Suspected document tampering
103 Person showing the document does not appear to match document photo
105 Suspicious behaviour
106 Known fraud
108 Velocity/abuse duplicated end-user
109 Velocity/abuse duplicated device
110 Velocity/abuse duplicated ID
112 Restricted IP location
113 Suspicious behaviour - Identity Farming

Verification decision: resubmission required

This table contains values for verification.reasonCode in case the verfication.status returned resubmission_requested. If you do not see the reason code you received here, see also granular reason codes

Note about the number of resubmissions: one user can resubmit their data up to 9 times. This means that the 10th attempt is automatically declined, and code 539 - Resubmission limit exceeded is sent. If you wish to allow the end-user to retry verification, you need to create a new session for them (see POST sessions for info).

Code Description
201 Video and/or photos missing
204 Poor image quality
205 Document damaged
206 Document type not supported
207 Document expired

Common HTTP status codes

Code Value Description
200 status: success, data Returned as a general "OK" code
201 status: created, data Returned when creating a session
400 status: fail
code: 1102		 Mandatory parameters are missing from the request
See the troubleshooting codes table
401 status: fail Not authorized
404 status: fail Entry not found
500 status: fail Something went wrong

Credentials and authorization codes

Code Description
1801 Mandatory X-AUTH-CLIENT header containing the API key is missing from the request
1802 API key is not a valid UUID
1803 Integration with the API key was not found
1804 Integration with the API key is not active
1812 Signature is not a valid SHA256 hash
1813 Signature does not match the SHA256 hash of query ID and integration API secret
1814 Signature does not match the SHA256 hash of request body and integration API secret
1818 Signature does not match the HMAC-SHA256 of query ID and integration API secret
1819 Signature does not match the HMAC-SHA256 of request body and integration API secret

Some troubleshooting codes

Code Description
1001 Query ID must be between 20 and 40 symbols.
1002 Query ID must be a valid UUID V4
1003 Query ID must be unique, it has already been used.
1102 Mandatory parameters are missing from the request.
1104 Request includes invalid parameters.
1201 Invalid timestamp. Timestamp must not be older than one hour.
1202 Timestamp format is incorrect. YYYY-MM-DDTHH:MM:S+Timezone Offset|Z or UTC.
1203 Invalid ISO 8601 date. Date needs to be in format YYYY-MM-DD.
1301 Requested features are not supported.
1302 Only HTTPS return URLs are allowed.
1303 Invalid status.
1304 Cannot transition to "$STATUS" status.
1308 ID number is missing.
1309 SSN validation requires person firstName + lastName OR fullName to be provided.
1310 "SSN validation requires person.dateOfBirth or address data to be provided.
1400 Image data not found.
1401 Image is not in valid base64.
1402 Image context is not supported.
1403 Image property is missing.
1500 vendorData field cannot be more than 1000 symbols. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer's domain)
1501 vendorData must be a string. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the customer's domain)
2003 Date of birth is not a valid date.
2101 Document number has to be between 6 and 9 characters.
2102 Document number may contain only characters and numbers A-Z, 0-9.
2103 Document type is not supported.
2104 Document from provided country is not supported.

Granular reason codes

The granular reason codes (hereinafter the GRC) mentioned here are subject to custom configuration on integration level, meaning that you may or may not receive all the reason codes listed here.

GRC verification decision: declined

This table contains values for verification.reasonCode in case the verfication.status returned declined.

Code Description
101 Physical document not used
106 Known fraud
108 Velocity/abuse duplicated end-user
109 Velocity/abuse duplicated device
110 Velocity/abuse duplicated ID
112 Restricted IP location
113 Suspicious behaviour - Identity Farming
120 Person on the portrait does not appear to match reference photo
121 User ID missing
122 No reference found
123 Unable to pass registry checks
126 Potential PEP match
127 Face match with blocklist
502 Multiple parties present in session
503 Attempted deceit
504 Attempted deceit, device screen used
505 Attempted deceit, printout used
507 Presented document tampered, data cross reference
508 Presented document tampered, document similarity to specimen
509 Person showing the document does not match document photo
510 Presented document type not supported
511 Presented document expired
515 Attempted deceit, device screen used for face image
526 Attempted deceit, photos streamed
527 Unable to collect proof of address data
528 Proof of address issue date too old
530 Person is under 13 years old
531 Person is under 14 years old
532 Person is under 16 years old
533 Person is under 18 years old
534 Person is under 20 years old
535 Person is under 21 years old
536 Person is under 25 years old
537 Unable to perform document media portrait cropping
539 Resubmission limit exceeded
540 Low confidence score for the session
541 Name on document does not match with name in session initialisation data
542 Unable to validate CPF

GRC verification decision: resubmit

This table contains values for verification.reasonCode in case the verfication.status returned resubmission_requested.

Code Description
203 Full document not visible
602 Presented document type not supported
603 Video missing
605 Face image missing
606 Face is not clearly visible
608 Document front missing
609 Document back missing
614 Document front not fully in frame
615 Document back not fully in frame
619 Document data not visible
620 Presented document expired
621 Document annulled or damaged
625 Unable to collect surname
626 Unable to collect first names
627 Unable to collect date of birth
628 Unable to collect issue date
629 Unable to collect expiry date
630 Unable to collect gender
631 Unable to collect document number
632 Unable to collect personal number
633 Unable to collect nationality
634 Unable to collect home address
635 Document and face image missing
636 Presented document not real, screen used
637 Presented document not real, printout used
640 Person did not give consent
641 Multiple Faces Detected
642 Multiple Documents Uploaded
643 Unable to crop face image from a document front
644 Unable to collect Identificador de Ciudadano (INE)
645 Resubmit - Unable to collect OCR (IFE)
646 Unable to estimate age
647 Document not recognised
648 Technical issues
649 Unable to collect foreigner information
650 Unable to collect process number
651 Unable to collect occupation information
652 Unable to collect employer information
653 Unable to collect residence permit type
654 Unable to collect driver's license number
655 Unable to collect additional name
657 Open passport image missing

Image context types

context names with the -pre suffix mean that the image is captured without camera flash.

Identity verification process

Context label name Description
face Returns the selfie picture, with a flash
face-pre Returns the selfie picture, without a flash
face-nfc Returns the selfie picture extracted from the document's NFC chip
document-front Returns the picture of the ID document's front, with a flash
document-front-pre Returns the picture of the ID document's front, without a flash
document-front-qrcode Returns the picture of the ID document's front, to display the QR-code
document-front-qrcode-pre Returns the picture of the ID document's front, without a flash, to display the QR-code
document-front-face-cropped Returns a cropped portrait image from a document
document-back Returns the picture of the ID document's back, with a flash
document-back-pre Returns the picture of the ID document's back, without a flash
document-and-face Returns the selfie with the the ID document's front, with a flash
document-and-face-pre Returns the selfie with the the ID document's front, without a flash
document-back-barcode Returns the picture of the ID document's back, to display the barcode
document-back-barcode-pre Returns the picture of the ID document's back, without a flash, to display the barcode
document-back-qrcode Returns the picture of the ID document's back, to display the QR-code
document-back-qrcode-pre Returns the picture of the ID document's back, without a flash, to display the QR-code
registry-face Returns the selfie picture extracted from a third party registry

Proof of Address verification process

Context label name Description
address-front Returns the image of the address that's displayed on the Proof of Address document's front

Video context types

Context label name Description
selfid_video Returns one video of the whole session, comprising the selfie, document front and document back videos
face-pre-video Returns the selfie video
document-front-pre-video Returns the video of the document's front
document-back-pre-video Returns the video of the document's back
document-and-face-pre-video Returns the selfie video with the document's front
document-back-barcode-pre-video Returns the selfie video with the document's back to display the document's barcode
document-front-qrcode-pre-video Returns the selfie video with the document's back to display the document's QR-code
document-back-qrcode-pre-video Returns the selfie video with the document's back to display the document's QR-code

Supported document types for IDV

In the Identity Verification process, the request and response bodies can display the document object. This contains the type string. The type can be one of the following document types:

If it's not possible to classify the document as one of the above, the response can show "type": "OTHER".

See also:

Document data fields

Abbreviation Field name Explanation
VIZ Visual Inspection Zone The data group of this zone includes the photograph, the document designation, personal data and the date of issue and validity of the document
MRZ Machine Readable Zone The two to three lines where the information from the viewing zone is strung together with alphanumeric characters and the "<" symbol
Barcode The barcode or the QR code on the document
NFC Near Field Communication Document's NFC chip

Glossary

Term Context Definition Additional info
API Key Public API A unique identifier of an integration and a required parameter for authentication. It is used to create the X-AUTH-CLIENT header value for API requests. You can find it in Station > Integration's page (requires a Station login).
Occasionally, referred to as the API public key or Publishable key.
API request Public API A message sent to a server asking for the API to provide service or information. Also referred to as the API call.
API URL Public API An address that allows you to access an API and its various features. It consists of a BaseURL and an Endpoint. Also referred to as the API URL path.
attemptId Public API, Webhooks An UUID v4 of a specific attempt.
You can find its value in your GET /sessions/{sessionId}/attempts response, as verification.id. 		In the API requests' context, an "attempt" is one step (uploading required data and getting a decision) inside a verification session, and it can be made several times during a verification session. This means that calling the GET /sessions/{sessionId}/attempts can return several verification objects, each one with a unique id value.
BaseURL Public API A "base address" for the specific API that you’re using.
Used to create the API URL value for API requests. 		Found in Station > Integration page (requires a Station login).
Body Public API, Webhooks Data inside the request and response payloads in an API request. A GET request's payload does not contain a body.
CallbackURL Public API URL address of the page where the end-user is sent after they've completed the web verification flow. This does not yet contain any verification or decision info.
See here [🡕] for more info about how to set it up.
Also referred to as the redirect URL.
Customer General Veriff's customer who is using our verification services. Occasionally, referred to as the vendor
Content-type header Public API Indicates the media type of the resource, in Veriff's context, usually "application/json".
Decision code General Numeric value representing the decision given to a verification session. See the Verification session status and decision codes for more info.
End-user General User of Veriff's customer's solution, the person who goes through the verification flow (aka the end-user flow).
Endpoint Public API A specific “point of entry” in an API. You attach these to the end of your BaseURL, thus completing the API URL. The results that you'll get from the API request will depend on the Endpoint you attach.
 You can find a list of endpoints in the Endpoints section.
Granular Reason Code General It is a kind of code which is sent depending on the configuration of the client's integration. See the Granular reason codes table for more info.
Headers Public API Mandatory elements in the API requests, containing the metadata.
IDV General Abbreviation of Identity Verification.
Integration Station An environment created according to client's needs to carry out, manage and observe verifications. Client can find the list of their integrations in Station > Integrations page on the top of the page (requires a Station login.
Live Integration General Integration which is created as per your requirements. It is used for production and verification sessions created will count towards paid usage. For live integration sessions, the sessions' statuses are set automatically. You need to define the Webhook decisions URL in Station (see here for instructions).
Payload Public API, Webhooks, SDK The data that you send when you make an API request, or that you receive when you get a response. In the API requests context, the hashed hex encoded payload is signed with the shared secret key to generate the X-HMAC-SIGNATURE.
PoA General Abbreviation of Proof of Address. See the article [🡕] in the Knowledge Base for more info.
Reason code General Numeric value representing the reason for rejecting a verification session or for asking it to be resubmitted. See the tables here for more info.
Session status General A label describing the status of a verification session. See the table here for more info.
sessionID Public API, Webhooks A unique identifier of a verification session.
It is automatically created as soon as you create a session.
You can find its value in the response payload of your POST session, as verification.id. 		In the API requests' context, one verification session comprises many steps (uploading data, uploading images, getting a decision, etc.). You can call several endpoints using the same {sessionID}, to get all kinds of different data from that specific session.
sessionToken Public API Session-specific token for a verification session.
It is a JSON Web Token (JWT) that consists of HS256 encrypted sessionID and the session creation timestamp. It is valid for 7 days and should always have the variable max length type.
You can find this value in the response payload of the POST session, as verification.sessionToken.
sessionURL Public API, SDKs A combination of the base URL and the sessionToken, created as soon as a session is started.
This where the end-user is directed to go through the verification flow, and it is unique for each verification session.
You can find its value in the response payload of your POST session, as verification.url.
Shared secret key Public API Required parameter for authentication, used to sign the payload to create the X-HMAC-SIGNATURE for API requests. This is a secret credential. You can find it in Station > Integration's page (requires a Station login).
Occasionally, referred to as the API private key or the Private key.
Test Integration General Integration which is automatically created for every client who onboards with Veriff. It is used for development purposes, and verification sessions that are created will not count towards paid usage. Veriff will not provide statuses for sessions created in test integration, you need to set them manually in the Station (see here for instructions). The Webhook decision URL is automatically created.
UUID General Abbreviation of the Universal Unique Identifier. It is a 128-bit value used to uniquely identify an object or entity on the internet.
UUID v4 General It is an UUID (see above) which has been created using a random number generator.
Veriff Station General Veriff's environment, a dashboard where the clients can see their end-users' verification data. See an introductory video here[🡕].
Depending on your setup, you may be required to access the environment via station.veriff.com or hub.veriff.com. Please check your sign-up email to make sure that you log in via correct address.
Verification flow General A process where the end-user submits the data required to get verified. Also referred to as the end-user flow.
Verification session General One verification session from start to end, i.e., from the moment a session is created until the moment a conclusive decision (“approved”, “declined”, “expired”/”abandoned”) is granted. Each verification session receives an unique ID, aka the {sessionID} used in the API request endpoints.
Verification session lifecycle General Umbrella term for the whole process of completing a verification process, comprising the stages completed by the client, the end-user, and Veriff.
Webhook Public API An event-triggered API, meaning that rather than sending information or performing a function as a response to an application's request, it performs this when a certain trigger event happens. There are different types of webhooks, see the Webhooks section for more info.
X-AUTH-CLIENT header Public API A mandatory header field in API requests, required to identify the request sender. Its value is the API Key (see above).
X-HMAC-SIGNATURE header Public API A mandatory header field in API requests, required to authenticate the request sender.
Its value is a HMAC-SHA256 hex encoded hashed value of the request payload that has been signed using a shared secret key known to both the sending and receiving party. 		See the relevant API request in the API Reference section for more details about which payload to encode, and the X-HMAC-SIGNATURE section for more info about the signature itself.
X-SIGNATURE
Legacy solution 		Public API A solution used before the X-HMAC-SIGNATURE header was implemented (see above).