View or Retrieve Workflow Transactions

Workflow transactions record end-user activity and provide decisions, risk scores, and credential evaluation results. Each transaction includes:

Metadata: Unique transaction ID, account ID, and UTC timestamps.
Service Information: Decisions and scores returned, rules triggered, and credentials evaluated.
Transaction decisions and risk scores: Overall decision, risk score, and rules applied to determine the outcome.

Transactions can be:

Viewed in the Jumio Portal.
Retrieved programmatically via 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.

note

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

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

tip

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.

info

The values of any rules that are triggered by the transaction also impact the overall score. See Rules Management.

Calling Retrieval APIs

Use the Retrieval APIs to programmatically fetch workflow transactions, credentials, and risk scores, enabling automated access to transaction data.

These APIs provide the following capabilities:

Workflow Status: Obtain the processing status of a transaction. Depending on the workflow, a transaction may take several minutes to complete. The Status API helps determine when the transaction details are available.
Workflow Details: Retrieve workflow metadata, credentials (including URLs for accessing each credential part), and the capabilities executed during the workflow.
Workflow Steps: Get information about each service called during the workflow and the capabilities executed for that service.
Individual Workflow Credentials: Access specific credentials associated with a transaction.
PDF Transaction Report: Download a transaction report as a PDF via a provided URL.

For the complete API specification see: Retrieval API Reference

Retrieval Best Practices and Recommended Retry Policy

Before retrieving transaction details, ensure that the transaction is complete:

If you have implemented a Callback service, wait for the callback before requesting the transactions details.
Alternatively, use the Workflow Status API. If the transaction status is:
- PROCESSED: The transaction is complete, and details/images can be retrieved.
- 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:

Start with an initial retry after 40 seconds.
Allow a maximum of 10 consecutive unsuccessful retrieval attempts after receiving the callback.
Recommended retry intervals(in seconds): 40, 60, 100, 160, 240, 340, 460, 600, 760, 940

important

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 approach avoids 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": "10549",
    "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.

tip

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 Jumio End-User Consent Documentation.

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 Jumio End-User Consent Documentation.
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.

info

Detail requests are subject to Rate Limits.

Example: Details Response

Details

{
  "workflow": {
    "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
    "status": "PROCESSED",
    "definitionKey": "10549",
    "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	Contains the extracted and processed data from the uploaded credentials.
DATA	DEVICE_RISK	Contains risk-related information about the device used during the transaction.
ID	FRONT_CROPPED	Cropped image of the front side of the ID captured by the user during the front-side capture process.(Planned for mid January 2026)
ID	BACK_CROPPED	Cropped image of the back side of the ID captured by the user during the back-side capture process. (Planned for mid January 2026)
SELFIE	FACE_CROPPED	Cropped image of the user’s face captured during the selfie capture process. (Planned for early-mid February 2026)

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:

camera if the camera in the end user's device was used to capture the image.
upload if 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 ..."
}

Transaction Decisions and Risk Scores​

Risk Scores​

Decision Types​

Decision Details Labels​

Capability Decisions​

Calling Retrieval APIs​

Retrieval Best Practices and Recommended Retry Policy​

Workflow Status​

Workflow Details​

Workflow Steps​

Workflow Credentials​

Classifier Values and Return Types​

captureType Value​

PDF Generation​

Table of Contents