Plaid Integration API Documentation

Overview

This document covers two endpoints for integrating Plaid into your application:

1. Get Plaid Link Token — Generates a short-lived token used to initialize Plaid Link on the client side.
2. Verify Account — Verifies a connected account after the user completes the Plaid Link flow.

Base URL

1
Sandbox: https://api-sandbox.upwardli.com/
2
Prod: https://api.upwardli.com/

Authentication

All requests require a Bearer token passed in the Authorization header.

1
Authorization: Bearer <your_token>

Required Scopes

Endpoints

1. Get Plaid Link Token

Generates a Plaid Link token for a specific consumer. This token is required to initialize the Plaid Link UI on the client side.

Method & URL

$
POST v2/consumers/{consumer_id}/accounts/plaid-link-token

Path Parameters

Headers

Request Body**

1
{
2
  "is_mobile_app": false
3
}

Example Request

$
curl --location 'https://api-sandbox.upwardli.com/v2/consumers/1234567/accounts/plaid-link-token' \
>
--header 'Authorization: Bearer QF1rMIM808v18dNTcsCN7oWkttgktt' \
>
--header 'Content-Type: application/json' \
>
--data '{
>
    "is_mobile_app": false
>
}'

Response

1
{
2
    "link_token": "link-sandbox-f1133b83-510a-46de-87d7-2add5fa593d3",
3
    "expiration": 1772778931000,
4
    "hosted_link_url": "https://secure.plaid.com/hl/lss6688o38065n91qr32q27nqq0sn048q8"
5
}

2. Verify Account

Verifies a specific account after the user has completed the Plaid Link flow. This should be called once Plaid Link has successfully returned a public token and the account has been created on your backend.

Method & URL

$
POST v2/accounts/{account_id}/verify

Path Parameters

Headers

Example Request

$
curl --location --request POST 'https://api-sandbox.upwardli.com/v2/accounts/7f65d732-da69-4fe0-b77c-ebbed53677e9/verify' \
>
--header 'Authorization: Bearer QF1rMIM808v18dNTcsCN7oWkttgktt'

Response

1
{
2
    "hosted_link_url": "https://secure.plaid.com/hl/lssr9pp15nr73197q93ron8n9pp00r8s10"
3
}

Supported Plaid Verification Flows

We support the following Plaid account verification flows:

1. Consumer Logs into Financial Institution

The consumer authenticates directly with their financial institution through Plaid Link. This is the fastest path — the account is verified instantly upon successful login.

2. Manual Entry

Used when the consumer’s financial institution does not support instant authentication. Two sub-flows are available depending on institution support:

2a. Instant Micro-Deposits

If the financial institution supports it, Plaid will send instant micro-deposits to the account. The consumer verifies the deposit amounts to confirm ownership.

2b. Same Day ACH

If instant micro-deposits are not supported, Same Day ACH is used as a fallback.

⚠️ Account Verification Required — With Same Day ACH, the consumer must explicitly verify their account after the deposit is received. Use the Verify Account endpoint to complete this step.

Opening and Closing the Plaid Browser

Step 1 — Open the Plaid Browser

Launch a secure.plaid.com browser session where the consumer can complete Plaid authentication. Use the hosted_link_url returned from the Get Plaid Link Token endpoint to open the session.

Step 2 — Handle Completion with Custom URL Schema

Once Plaid completes, Upwardli will send a deep link using the following schema:

$
upwardli://plaid-link

Step 3 — Close the Plaid Browser on Redirect

Your app must listen for the plaid completion_redirect_uri in order to close the Plaid browser session when the deep link is received.

Example — Plaid Completion / Close Browser

1
// Handle deep links
2
useEffect(() => {
3
  const handleUrl = ({ url }: { url: string }) => {
4
    if (url.includes("plaid-link")) {
5
      WebBrowser.maybeCompleteAuthSession();
6
    }
7
  };
8
9
  const subscription = Linking.addEventListener("url", handleUrl);
10
11
  return () => {
12
    subscription.remove();
13
  };
14
}, []);

Typical Integration Flow

$
1. Call POST v2/consumers/{consumer_id}/accounts/plaid-link-token
$
        ↓
$
2. Use the returned token to open Plaid Link on the client
$
        ↓
$
3. User connects their bank account via Plaid Link
$
        ↓
$
4. Call POST v2/accounts/{account_id}/verify
$
        ↓
$
5. Account is verified and ready to use

Notes

• All UUIDs (consumer IDs, account IDs) are in standard UUID v4 format.
• The Plaid Link token is short-lived — initialize the Plaid Link UI promptly after receiving it.
• The sandbox base URL (api-sandbox.upwardli.com) should be replaced with the production URL before going live.