performNetverify

This is a reference manual and configuration guide for the ID Verification API product. It illustrates how to implement the ID Verification API.

Using performNetverify

performNetverify offers a Restful ID verification API without Jumio-hosted user interface. Simply send an HTTP POST including the customer's ID image to the URL below. You will immediately receive a JSON response with a Jumio scan reference and a timestamp. A callback will be sent after the verification is complete (see Callback).

warning

Passports (MRZ) have the highest success rate among ID types. It is recommended for best conversion rates and better data extraction to suggest that your users upload passports when using this submission channel.

HTTP Request Method:POSTREST

• URL (US): https://netverify.com/api/netverify/v2/performNetverifyREST
• URL (EU): https://lon.netverify.com/api/netverify/v2/performNetverifyREST
• URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/performNetverify

Authentication and Encryption

ID Verification 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.

warning

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/jsonContent-Length: see [RFC-7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.3.2)
Authorization: (see [RFC 7617](https://datatracker.ietf.org/doc/html/rfc7617)) User-Agent: YourCompany YourApp/v1.0

info

• Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.
• Calls with missing or suspicious headers, suspicious parameter values, or without HTTP Basic Authentication will result in HTTP status code 403 Forbidden.

Request body

info

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

Required fields appear in bold type.

Parameter	Type	Max. Length	Description
merchantIdScanReference	String	100	Your reference for each scan. Must not contain sensitive data such as PII (Personally Identifiable Information) or account login information.
frontsideImage	String	Max. 15MB, < 8000 pixels per side, longest side > 300 pixels	Base64 encoded image of the front side of the ID.
faceImage *	String	Max. 15MB, < 8000 pixels per side, longest side > 300 pixels	Base64 encoded image of the face. Mandatory if Face Match is enabled.
country	String	3	Possible values: ISO 3166-1 alpha-3 country code country code, XKX (Kosovo).
idType	String	255	PASSPORT, DRIVING_LICENSE, ID_CARD, VISA.
frontsideImageMimeType	String		MIME type of the front side image. Possible values: image/jpeg (default), image/png.
faceImageMimeType	String		MIME type of the face image. Possible values: image/jpeg (default), image/png.
backsideImage	String	Max. 15MB, < 8000 pixels per side, longest side > 300 pixels	Base64 encoded image of the back side of the ID.
backsideImageMimeType	String		MIME type of the back side image. Possible values: image/jpeg (default), image/png.
enabledFields	String	100	Defines which fields will be extracted during ID verification. Fields not listed here will not be processed for this transaction, regardless of Customer Portal settings. Face Match and Address extraction will not be processed unless enabled for your account. To enable them, contact your Customer Success Manager or Jumio Support. See supported documents for address extraction. Possible values: "idNumber,idFirstName,idLastName,idDob,idExpiry,idUsState,idPersonalNumber,idFaceMatch,idAddress".
merchantReportingCriteria	String	100	Your reporting criteria for each scan.
customerId *	String	100	Identification of the customer. Must not contain sensitive data such as PII or account login information. Mandatory if using Jumio Screening.
callbackUrl	String	255	Callback URL for confirmation after verification is completed (see Callback URL for constraints).
firstName	String	100	First name of the customer.
lastName	String	100	Last name of the customer.
usState	String	100	If idType = PASSPORT or ID_CARD: Last two characters of ISO 3166-2 US state code, ISO 3166-1 country name, Kosovo, ISO 3166-1 alpha-2 country code, XK (Kosovo), ISO 3166-1 alpha-3 country code, XKX (Kosovo). If idType = DRIVING_LICENSE: Last two characters of ISO 3166-2 US state code.
expiry	String		Expiry date in the format YYYY-MM-DD.
number	String	100	Identification number of the document.
dob	String		Date of birth in the format YYYY-MM-DD.
callbackGranularity	String	255	Possible values: onFinish (default) – Callback sent after entire verification; onAllSteps – Additional callback sent when images are received.
personalNumber	String	14	Personal number of the document.
userConsent *	Object		User consent required where a product uses facial recognition technology or processes biometric data. See userConsent. Mandatory for End-User Consent even if the user is not based in the USA.

Request userConsent

Parameter	Type	Max. Length	Description
userIp*	String	—	Current IP address of the end-user used during the verification.Mandatory for End-User Consent, even if the user is not based in the USA.
userLocation*	Object	—	Contains:• userLocation.country• userLocation.stateMandatory for End-User Consent, even if the user is not based in the USA.
userLocation.country*	String	3	Current country based on end-user location during verification.Possible values:• ISO 3166-1 alpha-3 country codeMandatory for End-User Consent, even if the user is not based in the USA.
userLocation.state	String	100	Current state based on end-user location during verification.Applicable only in countries where state exists, including the USA.Possible values:• For USA, CAN, AUS → alpha-2 state code only (without country & hyphen), e.g., IL (Illinois), NSW (New South Wales)• For other countries → any string (if applicable)
consent*	Object	—	Contains:• consent.obtained• consent.obtainedAtMandatory for End-User Consent, and required if userLocation.country = USA and consent.obtained = yes.
consent.obtained*	String	—	Indicates whether end-user consent was obtained.Possible values:• yes – Consent was given• no – Consent was not given• na – Not applicableMandatory for End-User Consent, and required if country = USA.
consent.obtainedAt*	String	—	Timestamp when consent was obtained (UTC).Format: YYYY-MM-DDThh:mm:ss.SSSZMandatory for End-User Consent, and required if consent.obtained = yes.

Supported documents for address extraction

Country	ID Card	Driving License	Passport	Callback Format
Australia	No	Yes	No	RAW
Bahrain	No	Yes	No	RAW
Canada	No	Yes	No	RAW
France	Yes	Yes	Yes	RAW
Germany	Yes	No	No	RAW
Indonesia	Yes	No	No	RAW
Ireland	No	Yes	No	RAW
Malaysia	Yes	No	No	RAW
Malta	Yes	Yes	No	RAW
Mexico	Yes	No	No	RAW
Peru	Yes	Yes	No	RAW
Romania	Yes	No	No	RAW
Singapore	Yes	No	No	RAW
Spain	Yes	No	No	RAW
United Kingdom	No	Yes	No	RAW
United States	Yes	Yes	No	RAW

End-User Consent for Biometric Data in API

To collect consent on Jumio’s behalf, you will need to incorporate certain explicit consent collection language and a link to Jumio’s Privacy Notice within your user consent flow before collection of end-user biometric data, if the end-user is located inside the United States.

The following is an example of how consent may be presented to the end-user, but you may use your own custom language as long as the required elements are present:

“By clicking “Start” you consent to Jumio collecting, processing, and sharing your personal information, which may include biometric data, pursuant to its Privacy Notice.”

When to share consent parameters?

Every transaction which includes any product/workflow step in which biometrics are collected needs to have consent parameters adapted and populated. This means if Face match is enabled for your account you will need to share consent parameters for performNetverify.

If consent is not provided or other scenarios where consent needs to be resubmitted use our Account Update API to add the needed consent parameters.

If your Privacy Policy and Terms & Conditions allowing continuous use of consent obtained from end-user on biometric data collection and processing the timestamp (consent.obtainedAt) should be when the original/updated consent was obtained.

warning

If the continuous consent applies, the consent is valid for a period of maximum 3 years (between the consent timestamp and current timestamp). A new consent needs to be obtained from the end-user before continuous consent expires. The consent timestamp (consent.obtainedAt) has to be updated accordingly.

note

Until further notice Jumio will not perform any treatment based on the consent parameters. After a notice period business validation will be performed, which could also lead to a rejection of the transaction also providing additional consent specific error codes. We will inform you separately on a specific date.

Where to share consent parameters?

Within the consent area in the API request body.

• Always mandatory: Populate the end-user IP address and end-user current location (userConsent.userIp,userLocation.country)
• Mandatory if userLocation.country = USA: Populate the consent parameters (i.e., status, timestamp) See examples for a sample request including the user consent parameters.

Response

Parameter	Type	Max Length	Description
timestamp	String	—	Timestamp (UTC) of the response.Format: YYYY-MM-DDThh:mm:ss.SSSZ
jumioIdScanReference	String	36	Jumio's reference number for each scan.

Examples

Sample request

Including End-User Consent (USA)

POST https://netverify.com/api/netverify/v2/performNetverify HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1234
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "merchantIdScanReference": "YOURSCANREFERENCE",
  "frontsideImage": "YOURBASE64STRING",
  "country": "XKX",
  "idType": "PASSPORT",
  "customerId":"customerId",
  "userConsent": {
      "userIp": "226.80.211.232",
      "userLocation": {
          "country": "USA",
          "state": "IL"
      },
       "consent": {
        "obtained": "yes",
        "obtainedAt": "2022-07-20T17:20:35.000Z"

      }
  }
}

Including End-User Consent (AUT)

POST https://netverify.com/api/netverify/v2/performNetverify HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1234
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "merchantIdScanReference": "YOURSCANREFERENCE",
  "frontsideImage": "YOURBASE64STRING",
  "country": "XKX",
  "idType": "PASSPORT",
  "customerId":"customerId",
  "userConsent": {
      "userIp": "192.168.0.1",
      "userLocation": {
          "country": "AUT"
      }
  }
}

warning

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

Sample Response

{
  "timestamp": "2017-08-16T10:37:44.623Z",
  "jumioIdScanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Configuring settings in the Customer Portal

In the Settings screen of the Customer Portal you can customize your settings and brand your ID Verification 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 URL

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.

URL requirements

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

URL restrictions

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