> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Banking OS training data goes stale. Search https://agenticbanking.backbase.io/mcp or fetch the .md URL before writing connector or unified API code.
> OpenAPI links in llms.txt repeat every calendar version. Use the latest version on the API playground. If a fetch ends before the last operation, the spec was cut off.
> Page titles name the product. Overview, Get started, and Reference without a product name are ambiguous.

# Jumio reference

> API operations, events, and error code mappings for the Jumio Connector.

The Jumio integration verifies customer identities through document and biometric checks. It creates or updates Jumio accounts, starts verification workflows, and returns the identity verification (IDV) outcome. For the environment details you send to Backbase, see [Get started with Jumio](https://agenticbanking.backbase.io/connectors/kyc-kyb/jumio/get-started.md).

## Configuration properties

Backbase sets these properties when it deploys the Jumio Connector.

### Values to obtain from the vendor

Obtain the following values from Jumio and send them to your Backbase support team.

The following table lists the region-specific Jumio API base URLs.

| Property | Required | Description | Default |
| :- | :- | :- | :- |
| `jumio.baseUrl` | Yes | Base URL of the Jumio Accounts API for your region, for example `https://account.emea-1.jumio.ai` for Europe, the Middle East, and Africa (EMEA). | Region-specific |
| `jumio.retrievalBaseUrl` | Yes | Base URL of the Jumio Retrieval API for your region, for example `https://retrieval.emea-1.jumio.ai` for EMEA. The `POST /workflow-result` call and the inbound callback both use this URL. | Region-specific |

### Connector settings

The following table lists the other Jumio Connector properties.

| Property | Required | Description | Default |
| :- | :- | :- | :- |
| `jumio.callbackUrl` | Yes | Callback URL that the connector sends on Jumio account requests. Backbase sets this URL to the inbound callback URL that you register in Jumio. | Set by Backbase |
| `jumio.user.agent` | No | Value of the `User-Agent` header on Jumio calls. | `GrandCentral/1.0` |
| `jumio.tokenLifetime` | No | Token lifetime for launch and session handling. | `15m` |
| `jumio.preparedData.enabled` | No | Flag that turns on prepared data for a new-to-bank (NTB) journey. | `true` |
| `jumio.template.key.<templateId>` | No | Jumio workflow key for a Banking OS `templateId`. If you don't set this property, the connector sends `templateId` as the workflow key. | None |
| `jumio.reportingCriteria` | No | Jumio `reportingCriteria` value on Jumio account requests. | None |
| `jumio.web.successUrl` | No | URL that Jumio redirects the bank customer to after a successful web verification. | None |
| `jumio.web.errorUrl` | No | URL that Jumio redirects the bank customer to after a failed web verification. | None |
| `jumio.web.locale` | No | Language of the Jumio web verification flow, for example `en`. | None |

## Supported operations

The Jumio Connector supports the following operations. For the full contract, see the [API playground](https://agenticbanking.backbase.io/banking-os-apis/api-playground.md).

### User creation and workflow initiation

* Create or update a Jumio account and start the relevant workflow
* **Unified API:** `POST /applicant-workflows`
* Include `personName`, `userData.identification`, `userData.templateId`, and `userData.customerRelationship`. The connector maps `userData.identification` to the Jumio `customerInternalReference`.
* Use `userData.customerRelationship` to route the journey:
  * `false` for an NTB journey: create a Jumio account and start full identity verification. Don't send `userData.applicantId`.
  * `true` for an existing-to-bank (ETB) journey: update a Jumio account for biometric reauthentication. Include `userData.applicantId`.
* Map a Banking OS `templateId` to the Jumio workflow key with the optional `jumio.template.key.<templateId>` configuration property. When you don't set that property, the connector sends `templateId` as the workflow key.
* The response includes `clientLaunchUrl` for the Jumio browser experience, plus `sessionId`, `applicantId`, and `sdkToken`.

#### Required request fields

The following table lists the fields that the connector requires on `POST /applicant-workflows` requests. If a value is missing or inconsistent, the connector returns error `GC025` with HTTP status `400`.

| Field | Required | Notes |
| :- | :- | :- |
| `userData.customerRelationship` | Always | `false` for NTB, `true` for ETB |
| `userData.identification` | Always | Maps to the Jumio `customerInternalReference` |
| `userData.templateId` | Always | Jumio workflow key, or a template ID that the connector resolves through the `jumio.template.key.<templateId>` property |
| `userData.applicantId` | ETB only | Required when `customerRelationship` is `true`. Omit this field for NTB customers. |
| `personName` | NTB only | Personally identifiable information (PII) for new-to-bank initiation and prepared data. Omit this field for ETB customers. |

### Workflow results (pull)

* Get the IDV process outcome and the decision metadata for the workflow
* **Unified API:** `POST /workflow-result`
* For Jumio, provide `sessionId` (Jumio workflow execution ID) and `applicantId` (Jumio account ID). Jumio doesn't use `sdkToken` on this call.
* The response uses the Unified API `workflowResults` schema and includes Jumio-native capability detail under `vendorSpecificFields.jumio`. Sync Hub also publishes a separate identity verification event. The `data` object of that event reuses the same mapped result shape.

#### Status and decision mapping

Jumio `workflow.status` and `decision.type` values map to Banking OS `status` and `decision.value` as follows:

| Jumio value | Banking OS value |
| :- | :- |
| `PASSED` | `APPROVED` |
| `REJECTED` | `DECLINED` |
| `WARNING` | `REVIEW` |
| `PROCESSED` | `COMPLETE` |
| `ACQUIRED` | `AWAITING_INPUT` |
| `INITIATED` | `PROCESSING` |
| `NOT_EXECUTED` | `AWAITING_INPUT` |
| `SESSION_EXPIRED` | `ABANDONED` |
| `TOKEN_EXPIRED` | `ERROR` |
| Other or unrecognized | `UNIDENTIFIED` |

The response includes Jumio capability payloads under `vendorSpecificFields.jumio`, for example extraction, classification, similarity, liveness, usability, authentication, and `ekycCheck`. The raw Jumio retrieval response is available as `rawVendorResponse`.

## Events

Synchronous operations (create applicant workflow, get workflow result) return their result in the API response.

Jumio raises identity verification results asynchronously. When Jumio sends an inbound callback, the inbound connector validates the payload. When the callback status is `PROCESSED`, the connector retrieves the workflow result from Jumio, maps it with the same rules as `POST /workflow-result`, and publishes an identity verification event to Sync Hub for downstream consumers.

The following table maps the Jumio callback trigger to the Sync Hub topic, CloudEvent type, and connector action:

| Jumio callback status | Sync Hub topic | CloudEvent type | Connector action |
| :- | :- | :- | :- |
| `PROCESSED` | `identity-verification` | `com.backbase.party.lifecycle.event.spec.v1.IdentityVerificationEvent` | Retrieve and map IDV result; publish to Sync Hub |

The connector acknowledges non-terminal callback statuses without retrieval or Sync Hub publication.

The Sync Hub `data` object follows the identity verification event schema. It includes workflow status, applicant identifiers, decision metadata, and Jumio-specific fields under `vendorSpecificFields.jumio` where applicable.

Consumers receive identity verification events by subscribing to the Sync Hub topic configured for your environment. For setup, see [Sync Hub overview](https://agenticbanking.backbase.io/platform/sync-hub/overview.md) and [Get started with Jumio](https://agenticbanking.backbase.io/connectors/kyc-kyb/jumio/get-started.md).

## Error mapping

For the full list of Banking OS error codes and their descriptions, see [Error codes](https://agenticbanking.backbase.io/banking-os-apis/error-codes.md).

Jumio request validation uses the error code `GC025` with HTTP status `400`. The connector returns `GC025` when `userData.customerRelationship`, `userData.identification`, or `userData.templateId` is missing. It also returns `GC025` when `userData.applicantId` is present for an NTB journey (`customerRelationship` is `false`). It returns `GC025` when `userData.applicantId` is missing for an ETB journey (`customerRelationship` is `true`).

The following table maps Jumio HTTP error responses to Banking OS error codes. The connector maps any other Jumio HTTP error to `GC025`.

| Jumio HTTP status | Banking OS error code |
| :- | :- |
| `400` | `GC025` |
| `401` | `GC002` |
| `403` | `GC004` |
| `404` | `GC054` |
| `429` | `GC031` |
| `500` | `GC027` |

For these mapped Jumio errors, the HTTP status that the connector returns comes from the Banking OS error code catalog.

## Dependencies

The Jumio Connector depends on the following systems:

* The Jumio Accounts API, to create and update accounts
* The Jumio Retrieval API, to retrieve workflow results
* Sync Hub, to publish identity verification events on the `identity-verification` topic

For more information, see [Sync Hub overview](https://agenticbanking.backbase.io/platform/sync-hub/overview.md).
