Jumio Go - Callback
The callback is the authorative answer from Jumio. Specify a callback URL (see Configuring Settings in the Customer Portal) to automatically receive the result for each transaction.
Jumio callback IP list
These are the IPs which Jumio sends callbacks from. Whitelist these IPs and use them to verify that the callback was sent 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.
Callback for Jumio Go
An HTTP POST request is sent to your specified callback URL containing an application/x-www-form-urlencoded formatted string with the tranction 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, ID Verification API, and our SDK for Android and iOS.
For Android/iOS: ID Verification must be enabled to receive the callback.
Jumio Web Client
| 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 cleaned up after 15 minutes of no activity from the user. Callback: Verification status = NO_ID_UPLOADED |
| Drop off during second or third attempt | Done | Transaction will be finished after 15 minutes of no activity from the user. Callback: Verification status = ERROR_NOT_READABLE_ID with previous reject reason |
Jumio Mobile (Android/iOS)
| User journey state | Transaction state | Callback |
|---|---|---|
| Drop off | Pending → Failed | Transaction will be cleaned up from pending to failed after the authorization token lifetime expires. 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 | Possible states: APPROVED_VERIFIED, DENIED_FRAUD, DENIED_UNSUPPORTED_ID_TYPE1, DENIED_UNSUPPORTED_ID_COUNTRY1, ERROR_NOT_READABLE_ID, NO_ID_UPLOADED | ||
| idScanStatus | SUCCESS if verificationStatus = APPROVED_VERIFIED, otherwise ERROR | ||
| idScanSource | Possible values: WEB, WEB_CAM, WEB_UPLOAD, API, SDK | ||
| 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, otherwise N/A | ||
| 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 | Possible types: PASSPORT, DRIVING_LICENSE, ID_CARD | ||
| 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, e.g., XKX (Kosovo) | |
| rejectReason | Reject reason as JSON object if verificationStatus = DENIED_FRAUD or ERROR_NOT_READABLE_ID | See Reject Reason table below | |
| idScanImage | 255 | URL to retrieve the document image of transaction (JPEG or PNG) if available | |
| idScanImageFace | 255 | URL to retrieve the face image of transaction (JPEG or PNG) if available | |
| idScanImageBackside | 255 | URL to retrieve the document backside image of 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 | |
| idDob | 10 | Date of birth in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided | If idCountry = IND, date of birth can be incomplete (e.g., 1990-12-09, 1990-01-01, 1990-12-01, 1990-01-09) |
| 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 depend on idType and country | |
| personalNumber | 14 | Personal number of the document if available | |
| idAddress | Address as JSON object in US, EU, or 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 | Format: xxx.xxx.xxx.xxx | |
| firstAttempt | Timestamp (UTC) of the first transaction attempt | Format: YYYY-MM-DDThh:mm:ss.SSSZ | |
| presetCountry | 3 | Possible countries: ISO 3166-1 alpha-3 code | |
| presetIdType | Possible ID types: PASSPORT, DRIVING_LICENSE, ID_CARD | ||
| issuingDate | 10 | Issuing date of the document | Activation required |
| livenessImages | URLs to the liveness images of the transaction (JPEG or PNG) if available | ||
| facemap | 255 | URL to the facemap of the transaction, if available | Activation required |
| curp | 255 | CURP for Mexico if idCountry = MEX and idType/Pasport/ID_CARD/ELECTORAL_ID | Activation required |
| cpf | 255 | CPF number of the document | Activation required |
| registrationNumber | 255 | Registration number of the document | Activation required |
| personalIdentificationNumber | 255 | Personal identification number for specific countries | Activation required |
| rgNumber | 255 | “General Registration” number for Brazil | Activation required |
1 Transaction is declined as unsupported if the ID is not supported by Jumio Go, or not marked as accepted in your Customer Portal settings.
2 For ID types that are configured to support a seperate scan of the frontside and backside, there is a separate image of the frontside (idScanImage) and backside (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. The different address parameters are a part of the JSON object, if they are available on the ID.
4 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.
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 |
| Canada | No | Yes | No | Raw |
| France | Yes | No | No | Raw |
| United Kingdom | No | Yes | No | Raw |
| Indonesia | Yes | No | No | Raw |
| Ireland | No | Yes | No | Raw |
| Mexico | Yes | No | No | Raw |
| Malaysia | Yes | No | No | Raw |
| United States | Yes | Yes | No | Raw |
US address format
| Parameter | Max. Length | Description |
|---|---|---|
| city | 64 | City |
| stateCode | 6 | ISO 3166-2 state code |
| streetName | 64 | Street name |
| streetSuffix | 14 | Street suffix abbreviation (Examples: US, Canada, Australia) |
| streetDirection | 255 | Street direction abbreviation (Examples: US: E=EAST, W=WEST, N=NORTH, S=SOUTH; Canada, Australia) |
| streetNumber | 14 | Street number |
| unitDesignator | 14 | Unit designator abbreviation (Examples: US, Canada, Australia) |
| unitNumber | 14 | Unit number |
| zip | 14 | Zip code |
| zipExtension | 20 | Zip extension |
| country | 3 | Possible countries: ISO 3166-1 alpha-3 code, e.g., XKX (Kosovo) |
EU address format
| Parameter | Max. Length | Description |
|---|---|---|
| city | 64 | City |
| province | 64 | Province |
| streetName | 64 | Street name |
| streetNumber | 15 | Street number |
| unitDetails | 64 | Unit details |
| postalCode | 15 | Postal code |
| country | 3 | Possible countries: ISO 3166-1 alpha-3 country code, e.g., XKX (Kosovo) |
Raw Address Format (idAddress)
| 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, e.g., XKX (Kosovo) |
| postalCode | 15 | Postal code |
| city | 64 | City |
| subdivision | 100 | Subdivision (Region, State, Province, Emirate, Department, …) |
Upcoming Address format changes
On August 17, 2020 onwards, Jumio is going to streamline the EU and US format into a single Raw format. In addition to that, we will also be providing a new parameter called formattedAddress which will contain the entire address in a comma separated format.
| Original Format | Raw Address Format | Formatted Address |
|---|---|---|
| US Address Format | 150 N Alberny Dr APT. 7, New Mexico, US-AL 77358-5555, United States | |
| "streetNumber": "150", "streetDirection":"N", "streetName":"Alberny", "streetSuffix":"Dr", "unitDesignator":"APT", "unitNumber": "7" | "line1":"150 N Alberny Dr APT. 7" | |
| "city":"New Mexico" | "city":"New Mexico" | |
| "stateCode":"US-AL" | "subdivision":"US-AL" | |
| "zip":"77358", "zipExtension":"5555" | "postalCode":"77358-5555" | |
| "country":"USA" | "country":"USA" |
| Original Format | Raw Address Format | Formatted Address |
|---|---|---|
| EU Address Format | 180 Main Street ABC, Graz, Steiermark 2424, Austria | |
| "streetNumber":"180", "streetName":"Main Street", "unitDetails":"ABC" | "line1": "180 Main Street ABC" | |
| "city": "Graz" | "city": "Graz" | |
| "province": "Steiermark" | "subdivision": "Steiermark" | |
| "postalCode": "2424" | "postalCode": "2424" | |
| "country": "AUT" | "country": "AUT" |
Reject Reason
| Parameter | 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, 108 MRZ_CHECK_FAILED, 109 PUNCHED_DOCUMENTPossible 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, 206 MISSING_BACK |
| rejectReasonDetails | Object | Reject reason details as JSON array containing JSON objects if rejectReasonCode = 100 or 200, see table below |
Reject Reason Details
| Parameter | Type | Max. Length | Description |
|---|---|---|---|
| detailsCode | String | 5 | see below |
| detailsDescription | String | 32 | Possible codes and descriptions for rejectReasonCode = 100: 1002 DOCUMENT_NUMBERPossible codes and descriptions for rejectReasonCode = 200: 2001 BLURRED, 2002 BAD_QUALITY, 2006 GLARE |
Identity Verification
Required items appear in bold type.
| Parameter | 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
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%22country%22%3A%22USA%22%2C%22stateCode%22%3A%22US%2DOH%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: 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 | JSON array/object | URL to retrieve the face image of the transaction (JPEG or PNG) | |
| livenessImages | JSON array | URLs to the liveness images of the transaction (JPEG or PNG) | |
| 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
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.