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 Type	Event Payload	Description
LOAD	None	Truv Bridge module finished loading
OPEN	CommonEventData	Truv Bridge is ready
SCREEN_VIEW	ScreenViewData	Truv Bridge screen viewed
EMPLOYER_SELECTED	EmployerSelectedData	Employer or provider selected in Truv Bridge
DOC_UPLOAD_OPENED	CommonEventData	Document Upload opened
DOCUMENTS_UPLOADED	DocumentsUploadedData	Specific document types uploaded
LINK_CREATED	TaskData	User logging in to their payroll provider as a new Link
LOGIN_COMPLETE	TaskData	User successfully logged in to payroll provider
SUCCESS	TaskData	User data successfully retrieved from payroll provider
ERROR	ErrorData	Error during the payroll provider connection process
UNSUPPORTED_BROWSER	None	Truv Bridge is not supported by the user's browser
CLOSE	CloseData	Truv Bridge closes
MANUAL_DDS	ManualDDSData	Manual DDS operation was successfully submitted
OAUTH_OPENED	OAuthEventData	Sent 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.

Name	Type	Description
employer	`object`	Object 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.

Name	Type	Description
action	string	Type of operation, can be `EMAIL`, `DOWNLOAD`, `SHARE` or `EXTERNAL_FLOW` (if enabled).
depositType	string	Type 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.

Name	Type	Description
bridge_token	string	Value for bridge_token passed to TruvBridge.init
product_type	string	Type of the product
task_id	string	Unique identifier associated with attempt to use Link to retrieve data
provider_id	string	Unique identifier for selected provider
url	string	URL 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.

Name	Type	Description
error_type	string	Unique code describing type of error that occurred
error_code	string	Unique code indicating error that occurred, for more see Error codes section
error_message	string	Description 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