Netverify Web v4 Implementation Guide

This is a reference manual and configuration guide for the new Netverify Web client. It describes how to initiate a transaction, how to customize your settings and branding, and how to display Netverify to your users.

Revision history

Information about changes to features and improvements documented in each release is available in our Revision history.

Initiating a Netverify transaction

Call the RESTful API POST endpoint /initiate with a JSON object containing the properties described below to create a transaction for each user. You will receive a JSON object in the response containing a timestamp, Jumio transaction reference (scan reference), and a URL which you can use to present Netverify to your user.

HTTP Request Method: POST
REST URL (US): https://netverify.com/api/v4/initiate
REST URL (EU): https://lon.netverify.com/api/v4/initiate

Authentication and encryption

Netverify API calls are protected using HTTP Basic Authentication. Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under Settings > API credentials.

⚠️ Never share your API token, API secret, or Basic Auth credentials with anyone — not even Jumio Support.

The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see Supported cipher suites.

Request headers

The following fields are required in the header section of your request:

Accept: application/json
Content-Type: application/json
Content-Length: (see RFC-7230)
Authorization: (see RFC 7617)
User-Agent: YourCompany YourApp/v1.0

ℹ️ Jumio requires the `User-Agent` value to reflect your business or entity name for API troubleshooting.

Request body

The body of your initiate API request allows you to

provide your own internal tracking information for the user and transaction.
specify what user information is captured and by which method.
indicate where the user should be directed after the user journey.
select the language to be displayed.
preset options to enhance the user journey.

ℹ️ Values set in your API request will override the corresponding settings configured in the Customer Portal.

Required items appear in bold type.

Name	Type	Max. length	Description
customerInternalReference¹	string	100	Your internal reference for the transaction.
userReference¹	string	100	Your internal reference for the user.
reportingCriteria	string	100	Your reporting criteria for the transaction.
successUrl²	string	2047	Redirects to this URL after a successful transaction. Overrides Success URL in the Customer Portal.
errorUrl²	string	255	Redirects to this URL after an unsuccessful transaction. Overrides Error URL in the Customer Portal.
callbackUrl²	string	255	Sends verification result to this URL upon completion. Overrides Callback URL in the Customer Portal.
workflowId	integer	3	Applies this acquisition workflow to the transaction. Overrides Capture method in the Customer Portal. See supported workflowId values.
presets¹	JSON	-	Preset options to enhance the user journey. See supported preset values.
locale	string	5	Renders content in the specified language. Overrides Default locale in the Customer Portal. See supported locale values.
tokenLifetimeInMinutes	number	Max. value: 86400	Time in minutes until the authorization token expires. (minimum: 5, maximum: 86400) Overrides Authorization token lifetime in the Customer Portal.

¹ Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.
² See URL constraints for Callback, Error, and Success URLs.

Supported `workflowId` values

Acquisition workflows allow you to set a combination of verification and capture method options.

⚠️ Identity Verification must be enabled for your account to use an ID + Identity `workflowId`.

Value	Verification type	Capture method
100	ID only	camera + upload
101	ID only	camera only
102	ID only	upload only
200	ID + Identity	camera + upload
201	ID + Identity	camera only
202	ID + Identity	upload only

Supported `presets` values

It is possible to specify presets for ID Verification, for Identity Verification, for both together, or for neither. For each preset you use, all values must be passed together as a JSON array (see Sample request) for the request to be valid.

ID Verification: preset country and document type

Preset the country and document type to bypass the selection screen.

Required items appear in bold type.

Name	Type	Max. length	Description
index	integer	1	must be set to `1`
country	string	3	Possible values: • ISO 3166-1 alpha-3 country code • `XKX` (Kosovo)
type	string	15	Possible values: • `PASSPORT` • `DRIVING_LICENSE` • `ID_CARD`

Identity Verification: Liveness Detection for Web

⚠️ In order to use this preset, Identity Verification and Liveness Detection for Web must be enabled for your account. Jumio Support will ask you to provide a default custom phrase to be submitted by your users on a handwritten note during the Identity Verification process. After the default custom phrase has been configured for your account, this preset can be used to change the phrase for any transaction.

Required items appear in bold type.

Name	Type	Max. length	Description
index	integer	1	must be set to `2`
phrase¹	string	30	Possible values: • alpha-numeric Latin characters (upper or lower case) and spaces

¹ Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.

Supported `locale` values

Hyphenated combination of ISO 639-1:2002 alpha-2 language code plus ISO 3166-1 alpha-2 country (where applicable).

Value	Locale
bg	Bulgarian
cs	Czech
da	Danish
de	German
el	Greek
en	American English (default)
en-GB	British English
es	Spanish
es-MX	Mexican Spanish
et	Estonian
fi	Finnish
fr	French
hu	Hungarian
it	Italian
ja	Japanese
ko	Korean
lt	Lithuanian
nl	Dutch
no	Norwegian
pl	Polish
pt	Portuguese
pt-BR	Brazilian Portuguese
ro	Romanian
ru	Russian
sk	Slovak
sv	Swedish
tr	Turkish
vi	Vietnamese
zh-CN	Simplified Chinese
zh-HK	Traditional Chinese

Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

Required items appear in bold type.

Name	Type	Max. length	Description
timestamp	String	24	Timestamp (UTC) of the response. Format: YYYY-MM-DDThh:mm:ss.SSSZ
redirectUrl	String	255	URL used to load the Netverify client.
transactionReference	String	36	Jumio reference number for the transaction.

Examples

Sample request

POST https://netverify.com/api/v4/initiate/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1234
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
  "customerInternalReference" : "transaction_1234",
  "userReference" : "user_1234",
  "successUrl" : "https://www.yourcompany.com/success",
  "errorUrl" : "https://www.yourcompany.com/error",
  "callbackUrl" : "https://www.yourcompany.com/callback",
  "reportingCriteria" : "myReport1234",
  "workflowId" : 200,
  "presets" :
    [
      {
        "index"   : 1,
        "country" : "AUT",
        "type"    : "PASSPORT"
      },{      
        "index"   : 2,
        "phrase" : "MY CUSTOM PHRASE"     
      }
    ],
  "locale" : "en-GB"
}

⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

Sample response

{
  "timestamp": "2018-07-03T08:23:12.494Z",
  "transactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "redirectUrl": "https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx"
}

Configuring settings in the Customer Portal

In the Settings screen of the Customer Portal you can customize your settings and brand your Netverify page.
Save changes using your Customer Portal password to activate them.

ℹ️ Values set in your API request will override the corresponding settings configured in the Customer Portal.

Application settings — General

Callback, Error, and Success URLs

Define a Callback URL to receive verification results and extracted user data from Jumio when a transaction is completed. For more information, see our Callback documentation.

Define a Success URL to direct the user after images are accepted for processing. If no Success URL is specified in the Customer Portal or the initiate API request, the Jumio default success page will be displayed, including any custom images you have specified.

Define an Error URL to direct the user when the verification process ends with an error or a failure after 3 submission attempts. If no Error URL is specified in the Customer Portal or the initiate API request, the Jumio default error page will be displayed, including any custom images you have specified.

URL requirements:

HTTPS using the TLS Protocol (most recent version recommended)
Valid URL using ASCII characters or IDNA Punycode

URL restrictions:

IP addresses, ports, certain query parameters and fragment identifiers are not allowed.
Personally identifiable information (PII) is not allowed in any form.

Jumio appends the following parameters to your Success or Error URL to redirect your user at the conclusion of the user journey. These cannot be used as part of your Success or Error URL:

Name	Description
transactionStatus	• `SUCCESS` for successful submissions. • `ERROR`for errors and failure after 3 attempts.
customerInternalReference	Your internal reference for the transaction.
transactionReference	Jumio reference number for the transaction.
errorCode	Displayed when `transactionStatus` is `ERROR`.

Capture method

Specify how your user can submit their ID or Identity image for verification.

Choose from:

Webcam and image upload
Webcam only
Image upload only

⚠️ Selecting "Webcam only" means some mobile browsers will not be supported.

Skip "Start ID verification" screen

Select this checkbox to bypass the introductory screen in the Netverify Web client.

Authorization token lifetime

Specify the duration of time for which your redirectUrl will remain valid. Enter the value in minutes (minimum 5, maximum 86400). The default value is 30 minutes.

Application settings — Redirect

Domain name prefix

You can optionally define a domain name prefix (https://yourcompany.netverify.com) for the URL of your Netverify page.

Allowed characters are letters a-z, numbers 0-9, -
Must not start or end with -
Max. 63 characters

Default locale

Select a language from the dropdown list to set your display language for Netverify. If no language is selected, Netverify will be displayed in English (US).

Choose from:

English
English (United Kingdom)
German
Turkish
Finnish
Norwegian
Polish
Swedish
Russian
Portuguese
Portuguese (Brazil)
Spanish
Spanish (Mexico)
Italian
French
Dutch
Bulgarian
Chinese (China)
Chinese (Hong Kong)
Czech
Danish
Greek
Hungarian
Japanese
Korean
Romanian
Slovak
Vietnamese
Lithuanian
Estonian

Customize client

Colors

Specify primary and secondary colors for each locale to give Netverify your own look and feel.

Any locale which is not configured will first default to the root language (e.g. EN_GB to EN), then to your default configuration, and finally to the Jumio default.

You can also reset all colors to the Jumio default.

Images

Add a Header image for each locale to brand your Netverify page.

Add a Success image and Error image for each locale to be displayed on the Jumio default success and error pages when you do not specify your own Success URL and Error URL.

Any locale which is not configured will first default to the root language (e.g. EN_GB to EN), then to your default configuration, and finally to the Jumio default.

All images must be formatted as JPG or PNG and must not exceed 5 MB.

Displaying Netverify

The redirectUrl returned in the response to your initate API call, which loads your customized Netverify page, can be used in several ways:

within an iFrame on your web page
as a link on your web page
as a link shared securely with a user

Using Netverify in an iFrame

If you want to embed Netverify on a web page, place the iFrame tag in your HTML code where you want the client to appear. Use the redirectUrl as value of the src attribute.

⚠️ The `allow="camera"` attribute must be included to enable the camera for image capture in supported browsers.

Width and height

We recommend adhering to the responsive breaking points in the table below. The Netverify Web client will responsively fill the dimensions of your iFrame.

Size class	Width	Height
Large	≥ 900 px	≥ 710 px
Medium	640 px	660 px
Small	560 px	600 px
X-Small	≤ 480 px	≤ 535 px

Example HTML

<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="930" height="750" allow="camera"></iframe>

Optional iFrame logging

When the Netverify client is embedded in an iFrame¹, it will communicate with the containing page using the JavaScript window.postMessage() method to send events containing pre-defined data. This allows the containing page to react to events as they occur (e.g., by directing to a new page once the success event is received). Events include data that allows the containing page to identify which Netverify transaction triggered the event. Events are generated in a stateless way, so that each event contains general contextual information about the transaction (e.g., transaction reference, authorization token, etc.) in addition to data about the specific event that occurred.

Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the message event on the global window object and reacting to it as needed. The data passed by the Netverify Web client in this notification is represented as JSON in the data string property of the listener method's event argument. Parsing this JSON string results in an object with the properties described below.

All data is encoded with UTF-8.

¹ This functionality is not available for instances of Netverify running in a standalone window or tab.

`event.data` object

Required items appear in bold type.

Property	Type	Description
authorizationToken	string	Authorization token, valid for a specified duration.
transactionReference	string	Jumio reference number for the transaction.
customerInternalReference	string	Your internal reference for the transaction.
eventType	integer	Type of event that has occurred. Possible values: • `510` (application state-change)
dateTime	string	UTC timestamp of the event in the browser. Format: YYYY-MM-DDThh:mm:ss.SSSZ
payload	JSON object	Information specific to the event generated. (see `event.data.payload` object)

`event.data.payload` object

Required items appear in bold type.

Name	Type	Description
value	string	Possible values: • `loaded` (Netverify loaded in the user's browser.) • `success` (Images were accepted for verification.) • `error` (Verification could not be completed due to an error.)
metainfo	JSON object	Additional meta-information for error events. (see `metainfo` object)

`event.data.payload.metainfo` object

Required items appear in bold type.

Property	Type	Description
code	integer	see errorCode values
Note: The property is currently called `codeExternal` but will be updated within the next release (begin of January)

Example iFrame logging code

function receiveMessage(event) {
	var data = window.JSON.parse(event.data);
	console.log('Netverify Web was loaded in an iframe.');
	console.log('auth token:', data.authorizationToken);
	console.log('transaction reference:', data.transactionReference);
	console.log('customer internal reference:', data.customerInternalReference);
	console.log('event type:', data.eventType);
	console.log('date-time:', data.dateTime);
	console.log('event value:', data.payload.value);
	console.log('event metainfo:', data.payload.metainfo);
}
window.addEventListener("message", receiveMessage, false);

After the user journey

At the end of the user journey, the user is directed to your Success URL if the images they submitted were accepted for processing. If no Success URL has been defined, the Jumio default success page will be displayed, including any custom success image you have specified in the Customer Portal.

If acceptable images are not provided after three attempts (see Reject reasons), the user is directed to your Error URL. If no Error URL has been defined, the Jumio default error page will be displayed, including any custom error image you have specified in the Customer Portal.

To display relevant information on your success or error page, you can use the following parameters which we append when redirecting to your successUrl or errorUrl as HTTP GET query string parameters¹. It is also possible to set successUrl and errorUrl to the same address, by using the query parameter transactionStatus.

Required items appear in bold type.

Name	Description
transactionStatus	Possible values: • `SUCCESS` for successful submissions. • `ERROR`for errors and failure after 3 attempts.
customerInternalReference	Your internal reference for the transaction.
transactionReference	Jumio reference number for the transaction.
errorCode	Displayed when `transactionStatus` is `ERROR`. Possible values: • `9100` (Error occurred on our server.) • `9200` (Authorization token missing, invalid, or expired.) • `9210` (Session expired after the user journey started.) • `9300` (Error occurred transmitting image to our server.) • `9400` (Error occurred during verification step.) • `9800` (User has no network connection.) • `9801` (Unexpected error occurred in the client.) • `9810` (Problem while communicating with our server.) • `9820` (File upload not enabled and camera unavailable.) • `9835` (No acceptable submission in 3 attempts.)

¹ Because HTTP GET parameters can be manipulated on the client side, they may be used for display purposes only.

Sample success redirect

https://www.yourcompany.com/success/?transactionStatus=SUCCESS&customerInternalReference=YOUR_REF&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Sample error redirect

https://www.yourcompany.com/error/?transactionStatus=ERROR&customerInternalReference=YOUR_REF&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&errorCode=9820

Supported browsers

Jumio offers guaranteed support for Netverify on the following browsers and the latest major version of each operating system.

Desktop

Browser	Major version	Operating system	Supports image upload	Supports HTML5 video stream
Google Chrome	current + 1 previous	Windows + Mac	X	X
Mozilla Firefox	current + 1 previous	Windows + Mac	X	X
Apple Safari	current	Mac	X	X
Microsoft Internet Explorer	current	Windows	X
Microsoft Edge	current	Windows	X	X

Mobile

Netverify Web v4 does not support WebViews.

Browser name	Major browser version	Operating system	Supports image upload	Supports HTML5 video stream
Google Chrome	current	Android	X	X
Apple Safari	current	iOS	X	X

Files

netverify-web-v4.md

Latest commit

History

netverify-web-v4.md

File metadata and controls

Netverify Web v4 Implementation Guide

Revision history

Table of contents

Initiating a Netverify transaction

Authentication and encryption

Request headers

Request body

Supported workflowId values

Supported presets values

ID Verification: preset country and document type

Identity Verification: Liveness Detection for Web

Supported locale values

Response

Examples

Sample request

Sample response

Configuring settings in the Customer Portal

Application settings — General

Callback, Error, and Success URLs

URL requirements:

URL restrictions:

Capture method

Skip "Start ID verification" screen

Authorization token lifetime

Application settings — Redirect

Domain name prefix

Default locale

Customize client

Colors

Images

Displaying Netverify

Using Netverify in an iFrame

Width and height

Example HTML

Optional iFrame logging

event.data object

event.data.payload object

event.data.payload.metainfo object

Example iFrame logging code

After the user journey

Sample success redirect

Sample error redirect

Supported browsers

Desktop

Mobile

Supported `workflowId` values

Supported `presets` values

Supported `locale` values

`event.data` object

`event.data.payload` object

`event.data.payload.metainfo` object