Netverify Callback
The callback is the authoritative answer from Jumio. Specify a callback URL (for constraints see Configuring Settings in the Customer Portal) to automatically receive the result for each transaction.
Usage
Once Jumio has sent the callback, save it on your side and send us a response of 200 OK.
Any validation of the content should be done afterwards. In case you face any issues, please contact Jumio Technical Support at support@jumio.com with a sample.
Jumio Callback IP List
Whitelist these IP addresses for callbacks and use them to verify that the callback originated from Jumio.
US Data Center
34.202.241.227
34.226.103.119
34.226.254.127
52.52.51.178
52.53.95.123
54.67.101.173
Use the hostname: callback.jumio.com to look up the most current IP addresses.
EU Data Center
34.253.41.236
35.157.27.193
52.48.0.25
52.57.194.92
52.58.113.86
52.209.180.134
Use the hostname: callback.lon.jumio.com
SGP Data Center
3.0.109.121
52.76.184.73
52.77.102.92
Use the hostname: callback.core-sgp.jumio.com
Callback for ID Verification
An HTTP POST request is sent to your specified callback URL containing an application/x-www-form-urlencoded formatted string with the transaction result.
To specify a global callback URL in the Customer Portal, see Configuring Settings in the Customer Portal.
A callback URL can also be specified per transaction. See instructions for ID Verification Web v4, performNetverify, and our SDK for Android and iOS.
For Android/iOS: ID verification must be enabled to receive the callback.
Parameters
Required items appear in bold type.
ID Verification Web
| User Journey State | Transaction State | Callback |
|---|---|---|
| Not started | Pending => Failed | Transaction will be cleaned-up from pending to failed after the authorization token lifetime expires. Callback: Verification status NO_ID_UPLOADED |
| Drop off during first attempt | Pending => Failed | Transaction will be finished 15 minutes after the last update. Callback: Verification status NO_ID_UPLOADED |
| Drop off during second or third attempt | Done | Transaction will be finished 15 minutes after the last update. Callback: Verification status ERROR_NOT_READABLE_ID with previous reject reason |
| Finished | Done | Callback: Verification status depends on the result |
ID Verification Mobile (Android/iOS)
| User Journey State | Transaction State | Callback |
|---|---|---|
| Drop off | Pending => Failed | Transaction will be cleaned-up from pending to failed 15 minutes after the last update. Callback: Verification status NO_ID_UPLOADED |
| Finished | Done | ID verification will be performed. Callback: Verification status depends on the result (see table below) |
Parameters
The following parameters are posted to your callback URL for ID Verification Web, ID Verification API and ID Verification Mobile iOS/Android.
Required items appear in bold type.
| Parameter | Max. Length | Description | Notes |
|---|---|---|---|
| callBackType | NETVERIFYID | ||
| jumioIdScanReference | 36 | Jumio’s reference number for each transaction | |
| verificationStatus |
| ||
| idScanStatus | SUCCESS if verificationStatus = APPROVED_VERIFIED, otherwise ERROR | ||
| idScanSource |
| ||
| idCheckDataPositions | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A | ||
| idCheckDocumentValidation | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A | ||
| idCheckHologram | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A | ||
| idCheckMRZcode | OK for passports and supported ID cards if verificationStatus = APPROVED_VERIFIED and MRZ check is enabled otherwise N/A | not returned for DEU, HKG, JPN, NLD, SGP, KOR if NV masking is enabled | |
| idCheckMicroprint | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A | ||
| idCheckSecurityFeatures | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A | ||
| idCheckSignature | OK if verificationStatus = APPROVED_VERIFIED otherwise N/A | ||
| transactionDate | Timestamp (UTC) of the transaction creation format: YYYY-MM-DDThh:mm:ss.SSSZ | ||
| callbackDate | Timestamp (UTC) of the callback creation format: YYYY-MM-DDThh:mm:ss.SSSZ | ||
| identityVerification | Identity verification as JSON object, ONLY if verificationStatus = APPROVED_VERIFIED | activation required | |
| idType |
| ||
| idSubtype | 255 | Possible subtypes if idType = ID_CARD:
| |
| idCountry | 3 |
| |
| rejectReason | Reject reason as JSON object if verificationStatus = DENIED_FRAUD or ERROR_NOT_READABLE_ID | ||
| idScanImage | 255 | URL to retrieve the image of the transaction (JPEG or PNG) if available | |
| idScanImageFace | 255 | URL to retrieve the face image of the transaction (JPEG or PNG) if available | |
| idScanImageBackside | 255 | URL to retrieve the back side image of the transaction (JPEG or PNG) if available | |
| idNumber | 200 | Identification number of the document as available on the ID if enabled, otherwise if provided | |
| idFirstName | 200 | First name of the customer as available on the ID if enabled, otherwise if provided | |
| idLastName | 200 | Last name of the customer as available on the ID if enabled, otherwise if provided | activation required for Chinese name extraction |
| idDob | 10 | Date of birth in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided | |
| idExpiry | 10 | Date of expiry in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided | |
| idUsState | 255 | See ISO 3166-2 codes or free text if not mapped | |
| personalNumber | 14 | Personal number of the document if idType = PASSPORT and if data available on the document | |
| idAddress | Address as JSON object in RAW format | activation required | |
| merchantIdScanReference | 100 | Your reference for each transaction | |
| merchantReportingCriteria | 100 | Your reporting criteria for each transaction | |
| customerId | 100 | ID of the customer as provided | |
| clientIp | IP address of the client in the format xxx.xxx.xxx.xxx | ||
| firstAttemptDate | Timestamp (UTC) of the first transaction attempt format: YYYY-MM-DDThh:mm:ss.SSSZ | ||
| optionalData1 | 255 | Optional field of MRZ line 1 | |
| optionalData2 | 255 | Optional field of MRZ line 2 | |
| gender | 2 |
| activation required |
| presetCountry | 3 |
| |
| presetIdType |
| ||
| dlCarPermission | 255 |
| activation required |
| nationality | 3 | ISO 3166-1 alpha-3 country code (if MRZ contains nationality) | activation required |
| passportNumber | 255 | Passport number if idType = VISA and additional extraction enabled | activation required |
| issuingAuthority | 50 | Issuing authority of the document | activation required |
| issuingDate | 10 | Issuing date of the document | activation required |
| issuingPlace | 50 | Issuing place of the document | activation required |
| livenessImages | URLs to the liveness images of the transaction | ||
| facemap | 255 | URL to the facemap of the transaction if available | activation required |
| taxNumber | 255 | Tax number of the document | activation required |
| cpf | 255 | CPF number of the document | activation required |
| registrationNumber | 255 | Registration number of the document | activation required |
| mothersName | 255 | Name of the document holder's mother | activation required |
| fathersName | 255 | Name of the document holder's father | activation required |
| rgNumber | 255 | "General Registration" number for idCountry = BRA | activation required |
| voterIdNumber | 255 | "Clave de elector" number for idCountry = MEX | activation required |
| issuingNumber | 255 | "Numero de emission" number for idCountry = MEX | activation required |
| residentPermitType | Permit type related to "Golden Visas" if idCountry = GBR | activation required | |
| residentPermitRemarks | Permit type related to "Golden Visas" if idCountry = GBR | activation required | |
| disability |
| activation required |
1 Transaction is declined as unsupported if the ID is not supported by Jumio, or not marked as accepted in your customer portal settings. 2 For ID types that are configured to support a separate scan of the front side and back side, there is a separate image of the front side (idScanImage) and the back side (idScanImageBackside). If Identity Verification is enabled, there is also a picture of the face (idScanImageFace). 3 Address recognition is performed for supported IDs, if enabled. Please check Supported documents for Address Extraction to see which supported documents. The address parameters are a part of the JSON object, if they are available on the ID. 4 Fields containing certain kinds of personally identifying information are not returned if NV masking is enabled for the Netherlands, Germany, or South Korea. See ID Verification masking for more information. 5 Liveness images are returned only for transactions containing Identity Verification submitted via the Android and iOS SDKs. The number of images can vary and may not be returned in chronological order. 6 If one of the values such as "day" is not included in the document it will also not be returned in the object.
Retrieving images
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.
- Accept: image/jpeg, image/png
- 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.
Timestamp format
Timestamp are sent in format: YYYY-MM-DDThh:mm:ss.SSSZ with constraint that SSS (milliseconds) can either be
- Not included: YYYY-MM-DDThh:mm:ssZ
- 1 digit: YYYY-MM-DDThh:mm:ss.SZ
- 2 digits: YYYY-MM-DDThh:mm:ss.SSZ
- 3 digits: YYYY-MM-DDThh:mm:ss.SSSZ We encourage to use a standard library to convert the timestamp received from Jumio as the timeformat is valid with and without the SSS milliseconds.
Supported documents for address extraction
| Country | ID Card | Driving License | Passport | Callback Format |
|---|---|---|---|---|
| Australia | No | Yes | No | RAW |
| Bahrain | No | Yes | No | RAW |
| Canada | No | Yes | No | RAW |
| France | Yes | Yes | Yes | RAW |
| Germany | Yes | No | No | RAW |
| India | Yes | No | No | RAW |
| Indonesia | Yes | No | No | RAW |
| Ireland | No | Yes | No | RAW |
| Malaysia | Yes | No | No | RAW |
| Malta | Yes | Yes | No | RAW |
| Mexico | Yes | No | No | RAW |
| Peru | Yes | Yes | No | RAW |
| Romania | Yes | No | No | RAW |
| Singapore | Yes | No | No | RAW |
| Spain | Yes | No | No | RAW |
| United Kingdom | No | Yes | No | RAW |
| United States | Yes | Yes | No | RAW |
| Italy | Yes | Yes | Yes | RAW |
RAW address format
idAddress Object
| Parameter | Max. Length | Description |
|---|---|---|
| line1 | 100 | Line item 1 |
| line2 | 100 | Line item 2 |
| line3 | 100 | Line item 3 |
| line4 | 100 | Line item 4 |
| line5 | 100 | Line item 5 |
| country | 3 | Possible countries: • ISO 3166-1 alpha-3 country code • XKX (Kosovo) |
| postalCode | 15 | Postal code |
| city | 64 | City |
| subdivision | 100 | Subdivision (Region, State, Province, Emirate, Department, ...) |
| formattedAddress | Complete address in a formatted way |
Reject reason
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| rejectReasonCode | String | 5 | Code indicating why the verification was rejected. Possible values: see detailed codes below. |
| rejectReasonDescription | String | 64 | Human-readable description of the reject reason. Grouped by verificationStatus: DENIED_FRAUD: 100 MANIPULATED_DOCUMENT, 105 FRAUDSTER, 106 FAKE, 107 PHOTO_MISMATCH, 108 MRZ_CHECK_FAILED, 109 PUNCHED_DOCUMENT, 110 CHIP_DATA_MANIPULATED (ePassport only), 111 MISMATCH_PRINTED_BARCODE_DATA, 112 CHIP_MISSING, 113 MISMATCHING_DATA_REPEATED_FACE, 114 DIGITAL_MANIPULATION, 115 MISMATCH_HRZ_MRZ_DATA, 118 MISMATCH_FRONT_BACK 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 (multiple people in one image), 213 INVALID_WATERMARK, 214 MISSING_FRONT, 300 MANUAL_REJECTION |
| rejectReasonDetails | JSON object / JSON array | — | Additional details about the reject reason. Returns a JSON object if only one reason applies, or a JSON array of objects if multiple reasons exist (e.g., rejectReasonCode = 100 or 200). See table below for structure. |
1activation required
Reject reason details
| Parameter (rejectReasonDetails) | Type | Max. Length | Description |
|---|---|---|---|
| detailsCode | String | 5 | Code indicating the specific reason detail. Possible values: see below. |
| detailsDescription | String | 32 | Human-readable description of the detail. Grouped by 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, 10012 GENDER, 10013 DATE_OF_ISSUE 200: 2001 BLURRED, 2002 BAD_QUALITY, 2003 MISSING_PART_DOCUMENT, 2004 HIDDEN_PART_DOCUMENT, 2005 DAMAGED_DOCUMENT, 2006 GLARE, 2007 MISSING_MANDATORY_DATAPOINTS |
Identity Verification
Required items appear in bold type.
| Parameter (identityVerification) | Max. Length | Description |
|---|---|---|
| similarity | 1 | Possible values: MATCH, NO_MATCH, NOT_POSSIBLE (not executed or bad quality of face on document) |
| validity | 2 | 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 |
1 Is the person on the selfie the same as the one on the document? 2 Is it a live person? 3 Potential reasons LIVENESS_FAILED:
- User tries to spoof the system
- User does not want to show his face at all but wants to complete the onboarding
- User does not look straight into the camera
- User does not finish the the Identity Verification process
- User has bad lighting conditions (too dark, too bright, reflections on face, not enough contrast, …)
- User is covering (parts) of his face with a scarf, hat, or something similar
- User is not able to align his face with the oval
- A different person is performing the Identity Verification in the second step than in the first one
Driver License Categories
Required items appear in bold type.
| Parameter(dlCategories) | Max. Length | Description |
|---|---|---|
| category | 10 | String in Latin or Traditional Chinese characters |
| issueDate | Issue date in the format YYYY-MM-DD | |
| expiryDate | Date of expiry in the format YYYY-MM-DD as available on the driver license | |
| isReadable | Possible value:
| |
| availability | Possible values:
|
ID Verification Masking
Extracting certain sensitive information from identity documents in the Netherlands, Germany, and South Korea is prohibited by law for customers with a business presence in those countries. These customers can elect to enable ID Verification masking to protect this sensitive data.
When masking is enabled for these countries, certain fields cannot be extracted and returned in the callback. The information contained in these fields is masked before the user's image is stored.
| Country | Document | Affected parameters (not returned in the callback) |
|---|---|---|
| Denmark | Passport | personalNumber |
| Germany | Passport | idCheckMRZcode, idNumber |
| Germany | ID card | idCheckMRZcode, idNumber |
| Hong Kong | Passport | idCheckMRZcode, idNumber |
| Hong Kong | ID card | idNumber |
| Japan | ID card | idNumber |
| Netherlands | Passport | idCheckMRZcode, personalNumber |
| Netherlands | ID card | idCheckMRZcode, personalNumber |
| Netherlands | Driver license | image is masked, no extracted data fields are affected |
| Singapore | Passport | idCheckMRZcode, idNumber |
| Singapore | Driver license | idNumber |
| Singapore | ID card | idNumber |
| South Korea | Passport | idCheckMRZcode, personalNumber |
| South Korea | ID card | idNumber |
| South Korea | Driver license | idNumber |
Sample Callbacks
Sample callback (URL-encoded POST): Approved and verified
idExpiry=2022-12-31&idType=PASSPORT&idDob=1990-01-01&idCheckSignature=OK&idCheckDataPositions=OK&idCheckHologram=OK&idCheckMicroprint=OK&idCheckDocumentValidation=OK&idCountry=USA&idScanSource=SDK&idFirstName=FIRSTNAME&verificationStatus=APPROVED_VERIFIED&jumioIdScanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&personalNumber=N%2FA&merchantIdScanReference=YOURIDSCANREFERENCE&idCheckSecurityFeatures=OK&idCheckMRZcode=OK&idScanImage=https%3A%2F%2Fnetverify.com%2Frecognition%2Fv1%2Fidscan%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Ffront&callBackType=NETVERIFYID&clientIp=xxx.xxx.xxx.xxx&idLastName=LASTNAME&idAddress=%7B%22city%22%3A%22MIAMI%22%2C%22country%22%3A%22USA%22%2C%22formattedAddress%22%3A%22414+SOUTHWEST+AVE%2C+MIAMI%2C+FL%2C+33184%2C+USA%22%2C%22line1%22%3A%22414+SOUTHWEST+AVE%22%2C%22postalCode%22%3A%2233184%22%2C%22subdivision%22%3A%22FL%22%7D&idScanStatus=SUCCESS&identityVerification=%7B%22similarity%22%3A%22MATCH%22%2C%22validity%22%3Atrue%7D&idNumber=P1234
Sample callback (URL-encoded POST): Fraud
idType=PASSPORT&idCheckSignature=N%2FA&rejectReason=%7B%20%22rejectReasonCode%22%3A%22100%22%2C%20%22rejectReasonDescription%22%3A%22MANIPULATED_DOCUMENT%22%2C%20%22rejectReasonDetails%22%3A%20%5B%7B%20%22detailsCode%22%3A%20%221001%22%2C%20%22detailsDescription%22%3A%20%22PHOTO%22%20%7D%2C%7B%20%22detailsCode%22%3A%20%221004%22%2C%20%22detailsDescription%22%3A%20%22DOB%22%20%7D%5D%7D&idCheckDataPositions=N%2FA&idCheckHologram=N%2FA&idCheckMicroprint=N%2FA&idCheckDocumentValidation=N%2FA&idCountry=USA&idScanSource=SDK&verificationStatus=DENIED_FRAUD&jumioIdScanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&merchantIdScanReference=YOURSCANREFERENCE&idCheckSecurityFeatures=N%2FA&idCheckMRZcode=N%2FA&idScanImage=https%3A%2F%2Fnetverify.com%2Frecognition%2Fv1%2Fidscan%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Ffront&callBackType=NETVERIFYID&clientIp=xxx.xxx.xxx.xxx&idScanStatus=ERROR
Callback for Authentication
An HTTP POST request is sent to your specified callback URL containing an application/x-www-form-urlencoded formatted string with the transaction result.
To specify a global callback URL in the Customer Portal, see Configuring Settings in the Customer Portal.
A callback URL can also be specified per transaction in our Android and iOS SDK
Parameters
Required items appear in bold type.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| callbackDate | string | Timestamp of the callback in the format: YYYY-MM-DDThh:mm:ss.SSSZ | |
| 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:
| |
| transactionDate | string | Timestamp of the transaction in the format: YYYY-MM-DDThh:mm:ss.SSSZ | |
| scanSource | string | Possible values:
| |
| callBackType | string | NETVERIFY_AUTHENTICATION | |
| idScanImageFace | string | URL to retrieve the face image of the transaction (JPEG or PNG) 1 | |
| livenessImages | JSON array | URLs to the liveness images of the transaction (JPEG or PNG) 1,2 | |
| userReference | string | Your internal reference for the user |
1 Retrieve the images of the transaction. 2 The number of images can vary and may not be returned in chronological order.
Retrieving Images
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.
- Accept: image/jpeg, image/png
- 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.
Timestamp format
Timestamp are sent in format: YYYY-MM-DDThh:mm:ss.SSSZ with constraint that SSS (milliseconds) can either be
- Not included: YYYY-MM-DDThh:mm:ssZ
- 1 digit: YYYY-MM-DDThh:mm:ss.SZ
- 2 digits: YYYY-MM-DDThh:mm:ss.SSZ
- 3 digits: YYYY-MM-DDThh:mm:ss.SSSZ We encourage to use a standard library to convert the timestamp received from Jumio as the timeformat is valid with and without the SSS milliseconds.
Sample Callback
Sample callback (URL-encoded POST): Passed
scanSource=SDK&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&enrollmentTransactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callBackType=NETVERIFY_AUTHENTICATION&livenessImages=%5B%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F1%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F2%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F3%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F4%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F5%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F6%22%2C%22https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fliveness%2F7%22%5D&idScanImageFace=https%3A%2F%2Fnetverify.com%2Fapi%2Fnetverify%2Fv2%2Fauthentications%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fimages%2Fface&callbackDate=2019-05-30T08%3A37%3A35.822Z&transactionDate=2019-05-29T08%3A37%3A24.344Z&transactionResult=PASSED
Callback for Document Verification
Parameters
The following parameters are posted to your callback URL for Document Verification and Document Verification API.
Required items appear in bold type.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| scanReference | String | 36 | Jumio's reference number for each transaction |
| timestamp | String | Timestamp (UTC) of the response in the format: YYYY-MM-DDThh:mm:ss.SSSZ | |
| transaction | JSON object | Transaction related data, see table below | |
| document | JSON object | Document related data, see table below |
Transaction
Required items appear in bold type.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| date | String | Timestamp (UTC) of the transaction creation, format: YYYY-MM-DDThh:mm:ss.SSSZ | |
| status | String | Possible states:
| |
| source | String | Possible values:
| |
| merchantScanReference | String | 255 | Your reference for each transaction |
| customerId | String | 255 | ID of the customer |
| merchantReportingCriteria | String | 255 | Your reporting criteria for each transaction |
| clientIp | String | 100 | IP address of the client if provided for the Document Verification API |
Document
Required items appear in bold type.
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| status | String | Possible states:
| |
| country | String | 3 | Possible countries:
|
| type | String | Possible types:
| |
| images | JSON array | URLs to the images of the transaction (JPEG or PNG) 3 | |
| originalDocument | String | URL to the originally submitted document of the transaction (PDF) if available 3 | |
| customDocumentCode | String | 100 | Your custom document code (maintained in your Jumio customer portal) if type = CUSTOM |
| extractedData | JSON object | Extracted data if status = EXTRACTED, see Supported documents for Data Extraction |
1 This also applies for document type CCS where no masking was needed as no full PAN is displayed. 2 If masking has been done, status will be always EXTRACTED as well. This applies to all documents uploaded with type CC, as well as to documents uploaded with type CCS where a ful PAN is displayed. 3 Retrieve the images of the transaction.
Retrieving Images
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.
- Accept: image/jpeg, image/png
- 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.
Timestamp format
Timestamp are sent in format: YYYY-MM-DDThh:mm:ss.SSSZ with constraint that SSS (milliseconds) can either be:
Not included: YYYY-MM-DDThh:mm:ssZ 1 digit: YYYY-MM-DDThh:mm:ss.SZ 2 digits: YYYY-MM-DDThh:mm:ss.SSZ 3 digits: YYYY-MM-DDThh:mm:ss.SSSZ We encourage to use a standard library to convert the timestamp received from Jumio as the timeformat is valid with and without the SSS milliseconds.
Extracted Data
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| firstName | String | 255 | First name if readable |
| lastName | String | 255 | Last name if readable |
| name | String | 100 | Full name if readable |
| accountNumber | String | 34 | Bank account number of the customer from a bank statement |
| pan | String | 20 | Personal account number of credit card |
| issueDate | String | Issue date in the format YYYY-MM-DD | |
| expiryDate | String | Date of expiry in the format YYYY-MM-DD | |
| ssn | String | 255 | Social security number if readable |
| signatureAvailable | String | true if signature available, otherwise false | |
| swiftCode | String | 20 | BIC/SWIFT code |
| address | JSON object | Address as JSON object in RAW format if status = EXTRACTED, see table below |
RAW address format
| Parameter | Max. Length | Description |
|---|---|---|
| line1 | 100 | Line item 1 |
| line2 | 100 | Line item 2 |
| line3 | 100 | Line item 3 |
| line4 | 100 | Line item 4 |
| line5 | 100 | Line item 5 |
| countryCode | 3 | Possible countries of residence:
|
| postalCode | 15 | Postal code |
| city | 64 | City |
| subdivision | 50 | Name of subdivision |
| formattedAddress | Complete address in a formatted way |
Supported documents for data extraction
The following data points will be extracted for all documents printed in a Latin-script character set, provided that a minimum of one of these data points are available for extraction. If the document does not meet these extraction criteria, only the document image will be saved — no data extraction will be performed.
| Type | Extracted data |
|---|---|
| BS (bank statement) |
|
| UB (utility bill) |
|
| CCS (credit card statement) |
|
| OTHER (Other document type) |
|
| CC (credit card) 1,3 |
|
| SSC (Social Security card) 1,2 |
|
1 For CC and SSC all data points need to be available for extraction. 2 USA only. 3 For CC date extraction format is MM/YY
Sample Callbacks
Sample callback (URL-encoded POST): UPLOADED
timestamp=2017-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22AUT%22%2C%22images%22%3A%5B%22https%3A%2F%2Fretrieval.netverify.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22UPLOADED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3A%222014-10-17T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22DONE%22%7D
Sample callback (URL-encoded POST): EXTRACTED
timestamp=2017-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22USA%22%2C%22extractedData%22%3A%7B%22firstName%22%3A%22FIRSTNAME%22%2C%22lastName%22%3A%22LASTNAME%22%2C%22signatureAvailable%22%3Atrue%2C%22ssn%22%3A%22xxxxxxxxx%22%7D%2C%22images%22%3A%5B%22https%3A%2F%2Fretrieval.netverify.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22EXTRACTED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3A%222014-10-17T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22DONE%22%7D
Sample callback (URL-encoded POST): DISCARDED
timestamp=2017-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22USA%22%2C%22images%22%3A%5B%22https%3A%2F%2Fretrieval.netverify.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22DISCARDED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3A%222014-10-17T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22DONE%22%7D
ID Verification Retrieval API
If your server was not able to receive or process the callback, you can use the Retrieval API to retrieve the results of your transaction.