Guides
  1. Employee Self-Onboarding

Employee Bank Account Verification With Plaid

This guide describes the API sequence for adding an employee bank account and verifying it through Plaid.

Use this flow when your integration allows an employee to add a bank account for direct deposit and Plaid verification is enabled for that company.

Scope

This is an employee bank account flow in employee context.

  • the bank account belongs to the employee
  • the verification is done by the employee in self-service
  • the API endpoints are employee endpoints under companies/{companyId}/employees/{employeeId}/...

This is not the company bank account verification flow.

Goal

The goal is:

  1. create the employee bank account record in Worklio
  2. open Plaid Link for that bank account
  3. save the selected Plaid account to Worklio
  4. reload the bank account and read its final verification status

Required identifiers

You need these values before starting:

  • companyId
  • employeeId

After the first API call you will also have:

  • Worklio employee bank account accountId

Plaid Link documentation

Official Plaid documentation:

Use Hosted Link when the partner does not fully control the frontend or prefers Plaid to host the Link experience.

Prerequisites

  • the integration must be acting in employee context for the target employeeId
  • if Plaid verification is required, capability PLAID_VERIFY must be enabled

API sequence

1. Create the employee bank account

Call this when the employee submits bank account details.

  • Method: POST
  • Endpoint: companies/{companyId}/employees/{employeeId}/bankaccounts

Request body should include:

  • accountHolderName
  • accountNumber
  • routingNumber
  • accountType
  • verificationType

Set verificationType to:

  • Plaid when Plaid verification should be used
  • Manual when Plaid verification is not used

Important:

  • if you plan to verify with Plaid, this call must happen first
  • the response gives you the Worklio employee bank account accountId required by the Plaid endpoints

2. Request a Plaid link token

Call this only after step 1 succeeds and you have the Worklio employee bank account accountId.

  • Method: GET
  • Endpoint: companies/{companyId}/employees/{employeeId}/plaid/{accountId}/token

Use the returned linkToken to initialize Plaid Link.

Notes:

  • if the bank account was already linked before, this endpoint may return a Plaid update-mode token instead of a fresh-link token
  • if no linkToken is returned, stop the flow and treat it as a failure

3. Open Plaid Link

This is not a Worklio API call.

Use the linkToken from step 2 to open Plaid Link. When Plaid completes successfully, collect:

  • publicToken
  • selected Plaid account metadata
  • selected institution metadata

From the selected Plaid account, you will need:

  • Plaid accountId
  • accountMask
  • accountName
  • accountType
  • accountSubtype
  • verificationStatus

From the selected institution, you will need:

  • institutionId
  • institutionName

4. Save the Plaid connection

Call this only after Plaid Link returns success.

  • Method: POST
  • Endpoint: companies/{companyId}/employees/{employeeId}/plaid/{accountId}/link

Request body:

  • publicToken
  • accountId This is the Plaid account id selected in Plaid Link, not the Worklio bank account id from step 1.
  • accountMask
  • accountName
  • accountType
  • accountSubtype
  • institutionId
  • institutionName
  • verificationStatus

This call links the Worklio employee bank account to the selected Plaid account.

5. Reload the employee bank account

Call this immediately after step 4 succeeds.

  • Method: GET
  • Endpoint: companies/{companyId}/employees/{employeeId}/bankaccounts/{accountId}

Use this response as the source of truth for the bank account state.

Read:

  • isVerified
  • verificationType

Important:

  • there is no separate employee-side "complete verification" API after the Plaid link call
  • the final verification result should be read from the refreshed employee bank account returned by this endpoint

Recommended flow by scenario

Scenario A: New employee bank account with Plaid verification

Call the APIs in this order:

  1. POST /companies/{companyId}/employees/{employeeId}/bankaccounts
  2. GET /companies/{companyId}/employees/{employeeId}/plaid/{accountId}/token
  3. Open Plaid Link
  4. POST /companies/{companyId}/employees/{employeeId}/plaid/{accountId}/link
  5. GET /companies/{companyId}/employees/{employeeId}/bankaccounts/{accountId}

Scenario B: Existing unverified employee bank account, retry Plaid verification

Do not create a new bank account. Reuse the existing Worklio employee bank account accountId.

Call the APIs in this order:

  1. GET /companies/{companyId}/employees/{employeeId}/plaid/{accountId}/token
  2. Open Plaid Link
  3. POST /companies/{companyId}/employees/{employeeId}/plaid/{accountId}/link
  4. GET /companies/{companyId}/employees/{employeeId}/bankaccounts/{accountId}

Scenario C: No Plaid verification

If Plaid is not being used, only create the bank account and then reload it.

  1. POST /companies/{companyId}/employees/{employeeId}/bankaccounts
  2. GET /companies/{companyId}/employees/{employeeId}/bankaccounts/{accountId}

Failure handling

Plaid token request fails

  • do not open Plaid Link
  • show an error
  • allow retry

Employee exits Plaid without success

  • keep the employee bank account created in step 1
  • treat it as not verified yet
  • allow the user to retry later using the same Worklio employee bank account accountId

Plaid link save call fails

  • do not assume the account is verified
  • reload the employee bank account only if needed for recovery UI
  • allow retry using the same Worklio employee bank account accountId

Verification result

For partner integrations, the important rule is:

  • do not assume that successful Plaid Link means the account is already verified
  • after saving the Plaid connection, always call GET /companies/{companyId}/employees/{employeeId}/bankaccounts/{accountId} and use isVerified from that response

Updated about 2 hours ago