ID Verification Retrieval API Implementation Guide

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

Revision history

Date	Description
2021-09-01	Added reject reason code 115 for MISMATCH_HRZ_MRZ_DATA
2021-06-23	Added reject reason code 113 for MISMATCHING_DATA_REPEATED_FACE
2021-05-21	Added "personalNumberValidation" to "additionalChecks"
2020-08-15	Removed EU and US address format
2020-05-26	Added "enrollmentTransactionReference" to Authentication retrieval
2020-03-03	Added "faceSearchFindings" to "additionalChecks"
2020-01-27	Added "addressValidation" and "proofOfResidency" to "additionalChecks"
2019-07-23	Added response parameter "facemap" for ID Verification
2019-05-28	Added Retrieval API for Authentication
2019-04-17	Formatting and corrections
2019-02-15	Added value "OTHER" to parameter "type" for Document Verification
2019-01-31	Added new validity reason "LIVENESS_FAILED"
2019-01-15	Added response parameter "livenessImages" for ID Verification
2018-11-12	Added response parameter "issuingAuthority", "issuingPlace", and value "PUBLIC_SAFETY_ID" to parameter "idSubtype", updated idSubtype "MILITARY_ID"
2018-10-31	Updated usage guidelines
2018-10-02	Add swiftCode to Parameter "extractedData" for BS, removed deprecated faceMatch percentages
2018-02-01	Added response parameter "originalDocument" for Document Verification Retrieval Retrieving document data only Added Australia and Canada states to response parameter "usState"
2018-01-17	Added new validity reason BLACK_AND_WHITE Updated supported countries for idSubtype LEARNING_DRIVING_LICENSE
2017-11-23	Added value "Visa" to response parameter "type" for ID Verification Retrieval - Retrieving Document Data only
2017-09-21	Removed response parameter "additionalInformation"
2017-08-24	Added response parameter "identityVerification"
2017-05-23	Added response parameter "issuingDate" for retrieving scan details and document data only
2017-01-31	Added value "PASSPORT_CARD_ID" and "MILITARY_ID" to parameter "idSubType"
2016-11-15	Added reject reason detail code 10011 for PLACE_OF_BIRTH
2016-06-21	Removed Content-Length header for HTTP GET APIs
2016-05-18	Added value "STUDENT_ID" to parameter "idSubType" Removed TLS_DHE ciphers
2016-02-09	Added reject reason code 111 for MISMATCH_PRINTED_BARCODE_DATA
2015-11-17	Added parameter "idSubtype" to ID Verification Retrieval
2015-10-21	Added ECDHE ciphers to supported cipher suites
2015-09-23	Added parameter "country" and "customDocumentCode" for ID Verification Multi Document Retrieval
2015-09-09	Added ID Verification Multi Document Retrieval Added second set of API credentials for retrieving transaction data
2015-08-11	Added new classifier "face" for retrieving scan images
2015-07-14	Added value "XKX" for Kosovo to parameters "country" and "issuingCountry" Added value "Kosovo" to parameter "usState"
2015-06-30	Introduced EU data center
2015-04-08	Added reject reason code 109 for PUNCHED_DOCUMENT
2015-03-24	Removed cipher TLS_RSA_WITH_RC4_128_SHA due to RC4 deprecation
2014-03-05	Added sources WEB and REDIRECT Document type not mandatory anymore
2014-09-25	Changed parameter "maskhint" to apply for credit cards only
2014-08-19	Initial release

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 API and Delete API in the Customer Portal under Settings > API credentials > Transaction administration APIs.

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

⚠️ 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: GET
REST 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>

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

⚠️ 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: GET
REST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data
REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data
REST URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data

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
document	object		As listed in the section Retrieving document data only without timestamp and scanReference
transaction	object		As listed in the section Retrieving transaction data only without timestamp and scanReference
verification	object		As listed in the section Retrieving verification data only 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 which can be used to retrieve 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

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, does not contain a valid facemap or has been deleted.

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

⚠️ 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: GET
REST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/document
REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/document
REST URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/document

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		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
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
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)

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: GET
REST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/transaction
REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/transaction
REST URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/transaction

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
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: GET
REST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/data/verification
REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/data/verification
REST URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/data/verification

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
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 113 MISMATCHING_DATA_REPEATED_FACE¹ 115 MISMATCH_HRZ_MRZ_DATA 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 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

¹activation 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 10011 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

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

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

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

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: GET
REST URL (US): https://netverify.com/api/netverify/v2/scans/<scanReference>/images
REST URL (EU): https://lon.netverify.com/api/netverify/v2/scans/<scanReference>/images
REST URL (SGP): https://core-sgp.jumio.com/api/netverify/v2/scans/<scanReference>/images

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
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: GET
REST 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

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, has been deleted, or does not contain the image you requested.

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: GET
REST 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

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 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: GET
REST 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

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
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: GET
REST 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

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 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: GET
REST 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

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 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: GET
REST 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

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: • 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: GET
REST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data
REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/data
REST URL (SGP): https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data

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
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: GET
REST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data/document
REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/data/document
REST URL (SGP): https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data/document

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: • 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: GET
REST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data/transaction
REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/data/transaction
REST URL (SGP): https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/data/transaction

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 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: GET
REST URL (US): https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/pages
REST URL (EU): https://retrieval.lon.netverify.com/api/netverify/v2/documents/<scanReference>/pages
REST URL (SGP): https://retrieval.core-sgp.jumio.com/api/netverify/v2/documents/<scanReference>/pages

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
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: GET
REST 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

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, has been deleted, or does not contain the image you requested.

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.

Files

netverify-retrieval-api.md

Latest commit

History

netverify-retrieval-api.md

File metadata and controls

ID Verification Retrieval API Implementation Guide

Revision history

Table of Contents

Usage

Best Practice:

Authentication and encryption

Request headers

ID Verification retrieval

Retrieving status

Response

Examples

Sample request

Sample response

Retrieving details

Response

Parameter facemap

Retrieving facemap

Response

Examples

Sample request

Sample response

Retrieving document data only

Response

RAW address format

Examples

Sample request

Sample response

Retrieving transaction data only

Response

Examples

Sample request

Sample response

Retrieving verification data only

Response

Parameter rejectReason

Parameter rejectReasonDetails

Parameter identityVerification

Parameter additionalChecks

Parameter addressValidation

Parameter proofOfResidency

Parameter faceSearchFindings

Parameter personalNumberValidation

Examples

Sample request

Sample response

Approved verified

Error (not readable ID)

Retrieving available images

Response

Parameter images

Examples

Sample request

Sample response

Retrieving a specific image

Request path parameters

Response

Examples

Sample request

Retrieving liveness images

Request path parameters

Response

Examples

Sample request

Authentication retrieval

Retrieving details

Response

Parameter images

Examples

Sample request

Sample response

Retrieving a specific image

Request path parameters

Response

Examples

Parameter `facemap`

Parameter `rejectReason`

Parameter `rejectReasonDetails`

Parameter `identityVerification`

Parameter `additionalChecks`

Parameter `addressValidation`

Parameter `proofOfResidency`

Parameter `faceSearchFindings`

Parameter `personalNumberValidation`

Parameter `images`

Parameter `images`

`extractedData` object

Nested `extractedData` object

Parameter `images`