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.
Information about changes to features and improvements documented in each release is available in our Revision history.
- Usage
- Jumio Callback IP List
- Callback for ID Verification
- Callback for Authentication
- Callback for Document Verification
- ID Verification Retrieval API
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 [email protected] with a sample.
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 to look up the most current IP addresses.
SGP data center:
3.0.109.121
52.76.184.73
52.77.102.92
Use the hostname callback.core-sgp.jumio.com to look up the most current IP addresses.
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.
| 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 attept | 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 |
| User journey state | transaction state | Callback |
|---|---|---|
| Drop off | Pending => Failed | Transaction will be cleaned-up from pending to failed 15 minutes after 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) |
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 | Possible states: • APPROVED_VERIFIED • DENIED_FRAUD • DENIED_UNSUPPORTED_ID_TYPE 1 • DENIED_UNSUPPORTED_ID_COUNTRY 1 • ERROR_NOT_READABLE_ID • NO_ID_UPLOADED |
||
| idScanStatus | SUCCESS if verificationStatus = APPROVED_VERIFIED, otherwise ERROR | ||
| idScanSource | Possible values: • WEB ( NVW4 before capture method is selected) • WEB_CAM ( NVW4 with camera capture) • WEB_UPLOAD ( NVW4 with file upload) • API (performNetverify) • SDK (mobile) |
||
| 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 4 | |
| 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 see table Identity Verification below |
activation required | |
| idType | Possible types: • PASSPORT • DRIVING_LICENSE • ID_CARD • VISA Currently, Jumio only supports US and China visas in certain cases. Visas from other countries will be rejected as unsupported with idType = VISA |
||
| idSubtype | 255 | Possible subtypes if idType = 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) |
|
| idCountry | 3 | Possible countries: • ISO 3166-1 alpha-3 country code • XKX (Kosovo) |
|
| rejectReason | Reject reason as JSON object if verificationStatus = DENIED_FRAUD or ERROR_NOT_READABLE_ID, see tables below | ||
| idScanImage | 255 | URL to retrieve the image of the transaction (JPEG or PNG) if available 2 | |
| idScanImageFace | 255 | URL to retrieve the face image of the transaction (JPEG or PNG) if available 2 | |
| idScanImageBackside | 255 | URL to retrieve the back side image of the transaction (JPEG or PNG) if available 2 | |
| 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 • For following documents, N/A returned (if name contains non-Latin characters)- if idCountry = CHN and idType = DRIVING_LICENSE or ID_CARD - if idCountry = KOR and idType = DRIVING_LICENSE or ID_CARD - if idCountry = JPN and idType = DRIVING_LICENSE - if idCountry = RUS and idType = ID_CARD |
|
| idLastName | 200 | • Last name of the customer as available on the ID if enabled, otherwise if provided • For following documents, Chinese name as printed on the document returned (if enabled) - if idCountry = CHN and idType = DRIVING_LICENSE or ID_CARD (first name and last name) • Only if full name is printed in Latin characters - if idCountry = KOR and idType = DRIVING_LICENSE (first name and last name) • For following documents, N/A returned (if name contains non-Latin characters) - if idCountry = CHN and idType = DRIVING_LICENSE or ID_CARD - if idCountry = KOR and idType = DRIVING_LICENSE or ID_CARD - if idCountry = JPN and idType = DRIVING_LICENSE - if idCountry = RUS and idType = ID_CARD |
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 If idCountry = HKG, IND date of birth can be incomplete, possible values e.g.: • Year-Month-Day: 1990-12-09 • Year only: 1990-01-01 • Year-Month: 1990-12-01 • Year-Day: 1990-01-09 Additional parameter originDob will be provided |
not returned for KOR if NV masking is enabled 4 |
| idExpiry | 10 | Date of expiry in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided | |
| idUsState | 255 | Possible values if idType = PASSPORT or ID_CARD: • 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 If idType = DRIVING_LICENSE: • 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 |
|
| personalNumber | 14 | Personal number of the document • if idType = PASSPORT and if data available on the document | not returned for NLD, DEU, KOR if NV masking is enabled 4 |
| idAddress | Address as JSON object in RAW format, see tables below 3 | 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 | not returned for NLD ID if NV masking is enabled 4 |
| optionalData2 | 255 | Optional field of MRZ line 2 | |
| dni | 255 | DNI as available on the ID if idCountry = ESP and idSubtype = NATIONAL_ID | |
| curp | 255 | CURP is available if idCountry = MEX and idType = PASSPORT, DRIVING_LICENSE, or ID_CARD and idSubtype = ELECTORAL_ID | activation required |
| gender | 2 | Possible values: M, F • if idCountry = FRA, HKG and idSubtype = NATIONAL_ID (MRZ type CNIS) • if idCountry = BHR, SGP and idType = PASSPORT, ID_CARD, DRIVING_LICENSE • if idCountry = CHL and idType = ID_CARD • if idCountry = PHL and idType = DRIVING_LICENSE • if idCountry = PER and idType = PASSPORT, ID_CARD • if idType = VISA and additional extraction for Visa enabled • if readable: best effort |
activation required |
| presetCountry | 3 | Possible countries: • ISO 3166-1 alpha-3 country code • XKX (Kosovo) |
|
| presetIdType | Possible ID types: PASSPORT, DRIVING_LICENSE, ID_CARD | ||
| dlCarPermission | 255 | Only available if: •Extraction supported for specific country •verificationStatus = APPROVED_VERIFIED Possible values: • YES • NO • NOT_READABLE Currently, we support car permission extraction for the following countries: • Austria •Belarus •Belgium •Bulgaria •Croatia •Czech Republic •Denmark •Estonia •Finland •France •Germany •Gibraltar •Guernsey •Greece •Hungary •Iceland •Ireland •Isle of Man •Italy •Jersey •Latvia •Liechtenstein •Lithuania •Luxembourg •Macedonia •Malta •Moldova •Republic of Montenegro •Netherlands •Norway •Poland •Portugal •Romania •Russian Federation •Serbia •Slovakia •Slovenia •Spain •Sweden •Switzerland •Ukraine •United Kingdom •Taiwan (For Taiwan date is not extracted however it is given as mentioned below) DL categories: - category:大型重型機車 - availability:no - category:普通重型機車 - availability:yes |
activation required |
| dlCategories | JSON object | Driver license categories as JSON object, see table below Supported countries: • Austria • Belgium • Bulgaria • France • Germany • Great Britain • Italy • Latvia • Lithuania • Netherlands • Romania • Spain • Taiwan |
activation required |
| nationality | 3 | Possible values: • ISO 3166-1 alpha-3 country code (if MRZ contains nationality) |
activation required |
| passportNumber | 255 | Passport number if idType = VISA and additional extraction for Visa enabled | activation required |
| durationOfStay | 255 | Duration of stay if idType = VISA and additional extraction for Visa enabled | activation required |
| numberOfEntries | 255 | Number of entries if idType = VISA and additional extraction for Visa enabled | activation required |
| visaCategory | 255 | Visa category if idType = VISA and additional extraction for Visa enabled | activation required |
| originDob | 10 | Original format of date of birth if idCountry = IND Possible values e.g.: • Year/Month/Day: 1990/12/09 • Year only: 1990// • Year/Month: 1990/12/ • Year/Day: 1990//09 |
|
| issuingAuthority | 50 | Issuing authority of the document (if issuing authority extraction is enabled) • if idCountry = ITA |
activation required |
| issuingDate | 10 | Issuing date of the document (if issuing date extraction enabled) | activation required |
| issuingPlace | 50 | Issuing place of the document (if issuing place extraction is enabled) • if idCountry = COL, ITA |
activation required |
| livenessImages | URLs to the liveness images of the transaction (JPEG or PNG) if available 5 | ||
| placeOfBirth | 256 | Place of birth of document holder • if idCountry = AFG, AGO, AIA, ALB, AND, ARE, ARM, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BFA, BGD, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BWA, CAF, CAN, DEU, ESP, FRA, GBR, HKG, HUN, IDN, IND, IRL, ITA, NGA, NLD, PAK, PHL, POL, PRT, ROU, SGP, RUS, TUR, UKR, USA |
activation required |
| facemap | 255 | URL to the facemap of the transaction if available | activation required |
| taxNumber | 255 | Tax number of the document • if idCountry = ITA and idType = HEALTH_ID or TAX_ID |
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 |
| personalIdentificationNumber | 255 | Personal identification number as available on the ID • if idCountry = GEO and idSubtype = PASSPORT • if idCountry = COL and idSubtype = ID_CARD • if idCountry = LTU and idSubtype = DRIVING_LICENSE • if idCountry = TUR and idSubtype = ID_CARD, DRIVING_LICENSE • if idCountry = ROU and idSubtype = ID_CARD, DRIVING_LICENSE • if idCountry = ISR and idSubtype = DRIVING_LICENSE |
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 |
| expiryDateParts | Object containing the expiry date information (year, month, day) from the corresponding fields on the document 6 Example: {"year": "2022", "month": "08", "day": "31"} |
||
| dateOfBirthParts | Object containing the date of birth information (year, month, day) from the corresponding fields on the document 6 Example: {"year": "2022", "month": "08", "day": "31"} |
||
| issuingDateParts | Object containing the issuing date information (year, month, day) from the corresponding fields on the document 6 Example: {"year": "2022", "month": "08", "day": "31"} |
object containing the date information (year, month, day) from the corresponding fields on the document.
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. For examples and additional details, refer to our Knowledge Base.
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/pngUser-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 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.
| 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 |
Parameter idAddress |
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 |
Parameter rejectReason |
Type | Max. Length | Description |
|---|---|---|---|
| rejectReasonCode | String | 5 | see below |
| rejectReasonDescription | String | 64 | 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 (documents of multiple people in one image) 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 |
Type | Max. Length | Description |
|---|---|---|---|
| detailsCode | String | 5 | see below |
| detailsDescription | String | 32 | Possible codes and descriptions 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 descriptions 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 |
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 3 |
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
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: • FALSE |
|
| availability | Possible values: • yes • no • not readable |
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) |
|---|---|---|
| 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 |
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
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
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.
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: • PASSED • FAILED • INVALID • EXPIRED |
|
| transactionDate | string | Timestamp of the transaction in the format: YYYY-MM-DDThh:mm:ss.SSSZ |
|
| scanSource | string | Possible values: • SDK • WEB |
|
| 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.
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/pngUser-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 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.
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
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 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 |
Required items appear in bold type.
Parameter transaction |
Type | Max. Length | Description |
|---|---|---|---|
| date | String | Timestamp (UTC) of the transaction creation format: YYYY-MM-DDThh:mm:ss.SSSZ |
|
| status | String | Possible states: • DONE • FAILED (if initialized acquisition is not successfully finalized within 15 minutes after creation/last update) |
|
| source | String | Possible values: • DOC_UPLOAD (Document Verification) • DOC_API (Document Verification API) • DOC_SDK (Document Verification Mobile) |
|
| 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 |
Required items appear in bold type.
Parameter document |
Type | Max. Length | Description |
|---|---|---|---|
| status | String | Possible states: ⦁ UPLOADED (default) 1 ⦁ EXTRACTED if supported document for data extraction provided 2 ⦁ DISCARDED if no supported document for data extraction provided |
|
| country | String | 3 | Possible countries: ⦁ ISO 3166-1 alpha-3 country code ⦁ XKX (Kosovo) |
| 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) |
|
| 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.
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/pngUser-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 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.
Parameter extractedData |
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 |
Parameter address |
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: • ISO 3166-1 alpha-3 country code • XKX (Kosovo) |
| postalCode | 15 | Postal code |
| city | 64 | City |
| subdivision | 50 | Name of subdivision |
| formattedAddress | Complete address in a formatted way |
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) | name, issueDate, address, accountNumber, swiftCode |
| UB (utility bill) | name, issueDate, address, dueDate |
| CCS (credit card statement) | name, issueDate, address, cardNumberLastFourDigits |
| OTHER (Other document type) | name, issueDate, address |
| CC (credit card) 1 | name, pan, expiryDate (currently returned as issueDate) |
| SSC (Social Security card) 1,2 | firstName, lastName, ssn, signatureAvailable |
1 For CC and SSC all data points need to be available for extraction.
2 USA only.
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
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
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
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.
© Jumio Corporation, 395 Page Mill Road, Suite 150 Palo Alto, CA 94306