This guide illustrates how to implement the Netverify Retrieval API.
| Date | Description |
|---|---|
| 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 Netverify |
| 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 Netverify 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 Netverify Retrieval |
| 2015-10-21 | Added ECDHE ciphers to supported cipher suites |
| 2015-09-23 | Added parameter "country" and "customDocumentCode" for Netverify Multi Document Retrieval |
| 2015-09-09 | Added Netverify 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
- Authentication and header
- Netverify Retrieval
- Document Verification Retrieval
- Supported Cipher Suites
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.
- You must use Scan Status Retrieval for all requests until the scan is no longer in PENDING status.
- If the scan status is DONE or FAILED (not pending), retrieve scan details and image(s) once.
- Maximum of 10 consecutive retrieval attempts after successful image acquisition
(SDK/Web: User journey finshed; API: after performNetverify API call)
- In case a final result is not available after 10 attempts, you are allowed to perform an additional retrieval call once a 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: Each API call is protected. To access it, use HTTP Basic Authentication with your API token as the "userid" and your API secret as the "password". You can find your API token and API secret by logging into your Jumio customer portal and navigating to the "Settings" page and clicking on the "API credentials" tab.
Note: You have the opportunity to generate a second set of API credentials for retrieving transaction data in your customer portal under "API credentials - Transaction administration APIs".
Header: The following parameters are mandatory in the "header" section of your request.
Accept: application/jsonorimage/jpeg, image/pngfor "Retrieving specific image"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.
TLS handshake: The TLS protocol is required (see Supported cipher suites) and we strongly recommend using the latest version.
Note: Calls with missing or suspicious headers, suspicious parameter values, or without HTTP Basic Authentication result in HTTP status code 403 Forbidden.
Call the RESTful HTTP GET API below to receive the status of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://netverify.com/api/netverify/v2/scans/<scanReference>
If your customer account is in the EU data center, use lon.netverify.com instead of netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available or deleted.
| Parameter | 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 scan |
| status | String | Possible states: • PENDING • DONE • FAILED |
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"timestamp": "2014-08-13T12:08:02.068Z",
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "DONE"
}
Call the RESTful HTTP GET API below to receive document, transaction and verification details of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://netverify.com/api/netverify/v2/scans/<scanReference>/data
If your customer account is in the EU data center, use lon.netverify.com instead of netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available or deleted.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| 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 | |
| verification | Object | Same parameters as listed in the section Retrieving verification data only but without timestamp and scanReference |
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"timestamp": "2014-08-14T08:16:20.845Z",
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"document": {
"type": "PASSPORT",
"dob": "1990-01-01",
"expiry": "2022-12-31",
"firstName": "FIRSTNAME",
"issuingCountry": "USA",
"lastName": "LASTNAME",
"number": "P1234",
"status": "APPROVED_VERIFIED"
},
"transaction": {
"clientIp": "xxx.xxx.xxx.xxx",
"customerId": "CUSTOMERID",
"date": "2014-08-10T10:27:29.494Z",
"source": "WEB_UPLOAD",
"status": "DONE"
},
"verification": {
"mrzCheck": "OK"
}
}
Call the RESTful HTTP GET API below to receive document related data of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://netverify.com/api/netverify/v2/scans/<scanReference>/data/document
If your customer account is in the EU data center, use lon.netverify.com instead of netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available, pending or deleted.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| status * | String | Netverify: • APPROVED_VERIFIED • DENIED_FRAUD • DENIED_UNSUPPORTED_ID_TYPE • DENIED_UNSUPPORTED_ID_COUNTRY • ERROR_NOT_READABLE_ID • NO_ID_UPLOADED |
|
| type | String | Netverify: • 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 • OTHER_ID • VISA • UNKNOWN Possible subtypes if type = DRIVING_LICENSE • LEARNING_DRIVING_LICENSE Possible subtypes if type = PASSPORT • E_PASSPORT (only for mobile) |
| issuingCountry | String | 3 | Possible countries: • ISO 3166-1 alpha-3 country code - XKX (Kosovo) |
| firstName | String | 255 | First name of the customer |
| lastName | String | 255 | Last name of the customer |
| 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 US, EU or Raw format, see tables 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) |
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| city | String | 255 | City |
| stateCode | String | 6 | ISO 3166-2 state code |
| streetName | String | 255 | Street name |
| streetSuffix | String | 255 | Street suffix abbreviation Examples: US, Canada, Australia |
| streetDirection | String | 255 | Street direction abbreviation Examples: US (E=EAST, W=WEST, N=NORTH, S=SOUTH), Canada, Australia |
| streetNumber | String | 255 | Street number |
| unitDesignator | String | 255 | Unit designator abbreviation Examples: US, Canada, Australia |
| unitNumber | String | 255 | Unit number |
| zip | String | 255 | Zip code |
| zipExtension | String | 255 | Zip extension |
| country | String | 3 | Possible countries: • ISO 3166-1 alpha-3 country code • XKX (Kosovo) |
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| city | String | 255 | City |
| province | String | 255 | Province |
| streetName | String | 255 | Street name |
| streetNumber | String | 255 | Street number |
| unitDetails | String | 255 | Unit details |
| postalCode | String | 255 | Postal code |
| country | String | 3 | Possible countries: - ISO 3166-1 alpha-3 country code - XKX (Kosovo) |
| Parameter | 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 |
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/document HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"type": "PASSPORT",
"dob": "1990-01-01",
"expiry": "2022-12-31",
"firstName": "FIRSTNAME",
"issuingCountry": "USA",
"lastName": "LASTNAME",
"number": "P1234",
"issuingDate": "2015-11-01",
"status": "APPROVED_VERIFIED"
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": "2014-08-14T09:05:47.394Z"
}
Call the RESTful HTTP GET API below to receive transaction related data of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://netverify.com/api/netverify/v2/scans/<scanReference>/data/transaction
If your customer account is in the EU data center, use lon.netverify.com instead of netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available, pending or deleted.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| status * | String | Possible states: • PENDING • DONE • FAILED |
|
| source * | String | Netverify Web embedded: • WEB • WEB-CAM • WEB-UPLOAD Netverify Web redirect: • REDIRECT • REDIRECT-CAM • REDIRECT-UPLOAD performNetverify: • API Netverify 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 | ID of the customer |
| merchantScanReference | String | 255 | Your reference for each scan |
| merchantReportingCriteria | String | 255 | Your reporting criteria for each scan |
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/transaction HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"clientIp": "xxx.xxx.xxx.xxx",
"customerId": "CUSTOMERID",
"date": "2014-08-10T10:27:29.494Z",
"source": "WEB_UPLOAD",
"status": "DONE"
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": "2014-08-14T10:06:13.610Z"
}
Call the RESTful HTTP GET API below to receive verification related data of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://netverify.com/api/netverify/v2/scans/<scanReference>/data/verification
If your customer account is in the EU data center, use lon.netverify.com instead of netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available, pending, deleted or of source Netverify Multi Document Legacy.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| mrzCheck | String | Possible values: • OK • NOT_AVAILABLE |
|
| rejectReason | Object | Reject reason, see tables below | |
| identityVerification | Object | Identity verification, see table below |
| Parameter "rejectReason" | 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 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 | Object | Reject reason details as JSON array containing JSON objects if rejectReasonCode = 100 or 200, see table below |
| Parameter "rejectReasonDetails" | 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 Possible codes and description details for rejectReasonCode = 200: 2001 BLURRED 2002 BAD_QUALITY 2003 MISSING_PART_DOCUMENT 2004 HIDDEN_PART_DOCUMENT 2005 DAMAGED_DOCUMENT |
| Parameter "identityVerification" | Max. Length | 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 |
|
| handwrittenNoteMatches | Only visible if setting is turned on within your account. For questions about this feature, please contact your Support. Possible values: • TRUE • FALSE |
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/verification HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"mrzCheck": "OK",
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": "2014-08-14T10:56:19.088Z"
}
Call the RESTful HTTP GET API below to receive available images of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://netverify.com/api/netverify/v2/scans/<scanReference>/images
If your customer account is in the EU data center, use lon.netverify.com instead of netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available or deleted.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| images | JSON Array/Object | Available image/s see table below | |
| livenessImages | JSON Array | Available liveness images |
| Parameter "images" | Type | Description |
|---|---|---|
| classifier * | String | Netverify: • front • face • back |
| href * | String | REST URL to retrieve specific image (see Retrieving specific image section) |
| maskhint | String | For credit cards: • masked • unmasked |
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"timestamp": "2014-08-14T11:22:20.182Z",
"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"
}
],
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Call the RESTful HTTP GET API below to receive a specific image of a scan by specifying the Jumio scan reference as a path parameter.
To receive the unmasked credit card image, append the query parameter maskhint=unmasked. By default, retrieval of unmasked credit card images is disabled (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 if you already store/transmit/process credit card data on your systems.
In case you are unsure about the ramifications of retrieving unmasked images regarding PCI DSS please refer to "Information Supplement: PCI DSS E-commerce Guidelines, version 2.0, January 2013" and/or contact your acquirer and/or contact a PCI DSS QSA (Qualified Security Assessor).
HTTP request method: GET
REST URL: https://netverify.com/api/netverify/v2/scans/<scanReference>/images/<classifier>
If your customer account is in the EU data center, use lon.netverify.com instead of netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
| classifier * (path parameter) | String | Netverify: • front • face • back |
|
| maskhint (path parameter) | String | For credit cards: • masked (default) • unmasked |
You receive a JPG or PNG image in case of success with the according header (e.g. Content-Type: image/jpeg), or HTTP status code 404 Not Found if the scan is not available, deleted or not containing the specified image.
GET https://netverify.com/api/netverify/v2/scans/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/images/front HTTP/1.1
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
Call the RESTful HTTP GET API below to receive the status of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>
If your customer account is in the EU data center, use retrieval.lon.netverify.com instead of retrieval.netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available or deleted.
| Parameter | 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 scan |
| status | String | Possible states: • DONE • FAILED |
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": "2015-08-13T12:08:02.068Z",
"status": "DONE"
}
Call the RESTful HTTP GET API below to receive document and transaction details of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data
If your customer account is in the EU data center, use retrieval.lon.netverify.com instead of retrieval.netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available, pending or deleted.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| 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 |
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": "2015-08-14T08:16:20.845Z",
"document": {
"status": "EXTRACTED",
"type": "SSC",
"extractedData": {
"firstName": "FIRSTNAME",
"lastName": "LASTNAME",
"ssn": "12341234",
"signatureAvailable": true
}
},
"transaction": {
"status": "DONE",
"merchantReportingCriteria": "YOURMERCHANTREPORTINGCRITERIA",
"merchantScanReference": "YOURSCANREFERENCE",
"customerId": "CUSTOMERID",
"source": "DOC_UPLOAD"
}
}
Call the RESTful HTTP GET API below to receive document related data of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data/document
If your customer account is in the EU data center, use retrieval.lon.netverify.com instead of retrieval.netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available, pending or deleted.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| status * | String | Possible states: • UPLOADED (default) • EXTRACTED if supported document for data extraction provided • DISCARDED if no supported document for data extraction provided |
|
| 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 the originally submitted document of the scan (PDF) if available |
| customDocumentCode | String | 100 | Your custom document code (maintained in your Jumio customer portal) if type = CUSTOM |
| extractedData | Object | Extracted data if supported document for data extraction provided, see table below |
| Parameter "extractedData" | Type | Max. Length | Description |
|---|---|---|---|
| signatureAvailable | String | "true" if signature available, otherwise "false" | |
| ssn | String | 255 | Social security number if readable |
| firstName | String | 255 | First name if readable |
| lastName | String | 255 | Last name if readable |
| swiftCode | String | 20 | BIC/SWIFT code |
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/document HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": "2015-08-14T09:05:47.394Z",
"status": "EXTRACTED",
"type": "SSC",
"country": "USA",
"extractedData": {
"firstName": "FIRSTNAME",
"lastName": "LASTNAME",
"ssn": "12341234",
"signatureAvailable": true
}
}
Call the RESTful HTTP GET API below to receive transaction related data of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/data/transaction
If your customer account is in the EU data center, use retrieval.lon.netverify.com instead of retrieval.netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You will receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available, pending or deleted.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| status * | String | Possible states: • DONE • FAILED |
|
| source * | String | Possible status: • DOC_API • DOC_UPLOAD |
|
| merchantReportingCriteria | String | 255 | Your reporting criteria for each scan |
| merchantScanReference | String | 255 | Your reference for each scan |
| customerId | String | 255 | ID of the customer |
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/data/transaction HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"scanReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": "2015-08-14T10:06:13.610Z",
"status": "DONE",
"merchantReportingCriteria": "YOURMERCHANTREPORTINGCRITERIA",
"merchantScanReference": "YOURSCANREFERENCE",
"customerId": "CUSTOMERID",
"source": "DOC_UPLOAD"
}
Call the RESTful HTTP GET API below to receive available images of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/pages
If your customer account is in the EU data center, use retrieval.lon.netverify.com instead of retrieval.netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
You will receive a JSON response in case of success, or HTTP status code 404 Not Found if the scan is not available, pending, deleted or of source Netverify Multi Document Legacy.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | 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 scan |
| images | JSON Array/Object | Available image/s see table below |
| Parameter "images" | Type | Description |
|---|---|---|
| classifier * | Integer | Page number specified when uploading the page |
| href * | String | REST URL to retrieve specific image (see Retrieving specific image section) |
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages HTTP/1.1
Accept: application/json
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
{
"timestamp": "2015-08-14T11:22:20.182Z",
"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"
}
Call the RESTful HTTP GET API below to receive a specific image of a scan by specifying the Jumio scan reference as a path parameter.
HTTP request method: GET
REST URL: https://retrieval.netverify.com/api/netverify/v2/documents/<scanReference>/pages/<page_number>
If your customer account is in the EU data center, use lon.netverify.com instead of netverify.com.
Note: Mandatory parameters are marked with an asterisk * and highlighted bold.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference (path parameter) * |
String | 36 | Jumio’s reference number of an existing scan from your account |
| page_number * | String | 36 | Page number specified when uploading the page |
You will receive a JPG or PNG image in case of success with the according header (e.g. Content-Type: image/jpeg), or HTTP status code 404 Not Found if the scan is not available, pending, deleted or not containing the specified image.
GET https://retrieval.netverify.com/api/netverify/v2/documents/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pages/1 HTTP/1.1
User-Agent: YOURCOMPANYNAME YOURAPPLICATIONNAME/x.x.x
Authorization: Basic
Jumio supported cipher suites during the TLS handshake.
© Jumio Corp. 268 Lambert Avenue, Palo Alto, CA 94306