> ## 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.

# Get started with Jumio

> Prepare Jumio credentials and test the Jumio Connector.

Follow the steps in [Get started with connectors](https://agenticbanking.backbase.io/banking-os-connectors/get-started.md) before proceeding.

**Jumio access**: An active Jumio contract with accounts and credentials for Jumio test and production services.

**Workflow**: Before you start an identity verification, confirm the Jumio workflow keys or template keys your bank uses for new-to-bank (NTB) and existing-to-bank (ETB) journeys.

**Network connectivity**: Confirm routing between the Jumio environments and Banking OS Connectivity. For supported options, see [Network connectivity](https://agenticbanking.backbase.io/platform/network-connectivity.md).

**Sync Hub**: A Sync Hub consumer subscription if a downstream consumer receives identity verification results. For more information, see [Sync Hub overview](https://agenticbanking.backbase.io/platform/sync-hub/overview.md).

**Environment details**: You need the following environment details from Jumio:

| Parameter | Description |
| - | - |
| `jumio.baseUrl` | Region-specific base URL of the Jumio Accounts API |
| `jumio.retrievalBaseUrl` | Region-specific base URL of the Jumio Retrieval API |
| `jumio.template.key.<templateId>` | Optional override from a Banking OS `templateId` to a Jumio workflow key (for example NTB `10547` and ETB `10014`) |

## Prepare the connector

Backbase deploys this connector. To share connectivity details and provide the environment details, follow these steps:

1. **Share connectivity details.**

   Share connectivity details between Banking OS and Jumio as described in [Network connectivity](https://agenticbanking.backbase.io/platform/network-connectivity.md).

2. **Send environment details to Backbase.**

   Send `jumio.baseUrl`, `jumio.retrievalBaseUrl`, and any `jumio.template.key.<templateId>` overrides to your Backbase support team.

3. **Register the webhook with Jumio.**

   Ask your Backbase support team for the inbound callback URL. Register that URL in your Jumio callback configuration. Backbase sets the `jumio.callbackUrl` configuration property to the same URL.

4. **Configure Sync Hub consumption.**

   Configure your consumer to subscribe to the Sync Hub topic `identity-verification` and to parse the CloudEvent type `com.backbase.party.lifecycle.event.spec.v1.IdentityVerificationEvent`. For the `data` payload fields, see [Jumio reference](https://agenticbanking.backbase.io/connectors/kyc-kyb/jumio/reference.md).

For property names and defaults, see [Jumio reference](https://agenticbanking.backbase.io/connectors/kyc-kyb/jumio/reference.md).

## Test your integration

To use the Party Lifecycle Unified API, include your Banking OS subscription key in the request header. If you don't have a key, contact your Backbase support team to request one.

| Key | Value |
| :- | :- |
| `api-key` | `YOUR_SUBSCRIPTION_KEY` |

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

To create an applicant and start a workflow, call `POST /applicant-workflows`. Include `personName`, `userData.identification`, `userData.templateId`, and `userData.customerRelationship`. The connector maps `userData.identification` to the Jumio `customerInternalReference`. For an NTB journey, set `customerRelationship` to `false` and don't send `userData.applicantId`. For an ETB journey, set `customerRelationship` to `true` and include `userData.applicantId`. The response includes `clientLaunchUrl` for the Jumio browser experience, plus `sessionId`, `applicantId`, and `sdkToken`.

To retrieve results on demand, call `POST /workflow-result` with `sessionId` and `applicantId`. Jumio doesn't use `sdkToken` on this call.

## Troubleshooting

If your connector doesn't respond as expected, check these common scenarios.

> [accordion] 5xx: internal server error or core system down
>
> **Cause:** The Banking OS gateway can't establish a handshake with the Jumio endpoint. This typically indicates an upstream service outage at Jumio or a network routing failure.
>
> **Solution:** Verify the operational status of the Jumio environment with Jumio.

> [accordion] 5xx: timeout or SocketTimeoutException
>
> **Cause:** The request to Jumio exceeded the configured timeout threshold. This can occur during high load or network latency issues.
>
> **Solution:** Verify the operational status of the Jumio environment with Jumio.

> [accordion] Invalid authentication
>
> **Cause:** You entered incorrect credentials during setup.
>
> **Solution:** Verify your credentials with Jumio and contact your Backbase support team to update the connection.

> [accordion] 429: rate limit exceeded
>
> **Cause:** The number of incoming requests exceeded the defined threshold for your subscription tier. This response protects the stability of the Banking OS and partner infrastructure.
>
> **Solution:** Review your request patterns to identify unexpected spikes. If you require higher throughput, contact your Backbase support team to request an adjustment to your Azure API Management (APIM) rate limit policy.

> [accordion] Create applicant workflow validation fails
>
> **Cause:** Required Jumio fields are missing or inconsistent, for example `customerRelationship`, `identification`, `templateId`, `personName`, or an ETB `applicantId`.
>
> **Solution:** Confirm `customerRelationship` is set. For ETB (`true`), include `applicantId`. For NTB (`false`), omit `applicantId`. Confirm that `templateId` resolves to a configured Jumio workflow key. Include `personName` and `identification`.

> [accordion] Identity verification events not received on Sync Hub
>
> **Cause:** You haven't registered the Jumio callback, inbound authentication failed, the callback status is not `PROCESSED`, Sync Hub publishing isn't enabled, or your consumer doesn't subscribe to the `identity-verification` topic.
>
> **Solution:** Confirm that Jumio delivers callbacks to the Banking OS inbound URL. Verify that retrieval succeeds after `PROCESSED`, that Sync Hub publishing is enabled, and that your consumer subscription is active.
