This is a reference manual and configuration guide for the Jumio KYX Platform. It describes how to create an account, how to acquire the data by using different channels, and how to retrieve the extracted information.
ℹ️ Some functionalities described in this document might be unavailable, depending on the scope of your license with Jumio. Contact your Jumio Solutions Engineer if you have any questions.
API calls are protected using either HTTP Basic Authentication or OAuth2.
⚠️ Never share your API token, API secret, or OAuth2 credentials with anyone — not even Jumio Support!
The Account Management Service initiates the acquisition process and returns:
At the moment, your Basic Auth credentials are constructed using your API token as the User ID and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under:
Your new OAuth2 credentials are constructed using your API token as the Client ID and your API secret as the Client secret. You can view and manage your API token and secret in the Customer Portal under:
Client ID and Client secret are used to generate an OAuth2 access token. OAuth2 has to be activated for your account. Contact your Jumio Account Manager for activation.
https://auth.amer-1.jumio.ai/oauth2/token
https://auth.emea-1.jumio.ai/oauth2/token
https://auth.apac-1.jumio.ai/oauth2/token
The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see supported cipher suites.
ℹ️ Calls with missing, incorrect or suspicious headers or parameter values will result in HTTP status code __400 Bad Request Error__ or __403 Forbidden__
curl --location --request POST 'https://auth.amer-1.jumio.ai/oauth2/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'grant_type=client_credentials' \
--basic --user CLIENT_ID:CLIENT_SECRET
{
"access_token": "YOUR_ACCESS_TOKEN",
"expires_in": 3600,
"token_type": "Bearer"
}
Your OAuth2 access token is valid for 60 minutes. After the token lifetime is expired, it is necessary to generate a new access token.
The token lifetime is set to 30 minutes per default. It can be configured via the Jumio Customer Portal and can be overwritten using the API call (tokenLifetime
). Within this token lifetime the token can be used to initialize the SDK, API or Web journey.
As soon as the workflow (transaction) starts, a 15 minutes session timeout starts. For each action performed (capture image, upload image) the session timeout will reset, and the 15 minutes will start again.
Create a new account for your end user by using the following API endpoint and below mentioned request headers and request body:
HTTP Request Method: POST
https://account.amer-1.jumio.ai/api/v1/accounts
https://account.emea-1.jumio.ai/api/v1/accounts
https://account.apac-1.jumio.ai/api/v1/accounts
The following fields are required in the header section of your Request
Accept: application/json
Content-Type: application/json
Content-Length:
see RFC-7230
Authorization:
see RFC6749
User-Agent: YourCompany YourApp/v1.0
⚠️ Jumio requires the __User-Agent__ value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code __403 Forbidden__
The body of your initiate API request allows you to:
Values set in your API request will override the corresponding settings configured in the Customer Portal.
(Mandatory parameters in bold.)
Parameter | Type | Max. Length | Notes |
---|---|---|---|
customerInternalReference | string | 100 | Customer internal reference for a request to link it in the customer backend (must not contain any PII) |
workflowDefinition | object | Definition of the specific documents necessary to execute for the particular capabilities on them. | |
workflowDefinition.key | object | Key of the workflow definition which you want to execute See Workflow Definition Keys |
|
workflowDefinition.credentials | array (object) | Optional workflow definition object part to customize acquiring process and workflow process. Possible values: See workflowDefinition.credentials |
|
userReference | string | 100 | Reference for the end user in the customer backend (must not contain any PII) |
reportingCriteria | string | 255 | Additional information provided by a customer for searching and aggregation purposes |
callbackUrl | string | 255 | Definition of the callback URL for this particular request. Overrides callback URL in the Customer Portal. |
tokenLifetime | string | minimum: 5m, maximum: 60d, default: 30m |
Should be a valid date period unit definition: s - seconds m - minutes h - hours d - days Example: ‘1d’ / ‘30m’ / ‘600s’ Overrides Authorization token lifetime in the Customer Portal. |
web | object | Web parameters are only relevant for the WEB channel. | |
web.successUrl | string | 255 | URL to which the browser will send the end user at the end of a successful web acquisition user journey. Overrides success URL in the Customer Portal. |
web.errorUrl | string | 255 | URL to which the browser will send the end user at the end of a failed web acquisition user journey. Overrides error URL in the Customer Portal. |
web.locale | string | 5 | Renders content in the specified language. Overrides Default locale in the Customer Portal. See supported locale values. |
userConsent1 | object | User consent needed where a product uses facial recognition technology or processes biometric data Possible values: See userConsent |
1 Mandatory for End-User Consent even if the user is not based in USA. Only required when using the API channel. Web and SDK channels will capture the consent automatically during the user journey.
Parameter | Type | Max. Length | Notes |
---|---|---|---|
category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
|
country | object | Possible values: • country.predefinedType • country.values |
|
country.predefinedType | string | Possible values: • DEFINED (default: end user is not able to change country) • RECOMMENDED (country is preselected, end user is still able to change it) |
|
country.values | array (string) | See possible values. | Define at least one ISO 3166-1 alpha-3 country code for the workflow definition. Possible values: • ISO 3166-1 alpha-3 country code |
type | object | Possible values: • type.predefinedType • type.values |
|
type.predefinedType | object | Possible values: • DEFINED (default: end user is not able to change document type) • RECOMMENDED (type is preselected, end user is still able to change it) |
|
type.values | array (string) | See possible values. | Defined number of credential type codes. Possible values: If category = ID:• ID_CARD • DRIVING_LICENSE • PASSPORT • VISA If category = FACEMAP:• IPROOV_STANDARD (Web + SDK channel only) • IPROOV_PREMIUM (Workflow 3: ID and Identity Verification (Web + SDK channel only) / Workflow 9: Authentication (SDK only) / Workflow 16: Authentication on Premise (SDK only)) • JUMIO_STANDARD |
Parameter | Type | Max. Length | Notes |
---|---|---|---|
userIp1 | string | Current IP address of the end-user used during the verification | |
userLocation1 | object | Possible values: • userLocation.country • userLocation.state |
|
userLocation.country1 | string | 3 | Current country as per end-user location during the verification Possible values: • ISO 3166-1 alpha-3 country code |
userLocation.state | string | 100 | Current State as per end-user location during the verification Applicable only in countries where state exists, including USA Possible values: • For USA, CAN, or AUS alpha-2 code (state only - without country & hyphen), e.g. IL (Illinois), NSW (New South Wales)• For other countries, if applicable, any string |
consent2 | object | Possible values: • consent.obtained • consent.obtainedAt |
|
consent.obtained | String | If the end-user consent has been obtained Possible values: • yes (the consent was given by the end-user) • no (the consent was not given by the end-user) • na (not applicable) Mandatory for End-User Consent if userLocation.country = USA |
|
consent.obtainedAt | String | Timestamp when the consent was obtained (UTC) Format: YYYY-MM-DDThh:mm:ss.SSSZ Mandatory for End-User Consent if consent.obtained = yes |
1 Mandatory for End-User Consent even if the user is not based in USA. Only required when using the API channel. Web and SDK channels will capture the consent automatically during the user journey.
2 Mandatory for End-User Consent if userLocation.country = USA / consent.obtained = yes
Unsuccessful requests will return HTTP status code 400 Bad Request, 401 Unauthorized, 403 Forbidden or 404 Not Found (in case of a failed update scenario) if the scan is not available.
Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.
Parameter | Type | Notes |
---|---|---|
timestamp | string | Timestamp (UTC) of the response. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
account | object | Possible values: • account.id |
account.id | string | UUID of the account |
sdk | object | Possible values: • sdk.token SDK parameters are only relevant for the SDK channel. |
sdk.token | string | JWT token for performing any action SDK parameters are only relevant for the SDK channel. |
workflowExecution | object | Possible values: • workflowExecution.id • workflowExecution.credentials |
workflowExecution.id | string | UUID of the workflow |
workflowExecution.credentials | array (object) | Credential response See workflowExecution.credentials |
workflowDefinition.capabilities | object | Optional workflow definition object part to customize acquiring process and workflow process. Possible values: See workflowDefinition.capabilities |
web | object | Possible values: • web.href • web.successUrl • web.errorUrl Web parameters are only relevant for the WEB channel. |
web.href | string | URL used to load the ID Verification client. Web parameters are only relevant for the WEB channel. |
web.successUrl | string | URL to which the browser will send the end user at the end of a successful web acquisition user journey (defined either in the Customer Portal or overwritten in the initiate) SDK parameters are only relevant for the SDK channel. |
web.errorUrl | string | URL to which the browser will send the end user at the end of a failed web acquisition user journey(defined either in the Customer Portal or overwritten in the initiate) SDK parameters are only relevant for the SDK channel. |
Parameter | Type | Notes |
---|---|---|
id | string | UUID of the credentials |
category | string | Credential category. Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
country | object | Defined at least one ISO 3166-1 alpha-3 country code for the workflow definition. Possible values: • ISO 3166-1 alpha-3 country code |
type | object | Defined number of credential type codes. Possible values: • ID_CARD • DRIVING LICENSE • PASSPORT • VISA |
allowedChannels | array | Channels which can be used to upload particular credential Possible values: • WEB • API • SDK |
api | object | Available actions for the API calls, actions can be omitted due to unavailability Possible values: • api.token •api.parts • api.workflowExecution API parameters are only relevant for the API channel. |
api.token | string | JWT token for performing any action for API API parameters are only relevant for the API channel. |
api.parts | object | href to manage parts for the account credential Possible values: • FRONT • BACK • FACE • FACEMAP API parameters are only relevant for the API channel. |
api.workflowExecution | string | href to manage the acquisition and workflow processing API parameters are only relevant for the API channel. |
Parameter | Type | Max. Length | Notes |
---|---|---|---|
watchlistScreening | object | Possible values: • watchlistScreening.additionalProperties |
|
watchlistScreening.additionalProperties | string | Provide request options for watchlistScreening capability |
curl --location --request POST 'https://account.amer-1.jumio.ai/api/v1/accounts' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
"customerInternalReference": "CUSTOMER_REFERENCE",
"workflowDefinition": {
"key": 10013,
"credentials": [
{
"category": "ID",
"country": {
"predefinedType": "DEFINED",
"values": ["USA", "CAN", "AUT", "GBR"]
},
"type": {
"predefinedType": "DEFINED",
"values": ["DRIVING_LICENSE", "ID_CARD"]
}
}
],
"capabilities": {
"watchlistScreening": {
"additionalProperties": "string"
}
}
},
"callbackUrl": "YOUR_CALLBACK_URL",
"userReference": "YOUR_USER_REFERENCE",
"tokenLifetime": "5m",
"web":{
"successUrl":"https://www.yourcompany.com/success",
"errorUrl":"https://www.yourcompany.com/error",
"locale":"es"
},
"userConsent": {
"userIp": "226.80.211.232",
"userLocation": {
"country": "USA",
"state": "IL"
},
"consent": {
"obtained": "yes",
"obtainedAt": "2022-07-20T17:20:35.000Z"
}
}
}'
After you have created an account for an end user, you can use this API to update that account. You will use this API endpoint for every new workflow (transaction) you need to initialize for that end user.
Updating an account is very similar to creating one; the request headers and body are the same in both cases. The difference is that you pass the accountId
to the endpoint and use PUT instead of POST.
HTTP Request Method: PUT
https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>
https://account.emea-1.jumio.ai/api/v1/accounts/<accountId>
https://account.apac-1.jumio.ai/api/v1/accounts/<accountId>
Please refer to Account Create section.
Please refer to Account Create section.
Please refer to Account Create section.
curl --location --request PUT 'https://account.amer-1.jumio.ai/api/v1/accounts/<accountId>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: User Demo' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
"customerInternalReference": "CUSTOMER_REFERENCE",
"workflowDefinition": {
"key": 10013,
"credentials": [
{
"category": "ID",
"type": {
"values": ["DRIVING_LICENSE", "ID_CARD", "PASSPORT"]
},
"country": {
"values": ["USA", "CAN", "AUT", "GBR"]
}
}
]
},
"callbackUrl": "YOUR_CALLBACK_URL",
"userReference": "YOUR_USER_REFERENCE",
"web":{
"successUrl":"https://www.yourcompany.com/success",
"errorUrl":"https://www.yourcompany.com/error",
"locale":"es"
},
"userConsent": {
"userIp": "226.80.211.232",
"userLocation": {
"country": "AUT"
}
}
}'
{
"timestamp": "2021-05-28T09:17:50.240Z",
"account": {
"id": "11111111-1111-1111-1111-aaaaaaaaaaaa"
},
"web": {
"href": "https://mycompany.web.amer-1.jumio.ai/web/v4/app?authorizationTokenxxx&locale=es",
"successUrl": "https://www.yourcompany.com/success",
"errorUrl": "https://www.yourcompany.com/error"
},
"sdk": {
"token": "xxx"
},
"workflowExecution": {
"id": "22222222-2222-2222-2222-aaaaaaaaaaaa",
"credentials": [
{
"id": "33333333-3333-3333-aaaaaaaaaaaa",
"category": "ID",
"allowedChannels": [
"WEB",
"API",
"SDK"
],
"api": {
"token": "xxx",
"parts": {
"front": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/FRONT",
"back": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-aaaaaaaaaaaa/parts/BACK"
},
"workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
}
},
{
"id": "33333333-3333-3333-bbbbbbbbbbbb",
"category": "SELFIE",
"allowedChannels": [
"WEB",
"API",
"SDK"
],
"api": {
"token": "xxx",
"parts": {
"face": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa/credentials/33333333-3333-3333-bbbbbbbbbbbb/parts/FACE"
},
"workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/11111111-1111-1111-1111-aaaaaaaaaaaa/workflow-executions/22222222-2222-2222-2222-aaaaaaaaaaaa"
}
},
{
"id": "33333333-3333-3333-cccccccccccc",
"category": "FACEMAP",
"allowedChannels": [
"WEB",
"SDK"
]
}
]
}
}
A complete list of supported Workflow Definition Keys can be found here.
Workflows are specified using the key
attribute in the workflowDefinition
object:
"workflowDefinition": {
"key": DEFINITION_KEY,
"credentials": []
}
To collect consent on Jumio’s behalf, you will need to incorporate certain explicit consent collection language and a link to Jumio’s Privacy Notice within your user consent flow before collection of end-user biometric data, if the end-user is located inside the United States.
The following is an example of how consent may be presented to the end-user, but you may use your own custom language as long as the required elements are present:
“By clicking “Start” you consent to Jumio collecting, processing, and sharing your personal information, which may include biometric data, pursuant to its Privacy Notice.”
Every transaction which includes any product/workflow step in which biometrics are collected needs to have consent parameters adapted and populated. This means if Face match is enabled for your account, Liveness, or Authentication is used you will need to share consent parameters.
When using the Web and SDK channels, user consent will be captured automatically during the user journey, therefore you do not need to include the IP address and country during Account Creation or Account Update. However, if biometric data collection occurs on the API channel, the consent parameters are then mandatory. If consent was not provided during the previous steps or was not accepted, the transaction will be rejected at the credential upload step when using the API channel. To update or resubmit consent, you can use the Account Update to provide the consent parameters before uploading biometric data through the API channel.
If your Privacy Policy and Terms & Conditions allowing continuous use of consent obtained from end-user on biometric data collection and processing the timestamp (consent.obtainedAt
) should be when the original/updated consent was obtained.
⚠️ If the continuous consent applies, the consent is valid for a period of maximum 3 years (between the consent timestamp and current timestamp). A new consent needs to be obtained from the end-user before continuous consent expires. The consent timestamp (consent.obtainedAt
) has to be updated accordingly.
Note: Until further notice Jumio will not perform any treatment based on the consent parameters. After a notice period, business validation will be performed which could also lead to a rejection of the transaction, also providing additional consent specific error codes. The rejection will happen at the data acquisition step and not at the Account Create or Account Update stage. We will inform you separately on a specific date.
Jumio Product / Workflow Steps | Biometric Component |
---|---|
Jumio Identity Verification | Involves Liveness and Face match May also serve as base facemap creation for authentication |
Jumio Go | Involves Liveness and Face match |
Authentication | Involves new facemap creation and comparison with existing facemap |
ID Verification | Involves Face match (if enabled for the account) |
Jumio Video verification | Involves Liveness and Face match |
Jumio Screening | ID Verification: Involves Face match (if 1:n face match is enabled for the account) Identity Verification: Involves Liveness and Face match |
Note: In case there is a requirement to collect end user consent in the middle of the workflow (i.e. ID Verification happens on the 4th step) the same can be achieved by sharing the consent field when sending an Account Update request before the workflow steps initiation where biometrics is needed.
Within the consent area in the API request body.
userLocation.userIp
,userLocation.country
)See examples for a sample request including the user consent parameters.
This section illustrates how to implement the SDK.
After creating/updating a new account you will receive a sdk.token
(JWT) for initializing the SDK. Use this token with your Android or iOS code.
try {
sdk = JumioSDK(this)
// Set your access token
sdk.token = "yourAccessToken"
// Set the dataCenter, default is US
sdk.dataCenter = jumioDataCenter
} catch (e1: PlatformNotSupportedException) {
// Handle exceptions here
} catch (e2: NullPointerException) {
// Handle exceptions here
}
sdk = Jumio.SDK()
// Set your access token
sdk.token = "yourAccesToken"
// Set the dataCenter, default is US
sdk.dataCenter = jumioDataCenter
For more information on how to use the Jumio Mobile SDK please refer to our mobile guides for iOS and Android.
This section illustrates how to implement the API.
After creating/updating a new account, you receive one or more specific redirect URL(s) to upload needed credentials (ID, facemap, document, selfie).
The following fields are required in the header section of your request
Accept: application/json
Content-Type: multipart/form-data
Content-Length:
see RFC-7230
Authorization:
see RFC6749
User-Agent: YourCompany YourApp/v1.0
⚠️ Jumio requires the __User-Agent__ value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code __403 Forbidden__
HTTP Request Method: POST
https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>
https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>
https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/credentials/<credentialsId>/parts/<classifier>
Parameter | Type | Note |
---|---|---|
accountId | string | UUID of the account |
workflowExecutionId | string | UUID of the workflow |
credentialsId | string | UUID of the credentials |
classifier | string | Possible values: • FRONT • BACK • FACE • FACEMAP |
Key | Value |
---|---|
file | JPEG, PNG (max. size 5 MB and max resolution of 8000 x 8000) |
Unsuccessful requests will return HTTP status code 401 Unauthorized, 403 Forbidden or 404 Not Found if the scan is not available.
Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.
Parameter | Type | Notes |
---|---|---|
timestamp | string | Timestamp (UTC) of the response. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
account | object | Possible values: • account.id |
account.id | string | UUID of the account |
workflowExecution | object | Possible values: • workflowExecution.id • workflowExecution.credentials |
workflowExecution.id | string | UUID of the workflow |
workflowExecution.credentials | array (object) | Credential response See workflowExecution.credentials |
api | object | Available actions for the API calls, actions can be omitted due to unavailability Possible values: • api.token • api.parts • api.workflowExecution |
api.token | string | JWT token for performing any action for API |
api.parts | object | href to manage parts for the account credential Possible values: • FRONT • BACK • FACE • FACEMAP |
api.workflowExecution | string | href to manage the acquisition and workflow processing |
{
"timestamp": "2021-03-05T13:17:49.042Z",
"account": {
"id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"workflowExecution": {
"id": "22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"api": {
"token": "xxx",
"parts": {
"front": "https://api.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/credentials/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx/parts/FRONT",
"back": "https://api.apac-1.jumio.ai/api/v1/accounts/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/credentials/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx/parts/BACK"
},
"workflowExecution": "https://api.apac-1.jumio.ai/api/v1/accounts/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
When all data has been uploaded, be sure to finalize the workflow as described below.
Once the user has provided their data, the workflow needs to be finalized. Finalization sends the data to Jumio for processing and cleans up the workflow. If no finalization call happens, the workflow will be cleaned up after the token or session expires (workflowExecution.status = SESSION_EXPIRED
/ TOKEN_EXPIRED
).
HTTP Request Method: PUT
https://api.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
https://api.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
https://api.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
The following fields are required in the header section of your Request
Accept: application/json
Content-Type: application/json
Content-Length:
see RFC-7230
Authorization:
see RFC6749
User-Agent: YourCompany YourApp/v1.0
⚠️ Jumio requires the __User-Agent__ value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code __403 Forbidden__
Parameter | Type | Note |
---|---|---|
accountId | string | UUID of the account |
workflowExecutionId | string | UUID of the workflow |
Unsuccessful requests will return HTTP status code 401 Unauthorized, 403 Forbidden or 404 Not Found if the scan is not available.
Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.
Parameter | Type | Note |
---|---|---|
timestamp | string | Timestamp (UTC) of the response. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
account | object | Possible values: • account.id |
account.id | string | UUID of the account |
workflowExecution | object | Possible values: • workflowExectuion.id |
workflowExecution.id | string | UUID of the workflow |
PUT
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Host: api.apac-1.jumio.ai
Authorization: Bearer xxx
Content-Length: 38
Content-Type: multipart/form-data;
{
"timestamp": "2021-02-25T11:55:41.347Z",
"account": {
"id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"workflowExecution": {
"id": "22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}
This section illustrates how to implement the Web client.
Use the Account Creation or Account Update API to initiate a Web workflow.
The following optional web-specific parameters can be included in the body of the initiate request.
ℹ️ You need to define a subdomain in your Customer Portal under Settings > Application Settings > Redirect > Domain Name Prefix in order to successfully generate a web.href
.
Use web.successUrl
and web.errorUrl
to specify how the end user will be redirected by the browser at the end of the web acquisition user journey.
If these parameters are not provided, and the values are not present in the Customer Portal settings, the end user will be shown a success or error page instead.
Parameter web.locale
can be used to render the content of the client in the specified language.
Hyphenated combination of ISO 639-1:2002 alpha-2 language code plus ISO 3166-1 alpha-2 country (where applicable).
Value | Locale |
---|---|
ar | Arabic |
bg | Bulgarian |
cs | Czech |
da | Danish |
de | German |
el | Greek |
en | American English (default) |
en-GB | British English |
es | Spanish |
es-MX | Mexican Spanish |
et | Estonian |
fi | Finnish |
fr | French |
he | Hebrew |
hr | Croatian |
hu | Hungarian |
hy | Armenian |
id | Indonesian |
it | Italian |
ja | Japanese |
ka | Georgian |
km | Khmer |
ko | Korean |
lt | Lithuanian |
ms | Malay |
nl | Dutch |
no | Norwegian |
pl | Polish |
pt | Portuguese |
pt-BR | Brazilian Portuguese |
ro | Romanian |
ru | Russian |
sk | Slovak |
sv | Swedish |
th | Thai |
tr | Turkish |
vi | Vietnamese |
zh-CN | Simplified Chinese |
zh-HK | Traditional Chinese |
When you initiate the web client, the API returns the web.href
that you use to display the web client to the end user. You can provide this URL in several ways:
If you want to embed ID Verification on your web page, place the iFrame tag in your HTML code where you want the client to appear. Use web.href
as the value of the iFrame src
attribute.
⚠️ The allow="camera"
attribute must be included to enable the camera for image capture in supported browsers.
⚠️ If you are nesting the iFrame in another iFrame, the allow="camera"
attribute must be added to every iFrame.
⚠️ Do not add the iFrame element and its attributes with javascript dynamically at runtime. The iFrame must be present when the page loads.
⚠️ Camera capture is only possible within an iFrame when the containing page is served securely over https.
We recommend adhering to the responsive breaking points in the table below.
Size class | Width | Height |
---|---|---|
Large | ≥ 900 px | ≥ 710 px |
Medium | 640 px | 660 px |
Small | 560 px | 600 px |
X-Small | ≤ 480 px | ≤ 535 px |
When specifying the width and height of your iFrame, you may prefer to use percentage values so that the iFrame behaves responsively on your page.
⚠️ The ID Verification Web client itself will responsively fill the iFrame that it is loaded into.
⚠️ The allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen
iFrame attributes must be included to enable biometric face capture in supported browsers.
⚠️ If you are nesting the iFrame in another iFrame, the allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen
attribute must be added to every iFrame.
⚠️ Do not add the iFrame element and its attributes with javascript dynamically at runtime. The iFrame must be present when the page loads.
⚠️ Camera capture is only possible within an iFrame when the containing page is served securely over https.
⚠️ Biometric Face Capture is not possible within an iFrame on incognito mode.
Absolute sizing example
<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="930" height="750" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
Responsive sizing example
<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="70%" height="80%" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
Biometric face capture example
<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="70%" height="80%" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>
When the ID Verification client is embedded in an iFrame1, it will communicate with the containing page using the JavaScript window.postMessage()
method to send events containing pre-defined data. This allows the containing page to react to events as they occur (e.g., by directing to a new page once the success
event is received).
Events include data that allows the containing page to identify which ID Verification transaction triggered the event. Events are generated in a stateless way, so that each event contains general contextual information about the transaction (e.g., transaction reference, authorization token, etc.) in addition to data about the specific event that occurred.
Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the message
event on the global window
object and reacting to it as needed. The data passed by the ID Verification Web client in this notification is represented as JSON in the data
string property of the listener method’s event
argument. Parsing this JSON string results in an object with the properties described below.
All data is encoded with UTF-8.
1 This functionality is not available for instances of ID Verification running in a standalone window or tab.
event.data
objectRequired items appear in bold type.
Property | Type | Description |
---|---|---|
accountId | string | UUID of the account |
authorizationToken | string | Authorization token, valid for a specified duration |
workflowExecutionId | string | UUID of the workflow |
customerInternalReference1 | string | Internal reference for a request to link it in the customer backend. It must not contain Personally Identifiable Information (PII) or sensitive data such as e-mail addresses. |
eventType | integer | Type of event that has occurred. Possible values: • 510 (application state-change) |
dateTime | string | UTC timestamp of the event in the browser Format: YYYY-MM-DDThh:mm:ss.SSSZ |
payload | JSON object | Information specific to the event generated (see event.data.payload object) |
event.data.payload
objectRequired items appear in bold type.
Name | Type | Description |
---|---|---|
value | string | Possible values: • loaded (ID Verification loaded in the user’s browser.)• success (Images were accepted for verification.)• error (Verification could not be completed due to an error.) |
metainfo | JSON object | Additional meta-information for error events. (see metainfo object) |
event.data.payload.metainfo
objectRequired items appear in bold type.
Property | Type | Description |
---|---|---|
code | integer | Only present if payload.value = error See errorCode values |
function receiveMessage(event) {
var data = window.JSON.parse(event.data);
console.log('ID Verification Web was loaded in an iframe.');
console.log('auth-token:', data.authorizationToken);
console.log('event-type:', data.eventType);
console.log('date-time:', data.dateTime);
console.log('workflow-execution-id:', data.workflowExecutionId);
console.log('account-id:', data.accountId);
console.log('customer-internal-reference:', data.customerInternalReference);
console.log('value:', data.payload.value);
console.log('metainfo:', data.payload.metainfo);
}
window.addEventListener("message", receiveMessage, false);
ID Verification Web can be embedded within a WebView in your native mobile application.
See Supported Environments > Native WebView for information about support on Android and iOS.
This sections illustrates how to embed ID Verification Web in a native Android WebView.
Make sure that the required permissions are granted.
android.permission.INTERNET
- for remote resources accessandroid.permission.CAMERA
- for camera captureandroid.permission.READ_EXTERNAL_STORAGE
- for upload functionalityThe following settings are required for the native WebView for Android.
javaScriptEnabled
- tells the WebView to enable JavaScript executionallowFileAccess
- enables file access within WebViewallowFileAccessFromFileUrls
- sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from other file scheme URLsallowUniversalAccessFromFileUrls
- sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any originallowContentAccess
- enables content URL access within WebViewjavaScriptCanOpenWindowsAutomatically
- tells JavaScript to open windows automaticallydomStorageEnabled
- sets whether the DOM storage API is enabledmediaPlaybackRequiresUserGesture
- sets whether the WebView requires a user gesture to play mediaTo allow Jumio to identify the user runtime environment, you will need to embed a required script that sets flag __NVW_WEBVIEW__
to true
to interact with the webview window object. For details, see the sample code below.
You can handle messages from the ID Verification Web Client using the same method as described in Optional iFrame Logging.
You will need to register a postMessage handler and put the relevant code sections in the PostMessageHandler
class as in the example below.
AndroidManifest.xml example
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.jumio.nvw4">
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
...
</manifest>
build.gradle example
dependencies {
implementation 'androidx.appcompat:appcompat:1.2.0-beta01'
implementation 'androidx.webkit:webkit:1.2.0'
...
}
WebViewFragment.kt example
class WebviewFragment : Fragment() {
companion object {
var TAG: String = "NVW4"
var PERMISSION_REQUEST_CODE: Int = 1000
private var mUploadMessage: ValueCallback<Uri?>? = null
var uploadMessage: ValueCallback<Array<Uri>>? = null
const val REQUEST_SELECT_FILE = 1002
private const val FILECHOOSER_RESULTCODE = 1003
private var _binding: FragmentWebviewBinding? = null
private val binding get() = _binding!!
//Inject javascript code here that is executed after the page is loaded
val injectFunction = """
function () {
window['__NVW_WEBVIEW__'] = {
isAndroid: true
}
}
""".trimIndent()
private var mFilePathCallback: ValueCallback<Array<Uri>>? = null
fun newInstance(url: String): WebviewFragment {
val fragment = WebviewFragment()
val args = Bundle()
args.putString("url", url)
fragment.arguments = args
return fragment
}
}
override fun onCreateView(
inflater: LayoutInflater,
container: ViewGroup?,
savedInstanceState: Bundle?
): View {
_binding = FragmentWebviewBinding.inflate(inflater, container, false)
return binding.root
}
@SuppressLint("SetJavaScriptEnabled")
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)
WebView.setWebContentsDebuggingEnabled(true)
binding.webview.settings.javaScriptEnabled = true
binding.webview.settings.allowFileAccessFromFileURLs = true
binding.webview.settings.allowFileAccess = true
binding.webview.settings.allowContentAccess = true
binding.webview.settings.allowUniversalAccessFromFileURLs = true
binding.webview.settings.javaScriptCanOpenWindowsAutomatically = true
binding.webview.settings.mediaPlaybackRequiresUserGesture = false
binding.webview.settings.domStorageEnabled = true
binding.webview.addJavascriptInterface(PostMessageHandler(), "__NVW_WEBVIEW_HANDLER__")
binding.webview.webChromeClient = object : WebChromeClientFullScreen() {
// Grant permissions for cam
@TargetApi(Build.VERSION_CODES.M)
override fun onPermissionRequest(request: PermissionRequest) {
activity?.runOnUiThread {
if ("android.webkit.resource.VIDEO_CAPTURE" == request.resources[0]) {
if (ContextCompat.checkSelfPermission(
activity!!,
Manifest.permission.CAMERA
) == PackageManager.PERMISSION_GRANTED
) {
Log.d(
TAG,
String.format(
"PERMISSION REQUEST %s GRANTED",
request.origin.toString()
)
)
request.grant(request.resources)
} else {
ActivityCompat.requestPermissions(
activity!!,
arrayOf(
Manifest.permission.CAMERA,
Manifest.permission.READ_EXTERNAL_STORAGE
),
PERMISSION_REQUEST_CODE
)
}
}
}
}
// For Lollipop 5.0+ Devices
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
override fun onShowFileChooser(
mWebView: WebView?,
filePathCallback: ValueCallback<Array<Uri>>?,
fileChooserParams: FileChooserParams
): Boolean {
if (uploadMessage != null) {
uploadMessage!!.onReceiveValue(null)
uploadMessage = null
}
try {
uploadMessage = filePathCallback
val intent = fileChooserParams.createIntent()
intent.type = "image/*"
try {
startActivityForResult(intent, REQUEST_SELECT_FILE)
} catch (e: ActivityNotFoundException) {
uploadMessage = null
Toast.makeText(
activity?.applicationContext,
"Cannot Open File Chooser",
Toast.LENGTH_LONG
).show()
return false
}
return true
} catch (e: ActivityNotFoundException) {
uploadMessage = null
Toast.makeText(
activity?.applicationContext,
"Cannot Open File Chooser",
Toast.LENGTH_LONG
).show()
return false
}
}
private fun openFileChooser(uploadMsg: ValueCallback<Uri?>) {
mUploadMessage = uploadMsg
val i = Intent(Intent.ACTION_GET_CONTENT)
i.addCategory(Intent.CATEGORY_OPENABLE)
i.type = "image/*"
startActivityForResult(
Intent.createChooser(i, "File Chooser"),
FILECHOOSER_RESULTCODE
)
}
override fun onConsoleMessage(consoleMessage: ConsoleMessage): Boolean {
Log.d(TAG, consoleMessage.message())
return true
}
override fun getDefaultVideoPoster(): Bitmap {
return Bitmap.createBitmap(10, 10, Bitmap.Config.ARGB_8888)
}
}
binding.webview.webViewClient = object : WebViewClient() {
override fun onReceivedError(
view: WebView?,
errorCode: Int,
description: String?,
failingUrl: String?
) {
Toast.makeText(activity, description, Toast.LENGTH_SHORT).show()
}
override fun onReceivedSslError(
view: WebView?,
handler: SslErrorHandler?,
error: SslError?
) {
handler?.proceed()
}
override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
// Put your javascript function that you want to execute here
binding.webview.loadUrl("javascript:($injectFunction)()")
}
}
binding.webview.loadUrl(arguments?.get("url") as String)
}
override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
if (requestCode == REQUEST_SELECT_FILE) {
if (uploadMessage == null)
return
uploadMessage!!.onReceiveValue(
WebChromeClient.FileChooserParams.parseResult(
resultCode,
intent
)
)
uploadMessage = null
}
} else if (requestCode == FILECHOOSER_RESULTCODE) {
if (null == mUploadMessage)
return
val result =
if (intent == null || resultCode != AppCompatActivity.RESULT_OK) null else intent.data
mUploadMessage!!.onReceiveValue(result)
mUploadMessage = null
} else {
Toast.makeText(
activity?.applicationContext,
"Failed to Upload Image",
Toast.LENGTH_LONG
).show()
}
super.onActivityResult(requestCode, resultCode, intent)
}
class PostMessageHandler {
@JavascriptInterface
fun postMessage(json: String?, transferList: String?): Boolean {
/*
There we're handling messages from NVW4 client, its the same as for iFrame logging;
More details can be found here:
https://github.com/Jumio/implementation-guides/blob/master/netverify/netverify-web-v4.md#optional-iframe-logging
*/
Log.d(TAG, "postMessage triggered, json: " + json.toString())
return true
}
}
/**
* Custom WebChromClient to handle iProov full screen requirement
* More details can be found here:
* https://github.com/iProov/android/wiki/Java-WebView
*/
open inner class WebChromeClientFullScreen : WebChromeClient() {
private var customView: View? = null
private var customViewCallback: CustomViewCallback? = null
private var originalOrientation = ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
private var originalVisibility = View.INVISIBLE
/**
* Callback will tell the host application that the current page would
* like to show a custom View in a particular orientation
*/
override fun onShowCustomView(view: View, callback: CustomViewCallback) {
//If we have custom view, that means that we are already in full screen, and need to go to original state
if (customView != null) {
onHideCustomView()
return
}
//going full screen
customView = view
//We need to store there parameters, so we can restore app state, after we exit full screen mode
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
originalVisibility = activity?.window?.decorView?.visibility!!
(activity?.window?.decorView as FrameLayout).addView(
customView,
FrameLayout.LayoutParams(-1, -1)
)
activity?.window?.setDecorFitsSystemWindows(false)
} else {
originalVisibility = activity?.window?.decorView?.windowSystemUiVisibility!!
(activity?.window?.decorView as FrameLayout).addView(
customView,
FrameLayout.LayoutParams(-1, -1)
)
activity?.window?.decorView?.systemUiVisibility =
3846 or View.SYSTEM_UI_FLAG_LAYOUT_STABLE
}
originalOrientation = activity?.requestedOrientation!!
}
/**
* Callback will tell the host application that the current page exited full screen mode,
* and the app has to hide custom view.
*/
override fun onHideCustomView() {
(activity?.window?.decorView as FrameLayout).removeView(
customView
)
customView = null
//Restoring app state, as it was before we go to full screen
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
activity?.window?.setDecorFitsSystemWindows(true)
} else {
activity?.window?.decorView?.systemUiVisibility = originalVisibility
}
activity?.requestedOrientation = originalOrientation
if (customViewCallback != null) customViewCallback!!.onCustomViewHidden()
customViewCallback = null
}
}
Use of iProov
Please be aware that if iProov is included in your workflow, it is necessary to extend WebChromeClient
class to implement a custom view, in order to handle certain iProov full screen requirements.
See WebViewFragment.kt
code sample above, specifically WebChromeClientFullScreen
inner class.
Sample App
Check out our Sample App for the Native Android WebView
Jumio supports two types of webview for iOS:
Pros | Cons |
---|---|
Access to the camera during ID and Identity | No optional postMessage communication |
Fewer integration steps | Fewer options for troubleshooting |
Pros | Cons |
---|---|
Optional postMessage communication | Image upload only (no access to the camera) |
Better options for troubleshooting | More integration steps |
This section illustrates how to embed ID Verification Web in a Safari View Controller.
Make sure that camera permissions are granted.
import AVFoundation
import SafariServices
import UIKit
class ViewController: UIViewController {
@IBAction func loadButton(_ sender: Any) {
checkCameraPermission()
let url: String = "https://www.jumio.com/"
showSafariVC(inputText)
}
// present SFSafariViewController
private func showSafariVC(_ stringURL: String) {
guard let URL = URL(string: stringURL) else {
return
}
let safariVC = SFSafariViewController(url: URL)
present(safariVC, animated: true)
}
func safariViewControllerDidFinish(_ safariVC: SFSafariViewController) {
safariVC.dismiss(animated: true, completion: nil)
}
// ask for camera permissions
func checkCameraPermission() {
AVCaptureDevice.requestAccess(for: .video) { (granted) in
if !granted {
print("Camera permission denied")
}
}
}
}
Check out our Sample App for the iOS Safari WebView
This section illustrates how to embed ID Verification Web in a native iOS WebView.
No specific permissions are needed as we cannot access the camera due to native WebView limitations for iOS.
To allow Jumio to identify the user runtime environment, you will need to embed a required script that sets flag __NVW_WEBVIEW__
to true
to interact with the webview window object. For details, see the sample code below.
You can handle messages from the ID Verification Web Client using the same method as described in Optional iFrame Logging.
Register a postMessage handler and put the relevant code sections in the userContentController
function as shown below.
class ViewController: UIViewController {
@IBOutlet weak var webView: WKWebView!
override func viewDidLoad() {
super.viewDidLoad()
webView.navigationDelegate = self;
/**
* Registering handler for postMessage communication (iFrame logging equivalent - optional)
*/
webView.configuration.userContentController.add(self, name: "__NVW_WEBVIEW_HANDLER__")
webView.load( URLRequest("<<NVW4 SCAN REF LINK>>"));
}
}
extension ViewController: WKNavigationDelegate {
/**
* Embedding script at very beginning, before NVW4 initialize (important)
*/
func webView(_ webView: WKWebView, didStartProvisionalNavigation navigation: WKNavigation!) {
/**
* Necessary integration step - embedding script
*/
self.webView?.evaluteJavaScript("(function() { window['__NVW_WEBVIEW__'] = true })()") { _, error in
if let error = error {
print("ERROR while evaluating javascript \(error)") // error handling whenever executing script fails
}
print("executed injected javascript")
};
}
}
extension ViewController: WKScriptMessageHandler {
/**
* PostMessage handler for iframe logging equivalent (optional)
*/
func userContentController(_ userController: WKUserContentController, didReceive message: WKScriptMessage) {
if message.name == "__NVW_WEBVIEW_HANDLER__", let messageBody = message.body as? String {
/*
* See iFrame logging:
* https://github.com/Jumio/implementation-guides/blob/master/netverify/netverify-web-v4.md#optional-iframe-logging
*/
}
}
}
Check out our Sample App for the Native iOS WebView
At the end of the web acquisition user journey, the following query parameters are appended by the web client to the success or error URL before the end user is redirected by the browser.
Required items appear in bold type.
Name | Description |
---|---|
accountId | UUID of the account |
workflowExecutionId | UUID of the workflow |
acquisitionStatus | Possible values: • SUCCESS • ERROR |
customerInternalReference | Customer internal reference for a request to link it in the customer backend |
errorCode | Predefined list of error codes, only appended to errorUrl when acquisitionStatus is ERROR Possible values: • 9100 (Error occurred on our server.)• 9200 (Authorization token missing, invalid, or expired.)• 9210 (Session expired after the user journey started.)• 9300 (Error occurred transmitting image to our server.)• 9400 (Error occurred during verification step.)• 9800 (User has no network connection.)• 9801 (Unexpected error occurred in the client.)• 9810 (Problem while communicating with our server.)• 9820 (File upload not enabled and camera unavailable.)• 9821 (The biometric face capture process failed, e.g. issue with iProov)• 9822 (Browser does not support camera.)• 9835 (No acceptable submission in 3 attempts.)• 9836 (Authentication Failure.) |
Jumio offers guaranteed support for ID Verification on the following browsers and the latest major version of each operating system.
Browser | Major version | Operating system | Supports image upload | Supports camera capture | Supports biometric face capture |
---|---|---|---|---|---|
Google Chrome | current + 1 previous |
Windows + Mac | X | X | X |
Mozilla Firefox | current + 1 previous |
Windows + Mac | X | X | X |
Apple Safari | current | Mac | X | X | X |
Microsoft Edge | current | Windows | X | X | X |
Browser name | Major browser version | Operating system | Supports image upload | Supports camera capture | Supports biometric face capture |
---|---|---|---|---|---|
Google Chrome | current | Android | X | X | X |
Samsung Internet | current | Android | X | X | X |
Apple Safari | current | iOS | X | X | X1 |
1Fullscreen functionality during capture only supported for iPads. iPhone process works, but fullscreen is limited and capture may be less accurate.
Operating system | Major version | Supports image upload | Supports camera capture | Supports biometric face capture |
---|---|---|---|---|
Native Android WebView | current + 1 previous |
X | X | X |
Native iOS WebView1 | current + 1 previous |
X | ||
iOS Safari WebView | current + 1 previous |
X | X | X |
1If you are using a native WebView for iOS you will need to enable image upload to allow the end user to finish the user journey.
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.
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 account, see instructions in sections Account Creation and Account Update.
Allowlist the following IP addresses for callbacks, and use them to verify that the callback originated from Jumio.
US Data Center:
Use the hostname callback.jumio.com
to look up the most current IP addresses.
EU Data Center:
Use the hostname callback.lon.jumio.com
to look up the most current IP addresses.
SGP Data Center:
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/json
formatted string with the transaction result.
Parameter | Type | Notes |
---|---|---|
callbackSentAt | string | Timestamp of the callback in the format: YYYY-MM-DDThh:mm:ss.SSSZ |
userReference | string | User reference (if set in initiate call) |
workflowExecution | object | Possible values: • workflowExecution.id • workflowExecution.href |
workflowExecution.id | string | UUID of the workflow |
workflowExecution.href | sting | URL to retrieve workflow details |
workflowExecution.definitionKey | string | Key of the workflow definition you executed See supported keys |
workflowExecution.status | string | Possible values: • PROCESSED • SESSION_EXPIRED • TOKEN_EXPIRED |
account | object | Possible values: • account.id • account.href |
account.id | UUID of the account | |
account.href | URL to retrieve account details |
{
"callbackSentAt":"2021-01-21T14:55:01.917Z",
"workflowExecution":{
"id":"22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"href":"https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"definitionKey":"3",
"status":"PROCESSED"
},
"account":{
"id":"11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"href":"https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}
The Retrieval API allows you to get information from a transaction, including the transaction status, workflow details, and images.
The following fields are required in the header section of your request:
Accept: application/json
Content-Type: application/json
Content-Length:
see RFC-7230
Authorization:
see RFC6749
User-Agent: YourCompany YourApp/v1.0
⚠️ Jumio requires the __User-Agent__ value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code __403 Forbidden__
This section describes the Retrieval APIs: Status, Workflow Details, and Images.
HTTP Request Method: GET
https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/status
https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/status
https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/status
Parameter | Type | Note |
---|---|---|
accountId | string | UUID of the account |
workflowExecutionId | string | UUID of the workflow |
Unsuccessful requests will return HTTP status code 401 Unauthorized, 403 Forbidden or 404 Not Found if the scan is not available.
Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.
Parameter | Type | Note |
---|---|---|
account | object | Possible values: • account.id • account.href |
account.id | string | UUID of the account |
account.href | string | URL to retrieve account details |
workflowExecution | object | Possible values: • workflowExecution.id • workflowExecution.href • workflowExecution.definitionKey • workflowExecution.status |
workflowExecution.id | string | UUID of the workflow |
workflowExecution.href | string | URL to retrieve workflow details |
workflowExecution.definitionKey | string | Key of the workflow definition which you executed See supported keys |
workflowExecution.status | string | Possible values: • INITIATED • ACQUIRED • PROCESSED • SESSION_EXPIRED • TOKEN_EXPIRED |
{
"account": {
"id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"href": "https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"workflowExecution": {
"id": "22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"href": "https://retrieval.apac-1.jumio.ai/api/v1/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"definitionKey": "2",
"status": "PROCESSED"
}
}
HTTP Request Method: GET
https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
Parameter | Type | Note |
---|---|---|
accountId | string | UUID of the account |
workflowExecutionId | string | UUID of the workflow |
Unsuccessful requests will return HTTP status code 401 Unauthorized, 403 Forbidden or 404 Not Found if the scan is not available.
Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.
Parameter | Type | Note |
---|---|---|
createdAt | string | Timestamp (UTC) of the creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
startedAt | string | Timestamp (UTC) of the start. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
completedAt | string | Timestamp (UTC) of the completion. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
account | object | Possible values: • account.id |
account.id | string | UUID of the account |
workflow | object | Possible values: • workflow.id • workflow.status • workflow.definitionKey • workflow.userReference • workflow.customerInternalReference |
workflow.id | string | UUID of the workflow |
workflow.status | string | Possible values: • INITIATED • ACQUIRED • PROCESSED • SESSION_EXPIRED • TOKEN_EXPIRED |
workflow.definitionKey | string | See supported keys |
workflow.userReference | string | Customer internal reference for a request to link it in the customer backend (must not contain any PII) |
workflow.customerInternalReference | string | Reference for the end user in the customer backend (must not contain any PII) |
decision | object | See decision |
steps | object | See workflow.steps |
credentials | array (object) | See credentials |
capabilities | object | See capabilities |
Parameter | Type | Note |
---|---|---|
risk | object | Possible values: • risk.score |
risk.score | double | Possible values: • 0.00 - 100.00 (at max 2 decimal places) |
type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
details | object | Possible values: • details.label |
details.label | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • TECHNICAL_ERROR • WARNING |
Parameter | Type | Note |
---|---|---|
href | string | href to manage steps for the workflow see Get Workflow Steps |
Parameter | Type | Note |
---|---|---|
id | string | UUID of the credentials |
category | string | ID |
parts | object | Possible values: • parts.classifier • parts.href |
parts.classifier | string | Possible values: • FRONT • BACK • FACE |
parts.href | string | href to manage parts for the account credentials |
Since workflow execution consists of a chain of multiple capability executions (usability, extraction, liveness, …), some have dependencies between them and need the result of previous executions.
This means that some capabilities should not be executed if any of the previous capabilities were not successful because they were REJECTED or NOT_EXECUTED. If, for example, usability has passed, but imageChecks got rejected with the reason DIGITAL_COPY, the consequent extraction and dataChecks cannot be executed because of PRECONDITION_NOT_FULFILLED. The precondition in this case would be to successfully pass imageChecks.
Capability execution dependencies:
Parameter | Type | Note | Dependency |
---|---|---|---|
usability | array (object) | See usability | none |
liveness | array (object) | See liveness | usability |
similarity | array (object) | See similarity | usability |
authentication | array (object) | See authentication | usability |
imageChecks | array (object) | See imageChecks | usability |
extraction | array (object) | See extraction | usability, imageChecks |
dataChecks | array (object) | See dataChecks | usability, imageChecks, extraction |
watchlistScreening | array (object) | See watchlistScreening | usability, imageChecks, extraction |
addressValidation | array (object) | See addressValidation | usability, imageChecks, extraction |
proofOfResidency | array (object) | See proofOfResidency | usability, imageChecks, extraction |
drivingLicenseVerification | array (object) | See drivingLicenseVerification | usability, imageChecks, extraction |
braCpfValidation | array (object) | See braCpfValidation | |
biometricVerification | array (object) | See biometricVerification |
Dependency: none
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = NOT_EXECUTED: • TECHNICAL_ERROR • NOT_UPLOADED if decision.type = PASSED: • OK if decision.type = REJECTED: • BAD_QUALITY • BLURRED1 • BAD_QUALITY_IMAGE1 • PART_OF_DOCUMENT_MISSING1 • PART_OF_DOCUMENT_HIDDEN1 • DAMAGED_DOCUMENT1 • GLARE1 • MISSING_MANDATORY_DATAPOINTS1 • BLACK_WHITE • MISSING_PAGE • MISSING_SIGNATURE • NOT_A_DOCUMENT • PHOTOCOPY if decision.type = WARNING: • DOCUMENT_EXPIRY_WITHIN_CONFIGURED_LIMIT • LIVENESS_UNDETERMINED • UNSUPPORTED_COUNTRY • UNSUPPORTED_DOCUMENT_TYPE |
1 Will be added in the week of January 30, 2023.
Dependency: usability
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = REJECTED: • LIVENESS_UNDETERMINED • ID_USED_AS_SELFIE • MULTIPLE_PEOPLE • DIGITAL_COPY • PHOTOCOPY • MANIPULATED • NO_FACE_PRESENT • FACE_NOT_FULLY_VISIBLE • BLACK_WHITE if decision.type = PASSED: • OK if decision.type = WARNING: • AGE_DIFFERENCE • BAD_QUALITY if decision.type = NOT_EXECUTED: • PRECONDITION_NOT_FULFILLED • TECHNICAL_ERROR |
data | object | |
data.type | object | Possible values: • IPROOV_STANDARD (Web + SDK channel only) • IPROOV_PREMIUM (Workflow 3: ID and Identity Verification (Web + SDK channel only) / Workflow 9: Authentication (SDK only) / Workflow 16: Authentication on Premise (SDK only)) • JUMIO_STANDARD |
data.predictedAge | integer | Predicted age according to the selfie Example: ‘28’ |
data.ageConfidenceRange | string | Age range we are confident the selfie age is within Example: ‘25-34’ |
validFaceMapForAuthentication | string | href to manage facemap |
Dependency: usability
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = REJECTED: • NO_MATCH if decision.type = PASSED: • MATCH if decision.type = WARNING: • NOT_POSSIBLE if decision.type = NOT_EXECUTED: • PRECONDITION_NOT_FULFILLED • TECHNICAL_ERROR |
data | object | |
data.similarity | string | Possible values: • MATCH • NOT_MATCH • NOT_POSSIBLE |
Dependency: usability
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED |
decision.details | object | |
decision.details.label | string | if decision.type = PASSED: • OK if decision.type =REJECTED: • FAILED if decision.type = NOT_EXECUTED: • PRECONDITION_NOT_FULFILLED • TECHNICAL_ERROR |
data | object | |
data.type | object | Possible values: • IPROOV_STANDARD (Web + SDK channel only) • IPROOV_PREMIUM (Workflow 3: ID and Identity Verification (Web + SDK channel only) / Workflow 9: Authentication (SDK only) / Workflow 16: Authentication on Premise (SDK only)) |
validFaceMapForAuthentication | string | href to manage facemap |
Dependency: usability
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = NOT_EXECUTED: • PRECONDITION_NOT_FULFILLED • TECHNICAL_ERROR if decision.type = PASSED: • OK if decision.type = REJECTED: • DIGITAL_COPY • WATERMARK • MANIPULATED_DOCUMENT • MANIPULATED_DOCUMENT_PHOTO1 • MANIPULATED_DOCUMENT_EXPIRY1 • MANIPULATED_DOCUMENT_NAME1 • MANIPULATED_DOCUMENT_ADDRESS1 • MANIPULATED_DOCUMENT_SECURITY_CHECKS1 • MANIPULATED_DOCUMENT_SIGNATURE1 • MANIPULATED_DOCUMENT_PERSONAL_NUMBER1 • MANIPULATED_DOCUMENT_PLACE_OF_BIRTH1 • MANIPULATED_DOCUMENT_GENDER1 • MANIPULATED_DOCUMENT_ISSUING_DATE1 • OTHER_REJECTION • GHOST_IMAGE_DIFFERENT • PUNCHED • SAMPLE • FAKE • CHIP_MISSING • DIGITAL_MANIPULATION • MISMATCH_FRONT_BACK if decision.type = WARNING: • DIFFERENT_PERSON • REPEATED_FACE (same face with same data occurs multiple times –> potential opening of multiple accounts) |
data | object | See imageChecks.data |
1 Will be added in the week of January 30, 2023.
Parameter | Type | Note |
---|---|---|
data.faceSearchFindings | object | Result of 1:n face search on previous transactions |
data.faceSearchFindings.status | string | Possible values: • DONE • PENDING • ERROR |
data.faceSearchFindings.findings | array (string) | A face (on the ID or Selfie) is matching with another face (on the ID or Selfie) from a previous transaction |
data.faceSearchFindings.findings.items | string | UUID of the workflow |
Dependencies: usability, imageChecks
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | Possible values: • credentials.id • credentials.categrory |
credentials.id | string | UUID of the credentials |
credentials.categrory | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | Possible values: • decision.type • decision.details |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED |
decision.details | object | Possible values: • decision.details.label |
decision.details.label | string | if decision.type = NOT_EXECUTED: • PRECONDITION_NOT_FULFILLED • TECHNICAL_ERROR if decision.type = PASSED: • OK |
data | object | See extraction.data |
Parameter | Type | Note |
---|---|---|
data.type | string | Possible values: • PASSPORT • DRIVING_LICENSE • ID_CARD • VISA • UNSUPPORTED |
data.subType | string | Possible values if data.type = ID_CARD: • NATIONAL_ID • CONSULAR_ID • ELECTORAL_ID • RESIDENT_PERMIT_ID • TAX_ID • STUDENT_ID • PASSPORT_CARD_ID • MILITARY_ID • PUBLIC_SAFETY_ID • HEALTH_ID • OTHER_ID • VISA • UNKOWN Possible values if data.type = DRIVING_LICENSE: • REGULAR_DRIVING_LICENSE • LEARNING_DRIVING_LICENSE Possible values if data.type = PASSPORT: • E_PASSPORT (mobile only) |
data.issuingCountry | string | ISO 3166-1 alpha-3 country code |
data.firstName | string | First name of the user as available on the ID if enabled, otherwise if provided |
data.lastName | string | Last name of the customer as available on the ID if enabled, otherwise if provided |
data.dateOfBirth | string | Date of birth in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided |
data.expiryDate | string | Date of expiry in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided |
data.issuingDate | string | Date of issue in the format YYYY-MM-DD as available on the ID if enabled, otherwise if provided |
data.documentNumber | string | |
data.state | string | 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 • Free text if it can’t be mapped to a state/country code |
data.personalNumber | string | Personal number of the document, if idType = PASSPORT and if data available on the document (activation required) |
data.optionalMrzField1 | string | Optional field of MRZ line 1 |
data.optionalMrzField2 | string | Optional field of MRZ line 2 |
data.address | string | See data.address (activation required) |
data.issuingAuthority | string | Issuing authority of the document (activation required) |
data.issuingPlace | string | Issuing authority of the document (activation required) |
data.curp | string | CURP for Mexican documents (activation required) |
data.gender | string | Possible values: • M • F • X |
data.nationality | string | Possible values: • ISO 3166-1 alpha-3 country code (activation required) |
data.placeOfBirth | string | Place of birth of document holder |
data.taxNumber | string | Tax number of the document if country = ITA and type = HEALTH_ID, TAX_ID (activation required) |
data.cpf | string | CPF number of the document (activation required) |
data.registrationNumber | string | Registration number of the document (activation required) |
data.mothersName | string | Name of the document holder’s mother (activation required) |
data.fathersName | string | Name of the document holder’s father (activation required) |
data.personalIdentificationNumber | string | 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 (activation required) |
data.rgNumber | string | “General Registration” number if idCountry = BRA (activation required) |
data.dlCategories | array | Category of driving license |
data.voterIdNumber | string | Voter ID number if idCountry = MEX (activation required) |
data.issuingNumber | string | Issuing number if idCountry = MEX (activation required) |
data.passportNumber | string | Passport number if idType = VISA (activation required) |
data.durationOfStay | string | Duration of stay if idType = VISA (activation required) |
data.numberOfEntries | string | Number of entries if idType = VISA (activation required) |
data.visaCategory | string | Visa category if idType = VISA (activation required) |
data.dni | string | DNI (“Documento nacional de identidad”) number as available on the ID if idCountry = ESP and idSubType = NATIONA_ID (activation required) |
data.pesel | string | PESEL (“Powszechny Elektroniczny System Ewidencji Ludności”) number as available on the ID if idCountry = POL (activation required) |
data.expiryDateParts | object | Expiry date information (year, month, day) from the corresponding fields on the document 1 Example: {“year”: “2022”, “month”: “08”, “day”: “31”} |
data.dateOfBirthParts | object | Date of birth information (year, month, day) from the corresponding fields on the document 1 Example: {“year”: “2022”, “month”: “08”, “day”: “31”} |
data.issuingDateParts | object | Issuing date information (year, month, day) from the corresponding fields on the document 1 Example: {“year”: “2022”, “month”: “08”, “day”: “31”} |
data.laborIdentificationNumber | string | CUIL (“Clave Único de Identificación Laboral”) number as available on the ID if idCountry = ARG (activation required) |
data.documentCopy | string | Ejemplar number as available on the ID if idCountry = ARG (activation required) |
data.residentPermitType | string | Permit type related to “Golden Visas” if idCountry = GBR (activation required) |
data.residentPermitRemarks | string | Permit remarks related to “Golden Visas” if idCountry = GBR (activation required) |
data.documentIdentificationNumber | string | Document Identification Number (activation required) |
data.citizenship | string | Citizenship • if idCountry = IDN (activation required) |
data.maritalStatus | string | Marital Status • if idCountry = IDN (activation required) |
data.religion | string | Religion • if idCountry = IDN, MYS (activation required) |
data.currentAge | integer | Current age calculated as extracted from the ID (= current date - extracted date of birth) Example: ‘30’ |
data.lastNameAtBirth | string | Last name at birth • if idCountry = SLO (activation required) |
data.remarks | string | Special remarks/titles • if idCountry = SLO Example: Mgr (activation required) |
data.disability | string | Check if there is at least one disability icon available on the back side • if idCountry = BHR Possible values: • YES • NO (activation required) |
1 If one of the values such as “day” is not included in the document it will also not be returned in the object. For examples and additional details, refer to our Knowledge Base.
Parameter | Type | Note |
---|---|---|
line1 | string | Line item 1 |
line2 | string | Line item 2 |
line3 | string | Line item 3 |
line4 | string | Line item 4 |
line5 | string | Line item 5 |
country | string | Possible values: • ISO 3166-1 alpha-3 country code • XKX (Kosovo) |
postalCode | string | Postal code |
subdivision | string | Subdivision (Region, State, Province, Emirate, Department, …) |
city | string | City |
formattedAddress | string | Complete address in a formatted way |
Dependencies: usability, imageChecks, extraction
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED |
decision.details | object | |
decision.details.label | string | if decision.type = NOT_EXECUTED: • PRECONDITION_NOT_FULFILLED • TECHNICAL_ERROR if decision.type = PASSED: • OK if decision.type = REJECTED: • NFC_CERTIFICATE • MISMATCHING_DATAPOINTS • MRZ_CHECKSUM • MISMATCHING_DATA_REPEATED_FACE (same face occurs multiple times, data is different –> high possibility of fraud attempt) • MISMATCH_HRZ_MRZ_DATA |
Dependencies: usability, imageChecks, extraction
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = NOT_EXECUTED: • NOT_ENOUGH_DATA • VALIDATION_FAILED • INVALID_MERCHANT_SETTINGS • TECHNICAL_ERROR • EXTRACTION_NOT_DONE • NO_VALID_ID_CREDENTIAL • PRECONDITION_NOT_FULFILLED if decision.type = PASSED: • OK if decision.type = WARNING: • ALERT |
data | object | See watchlistScreening.data |
Parameter | Type | Note |
---|---|---|
searchDate | string | Timestamp (UTC) of the response. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
searchStatus | string | Possible values: • DONE • NOT_DONE • ERROR |
searchId | string | Only if searchStatus = DONE |
searchReference | string | Only if searchStatus = DONE |
searchResultUrl | string | Only if searchStatus = DONE |
searchResults | integer | Only if searchStatus = DONE |
Dependencies: usability, imageChecks, extraction
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = NOT_EXECUTED: • NOT_ENOUGH_DATA • TECHNICAL_ERROR • UNSUPPORTED_COUNTRY • PRECONDITION_NOT_FULFILLED if decision.type = PASSED • OK if decision.type = REJECTED: • DENY if decision.type = WARNING: • ALERT |
Dependencies: usability, imageChecks, extraction
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = NOT_EXECUTED: • NOT_ENOUGH_DATA • TECHNICAL_ERROR • UNSUPPORTED_COUNTRY • PRECONDITION_NOT_FULFILLED if decision.type = PASSED: • OK if decision.type = REJECTED: • DENY if decision.type = WARNING: • ALERT |
Dependencies: usability, imageChecks, extraction
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • DATA |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = NOT_EXECUTED: • TECHNICAL_ERROR • UNSUPPORTED_COUNTRY • UNSUPPORTED_STATE • PRECONDITION_NOT_FULFILLED • VALIDATION_FAILED if decision.type = PASSED: • OK if decision.type = REJECTED: • DENY if decision.type = WARNING: • ALERT |
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • ID • FACEMAP • DOCUMENT • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | if decision.type = NOT_EXECUTED: • NOT_ENOUGH_DATA • TECHNICAL_ERROR • INVALID_MERCHANT_SETTINGS • VALIDATION_FAILED • PRECONDITION_NOT_FULFILLED if decision.type = PASSED: • OK if decision.type = REJECTED: • DENY if decision.type = WARNING: • UNSUPPORTED_COUNTRY |
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • DATA • SELFIE |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | Possible values: • LOW_RISK • MEDIUM_RISK • HIGH_RISK • TECHNICAL_ERROR • PERMISSION_DENIED • BAD_REQUEST • PRECONDITION_NOT_FULFILLED |
Parameter | Type | Note |
---|---|---|
id | string | UUID of the capability |
credentials | object | |
credentials.id | string | UUID of the credentials |
credentials.category | string | Possible values: • DATA |
decision | object | |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | |
decision.details.label | string | Possible values: • OK • DENY • ALERT • VALIDATION_FAILED • UNSUPPORTED_COUNTRY • TECHNICAL_ERROR • UNSUPPORTED_STATE |
GET
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Host: retrieval.apac-1.jumio.ai
User-Agent: User Demo
Authorization: Bearer xxx
{
"workflow": {
"id": "22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "PROCESSED",
"definitionKey": "10013"
},
"account": {
"id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"createdAt": "2021-03-12T15:47:17.234Z",
"startedAt": "2021-03-12T15:49:32.202Z",
"completedAt": "2021-03-12T15:49:33.421Z",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID",
"parts": [
{
"classifier": "FRONT",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/credentials/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx/parts/FRONT"
}
]
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "PASSED"
},
"risk": {
"score": 0.0
}
},
"steps": {
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/steps"
},
"capabilities": {
"extraction": [
{
"id": "1a11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"type": "PASSPORT",
"subType": "E_PASSPORT",
"firstName": "JANE",
"lastName": "DOE",
"dateOfBirth": "1990-01-01",
"expiryDate": "2023-12-01",
"issuingDate": "2014-01-01",
"documentNumber": "xxxxxxxx",
"personalNumber": "<<<<<<<<<<<<<<",
"address": {
"country": "AUT",
"formattedAddress": "AUT"
}
}
}
],
"dataChecks": [
{
"id": "1b11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
],
"imageChecks": [
{
"id": "1c11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
],
"usability": [
{
"id": "1d11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
{
"id": "1f11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "44444444-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "SELFIE"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
},
{
"id": "1g11111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "55555555-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
]
"watchlistScreening": [
{
"id": "1411111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"searchDate": "2021-07-15T10:44:11.000Z",
"searchId": "12345678",
"searchReference": "1626345851-xxxxxx",
"searchResultUrl": "https://app.xxx.com/public/search/123456XXC-xxxx/xxxccc",
"searchResults": 0,
"searchStatus": "SUCCESS"
}
}
],
“addressValidation”: [
{
"id": "1511111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
}
],
“proofOfResidency”: [
{
"id": "1611111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
}
],
"drivingLicenseVerification": [
{
"id": "1711111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"credentials": [
{
"id": "33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
}
]
}
}
HTTP Request Method: GET
https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/credentials/<credentialId>/parts/<classifier>
https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/credentials/<credentialId>/parts/<classifier>
https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/credentials/<credentialId>/parts/<classifier>
Parameter | Type | Note |
---|---|---|
accountId | string | UUID of the account |
credentialId | string | UUID of the credential |
classifier | string | Possible values: • FRONT • BACK • FACE • FACEMAP |
Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available, has been deleted, or does not contain the image you requested. Successful requests will return HTTP status code 200 OK along with a JPG or PNG image and the appropriate header (e.g. Content-Type: image/jpeg).
GET
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/credentialsId/33333333-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Host: retrieval.apac-1.jumio.ai
User-Agent: User Demo
Authorization: Bearer xxx
HTTP Request Method: GET
https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/steps
https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/steps
https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>/steps
Parameter | Type | Note |
---|---|---|
accountId | string | UUID of the account |
workflowExecutionId | string | UUID of the workflow |
Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error. HTTP status code 404 Not Found will be returned if the transaction is not available, has been deleted, or is not a KYX workflow.
Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.
Parameter | Type | Note |
---|---|---|
steps | array (object) | See steps |
Parameter | Type | Note |
---|---|---|
id | string | UUID of the workflow step |
name | string | Workflow step name Possible values: • ADDRESS_VERIFICATION • DL_VERIFICATION • ID_IV • SCREENING |
capabilityIds | array (string) | List of the capabilityIds executed for this step |
decision | object | Possible values: • decision.risk • decision.risk.score • decision.type • decision.details • decision.details.label |
decision.risk | object | Possible values: • decision.risk.score |
decision.risk.score | double | Possible values: • 0.00 - 100.00 (max 2 decimal places) |
decision.type | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
decision.details | object | Possible values: • decision.details.label |
decision.details.label | string | Possible values: • NOT_EXECUTED • PASSED • REJECTED • WARNING |
GET
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx/steps HTTP/1.1
Host: retrieval.apac-1.jumio.ai
User-Agent: User Demo
Authorization: Bearer xxx
{
"steps": [
{
"id": "44111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "ID_IV",
"capabilityIds": [
"1111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"1211111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"1333111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"1311111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
],
"decision": {
"type": "PASSED",
"details": {
"label": "PASSED"
}
}
},
{
"id": "44211111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "SCREENING",
"capabilityIds": [
"1411111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
],
"decision": {
"type": "PASSED",
"details": {
"label": "PASSED"
}
}
},
{
"id": "44311111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "ADDRESS_VERIFICATION",
"capabilityIds": [
"1511111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
“1611111-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
],
"decision": {
"type": "PASSED",
"details": {
"label": "PASSED"
}
}
},
{
"id": "44411111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "DL_VERIFICATION",
"capabilityIds": [
"1711111-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
],
"decision": {
"type": "PASSED",
"details": {
"label": "PASSED"
}
}
}
]
}
Use this API to check the status of the Jumio services.
The following fields are required in the header section of your request:
Accept: application/json
User-Agent: YourCompany YourApp/v1.0
⚠️ Jumio requires the User-Agent
value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code __403 Forbidden__
HTTP Request Method: GET
https://status.amer-1.jumio.ai
https://status.emea-1.jumio.ai
https://status.apac-1.jumio.ai
Parameter | Type | Note |
---|---|---|
status | string | Possible values: • UP • DEGRADED • DOWN |
details | object | Possible values: • details.api • details.callback • details.mobile • details.processing • details.retrieval • details.web |
details.api | string | Possible values: • UP • DEGRADED • DOWN |
details.callback | string | Possible values: • UP • DEGRADED • DOWN |
details.mobile | string | Possible values: • UP • DEGRADED • DOWN |
details.processing | string | Possible values: • UP • DEGRADED • DOWN |
details.retrieval | string | Possible values: • UP • DEGRADED • DOWN |
details.web | string | Possible values: • UP • DEGRADED • DOWN |
> curl https://status.apac-1.jumio.ai
{
"status":"UP"
}
//
{
"status":"DEGRADED",
"details": {
"mobile":"DEGRADED",
"callback":"DEGRADED"
}
}
//
{
"status":"DOWN",
"details": {
"retrieval": "DOWN",
"callback": "DOWN",
"api":"DOWN"
}
}
Use this API to delete accounts or workflows.
The following fields are required in the header section of your request:
Accept: application/json
Authorization:
see RFC6749
User-Agent: YourCompany YourApp/v1.0
⚠️ Jumio requires the __User-Agent__ value to reflect your business or entity name for API troubleshooting.
ℹ️ Calls with missing or suspicious headers, suspicious parameter values, or without OAuth2 will result in HTTP status code __403 Forbidden__
Deletes the account and all related workflows to the account specified by accountId
.
HTTP Request Method: DELETE
https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>
https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>
https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>
Parameter | Type | Note |
---|---|---|
accountId | string | UUID of the account |
Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.
Successful requests will return HTTP status code 200 OK as confirmation that you have successfully deleted the image(s) and extracted data from the specified transaction record.
Deletes the workflow specified by workflowExecutionId
.
HTTP Request Method: DELETE
https://retrieval.amer-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
https://retrieval.emea-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
https://retrieval.apac-1.jumio.ai/api/v1/accounts/<accountId>/workflow-executions/<workflowExecutionId>
Parameter | Type | Note |
---|---|---|
accountId | string | UUID of the account |
workflowExecutionId | string | UUID of the workflow |
Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.
Successful requests will return HTTP status code 200 OK as confirmation that you have successfully deleted the image(s) and extracted data from the specified transaction workflow.
DELETE
/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Host: retrieval.apac-1.jumio.ai
User-Agent: User Demo
Authorization: Bearer xxx
© Jumio Corporation, 100 Mathilda Place, Suite 100, Sunnyvale, CA 94086