View/Retrieve Workflow Transactions
The results of a workflow execution are recorded as a transaction. The transaction data includes:
- Metadata including the unique transaction ID, the account ID, and UTC timestamps.
- Information about the service(s) that were used by the transaction, including:
- The decision and score returned by the service.
- The rules that were fired to determine the service score and decision.
- The credentials evaluated by the service.
- Information about Transaction Decisions and Risk Scores including:
- The decision rendered for the transaction.
- The risk score for the transaction.
- The rules that were fired to determine the transaction score and decision.
Transactions can be:
- Viewed in the Jumio Portal, (refer Explorer).
- Retrieved programmatically by calling the Retrieval APIs.
See Calling Retrieval APIs
Transaction Decisions and Risk Scores
Each executed transaction includes a decision. The decision is based on the risk scorethat indicates the overall level of fraud risk for the transaction. The decision is provided as a JSON object in the Workflow Details response and can be seen in the Portal.
Example: Decision Object
"decision": {
"type": "WARNING",
"details": {
"label": "WARNING"
},
"risk": {
"score": 50.0
}
}
Risk Scores
Scores for transactions range from -1 to 100, with:
- -1 indicating that the workflow was not executed.
- 0 indicating no identified risk.
- 100 indicating extremely high risk.
Transactions that are started but not completed are assigned a score of -1 and a decision:type value of NOT_EXECUTED. This usually happens when the end-user exits the process before submitting the necessary credentials.
"decision": {
"type": "NOT_EXECUTED",
"details": {
"label": "TOKEN_EXPIRED"
},
"risk": {
"score": -1.0
}
},
Decision Types and Labels
The transactions is assigned a decision type value based on the score. By default the decision types are determined as follows:
- PASSED = 0-30
- WARNING = 31-70
- REJECTED = 71-100
- NOT_EXECUTED = -1
The decision type thresholds can be configured to meet your needs and risk appetite. Contact Jumio Support.
Decision Details Labels
| Decision Type | Label | Description |
|---|---|---|
| PASSED | PASSED | Label is the same as the type value. |
| REJECTED | REJECTED | Label is the same as the type value. |
| WARNING | WARNING | Label is the same as the type value. |
| NOT_EXECUTED | TOKEN_EXPIRED | The bearer token obtained from the Creating or Updating Accounts response expired prior to finalization. |
| NOT_EXECUTED | SESSION_EXPIRED | The session expired prior to finalization. |
Capability Decisions
Each capability or risk signal that is called by the transaction workflow returns its own risk score and decision type. For transactions that call a single service, the transaction score and decision type are the same as the service score. However, the service is first assigned a decision type based on factors specific to each service, and the service score depends on the decision type:
- PASSED = 0
- WARNING = 50
- REJECTED = 100
- NOT_EXECUTED = -1
See the reference topics listed under Capabilities Overview and Risk Signals for descriptions of when and why the decision types are assigned.
For workflows that call multiple services or risk signals, the overall transaction score is calculated from the weighted average of each of the services. Weights are applied so that more significant services and signals have a greater impact on the overall score.
The values of any rules that are triggered by the transaction also impact the overall score. See Rules Management.
Calling Retrieval APIs
APIs are available for retrieving:
- Workflow Status to obtain the processing status of the transaction. Depending on the workflow being executed the transaction may take up to several minutes to complete. The Status API provides a way to determine when the transaction details are actually available.
Workflow Details including the workflow metadata, credentials (including URLs for accessing each credential part), and the capabilities that were executed. - Workflow Steps with information about each service that was called, and the capabilities that were executed for that service.
- Individual Workflow Credentials.
- A URL that allows you to download a PDF transaction report
For the complete API specification see: Retrieval API Reference
Retrieval Best Practices
Make sure the transaction is complete before retrieving the detail data:
- lf you have implemented a Callback service, wait for the callback before requesting the transactions details.
- Alternatively, call the Workflow Status API. If the transaction status is:
- PROCESSED you can retrieve the details and images.
- SESSION_EXPIRED or TOKEN_EXPIRED, the transaction was unsuccessful and details will not be available.
Recommended Retry Policy
To accommodate any brief interruptions to the retrieval service Jumio recommends you implement a retry policy with an initial retry after 40 seconds and a maximum of 10 consecutive unsuccessful retrieval attempts after receiving the callback. The recommended timings are 40, 60, 100, 160, 240, 340, 460, 600, 760, and 940 seconds.
If the transaction status remains UNPROCESSED after 940 seconds (approx. 15.5 minutes) of retrying using the recommended exponential backoff strategy, you should:
- Stop further retrieval attempts.
- Check the Jumio Status Page for any known incidents or delays.
- If no issue is reported, reach out to Jumio Support for further investigation.
This helps avoid unnecessary load on your system and Jumio's APIs during potential service incidents or processing delays.
Workflow Status
The Status API returns information about the status of the transaction. This is typically used to verify that the transaction has completed before retrieving the details.
Example Status Response
{
"account": {
"id": "42ff9aeb-62ce-4481-99bd-b56346a4ba1a",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/42ff9aeb-62ce-4481-99bd-b56346a4ba1a"
},
"workflowExecution": {
"id": "c3257562-941c-440c-bc9b-f59478bb48ef",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/workflow-executions/c3257562-941c-440c-bc9b-f59478bb48ef",
"definitionKey": "10011",
"status": "PROCESSED"
}
}
| 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 |
| workflowExecution.status | string | Possible values: - INITIATED Waiting for credentials to be uploaded and the transaction finalized. - ACQUIRED Transaction has been finalized but processing has not completed. - PROCESSED The transaction is completed. - SESSION_EXPIRED The session expired prior to finalization. - TOKEN_EXPIRED The authorization token expired prior to finalization. |
Workflow Details
The Execution Details API returns detailed information about:
- The workflow metadata and execution timestamps in UTC:
createdAt
The timestamp when the end user started the customer journey.startedAt
The timestamp when the workflow execution started, following the call to finalize after all credentials were uploaded.completedAt
The timestamp when the transaction was completed, the decision was available, and the documents saved.
- An array of the credentials that were evaluated, including URLs for accessing the credential parts.
See also: Credential Reference for information about the various types of credentials.
If enabled for your tenant, each credential object will include a "consent" object with information on if and when the end user consent was obtained. See also: End-User Consent to Collect Personal Data.
- The overall decision that was rendered by the workflow.
See Transaction Decisions and Risk Scores. - If enabled for your tenant, a
"consent"object with information on if and when the end user consent was obtained.
See also: End-User Consent to Collect Personal Data. - An array of the capabilities that were executed, with details on the decision that was rendered by the capability, and any additional data returned by the capability. See also: Capabilities Reference.
Detail requests are subject to Rate Limits.
Example: Details Response
Details
{
"workflow": {
"id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
"status": "PROCESSED",
"definitionKey": "10011",
"userReference": "MyUser",
"customerInternalReference": "MyCompany"
},
"account": {
"id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
},
"createdAt": "2022-11-28T23:45:02.528Z",
"startedAt": "2022-11-28T23:50:37.221Z",
"completedAt": "2022-11-28T23:50:55.232Z",
"credentials": [
{
"id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
"category": "SELFIE",
"parts": [
{
"classifier": "FACE",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
}
],
"consent": {
"decisionAccepted": true,
"collectedBy": "CUSTOMER"
}
},
{
"id": "e25c0737-5753-4812-ab5c-94813e067ec9",
"category": "FACEMAP",
"parts": [
{
"classifier": "FACEMAP"
},
{
"classifier": "LIVENESS_1",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_1"
},
{
"classifier": "LIVENESS_3",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_3"
},
{
"classifier": "LIVENESS_2",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_2"
},
{
"classifier": "LIVENESS_5",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_5"
},
{
"classifier": "LIVENESS_4",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_4"
},
{
"classifier": "LIVENESS_6",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/e25c0737-5753-4812-ab5c-94813e067ec9/parts/LIVENESS_6"
}
],
"consent": {
"decisionAccepted": true,
"collectedBy": "CUSTOMER"
}
},
{
"id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
"category": "ID",
"parts": [
{
"classifier": "FRONT",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT"
},
{
"classifier": "BACK",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
}
],
"consent": {
"decisionAccepted": true,
"collectedBy": "CUSTOMER"
}
}
],
"decision": {
"type": "WARNING",
"details": {
"label": "WARNING"
},
"risk": {
"score": 50.0
}
},
"consent": {
"obtained": "yes",
"obtainedAt": "2022-11-28T23:50:40.136Z"
},
"steps": {
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/steps"
},
"capabilities": {
"extraction": [
{
"id": "5483e41e-08a7-4d9d-a09d-9f21e41b9e72",
"credentials": [
{
"id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"type": "DRIVING_LICENSE",
"subType": "REGULAR_DRIVING_LICENSE",
"issuingCountry": "USA",
"firstName": "JOHN JACOB",
"lastName": "SMITH",
"dateOfBirth": "1969-01-18",
"expiryDate": "2025-01-18",
"issuingDate": "2019-12-26",
"documentNumber": "N1234567",
"state": "CA",
"gender": "M",
"currentAge": "54"
}
}
],
"similarity": [
{
"id": "1fc799e4-f0ba-4dde-aaae-af857eef7b6e",
"credentials": [
{
"id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
"category": "SELFIE"
},
{
"id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "MATCH"
}
},
"data": {
"similarity": "MATCH"
}
}
],
"liveness": [
{
"id": "789f4e4a-7c2f-4764-a98d-c519d082ba6d",
"credentials": [
{
"id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
"category": "SELFIE"
},
{
"id": "e25c0737-5753-4812-ab5c-94813e067ec9",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"type": "JUMIO_STANDARD",
"predictedAge": 44,
"ageConfidenceRange": "32-56"
}
}
],
"dataChecks": [
{
"id": "da2a93b5-8a1f-4db6-bdfa-fb57ada57b12",
"credentials": [
{
"id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
],
"imageChecks": [
{
"id": "b336a404-7775-4793-9cf6-30a7e5be1d0b",
"credentials": [
{
"id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
"category": "SELFIE"
},
{
"id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
"category": "ID"
}
],
"decision": {
"type": "WARNING",
"details": {
"label": "REPEATED_FACE"
}
},
"data": {
"faceSearchFindings": {
"status": "DONE",
"findings": [
"22771260-8cb0-42a2-a38a-d8f853063cc2",
"27232651-4b18-4cf1-8d4a-df0451abc717",
"9541ae91-834e-4914-a30d-6534fed4eb6d",
"9414413d-2c76-44d2-9052-8876fa327a02"
]
}
}
}
],
"usability": [
{
"id": "1bb41666-2745-4c9a-bd5f-d0e338d0242b",
"credentials": [
{
"id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
"category": "ID"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
},
{
"id": "db0fd83a-5f9f-4739-94f7-7868194ba1dc",
"credentials": [
{
"id": "e25c0737-5753-4812-ab5c-94813e067ec9",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
},
{
"id": "e991586b-3345-4a2d-bfc3-1690ccb477b3",
"credentials": [
{
"id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
"category": "SELFIE"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
]
}
}
Workflow Steps
The Steps API returns details about the services that were called by the workflow. The response includes a "steps" array that contains an object for each service that was called as a workflow step. Each step object contains the decision rendered by that service, a "capabilities" aray that contains an object for each capability that was executed as part of the step, and an array that simply lists the IDs of each capability that was called.
Example: Steps Response
Details
{
"steps": [
{
"id": "73898f70-edd5-4bff-8d15-8f6e9eb81329",
"name": "ID_IV",
"decision": {
"type": "WARNING",
"details": {
"label": "WARNING"
}
},
"capabilities": [
{
"id": "1bb41666-2745-4c9a-bd5f-d0e338d0242b",
"category": "usability"
},
{
"id": "db0fd83a-5f9f-4739-94f7-7868194ba1dc",
"category": "usability"
},
{
"id": "e991586b-3345-4a2d-bfc3-1690ccb477b3",
"category": "usability"
},
{
"id": "b336a404-7775-4793-9cf6-30a7e5be1d0b",
"category": "imageChecks"
},
{
"id": "da2a93b5-8a1f-4db6-bdfa-fb57ada57b12",
"category": "dataChecks"
},
{
"id": "5483e41e-08a7-4d9d-a09d-9f21e41b9e72",
"category": "extraction"
},
{
"id": "1fc799e4-f0ba-4dde-aaae-af857eef7b6e",
"category": "similarity"
},
{
"id": "789f4e4a-7c2f-4764-a98d-c519d082ba6d",
"category": "liveness"
}
],
"capabilityIds": [
"1bb41666-2745-4c9a-bd5f-d0e338d0242b",
"db0fd83a-5f9f-4739-94f7-7868194ba1dc",
"e991586b-3345-4a2d-bfc3-1690ccb477b3",
"b336a404-7775-4793-9cf6-30a7e5be1d0b",
"da2a93b5-8a1f-4db6-bdfa-fb57ada57b12",
"5483e41e-08a7-4d9d-a09d-9f21e41b9e72",
"1fc799e4-f0ba-4dde-aaae-af857eef7b6e",
"789f4e4a-7c2f-4764-a98d-c519d082ba6d"
]
}
]
}
Workflow Credentials
You can use the GET parts API to download the credential images and data that are associated with a transaction
The fully parameterized URLs for retrieving the credential parts are available in the Workflow Details response.
Example
"credentials": [
{
"id": "66e0a64a-4afe-4e29-89e7-ae53db4aba93",
"category": "ID",
"clientIp": "xx.xx.xxx.xxx",
"parts": [
{
"classifier": "FRONT",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/6fec5b29-0e4c-42c4-b41f-72dc45307e53/credentials/66e0a64a-4afe-4e29-89e7-ae53db4aba93/parts/FRONT",
"captureType": "camera"
}
]
}
],
There will be a URL for each uploaded credential part. The part can be downloaded with a GET request to the URL. Authorization requires a valid bearer token for your tenant. See Authorization for information about obtaining the bearer token.
The form of the URLs is:
https://retrieval.{data_center}/api/v1/accounts/{accountId}/credentials/{credentialId}/parts/{classifier}
Classifier Values and Return Types
The response body of a successful request will contain the credential part as it was stored at the conclusion of the transaction.
| Credential | Type | Classifier Description |
|---|---|---|
| ID | FRONT | The file may be a PNG or a JPEG, depending on what was uploaded. |
| ID | FRONT_WITH_FLASH | If the ID was captured on a mobile device with a flash the image taken with the flash is available in addition to the non-flash FRONT image. |
| ID | BACK | The file may be a PNG or a JPEG, depending on what was uploaded. |
| SELFIE | FACE | The file may be a PNG or a JPEG, depending on what was uploaded. |
| FACEMAP | LIVENESS_n | The parts for a FACEMAP credential typically include one or several JPEG images that can be downloaded using the URLs with the LIVENESS_n classifiers. |
| DOCUMENT | ORIGIN | If a PDF was uploaded, it will be available using the URL with the ORIGIN classifier. Individual pages will also be available as JPEG files using URLs with the page number as the classifier. For example,to download the JPEG image of page 2 use: /parts/2 |
| DATA | PREPARED_DATA | |
| DATA | DEVICE_RISK |
captureType Value
The captureType will only be returned if your tenant is enabled. Contact Support if you are interested in this feature.For ID and Selfie parts, the captureType value indicates how the part was captured by the end user. Values may be:
cameraif the camera in the end user's device was used to capture the image.uploadif the image was uploaded from the end user's device.
PDF Generation
The Generate API returns a presigned URL that can be used to download a transaction report as a PDF. This document provides the overall decision and risk score for the transaction as well as the decision and summary information returned by each capability executed by the workflow.
The PDF transaction report is identical to the PDF accessible from the transaction details page in the Jumio Portal.
Example: PDF Generation Response
{
"workflowId": "8a68ee36-1663-473c-ae32-924ecdb0f33f",
"presignedUrl": "https://core-us-prod-kyx-transaction-pdf.s3.us-east-1.amazonaws.com/8a68ee36-1663-473c-ae32-924ecdb0f33f.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIA373BKWO4OBSY5POP%2F20240520%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240520T180143Z&X-Amz-Expires=7200&X-Amz-Security-Token=IQoJb3JpZ2luX2VjELr%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLW ..."
}