Skip to content

Latest commit

 

History

History
1504 lines (1152 loc) · 69.7 KB

netverify-retrieval-api.md

File metadata and controls

1504 lines (1152 loc) · 69.7 KB
Raw

Jumio

ID Verification Retrieval API Implementation Guide

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

Revision history

Date Description
2022-01-26 Added reject reason code 112 for CHIP_MISSING
Added reject reason code 114 for DIGITAL_MANIPULATION
2022-01-23 Added response parameter "expiryDateParts", "dateOfBirthParts", "issuingDateParts"
2021-12-07 Added reject reason code 214 for MISSING_FRONT
2021-11-15 Added reject reason code 116 for SUPERIMPOSED_TEXT
Added reject reason code 118 for MISMATCH_FRONT_BACK
Added reject reason description code 2007 for MISSING_MANDATORY_DATAPOINTS
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

Table of Contents

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 [email protected] 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 (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 1
Example:
{"year": "2022",
"month": "08",
"day": "31"}
dateOfBirthParts object Object containing the date of birth information (year, month, day) from the corresponding fields on the document 1
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 1
Example:
{"year": "2022",
"month": "08",
"day": "31"}

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: 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
112 CHIP_MISSING
113 MISMATCHING_DATA_REPEATED_FACE1
114 DIGITAL_MANIPULATION
115 MISMATCH_HRZ_MRZ_DATA
116 SUPERIMPOSED_TEXT
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
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
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

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.

© Jumio Corporation, 395 Page Mill Road, Suite 150 Palo Alto, CA 94306