Events Reference

View reference information for Truv Bridge callbacks, events, and errors.

Overview

Truv Bridge provides payload responses with user interaction data. Find information for Truv Bridge responses below.

  • Callbacks - Responses for specific Truv Bridge actions
  • Event data - Event type and payload descriptions
  • Errors - Truv Bridge error objects, types, and codes

Callbacks

This section describes the callbacks for the standard Truv Bridge flow. The Embedded Order flow uses a different callback signature – see the Initiate Truv Bridge for Embedded Flow section for details.

const bridge = TruvBridge.init({
  bridgeToken: bridgeToken,
  onSuccess(publicToken, metadata) {},
  // Optional callbacks
  onLoad() {},
  onEvent(type, payload) {},
  onClose() {},
})

The functions in this table cover specific actions.

Callback

Description

Required

onSuccess

User has successfully connected to a payroll provider and closed

Bridge

, function expects two arguments, the 

public_token

 and a metadata object

required

onLoad

Truv Bridge

has finished loading

optional

onEvent

Specific event occurs with

Truv Bridge

, see

Event data

optional

onClose

Truv Bridge

closes

optional

Event data

The sections below cover values and descriptions for events within Truv Bridge.

onEvent types

These event types are for specific actions occurring within Truv Bridge.

Event TypeEvent PayloadDescription
LOADNoneTruv Bridge module finished loading
OPENCommonEventDataTruv Bridge is ready
SCREEN_VIEWScreenViewDataTruv Bridge screen viewed
EMPLOYER_SELECTEDEmployerSelectedDataEmployer or provider selected in Truv Bridge
DOC_UPLOAD_OPENEDCommonEventDataDocument Upload opened
DOCUMENTS_UPLOADEDDocumentsUploadedDataSpecific document types uploaded
LINK_CREATEDTaskDataUser logging in to their payroll provider as a new Link
LOGIN_COMPLETETaskDataUser successfully logged in to payroll provider
SUCCESSTaskDataUser data successfully retrieved from payroll provider
ERRORErrorDataError during the payroll provider connection process
UNSUPPORTED_BROWSERNoneTruv Bridge is not supported by the user's browser
CLOSECloseDataTruv Bridge closes
MANUAL_DDSManualDDSDataManual DDS operation was successfully submitted
OAUTH_OPENEDOAuthEventDataSent when the user is redirected to a financial institution's login page, for assets and transactions product only

Common Event Data

The values in the table below are for general Truv Bridge metadata.

Name

Type

Description

bridge_token

string

The bridge_token value passed to TruvBridge.init

product_type

string

Type of product, can be undefined if bridge_token is expired

data_source

string

Optional. The data source that underlies the Truv Bridge viewed by the user.
Possible values: payroll, docs, financial_accounts, tax, insurance

Common Event example response

View the JSON object sample response below for Common Event Data.

{
    "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
    "product_type": "income",
    "data_source": "payroll"
}

ScreenViewData

This table has data for the Truv Bridge screen events.

Name

Type

Description

view_name

string

Name of Truv Bridge screen viewed
Possible values: SELECT_EMPLOYER, PROVIDER_LIST, PROVIDER_LOGIN, PROVIDER_ORG_ID, ERROR, SUCCESS, DOC_UPLOAD, DOC_UPLOAD_TYPES

bridge_token

string

Value for bridge_token passed to TruvBridge.init

product_type

string

Type of product

doc_type

string

Applicable for only DOC_UPLOAD view name, type of documents to upload, can be paystub, w2 or f1099

data_source

string

The data source that underlies the Truv Bridge viewed by the user.
Possible values: payroll, docs, financial_accounts, tax, scoring_attributes, insurance

{
    "view_name": "PROVIDER_LOGIN",
    "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
    "product_type": "income",
    "data_source": "payroll"
}

EmployerSelectedData

This data is for events during the employer or provider selection process.

Name

Type

Description

bridge_token

string

Value for bridge_token  passed to TruvBridge.init

product_type

string

Type of product

employer

object

Object with employer data, contains employer's name, can be null

provider

string

ID of the selected provider, can be null

data_source

string

The data source that underlies the Truv Bridge viewed by the user.
Possible values: payroll, docs, financial_accounts, tax, scoring_attributes, insurance

EmployerSelectedData example response

The sample JSON object below is for EmployerSelectedData.

{
    "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
    "product_type": "income",
    "employer": {
        "name": "Facebook Demo"
    },
    "provider": "workday",
    "data_source": "payroll"
}

DocumentsUploadedData

The table below covers events from uploading documents.

Name

Type

Description

bridge_token

string

Value for bridge_token passed to TruvBridge.init

product_type

string

Type of product

doc_type

string

Type of document uploaded, can be paystub, w2 or f1099

data_source

string

The data source that underlies the Truv Bridge viewed by the user.
Possible values: payroll, docs, financial_accounts, tax, scoring_attributes, insurance

DocumentsUploadedData example response

The JSON object below is a sample response.

{
    "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
    "product_type": "income",
    "doc_type": "paystub",
    "data_source": "docs"
}

TaskData

The values in the table below cover events from Tasks.

Name

Type

Description

public_token

string

Value for public_token exchanged for access_token

task_id

string

Unique identifier to use Link when attempting to retrieve payroll data
NOTE: include identifier value for support tickets

bridge_token

string

Value for bridge_token passed to TruvBridge.init

product_type

string

Type of product

employer

object

Employer data object, contains employer's name, may be undefined for admin product type

provider_id

string

Unique identifier for selected provider

data_source

string

The data source that underlies the Truv Bridge viewed by the user.
Possible values: payroll, docs, financial_accounts, tax, scoring_attributes, insurance

TaskData example response

View the JSON object below for a sample response.

{
    "public_token": "d80ec8255dc54c5eb7cc03ac05d18ebd",
    "task_id": "2b0e7a7dec1d47678fec4e02af621cc0",
    "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
    "product_type": "income",
    "provider_id": "adp",
    "employer": {
      "name": "Facebook Demo"
    },
    "data_source": "payroll"
}

ErrorData

Values in the table below are responses for errors.

Name

Type

Description

error

Error

See Errors section for reference

public_token

string

Associated public_token to connection attempt
NOTE: This field is only available if the error returned is associated to apublic_token.

task_id

string

Unique identifier associated with attempt to use Link to retrieve payroll data
NOTE: Include this identifier when opening a support ticket for additional support.

bridge_token

string

Value for bridge_token passed to TruvBridge.init

product_type

string

Type of the product

data_source

string

The data source that underlies the Truv Bridge viewed by the user.
Possible values: payroll, docs, financial_accounts, tax, scoring_attributes, insurance

{
    "error": {
        "error_code": "LOGIN_ERROR",
        "error_message": "Username or password is incorrect",
        "error_type": "LINK_ERROR"
    },
    "public_token": "d80ec8255dc54c5eb7cc03ac05d18ebd",
    "task_id": "5ad1938450c54024bbc967a3a7dc9020",
    "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
    "product_type": "income",
    "data_source": "payroll"
}

CloseData

This value is for the Truv Bridge closing.

NameTypeDescription
employerobjectObject with employer data, contains employer's name, can be undefined if no employer was selected
{
   "employer": {
        "name": "Facebook Demo"
    }
}

ManualDDSData

The table below covers events from a manual DDS operation.

NameTypeDescription
actionstringType of operation, can be EMAIL, DOWNLOAD, SHARE or EXTERNAL_FLOW (if enabled).
depositTypestringType of deposit selected in the Truv Bridge, can be entire, percent or amount. Not provided for EXTERNAL_FLOW action.
{
    "depositType": "entire",
    "action": "EMAIL"
}

OAuthEventData

The table below covers events when OAuth is initiated to a financial institution's login page.

NameTypeDescription
bridge_tokenstringValue for bridge_token passed to TruvBridge.init
product_typestringType of the product
task_idstringUnique identifier associated with attempt to use Link to retrieve data
provider_idstringUnique identifier for selected provider
urlstringURL the user is redirected to
{
    "bridge_token": "b5cb1933e43043a792a9b337af5824e2",
    "product_type": "assets",
    "provider_id": "truv_bank_oauth",
    "task_id": "5ad1938450c54024bbc967a3a7dc9020",
    "url": "https://www.truv.com/oauth-login.html?provider_id=truv_bank_oauth&bridge_token=b5cb1933e43043a792a9b337af5824e2&task_id=5ad1938450c54024bbc967a3a7dc9020&token=eb18f867490347a497f36f43bec39043"
}

Errors

Below view the error codes for Truv Bridge. Truv Bridge values return as a callback.

{
    "error": {
        "error_code": "LOGIN_ERROR",
        "error_message": "Username or password is incorrect",
        "error_type": "LINK_ERROR"
    }
}
📘

Tip

Design your user experience to notify your users of login errors when connecting to payroll.

Error object

The table below contains information about the error objects.

NameTypeDescription
error_typestringUnique code describing type of error that occurred
error_codestringUnique code indicating error that occurred, for more see Error codes section
error_messagestringDescription of the error that occurred

Error types

This data is for error type values.

  • LINK_ERROR - Generic error type has occurred

Error codes

These codes provide descriptions for the error.

  • ERROR - Generic error occurred
  • LINK_EXISTS - User's account is already connected
  • LOGIN_ERROR - Incorrect username, password, or both
  • MFA_ERROR - Invalid input for the multi-factor authentication
  • NO_DATA - User account has no data
  • UNAVAILABLE - Payroll provider is unreachable at the time of connection