ID Verification Retrieval API Implementation Guide

This guide describes how to implement the ID Verification Retrieval API.

Usage

The Retrieval API is an alternative way to retrieve the results of a Jumio transaction for customers who choose not to implement our callback functionality, or in cases where a callback could not be received or processed.

Please contact Jumio Support at support@jumio.com to coordinate bulk requests to the Retrieval API.

Best Practice

You must use the status retrieval for all requests until the transaction is no longer in PENDING status.
If the transaction status is DONE or FAILED (not pending), retrieve details and image(s) once.
Maximum of 10 consecutive retrieval attempts after successful image acquisition (SDK/Web: User journey finshed; API: after ID Verification API call)
If a final result is not available after 10 attempts, you are allowed to perform an additional retrieval call once per day.
Request timings recommendation: 40, 60, 100, 160, 240, 340, 460, 600, 760, 940 seconds You are also allowed to set your own definition.

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. You can create a separate set of API credentials to be used specifically with the Retrieval and Delete API in the Customer Portal under Settings > API credentials > Transaction administration APIs.

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/jsonorimage/jpeg, image/png when retrieving a specific image 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.

warning

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

ID Verification retrieval

Retrieving status

Call the RESTful API GET endpoint below to retrieve the status of a ID Verification transaction by specifying the Jumio transaction reference (scan reference) of an existing transaction from your account as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>

info

Jumio Netverify customers are now subject to default rate limits of 45 per second and 2700 per minute for retrieval requests.

Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available or has been deleted.

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		Timestamp of the response in the format `YYYY-MM-DDThh:mm:ss.SSSZ`
scanReference	string	36	Jumio’s reference number for the transaction
status	string		Possible states: PENDING, DONE, FAILED

Examples

Sample request

GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

warning

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

Sample response

{
    "timestamp": "2019-01-01T16:23:55.039Z",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "DONE"
}

Retrieving details

Call the RESTful API GET endpoint below to retrieve document, transaction, and verification details by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/dataREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/dataREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data

Response

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		Timestamp of the response in the format `YYYY-MM-DDThh:mm:ss.SSSZ`
scanReference	string	36	Jumio’s reference number for the transaction
document	object		As listed in the section Retrieving document data (without timestamp and scanReference)
transaction	object		As listed in the section Retrieving transaction data (without timestamp and scanReference)
verification	object		As listed in the section Retrieving verification data (without timestamp and scanReference)
facemap	object		facemap (if download of facemap is enabled), see table below

Parameter facemap

Required items appear in bold type.

Name	Type	Max. Length	Description
classifier	string	5	Possible value: facemap
href	string	5	REST URL used to retrieve the facemap content

Retrieving facemap Call the RESTful API GET endpoint to retrieve a raw facemap which will be returned in a binary format.

Use HTTP GET with Basic Authorization using your API token and secret, as userid and password. Header: The following parameters are mandatory in the header section of your request.

User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/VERSION The value for User-Agent must contain a reference to your business or entity for Jumio to be able to identify your requests. (e.g. YourCompanyName YourAppName/1.0.0). Without a proper User-Agent header, Jumio will take longer to diagnose API issues. The TLS protocol is required during the TLS handshake (see [Supported cipher suites]) and we strongly recommend using the latest version.

Response

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

Examples

Sample request

GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

warning

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

Sample response

{
    "timestamp": "2019-03-20T16:25:38.663Z",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "document": {
        "type": "DRIVING_LICENSE",
        "dob": "1990-01-01",
        "expiry": "2022-12-31",
        "firstName": "FIRST NAME",
        "issuingCountry": "AUT",
        "issuingDate": "2013-01-01",
        "lastName": "LAST NAME",
        "number": "123456789",
        "status": "APPROVED_VERIFIED"
    },
    "transaction": {
        "clientIp": "XX.XX.X.XX",
        "customerId": "CUSTOMERID",
        "date": "2019-01-01T11:01:10.227Z",
        "merchantReportingCriteria": "YOURREPORTINGCRITERIA",
        "merchantScanReference": "YOURSCANREFERENCE",
        "source": "WEB_UPLOAD",
        "status": "DONE"
    },
    "verification": {
        "identityVerification": {
            "similarity": "MATCH",
            "validity": "true"
        },
        "mrzCheck": "NOT_AVAILABLE"
    },
        "facemap": {
        "classifier": "facemap",
        "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/facemap"
    }
}

Retrieving document data only

Call the RESTful API GET endpoint below to retrieve document data by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/documentREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/documentREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/document

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for the transaction
status	string		ID Verification: APPROVED_VERIFIED, DENIED_FRAUD, DENIED_UNSUPPORTED_ID_TYPE, DENIED_UNSUPPORTED_ID_COUNTRY, ERROR_NOT_READABLE_ID, NO_ID_UPLOADED
type	string		ID Verification: PASSPORT, DRIVING_LICENSE, ID_CARD, VISA, UNSUPPORTED
idSubtype	string	255	Possible subtypes if type = ID_CARD: NATIONAL_ID, CONSULAR_ID, ELECTORAL_ID, RESIDENT_PERMIT_ID, TAX_ID, STUDENT_ID, PASSPORT_CARD_ID, MILITARY_ID, PUBLIC_SAFETY_ID, HEALTH_ID, OTHER_ID, VISA, UNKNOWN. Possible subtypes if idType = DRIVING_LICENSE: REGULAR_DRIVING_LICENSE, LEARNING_DRIVING_LICENSE. Possible subtypes if idType = PASSPORT: E_PASSPORT (only for mobile)
issuingCountry	string	3	Possible countries: ISO 3166-1 alpha-3 country code - XKX (Kosovo)
firstName	string	255	Customer's first name
lastName	string	255	Customer's last name
middleName	string	255	Customer's middle name. For document types that have a separate, dedicated middle name.
dob	string		Date of birth in the format YYYY-MM-DD
expiry	string		Date of expiry in the format YYYY-MM-DD
issuingDate	string	10	Issue date in the format YYYY-MM-DD (if issuing date extraction is enabled)
number	string	255	Identification number of the document
usState	string	255	Possible values: Last two characters of ISO 3166-2:US state code; Last 2-3 characters of ISO 3166-2:AU state code; Last two characters of ISO 3166-2:CA state code; ISO 3166-1 country name; XKX (Kosovo); Free text - if it can't be mapped to a state/country code
personalNumber	string	255	Personal number of the document
optionalData1	string	255	Optional field of MRZ line 1
optionalData2	string	255	Optional field of MRZ line 2
address	object		Address in RAW format, see table below
issuingAuthority	string	50	Issuing authority of the document (if issuing authority extraction is enabled)
issuingPlace	string	50	Issuing place of the document (if issuing place extraction is enabled)
curp	string	18	CURP (if CURP extraction is enabled)
gender	string	1	Possible values: M, F
nationality	string	3	Nationality of the document holder in ISO 3166-1 alpha-3 country code (if extraction is enabled)
placeOfBirth	string	255	Place of birth of document holder
taxNumber	string	255	Tax number of the document if idCountry = ITA and idType = HEALTH_ID or TAX_ID (if Tax number extraction is enabled)
cpf	string	255	CPF number of the document (if CPF number extraction is enabled)
registrationNumber	string	255	Registration number of the document (if Registration number extraction is enabled)
mothersName	string	255	Name of the document holder's mother (if extraction is enabled)
fathersName	string	255	Name of the document holder's father (if extraction is enabled)
personalIdentificationNumber	string	255	National personal identification number of the document (if extraction is enabled)
rgNumber	string	255	"General Registration" number of Brazilian documents (if extraction is enabled)
voterIdNumber	string	255	"Clave de elector" number for idCountry = MEX (if extraction is enabled)
issuingNumber	string	255	"Numero de emission" number for idCountry = MEX (if extraction is enabled)
expiryDateParts	object		Object containing the expiry date information (year, month, day) from the corresponding fields on the document. Example: `{"year": "2022","month": "08","day": "31"}`
dobDateParts	object		Object containing the date of birth information (year, month, day) from the corresponding fields on the document. Example: `{"year": "2022","month": "08","day": "31"}`
issuingDateParts	object		Object containing the issuing date information (year, month, day) from the corresponding fields on the document. Example: `{"year": "2022","month": "08","day": "31"}`
laborIdentificationNumber	string		CUIL number of the document (if CUIL number extraction is enabled)
documentCopy	string		Ejemplar number of the document (if Ejemplar number extraction is enabled)
residentPermitType	string		Permit type related to "Golden Visas" if idCountry = GBR (if extraction is enabled)
residentPermitRemarks	string		Permit type related to "Golden Visas" if idCountry = GBR (if extraction is enabled)
documentIdentificationNumber	string		Document Identification Number (if extraction is enabled)
citizenship	string		Citizenship if idCountry = IDN (if extraction is enabled)
maritalStatus	string		Marital Status if idCountry = IDN (if extraction is enabled)
religion	string		Religion if idCountry = IDN, MYS (if extraction is enabled)
lastNameAtBirth	string		Last name at birth if idCountry = SLO (if extraction is enabled)
remarks	string		Special remarks/titles if idCountry = SLO Example: Mgr (if extraction is enabled)
disability	string		Check if there is at least one disability icon available on the back side if idCountry = BHR. Possible values: YES, NO (if extraction is enabled)

1 If one of the values such as "day" is not included in the document it will also not be returned in the object. For examples and additional details, refer to our Knowledge Base.

RAW address format

Name	Type	Max. Length	Description
line1	string	255	Line item1
line2	string	255	Line item2
line3	string	255	Line item3
line4	string	255	Line item4
line5	string	255	Line item5
country	string	3	Possible countries: ISO 3166-1 alpha-3 country code, XKX (Kosovo)
postalCode	string	255	Postal code
city	string	255	City
formattedAddress	string		Complete address in a formatted way

note

On 2020-08-15 we removed old address formats (EU, US). Retrieving document data for transactions older than 2020-08-15 which were initially returned in EU or US format will be now returned in RAW format.

Examples

Sample request

GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/document HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

{
    "type": "DRIVING_LICENSE",
    "dob": "1990-01-01",
    "expiry": "2022-12-31",
    "firstName": "FIRST NAME",
    "issuingCountry": "AUT",
    "gender": "M",
    "issuingDate": "2013-01-01",
    "lastName": "LAST NAME",
    "nationality": "BHR",
    "personalNumber": "12345679",
    "number": "123456789",
    "status": "APPROVED_VERIFIED",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-03-01T11:44:56.741Z"
}

Retrieving transaction data only

Call the RESTful API GET endpoint below to retrieve transaction metadata by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/transactionREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/transactionREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/transaction

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for the transaction
status	string		Possible states: PENDING, DONE, FAILED
source	string		ID Verification Web embedded: WEB, WEB-CAM, WEB-UPLOAD. ID Verification Web redirect: REDIRECT, REDIRECT-CAM, REDIRECT-UPLOAD. ID Verification API: API. ID Verification Mobile: SDK
date	string		Timestamp of the scan creation in the format YYYY-MM-DDThh:mm:ss.SSSZ
clientIp	string		IP address of the client in the format xxx.xxx.xxx.xxx
customerId	string	255	Your internal reference for the user.
merchantScanReference	string	255	Your internal reference for each transaction
merchantReportingCriteria	string	255	Your internal reporting criteria for each transaction

Examples

Sample request

GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/transaction HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

{
    "clientIp": "xxx.xxx.xxx.xxx",
    "customerId": "CUSTOMERID",
    "date": "2019-02-01T11:01:10.227Z",
    "merchantReportingCriteria": "YOURMERCHANTREPORTINGCRITERIA",
    "merchantScanReference": "YOURSCANREFERENCE",
    "source": "WEB_UPLOAD",
    "status": "DONE",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-03-01T11:46:57.127Z"
}

Retrieving verification data only

Call the RESTful API GET endpoint below to retrieve verification data by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/verificationREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/verificationREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/verification

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for the transaction
mrzCheck	string		Possible values: OK, NOT_AVAILABLE
rejectReason	object		Reject reason, see tables below
identityVerification	object		Identity verification, see table below
additionalChecks	object		Additional checks, see table below

Parameter rejectReason

Name	Type	Max. Length	Description
rejectReasonCode	string	5	see below
rejectReasonDescription	string	255	Possible codes and descriptions for verification status DENIED_FRAUD: 100 MANIPULATED_DOCUMENT 105 FRAUDSTER 106 FAKE 107 PHOTO_MISMATCH 108 MRZ_CHECK_FAILED 109 PUNCHED_DOCUMENT 110 CHIP_DATA_MANIPULATED (only available for ePassport) 111 MISMATCH_PRINTED_BARCODE_DATA 112 CHIP_MISSING 113 MISMATCHING_DATA_REPEATED_FACE1 114 DIGITAL_MANIPULATION 115 MISMATCH_HRZ_MRZ_DATA 118 MISMATCH_FRONT_BACK Possible codes and descriptions for verificationStatus = ERROR_NOT_READABLE_ID: 102 PHOTOCOPY_BLACK_WHITE 103 PHOTOCOPY_COLOR 104 DIGITAL_COPY 200 NOT_READABLE_DOCUMENT 201 NO_DOCUMENT 202 SAMPLE_DOCUMENT 206 MISSING_BACK 207 WRONG_DOCUMENT_PAGE 209 MISSING_SIGNATURE 210 CAMERA_BLACK_WHITE 211 DIFFERENT_PERSONS_SHOWN 213 INVALID_WATERMARK 214 MISSING_FRONT 300 MANUAL_REJECTION
rejectReasonDetails	JSON object / JSON array		Reject reason details as JSON object (if only one item is returned) or JSON array (containing JSON objects) if rejectReasonCode = 100 or 200, see table below

Name

Type

Max. Length

Description

rejectReasonCode

string

see below

rejectReasonDescription

string

255

Possible codes and descriptions for verification status DENIED_FRAUD:

100 MANIPULATED_DOCUMENT
105 FRAUDSTER
106 FAKE
107 PHOTO_MISMATCH
108 MRZ_CHECK_FAILED
109 PUNCHED_DOCUMENT
110 CHIP_DATA_MANIPULATED (only available for ePassport)
111 MISMATCH_PRINTED_BARCODE_DATA
112 CHIP_MISSING
113 MISMATCHING_DATA_REPEATED_FACE1
114 DIGITAL_MANIPULATION
115 MISMATCH_HRZ_MRZ_DATA
118 MISMATCH_FRONT_BACK

Possible codes and descriptions for verificationStatus = ERROR_NOT_READABLE_ID:

102 PHOTOCOPY_BLACK_WHITE
103 PHOTOCOPY_COLOR
104 DIGITAL_COPY
200 NOT_READABLE_DOCUMENT
201 NO_DOCUMENT
202 SAMPLE_DOCUMENT
206 MISSING_BACK
207 WRONG_DOCUMENT_PAGE
209 MISSING_SIGNATURE
210 CAMERA_BLACK_WHITE
211 DIFFERENT_PERSONS_SHOWN
213 INVALID_WATERMARK
214 MISSING_FRONT
300 MANUAL_REJECTION

rejectReasonDetails

JSON object / JSON array

Reject reason details as JSON object (if only one item is returned) or JSON array (containing JSON objects) if rejectReasonCode = 100 or 200, see table below

1activation required

Parameter rejectReasonDetails

Name	Type	Max. Length	Description
detailsCode	string	5	see below
detailsDescription	string	255	Possible codes and description details for rejectReasonCode = 100: 1001 PHOTO 1002 DOCUMENT_NUMBER 1003 EXPIRY 1004 DOB 1005 NAME 1006 ADDRESS 1007 SECURITY_CHECKS 1008 SIGNATURE 1009 PERSONAL_NUMBER 1011 PLACE_OF_BIRTH Possible codes and description details for rejectReasonCode = 200: 2001 BLURRED 2002 BAD_QUALITY 2003 MISSING_PART_DOCUMENT 2004 HIDDEN_PART_DOCUMENT 2005 DAMAGED_DOCUMENT 2006 GLARE 2007 MISSING_MANDATORY_DATAPOINTS

Name

Type

Max. Length

Description

detailsCode

string

see below

detailsDescription

string

255

Possible codes and description details for rejectReasonCode = 100:

1001 PHOTO
1002 DOCUMENT_NUMBER
1003 EXPIRY
1004 DOB
1005 NAME
1006 ADDRESS
1007 SECURITY_CHECKS
1008 SIGNATURE
1009 PERSONAL_NUMBER
1011 PLACE_OF_BIRTH

Possible codes and description details for rejectReasonCode = 200:

2001 BLURRED
2002 BAD_QUALITY
2003 MISSING_PART_DOCUMENT
2004 HIDDEN_PART_DOCUMENT
2005 DAMAGED_DOCUMENT
2006 GLARE
2007 MISSING_MANDATORY_DATAPOINTS

Parameter identityVerification

Name	Description
similarity	Possible values: MATCH NO_MATCH NOT_POSSIBLE
validity	Possible values: TRUE FALSE
reason	Provided if validity = FALSE. Possible values: SELFIE_CROPPED_FROM_ID ENTIRE_ID_USED_AS_SELFIE MULTIPLE_PEOPLE SELFIE_IS_SCREEN_PAPER_VIDEO SELFIE_MANIPULATED AGE_DIFFERENCE_TOO_BIG NO_FACE_PRESENT FACE_NOT_FULLY_VISIBLE BAD_QUALITY BLACK_AND_WHITE LIVENESS_FAILED

Parameter additionalChecks

Name	Type	Description	Notes
addressValidation	JSON	Result of Address Validation see table below	activation required
proofOfResidency	JSON	Result of Proof of Residency check if idCountry = AUS, BRA, CAN, DEU, ESP, GBR, MEX, see table below	activation required
watchlistScreening	JSON	Result of Jumio Screening (see ID Verification & ComplyAdvantage Screening Implementation Guide)	activation required
faceSearchFindings	JSON	Result of 1:n face search on previous transactions see table below	activation required
personalNumberValidation	JSON	Result of validation for CPF number see table below	activation required

Parameter addressValidation

Name	Type	Description
searchResults	enum	If verificationStatus = APPROVED_VERIFIED possible values: POSITIVE_RESULT PARTIAL_RESULT NEGATIVE_RESULT else CHECK_NOT_DONE (see searchResponse)
searchResponse	enum	Possible values: UNSUPPORTED_COUNTRY NOT_ENOUGH_DATA TECHNICAL_ERROR

Name

Type

Description

searchResults

enum

If verificationStatus = APPROVED_VERIFIED possible values:

POSITIVE_RESULT
PARTIAL_RESULT
NEGATIVE_RESULT

else

CHECK_NOT_DONE (see searchResponse)

searchResponse

enum

Possible values:

UNSUPPORTED_COUNTRY
NOT_ENOUGH_DATA
TECHNICAL_ERROR

Parameter proofOfResidency

Name	Type	Description
searchResults	enum	If verificationStatus = APPROVED_VERIFIED possible values: POSITIVE_RESULT PARTIAL_RESULT NEGATIVE_RESULT else CHECK_NOT_DONE (see searchResponse)
searchResponse	enum	Possible values: UNSUPPORTED_COUNTRY NOT_ENOUGH_DATA TECHNICAL_ERROR

Name

Type

Description

searchResults

enum

If verificationStatus = APPROVED_VERIFIED possible values:

POSITIVE_RESULT
PARTIAL_RESULT
NEGATIVE_RESULT

else

CHECK_NOT_DONE (see searchResponse)

searchResponse

enum

Possible values:

UNSUPPORTED_COUNTRY
NOT_ENOUGH_DATA
TECHNICAL_ERROR

Parameter faceSearchFindings

Name	Type	Description
status	enum	Possible values: DONE PENDING ERROR
findings	String/JSON array	A face (on the ID or Selfie) is matching with another face (on the ID or Selfie) from a previous transaction. Possible values: No findings: parameter not returned Single finding: String of the transaction reference Multiple findings: Array of transaction references

See 1:n Best Practice for further details.

Parameter personalNumberValidation

Name	Type	Description
searchResults	enum	If verificationStatus = APPROVED_VERIFIED possible values: POSITIVE_RESULT NEGATIVE_RESULT else CHECK_NOT_DONE (see searchReason)
searchReason	enum	Possible values: NOT_ENOUGH_DATA TECHNICAL_ERROR

Name

Type

Description

searchResults

enum

If verificationStatus = APPROVED_VERIFIED possible values:

POSITIVE_RESULT
NEGATIVE_RESULT

else

CHECK_NOT_DONE (see searchReason)

searchReason

enum

Possible values:

NOT_ENOUGH_DATA
TECHNICAL_ERROR

Examples

Sample request

GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/verification HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

{
    "additionalChecks": {
        "addressValidation": {
            "searchResults": "POSITIVE_RESULT"
        }
        "proofOfResidency": {
            "searchResults": "PARTIAL_RESULT"
        }
        "faceSearchFindings": {
            "status": "DONE",
            "findings": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
        }
        "personalNumberValidation": {
          "searchResults": "POSITIVE_RESULT"
        }
    },
    "identityVerification": {
        "similarity": "MATCH",
        "validity": "true"
    },
    "mrzCheck": "OK",
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-03-01T11:48:31.331Z"
}

Error (not readable ID)

{
    "mrzCheck": "OK",
    "rejectReason": {
        "rejectReasonCode": "201",
        "rejectReasonDescription": "NO_DOCUMENT"
    },
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-03-01T11:51:39.876Z"
}

Retrieving available images

Call the RESTful API GET endpoint below to retrieve a list of the available images for a transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/imagesREST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/imagesREST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/images

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for the transaction
images	JSON array/object		See table below
livenessImages	JSON array		List of REST URLs to retrieve specific liveness images

Parameter images

Required items appear in bold type.

Name	Type	Description
classifier	string	ID Verification: front face back
href	string	REST URL to retrieve specific image (see Retrieving a specific image section)

Examples

Sample request

GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

{
    "timestamp": "2019-03-01T11:53:52.878Z",
    "images": [
        {
            "classifier": "back",
            "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/back"
        },
        {
            "classifier": "front",
            "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/front"
        },
        {
            "classifier": "face",
            "href": "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/face"
        }
    ],
        "livenessImages": [
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/7",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/5",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/6",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/3",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/4",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/1",
                "https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/2"
    ],
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Retrieving a specific image

Call the RESTful GET API endpoint below to retrieve a specific image from a transaction by specifying the image classifier and the Jumio transaction reference (scan reference) of an existing transaction from your account as path parameters.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/images/<classifier>REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/images/<classifier>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/images/<classifier>

Request path parameters Required items appear in bold type.

Name	Type	Max. length	Description
scanReference	string	36	Jumio’s reference number for the transaction
classifier	string		ID Verification: front face back

Response

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

Examples

Sample request

GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/front HTTP/1.1
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

Retrieving liveness images

Call the RESTful API GET endpoint below to retrieve liveness images from a transaction by specifying the liveness number and the Jumio transaction reference (scan reference) of an existing transaction from your account as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/images/liveness/<livenessNumber>REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/images/liveness/<livenessNumber>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/images/liveness/<livenessNumber>

Request path parameters

Required items appear in bold type.

Name	Type	Max. length	Description
scanReference	string	36	Jumio’s reference number for the transaction
livenessNumber	integer		Number of image from the liveness sequence

Response

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

Examples

Sample request

GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/1 HTTP/1.1
Accept: image/jpeg
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Authentication retrieval

Retrieving details

Call the RESTful API GET endpoint below to retrieve the details of an Authentication transaction by specifying the Jumio transaction reference of an existing Authentication transaction from your account as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/authentications/<transactionReference>REST URL (EU): https://lon.netverify.com/api/netverify/v2/authentications/<transactionReference>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/authentications/<transactionReference>

Response

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
transactionReference	string	36	Jumio’s reference number for the Authentication transaction
enrollmentTransactionReference	string	36	Jumio’s reference number of the enrollment transaction (ID)
transactionResult	string		Possible values: CREATED STARTED PASSED FAILED INVALID EXPIRED
transactionDate	string		Timestamp of the transaction in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanSource	string		Possible value: SDK WEB
userReference	string		Your internal reference for the user
images	JSON array/object		See table below
livenessImages	JSON array		List of REST URLs to retrieve specific liveness images

Parameter images

Required items appear in bold type.

Name	Type	Description
classifier	string	Possible value: face
href	string	REST URL to retrieve specific image (see Retrieving a specific image)

Examples

Sample request

GET https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

{
    "transactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "enrollmentTransactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "transactionResult": "PASSED",
    "scanSource": "SDK",
    "transactionDate": "2019-05-23T14:32:27.534",
    "images": [
        {
            "classifier": "face",
            "href": "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/face"
        }
    ],
    "livenessImages": [
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/1",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/2",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/3",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/4",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/5",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/6",
        "https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/7"
    ]
}

Retrieving a specific image

Call the RESTful API GET endpoint below to retrieve the face image from an Authentication transaction by specifying the Jumio transaction reference of an existing Authentication transaction from your account as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/authentications/<transactionReference>/images/<classifier>REST URL (EU): https://lon.netverify.com/api/netverify/v2/authentications/<transactionReference>/images/<classifier>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/authentications/<transactionReference>/images/<classifier>

Request path parameters

Required items appear in bold type.

Name	Type	Max. length	Description
transactionReference	string	36	Jumio’s reference number for the Authentication transaction
classifier	string		Possible value: face

Response

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

Examples

Sample request

GET https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/face HTTP/1.1
Accept: image/jpeg
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Retrieving liveness images

Call the RESTful API GET endpoint below to retrieve liveness images from an Authentication transaction by specifying the liveness number and the Jumio transaction reference of an existing Authentication transaction from your account as a path parameter.

HTTP request method:GETREST URL (US): https://netverify.com/api/netverify/v2/authentications/<transactionReference>/images/liveness/<livenessNumber>REST URL (EU): https://lon.netverify.com/api/netverify/v2/authentications/<transactionReference>/images/liveness/<livenessNumber>REST URL (SGP):https://core-sgp.jumio.com/api/netverify/v2/authentications/<transactionReference>/images/liveness/<livenessNumber>

Request path parameters

Required items appear in bold type.

Name	Type	Max. length	Description
transactionReference	string	36	Jumio’s reference number for the Authentication transaction
livenessNumber	integer		Number of image from the liveness sequence

Response

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

Examples

Sample request

GET https://netverify.com/api/netverify/v2/authentications/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/liveness/1 HTTP/1.1
Accept: image/jpeg
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Document Verification retrieval

Retrieving status

Call the RESTful API GET endpoint below to retrieve the status of a Document Verification transaction by specifying the Jumio transaction reference (scan reference) of an existing transaction from your account as a path parameter.

HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>REST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for the transaction
status	string		Possible states: DONE FAILED

Examples

Sample request

GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:52:48.864Z",
    "status": "DONE"
}

Retrieving details

Call the RESTful API GET endpoint below to retrieve the document and transaction details of a Document Verification transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/dataREST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/dataREST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for the transaction
document	object		Same parameters as listed in the section Retrieving document data only but without timestamp and scanReference
transaction	object		Same parameters as listed in the section Retrieving transaction data only but without timestamp and scanReference

Examples

Sample request

GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Sample requests cannot be run as-is. Replace example data with your own values. Sample response Credit card (CC)

{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:42:31.858Z",
    "document": {
        "status": "EXTRACTED",
        "type": "CC",
        "extractedData": {
            "firstName": "FULL NAME",
            "signatureAvailable": false,
            "extractedData": "{\"expiryDate\":\"01/22\",\"firstName\":\"FULL NAME\",\"pan\":\"XXXXXXXXXXXX1234\"
            }"
        },
        "country": "AUT"
    },
    "transaction": {
        "status": "DONE",
        "merchantScanReference": "YOURSCANREFERENCE",
        "customerId": "CUSTOMERID",
        "source": "DOC_UPLOAD"
    }
}

Social Security card (SSC)

{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:40:49.124Z",
    "document": {
        "status": "EXTRACTED",
        "type": "SSC",
        "extractedData": {
            "firstName": "FIRST NAME",
            "lastName": "LAST NAME",
            "ssn": "123-45-6789",
            "signatureAvailable": false,
            "extractedData": "{\"lastName\":\"LAST NAME\",\"firstName\":\"FIRST NAME\",\"signaturePresent\":\"true\",\"ssn\":\"123-45-6789\"
            }"
        },
        "country": "USA"
    },
    "transaction": {
        "status": "DONE",
        "merchantScanReference": "YOURSCANREFERENCE",
        "customerId": "CUSTOMERID",
        "source": "DOC_UPLOAD"
    }
}

Bank statement (BS)

{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:32:22.606Z",
    "document": {
        "status": "EXTRACTED",
        "type": "BS",
        "extractedData": {
            "firstName": "FULL NAME",
            "signatureAvailable": false,
            "extractedData": "{\"city\":\"CITY\",\"addressFormat\":\"RAW\",\"postalCode\":\"12345\",\"accountNumber\":\"123456789\",\"subdivision\":\"XX\",\"firstName\":\"FULL NAME\",\"issueDate\":\"2019-01-01\",\"line1\":\"12345 EASY STREET\"}"
        },
        "country": "USA",
        "originalDocument": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/original"
    },
    "transaction": {
        "status": "DONE",
        "merchantScanReference": "YOURSCANREFERENCE",
        "customerId": "CUSTOMERID",
        "source": "DOC_UPLOAD"
    }
}

Retrieving document data only

Call the RESTful API GET endpoint below to retrieve the document data of a Document Verification transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data/documentREST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/data/documentREST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data/document

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for the transaction
status	string		Possible states: UPLOADED (default) EXTRACTED if the document provided is supported for data extraction DISCARDED if the document provided is not supported for data extraction
type	string		Possible types: CC (Credit card, front and back side) BS (Bank statement, front side) IC (Insurance card, front side) UB (Utility bill, front side) CAAP (Cash advance application, front and back side) CRC (Corporate resolution certificate, front and back side) CCS (Credit card statement, front and back side) LAG (Lease agreement, front and back side) LOAP (Loan application, front and back side) MOAP (Mortgage application, front and back side) TR (Tax return, front and back side) VT (Vehicle title, front side) VC (Voided check, front side) STUC (Student card, front side) HCC (Health care card, front side) CB (Council bill, front side) SENC (Seniors card, front side) MEDC (Medicare card, front side) BC (Birth certificate, front side) WWCC (Working with children check, front side) SS (Superannuation statement, front side) TAC (Trade association card, front side) SEL (School enrolment letter, front side) PB (Phone bill, front side) SSC (Social security card, front side) CUSTOM (Custom document type) OTHER (Other document type)
country	string	3	Possible countries: ISO 3166-1 alpha-3 country code XKX (Kosovo)
originalDocument	string	255	URL to retrieve the original document (PDF), if available
customDocumentCode	string	100	Your custom document code (configured in the Customer Portal) if type = CUSTOM
extractedData	object		Extracted data when the document provided is supported for data extraction, see table below

extractedData object

Name	Type	Max. Length	Description
signatureAvailable	Boolean		true if signature available, otherwise false
ssn	string	255	Social security number (if readable)
firstName	string	255	First name if readable for SSC type, full name if readable for all other types
lastName	string	255	Last name if readable (SSC type only).
extractedData	object		Extracted data when the document provided is supported for data extraction, see table below

Nested extractedData object

Name	Type	Max. Length	Description
addressFormat	string	255	RAW
line1	string	100	Address line 1
line2	string	100	Address line 2
countryCode	string	3	Possible countries of residence: ISO 3166-1 alpha-3 country code XKX (Kosovo)
postalCode	string	15	Postal code
city	string	64	City
subdivision	string	50	Name of subdivision (US state is returned in this field)
firstName	string	255	First name if readable for SSC type, full name if readable for all other types
lastName	string	255	Last name if readable (SSC type only)
ssn	string	255	Social security number if readable (SSC type only)
signaturePresent	string	255	"true" if signature is present, otherwise "false"
accountNumber	string		IBAN or account number
swiftCode	string	20	BIC/SWIFT code
issueDate	string		Issue date in the format YYYY-MM-DD
expiryDate	string		Date of expiry in the format MM/YY (CC type only)
pan	string	20	Personal account number of credit card (CC type only)

Examples

Sample request

GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/document HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Sample response

Credit card (CC)

{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:02:43.691Z",
    "status": "EXTRACTED",
    "type": "CC",
    "extractedData": {
        "firstName": "FULL NAME",
        "signatureAvailable": false,
        "extractedData": "{\"expiryDate\":\"01/22\",\"firstName\":\"FULL NAME\",\"pan\":\"XXXXXXXXXXXX1234\"}"
    },
    "country": "AUT"
}

Social Security card (SSC)

{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:05:21.904Z",
    "status": "EXTRACTED",
    "type": "SSC",
    "extractedData": {
        "firstName": "FIRST NAME",
        "lastName": "LAST NAME",
        "ssn": "123-45-6789",
        "signatureAvailable": false,
        "extractedData": "{\"lastName\":\"LAST NAME\",\"firstName\":\"FIRST NAME\",\"signaturePresent\":\"true\",\"ssn\":\"123-45-6789\"}"
    },
    "country": "USA"
}

Bank statement (BS)

{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T15:07:25.098Z",
    "status": "EXTRACTED",
    "type": "BS",
    "extractedData": {
        "firstName": "FULL NAME",
        "signatureAvailable": false,
        "extractedData": "{\"city\":\"CITY\",\"addressFormat\":\"RAW\",\"postalCode\":\"12345\",\"accountNumber\":\"123456789\",\"subdivision\":\"XX\",\"firstName\":\"FULL NAME\",\"issueDate\":\"2019-01-01\",\"line1\":\"12345 EASY STREET\"}"
    },
    "country": "USA",
    "originalDocument": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/original"
}

Retrieving transaction data only

Call the RESTful API GET endpoint below to retrieve the transaction metadata of a Document Verification transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data/transactionREST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/data/transactionREST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data/transaction

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for each transaction
status	string		Possible states: DONE FAILED
source	string		Possible status: DOC_API DOC_UPLOAD
merchantReportingCriteria	string	255	Your internal reporting criteria for each transaction
merchantScanReference	string	255	Your internal reference for each transaction
customerId	string	255	Your internal reference for the user.

Examples

Sample request

GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/transaction HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

{
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "timestamp": "2019-01-01T16:02:25.646Z",
    "status": "DONE",
    "merchantScanReference": "YOURSCANREFERENCE",
    "customerId": "CUSTOMERID",
    "source": "DOC_UPLOAD"
}

Retrieving available images

Call the RESTful API GET endpoint below to retrieve a list of the available images for a Document Verification transaction by specifying the Jumio transaction reference (scan reference) as a path parameter.

HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/pagesREST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/pagesREST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/pages

Response

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		Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
scanReference	string	36	Jumio’s reference number for the transaction
images	JSON array/object		See table below

Parameter images

Required items appear in bold type.

Name	Type	Description
classifier	integer	Page number specifed when uploading the image
href	string	REST URL to retrieve specific image (see Retrieving a specific image section)

Examples

Sample request

GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages HTTP/1.1
Accept: application/json
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Sample requests cannot be run as-is. Replace example data with your own values. Sample response Bank statement (BS)

{
    "timestamp": "2019-01-01T16:04:07.751Z",
    "images": [
        {
            "classifier": 1,
            "href": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/1"
        }
        {
            "classifier": 2,
            "href": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/2"
        }
    ],
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Credit card (CC)

{
    "timestamp": "2019-01-01T16:10:42.368Z",
    "images": [
        {
            "classifier": 101,
            "href": "https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/101"
        }
    ],
    "scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Retrieving a specific image

Call the RESTful HTTP GET API below to receive a specific image from a Document Verification transaction by specifying the Jumio scan reference as a path parameter.

To retrieve an unmasked credit card image, append the query parameter maskhint=unmasked. By default, retrieval of unmasked credit card images is disabled, and will return HTTP status code 403 Forbidden. If you want to enable it please contact Jumio Support. Retrieving unmasked credit card images might impose additional security requirements on your systems depending on whether you already store/transmit/process credit card data on your systems.

If you are unsure about the PCI DSS ramifications of retrieving unmasked credit card images, please refer to Information Supplement: PCI DSS E-commerce Guidelines, version 2.0, January 2013, and/or contact your acquirer or a PCI DSS QSA (Qualified Security Assessor).

HTTP request method:GETREST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/pages/<page_number>REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/pages/<page_number>REST URL (SGP):https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/pages/<page_number>

Request path parameters Required items appear in bold type.

Name	Type	Max. Length	Description
scanReference	string	36	Jumio’s reference number for the transaction
page_number	string	36	Page number specified when uploading the image
maskhint	string		For credit cards: masked (default) unmasked

Response

Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).

Examples

Sample request

GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/1 HTTP/1.1
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Usage​

Best Practice​

Authentication and encryption​

Request Headers​

ID Verification retrieval​

Retrieving status​

Response​

Examples​

Retrieving details​

Response​

Parameter facemap​

Response​

Examples​

Sample request​

Sample response​

Retrieving document data only​

Response​

RAW address format​

Examples​

Retrieving transaction data only​

Response​

Examples​

Retrieving verification data only​

Response​

Parameter rejectReason​

Parameter rejectReasonDetails​

Parameter identityVerification​

Parameter additionalChecks​

Parameter addressValidation​

Parameter proofOfResidency​

Parameter faceSearchFindings​

Parameter personalNumberValidation​

Examples​

Retrieving available images​

Response​

Parameter images​

Examples​

Retrieving a specific image​

Response​

Examples​

Retrieving liveness images​

Request path parameters​

Response​

Examples​

Authentication retrieval​

Retrieving details​

Response​

Parameter images​

Examples​

Retrieving a specific image​

Request path parameters​

Response​

Examples​

Retrieving liveness images​

Request path parameters​

Response​

Examples​

Document Verification retrieval​

Retrieving status​

Response​

Examples​

Retrieving details​

Response​

Examples​

Retrieving document data only​

Response​

extractedData object​

Nested extractedData object​

Examples​

Retrieving transaction data only​

Response​

Examples​

Retrieving available images​

Response​

Parameter images​

Examples​

Retrieving a specific image​

Response​

Examples​

Table of Contents

Usage

Best Practice

Authentication and encryption

Request Headers

ID Verification retrieval

Retrieving status

Response

Examples

Retrieving details

Response

Parameter facemap

Response

Examples

Sample request

Sample response

Retrieving document data only

Response

RAW address format

Examples

Retrieving transaction data only

Response

Examples

Retrieving verification data only

Response

Parameter rejectReason

Parameter rejectReasonDetails

Parameter identityVerification

Parameter additionalChecks

Parameter addressValidation

Parameter proofOfResidency

Parameter faceSearchFindings

Parameter personalNumberValidation

Examples

Retrieving available images

Response

Parameter images

Examples

Retrieving a specific image

Response

Examples

Retrieving liveness images

Request path parameters

Response

Examples

Authentication retrieval

Retrieving details

Response

Parameter images

Examples

Retrieving a specific image

Request path parameters

Response

Examples

Retrieving liveness images

Request path parameters

Response

Examples

Document Verification retrieval

Retrieving status

Response

Examples

Retrieving details

Response

Examples

Retrieving document data only

Response

extractedData object

Nested extractedData object

Examples

Retrieving transaction data only

Response

Examples

Retrieving available images

Response

Parameter images

Examples

Retrieving a specific image

Response

Examples