Managing Plaid Accounts

Now that you've integrated Plaid Link with the Hurdlr API, you may find that your user needs the ability to take certain actions to manage their linked bank accounts. The Hurdlr API makes this process easy, reducing how much back-end you need to build to support your Plaid integration.

1. Getting Plaid items

Once you've sent your user's Plaid access_token to Hurdlr, Hurdlr will then fetch and store the associated Plaid "Item", which is a parent-level object for any given bank. You can obtain all of a given user's Plaid Items (one per banking institution), by running the following GET request:

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/banks/plaidItems \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /plaidItems contains an array of the user's Plaid Items (banks):

[
  {
    "id": 52320,
    "status": "ACTIVE",
    "createdDate": "2020-02-20T21:22:07.000Z",
    "isInitialReady": true,
    "isHistoricalReady": true,
    "apiItemId": "3E51DvPAgMigGmybkpv9tzNjbjboEotqykvEo",
    "apiInstitutionId": "ins_5",
    "apiInstitutionName": "Citi",
    "apiAccessToken": "access-sandbox-da40d92a-dbc7-4399-be1c-fdb63338a147",
    "apiErrorCode": "ITEM_LOGIN_REQUIRED",
    "apiErrorMessage": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state"
  },
  {
    "id": 64002,
    "status": "ACTIVE",
    "createdDate": "2021-09-15T17:49:12.000Z",
    "isInitialReady": true,
    "isHistoricalReady": true,
    "apiItemId": "AE7w17gMyNtn81AjggmQCXnWRpAJ8ri9zEmL3",
    "apiInstitutionId": "ins_4",
    "apiInstitutionName": "Wells Fargo",
    "apiAccessToken": "access-sandbox-0a9d120a-6656-4dd2-87b6-9d7f52abc16e",
    "apiErrorCode": null,
    "apiErrorMessage": null
  }
]

On each item, you may find the following attributes to be of particular interest:

Field

Description

Format

id

Id of the Plaid Item, for reference within the Hurdlr API

Numeric

isInitialReady

Whether the INITIAL Plaid Item webhook has been sent by Plaid, indicating that recent transactions are available

Boolean

isHistoricalReady

Whether the HISTORICAL Plaid Item webhook has been sent by Plaid, indicating that historical transactions are available

Boolean

apiItemId

Id of the Plaid Item, for reference within Plaid's API

String

apiAccessToken

access_token Plaid Item, for reference within Plaid's API

String

apiInstitutionId

Id of the institution that the transaction originated from

String

apiErrorCode

error_code of the Plaid Item error

String

apiErrorMessage

error_message of the Plaid Item error

String

If you are using Hurdlr's Embeddable Expense Dashboard or Income Dashboard, then your design and development teams do not need to spend any time figuring out how to handle bank authentication-related errors. Hurdlr's Embeddable User Interface gracefully handles Plaid-related errors and walks your users through the steps on resolving those errors.

If you intend to resolve these errors on your own, then you will find the apiErrorCode and apiErrorMessage fields critical to your successful implementation.

2. Getting Plaid accounts

To see the actual bank (and credit card) accounts that your user has linked, you will want to retrieve the user's Plaid item accounts:

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/banks/plaidItemAccounts \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /plaidItemAccounts contains an array of the user's linked accounts:

[
  {
    "id": 142563,
    "plaidItemId": 52320,
    "status": "ACTIVE",
    "createdDate": "2020-02-20T21:02:06.000Z",
    "lastExpenseSyncedDate": "2020-03-16T19:48:45.000Z",
    "lastRevenueSyncedDate": "2020-03-16T19:48:45.000Z",
    "tranStartDate": "2020-01-21",
    "tranMinStartDate": "2019-01-01",
    "apiAccountId": "dz1g6e8WxQFEPDrkvRzkcDNNbkDVyxfZ3rm1Z",
    "apiAccountName": "Citi Checking",
    "apiInstitutionId": "ins_5",
    "apiMask": "3332",
    "apiOfficialName": "Citi Gold Standard 0% Interest Checking",
    "apiType": "DEPOSITORY",
    "apiSubType": "CHECKING",
    "apiAvailableBalance": 100.0,
    "apiCurrentBalance": 110.0,
    "apiLimitBalance": null,
    "autoClassify": "OFF",
    "defaultBusinessId": null
  },
  {
    "id": 142564,
    "plaidItemId": 52320,
    "status": "ACTIVE",
    "createdDate": "2020-02-20T21:02:06.000Z",
    "lastExpenseSyncedDate": "2020-03-16T19:48:45.000Z",
    "lastRevenueSyncedDate": null,
    "tranStartDate": "2020-01-21",
    "tranMinStartDate": "2019-01-01",
    "apiAccountId": "aqQkbJ9gzjilDyLK57qKI1QQ631X8yc79VzmZ",
    "apiAccountName": "Citi Credit",
    "apiInstitutionId": "ins_5",
    "apiMask": "3333",
    "apiOfficialName": "Citi Premier® Card",
    "apiType": "CREDIT",
    "apiSubType": "CREDIT_CARD",
    "apiAvailableBalance": 200.0,
    "apiCurrentBalance": 210.0,
    "apiLimitBalance": null,
    "autoClassify": "OFF",
    "defaultBusinessId": null
  },
  {
    "id": 142565,
    "plaidItemId": 64002,
    "status": "ACTIVE",
    "createdDate": "2020-02-20T21:02:06.000Z",
    "lastExpenseSyncedDate": "2020-03-16T19:48:45.000Z",
    "lastRevenueSyncedDate": "2020-03-16T19:48:45.000Z",
    "tranStartDate": "2020-01-21",
    "tranMinStartDate": "2019-01-01",
    "apiAccountId": "4W165wG79lFGAMP58lR5iB66w4BN7aCdx4Zyl",
    "apiAccountName": "Wells Fargo CD",
    "apiInstitutionId": "ins_4",
    "apiMask": "2222",
    "apiOfficialName": "Wells Fargo Bronze Standard 0.2% Interest CD",
    "apiType": "DEPOSITORY",
    "apiSubType": "CD",
    "apiAvailableBalance": null,
    "apiCurrentBalance": 1000.0,
    "apiLimitBalance": null,
    "autoClassify": "OFF",
    "defaultBusinessId": null
  }
]

On each account, you may find the following attributes to be of particular interest:

Field

Description

Format

id

Id of the Plaid Item account, for reference within the Hurdlr API

Numeric

plaidItemId

Id of the Plaid Item that this account belongs to, for reference within the Hurdlr API

Numeric

lastExpenseSyncedDate

Last date that expense transactions were pulled for this account

yyyy-MM-dd'T'HH:mm:ss.SSSZ

lastRevenueSyncedDate

Last date that income transactions were pulled for this account

yyyy-MM-dd'T'HH:mm:ss.SSSZ

tranStartDate

Earliest transaction date that Hurdlr pulled transactional data from

yyyy-MM-dd

tranMinStartDate

Earliest transaction date that Hurdlr can pull transactional data from

yyyy-MM-dd'T'HH:mm:ss.SSSZ

apiInstitutionId

Id of the institution that the transaction originated from

String

apiAccountName

Name of the account, either assigned by the user or financial institution

String

apiOfficialName

Official name of the account, as given by the financial institution

String

apiMask

Mask of the user's bank account, often the last 4 digits of the account number

2-4 Alphanumeric characters

apiType

Type of the account

String

apiSubType

Subtype of the account

String

apiAvailableBalance

Amount of funds available to be withdrawn from the account

Numeric, with 2 decimal places

apiCurrentBalance

Amount of funds in or owed by the account

Numeric, with 2 decimal places

apiLimitBalance

Credit or overdraft limit

Numeric, with 2 decimal places

autoClassify

Type of auto-classification; for any bank or credit card account that is not a business-only account, use "OFF"

Must be one of the following: "OFF", "BUSINESS", "NOT_BUSINESS"

defaultBusinessId

Id of the business that transactions from this account should be auto-assigned to; required (and only used) if autoClassify is set to "BUSINESS"

Numeric

3. Pulling historical transactions

When you link your user's Plaid accounts to the Hurdlr API, Hurdlr pulls 30 days of transactions by default. Leveraging our experience iterating Hurdlr's own app with over 700k+ users, we concluded that 30 days is the best balance between giving users enough information to provide value, but without providing too much information so as to overwhelm them. With that being said, there are many use cases where you or your users may want to pull transactions further back, and Hurdlr makes that easy to do so.

For any given Plaid account, you can simply update the tranStartDate field to the desired historical date, and POST that account to the /plaidItemAccounts endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/banks/plaidItemAccounts \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "plaidItemAccounts": [
      {
        "id": 142565,
        "tranStartDate": "2019-01-01",
      }
    ]
  }'

🚧

The tranStartDate must be less than or equal to the tranMinStartDate on the given account. The tranMinStartDate is the earliest date that Plaid has transactional data for the given account. That date varies by banking institution as well as when the user first linked with Plaid (including in other applications).

4. Setting an account to business-only

If a user has a business account that they do not commingle personal transactions into, you can set their account up so that every transaction that comes in is automatically classified as a business transaction. For any given Plaid account, you can simply update the autoClassify and defaultBusinessId fields, and POST that account to the /plaidItemAccounts endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/banks/plaidItemAccounts \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "plaidItemAccounts": [
      {
        "id": 142565,
        "autoClassify": "BUSINESS",
        "defaultBusinessId": 416080
      }
    ]
  }'

4. Removing a Plaid item

If your users wants to unlink a bank altogether, you can unlink the associated Plaid Item by making the following DELETE call, including the relevant Plaid Item's ID from the Hurdlr API:

curl \
  --request DELETE \
  --url https://sandbox.hurdlr.com/rest/v5/banks/plaidItem \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 1234,
    "removeFromPlaid": true
  }'

Setting the removeFromPlaid parameter to true will also unlink the account with Plaid, so that Plaid no longer bills you for this item.