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):
{
data: [
{
"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
}
],
lastUpdatedDate: "2021-09-01T15:37:40.107Z"
}
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 accounts:
curl \
--request GET \
--url https://sandbox.hurdlr.com/rest/v5/banks/accounts?apiName=PLAID \
--header 'Authorization: Bearer ${access_token}' \
--header 'Content-Type: application/json'
The response from GET /accounts contains an array of the user's linked accounts:
{
data: [
{
"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",
"apiAccountNo": "3332",
"apiAccountSubType": "CHECKING",
"apiInstitutionId": "ins_5",
"apiOfficialName": "Citi Gold Standard 0% Interest Checking",
"apiAccountType": "DEPOSITORY",
"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",
"apiAccountNo": "3333",
"apiAccountType": "CREDIT",
"apiAccountSubType": "CREDIT_CARD",
"apiInstitutionId": "ins_5",
"apiOfficialName": "Citi Premier® 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",
"apiAccountNo": "2222",
"apiAccountType": "DEPOSITORY",
"apiAccountSubType": "CD",
"apiInstitutionId": "ins_4",
"apiOfficialName": "Wells Fargo Bronze Standard 0.2% Interest CD",
"apiAvailableBalance": null,
"apiCurrentBalance": 1000.0,
"apiLimitBalance": null,
"autoClassify": "OFF",
"defaultBusinessId": null
}
],
lastUpdatedDate: "2021-09-01T15:40:40.107Z"
}
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 |
apiAccountType | Type of the account | String |
apiAccountSubType | Subtype of the account | 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 |
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 /accounts endpoint:
curl \
--request POST \
--url https://sandbox.hurdlr.com/rest/v5/banks/accounts \
--header 'Authorization: Bearer ${access_token}' \
--header 'Content-Type: application/json' \
--data '{
"accounts": [
{
"id": 142565,
"tranStartDate": "2019-01-01",
}
]
}'
The
tranStartDate
must be greater than or equal to thetranMinStartDate
on the given account. ThetranMinStartDate
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 /accounts endpoint:
curl \
--request POST \
--url https://sandbox.hurdlr.com/rest/v5/banks/accounts \
--header 'Authorization: Bearer ${access_token}' \
--header 'Content-Type: application/json' \
--data '{
"accounts": [
{
"id": 142565,
"autoClassify": "BUSINESS",
"defaultBusinessId": 416080
}
]
}'
The
defaultBusinessId
field is not required for users who only have one business; the Hurdlr API will automatically default to the user's sole business.
5. 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.
Updated 17 days ago