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.
Getting started with Veriff
Signing up
Fill-in the form at veriff.com and an e-mail with instructions on how to log in will be sent to you.
Logging in
Veriff’s environment can be accessed by going to Veriff Station. To log in for the first time, please use the link sent in the email and follow instructions.
New users for your colleagues can be created by an Administrator role account in Veriff Station Team page.
How to find your API keys
Your API keys are stored in the Veriff Station. Choose Integrations in the top menu, then integration you need.
Once you open integration you'll see Publishable key and Private key. Private key is your API secret and Publishable key is the API Key
There are two types of Integrations that can be created by Station user:
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 a user",
"timestamp": "2016-05-19T08:30:25.597Z"
}
}
The simplest way to get a verification link for web verification flow is to create JSON object containing the user's name and the redirect(callback) URL to which the user will be sent after completing 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 session ID should be saved on your end - you can tie back the webhook responses to your customer record that way.
The session token is a JSON web token that consists of HS256 encrypted session ID and session creation timestamp. It will expire in 7 days.
Once the end user completes the verification flow, they will be redirected to the callback URL. If callback URL is not specified for the session, user will be redirected to Integration's default Callback URL, which can be set up in Station. It is important to note, the callback does not contain any decision or verification information yet.
Receiving decisions
There are 3 options to fetch decisions for a verification session:
Manual: Station Verifications list 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 key (API private 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 API private 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 View the individual verification sessions.
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 vendor:
Android
Xiaomi browser
UC Browser
Facebook webview
iOS
- All Non-Safari iOS browsers on iOS versions prior to 14.3.
Integrations
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:4.+'
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 |
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()
.themeColor(getResources().getColor(R.color.theme_color))
.backgroundColor(getResources().getColor(R.color.background_color))
.statusBarColor(getResources().getColor(R.color.status_bar_color))
.primaryTextColor(getResources().getColor(R.color.primary_text_color))
.secondaryTextColor(getResources().getColor(R.color.secondary_text_color))
.toolbarIcon(R.drawable.toolbar_icon)
.bulletPoint(R.drawable.bullet_point)
.buttonCornerRadius(48f)
.notificationIcon(R.drawable.notification_icon)
.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 primary button background color
You can customize the background color of the primary button in the SDK by passing a color value to the primaryButtonBackgroundColor
method ot the Branding
builder. Note that this value is expected to be
a @ColorInt
representation of color. In case the custom button background color is not specified the SDK will use themeColor
. If themeColor
is not specified SDK will use default color instead.
Branding branding = new Branding.Builder()
.primaryButtonBackgroundColor(getResources().getColor(R.color.your_custom_button_background_color))
.build();
Customizing the button height
You can customize the height of the buttons used in the SDK by passing a height value to the buttonHeight
method of the Branding
builder. Note that this value is expected to be
a float denoting the dp value and should be in the inclusive range of 32f to 96f. In case the height is not customized or the value passed is out of the range the default height of 60dp will be used.
branding.buttonHeight(50f);
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
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 4 types of fonts via the setNormalAndBold
setItalic
and setBoldItalic
methods.
It is mandatory to pass both normal and bold fonts when setting a custom font hence the setNormalAndBold
method accepts both, in case you want to set one type of font only you can pass the same font resource ID as
arguments to both parameters to the setNormalAndBold
method. The setItalic
and setBoldItalic
are optional and does not have any effect now, they are added for future compatibility.
branding.font(
new com.veriff.Font.Builder()
.setNormalAndBold(R.font.comic_neue_regular, 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 user's perspective
break;
case CANCELED:
// 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(<Instance of your logging class>);
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 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:4.0.0') {
exclude group: 'com.veriff', module: 'mlkit'
}
Android SDK Changelog
Please refer to release notes.
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.
java
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.
java
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 9.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/
After clicking Next, select the version you would like to integrate and complete the integration.
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"
After a carthage update
add Veriff framework from Carthage/Build/<platform>
to project.
To target build phases carthage copy-frameworks
run script step add the following input files:
$(SRCROOT)/Carthage/Build/iOS/Veriff.framework
To target build phases carthage copy-frameworks
run script step add the following output files:
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Veriff.framework
Using XCFramework
To integrate VeriffSDK into your project manually, please download VeriffSDK.
After framework is downloaded, drag VeriffSDK.xcframework into the Frameworks, Libraries, and Embedded Content section of your target and that's all!
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 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 4 descriptions listed below to info.plist
of your application with the explanation of the usage.
NSCameraUsageDescription
NSMicrophoneUsageDescription
NSPhotoLibraryUsageDescription
NFCReaderUsageDescription
Add required steps for NFC scanning
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>
Add a new entitlement for NFC scanning, available since iOS 13. This new entitlement is added automatically by Xcode when enabling the Near Field Communication Tag Reading capability in the target Signing & Capabilities. After enabling the capability the *.entitlements file needs to contain the TAG format:
<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 sessionUrl
you receive from your backend implementation [Required].
// 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 |
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 theme color, navigation bar title image, button background color, height and corner radius, background color, status bar color, primary and secondary text colors, bullet point image, button title text casing and font. 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 yourColor = UIColor.someColor()
let yourImage = UIImage(named: "logo.png")
let branding = VeriffSdk.Branding(themeColor: yourColor, logo: yourImage)
branding.primaryButtonBackgroundColor = UIColor.primaryButtonBackgroundColor
branding.buttonHeight = CGFloat.buttonHeight
branding.buttonCornerRadius = CGFloat.cornerRadius
branding.backgroundColor = UIColor.backgroundColor
branding.statusBarColor = UIColor.statusBarColor
branding.primaryTextColor = UIColor.primaryTextColor
branding.secondaryTextColor = UIColor.secondaryTextColor
branding.bulletPoint = UIImage(named: "bulletPoint.png")
branding.isTextUppercase = false
branding.font = VeriffSdk.Branding.Font(regularFontName: "Font", lightFontName: "Font-Light", semiBoldFontName: "Font-SemiBold", boldFontName: "Font-Bold")
// Objective-C
UIImage *logo = [UIImage imageNamed:@"logo.png"];
VeriffBranding *branding = [[VeriffBranding alloc] initWithThemeColor:[UIColor greenColor] logo:logo];
branding.primaryButtonBackgroundColor = [UIColor greenColor];
branding.buttonHeight = 56;
branding.buttonCornerRadius = 5;
branding.backgroundColor = [UIColor lightGrayColor];
branding.statusBarColor = [UIColor redColor];
branding.primaryTextColor = [UIColor darkTextColor];
branding.secondaryTextColor = [UIColor lightTextColor];
branding.bulletPoint = [UIImage imageNamed:@"bulletPoint.png"];
branding.isTextUppercase = false;
branding.font = [[VeriffBrandingFont alloc] initWithRegularFontName: @"Font" lightFontName: @"Font-Light" semiBoldFontName: @"Font-SemiBold" boldFontName: @"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 user successfully submitted the session
break
case .canceled:
// The user canceled the verification process.
break
case .error(let error):
switch error {
// ...
}
}
}
}
// Objective-C
- (void)sessionDidEndWithResult:(VeriffResult *)result {
switch (result.status) {
case VeriffStatusDone:
// The user successfully submitted the session
break;
case VeriffStatusCanceled:
// The 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
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. See the example here.
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.
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 9.0 and Android version 5.0 (api 21) or higher.
Install the plugin to your project
Follow instructions here to install the plugin.
Android specific configuration
If you want to customize the notification icon please add the icon to your flutter app`s Android resources at android/res/drawable
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 and NFC reader permissions for capturing photos, video and scanning passport during identification. Your application is responsible to describe the reason why camera, microphone 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
NFCReaderUsageDescription
Add required steps for NFC scanning
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>
Add a new entitlement for NFC scanning, available since iOS 13. This new entitlement is added automatically by Xcode when enabling the Near Field Communication Tag Reading capability in the target Signing & Capabilities. After enabling the capability the *.entitlements file needs to contain the TAG format:
<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 9.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 sessionUrl you receive from your backend implementation[Required].
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 main color and logo.
See the Veriff SDK customization guide document to see what it looks like.
Veriff Flutter plugin allows the customization of UI elements and icons in the SDK flow by passing the optional parameters when launching Veriff;
AssetImage logo = AssetImage(path_of_image);
Branding branding = Branding(
themeColor: "#ff00ff",
backgroundColor: "#f2ff00",
statusBarColor: "#ff7700",
primaryTextColor: "#52b35c",
secondaryTextColor: "#3a593d",
buttonCornerRadius: 5,
logo: logo,
androidNotificationIcon: "ic_notification",
primaryButtonBackgroundColor: "#123abc"
);
Note: If you are customizing androidNotificationIcon
don't forget to add the icon to the android/res/drawable
folder.
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. Same applies to image assets - when they aren't defined, the defaults are 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 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 9.0 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 9.0 or higher:
platform :ios, '9.0'
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 and NFC reader permissions for capturing photos, video and scanning passport during identification. Your application is responsible to describe the reason why camera, microphone 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
NFCReaderUsageDescription
Add required steps for NFC scanning
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>
Add a new entitlement for NFC scanning, available since iOS 13. This new entitlement is added automatically by Xcode when enabling the Near Field Communication Tag Reading capability in the target Signing & Capabilities. After enabling the capability the *.entitlements file needs to contain the TAG format:
<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 9.0 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';
Before you can launch the verification flow you'll need a session URL. See our documentation on generating one.
Once you have the URL 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 main color and logo.
See Veriff SDK customization guide document on how it looks.
Veriff React Native SDK allows the customization of various colors, images and fonts in the SDK flow by passing in these optional properties when launching Veriff:
var result = await VeriffSdk.launchVeriff({
sessionUrl: SESSION_URL,
branding: {
themeColor: '#ff00ff',
backgroundColor: '#ffffff',
statusBarColor: '#ff00ff',
primaryTextColor: '#000000',
secondaryTextColor: '#333333',
primaryButtonBackgroundColor: '#444444',
buttonCornerRadius: 28,
logo: 'parrot', // see alternative options for logo below
androidNotificationIcon: 'ic_parrot',
iOSFont: {
regularFontName: 'Font-Regular',
lightFontName: 'Font-Light',
semiBoldFontName: 'Font-Semibold',
boldFontName: 'Font-Bold'
},
androidFont: {
regularFontName: 'font_regular',
boldFontName: 'font_bold',
}
},
});
When a color or a font isn't defined the default Veriff theme color or font is used. Same applies to image assets - when they aren't defined the defaults are 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 both 'parrot.png' and 'ic_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: {
themeColor: '#ff00ff',
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: {
themeColor: '#ff00ff',
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,
branding: {
themeColor: '...',
},
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,
branding: {
themeColor: '...',
},
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:
// user submitted the images and completed the flow
// note that this does not mean a final decision yet
break;
case VeriffSdk.statusCanceled:
// 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 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
Versions
- Added new customization option to provide background color for primary button.
- Added implmentation type parameter.
- Updated public readme of the package in npmjs, no functional changes.
- Updated public readme of the package in npmjs, no functional changes.
- Added new customization options to provide background, status bar and text colors.
- Added an option to customize primary button corner radius.
- The logo customization option now supports URLs and RN assets.
- Updated the iOS native module to use Veriff iOS SDK 4.+
- New public API for the React Native SDK.
- Updated the iOS native module to use Veriff iOS SDK 3.+
- Updated the Android native module to use Veriff Android SDK 3.+
- Enabled Java 8 support for Android.
- Added more granular error messages for NFC related errors.
- Fixed a 'NoSuchKeyException: branding' error on Android if no customization was applied
- Added support for UI customization
- Updated README in npmjs.com
- Initial React Native SDK release
Release 2.5.0
Release 2.4.0
Release 2.3.2
Release 2.3.1
Release 2.3.0
Release 2.2.0
Release 2.1.0
Release 2.0.0
Release 1.1.0
Release 1.0.1
Release 1.0.0
Release 0.9.1
Release 0.9.0
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.1/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.
const veriff = Veriff({
apiKey: 'API_KEY',
parentId: 'veriff-root',
onSession: function(err, response) {
// received the response, verification can be started now
}
});
veriff.mount();
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 400 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 of the vendor environment). 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 a 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
- user closed the modal.FINISHED
- user finished verification flow.
Closing modal
const veriffFrame = createVeriffFrame({ url: VERIFF_SESSION_URL });
veriffFrame.close();
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 });
Adding Content Security Policy to JS SDK
add_header Content-Security-Policy default-src 'self' *.veriff.me;
script-src 'unsafe-inline' 'unsafe-eval' 'self' *.veriff.me *.google-analytics.com *.googletagmanager.com *.hotjar.com *.probity.io;
img-src blob: 'self' *.probity.io *.google-analytics.com;
frame-src 'self' *.hotjar.com;
connect-src 'self' *.veriff.me *.probity.io;
style-src 'self' *.veriff.me 'unsafe-inline';
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 customers. For example:
- you wish to completely implement your own front-end
- you wish to do an offline bulk audit of previously verified customers
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 customers, or not expect customers to be present for the verification.
Here are the steps you should do to use the API for upload.
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).
If you wish to restrict the accepted document to be the one you have on file, you can also send the document type, country, and number along with the session. Document type can be one of [‘PASSPORT’, ‘ID_CARD’, ‘RESIDENCE_PERMIT’, ‘DRIVERS_LICENSE'].
Send photos
Send photos (face, document front, document back, etc) by uploading all the pictures one by one using POST request to ‘/media’
The goal here is to upload the required photos and associate them with the verification created in step 1.
Documentation: /sessions/{sessionId} /media (POST)
Submit session for review
Submit the verification session using PATCH request to ‘/sessions/:id’
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.
Documentation: /sessions/{sessionid} (PATCH)
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.
Documentation: Webhook Decision (POST)
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
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 quality of Veriff responses, please select plan and subscribe to a Trial on Billing page - this will allow to create Live integrations.
Testing verification sessions checklist
- New session link is generated
- Session data is saved with your customer record
- Sessions with odd names can be started
- Sessions with vendorData - do you get them back and do you perform actions on them
- User is granted access to your platform after receiving an "Approved" decision
- User is notified about verification failure after receiving "Resubmission" or "Declined" decision
- User is prompted to try again after receiving "Resubmission" decision
- In case of resubmitted session, user is directed to same SessionURL
- In case of disrupted session (browser close, user logout, etc), user should be directed back to earlier session
- In case generated session is over 7 days old (and thus in Expired or Abandonded status)- new session is generated
- At end of verification, callback URL 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 public 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 Requested (Decision endpoint)
- Review (Decision endpoint)
- Expired (Decision endpoint)
- Abandoned (Decision endpoint)
Testing process in your app
You should test the handling of best cases as well as edge cases
- approved users handled or notified as appropriate
- declined users handled as appropriate, your back office notified if necessary
- in case of resubmission request, user is invited back to try KYC again using the same session URL
- in case of Expired or Abandoned session (after 7 days), user is not offered to continue from same session, new session URL 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 customers 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
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;
- Webhook listener should gracefully handle unfamiliar event types;
Requirements
API public key and API private key can be found in customers integration settings page.
Headers
X-AUTH-CLIENT: string (required) - API public 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 API private key
API URL https://<Base-URL>/v1/
Note: to get Base URL, choose 'Integrations' in the top menu of Veriff Station, then integration you need.
Lifecycle of a verification:
Endpoints
In this post request the vendor sends the data of the client to Veriff and in return, recieves a unique sessionToken that is related to the client.
You can find the sample implementation for Javascript.
https://github.com/Veriff/js-integration-demo
The URIs have the following structure:
https://<Base-URL>/v1/
For example, https://your-veriff-baseUrl/v1/sessions/
Note: to get Base URL choose Integrations in the top menu of Veriff Station, then integration you need.
Available endpoints and methods:
/sessions
Creates a session with specified verification data.
Available request properties:
verification
:object (required)
Verification objectcallback
:String
- default is defined on settings - Callback url to which the client 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, DRIVERS_LICENSE, RESIDENCE_PERMIT) Document type
additionalData
:object (This field is deprecated , not actively used by Veriff)
- Data from the filled application. JSON object should not have any nested objects it’s just simple key value pairvendorData
:string
- Vendor specific data string, max 400 characters long, will be sent back unmodified using webhooks. 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)timestamp
:String (required)
- Combined ISO 8601 date and time in UTC (YYYY-MM-DDTHH:MM:S+Timezone Offset|Z, i.e., 2018-04-18T11:02:05.261Z)
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
Content-Type: application/json
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"
},
"vendorData": "11111111",
"timestamp": "2016-05-19T08:30:25.597Z"
}
}'
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',
timestamp: '2016-05-19T08:30:25.597Z' } },
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'
],
'timestamp': '2016-05-19T08:30:25.597Z'
}
})
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
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 the baseUrl and sessionToken)sessionToken
:String
Session specific token of the verificationbaseUrl
:String
The base url the sessionToken can be used for
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Content-Type: application/json
Sample RESPONSE
{ "status": "success",
"verification":{
"id":"f04bdb47-d3be-4b28-b028-a652feb060b5",
"url": "https://alchemy.veriff.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoX3Rva2VuIjoiOThiYzdjMjEtZTQ0Yy00MTZiLTkxOTMtMTU5ZGZkMzBmMDg4Iiwic2Vzc2lvbl9pZCI6Ijc2ODhmMzYzLTAyZjctNDE1My1iMzM1LWE0ODQ3OTRkMzZmNyIsImlhdCI6MTUwMTIyODI1MSwiZXhwIjoxNTAxODMzMDUxfQ.bMEF37E6-zT2Aa6Q8UXK3B_ZL51w6D_lxnGgQvhj214",
"sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoX3Rva2VuIjoiOThiYzdjMjEtZTQ0Yy00MTZiLTkxOTMtMTU5ZGZkMzBmMDg4Iiwic2Vzc2lvbl9pZCI6Ijc2ODhmMzYzLTAyZjctNDE1My1iMzM1LWE0ODQ3OTRkMzZmNyIsImlhdCI6MTUwMTIyODI1MSwiZXhwIjoxNTAxODMzMDUxfQ.bMEF37E6-zT2Aa6Q8UXK3B_ZL51w6D_lxnGgQvhj214",
"baseUrl": "https://alchemy.veriff.com"
}
}
/sessions/{sessionId} PATCH
Method to change the status of the verification.
Request properties explained:
verification
:object
(required)status
:String
(required) Status of a verification (submitted)timestamp
:String
(required) Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:S+Timezone Offset|Z, i.e., 2018-04-18T11:02:05.261Z)
Request method: PATCH
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Content-Type: application/json
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",
"timestamp": "2019-10-29T06:30:25.597Z"
}
}'
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',
timestamp: '2019-10-29T06:30:25.597Z' } },
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',
'timestamp': '2019-10-29T06:30:25.597Z'
}
})
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
Response properties explained:
status
:String
Request statusverification
:object
Verification objectid
:UUID-v4
String UUID v4 which identifies the imageurl
:String
URL for the timestamphost
:String
Host URIstatus
:String
Status of the verificationsessionToken
:String
Session specific token of the verification
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Content-Type: application/json
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"
}
}
/sessions/{sessionId} DELETE
Method to request deletion of a session. Availability of this feature depends on service level.
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 method: DELETE
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Session ID signed with API Private 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 Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Content-Type: application/json
Success response
Response HTTP status code: 202 Accepted
Response body:
{
"status": "success",
"verification": {
"id": "fd5c1563-1d23-4b1a-ae46-7ba429927ed8"
}
}
Limited access response
Response HTTP status code: 429 Too Many Requests
Response body:
{
"status": 429,
"code": "1004",
"message": "Too many requests",
}
/sessions/{sessionId}/media GET
Get the list of media objects with sessionId = {sessionId} If fetched within 7 days of session submit, the list of objects will be sorted by most relevant-> least relevant.
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Session ID signed with API Private 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
Response Properties explained:
status
:String
Status of the requestvideos
:object
Array of JSON objects identifying the videoscontext
:String
Type of a video (selfid_video|face-pre-video|document-front-pre-video|document-back-pre-video|document-and-face-pre-video|document-back-barcode-pre-video)id
:UUID
-v4 Video Idname
:String
Video nameduration
:String
Video duration in secondsurl
:String
Video download urlsize
:String
Video size in bytestimestamp
:object
Timestamp object, deprecated, will return null/None
images
:object
Array of JSON objects identifying the imagescontext
:String
Type of an image (face|face-pre|face-nfc|document-back|document-back-pre|document-front|document-front-pre|document-and-face|document-and-face-pre). For proof of address images will return type (address-front)id
:UUID
-v4 Image Idname
:String
Image nameurl
:String
Image download urlsize
:String
Image size in bytestimestamp
:object
Timestamp object, deprecated, will return null/None
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Content-Type: application/json
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": null(deprecated),
"url": "{MEDIA_DOWNLOAD_URL}"
}
],
"images": [
{
"context": "{IMAGE_TYPE}",
"id": "{MEDIA_ID}",
"name": "{IMAGE_NAME}",
"url": "{MEDIA_DOWNLOAD_URL}",
"sessionId": "{SESSIOND_ID}",
"timestamp": null(deprecated),
"size": "{SIZE_IN_B}",
"mimetype": "{MEDIA_MIME_TYPE}"
}
]
}
/sessions/{sessionId}/media POST
In this post request the vendor sends a file (base64 encoded image string inside a JSON body object), where they could upload images (1 image at a time), specifying also a type of the image that is being uploaded.
Request
Request properties explained:
image
:object
(required)context
:String
(required) Type of a document (face|document-front|document-back)content
:String
base64 encoded image (png|jpg|jpeg)- Example
data:image/png;base64,R0lGODlhAQABAAAAACw=
timestamp
:string
(required) Combined ISO 8601 date and time in UTC (YYYY-MM-DDTHH:MM:S+Timezone Offset|Z, i.e., 2018-04-18T11:02:05.261Z)
Request method: POST
Media type: application/json
Type: object
Headers:
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Content-Type: application/json
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=",
"timestamp": "2019-10-29T06:30:25.597Z"
}
}'
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=',
timestamp: '2019-10-29T06:30:25.597Z' } },
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=',
'timestamp': '2019-10-29T06:30:25.597Z'
}
})
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:
Response properties explained:
status
:String
Request statusimage
:object
Image objectcontext
:String
Type of an imageid
:UUID-v4
String UUID v4 which identifies the imagename
:String
File name that identifies the imagetimestamp
:Object
Timestamp object, deprecated, will return null/Nonesize
:Integer
Size for the imagemimetype
:String
Type for the imageurl
:String
URL for the image
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Content-Type: application/json
Sample RESPONSE
{ "status": "success",
"image":{
"context": "document-back",
"id": "39388f8d-c6d6-4e9b-92c6-6978b2e8d664",
"name": "document-back",
"timestamp": null,
"size": 52268,
"mimetype": "image/png",
"url": "/v1/media/39388f8d-c6d6-4e9b-92c6-6978b2e8d664"
}
}
/sessions/{sessionId}/person
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Session ID signed with API Private 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 Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private key
Content-Type: application/json
Sample response from primary data provider
{
"status": "success",
"person": {
"id": "uuid",
"firstName": "string",
"lastName": "string",
"idCode": "string",
"dateOfBirth": "string, format (YYYY-MM-DD)",
"gender": "string, values can be M - male, F - female, null - undefined",
"nationality": "string, iso2 country code",
"placeOfBirth": "string, place of birth",
"citizenships": [
{
"kind": "string, Main or Secondary",
"citizenship": "string, country name"
}
],
"pepSanctionMatches": [
{
"numberOfMatches": "number",
"providerSearchId": null,
"date": "date with timestamp, 2018-11-28T17:13:28.154Z",
"matches": [
{
"name": "string",
"nationality": "string",
"category": "string, SIP or PEP"
},
],
"hits": []
}
]
}
}
Sample response from alternative data provider
{
"status": "success",
"person": {
"id": "uuid",
"firstName": "string",
"lastName": "string",
"idCode": "string",
"dateOfBirth": "string, format (YYYY-MM-DD)",
"gender": "string, values can be M - male, F - female, null - undefined",
"nationality": "string, iso2 country code",
"placeOfBirth": "string, place of birth",
"citizenships": [
{
"kind": "string, Main or Secondary",
"citizenship": "string, country name"
}
],
"pepSanctionMatches": [
{
"providerSearchId": "string"
"numberOfMatches": "number",
"date": "date with timestamp, 2018-11-28T17:13:28.154Z",
"matches": [],
"hits": [
{
"doc": {
"aka": [
{ "name": "string" },
],
"associates": [
{
"association": "string",
"name": "string"
},
],
"entity_type": "string, values can be person or organisation",
"fields": [
{
"name": "string",
"source": "string",
"value": "string",
"tag": "string",
"locale": "string"
},
],
"id": "string",
"keywords": ["string"],
"last_updated_utc": "date with timestamp, 2018-11-28T17:13:28Z",
"name": "string",
"source_notes": {},
"sources": ["string"],
"types": ["string"]
},
"match_types": ["string, values can be: name_exact, aka_exact, name_fuzzy, aka_fuzzy, phonetic_name, phonetic_aka, equivalent_name, equivalent_aka, unknown"],
"match_types_details": {
"string": {
"match_types": {
"string": ["string, values can be: name_exact, aka_exact, name_fuzzy, aka_fuzzy, phonetic_name, phonetic_aka, equivalent_name, equivalent_aka, unknown"],
},
"type": "string"
},
},
"score": "decimal",
"match_status": "string, can be: no_match, false_positive, potential_match, true_positive, unknown, true_positive_approve, true_positive_reject",
"is_whitelisted": "boolean"
},
]
}
]
}
}
/sessions/{sessionId}/watchlist-screening (GET)
Request method: GET
Media type: application/json
Type: object.
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Session ID signed with API Private 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 Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private key
Content-Type: application/json
Response Properties:
status
:String
Status of the responsedata
:Object
Status of the responseattemptId
:String
UUID v4 which identifies session attemptvendorData
:String
Client - specific data string, max 400 characters long, set during session creation. 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).checkType
:updated_result
(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 foundsource_name
:String
Name of the listingsource_url
: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 foundsource_name
:String
Name of the listingsource_url
: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 foundsource_name
:String
Name of the listingsource_url
: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 foundsource_name
:String
Name of the listingsource_url
: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 foundsource_name
:String
Name of the listingsource_url
: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."
}
/sessions/{sessionId}/attempts
Get the list of attempt objects with sessionId = {sessionId}
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Session ID signed with API Private key
Content-Type: application/json
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 = {
'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
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
.
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private key
Content-Type: application/json
Sample Response
{
"status": "success",
"verifications": [
{
"id": "f5c68aea-7f4d-478d-80ab-ca9356074f69",
"status": "approved"
},
{
"id": "f2270684-8c51-4d03-88eb-dafd43e8b486",
"status": "resubmission_requested"
}
]
}
/attempts/{attemptId}/media
Get the list of media objects with attemptId = {attemptId} If fetched within 7 days of session submit, the list of objects will be sorted by most relevant-> least relevant.
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Attempt ID signed with API Private key
Content-Type: application/json
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
Get the media with attemptId = {attemptId}
Response Properties explained:
status
:String
Status of the requestvideos
:Object
Array of JSON objects identifying the videoscontext
:String
Type of a video (selfid_video|face-pre-video|document-front-pre-video|document-back-pre-video|document-and-face-pre-video|document-back-barcode-pre-video)id
:UUID
-v4 Video Idname
:String
Video nameduration
:String
Video duration in secondsurl
:String
Video download urlsize
:String
Video size in bytestimestamp
:object
Timestamp object, deprecated, will return null/None
images
:Object
Array of JSON objects identifying the imagescontext
:String
Type of an image (face|face-pre|face-nfc|document-back|document-back-pre|document-front|document-front-pre|document-and-face|document-and-face-pre)id
:UUID-v4
Image Idname
:String
Image nameurl
:String
Image download urlsize
:String
Image size in bytestimestamp
:object
Timestamp object, deprecated, will return null/None
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private key
Content-Type: application/json
Sample RESPONSE
{
"status": "success",
"videos": [
{
"context": "{VIDEO_TYPE}",
"id": "{MEDIA_ID}",
"name": "{VIDEO_NAME}",
"duration": "{DURATION_IN_SECONDS}",
"url": "{MEDIA_DOWNLOAD_URL}",
"timestamp": "null",
"size": "{SIZE_IN_B}",
"mimetype": "{MEDIA_MIME_TYPE}"
}
],
"images": [
{
"context": "{IMAGE_TYPE}",
"id": "{MEDIA_ID}",
"name": "{IMAGE_NAME}",
"url": "{MEDIA_DOWNLOAD_URL}",
"timestamp": "null",
"size": "{SIZE_IN_B}",
"mimetype": "{MEDIA_MIME_TYPE}"
}
]
}
/transportation-registry/{attemptId}
Get the list of transportation registry results with attemptId = {attemptId}
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Attempt ID signed with API Private key
Content-Type: application/json
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
Get the media with attemptId = {attemptId}
Response Properties explained:
rightToDrive
:Object
Right to drive check resultattemptId
:String
UUID v4 which identifies session attemptstatus
:String
Status of the right to drive, can be any of ['valid', 'invalid', 'not_applicable', 'inconclusive']reason
:String
Human readable reason, only in case right to drive is invalidvalidUntil
:String
right to drive is valid until (YYYY-MM-DD)
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private key
Content-Type: application/json
Sample RESPONSE
{
"rightToDrive": {
"attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
"reason": "Expired right to drive",
"status": "invalid",
"validUntil": "2016-08-31",
},
}
/address/{addressId}/media
Get the list of media objects with addressId = {addressId} for proof of address sessions.
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Address ID signed with API Private key
Content-Type: application/json
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
Get the media with attemptId = {attemptId}
Response Properties explained:
status
:String
Status of the requestimages
:Object
Array of JSON objects identifying the imagescontext
:String
Type of an image (address-front)id
:UUID-v4
Image Idname
:String
Image nameurl
:String
Image download urlsize
:String
Image size in bytes
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private key
Content-Type: application/json
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}"
}
]
}
/sessions/{sessionId}/decision
Get the session decision with sessionId = {sessionId}
Note: to have verification object filled, it is necessary to have a webhook url configured for the integration which sessionId is linked with.
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Session ID signed with API Private key
Content-Type: application/json
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
Get the session decision with sessionId = {sessionId}
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
:9001
(one of 9001, 9102, 9103, 9104, 9121) Verification response code. Detailed meaning of the response codes:
Code Meaning Description 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. 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. 9103 Resubmitted: Resubmission has been requested The verification process is not completed. Something was missing from the client and she or he needs to go through the flow once more. The same sessionURL can and should be used for this purpose. 9104 Negative: Verification has been expired The verification process is complete. After 7 days the session gets expired. If the client started the verification process we reply - "abandoned", otherwise, if the client never comes back to the verification, the status will be "expired". 9121 Review: No conclusive decision is made Review status is issued whenever automation engine could not issue a conclusive decision and the verification session needs to be reviewed by a human. This status will be sent depending on service agreement. person
:object
Verified personfirstName
:String
First namelastName
:String
Last nameidNumber
:String
Identification numbercitizenship
:ISO-2
String CitizenshipdateOfBirth
:String
(YYYY-MM-DD) Date of birthgender
:String
(M, F or Null) Gender
reason
:String
Reason of failed Verificationstatus
:approved
(one of approved, resubmission_requested, declined, expired, abandoned, review) Verification statuscomments
:object
Array of additional comments by verification specialisttype
:String
The type of the commentcomment
:String
The comment itselftimestamp
:String
UTC timestamp
document
:object
Verified documentnumber
:String
Document numbertype
:String
(one of PASSPORT, ID_CARD, DRIVERS_LICENSE, RESIDENCE_PERMIT) Document typecountry
:ISO-2
String Document countryvalidFrom
:String
Document is valid from date
validUntil
:String
Document is valid until datehighRisk
:bool
if session is considered high risk or notriskLabels
:array
Optional array of risk labels related to the session. The presence of this property depends on risk labels being enabled for the integrationlabel
:String
name of the risk labelcategory
:String
(one of client_data_mismatch, crosslinks, device, document, images, network, session, person)
vendorData
:String
- Vendor specific data string. 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).decisionTime
:String
Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:S+Timezone OffsetacceptanceTime
:String
Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:S+Timezone OffsetadditionalVerifiedData
:object
Data which has been optionally verified for session.driversLicenseCategory
:object
Optional, depending on integration.B
:boolean | null
driversLicenseCategoryFrom
:object
(YYYY-MM-DD) Driving license category obtention date. Optional, depending on integration.B
:String
driversLicenseCategoryUntil
:object
(YYYY-MM-DD) Driving license category expiry date. Optional, depending on integration.B
:String
technicalData
:object
Technical data objectip
:String
Ip of the device from which the verification was made
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private key
Content-Type: application/json
/media/{mediaId}
Get the media with mediaId = {mediaId}
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Media ID signed with API Private key
Content-Type: application/json
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 Public Key
X-HMAC-SIGNATURE: string (required)
- Response body signed with API Private 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 Public Key
X-HMAC-SIGNATURE: string (required)
- Media ID signed with API Private key
Media ID: string (required)
- Media ID which can be parsed from /media response by session or attempt
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)
/address-media/{mediaId}
Get the media for proof of address with mediaId = {mediaId}
Request method: GET
Media type: application/json
Type: object
Headers
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Media ID signed with API Private key
Content-Type: application/json
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 Public Key
X-HMAC-SIGNATURE: string (required)
- Response body signed with API Private 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 Public Key
X-HMAC-SIGNATURE: string (required)
- Media ID signed with API Private 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)
X-HMAC-SIGNATURE
Signing requests
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.
You can secure the webhook listener in three ways:
- Have a secure SSL server for your webhook listener (Veriff will call only HTTPS URLs which are hosted by servers with a publicly verifiable certificate)
- Check the X-AUTH-CLIENT and X-HMAC-SIGNATURE headers on the received webhooks (the signature is calculated using the API private key that only you and Veriff know)
- If it is required you may restrict your webhook listener to only accept calls from the Veriff IP range (please ask your Veriff integration onboarding specialist for those details)
How to make sure the request to your endpoint originates from Veriff:
- Make sure X-AUTH-CLIENT and X-HMAC-SIGNATURE headers are present
- Compare the X-AUTH-CLIENT header to your public api key
- Generate the keyed hash using HMAC-SHA256 function and the API private key
- Hex encode the hash
- Compare the hex encoded hash with the X-HMAC-SIGNATURE header sent by Veriff
Generating X-HMAC-SIGNATURE
Here are few code examples how to sign the request.
Example verification payload:
In case of a GET request, where there is no payload in the body and just URL parameters, for example GET "/transportation-registry/123456, the payload to be signed will be the id from the URL as shown below:
payloadAsString="123456"
A second example, for POST /sessions, in this case the body includes a json payload:
payloadAsString="{"verification":{"callback":"https://veriff.com","person":{"firstName":"John","lastName":"Smith"},"document":{"type":"PASSPORT","country":"EE"},"vendorData":"unique id of a user","timestamp":"2016-05-19T08:30:25.597Z"}}"
The result of the generated hash should be 6af6d95822e19e9cc707aec55395d8d363ba2c7bc4625bc04ebeca0c7bf8cd67
using code examples below with the API private key abcdef12-abcd-abcd-abcd-abcdef012345
.
JavaScript / ECMAScript
const signature = crypto
.createHmac('sha256', apiPrivateKey)
.update(Buffer.from(payloadAsString, 'utf8'))
.digest('hex')
.toLowerCase();
console.log(signature);
Python
signature = hmac \
.new(api_secret, msg=payloadAsString, digestmod=hashlib.sha256) \
.hexdigest() \
.lower()
print(signature)
PHP
<?php
$signature = strtolower(hash_hmac('sha256', $payloadAsString, $apiPrivateKey));
echo $signature;
C# / .Net
var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(api_private_key));
var hash = hmacsha256.ComputeHash(Encoding.UTF8.GetBytes(payloadAsString));
var signature = Convert.ToHexString(hash).ToLower();
Console.WriteLine(signature);
Using online tooling
Use your favorite HMAC-SHA256 calculator to calculate the hash. E.g. https://codebeautify.org/hmac-generator (link opens in new window)
- Select SHA256 from the algorithm dropdown
- Paste the API private key provided earlier into "Enter Key" field
- Paste the example verification payload provided earlier into "Enter the Plain or Cipher Text" field
- Click on
Generate HMAC
- The result of generated hash is the same provided earlier
Signing your request with headers
To make sure you are sending correct HTTP headers, here is the list of the headers and their values to compose the correct request.
CONTENT-TYPE: application/json
X-AUTH-CLIENT: abcdef12-abcd-abcd-abcd-abcdef012345
X-HMAC-SIGNATURE: 6af6d95822e19e9cc707aec55395d8d363ba2c7bc4625bc04ebeca0c7bf8cd67
Validating X-HMAC-SIGNATURE
We sign all responses using the same logic so you can make sure that the response is sent by Veriff using the X-HMAC-SIGNATURE header.
Here are few examples how to validate the response signature.
JavaScript / ECMAScript
function isSignatureValid({ signature, apiPrivateKey, payload }) {
if (payload.constructor === Object) {
payload = JSON.stringify(payload);
}
if (payload.constructor !== Buffer) {
payload = new Buffer.from(payload, 'utf8');
}
const digest = crypto
.createHmac('sha256', apiPrivateKey)
.update(Buffer.from(payload, 'utf8'))
.digest('hex')
.toLowerCase();
return digest === signature.toLowerCase();
}
Testing the validation functionality
The easiest way to test the validation functionality is to setup small service in your localhost and use cURL with the correct payload to test it. This way you can test your functionality independently from our Webhook or API service.
Step 1 - Setup a simple HTTP server with a simple POST endpoint
Small JavaScript / ECMAScript code example
import express from 'express';
import bodyParser from 'body-parser';
import { createHmac } from 'crypto';
import { Server } from 'http';
const app = express();
const SERVICE_PORT = 3001;
const API_SECRET = 'abcdef12-abcd-abcd-abcd-abcdef012345';
function isSignatureValid({ signature, apiPrivateKey, payload }) {
if (payload.constructor === Object) {
payload = JSON.stringify(payload);
}
if (payload.constructor !== Buffer) {
payload = new Buffer.from(payload, 'utf8');
}
const digest = createHmac('sha256', apiPrivateKey)
.update(Buffer.from(payload, 'utf8'))
.digest('hex')
.toLowerCase();
return digest === signature.toLowerCase();
}
app.use(bodyParser.json());
let server = Server(app);
app.post('/verification/', (req, res) => {
res.json({
isSignatureValid: isSignatureValid({
signature: req.get('x-hmac-signature'), apiPrivateKey: API_SECRET, payload: req.body
})
});
})
server.listen(SERVICE_PORT, () => console.log('Server is UP \n Listening port:', SERVICE_PORT));
Step 2 - Post a prepared data into HTTP server
The curl request described below will return {"isSignatureValid":true}
if you use abcdef12-abcd-abcd-abcd-abcdef012345
as an API private key to validate the signature.
curl --request POST 'http://localhost:3001/verification/' -k \
--header 'accept:application/json' \
--header 'x-auth-client:abcdef12-abcd-abcd-abcd-abcdef012345' \
--header 'x-hmac-signature:6af6d95822e19e9cc707aec55395d8d363ba2c7bc4625bc04ebeca0c7bf8cd67' \
--header 'content-type:application/json' \
--data '{"verification":{"callback":"https://veriff.com","person":{"firstName":"John","lastName":"Smith"},"document":{"type":"PASSPORT","country":"EE"},"vendorData":"unique id of a user","timestamp":"2016-05-19T08:30:25.597Z"}}'
Attempts
/attempts /{attemptId}/media (GET)
Get the list of media objects with attemptId = {attemptId}
Request
URI Parameters attemptId: string (required)
Response
Properties
{
"status": "success",
"videos": [
{
"id": "{MEDIA_ID}",
"name": "{VIDEO_NAME}",
"duration": "{DURATION_IN_SECONDS}",
"url": "{MEDIA_DOWNLOAD_URL}",
"timestamp": {
"url": "{GUARDTIME_TIMESTAMP_URL}",
"id": "{TIMESTAMP_ID}"
},
"size": "{SIZE_IN_KB}",
"mimetype": "{MEDIA_MIME_TYPE}"
}
],
"images": [
{
"id": "{MEDIA_ID}",
"name": "{IMAGE_NAME}",
"url": "{MEDIA_DOWNLOAD_URL}",
"timestamp": {
"url": "{GUARDTIME_TIMESTAMP_URL}",
"id": "{TIMESTAMP_ID}"
},
"size": "{SIZE_IN_KB}",
"mimetype": "{MEDIA_MIME_TYPE}"
}
]
}
- status: String (required) Status of the request
- videos: object (required) Array of JSON objects identifying the videos
- id: UUID-v4 (required) Video Id
- name: String (required) Video name
- duration: String (required) Video duration in seconds
- url: String (required) Video download url
- size: String (required) Video size in KB
- timestamp: object (required) Timestamp object
- id: UUID-v4 (required) Timestamp Id
- url: String (required) Timestamp url
- images: object (required) Array of JSON objects identifying the images
- id: UUID-v4 (required) Image Id
- name: String (required) Image name
- url: String (required) Image download url
- size: String (required) Image size in KB
- timestamp: object (required) Timestamp object
- id: UUID-v4 (required) Timestamp Id
- url: String (required) Timestamp url
Media
/media /{mediaId} (GET)
Get the media
Request
Headers
X-AUTH-CLIENT
: string (required) API Public Key
X-HMAC-SIGNATURE
: string (required) Media ID signed with API Private key
URI Parameters
mediaId: string (required)
Response
Headers
X-AUTH-CLIENT
: string (required) API Public Key
X-HMAC-SIGNATURE
: string (required) Response body signed with API Private key
TRANSFER-ENCODING
: chunked
Response and error codes
Note: If you do not see the reason code you received here, see also granular reason codes
Common response codes | |
---|---|
Code | Description |
200 | `{ "status": "success", "data" }` |
201 | `{ "status": "success", "data" }` |
400 | `{ "status": "fail", "code:": "1102", "message": "Mandatory parameters are missing from the request." }` |
401 | `{ "status": "fail", "message": "Not Authorized." }` |
404 | `{ "status": "fail", "message": "Entry not found." }` |
500 | `{ "status": "fail", "message": "Something went wrong." }` |
Credentials & Authorization | |
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 | Vendor data cannot be more than 400 symbols. 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. |
1501 | Vendor data must be a string. We require only non-semantic data to be submitted (UUID-s etc that can not be resolved or used outside of the vendor environment). |
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. |
Reason and Decision codes | |
Decline | verification.reasonCode |
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 user. |
109 | Velocity/abuse duplicated device. |
110 | Velocity/abuse duplicated ID. |
112 | Restricted IP location |
Resubmit | verification.reasonCode |
Code | Description |
201 | Video and/or photos missing. |
204 | Poor image quality. |
205 | Document damaged. |
206 | Document type not supported. |
207 | Document expired. |
Decision | verification.code |
Code | Description |
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. |
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. |
9103 | Resubmitted: Resubmission has been requested. The verification process is not completed. Something was missing from the client and she or he needs to go through the flow once more. The same sessionURL can and should be used for this purpose. |
9104 | Negative: Verification has been expired. The verification process is complete. After 7 days the session gets expired. If the client started the verification process we reply "abandoned" here, otherwise if the client never arrived in our environment the status will be "expired" |
9121 | Review: Review status is issued whenever automation engine could not issue a conclusive decision and the verification session needs to be reviewed by a human. This status will be sent depending on service agreement. |
Granular reason codes
The reason codes mentioned here are subject to custom configuration in integration level, so please keep in mind that, you may or may not receive all the reason codes listed here .
Special Reason codes | |
---|---|
Decline | verification.reasonCode |
Code | Description |
106 | Known fraud |
108 | Velocity/abuse duplicated user |
109 | Velocity/abuse duplicated device |
110 | Velocity/abuse duplicated ID |
112 | Restricted IP location |
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 |
Resubmit | verification.reasonCode |
Code | Description |
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 |
Assisted Image Capture API
Process overview
- Generate session. Check
/sessions
endpoint in the API reference here to learn how to generate one. - Upload media
- Wait for response
- Patch session to inflow_completed
Upload media
Upload media for a specific verification session and receive inflow feedback
URL
/sessions/{sessionId}/media
Method
POST
URI Parameters
sessionId: string (required)
- Session uuid
Headers
Content-Type: application/json
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Request Properties
image
:object (required)
context
:string (required)
information about the media being uploaded. Possible options aredocument-front
,document-back
,face
,document-and-face
content
:string (required)
base64 encoded image (png|jpg|jpeg)timestamp
:string (required)
timestamp of when the photo was takeninflowFeedback
:boolean (optional)
if true, we wait up to 4 seconds to respond with feedback
Example request body
{
"image": {
"content": "/9j/4AAQSkZJRgABAQEBLAEsAAD/4R...",
"context": "document-back",
"timestamp": "2019-10-16T10:19:48.445Z",
"inflowFeedback": true
}
}
RESPONSE
Inflow feedback passed Happens when no issues were found with the image
Code
: 200 OK
{
"status": "success",
"image": {
"id": "be660c8f-3fc4-49aa-8051-ac042f07d6c7",
"name": "document-back",
"context": "document-back",
"timestamp": {
"url": "https://<Base-URL>/v1/timestamps/b65b3628-232c-424a-9277-f3b84b568e82",
"id": "b65b3628-232c-424a-9277-f3b84b568e82"
},
"size": 35406,
"mimetype": "image/jpeg",
"url": "https://<Base-URL>/v1/media/be660c8f-3fc4-49aa-8051-ac042f07d6c7",
"sessionId": "7c66bb47-b071-451f-a55b-66a8d125470f",
"inflowFeedback": {
"combined": {
"result": true
},
"reasons": []
}
}
}
Inflow feedback rejected Happens when some issues were found with the image
Code
: 200 OK
{
"status": "success",
"image": {
"id": "be660c8f-3fc4-49aa-8051-ac042f07d6c7",
"name": "document-back",
"context": "document-back",
"timestamp": {
"url": "https://<Base-URL>/v1/timestamps/b65b3628-232c-424a-9277-f3b84b568e82",
"id": "b65b3628-232c-424a-9277-f3b84b568e82"
},
"size": 35406,
"mimetype": "image/jpeg",
"url": "https://<Base-URL>/v1/media/be660c8f-3fc4-49aa-8051-ac042f07d6c7",
"sessionId": "7c66bb47-b071-451f-a55b-66a8d125470f",
"inflowFeedback": {
"combined": {
"result": false
},
"reasons": [
{
"name": "document_data_readable",
"result": false
},
{
"name": "document_found",
"result": false
},
{
"name": "document_valid_position",
"result": false
}
]
}
}
}
Inflow feedback timeout Happens when we’re not able to give feedback in time
Code
: 200 OK
{
"status": "success",
"image": {
"id": "be660c8f-3fc4-49aa-8051-ac042f07d6c7",
"name": "document-back",
"context": "document-back",
"timestamp": {
"url": "https://<Base-URL>/v1/timestamps/b65b3628-232c-424a-9277-f3b84b568e82",
"id": "b65b3628-232c-424a-9277-f3b84b568e82"
},
"size": 35406,
"mimetype": "image/jpeg",
"url": "https://<Base-URL>/v1/media/be660c8f-3fc4-49aa-8051-ac042f07d6c7",
"sessionId": "7c66bb47-b071-451f-a55b-66a8d125470f",
"inflowFeedback": null
}
}
List of feedbacks
Priority | Suggested user guidance | Reason identifier | Image type |
---|---|---|---|
1 | Photo is too dark. Please take a brighter photo to continue. | image_not_too_dark | Any |
2 | No ID card/driver's license/residence permit/passport detected. Please check if your card/driver's license/residence permit/passport is valid and in the photo | document_found | Document |
3 | ID card/driver's license/residence permit/passport is too small. Try bringing your ID card closer to the camera. | document_valid_size | Document |
4 | Make sure your ID card/driver's license/residence permit/passport photo page fits fully in the frame. | document_valid_position | Document |
5 | Please use a valid and supported identification document. These include ID cards, passports, residence permits, or driver's licenses. | document_valid_type | Document |
6 | Monochrome photo. Please take a color photo of your original ID card/driver's license/residence permit/passport to continue. | document_photocopy_not_monochrome | Document |
7 | Take a photo of the front of your ID card/driver's license/residence permit. | document_front_shown | Document front |
8 | Take a photo of the back of your ID card/driver's license/residence permit. | document_back_shown | Document back |
9 | Camera glare detected. Try moving away from direct light. | document_data_glare | Document |
10 | Document data is not readable. Please take a sharper photo to continue. / Make sure there is no finger covering the data. | document_data_readable | Document |
11 | Make sure your face and ID card/driver's license/residence permit/passport photo page are fully in the frame when taking a photo. | document_face_shown | Face + Document |
12 | Make sure that your face is in the frame and clearly visible | face_found | Face |
Patch the session
Patching session to inflow_completed
signals Veriff to leave the session alone. Check /sessions/{sessionId}
endpoint in the API reference here for more details.
Method
PATCH
URI Parameters
sessionId: string (required)
- Session uuid
Headers
Content-Type: application/json
X-AUTH-CLIENT: string (required)
- API Public Key
X-HMAC-SIGNATURE: string (required)
- Request body signed with API Private Key
Request Properties
verification
:object
(required)status
:string
(required) Status of a verification (submitted)timestamp
:string
(required) Combined ISO 8601 date and time in UTC YYYY-MM-DDTHH:MM:S+Timezone Offset|Z, i.e., 2018-04-18T11:02:05.261Z)
Example request body
{
"verification": {
"status": "inflow_completed",
"timestamp": "2019-09-03T08:36:25.597Z"
}
}
RESPONSE
Code
: 200 OK
{
"status": "success",
"verification": {
"id": "4bb7b3b1-986c-4134-af72-8683c532cfe2",
"url": "https://alchemy.veriff.com/v1/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiNGJiN2IzYjEtOTg2Yy00MTM0LWFmNzItODY4M2M1MzJjZmUyIiwiaWF0IjoxNTcxNjU5ODgwfQ.0Z7ZmPM9sNOljt2IfOGisCJGqw4u5AywcpXASmunyo8",
"vendorData": "11111111",
"host": "https://alchemy.veriff.com",
"status": "completed",
"sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiNGJiN2IzYjEtOTg2Yy00MTM0LWFmNzItODY4M2M1MzJjZmUyIiwiaWF0IjoxNTcxNjU5ODgwfQ.0Z7ZmPM9sNOljt2IfOGisCJGqw4u5AywcpXASmunyo8"
}
}
Biometric authentication
Prerequisites
- 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 user to the biometric authentication product,
it is required that the user has an approved IDV session from the IDV integration, where the
vendorData
field is populated with a uuid, unique to each user that has been verified.
Process overview
Verify the user’s identity
Using your configured IDV integration, verify the user’s identity. (Integrations reference)
vendorData
field must be set to the unique 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 user
This is applicable once the 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 user identifier used in the IDV session - 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.
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. It could also have been that due to a bad image quality the person could not been matched. If you decide to give the client another try you need to create a new session. |
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. |
Handling the decision reasons
verification.status | verification.reasonCode | verification.reason |
---|---|---|
declined | 105 | Suspicious behaviour |
declined | 120 | Person on the portrait does not appear to match reference photo |
expired | null | null |
abandoned |
Authentication Service Flow Diagram
Face Match (Deprecated)
Prerequisites
- 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!)
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.
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. |
Handling the decision 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.
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 customer
When your server receives a payload from Veriff, you need to be able to reference a customer.
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 customer ID
To use your own customer ID you need to provide your internal customer ID to Veriff, or some other key that uniquely identifies your customer.
You can store your identifier in the vendorData
property during the session creation.
Please bear in mind that it is technically possible for one customer to be associated with multiple verification sessions,
and this could potentially create ambiguous situations in code, if you are only recognizing customers 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 different 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 Response and error codes
Explanation of the meaning of the response codes: Meaning of the various event codes
- 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.
- 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.
- 9103 : Resubmitted: Resubmission has been requested. The verification process is not completed. Something was missing from the client and she or he needs to go through the flow once more. The same sessionURL can and should be used for this purpose.
- 9104 : Negative: Verification has been expired. The verification process is complete. After 7 days the session get's expired. If the client started the verification process we reply "abandoned" here, otherwise if the client never arrived in our environment the status will be "expired"
- 9121 : Review: Review status is issued whenever automation engine could not issue a conclusive decision and the verification session needs to be reviewed by a human. This status will be sent depending on service agreement.
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 user has provided us with:
- photos and videos uploaded to us
- the data on the document is readable and matches throughout the document
- the user's portrait photo is recognizable
- the 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 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
*In case of verifications which have received a "Resubmission requested" decision from Veriff, we highly recommend notifying the user about the reason why the verification did verification fail and tips for what could be done better on the next attempt. This can be done either via e-mail, SMS and/or in your platform for better visibility. In case of resubmitted verification attempts where something was missing or the quality of the submission was poor, a next attempt is created ready to be used and accessible via the same session URL. The same session URL should be used for verification attempts by the same user.
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
- A user is unable to pass verification as required, but their attempt is sincere and the document is legitimate
- A user has made multiple fraudulent attempts to verify and cannot pass Veriff's verification any more
- You wish to restrict the user's access to your platform based on their earlier behavior Veriff provides a more standardized solution where unconventional 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 customer's verification is often a requirement. While Veriff stores and holds the customer'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 mediaIds, 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 vendor once the verification has been processed.
In most cases we send decision webhook instantly after decision is made with an exception of "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't 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",
"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"
},
"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"
}
},
"riskLabels": [
{
"label": "document_integration_level_crosslinked_with_fraud",
"category": "document"
},
{
"label": "document_integration_level_crosslinked_with_multiple_declines",
"category": "document"
}]
},
"technicalData": {
"ip": "186.153.67.122"
}
}
Properties explained:
status
:String
(required) Status of the responseverification
:object
Verification request decision object. Null if decision is not available yetid
:String
UUID v4 which identifies the verification sessionstatus
:approved
(one of approved, resubmission_requested, declined, review, expired, abandoned) Verification statuscode
:9001
(one of 9001, 9103, 9102, 9121, 9104) Verification response code. See Response and error codesreason
:String
Reason of failed Verificationperson
:object
Verified personfirstName
:String
First namelastName
:String
Last nameidNumber
:String
National Identification numbercitizenship
:(Deprecated)
ISO-2
String CitizenshipdateOfBirth
:String
(YYYY-MM-DD) Date of birthnationality
:String
NationalitypepSanctionMatch
:String
PEP check result. It is optional, depending on integration.gender
:String
(M, F or Null) GenderyearOfBirth
:String
(YYYY) Year of birthplaceOfBirth
:String
Place of birth
document
:object
Verified documentnumber
:String
Document numbertype
:String
(one of PASSPORT, ID_CARD, DRIVERS_LICENSE, RESIDENCE_PERMIT, OTHER) Document typecountry
:ISO-2
String Document countryvalidFrom
:String
Document is valid from date in YYYY-MM-DD formatvalidUntil
:String
Document is valid until date in YYYY-MM-DD format
comments
:object
(Deprecated)
Array of additional comments by verification specialisttype
:String
The type of the commentcomment
:String
The comment itselftimestamp
:String
UTC timestamp
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
:Category is valid from date in YYYY-MM-DD format | null
driversLicenseCategoryUntil
:object
Driving license category expiry date. Optional, depending on integration.B
:Category is valid until date in YYYY-MM-DD format | null
vendorData
:string
Additional vendor specific data. 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).reasonCode
:102
Suspected document tampering. See Response and error codesdecisionTime
:string
Timestamp of the decisionacceptanceTime
:string
Timestamp of the session generationriskLabels
:array
Optional array of risk labels related to the session. The presence of this property depends on risk labels being enabled for the integration.label
:String
name of the risk labelcategory
:String
(one of client_data_mismatch, crosslinks, device, document, images, network, session, person)
technicalData
:object
Technical data objectip
:String
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 user.
- Proof of address events: if feature is enabled, tracks events for proof of address data gathering performed by 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:
- user arrives to Veriff environment and starts the verification process
- 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
Vendor specific data string, max 400 characters long, set during session creation. 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).
Proof of address events
To track the progress of proof of address data gathering, Veriff allows to subscribe to the following events:
- when user arrives to Veriff environment and starts the proof of address process
- when 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
Vendor specific data string, max 400 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": [
{
"source_name": "United Kingdom Insolvency Service Disqualified Directors",
"source_url": "https://www.insolvencydirect.bis.gov.uk/IESdatabase/viewdirectorsummary-new.asp"
}
],
"pep": [
{
"source_name": "United States Navy Leadership and Senior Military Officials",
"source_url": "https://www.navy.mil/Leadership/Biographies/"
}
],
"adverseMedia": [
{
"date": "2020-09-23T00:00:00Z",
"source_name": "SNA's Old Salt Award Passed to Adm. Davidson",
"source_url": "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 (e.g. UUID-s, etc that can not be resolved or used outside of the vendor environment).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 foundsource_name
:String
Name of the listingsource_url
: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 foundsource_name
:String
Name of the listingsource_url
: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 foundsource_name
:String
Name of the listingsource_url
: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 foundsource_name
:String
Name of the listingsource_url
: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 foundsource_name
:String
Name of the listingsource_url
: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 vendor specific data. 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).
Testing
For testing purposes we provide an example payload so you do not depend on Veriff sending the response. You can use this Curl command. Beware, 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:6d5041590ae0fb2795cc198bf37daaa7aea80f870b0d169710497f3b4e46f93e' \
--header 'content-type:application/json' \
--data '{"status":"success","verification":{"id":"12df6045-3846-3e45-946a-14fa6136d78b","code":9001,"person":{"gender":null,"idNumber":null,"lastName":"MORGAN","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"},"reasonCode":null,"vendorData":"12345678","decisionTime":"2019-11-06T07:18:36.916Z","acceptanceTime":"2019-11-06T07:15:27.000Z","additionalVerifiedData":{},"riskLabels":[{"label":"document_integration_level_crosslinked_with_fraud","category":"document"},{"label":"document_integration_level_crosslinked_with_multiple_declines","category":"document"}]},"technicalData":{"ip":"186.153.67.122"}}'
Response and error codes
Note: If you do not see the reason code you received here, see also granular reason codes
Common response codes | |
---|---|
Code | Description |
200 | `{ "status": "success", "data" }` |
201 | `{ "status": "success", "data" }` |
400 | `{ "status": "fail", "code:": "1102", "message": "Mandatory parameters are missing from the request." }` |
401 | `{ "status": "fail", "message": "Not Authorized." }` |
404 | `{ "status": "fail", "message": "Entry not found." }` |
500 | `{ "status": "fail", "message": "Something went wrong." }` |
Credentials & Authorization | |
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 | Vendor data cannot be more than 400 symbols. 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. |
1501 | Vendor data must be a string. We require only non-semantic data to be submitted (UUID-s etc that can not be resolved or used outside of the vendor environment). |
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. |
Reason and Decision codes | |
Decline | verification.reasonCode |
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 user. |
109 | Velocity/abuse duplicated device. |
110 | Velocity/abuse duplicated ID. |
112 | Restricted IP location |
Resubmit | verification.reasonCode |
Code | Description |
201 | Video and/or photos missing. |
204 | Poor image quality. |
205 | Document damaged. |
206 | Document type not supported. |
207 | Document expired. |
Decision | verification.code |
Code | Description |
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. |
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. |
9103 | Resubmitted: Resubmission has been requested. The verification process is not completed. Something was missing from the client and she or he needs to go through the flow once more. The same sessionURL can and should be used for this purpose. |
9104 | Negative: Verification has been expired. The verification process is complete. After 7 days the session gets expired. If the client started the verification process we reply "abandoned" here, otherwise if the client never arrived in our environment the status will be "expired" |
9121 | Review: Review status is issued whenever automation engine could not issue a conclusive decision and the verification session needs to be reviewed by a human. This status will be sent depending on service agreement. |
Granular reason codes
The reason codes mentioned here are subject to custom configuration in integration level, so please keep in mind that, you may or may not receive all the reason codes listed here .
Special Reason codes | |
---|---|
Decline | verification.reasonCode |
Code | Description |
106 | Known fraud |
108 | Velocity/abuse duplicated user |
109 | Velocity/abuse duplicated device |
110 | Velocity/abuse duplicated ID |
112 | Restricted IP location |
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 |
Resubmit | verification.reasonCode |
Code | Description |
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 |