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.
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:
Test Integrations are used for development and sessions will not count towards paid usage. Veriff will not provide decisions on sessions created for test integrations. Stress testing without prior agreement is not allowed
Live Integrations are used for production and sessions created will count towards paid usage and Veriff will be providing decisions for those
Sessions Lifecycle
Generating verification with Veriff
Generating sessions manually
To generate a verification:
- Click "Verifications" on top menu
- Click "Add Verification" from the opened window
- Choose "Integration"
- Fill in the first name, last name
- Click "Generate Verification"
- Click on "Share" to copy the URL or QR image into clipboard
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:
Manual: the Verifications page in Station displays sessions' details including decisions made
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
Google Chrome
Mozilla Firefox
Safari
Microsoft Edge (Chromium based)
Opera
Yandex Browser
In addition to the listed browsers other Chromium based browsers may work.
iOS
- Safari
- On iOS 14.3 and newer iOS versions all browsers are supported.
Android
Google Chrome
Mozilla Firefox
Samsung Browser
Opera
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
Xiaomi browser
UC Browser
Facebook webview
iOS
- All Non-Safari iOS browsers on iOS versions prior to 14.3.
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
- Veriff Android SDK needs your
minSdkVersion
to be of 21 or above. - Your project must have
Java 8
enabled and useAndroidX
instead of older support libraries. android-gradle-plugin
version must be4.0.0
or above.Proguard
version must be6.2.2
or above. In case R8 is enabled no other updates are needed.kotlin-gradle-plugin
version must be1.4.0
or above.
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/" } //make sure to add this before other repos
google()
jcenter()
}
}
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 clients. First, please ask about this possibility from your account manager. In case we can offer it for you then removal process is following:
- You agree your own introduction screen visuals and copy with our account manager and get relevant legal documents signed in case they are needed.
- After that Veriff will enable custom introduction screen from backend for your integrations.
- After you have implemented your own introduction screen you can change the configuration option specified below.
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 account manager 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:
Branding.Builder.themeColor(color)
- this was split into two different attributes:Branding.Builder.primary(color)
&Branding.Builder.secondary(color)
Branding.Builder.logomark(drawable)
Branding.Builder.primaryButtonBackgroundColor(color)
- the button background will be set based on the newBranding.Builder.onPrimary(color)
attributeBranding.Builder.bulletPoint(color)
- bullet point color can be controlled by the newBranding.Builder.secondary(color)
&Branding.Builder.onSecondary(color)
attributesBranding.Builder.notificationIcon(color)
The following APIs were renamed:
Branding.Builder.toolbarIcon(drawable)
- renamed toBranding.Builder.logo(drawable)
Branding.Builder.backgroundColor(color)
- renamed toBranding.Builder.background(color)
Branding.Builder.primaryTextColor(color)
- renamed toBranding.Builder.onBackground(color)
Branding.Builder.secondaryTextColor(color)
- renamed toBranding.Builder.onBackgroundSecondary(color)
Branding.Builder.buttonCornerRadius(cornerRadius)
- renamed toBranding.Builder.buttonRadius(cornerRadius)
The following APIs were added:
Branding.Builder.onBackgroundTertiary(color)
Branding.Builder.primary(color)
Branding.Builder.onPrimary(color)
Branding.Builder.secondary(color)
Branding.Builder.onSecondary(color)
Branding.Builder.outline(color)
Branding.Builder.error(color)
Branding.Builder.success(color)
Migrating Veriff Android SDK from 4.x.x to 5.0.0
SDK integration
The following APIs were removed:
Branding.Builder.buttonHeight(height)
- buttons are now always with a60dp
heightBranding.Builder.statusBarColor(color)
- the status bar is now using thebackgroundColor
attribute insteadBranding.Builder.externalResources(externalResources)
- resources can be customized viatoolbarIconProvider()
,toolbarIcon()
and the newlogomark()
method.Font.Builder.setNormalAndBold(normal, bold)
- this was split into separate setters for font weights
The following APIs were added:
Branding.Builder.logomark(drawable)
- Sets a drawable to use in UI elements where a square logo is needed. (Defaults to the Veriff logomark when this attribute is not set)Font.Builder.setRegular(regularFont)
- Sets regular weight fontFont.Builder.setMedium(mediumFont)
- Sets medium weight fontFont.Builder.setBold(boldFont)
- Sets bold weight font
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 (downloads a zip file).
After framework is downloaded, 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.
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.
NSCameraUsageDescription
NSMicrophoneUsageDescription
NSPhotoLibraryUsageDescription
Add required steps for NFC scanning
- Add
NFCReaderUsageDescription
description toInfo.plist
. 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>
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>
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.
// 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. |
Customize user interface (Optional)
Setting theme color, font and logo
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:
background
- screen and dialog backgroundonBackground
- non-surface content (such as text, icons) displayed on thebackground
coloronBackgroundSecondary
- secondary non-surface content (such as text) displayed on thebackground
coloronBackgroundTertiary
- tertiary non-surface content (such as text) displayed on thebackground
colorprimary
- primary surfaces (such as buttons) displayed on thebackground
coloronPrimary
- non-surface content (such as text) displayed onprimary
surfacessecondary
- secondary surfaces (such as bullet points and illustrations) displayed on thebackground
coloronSecondary
- non-surface content (such as text) displayed onsecondary
surfacescameraOverlay
- overlay surface color on top of the camera preview screenonCameraOverlay
- non-surface content (such as text, icons) displayed oncameraOverlay
outline
- outlines and boundaries of UI elements (such as text inputs)error
- error indicators (such as text, borders, icons) displayed onbackground
colorsuccess
- success indicators (such as borders, icons) displayed onbackground
color
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"];
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 clients. First, please ask about this possibility from your account manager. In case we can offer it for you then removal process is following:
- You agree your own introduction screen visuals and copy with our account manager and get relevant legal documents signed in case their needed.
- After that Veriff will enable custom introduction screen from backend for your integrations.
- After you have implemented your own introduction screen you can change the configuration option specified below.
configuration.customIntroScreen = true
Note: This step alone is not enough to enable the custom intro screen. Make sure to contact your account manager so they can enable the feature 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:
done
The session status is finished from clients perspectivecanceled
The end-user canceled the verification processerror
An error occurred. To see the error reason:- In Swift: check the associated value (
Veriff.Error
) passed by error status. - In Objective-C: check
result.error.code
(VeriffErrorCode
).
- In Swift: check the associated value (
Notes
- The Veriff SDK always shows an error screen itself. The errors returned by the session are to inform your application.
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:
buttonHeight
statusBarColor
secondaryTextColor
isTextUppercase
Fonts API changes:
lightFontName
is removedregularFontName
,semiBoldFontName
andboldFontName
are renamed toregular
,medium
andbold
.
logomark
customization is added.
Migrating to Veriff iOS 6.0.0
Updated VeriffSdk.Branding
object
Following configurations are added:
background
onBackground
onBackgroundSecondary
onBackgroundTertiary
primary
onPrimary
secondary
onSecondary
outline
error
success
Following configurations are removed:
themeColor
backgroundColor
primaryTextColor
primaryButtonBackgroundColor
bulletPoint
Following configurations are deprecated:
logomark
not used anymore
Following configurations are renamed:
buttonCornerRadius
->buttonRadius
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.
NSCameraUsageDescription
NSMicrophoneUsageDescription
NSPhotoLibraryUsageDescription
Add required steps for NFC scanning
- Add
NFCReaderUsageDescription
description toInfo.plist
. 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>
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 clients. First, please ask about this possibility from your account manager. In case we can offer it for you then removal process is following:
- You agree your own introduction screen visuals and copy with our account manager and get relevant legal documents signed in case their needed.
- After that Veriff will enable custom introduction screen from backend for your integrations.
- After you have implemented your own introduction screen you can change the configuration option specified below.
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;
- Error.cameraUnavailable
- Error.microphoneUnavailable
- Error.networkError
- Error.sessionError
- Error.deprecatedSDKVersion
- Error.unknown
- Error.nfcError
- Error.setupError
- Error.none
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.
NSCameraUsageDescription
NSMicrophoneUsageDescription
NSPhotoLibraryUsageDescription
Add required steps for NFC scanning
- Add
NFCReaderUsageDescription
description toInfo.plist
. 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>
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
.
Alternative ways to provide the logo
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 clients. Please request this from your account manager. The removal process is following:
- Agree your own introduction screen visuals and copy with our account manager and get relevant legal documents signed;
- Veriff will enable custom introduction screen for your integrations;
- After you have implemented your own introduction screen you can change the configuration option as specified below;
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:
- background
- onBackground
- onBackgroundSecondary
- onBackgroundTertiary
- primary
- onPrimary
- secondary
- onSecondary
- outline
- error
- success
Following configurations are removed:
- themeColor
- backgroundColor
- primaryTextColor
- primaryButtonBackgroundColor
- bulletPoint
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.
Rename parameter navigationBarImage
to logo
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.url;
// incontext sdk
createVeriffFrame({url: response.url});
}
});
veriff.mount();
Read more about incontext sdk method or redirection.
By default, the following form will be rendered:
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 - Client-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 client'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'
});
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...'
});
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;
}
}
})
msg
:STARTED
- session status changed to 'started'.CANCELED
- end-user closed the modal.FINISHED
- end-user finished verification flow.
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])
[options]
- Configuration object:url
- Veriff session URLlang
- Override user interface languageonEvent
- Event callback functiononReload
- Reload request callback - handle reloading the webpage and reopening the SDK
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>
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:
- You wish to completely implement your own front-end
- You wish to do an offline bulk audit of previously verified end-users
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.
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 clients, 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 support for 6 months after release, including:
- Fixing all reported bugs in the upcoming SDK release
- Fixing critical bugs in any final version before a major release for three months
- In case an SDK release requires major implementation efforts, then the old version will be supported for one year
Notifications before major changes to SDK support such as:
- Dropping support for an SDK version, where we will inform you via email one month in advance
- The end of the one-month grace period, after which Veriff will block future use of a specified SDK version
- When end-users engage with outdated SDKs, they will receive a prompt to upgrade the host application
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:
- Major Release (X) - These releases may require addtional development efforts, and often come with large-scale improvements to the SDK
- Minor Release (Y) - These do not come with any mandatory development efforts on your end, but may include new functionalities that require development efforts to be activated
- Bug-fix Release (Z) - These resolve issues from the previous release and do not introduce any new features or improvements
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 account manager. 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
- New session link is generated
- Session data is saved with your record
- Sessions with odd names can be started
- Sessions with
vendorData
- do you get them back and do you perform actions on them - End-user is granted access to your platform after receiving an
Approved
decision - End-user is notified about verification failure after receiving
Resubmission
orDeclined
decision - End-user is prompted to try again after receiving
Resubmission
decision. Note that the end-user has 9 resubmission attempts, the 10th attempt is an automatic decline. See the note here for more info. - In case of resubmitted session, end-user is directed to same
sessionURL
- In case of disrupted session (browser close, end-user logout, etc.,), the end-user should be directed back to earlier session
- In case generated session is over 7 days old (and thus in
Expired
orAbandonded
status), a new session is generated - At end of verification,
callbackURL
redirects back to the correct place in your platform
Also see our support article for getting the desired test verification result [🡕]
Testing security
- A webhook with wrong API key should not be accepted
- A webhook with mismatched X-HMAC-SIGNATURE should not be accepted
- A webhook with invalid JSON should not break or crash your server
Testing responses
Each type of response should be accepted:
- Approved (Decision endpoint)
- Declined (Decision endpoint)
- Resubmission (Decision endpoint)
- Review (Decision endpoint)
- Expired (Decision endpoint)
- Abandoned (Decision endpoint)
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:
- Approved end-users handled or notified as appropriate
- Declined end-users handled as appropriate, your back office notified if necessary
- In case of resubmission request, end-user is invited back to try KYC again using the same
sessionURL
- In case of
Expired
orAbandoned
session (after 7 days), end-user is not offered to continue from same session, newsessionURL
is created
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/)
- Download and install Node.js
- Download and extract js-integration-demo-master.zip
- Open Command (Windows) or Terminal (Mac) on your local computer.
- Navigate to js-integration-demo-master folder
cd C:\Users\User\Desktop\Veriff API).
- Run command >npm install
- 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 most of the clients. For batch tests, clients will need to prepare dataset that will be used for testing. If you have been asked for dataset please see batch test data preparetion guide [🡕].
End-User In The Flow
Session Status Diagram
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:
- the API key, to use it as the X-AUTH-CLIENT value in the Header
- the shared secret key, to create the X-HMAC-SIGNATURE value for the Header
- the BaseURL, to create the API URL for the request
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:
- Adding new properties to existing API responses
- Changing the order of properties in existing API responses
- Adding new API resources
- Adding new optional request parameters to existing API methods
- Changing the length or format of opaque strings, such as error messages, object IDs, etc.,
- Adding new event types to Webhooks
- Adding new properties to Webhook payloads
- Webhook listener should gracefully handle unfamiliar event types
Endpoints
Available endpoints and methods:
- POST /sessions
- GET /attempts/{attemptId}/media
- GET /media/{mediaId}
- GET /transportation-registry/{attemptId}
- GET /attempts/{attemptId}/proof-of-address
- GET /address/{addressId}/media
- GET /address-media/{mediaId}
- POST /validate-registry
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.
POST /sessions
Creates a session with the data specified in the request body.
The client 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
verification
:object
Verification objectcallback
:string
Default is defined on settings.callbackUrl
to where the end-user is redirected after the verification session is completedperson
:object
Person to be verifiedfirstName
:string
First namelastName
:string
Last nameidNumber
:string
National identification numbergender
:string
GenderdateOfBirth
:string
(YYYY-MM-DD) Date of birth
document
:object
Document of a person to be verifiednumber
:string
Document numbercountry
:ISO-2
String Issuing country of the documenttype
:string
(PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS_LICENSE) Document type. See the document types
address
:object
Address of a person to be verifiedfullAddress
:string
Full address
vendorData
:string
Client-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 client's domain). Although it can have several use-cases, this is a recommended field to improve fraud mitigation.
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
status
:string
Request statusverification
:object
Verification objectid
:UUID
-v4 String UUID v4 which identifies the verification sessionurl
:string
URL of the verification to which the person is redirected (Combination of thebaseUrl
andsessionToken
)vendorData
:string
- Client-specific data string, max 1000 characters longhost
:string
The base url the sessionToken can be used forstatus
:string
Verification session statussessionToken
:string
Session-specific token of the verification
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
.
- Only one image can be uploaded with one request
- Only .jpg, .jpeg and .png formats can be uploaded
- The image file is defined as base64 encoded image string inside a JSON body object
- To avoid issues with upload, keep the image smaller than 24MB in base64 encoding (approx 17MB in jpg/png format)
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
image
:object
(required)context
:string
(required) Context type of the document (one offace
,document-front
,document-back
)content
:string
(required) base64 encoded image (only .png, .jpg, .jpeg formats)- Example
data:image/png;base64,R0lGODlhAQABAAAAACw=
- Example
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
status
:string
Request statusimage
:object
Image objectcontext
:string
Context type of the imageid
:UUID-v4
String UUID v4 which identifies the imagename
:string
File name that identifies the imagetimestamp
:object
(Deprecated) Timestamp object, will return null/Nonesize
:integer
Size for the imagemimetype
:string
Format of the media fileurl
:string
URL for the image
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
verification
:object
(required)status
:string
(required) Status of a verification ("submitted")
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
status
:string
Request statusverification
:object
Verification objectid
:UUID-v4
String UUID v4 which identifies the verification sessionurl
:string
URL for the timestampvendorData
:string
Client specific data string, max 1000 characters longhost
:string
Host URIstatus
:string
Status of the verificationsessionToken
:string
Session specific token of the verification
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}
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
status
:string
Status of the requestverifications
:object
Array of JSON objects identifying the attemptsid
:UUID
-v4` attempt Idstatus
:string
status of the attempt. It can be one ofcreated
,started
,abandoned
,expired
,submitted
,approved
,resubmission_requested
,declined
,inflow_completed
,review
.
Sample Response
{
"status": "success",
"verifications": [
{
"id": "f5c68aea-7f4d-478d-80ab-ca9356074f69",
"status": "approved"
},
{
"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:
- the Integration needs to have the Webhook decisions URL configured
- 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:
- Open the verification session on Verifications [🡕] page (requires a login to Station)
- Press the Update status button
- Select a status
Live integrations
For live integrations, you need to define the Webhook decisions URL:
- Go to the Integrations [🡕] page (requires a login to Station)
- Open the relevant integration
- Navigate to Integration Settings
- Add your URL to the Webhook decisions URL field
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
status
:string
Status of the responseverification
:object
Verification request decision object. Null if decision is not available yetid
:string
UUID v4 which identifies the verification sessioncode
:integer
(one of 9001, 9102, 9103, 9104, 9121) Verification response code. More information about decision codesperson
:object
Verified persongender
:string | null
(M, F or Null) GenderidNumber
:string | null
National identification numberlastName
:string | null
Last namefirstName
:string | null
First namecitizenship
:(Deprecated)
null
dateOfBirth
:string
(YYYY-MM-DD) Date of birthnationality
:string | null
NationalityyearOfBirth
:string | null
(YYYY) Year of birthplaceOfBirth
:string | null
Place of birthpepSanctionMatch
:string | null
PEP check result. It is optional, depending on integration.addresses
:array of objects
It is optional, depending on integration.fullAddress
:string
Address as single string.parsedAddress
:object
Object with parsedfullAddress
. It is optional, depending on integration.city
:string | null
unit
:string | null
Apartment numberstate
:string | null
street
:string | null
country
:string | null
postcode
:string | null
houseNumber
:string | null
reason
:string | null
Reason of failed Verificationstatus
:approved
(one of approved, resubmission_requested, review, declined, expired, abandoned) Verification statuscomments
:array
(Deprecated)document
:object
Verified documenttype
:string
(PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS_LICENSE, OTHER) Document type. See the document typesnumber
:string | null
Document numbercountry
:string
ISO-2 Document countryvalidFrom
:string | null
Document is valid from datevalidUntil
:string | null
Document is valid until dateplaceOfIssue
:string | null
Place where document was issued. Optional field, depending on integration.firstIssue
:string | null
Date of document first issue in YYYY-MM-DD format. Optional field, depending on integration.issueNumber
:string | null
Document issue number. Optional field, depending on integration.issuedBy
:string | null
Document issuing authority. Optional field, depending on integration.
reasonCode
:integer | null
Reason code of failed Verification See Response and error codesvendorData
:string | null
Client-specific data string. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the client's domain)decisionTime
:string
Timestamp of the decision. Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:SSS+Timezone OffsetacceptanceTime
:string
Timestamp of the session generation. Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:SSS+Timezone OffsethighRisk
:boolean
If session is considered high risk or not. Optional, depending on integration.additionalVerifiedData
:object
Data which has been optionally verified for session.driversLicenseCategory
:object
Optional, depending on integration.B
:boolean | null
driversLicenseCategoryFrom
:object
Driving license category obtention date. Optional, depending on integration.B
:string | null
Category is valid from date in YYYY-MM-DD format
driversLicenseCategoryUntil
:object
Driving license category expiry date. Optional, depending on integration.B
:string | null
Category is valid until date in YYYY-MM-DD format
estimatedAge
:number
Estimated age. Optional, depending on integration.estimatedGender
:number
Estimated gender. Optional, depending on integration. Values closer to 0.0 indicate 'male', values closer to 1.0 indicate 'female'.
riskLabels
:array
Optional array of risk labels related to the session. The presence of this property depends on risk labels being enabled for the integration. Full list of risk labels (requires Veriff Station login) [🡕]label
:string
Name of the risk labelcategory
:string
(one of client_data_mismatch, cross-links, device, document, images, network, session, person)sessionIds
:array of strings
Array of verification IDs that are referenced to the particular risk label.
biometricAuthentication
object
Optional object of Biometric Authentication data of the session. The presence of this property depends on biometric authentication being enabled for the integration.matchedSessionId
:string | null
UUID v4 which refers to the verification session ID which face matched.matchedSessionVendorData
:string | null
UUID v4 which refers to the verification session vendor data or end-user UUID which face matched.
technicalData
:object
Technical data objectip
:string | null
IP of the device from which the verification was made
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",
"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"
}
}
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
status
:string
Status of the requestperson
:object
List of objects identifying the Person associated with the search termid
:uuid
Unique identifier of the PersonfirstName
:string
Person's first namelastName
:string
Person's last nameidCode
:string
Person's ID codedateOfBirth
:string
(YYYY-MM-DD) Person's date of birthgender
:string
(M: male, F: female, null: undefined) Person's gendernationality
:string
ISO 3166-1 Alpha-2 country codeplaceOfBirth
:string
Person's place of birthcitizenships
: Deprecated, will return [ ]pepSanctionMatches
:object
Array of objects identifying the PEP and Sanction valuesprovider
:string
Name of the data providernumberOfMatches
:number
Total number of hitsdate
:string
Combined ISO 8601 date and time in UTC (YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset|Z, i.e., 2018-04-18T11:02:05.261Z)matches
:object
Array of objects listing info about matches to the search termname
:string
Person's namenationality
:string
Person's nationalitycategory
:string
Defines the category, SIP of PEP
hits
:object
Array of objects matching the search termdoc
: Array of objects identifying the info in the document of the Personid
:string
Document numberlast_updated_utc
: Combined ISO 8601 date and time in UTC (YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset|Z, i.e., 2018-04-18T11:02:05.261Z)createdUtc
: Combined ISO 8601 date and time in UTC (YYYY-MM-DDTHH:MM:S.SSS+Timezone Offset|Z, i.e., 2018-04-18T11:02:05.261Z)fields
:object
Array of objects describing the document fieldsname
:string
Name of the document fieldsource
:string
Source of the information in the documentvalue
:string
Value in the document fieldtag
:string
Tag related to the name objectlocale
:string
Language
types
:string
Array of objects (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) Names of match types as defined by the data providername
:string
Person's name on the documententity_type
:string
(person) Type of entity. In this GET request, it's always "person"aka
: Array of alternative names of the Personname
:string
Person's alternative name
associates
:object
Array of objects identifying Associates of the Personassociation
:string
Type of association (relationship)name
:string
Associate's name
sources
:array
Info about the information sourceskeywords
:array
Will return []media
: Array of objects containing media about the Persondate
:string
Combined ISO 8601 date and time in UTC (YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset|Z, i.e., 2022-04-18T11:02:05.261Z)snippet
:string
Text about the Persontitle
:string
Title of the text about the Personurl
:string
Web address to the text about the Person
assets
: Array of objects listing the info about media sourcespublicURL
:string
Web addresssource
:string
Name of the sourcetype
:string
File format
sourceNotes
:object
Array of objects identifying the information sourceamlTypes
:array
List of types as defined by the data providercountry_codes
:array
List of country ISO 1366-1 Alpha-2 codeslistingStartedUtc
: Combined ISO 8601 date and time in UTC (YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset|Z, i.e., 2022-04-18T11:02:05.261Z)name
:string
Name of the info sourceurl
:string
Web address of the info source
matchTypes
:string
(name_exact, aka_exact, name_fuzzy, aka_fuzzy, phonetic_name, phonetic_aka, equivalent_name, equivalent_aka, unknown) Info about which data was matchedmatchTypesDetails
: Array of more detailed breakdown of why a match happenedmatchTypes
:string
(name_exact, aka_exact, name_fuzzy, aka_fuzzy, phonetic_name, phonetic_aka, equivalent_name, equivalent_aka, unknown) Info about which data was matchedtype
:string
Displays the type of the match_type that was matched
matchStatus
:string
(no_match, false_positive, potential_match, true_positive, unknown, true_positive_approve, true_positive_reject) Status of the matchisWhitelisted
:boolean
Indicates whether an entity has been whitelisted. Availability depends on the configurationscore
:decimal
The request results match and ranking is computed via a score that is included as part of the metadata. It is not an absoluteT ranking of the document, only giving some relative indication of relevance.
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
status
:string
Status of the requestvideos
:object
Array of JSON objects identifying the videoscontext
:string
Context type of the video. See here for more info about the videocontext
.id
:UUID
-v4 Video Idmimetype
:string
Format of the media filename
:string
Video nameduration
:string
Video duration in secondsurl
:string
Video download urlsize
:string
Video size in bytestimestamp
:object
(Deprecated) Timestamp object, will return null/None
images
:object
Array of JSON objects identifying the imagescontext
:string
Context type of the image. See here for more info about the imagecontext
.id
:UUID
-v4 Image Idname
:string
Image nameurl
:string
Image download urlsize
:string
Image size in bytesmimetype
:string
Format of the media filetimestamp
:object
(Deprecated) Timestamp object, will return null/None
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 Clients 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
status
:string
Status of the responsedata
:object
Status of the responseattemptId
:string
UUID v4 which identifies session attemptvendorData
:string
Client-specific data string, max 1000 characters long, set during session creation. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the client's domain)checkType
:string
(one of initial_result, updated_result)matchStatus
:string
(one of possible_match, no_match)searchTerm
:object
Data used to perform the checkname
:string
Full name used during the checkyear
:string
Birth year used during the check
totalHits
:integer
total number of hits returned from the checkcreatedAt
:string
Timestamp indicating when the check response was receivedhits
:array
Check response hits array of matched records. Empty array if no hits were not foundmatchedName
:string
The name that was matched in this hit based on the search termcountries
:array
List of countries that sources listed in relation to this hitdateOfBirth
:string
Birth date of the person in the matched listingsdateOfDeath
:string
Death date of the person in the matched listingsmatchTypes
:array
Array that shows the match type in the listingsaka
:array
Array of names that the matched person is also known asassociates
:array
Array of names that the matched person is associated withlistingsRelatedToMatch
:object
Matched listings. Empty object if subscription addon "PEP & Sanctions check" was not enabledwarnings
:array
Array of warning matches. Empty array if no warnings were foundsourceName
:string
Name of the listingsourceUrl
:string
Url of the listingdate
:string
Date of the listing. Null if listing doesn't have a date
sanctions
:array
Array of sanctions matches. Empty array if no sanctions were foundsourceName
:string
Name of the listingsourceUrl
:string
Url of the listingdate
:string
Date of the listing. Null if listing doesn't have a date
fitnessProbity
:array
Array of fitness probity matches. Empty array if no fitness probities were foundsourceName
:string
Name of the listingsourceUrl
:string
Url of the listingdate
:string
Date of the listing. Null if listing doesn't have a date
pep
:array
Array of PEP matches. Empty array if no PEP matches were foundsourceName
:string
Name of the listingsourceUrl
:string
Url of the listingdate
:string
Date of the listing. Null if listing doesn't have a date
adverseMedia
:array
Array of media matches. Empty array if no media were foundsourceName
:string
Name of the listingsourceUrl
:string
Url of the listingdate
:string
Date of the listing. Null if listing doesn't have a date
Sample response
No match
{
"status": "success",
"data": {
"attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",
"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",
"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
status
:string
Status of the requestvideos
:object
Array of JSON objects identifying the videoscontext
:string
Context type of the video. See here for more info about the videocontext
.id
:UUID
-v4 Video Idname
:string
Video nameduration
:string
Video duration in secondsurl
:string
Video download urlsize
:string
Video size in bytestimestamp
:object
(Deprecated) Timestamp object, will return null/Nonemimetype
:string
Format of the media file
images
:object
Array of JSON objects identifying the imagescontext
:string
Context type of the image. See here for more info about the imagecontext
.id
:UUID-v4
Image Idname
:string
Image nameurl
:string
Image download urlsize
:string
Image size in bytestimestamp
:object
(Deprecated) Timestamp object, will return null/Nonemimetype
:string
Format of the media file
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
rightToDrive
:object
Right to drive check resultattemptId
:string
UUID v4 which identifies session attemptstatus
:string
(valid, invalid, not_applicable, inconclusive) Status of the right to drivereason
:string
Human readable reason, only in case right to drive is invalidvalidUntil
:string
right to drive is valid until (YYYY-MM-DD)
Sample response
{
"rightToDrive": {
"attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
"reason": "Expired right to drive",
"status": "invalid",
"validUntil": "2016-08-31",
},
}
GET /attempts/{attemptId}/proof-of-address
Returns the Proof of Address check result for an attempt 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)
= attemptId
signed with the shared secret key
Content-Type: application/json
Sample request
curl
curl -X GET \
--url '/v1/attempts/55d3a307-f799-44d7-aab2-0de70ebe1f2c/proof-of-address' \
-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/55d3a307-f799-44d7-aab2-0de70ebe1f2c/proof-of-address',
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/55d3a307-f799-44d7-aab2-0de70ebe1f2c/proof-of-address'
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
status
:string
Status of the requestdata
:object
JSON object contained proof of address check resultattemptId
:UUID-v4
Attempt IDstatus
:string
Status of the proof of address checkcreated
:string
Check was created at dateupdated
:string
Check was updated at datename
:string
Name of the end-useraddress
:string
Normalized addressparsedAddress
:object
Parsed addresscity
:string
Citystate
:string
Stateline1
:string
Line 1line2
:string
Line 2country
:string
CountrypostCode
:string
Post code
dateOfIssue
:string
Detected document issue datenameConfidence
:number
Name extraction confidence. Float number ranging from 0.00 to 1.00nameMatched
:boolean | null
Comparison between the uploaded document, and an optional name input. It will return null if name is not inputaddressConfidence
:number
Address extraction confidence. Float number ranging from 0.00 to 1.00documentConfidence
:number
Document confidence. Integer number ranging from 1 to 100documentType
:string
See the document types
Sample response
{
"status": "success",
"data": {
"attemptId": "55d3a307-f799-44d7-aab2-0de70ebe1f2c",
"status": "success",
"created": "2022-08-16T07:45:07.627Z",
"updated": "2022-08-16T07:45:07.627Z",
"name": "Jane Doe",
"address": "Jaan Koorti 777, 99999 Tallinn, Estonia",
"parsedAddress": {
"city": "Tallinn",
"state": "Harju maakond",
"line1": "777 Jaan Koorti",
"line2": "Lasnamäe linnaosa",
"country": "Estonia",
"postCode": "99999",
},
"dateOfIssue": "2022-10-05",
"nameConfidence": 0.96,
"nameMatched": true,
"addressConfidence": 0.93,
"documentConfidence": 62,
"documentType": "invoice"
}
}
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
status
:string
Status of the requestimages
:object
Array of JSON objects identifying the imagescontext
:string
Context type of the image (address-front
)id
:UUID-v4
Image Idname
:string
Image nameurl
:string
Image download urlsize
:string
Image size in bytesmimetype
:string
Format of the media file
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:
idNumber
fullName
OR (firstName
+lastName
)dateOfBirth
ORaddress
data.- If
address
data is provided thenfullAddress
OR (street
+houseNumber
) are required
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
verification
:object (required)
Verification objectcallback
:string
Default is defined on settings.callbackUrl
to where the end-user is redirected after the verification session is completedperson
:object (required)
Person whose national ID will be validatedidNumber
:string (required)
National ID to validatefirstName
:string
First namelastName
:string
Last namefullName
:string
Full namephoneNumber
:string
Phone numberdateOfBirth
:string
(YYYY-MM-DD) Date of birth
address
:object
Address datastreet
:string
StreethouseNumber
:string
House numberfullAddress
:string
Full addresscity
:string
Citystate
:string
Statepostcode
:string
Postal codeunit
:string
Unit
vendorData
:string
Client-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 client's domain)
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
status
:string
Request statusverification
:object
Verification objectid
:UUID
-v4 String UUID v4 which identifies the verification sessionvendorData
:string
Client-specific data string, max 1000 characters longstatus
:string
Verification session statussessionToken
:string
Session specific token of the verification
Sample response
{
"status": "success",
"verification": {
"id":"f04bdb47-d3be-4b28-b028-a652feb060b5",
"vendorData": "11111111",
"status": "submitted",
"sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoX3Rva2VuIjoiOThiYzdjMjEtZTQ0Yy00MTZiLTkxOTMtMTU5ZGZkMzBmMDg4Iiwic2Vzc2lvbl9pZCI6Ijc2ODhmMzYzLTAyZjctNDE1My1iMzM1LWE0ODQ3OTRkMzZmNyIsImlhdCI6MTUwMTIyODI1MSwiZXhwIjoxNTAxODMzMDUxfQ.bMEF37E6-zT2Aa6Q8UXK3B_ZL51w6D_lxnGgQvhj214"
}
}
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
providerName
:string
Fingerprinting service provider's name, max 255 charactersperson
:object
Array of information about the person. Optional fieldemail
:string
Person's e-mail address entered during the validation. Optional fieldphoneNumber
:string
Person's phone number, can include numbers, whitespaces and the "+" sign in front. Optional field
network
:object
Array of network related datamobileCarrier
:string
Name of the service provider. Optional fieldssid
:string
Service Set Identifier (SSID) value. Optional fieldhostname
:string
Optional fieldlocation
:object
Array of location data. Optional fieldcountryCode
:string
ISO 3166-1 Alpha-2 country code. Optional fieldcontinentCode
:string
(EU, NA, AS, SA, AF, OC) Two-letter code of the continent. Optional fieldcity
:string
City name, in English. Optional fieldregion
:string
Region code or name, in English. Optional fieldtimezone
:string
Timezone abbreviation as listed in the Timezones Database. Optional field
ip
:object
Array of IP info. At least one is mandatory!addressV4
:string
IPv4 info. Optional if IPv6 info is includedaddressV6
:string
IPv6 info. Optional if IPv4 info is included
asn
:object
Array of ASN info. Optional fieldnumber
:string
Autonomous System Number (ASN). Optional fieldorganisation
:string
Name of the organization owning the ASN. Optional field
device
:object
Array of end-user's device related datafingerprint
:string
Device fingerprint, max 255 charactersandroidId
:string
The Android unique device ID is a combination of 8 digits and letters, followed by a dash and three sets of 4 digits and letters, all letters are lowercase. Optional fieldidfv
:string
The Identifier for Vendors (IDFV) code, example F325G3GB-12FC-352F-C6C3-DZ52F0F690D8. Optional fieldmodel
:string
Device model. Optional fieldvendor
:string
Device supplier. Optional fieldtype
:string
(desktop, mobile, tablet, other) Device type. Optional fieldbrowser
:object
Array of browser data. Optional fieldlanguages
:array
IETF language tag, for example: "es-419", "en-gb", "pl". Optional fielduserAgent
:string
Browser user agent, max 255 characters. Optional fieldtimezoneOffsetMinutes
:number
An integer number for the time offset from the UTC, in minutes (range from -1440 to +1440 minutes) Optional fieldisIncognito
:boolean
Data about whether the incognito mode is on. Optional field
audio
:object
Array of device audio info. Optional fielddevices
: [{name
:string
}] Array of objects. Optional field
screen
:object
Array of data about device screen. Optional fieldheightPixels
:number
An integer number in range of 1–100000. Optional fieldwidthPixels
:number
An integer number in range of 1–100000. Optional fielddpi
:number
An integer number in range of 1–100000. Optional field
battery
:object
Array of device battery related info. Optional fieldlevel
:number
A float number in range of 0.0–1.0. Optional fieldcharging
:boolean
Data about whether the device is charging. Optional field
os
:object
Array of device operating system (OS) data. Optional fieldfamily
:string
OS family. Optional fieldname
:string
OS name. Optional fieldplatform
:string
OS platform type, for example "x64", "ARM", "OS/390". Optional fieldversion
:string
OS version. Optional field
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
status
:string
Status of the requestsessionId
:string
UUID v4 which identifies the verification sessionattemptId
:string
UUID v4 which identifies the attempt
Sample response
{
"status": "success",
"sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"attemptId": "f5c68aea-7f4d-478d-80ab-ca9356074f69"
}
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 different IDV endpoints.
Brief overview of the flow
- Submit a session using the POST sessions endpoint
- Make a POST /sessions/{sessionId}/media request to send image file
- Update the session status to "submitted" using the PATCH /sessions/{sessionId}
- 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:
- A list of the prerequisites you need to generate an X-HMAC-SIGNATURE
- Examples of some technical options which you can use to generate the signature
- Explanation about how you can locally validate the generated signature
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:
- API key (you can find it in Station, on relevant integration’s page). You will use it as X-AUTH-CLIENT header
- Shared secret key (you can find it in Station, on relevant integration’s page). You will use it to sign the payload
Content-Type
header (in Veriff’s API requests case,application/json
)- API request’s payload (defined in each Endpoint’s
Headers
explanation)
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:
- For ease of use, go for a dedicated HMAC signature generator which supports the generation of HMAC-SHA256 signatures, like OpenSLL, OAuth.io [🡕] or Postman
- If you want control and flexibility, you can create a script (see some mock scripts here) or use a command-line tool (a mock openssl script)
- If you are familiar with a programming language, you can use built-in cryptographic libraries (see a mock Python example here)
- If you need the signature quickly and security is not a priority, you can use an online tool (see an example below)
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
Biometric Authentication
Veriff offers two different possibilities to use biometric authentication.
Broadly explained, the options are:
- 1:1 matching - you can verify that the person authenticating themselves is the person they claim they are
- 1:n matching - you can find out if the person authenticating themselves has been verified before, and who they are
Prerequisites for Biometric Authentication
- An IDV integration and an authentication integration set up, connected to one another (has to be done by your dedicated team at Veriff)
- 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:
- Generate an authentication session using the Authentication integration tokens. (Check
/sessions
endpoint in the API reference here). a. Use thevendorData
field to pass the same end-user identifier used in the IDV session if you are doing 1:1 biometric match. b. LeavevendorData
field empty if you are doing 1:n biometric match. - 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 tosubmitted
status using PATCH /sessions/{sessionId} endpoint. - Receive the results from Veriff via webhooks.
Biometric Authentication handling decisions
The verification.status
and verification.code
can be :
approved
, code 9001declined
, code 9102expired
/abandoned
, code 9104
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
Face Match (Deprecated)
Prerequisites for Face Match
- 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.
- A Face-match integration should be configured. (Reach out to your contact at Veriff to set it up for you!)
Face Match process overview
- 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). - Upload the reference image (document-front). Check
/sessions/{sessionId}/media POST
endpoint here. Note: Set context parameter asdocument-front
while using POST media endpoint. - 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 tosubmitted
status using PATCH /sessions/{sessionId} endpoint. - 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 client 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 client 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 client 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 |
|
resubmission_requested | 606 | Face is not clearly visible | |
resubmission_requested | 608 | Document front missing |
|
resubmission_requested | 619 | Document data not visible | |
expired | null | null | Create a new session for the user |
abandoned |
Face Match Service Flow Diagram
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 retry the notification once in every hour 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.
Webhook decisions URL
is where we post decisions about verifications (approved, declined, resubmission_required, expired, abandoned, review), see the sample payloadWebhook events URL
is where we post events during the lifecycle of a verification (started, submitted), see the sample payload or a proof of address data gathering (started, submitted) see the sample payload.Webhook watchlist screening URL
is where we post events related to both the initial and monitored results of the PEP, sanctions, and adverse media checks, see the example payload
Meaning of the various verification responses
Verification status is one of
- approved
- resubmission_requested
- declined
- expired
- abandoned
- review
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:
- Photos and videos uploaded to us
- The data on the document is readable and matches throughout the document
- The end-user's portrait photo is recognizable
- The end-user on the portrait photo corresponds to the person on the document photo
- The document is valid (dates, etc.,) A positive decision means that the person was verified. The verification process is complete.
Accessing the KYC session URL again will tell the end-user that nothing more is to be done.
Reasons for negative conclusive decisions
- Physical document not used
- Suspected document tampering
- Person showing the document does not appear to match document photo
- Suspicious behaviour
- Velocity/abuse
- Known fraud
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
- Video and/or photos missing
- Face not clearly visible
- Full document not visible
- Poor image quality
- Document damaged
- Document type not supported
- Document expired
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:
- Age checks
- Name validation checks
- An end-user is unable to pass verification as required, but their attempt is sincere and the document is legitimate
- An end-user has made multiple fraudulent attempts to verify and cannot pass Veriff's verification any more
- You wish to restrict the end-user's access to your platform based on their earlier behavior
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:
7001
:Started
7002
:Submitted
For proof of address:
7004
:Started
7005
:Submitted
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 account manager to activate the feature.
Properties
{
"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"
}
}
Properties explained:
status
:String
Status of the responseverification
:object
Verification request decision object. Null if decision is not available yetid
:String
UUID v4 which identifies the verification sessioncode
:Integer
(one of 9001, 9102, 9103, 9104, 9121) Verification session decision code. More information about verification session decision code.person
:object
Verified persongender
:String | null
(M, F or Null) GenderidNumber
:String | null
National identification numberlastName
:String | null
Last namefirstName
:String | null
First namecitizenship
:(Deprecated)
null
dateOfBirth
:String
(YYYY-MM-DD) Date of birthnationality
:String | null
NationalityyearOfBirth
:String | null
(YYYY) Year of birthplaceOfBirth
:String | null
Place of birthpepSanctionMatch
:String | null
PEP check result. It is optional, depending on integration.addresses
:Array of objects
It is optional, depending on integration.fullAddress
:String | null
Address as single string.parsedAddress
:object
Object with parsedfullAddress
. It is optional, depending on integration.city
:String | null
unit
:String | null
Apartment numberstate
:String | null
street
:String | null
country
:String | null
postcode
:String | null
houseNumber
:String | null
reason
:String | null
Reason of failed Verificationstatus
:approved
(one of approved, resubmission_requested, review, declined, expired, abandoned) Verification statuscomments
:(Deprecated)
Array
document
:object
Verified documenttype
:String
(PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS_LICENSE, OTHER) Document type. See the document typesnumber
:String | null
Document numbercountry
:String
ISO-2 Document countryvalidFrom
:String | null
Document is valid from datevalidUntil
:String | null
Document is valid until dateplaceOfIssue
:String | null
Place where document was issued. Optional field, depending on integration.firstIssue
:String | null
Date of document first issue in YYYY-MM-DD format. Optional field, depending on integration.issueNumber
:String | null
Document issue number. Optional field, depending on integration.issuedBy
:String | null
Document issuing authority. Optional field, depending on integration.
reasonCode
:Integer | null
Reason code of failed Verification See Response and error codesvendorData
:String | null
Client-specific data string. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the client's domain).decisionTime
:String
Timestamp of the decision. Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone OffsetacceptanceTime
:String
Timestamp of the session generation. Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone OffsethighRisk
:bool
If session is considered high risk or not. Optional, depending on integration.additionalVerifiedData
:object
Data which has been optionally verified for session.driversLicenseCategory
:object
Optional, depending on integration.B
:boolean | null
driversLicenseCategoryFrom
:object
Driving license category obtention date. Optional, depending on integration.B
:String | null
Category is valid from date in YYYY-MM-DD format
driversLicenseCategoryUntil
:object
Driving license category expiry date. Optional, depending on integration.B
:String | null
Category is valid until date in YYYY-MM-DD format
estimatedAge
:Number
Estimated age. Optional, depending on integration.estimatedGender
:Number
Estimated gender. Optional, depending on integration. Values closer to 0.0 indicate 'male', values closer to 1.0 indicate 'female'.
riskLabels
:array
Optional array of risk labels related to the session. The presence of this property depends on risk labels being enabled for the integration. Full list of risk labels (requires Veriff Station login) [🡕]label
:String
Name of the risk labelcategory
:String
(one of client_data_mismatch, crosslinks, device, document, images, network, session, person)sessionIds
:Array of strings
Array of verification IDs that are referenced to the particular risk label.
biometricAuthentication
object
Optional object of Biometric Authentication data of the session. The presence of this property depends on biometric authentication being enabled for the integration.matchedSessionId
:String | null
UUID v4 which refers to the verification session ID which face matched.matchedSessionVendorData
:String | null
UUID v4 which refers to the verification session vendor data or end-user UUID which face matched.
technicalData
:object
Technical data objectip
:String | null
IP of the device from which the verification was made
Event webhook
This is the description of the payload sent to Webhook events URL
.
We can get two types of events:
- Verification events: tracks events for identity verification process performed by the end-user.
- Proof of address events: if feature is enabled, tracks events for proof of address data gathering performed by the end-user.
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:
- The end-user arrives to Veriff environment and starts the verification process
- The end-user is done with the process and submits the attempt.
Properties
{
"id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
"feature": "selfid",
"code": 7002,
"action": "submitted",
"vendorData": "QWE123"
}
Properties explained:
id
:String
(required) UUID v4 which identifies the verification sessionattemptId
:String
(required) UUID v4 which identifies session attemptfeature
:String
(required) Feature on which the event was triggered (selfid refers to the end-user flow)code
:Integer
(required) Event code (one of 7001, 7002)action
:String
(required) Corresponding action description (one of started, submitted)vendorData
:String
Client-specific data string, max 1000 characters long, set during session creation. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the client's domain).
Proof of address events
To track the progress of proof of address data gathering, Veriff allows to subscribe to the following events:
- When the end-user arrives to Veriff environment and starts the proof of address process
- When the end-user is done with the process and submits the attempt.
Properties
{
"id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"addressId": "f087f21f-5282-41b8-9857-6f85c28b8122",
"feature": "selfid",
"code": 7005,
"action": "submitted",
"vendorData": "QWE123"
}
Properties explained:
id
:String
(required) UUID v4 which identifies the proof of address sessionaddressId
:String
(required) UUID v4 which identifies proof of address session attempt. Used for example for getting uploaded mediafeature
:String
(required) Feature on which the event was triggered (selfid refers to the end-user flow)code
:String
(required) Event code (one of 7004, 7005)action
:String
(required) Corresponding action description (one of started, submitted)vendorData
:String
Client-specific data string, max 1000 characters long, set during session creation
Watchlist screening webhook
This is the description of the payload sent to Webhook watchlist screening URL
.
The response of the check is sent back to the client once the check is complete or an ongoing monitoring check comes in.
Properties
{
"checkType": "updated_result",
"attemptId": "54233318-f81c-4ec4-8e4c-413168a3f5e6",
"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"
}
]
}
}
]
}
Properties explained:
checkType
:updated_result
(one of initial_result, updated_result)attemptId
:String
UUID v4 which identifies session attemptvendorData
:String
Custom unique identifier that you can set. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the client's domain).matchStatus
:String
(one of possible_match, no_match)searchTerm
:Object
Data used to perform the checkname
:String
Full name used during the checkyear
:String
Birth year used during the check
totalHits
:Integer
total number of hits returned from the checkcreatedAt
:String
Timestamp indicating when the check response was receivedhits
:Array
Check response hits array of matched records. Empty array if no hits were not foundmatchedName
:String
The name that was matched in this hit based on the search termcountries
:Array
List of countries that sources listed in relation to this hitdateOfBirth
:String
Birth date of the person in the matched listingsdateOfDeath
:String
Death date of the person in the matched listingsmatchTypes
:Array
Array that shows the match type in the listingsaka
:Array
Array of names that the matched person is also known asassociates
:Array
Array of names that the matched person is associated withlistingsRelatedToMatch
:Object
Matched listings. Empty object if "PEP & Sanctions" add-on is not enabledwarnings
:Array
Array of warning matches. Empty array if no warnings were foundsourceName
:String
Name of the listingsourceUrl
:String
Url of the listingdate
:String
Date of the listing. Null if listing doesn't have a date
sanctions
:Array
Array of sanctions matches. Empty array if no sanctions were foundsourceName
:String
Name of the listingsourceUrl
:String
Url of the listingdate
:String
Date of the listing. Null if listing doesn't have a date
fitnessProbity
:Array
Array of fitness probity matches. Empty array if no fitness probities were foundsourceName
:String
Name of the listingsourceUrl
:String
Url of the listingdate
:String
Date of the listing. Null if listing doesn't have a date
pep
:Array
Array of PEP matches. Empty array if no PEP matches were foundsourceName
:String
Name of the listingsourceUrl
:String
Url of the listingdate
:String
Date of the listing. Null if listing doesn't have a date
adverseMedia
:Array
Array of media matches. Empty array if no media were foundsourceName
:String
Name of the listingsourceUrl
:String
Url of the listingdate
:String
Date of the listing. Null if listing doesn't have a date
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.
Properties
{
"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"
}
Properties explained:
eventType
:String
Transportation registry events, one of [transportation_registry_check.verified
]eventCode
:Number
Code for the current event type, one of [7006]details
:Objbect
Details connected to the specific check against one transportation registryrightToDrive
:String
Right to drive check data included in this elementattemptId
:String
UUID v4 which identifies session attemptreason
:String
Description of the reason for the resultstatus
:String
Status of the right to drive check, one of [valid, invalid, not_supported, inconclusive]validUntil
:String
(YYYY-MM-DD) Ending date of the validity of the right to drive (note: this value is different than expiration date of the driver's document)
sessionId
:String
Unique identifier for the session where this check was executedvendorData
:String
Additional client.-specific data. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the client's domain).
Proof of address webhook
This is the description of the payload sent to Webhook proof of address URL
.
The response of the check is sent back to the client once the check is completed.
Properties
{
"eventCode": 9201,
"eventType": "proof_of_address_success",
"version": "1.0.0",
"created": "2022-08-24T19:50:10.664Z",
"sessionId": "125c0472-ebae-4cc9-a0de-bd6574c6bfc1",
"vendorData": null,
"details": {
"attemptId": "55d3a307-f799-44d7-aab2-0de70ebe1f2c",
"status": "success",
"created": "2022-08-16T07:45:07.627Z",
"updated": "2022-08-16T07:45:07.627Z",
"name": "Jane Doe",
"address": "Jaan Koorti 777, 99999 Tallinn, Estonia",
"parsedAddress": {
"city": "Tallinn",
"state": "Harju maakond",
"line1": "777 Jaan Koorti",
"line2": "Lasnamäe linnaosa",
"country": "Estonia",
"postCode": "99999"
},
"dateOfIssue": "2022-10-05",
"documentType": "invoice",
"nameConfidence": 0.96,
"nameMatched": true,
"addressConfidence": 0.93,
"documentConfidence": 62
}
}
Properties explained:
eventCode
:Number
Code for the current event type, one of [9201]eventType
:String
Proof of address events, one of [proof_of_address_success
]version
:String
Proof of address webhook version. Uses semantic versioning.created
:String
Timestamp indicating when the check response was receivedsessionId
:String
Unique identifier for the session where this check was executedvendorData
:String
Additional client-specific data. We require only non-semantic data to be submitted (UUID-s etc., that can not be resolved or used outside the client's domain).details
:Object
Details connected to the specific check against one proof of addressattemptId
:String
UUID v4 which identifies session attemptstatus
:String
Status of the proof of address check, one of [success]created
:String
Timestamp indicating when the attempt was createdupdated
:String
Timestamp indicating when the attempt was updatedname
:String
Name of the end-useraddress
:String
Normalized addressparsedAddress
:Object
Parsed addresscity
:String
Citystate
:String
Stateline1
:String
Line 1line2
:String
Line 2country
:String
CountrypostCode
:String
Postal code
dateOfIssue
:String
Detected document issue datenameConfidence
:Number
Name match confidence. Float number ranging from 0.00 to 1.00nameMatched
:boolean | null
Comparison between the uploaded document, and an optional name input. It will return null if name is not inputaddressConfidence
:Number
Address match confidence. Float number ranging from 0.00 to 1.00documentConfidence
:Number
Document confidence. Integer number ranging from 1 to 100documentType
:String
See the document types
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"}}'
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. This has to be done by your dedicated team at Veriff.
Process overview
- Once the integration is set up, generate a verification session using the regular /sessions endpoint.
- 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
- 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. This has to be done by your dedicated team at Veriff.
Process overview
- 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
- Change the status of the session to “Submitted” using PATCH /sessions/{sessionId} endpoint
- 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
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. |
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 client'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 client'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 |
---|---|
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 |
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 |
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 |
539 | Resubmission limit exceeded |
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 |
640 | Person did not give consent |
641 | Multiple Faces Detected |
642 | Multiple Documents Uploaded |
643 | Unable to crop face image from a document front |
646 | Unable to estimate age |
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:
PASSPORT
ID_CARD
DRIVERS_LICENSE
RESIDENCE_PERMIT
If it's not possible to classify the document as one of the above, the response can show "type": "OTHER"
.
See also:
- request body of POST /session
- response body of GET /sessions/{sessionId}/decision
- response body of decision webhook
Supported document types for PoA
In the Proof of Address verification, the response bodies can display the
document
object. This contains the documentType
string. The documentType
can be one of the following
document types:
BANK_STATEMENT
PAYSLIP
TAX_FORM
INVOICE
UTILITY_BILL
CHECK
DRIVING_LICENSE
BUSINESS_FILING
FINANCIAL_STATEMENT
SOCIAL_SECURITY_CARD
If it's not possible to classify the document as one of the above, the response shows "documentType": "UNKNOWN"
.
See also:
- response body of PoA webhook
- response body of GET /attempts/{attemptId}/proof-of-address
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. |
|
Client | General | Veriff's client 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 | Client's customer, who goes through the verification flow (aka end-user flow). | Occasionally, referred to as the customer. | |
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). |