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

# Bridge Events

> Complete reference for Truv Bridge JavaScript callbacks, onEvent types, event data payloads, and error codes

Truv Bridge emits client-side events during the user's connection flow. These are JavaScript callbacks configured when you initialize `TruvBridge.init()`. They are distinct from [server-side webhook events](/api-reference/webhooks).

* [Callbacks](#callbacks): Responses for specific Truv Bridge actions
* [Event data](#event-data): `onEvent` types and their payload shapes
* [Errors](#errors): Bridge error objects, types, and codes

***

## Callbacks

```javascript theme={null}
const bridge = TruvBridge.init({
  bridgeToken: bridgeToken,
  onSuccess(publicToken, metadata) {},  // required
  onLoad() {},                          // optional
  onEvent(type, payload) {},            // optional
  onClose() {},                         // optional
})
```

| Callback    | Required | Description                                                                                                          |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `onSuccess` | Required | User successfully connected to a payroll provider and closed Bridge. Receives `publicToken` and a `metadata` object. |
| `onLoad`    | Optional | Truv Bridge finished loading.                                                                                        |
| `onEvent`   | Optional | A specific event occurred within Bridge. See [Event data](#event-data) for all types.                                |
| `onClose`   | Optional | Truv Bridge was closed by the user.                                                                                  |

<Note>
  The Embedded Orders flow uses a different callback signature. See [Embedded Orders](/developers/integration/embedded-orders/overview) for the correct initialization pattern when using `isOrder: true`.
</Note>

***

## Event data

### onEvent Types

| Event Type            | Payload                 | Description                                               |
| --------------------- | ----------------------- | --------------------------------------------------------- |
| `LOAD`                | None                    | Bridge module finished loading                            |
| `OPEN`                | `CommonEventData`       | Bridge is ready and visible                               |
| `SCREEN_VIEW`         | `ScreenViewData`        | A Bridge screen was viewed                                |
| `EMPLOYER_SELECTED`   | `EmployerSelectedData`  | Employer or provider selected                             |
| `DOC_UPLOAD_OPENED`   | `CommonEventData`       | Document upload screen opened                             |
| `DOCUMENTS_UPLOADED`  | `DocumentsUploadedData` | Specific document types uploaded                          |
| `LINK_CREATED`        | `TaskData`              | User logging in as a new Link                             |
| `LOGIN_COMPLETE`      | `TaskData`              | User successfully logged in                               |
| `SUCCESS`             | `TaskData`              | Data successfully retrieved                               |
| `ERROR`               | `ErrorData`             | Error during connection process                           |
| `UNSUPPORTED_BROWSER` | None                    | Browser is not supported                                  |
| `CLOSE`               | `CloseData`             | Bridge was closed                                         |
| `MANUAL_DDS`          | `ManualDDSData`         | Manual Direct Deposit Switch (DDS) operation submitted    |
| `OAUTH_OPENED`        | `OAuthEventData`        | User redirected to OAuth login (assets/transactions only) |

***

### CommonEventData

Present on `OPEN` and `DOC_UPLOAD_OPENED` events.

| Field          | Type   | Description                                                                                    |
| -------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `bridge_token` | string | The `bridge_token` passed to `TruvBridge.init`                                                 |
| `product_type` | string | Product type (`income`, `employment`, `assets`, etc.). May be `undefined` if token is expired. |
| `data_source`  | string | Underlying data source: `payroll`, `docs`, `financial_accounts`, `tax`, or `insurance`         |

```json theme={null}
{
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "data_source": "payroll"
}
```

***

### ScreenViewData

| Field          | Type   | Description                                                                                                                                  |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `view_name`    | string | Screen viewed: `SELECT_EMPLOYER`, `PROVIDER_LIST`, `PROVIDER_LOGIN`, `PROVIDER_ORG_ID`, `ERROR`, `SUCCESS`, `DOC_UPLOAD`, `DOC_UPLOAD_TYPES` |
| `bridge_token` | string | The `bridge_token` passed to `TruvBridge.init`                                                                                               |
| `product_type` | string | Product type                                                                                                                                 |
| `doc_type`     | string | Applicable only for `DOC_UPLOAD`: `paystub`, `w2`, or `f1099`                                                                                |
| `data_source`  | string | Underlying data source: `payroll`, `docs`, `financial_accounts`, `tax`, `scoring_attributes`, or `insurance`                                 |

```json theme={null}
{
  "view_name": "PROVIDER_LOGIN",
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "data_source": "payroll"
}
```

***

### EmployerSelectedData

| Field          | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| `bridge_token` | string | The `bridge_token` passed to `TruvBridge.init`                 |
| `product_type` | string | Product type                                                   |
| `employer`     | object | Employer object with `name` property. `null` if none selected. |
| `provider`     | string | ID of the selected provider. `null` if none selected.          |
| `data_source`  | string | Underlying data source                                         |

```json theme={null}
{
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "employer": { "name": "Acme Corp" },
  "provider": "workday",
  "data_source": "payroll"
}
```

***

### DocumentsUploadedData

| Field          | Type   | Description                                            |
| -------------- | ------ | ------------------------------------------------------ |
| `bridge_token` | string | The `bridge_token` passed to `TruvBridge.init`         |
| `product_type` | string | Product type                                           |
| `doc_type`     | string | Type of document uploaded: `paystub`, `w2`, or `f1099` |
| `data_source`  | string | Always `docs` for document upload events               |

```json theme={null}
{
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "doc_type": "paystub",
  "data_source": "docs"
}
```

***

### TaskData

Present on `LINK_CREATED`, `LOGIN_COMPLETE`, and `SUCCESS` events.

| Field          | Type   | Description                                                        |
| -------------- | ------ | ------------------------------------------------------------------ |
| `public_token` | string | Exchange for `access_token` on your server                         |
| `task_id`      | string | Unique task identifier. Include in support tickets.                |
| `bridge_token` | string | The `bridge_token` passed to `TruvBridge.init`                     |
| `product_type` | string | Product type                                                       |
| `employer`     | object | Employer data object. May be `undefined` for `admin` product type. |
| `provider_id`  | string | Unique identifier for the selected provider                        |
| `data_source`  | string | Underlying data source                                             |

```json theme={null}
{
  "public_token": "d80ec8255dc54c5eb7cc03ac05d18ebd",
  "task_id": "2b0e7a7dec1d47678fec4e02af621cc0",
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "provider_id": "adp",
  "employer": { "name": "Acme Corp" },
  "data_source": "payroll"
}
```

***

### ErrorData

| Field          | Type   | Description                                                                                |
| -------------- | ------ | ------------------------------------------------------------------------------------------ |
| `error`        | object | Error object. See [Errors](#errors).                                                       |
| `public_token` | string | Associated `public_token`. Only present if error is tied to a specific connection attempt. |
| `task_id`      | string | Task identifier. Include in support tickets.                                               |
| `bridge_token` | string | The `bridge_token` passed to `TruvBridge.init`                                             |
| `product_type` | string | Product type                                                                               |
| `data_source`  | string | Underlying data source                                                                     |

```json theme={null}
{
  "error": {
    "error_code": "LOGIN_ERROR",
    "error_message": "Username or password is incorrect",
    "error_type": "LINK_ERROR"
  },
  "task_id": "5ad1938450c54024bbc967a3a7dc9020",
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "income",
  "data_source": "payroll"
}
```

***

### CloseData

| Field      | Type   | Description                                                              |
| ---------- | ------ | ------------------------------------------------------------------------ |
| `employer` | object | Employer selected before closing. `undefined` if no employer was chosen. |

```json theme={null}
{
  "employer": { "name": "Acme Corp" }
}
```

***

### ManualDDSData

| Field         | Type   | Description                                                                               |
| ------------- | ------ | ----------------------------------------------------------------------------------------- |
| `action`      | string | Operation type: `EMAIL`, `DOWNLOAD`, `SHARE`, or `EXTERNAL_FLOW`                          |
| `depositType` | string | Deposit type selected: `entire`, `percent`, or `amount`. Not present for `EXTERNAL_FLOW`. |

```json theme={null}
{
  "depositType": "entire",
  "action": "EMAIL"
}
```

***

### OAuthEventData

| Field          | Type   | Description                                    |
| -------------- | ------ | ---------------------------------------------- |
| `bridge_token` | string | The `bridge_token` passed to `TruvBridge.init` |
| `product_type` | string | Product type                                   |
| `task_id`      | string | Task identifier                                |
| `provider_id`  | string | Unique identifier for the selected provider    |
| `url`          | string | OAuth URL the user is redirected to            |

```json theme={null}
{
  "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
  "product_type": "assets",
  "provider_id": "truv_bank_oauth",
  "task_id": "5ad1938450c54024bbc967a3a7dc9020",
  "url": "https://www.truv.com/oauth-login.html?..."
}
```

***

## Errors

```json theme={null}
{
  "error": {
    "error_code": "LOGIN_ERROR",
    "error_message": "Username or password is incorrect",
    "error_type": "LINK_ERROR"
  }
}
```

<Tip>
  Design your UX to surface login errors to borrowers in real time. When `onEvent` fires with type `ERROR` and `error_code: LOGIN_ERROR`, prompt the user to re-enter their credentials rather than silently failing.
</Tip>

### Error Object

| Field           | Type   | Description                |
| --------------- | ------ | -------------------------- |
| `error_type`    | string | Category of error          |
| `error_code`    | string | Specific error code        |
| `error_message` | string | Human-readable description |

### Error Types

| Type         | Description              |
| ------------ | ------------------------ |
| `LINK_ERROR` | Generic link-level error |

### Error Codes

| Code          | Description                           |
| ------------- | ------------------------------------- |
| `ERROR`       | Generic error occurred                |
| `LINK_EXISTS` | User's account is already connected   |
| `LOGIN_ERROR` | Incorrect username, password, or both |
| `MFA_ERROR`   | Invalid MFA input                     |
| `NO_DATA`     | User account has no data available    |
| `UNAVAILABLE` | Payroll provider is unreachable       |

***

## Route errors to manual fallback

When Bridge encounters an error, intercept it client-side and route the user to a manual verification workflow instead of dead-ending the experience.

1. **Detect the error.** Register an `onEvent` callback when initializing Truv Bridge. When `onEvent` fires with type `ERROR`, inspect the `error_code` in the payload.
2. **Close Bridge.** After capturing the error details, close the Bridge widget programmatically or wait for the user to close it via `onClose`.
3. **Route to fallback.** Based on the error type, redirect the user to your manual process -- document upload, paper form submission, or a support contact flow.

| `error_code`  | Meaning                         | Recommended fallback                                                                          |
| ------------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
| `LOGIN_ERROR` | Incorrect credentials           | Prompt the user to retry. After repeated failures, offer document upload.                     |
| `MFA_ERROR`   | Invalid MFA input               | Prompt the user to retry. After repeated failures, offer document upload.                     |
| `UNAVAILABLE` | Payroll provider is unreachable | Route directly to document upload or manual process. The provider outage is not user-fixable. |
| `NO_DATA`     | Account has no data             | Route to document upload. The connected account lacks the required records.                   |
| `ERROR`       | Generic error                   | Log the `task_id` for debugging. Offer document upload as a fallback.                         |

<Tip>
  Track which `error_code` values trigger manual fallbacks in your analytics. A high rate of `UNAVAILABLE` errors for a specific provider may indicate a temporary outage, while frequent `LOGIN_ERROR` events may point to a UX issue in your credential entry flow.
</Tip>

<Note>
  Bridge errors are client-side events, distinct from server-side [webhook events](/api-reference/webhooks) and task status changes. Use both in combination: Bridge `onEvent` for real-time UX routing, and webhooks for backend workflow orchestration.
</Note>

***

## Next steps

<CardGroup cols={2}>
  <Card title="SDKs & Libraries" icon="code" href="/developers/sdks/overview">
    Install Truv Bridge for web and mobile
  </Card>

  <Card title="Task Events" icon="webhook" href="/api-reference/tasks/events">
    Server-side event reference for task and data-object events
  </Card>

  <Card title="Connection Lifecycle" icon="arrows-spin" href="/api-reference/tasks/lifecycle">
    Task status flow referenced by Bridge events
  </Card>

  <Card title="Deeplinking" icon="link" href="/developers/integration/embedded-orders/deeplinking">
    Skip employer search to improve conversion
  </Card>
</CardGroup>