Quickstarts
LinkMoney API
Aggregator Guides
FinSight API
Resources
Privacy
Developer Account
Plaid Guide
Since FinGoal handles user registration there is no need to add link token
creation or exchange. First, you just need to register with the FinSightAPI, then you're ready to send users to the Link Money Gateway with { auth headers } where they'll link their accounts.
Responses from data dumps can be sent via webhooks or you can call for the data manually via the endpoints listed below.
Plaid Endpoints
The Link Money API exposes numerous endpoints for developers to interact with our data in a variety of ways. Broadly speaking, these endpoints can be divided into a couple of categories.
URL Construction
Depending on which endpoint collection, you may only need to access certain endpoint collections and not others. Endpoint construction is essentially:
- The Base URL - for example,
https://linkmoney-dev.fingoal.com
- The endpoint collection's name - In this case,
plaid
. - The version - each endpoint collection has separate versioning rather than a holistic version control for the entire api - for example,
v1
. - The endpoint, as specified in each endpoint's documentation.
Some examples include:
https://linkmoney-dev.fingoal.com/v1/plaid/transactions/get
https://linkmoney-dev.fingoal.com/v2/plaid/transactions
https://linkmoney-dev.fingoal.com/v1/plaid/configuration
Since FinGoal handles user registration there is no need to add link token
creation or exchange. First, you just need to register with the FinSightAPI, then you're ready to send users to the Link Money Web Portal with your token where they'll link their accounts.
Endpoints are broadly divided into sections described by the index. Each collection of endpoints offers access to a different set of functions. Most developers will only require a small portion of these endpoints to fully integrate with Link Money.
Responses from data dumps can be sent via webhooks or you can call for the data manually via the endpoints listed above.
Some developers who use Link Money API will be coming from another aggregator, Plaid. Though Plaid's functionality is similar to what we're offering, it has a different call structure from our own. In order to minimize friction during the migration process, Link Money API provides endpoints that clone the Plaid structure and receive and return Plaid data.
Items
Items are borrowed from the Plaid terminology. Per their documentation:
"An item represents a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items."
While the LinkMoney API does not use the item system in its underlying data scheme, it still leverages the term in Plaid endpoints to help with transition from the Plaid platform.
Developers can use the Plaid Item endpoints to retrieve items from the LinkMoney API. As with Plaid, these Items will include only data associated with a login from a single institution.
Retrieve An Item.
Endpoint: POST
/item/get
Find a single item and return its status.
Parameters
Name | Location | Description |
---|---|---|
access_token | Request BodyHeaders | Like Plaid, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X POST /item/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
Response
See the Item Model for a full description of the schema.
{
"item": {
"error": null,
"institution_id": "ins_109508",
"item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
"update_type": "background",
"webhook": "/example/hook",
"consent_expiration_time": null
},
"status": {
"transactions": {
"last_successful_update": "2019-02-15T15:52:39.000Z",
"last_failed_update": "2019-01-22T04:32:00.000Z"
},
"last_webhook": {
"sent_at": "2019-02-15T15:53:00.000Z",
"code_sent": "DEFAULT_UPDATE"
}
},
"request_id": "m8MDnv9okwxFNBV"
}
Remove an Item.
Endpoint: POST
/item/remove
Removes a specific item. Note that if the user has accounts with other financial institutions, these will not be removed.
Parameters
Name | Location | Description |
---|---|---|
access_token | Request BodyHeaders | Like Plaid, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual. |
Example Request
curl -X POST /item/remove \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
Response
Removing an item will respond with a request_id
for troubleshooting common problems. ( link to troubleshooting )
{
"request_id": "c9b50715-d8ab-4e90-bba1-f9d93059c6c0"
}
Institutions
Institutions are organizations that hold user financial data. Developers can see which institutions are available through the LinkMoney platform and what the institution's status is. For particular use cases, developers can search for particular institutions to find details about a certain provider.
Get Details of Supported Institutions.
Endpoint: POST
/institutions/get
Find important data about institutions supported in LinkMoney.
Parameters
Example Request
curl -X POST /institutions/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"count": 500,
"offset": 1000,
}'
Example Response
For more information about the response, see the model documentation entry on Plaid institutions.
{
"institutions": [
{
"institution_id": "ins_1",
"name": "Bank of America",
}
],
"request_id": "tbFyCEqkU774ZGG",
"total": 11384
}
Get Details of an Institution
Endpoint: POST
/institutions/get_by_id
Get the details for a specific financial institution supported by Link Money.
Parameters
Name | Location | Description |
---|---|---|
institution_id | Request Body | The ID of the institution to get details about. |
Example Request
curl -X POST /institutions/get_by_id \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"institution_id": "ins_109512",
}'
Example Response
{
"institution": {
"institution_id": "ins_109512",
"name": "Houndstooth Bank",
"status": {
"item_logins": {
"status": "HEALTHY",
"last_status_change": "2019-02-15T15:53:00Z",
"breakdown": {
"success": 0.9,
"error_link_money": 0.01,
"error_institution": 0.09
}
},
"transactions_updates": {
"status": "HEALTHY",
"last_status_change": "2019-02-12T08:22:00Z",
"breakdown": {
"success": 0.95,
"error_link_money": 0.02,
"error_institution": 0.03,
"refresh_interval": "NORMAL"
}
},
"auth": {
"status": "HEALTHY",
"last_status_change": "2019-02-15T15:53:00Z",
"breakdown": {
"success": 0.91,
"error_link_money": 0.01,
"error_institution": 0.08
}
},
"balance": {
"status": "HEALTHY",
"last_status_change": "2019-02-15T15:53:00Z",
"breakdown": {
"success": 0.89,
"error_link_money": 0.02,
"error_institution": 0.09
}
},
"identity": {
"status": "DEGRADED",
"last_status_change": "2019-02-15T15:50:00Z",
"breakdown": {
"success": 0.42,
"error_link_money": 0.08,
"error_institution": 0.5
}
},
"investments": {
"status": "HEALTHY",
"last_status_change": "2019-02-15T15:53:00Z",
"breakdown": {
"success": 0.89,
"error_link_money": 0.02,
"error_institution": 0.09
},
"liabilities": {
"status": "HEALTHY",
"last_status_change": "2019-02-15T15:53:00Z",
"error_link_money": {
"success": 0.89,
"error_plaid": 0.02,
"error_institution": 0.09
}
}
},
"investments_updates": {
"status": "HEALTHY",
"last_status_change": "2019-02-12T08:22:00Z",
"breakdown": {
"success": 0.95,
"error_plaid": 0.02,
"error_institution": 0.03,
"refresh_interval": "NORMAL"
}
},
"liabilities_updates": {
"status": "HEALTHY",
"last_status_change": "2019-02-12T08:22:00Z",
"breakdown": {
"success": 0.95,
"error_plaid": 0.02,
"error_institution": 0.03,
"refresh_interval": "NORMAL"
}
},
"primary_color": "#004966",
"url": "https://example-bank.com",
"logo": null
}
},
"request_id": "m8MDnv9okwxFNBV"
}
Search Institutions
Endpoint: POST
/institutions/search
Use query parameters to find up to ten matching institutions.
Parameters
Name | Location | Description |
---|---|---|
query | Request Body | A string search query to filter down results. |
Example Request
curl -X POST /institutions/search \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"query": "Gingham",
}'
Example Response
{
"institutions": [
{
"institution_id": "ins_118923",
"name": "Red Platypus Bank - Red Platypus Bank"
}
],
"request_id": "Ggmk0enW4smO2Tp"
}
Accounts & Transactions
Most user data lives in accounts and transactions. By using these endpoints, developers can access details about user accounts and their associated transactions.
Retrieve Accounts
Endpoint: POST
/accounts/get
Retrieve an account summary for any linked items that are not closed and actively carrying a balance.
Parameters
Name | Location | Is Required | Description |
---|---|---|---|
options | Request Body | false | An optional JSON object containing specific parameters to request more specific data. See Options below |
Name | Type | Description |
---|---|---|
account_ids | String[] | An array of account_ids to retrieve for the Account. |
Example Request
curl -X POST /accounts/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
Response
{
"accounts": [
{
"account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
"balances": {
"available": 100,
"current": 110,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "0000",
"name": "Plaid Checking",
"official_name": "Plaid Gold Standard 0% Interest Checking",
"subtype": "checking",
"type": "depository"
},
{
"account_id": "6PdjjRP6LmugpBy5NgQvUqpRXMWxzktg3rwrk",
"balances": {
"available": null,
"current": 23631.9805,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "6666",
"name": "Plaid 401k",
"official_name": null,
"subtype": "401k",
"type": "investment"
},
{
"account_id": "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
"balances": {
"available": null,
"current": 65262,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "7777",
"name": "Plaid Student Loan",
"official_name": null,
"subtype": "student",
"type": "loan"
}
],
"item": {
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_117650",
"item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
"update_type": "background",
"webhook": "https://www.genericwebhookurl.com/webhook"
},
"request_id": "bkVE1BHWMAZ9Rnr"
}
Get Transaction Data
Endpoint: POST
/transactions/get
Receive user-authorized transaction data for credit, depository, and some loan-type accounts. For transaction history from investment accounts, use the endpoints instead.
Parameters
Name | Location | Description | Required |
---|---|---|---|
options | Request Body | An optional object to be used with the request. | |
start_date | Request Body | The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD | |
end_date | Request Body | The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD . |
Name | Type | Description |
---|---|---|
account_ids | String[] | A list of the account_ids to retrieve for the item. Note that an error will be returned if a provided account_id is not associated with the item. |
count | number | The number of transactions to fetch. Defaults to 100 , and can be set anywhere between 1 and 500 . |
offset | number | The number of transactions to skip for pagination. The default value is 0 . |
Example Request
curl -X POST /transactions/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"start_date": "2018-01-01",
"end_date": "2018-02-01",
"options": {
"count": 250,
"offset": 100
},
}'
Response
{
"accounts": [
{
"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
"balances": {
"available": 110,
"current": 110,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "0000",
"name": "Plaid Checking",
"official_name": "Plaid Gold Standard 0% Interest Checking",
"subtype": "checking",
"type": "depository"
}
],
"transactions": [
{
"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
"amount": 2307.21,
"iso_currency_code": "USD",
"unofficial_currency_code": null,
"category": [
"Shops",
"Computers and Electronics"
],
"category_id": "19013000",
"date": "2017-01-29",
"datetime": null,
"authorized_date": "2017-01-27",
"authorized_datetime": null,
"location": {
"address": "300 Post St",
"city": "San Francisco",
"region": "CA",
"postal_code": "94108",
"country": "US",
"lat": 40.740352,
"lon": -74.001761,
"store_number": "1235"
},
"name": "Apple Store",
"merchant_name": "Apple",
"payment_meta": {
"by_order_of": null,
"payee": null,
"payer": null,
"payment_method": null,
"payment_processor": null,
"ppd_id": null,
"reason": null,
"reference_number": null
},
"payment_channel": "in store",
"pending": false,
"pending_transaction_id": null,
"account_owner": null,
"transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
"transaction_code": null,
"transaction_type": "place"
}
],
"item": {
"available_products": [
"balance",
"identity",
"investments"
],
"billed_products": [
"assets",
"auth",
"liabilities",
"transactions"
],
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_3",
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
"update_type": "background",
"webhook": "https://www.genericwebhookurl.com/webhook"
},
"total_transactions": 1,
"request_id": "45QSn"
}
Refresh Transaction Data
Endpoint: POST
/transactions/refresh
Initiate an on-demand extraction to fetch the newest transactions for an Item. This on-demand extraction takes place in addition to the periodic extractions that automatically occur multiple times a day for any Transactions-enabled Item. If changes are discovered after calling this endpoint, LinkMoney will send one of the following webhooks to your specified callback URL:
TRANSACTIONS_REMOVED
, if removed transactions are detected.DEFAULT_UPDATE
, if new transactions are detected. New transactions can also be accessed with the Get Transaction Data endpoint (see above).
— link to Webhooks for Plaid once we have them, since that's going to be a big deal —
Example Request
curl -X POST /transactions/refresh \
-H 'content-type: application/json' \
-H "Authorization: Bearer {access_token}" \
Example Response
{
"request_id": "1vwmF5TBQwiqfwP"
}
Get Categories
Endpoint: POST
/categories/get
Get detailed information on categories returned by LinkMoney in Plaid format. You can also refer to the Category Documentation (link to documentation) for a reference on what categories are available in the LinkMoney API.
Example Request
curl -X POST /categories/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'
Example Response
{
"categories": [
{
"category_id": "10000000",
"group": "special",
"hierarchy": [
"Bank Fees"
]
},
{
"category_id": "10001000",
"group": "special",
"hierarchy": [
"Bank Fees",
"Overdraft"
]
},
{
"category_id": "12001000",
"group": "place",
"hierarchy": [
"Community",
"Animal Shelter"
]
}
],
"request_id": "ixTBLZGvhD4NnmB"
}
Retrieve Account Balances
Endpoint: POST
/accounts/balance/get
Retrieve the real-time balance of each of an Item's accounts. While the /accounts/get endpoint does include balance objects in the return data, this endpoint will force an account's balances to refresh, ensuring that the data returned is real0time.
Parameters
Name | Location | Description |
---|---|---|
options | Request Body | An optional object to filter the results of this call. |
Name | Type | Description |
---|---|---|
account_ids | String[] | A list of account_ids to retrieve for the item. Defaults to null. An error will be returned if a provided account_id is not associated with the item. |
min_last_updated_datetime | StringYYYY-MM-DDTHH:mm:ssZ | A timestamp indicating the oldest acceptable balance when making a request. |
Example Request
curl -X POST /accounts/balance/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"options": {
"account_ids": [String]
}
}'
Example Response
{
"accounts": [
{
"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
"balances": {
"available": 100,
"current": 110,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "0000",
"name": "Plaid Checking",
"official_name": "Plaid Gold Standard 0% Interest Checking",
"subtype": "checking",
"type": "depository"
},
{
"account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
"balances": {
"available": null,
"current": 410,
"iso_currency_code": "USD",
"limit": 2000,
"unofficial_currency_code": null
},
"mask": "3333",
"name": "Plaid Credit Card",
"official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
"subtype": "credit card",
"type": "credit"
},
{
"account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
"balances": {
"available": null,
"current": 65262,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "7777",
"name": "Plaid Student Loan",
"official_name": null,
"subtype": "student",
"type": "loan"
}
],
"item": {
"available_products": [
"balance",
"identity",
"investments"
],
"billed_products": [
"assets",
"auth",
"liabilities",
"transactions"
],
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_3",
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
"update_type": "background",
"webhook": "https://www.genericwebhookurl.com/webhook"
},
"request_id": "qk5Bxes3gDfv4F2"
}
Investments
Some accounts are not included in traditional accounts calls and have their own endpoints, separate from accounts. Investments are one such account type. Endpoints for Liabilities also have their own separate collection. For every other type of accounts, use the generic Accounts & Transactions endpoint collection.
Get Investment Holdings
Endpoint: POST
/investment/holdings/get
Parameters
Name | Location | Description |
---|---|---|
options | Request Body | An optional object to filter the results of this call. |
Name | Type | Description |
---|---|---|
account_ids | String[] | An array of account_ids to retrieve for the Item. An error will be returned if a provided account_id is not associated with the Item. |
Example Request
curl -X POST /investments/holdings/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'
Example Response
{
"accounts": [
{
"account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g",
"balances": {
"available": 43200,
"current": 43200,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "4444",
"name": "Plaid Money Market",
"official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
"subtype": "money market",
"type": "depository"
},
{
"account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
"balances": {
"available": null,
"current": 320.76,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "5555",
"name": "Plaid IRA",
"official_name": null,
"subtype": "ira",
"type": "investment"
},
{
"account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
"balances": {
"available": null,
"current": 23631.9805,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "6666",
"name": "Plaid 401k",
"official_name": null,
"subtype": "401k",
"type": "investment"
}
],
"holdings": [
{
"account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
"cost_basis": 1,
"institution_price": 1,
"institution_price_as_of": "2021-04-13",
"institution_value": 0.01,
"iso_currency_code": "USD",
"quantity": 0.01,
"security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
"unofficial_currency_code": null
},
{
"account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
"cost_basis": 1.5,
"institution_price": 2.11,
"institution_price_as_of": null,
"institution_value": 2.11,
"iso_currency_code": "USD",
"quantity": 1,
"security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",
"unofficial_currency_code": null
},
{
"account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
"cost_basis": 10,
"institution_price": 10.42,
"institution_price_as_of": null,
"institution_value": 20.84,
"iso_currency_code": "USD",
"quantity": 2,
"security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
"unofficial_currency_code": null
},
{
"account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
"cost_basis": 0.01,
"institution_price": 0.011,
"institution_price_as_of": null,
"institution_value": 110,
"iso_currency_code": "USD",
"quantity": 10000,
"security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
"unofficial_currency_code": null
},
{
"account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
"cost_basis": 23,
"institution_price": 27,
"institution_price_as_of": null,
"institution_value": 636.309,
"iso_currency_code": "USD",
"quantity": 23.567,
"security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
"unofficial_currency_code": null
},
{
"account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
"cost_basis": 15,
"institution_price": 13.73,
"institution_price_as_of": null,
"institution_value": 1373.6865,
"iso_currency_code": "USD",
"quantity": 100.05,
"security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",
"unofficial_currency_code": null
},
{
"account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
"cost_basis": 1,
"institution_price": 1,
"institution_price_as_of": null,
"institution_value": 12345.67,
"iso_currency_code": "USD",
"quantity": 12345.67,
"security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
"unofficial_currency_code": null
}
],
"item": {
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_3",
"item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g",
"update_type": "background",
"webhook": "https://www.genericwebhookurl.com/webhook"
},
"request_id": "l68wb8zpS0hqmsJ",
"securities": [
{
"close_price": 0.011,
"close_price_as_of": "2021-04-13",
"cusip": null,
"institution_id": null,
"institution_security_id": null,
"is_cash_equivalent": false,
"isin": null,
"iso_currency_code": "USD",
"name": "Nflx Feb 01'18 $355 Call",
"proxy_security_id": null,
"security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
"sedol": null,
"ticker_symbol": "NFLX180201C00355000",
"type": "derivative",
"unofficial_currency_code": null
},
{
"close_price": 27,
"close_price_as_of": null,
"cusip": "577130834",
"institution_id": null,
"institution_security_id": null,
"is_cash_equivalent": false,
"isin": "US5771308344",
"iso_currency_code": "USD",
"name": "Matthews Pacific Tiger Fund Insti Class",
"proxy_security_id": null,
"security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
"sedol": null,
"ticker_symbol": "MIPTX",
"type": "mutual fund",
"unofficial_currency_code": null
},
{
"close_price": 2.11,
"close_price_as_of": null,
"cusip": "00448Q201",
"institution_id": null,
"institution_security_id": null,
"is_cash_equivalent": false,
"isin": "US00448Q2012",
"iso_currency_code": "USD",
"name": "Achillion Pharmaceuticals Inc.",
"proxy_security_id": null,
"security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",
"sedol": null,
"ticker_symbol": "ACHN",
"type": "equity",
"unofficial_currency_code": null
},
{
"close_price": 10.42,
"close_price_as_of": null,
"cusip": "258620103",
"institution_id": null,
"institution_security_id": null,
"is_cash_equivalent": false,
"isin": "US2586201038",
"iso_currency_code": "USD",
"name": "DoubleLine Total Return Bond Fund",
"proxy_security_id": null,
"security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
"sedol": null,
"ticker_symbol": "DBLTX",
"type": "mutual fund",
"unofficial_currency_code": null
},
{
"close_price": 1,
"close_price_as_of": null,
"cusip": null,
"institution_id": null,
"institution_security_id": null,
"is_cash_equivalent": true,
"isin": null,
"iso_currency_code": "USD",
"name": "U S Dollar",
"proxy_security_id": null,
"security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
"sedol": null,
"ticker_symbol": "USD",
"type": "cash",
"unofficial_currency_code": null
},
{
"close_price": 13.73,
"close_price_as_of": null,
"cusip": null,
"institution_id": "ins_3",
"institution_security_id": "NHX105509",
"is_cash_equivalent": false,
"isin": null,
"iso_currency_code": "USD",
"name": "NH PORTFOLIO 1055 (FIDELITY INDEX)",
"proxy_security_id": null,
"security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",
"sedol": null,
"ticker_symbol": "NHX105509",
"type": "etf",
"unofficial_currency_code": null
}
]
}
Get Investment Transactions
Endpoint: POST
/investments/transactions/get
Retrieve user-authorized transaction data for investment accounts. Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift.
Parameters
Name | Location | Description |
---|---|---|
start_date | Request Body | The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. |
end_date | Request Body | The latest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. |
options | Request Body | An optional object to filter the results of this call. |
Name | Type | Description |
---|---|---|
account_ids | String[] | An array of account_ids to retrieve for the item. |
count | Number | The number of transactions to fetch. Defaults to 100 and can be any number between 1 and 500 . |
offset | Number | The number of transactions to skip for pagination. Defaults to 0 . |
Example Request
curl -X POST /investments/transactions/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
"start_date": "2018-03-01",
"end_date": "2018-04-30",
"options": {
"count": 250,
"offset": 100
}
}'
Example Response
{
"accounts": [
{
"account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe",
"balances": {
"available": 100,
"current": 110,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "0000",
"name": "Plaid Checking",
"official_name": "Plaid Gold Standard 0% Interest Checking",
"subtype": "checking",
"type": "depository"
},
{
"account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z",
"balances": {
"available": null,
"current": 320.76,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "5555",
"name": "Plaid IRA",
"official_name": null,
"subtype": "ira",
"type": "investment"
},
{
"account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
"balances": {
"available": null,
"current": 23631.9805,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "6666",
"name": "Plaid 401k",
"official_name": null,
"subtype": "401k",
"type": "investment"
}
],
"investment_transactions": [
{
"account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
"amount": -8.72,
"cancel_transaction_id": null,
"date": "2020-05-29",
"fees": 0,
"investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
"iso_currency_code": "USD",
"name": "INCOME DIV DIVIDEND RECEIVED",
"price": 0,
"quantity": 0,
"security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
"subtype": "dividend",
"type": "cash",
"unofficial_currency_code": null
},
{
"account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
"amount": -1289.01,
"cancel_transaction_id": null,
"date": "2020-05-28",
"fees": 7.99,
"investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57",
"iso_currency_code": "USD",
"name": "SELL Matthews Pacific Tiger Fund Insti Class",
"price": 27.53,
"quantity": -47.74104242992852,
"security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
"subtype": "sell",
"type": "sell",
"unofficial_currency_code": null
},
{
"account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
"amount": 7.7,
"cancel_transaction_id": null,
"date": "2020-05-27",
"fees": 7.99,
"investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv",
"iso_currency_code": "USD",
"name": "BUY DoubleLine Total Return Bond Fund",
"price": 10.42,
"quantity": 0.7388014749727547,
"security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
"subtype": "buy",
"type": "buy",
"unofficial_currency_code": null
}
],
"item": {
"available_products": [
"assets",
"balance",
"identity",
"transactions"
],
"billed_products": [
"auth",
"investments"
],
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_12",
"item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq",
"update_type": "background",
"webhook": "https://www.genericwebhookurl.com/webhook"
},
"request_id": "iv4q3ZlytOOthkv",
"securities": [
{
"close_price": 27,
"close_price_as_of": null,
"cusip": "577130834",
"institution_id": null,
"institution_security_id": null,
"is_cash_equivalent": false,
"isin": "US5771308344",
"iso_currency_code": "USD",
"name": "Matthews Pacific Tiger Fund Insti Class",
"proxy_security_id": null,
"security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
"sedol": null,
"ticker_symbol": "MIPTX",
"type": "mutual fund",
"unofficial_currency_code": null
},
{
"close_price": 10.42,
"close_price_as_of": null,
"cusip": "258620103",
"institution_id": null,
"institution_security_id": null,
"is_cash_equivalent": false,
"isin": "US2586201038",
"iso_currency_code": "USD",
"name": "DoubleLine Total Return Bond Fund",
"proxy_security_id": null,
"security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
"sedol": null,
"ticker_symbol": "DBLTX",
"type": "mutual fund",
"unofficial_currency_code": null
},
{
"close_price": 34.73,
"close_price_as_of": null,
"cusip": "84470P109",
"institution_id": null,
"institution_security_id": null,
"is_cash_equivalent": false,
"isin": "US84470P1093",
"iso_currency_code": "USD",
"name": "Southside Bancshares Inc.",
"proxy_security_id": null,
"security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
"sedol": null,
"ticker_symbol": "SBSI",
"type": "equity",
"unofficial_currency_code": null
}
],
"total_investment_transactions": 3
}
Plaid Auth
Auth endpoints are used to obtain the information required to initiate transfer between accounts. These endpoints are designed specifically for developers migrating from Plaid to Link Money, and are designed to follow the Plaid specification for their auth API.
Retrieve Auth Data
Endpoint: POST
/v1/plaid/auth/get
Retrieves account and bank information necessary for transfers. Account, Routing, and Wire Routing numbers, as well as account balances (when available).
Name | Location | Is Required | Description |
---|---|---|---|
access_token | Request Body | True | Access token created for the item |
options | Request Body | False | Optional filter for the response |
Name | Type | Description |
---|---|---|
account_ids | String[] | List of account_ids to be retrieved |
Example Request
curl -X POST /auth/get \
-H 'Content-Type: application/json' \
-d '{
"client_id": String,
"secret": String,
"access_token": String,
"options": {
"account_ids": [String]
}
}'
Example Response
{
"accounts": [
{
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"balances": {
"available": 100,
"current": 110,
"limit": null,
"iso_currency_code": "USD",
"unofficial_currency_code": null
},
"mask": "9606",
"name": "Link Money Checking",
"official_name": "Link Money Silver Checking",
"subtype": "checking",
"type": "depository"
}
],
"numbers": {
"ach": [
{
"account": "9900009606",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"routing": "011401533",
"wire_routing": "021000021"
}
],
"eft": [
{
"account": "111122223333",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"institution": "021",
"branch": "01140"
}
],
"international": [
{
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"bic": "NWBKGB21",
"iban": "GB29NWBK60161331926819"
}
],
"bacs": [
{
"account": "31926819",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"sort_code": "601613"
}
]
},
"item": {
"available_products": [
"balance",
"identity",
"payment_initiation",
"transactions"
],
"billed_products": [
"assets",
"auth"
],
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_117650",
"item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
"update_type": "background",
"webhook": "https://www.genericwebhookurl.com/webhook"
},
"request_id": "m8MDnv9okwxFNBV"
}
{
"accounts": [
{
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"balances": {
"available": 100,
"current": 110,
"limit": null,
"iso_currency_code": "USD",
"unofficial_currency_code": null
},
"mask": "9606",
"name": "Link Money Checking",
"official_name": "Link Money Gold Checking",
"subtype": "checking",
"type": "depository"
}
],
"numbers": {
"ach": [
{
"account": "9900009606",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"routing": "011401533",
"wire_routing": "021000021"
}
],
"eft": [
{
"account": "111122223333",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"institution": "021",
"branch": "01140"
}
],
"international": [
{
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"bic": "NWBKGB21",
"iban": "GB29NWBK60161331926819"
}
],
"bacs": [
{
"account": "31926819",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"sort_code": "601613"
}
]
},
"item": {
"available_products": [
"balance",
"identity",
"payment_initiation",
"transactions"
],
"billed_products": [
"assets",
"auth"
],
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_117650",
"item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
"update_type": "background",
"webhook": "https://www.genericwebhookurl.com/webhook"
},
"request_id": "m8MDnv9okwxFNBV"
}
Liabilities
The liabilities endpoint collection offers a single operation to retrieve liabilities. Liabilities are a specific type of account in LinkMoney's Plaid collection. To link Investments see the collection documentation. For any other type of account, use the generic Accounts & Transactions endpoints.
Retrieve Liabilities Data.
Endpoint: POST
/liabilities/get
Retrieve various details about an Item with loan or credit accounts.
The types of information returned by Liabilities can include balances and due dates, loan terms, and specific details such as the original loan amount and guarantor.
Parameters
Name | Location | Description |
---|---|---|
options | Request Body | An optional object to filter the results of this call. |
Name | Type | Description |
---|---|---|
account_ids | String[] | An array of account_ids to retrieve for the Item. An error will be returned if a provided account_id is not associated with the Item. |
Example Request
curl -X POST /liabilities/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'
Example Response
{
"accounts": [
{
"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
"balances": {
"available": 100,
"current": 110,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "0000",
"name": "Plaid Checking",
"official_name": "Plaid Gold Standard 0% Interest Checking",
"subtype": "checking",
"type": "depository"
},
{
"account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
"balances": {
"available": null,
"current": 410,
"iso_currency_code": "USD",
"limit": 2000,
"unofficial_currency_code": null
},
"mask": "3333",
"name": "Plaid Credit Card",
"official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
"subtype": "credit card",
"type": "credit"
},
{
"account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
"balances": {
"available": null,
"current": 65262,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "7777",
"name": "Plaid Student Loan",
"official_name": null,
"subtype": "student",
"type": "loan"
},
{
"account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
"balances": {
"available": null,
"current": 56302.06,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "8888",
"name": "Plaid Mortgage",
"official_name": null,
"subtype": "mortgage",
"type": "loan"
}
],
"item": {
"available_products": [
"balance",
"investments"
],
"billed_products": [
"assets",
"auth",
"identity",
"liabilities",
"transactions"
],
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_3",
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
"update_type": "background",
"webhook": "https://www.genericwebhookurl.com/webhook"
},
"liabilities": {
"credit": [
{
"account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
"aprs": [
{
"apr_percentage": 15.24,
"apr_type": "balance_transfer_apr",
"balance_subject_to_apr": 1562.32,
"interest_charge_amount": 130.22
},
{
"apr_percentage": 27.95,
"apr_type": "cash_apr",
"balance_subject_to_apr": 56.22,
"interest_charge_amount": 14.81
},
{
"apr_percentage": 12.5,
"apr_type": "purchase_apr",
"balance_subject_to_apr": 157.01,
"interest_charge_amount": 25.66
},
{
"apr_percentage": 0,
"apr_type": "special",
"balance_subject_to_apr": 1000,
"interest_charge_amount": 0
}
],
"is_overdue": false,
"last_payment_amount": 168.25,
"last_payment_date": "2019-05-22",
"last_statement_issue_date": "2019-05-28",
"minimum_payment_amount": 20,
"next_payment_due_date": "2020-05-28"
}
],
"mortgage": [
{
"account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
"account_number": "3120194154",
"current_late_fee": 25,
"escrow_balance": 3141.54,
"has_pmi": true,
"has_prepayment_penalty": true,
"interest_rate": {
"percentage": 3.99,
"type": "fixed"
},
"last_payment_amount": 3141.54,
"last_payment_date": "2019-08-01",
"loan_term": "30 year",
"loan_type_description": "conventional",
"maturity_date": "2045-07-31",
"next_monthly_payment": 3141.54,
"next_payment_due_date": "2019-11-15",
"origination_date": "2015-08-01",
"origination_principal_amount": 425000,
"past_due_amount": 2304,
"property_address": {
"city": "Malakoff",
"country": "US",
"postal_code": "14236",
"region": "NY",
"street": "2992 Cameron Road"
},
"ytd_interest_paid": 12300.4,
"ytd_principal_paid": 12340.5
}
],
"student": [
{
"account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
"account_number": "4277075694",
"disbursement_dates": [
"2002-08-28"
],
"expected_payoff_date": "2032-07-28",
"guarantor": "DEPT OF ED",
"interest_rate_percentage": 5.25,
"is_overdue": false,
"last_payment_amount": 138.05,
"last_payment_date": "2019-04-22",
"last_statement_issue_date": "2019-04-28",
"loan_name": "Consolidation",
"loan_status": {
"end_date": "2032-07-28",
"type": "repayment"
},
"minimum_payment_amount": 25,
"next_payment_due_date": "2019-05-28",
"origination_date": "2002-08-28",
"origination_principal_amount": 25000,
"outstanding_interest_amount": 6227.36,
"payment_reference_number": "4277075694",
"pslf_status": {
"estimated_eligibility_date": "2021-01-01",
"payments_made": 200,
"payments_remaining": 160
},
"repayment_plan": {
"description": "Standard Repayment",
"type": "standard"
},
"sequence_number": "1",
"servicer_address": {
"city": "San Matias",
"country": "US",
"postal_code": "99415",
"region": "CA",
"street": "123 Relaxation Road"
},
"ytd_interest_paid": 280.55,
"ytd_principal_paid": 271.65
}
]
},
"request_id": "dTnnm60WgKGLnKL"
}
Assets
Asset endpoints allow you to create, delete, retrieve, and share Asset Reports with information about a user's assets and transactions.
Create an Asset Report
Endpoint: '/asset_report/create'
The create endpoint initiates the process of creating an Asset Report, which can then be retrieved by passing the asset_report_token return value to the /asset_report/get or /asset_report/pdf/get endpoints.
The Asset Report takes some time to be created and is not available immediately after calling create. When the Asset Report is ready to be retrieved using /asset_report/get or /asset_report/pdf/get, Plaid will fire a PRODUCT_READY webhook.
The create endpoint creates an Asset Report at a moment in time. Asset Reports are immutable. To get an updated Asset Report, use the refresh endpoint.
Field | Sub-Field | Type | Purpose |
---|---|---|---|
client_id | string | Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | |
secret | string | Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | |
access_tokens (required) | string | An array of access tokens corresponding to the Items that will be included in the report. The assets product must have been initialized for the Items during link; the Assets product cannot be added after initialization.
Min items: 1
Max items: 99 | |
days_requested | integer | The maximum integer number of days of history to include in the Asset Report. If using Fannie Mae Day 1 Certainty, days_requested must be at least 61 for new originations or at least 31 for refinancings.
Maximum: 731
Minimum: 0 | |
options | object | An optional object to filter /asset_report/create results. If provided, must be non-null. The optional user object is required for the report to be eligible for Fannie Mae's Day 1 Certainty program. | |
client_report_id | string | Client-generated identifier, which can be used by lenders to track loan applications. | |
webhook | string | URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready. | |
user | object | The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program. | |
client_user_id | string | An identifier you determine and submit for the user. | |
first_name | string | The user's first name. Required for the Fannie Mae Day 1 Certainty™ program. | |
middle_name | string | The user's middle name. | |
last_name | string | The user's last name. Required for the Fannie Mae Day 1 Certainty™ program. | |
ssn | string | The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd" | |
phone_number | string | The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis. | |
email | string | The user's email address. |
Example Request
const daysRequested = 60;
const options = {
client_report_id: '123',
webhook: 'https://www.example.com',
user: {
client_user_id: '7f57eb3d2a9j6480121fx361',
first_name: 'Jane',
middle_name: 'Leah',
last_name: 'Doe',
ssn: '123-45-6789',
phone_number: '(555) 123-4567',
email: 'jane.doe@example.com',
},
};
const request: AssetReportCreateRequest = {
access_tokens: [accessToken],
days_requested,
options,
};
// accessTokens is an array of Item access tokens.
// Note that the assets product must be enabled for all Items.
// All fields on the options object are optional.
try {
const response = await plaidClient.assetReportCreate(request);
const assetReportId = response.data.asset_report_id;
const assetReportToken = response.data.asset_report_token;
} catch (error) {
// handle error
}
Field | Type | Description |
---|---|---|
asset_report_token | string | A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
asset_report_id | string | A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. |
request_id | string | A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
Example Response:
{
"asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
"asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
"request_id": "Iam3b"
}
Retrieve an Asset Report
Endpoint '/asset_report/get'
The get endpoint retrieves the Asset Report in JSON format. Before calling the get endpoint, you must first create the Asset Report using create (or filter an Asset Report using filter) and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.
By default, an Asset Report includes transaction descriptions as returned by the bank, as opposed to parsed and categorized by Plaid. You can also receive cleaned and categorized transactions, as well as additional insights like merchant name or location information. We call this an Asset Report with Insights. An Asset Report with Insights provides transaction category, location, and merchant information in addition to the transaction strings provided in a standard Asset Report.
To retrieve an Asset Report with Insights, call the /asset_report/get
endpoint with include_insights
set to true
.
Field | Type | Description |
---|---|---|
client_id | string | Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secret | string | Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_token (required) | string | A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
include_insights | boolean | true if you would like to retrieve the Asset Report with Insights, false otherwise. This field defaults to false if omitted.
Default: false |
const request: request = {
asset_report_token: assetReportToken,
include_insights: true,
};
try {
const response = await plaidClient.assetReportGet(request);
const assetReportId = response.data.asset_report_id;
} catch (error) {
if (error.data.error_code == 'PRODUCT_NOT_READY') {
// Asset report is not ready yet. Try again later
} else {
// handle error
}
}
Field | Sub-Field | Type | Description |
---|---|---|---|
report | object | An object representing an Asset Report. | |
asset_report_id | string | A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. | |
client_report_id | string | An identifier you determine and submit for the Asset Report. | |
date_generated | string | The date and time when the Asset Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z").
Format: date-time | |
days_requested | number | The duration of transaction history you requested. | |
user | object | The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program. | |
client_user_id | stringnullable | An identifier you determine and submit for the user. | |
first_name | stringnullable | The user's first name. Required for the Fannie Mae Day 1 Certainty™ program. | |
middle_name | stringnullable | The user's middle name. | |
last_name | stringnullable | The user's last name. Required for the Fannie Mae Day 1 Certainty™ program. | |
ssn | stringnullable | The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd" | |
phone_number | stringnullable | The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis. | |
email | stringnullable | the user's email address. | |
items | object | Data returned by Plaid about each of the Items included in the Asset Report. | |
item_id | string | The item_id of the Item associated with this webhook, warning, or error | |
institution_name | string | The full financial institution name associated with the Item. | |
institution_id | string | The id of the financial institution associated with the Item. | |
date_last_updated | string | The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format.
Format: date-time | |
accounts | object | Data about each of the accounts open on the Item. | |
account_id | string | Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive. | |
balances | object | A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get. | |
available | numbernullable | The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts, the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null. | |
current | numbernullable | The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts, the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null. | |
limit | numbernullable | For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts. | |
iso_currency_code | stringnullable | The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null. | |
unofficial_currency_code | stringnullable | The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. | |
last_updated_datetime | stringnullable | Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).
Format: date-time | |
mask | stringnullable | The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. | |
name | string | The name of the account, either assigned by the user or by the financial institution itself. | |
official_name | stringnullable | The official name of the account as given by the financial institution. | |
type | string | investment: Investment account
credit: Credit card
depository: Depository account
loan: Loan account
brokerage: An investment account. Used for /assets/ endpoints only; other endpoints use investment.
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.
Possible values: investment, credit, depository, loan, brokerage, other | |
subtype | stringnullable | See the Account type schema for a full listing of account types and corresponding subtypes.
Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null | |
verification_status | string | The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.
Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed | |
days_available | number | The duration of transaction history available for this Item, typically defined as the time since the date of the earliest transaction in that account. Only returned by Assets endpoints. | |
transactions | object | Transaction history associated with the account. Only returned by Assets endpoints. Transaction history returned by endpoints such as /transactions/get or /investments/transactions/get will be returned in the top-level transactions field instead. | |
transaction_type | stringdeprecated | Please use the payment_channel field, transaction_type will be deprecated in the future.
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.
Possible values: digital, place, special, unresolved | |
pending_transaction_id | stringnullable | The ID of a posted transaction's associated pending transaction, where applicable. | |
category_id | stringnullable | The ID of the category to which this transaction belongs. See Categories.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights. | |
category | stringnullable | A hierarchical array of the categories to which this transaction belongs. See Categories.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights. | |
location | object | A representation of where a transaction took place. | |
address | stringnullable | The street address where the transaction occurred. | |
city | stringnullable | The city where the transaction occurred. | |
region | stringnullable | The region or state where the transaction occurred. | |
postal_code | stringnullable | The postal code where the transaction occurred. | |
country | stringnullable | The ISO 3166-1 alpha-2 country code where the transaction occurred. | |
lat | numbernullable | The latitude where the transaction occurred. | |
lon | numbernullable | The longitude where the transaction occurred. | |
store_number | stringnullable | The merchant defined store number where the transaction occurred. | |
payment_meta | object | Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights. | |
reference_number | stringnullable | The transaction reference number supplied by the financial institution. | |
ppd_id | stringnullable | The ACH PPD ID for the payer. | |
payee | stringnullable | For transfers, the party that is receiving the transaction. | |
by_order_of | stringnullable | The party initiating a wire transfer. Will be null if the transaction is not a wire transfer. | |
payer | stringnullable | For transfers, the party that is paying the transaction. | |
payment_method | stringnullable | The type of transfer, e.g. 'ACH'. | |
payment_processor | stringnullable | The name of the payment processor. | |
reason | stringnullable | The payer-supplied description of the transfer. | |
account_owner | stringnullable | The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts. | |
name | string | The merchant name or transaction description.
If the transactions object was returned by a Transactions endpoint such as /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights. | |
original_description | stringnullable | The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true. | |
account_id | string | The ID of the account in which this transaction occurred. | |
amount | number | The settled value of the transaction, denominated in the account's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. | |
iso_currency_code | stringnullable | The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null. | |
unofficial_currency_code | stringnullable | The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes. | |
date | string | For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ).
Format: date | |
pending | boolean | When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. | |
transaction_id | string | The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive. | |
date_transacted | stringnullable | The date on which the transaction took place, in ISO 8601 format. | |
owners | object | Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. | |
names | string | A list of names associated with the account by the financial institution. These should always be the names of individuals, even for business accounts. If the name of a business is reported, please contact Plaid Support. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array. | |
phone_numbers | object | A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. | |
data | object | The phone number. | |
primary | boolean | When true, identifies the phone number as the primary number on an account. | |
type | string | The type of phone number.
Possible values: home, work, office, mobile, mobile1, other | |
emails | object | A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. | |
data | string | The email address. | |
primary | boolean | When true, identifies the email address as the primary email on an account. | |
type | string | The type of email account as described by the financial institution.
Possible values: primary, secondary, other | |
addresses | object | Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. | |
data | object | Data about the components comprising an address. | |
city | string | The full city name | |
region | stringnullable | The region or state
Example: "NC" | |
street | string | The full street address
Example: "564 Main Street, APT 15" | |
postal_code | stringnullable | The postal code. | |
country | stringnullable | The ISO 3166-1 alpha-2 country code | |
primary | boolean | When true, identifies the address as the primary address on an account. | |
historical_balances | object | Calculated data about the historical balances on the account. Only returned by Assets endpoints. | |
date | string | The date of the calculated historical balance, in an ISO 8601 format (YYYY-MM-DD)
Format: date | |
current | number | The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each transaction.
If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting. | |
iso_currency_code | stringnullable | The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null. | |
unofficial_currency_code | stringnullable | The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes. | |
warnings | object | If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing. | |
warning_type | string | The warning type, which will always be ASSET_REPORT_WARNING. | |
warning_code | string | The warning code identifies a specific kind of warning. Currently, the only possible warning code is OWNERS_UNAVAILABLE, which indicates that account-owner information is not available.
Possible values: OWNERS_UNAVAILABLE | |
cause | object | An error object and associated item_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. | |
item_id | string | The item_id of the Item associated with this webhook, warning, or error. | |
error | objectnullable | We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. Error fields will be null if no error has occurred. | |
error_type | string | A broad categorization of the error. Safe for programatic use.
Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR | |
error_code | string | The particular error code. Safe for programmatic use. | |
error_message | string | A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. | |
display_message | stringnullable | A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use. | |
requiest_id | string | A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. | |
causes | array | In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. | |
status | numbernullable | The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. | |
documentation_url | string | The URL of a Plaid documentation page with more information about the error. | |
suggested_action | string | Suggested steps for resolving the error | |
request_id | string | A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
{
"report": {
"asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
"client_report_id": "123abc",
"date_generated": "2020-06-05T22:47:53Z",
"days_requested": 3,
"items": [
{
"accounts": [
{
"account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
"balances": {
"available": 200,
"current": 210,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"days_available": 3,
"historical_balances": [
{
"current": 210,
"date": "2020-06-04",
"iso_currency_code": "USD",
"unofficial_currency_code": null
},
{
"current": 210,
"date": "2020-06-03",
"iso_currency_code": "USD",
"unofficial_currency_code": null
},
{
"current": 210,
"date": "2020-06-02",
"iso_currency_code": "USD",
"unofficial_currency_code": null
}
],
"mask": "1111",
"name": "Plaid Saving",
"official_name": "Plaid Silver Standard 0.1% Interest Saving",
"owners": [
{
"addresses": [
{
"data": {
"city": "Malakoff",
"country": "US",
"postal_code": "14236",
"region": "NY",
"street": "2992 Cameron Road"
},
"primary": true
},
{
"data": {
"city": "San Matias",
"country": "US",
"postal_code": "93405-2255",
"region": "CA",
"street": "2493 Leisure Lane"
},
"primary": false
}
],
"emails": [
{
"data": "accountholder0@example.com",
"primary": true,
"type": "primary"
},
{
"data": "accountholder1@example.com",
"primary": false,
"type": "secondary"
},
{
"data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
"primary": false,
"type": "other"
}
],
"names": [
"Alberta Bobbeth Charleson"
],
"phone_numbers": [
{
"data": "1112223333",
"primary": false,
"type": "home"
},
{
"data": "1112224444",
"primary": false,
"type": "work"
},
{
"data": "1112225555",
"primary": false,
"type": "mobile"
}
]
}
],
"ownership_type": null,
"subtype": "savings",
"transactions": [],
"type": "depository"
},
{
"account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
"balances": {
"available": null,
"current": 56302.06,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"days_available": 3,
"historical_balances": [],
"mask": "8888",
"name": "Plaid Mortgage",
"official_name": null,
"owners": [
{
"addresses": [
{
"data": {
"city": "Malakoff",
"country": "US",
"postal_code": "14236",
"region": "NY",
"street": "2992 Cameron Road"
},
"primary": true
},
{
"data": {
"city": "San Matias",
"country": "US",
"postal_code": "93405-2255",
"region": "CA",
"street": "2493 Leisure Lane"
},
"primary": false
}
],
"emails": [
{
"data": "accountholder0@example.com",
"primary": true,
"type": "primary"
},
{
"data": "accountholder1@example.com",
"primary": false,
"type": "secondary"
},
{
"data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
"primary": false,
"type": "other"
}
],
"names": [
"Alberta Bobbeth Charleson"
],
"phone_numbers": [
{
"data": "1112223333",
"primary": false,
"type": "home"
},
{
"data": "1112224444",
"primary": false,
"type": "work"
},
{
"data": "1112225555",
"primary": false,
"type": "mobile"
}
]
}
],
"ownership_type": null,
"subtype": "mortgage",
"transactions": [],
"type": "loan"
},
{
"account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
"balances": {
"available": null,
"current": 410,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"days_available": 3,
"historical_balances": [
{
"current": 410,
"date": "2020-06-04",
"iso_currency_code": "USD",
"unofficial_currency_code": null
},
{
"current": 410,
"date": "2020-06-03",
"iso_currency_code": "USD",
"unofficial_currency_code": null
},
{
"current": 410,
"date": "2020-06-02",
"iso_currency_code": "USD",
"unofficial_currency_code": null
}
],
"mask": "3333",
"name": "Plaid Credit Card",
"official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
"owners": [
{
"addresses": [
{
"data": {
"city": "Malakoff",
"country": "US",
"postal_code": "14236",
"region": "NY",
"street": "2992 Cameron Road"
},
"primary": true
},
{
"data": {
"city": "San Matias",
"country": "US",
"postal_code": "93405-2255",
"region": "CA",
"street": "2493 Leisure Lane"
},
"primary": false
}
],
"emails": [
{
"data": "accountholder0@example.com",
"primary": true,
"type": "primary"
},
{
"data": "accountholder1@example.com",
"primary": false,
"type": "secondary"
},
{
"data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
"primary": false,
"type": "other"
}
],
"names": [
"Alberta Bobbeth Charleson"
],
"phone_numbers": [
{
"data": "1112223333",
"primary": false,
"type": "home"
},
{
"data": "1112224444",
"primary": false,
"type": "work"
},
{
"data": "1112225555",
"primary": false,
"type": "mobile"
}
]
}
],
"ownership_type": null,
"subtype": "credit card",
"transactions": [],
"type": "credit"
}
],
"date_last_updated": "2020-06-05T22:47:52Z",
"institution_id": "ins_3",
"institution_name": "Chase",
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"
}
],
"user": {
"client_user_id": "123456789",
"email": "accountholder0@example.com",
"first_name": "Alberta",
"last_name": "Charleson",
"middle_name": "Bobbeth",
"phone_number": "111-222-3333",
"ssn": "123-45-6789"
}
},
"request_id": "eYupqX1mZkEuQRx",
"warnings": []
}
Retrieve a PDF Asset Report
Endpoint: '/asset_report/pdf/get'
The '/asset_report/pdf/get' endpoint retrieves the Asset Report in PDF format. Before calling '/asset_report/pdf/get', you must first create the Asset Report using '/asset_report/create' (or filter an Asset Report using '/asset_report/filter') and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.
The response to '/asset_report/pdf/get' is the PDF binary data. The request_id
is returned in the Plaid-Request-ID header.
Field | Type | Description |
---|---|---|
client_id | string | Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secret | string | Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_token | stringrequired | A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
Example Request
try {
const request: AssetReportPDFGetRequest = {
asset_report_token: assetReportToken,
};
const response = await plaidClient.assetReportPdfGet(request, {
responseType: 'arraybuffer',
});
const pdf = response.buffer.toString('base64');
} catch (error) {
// handle error
}
A PDF of the Asset Report will be returned.
Refresh an Asset Report
Endpoint: '/asset_report/refresh'
An Asset Report is an immutable snapshot of a user's assets. In order to "refresh" an Asset Report you created previously, you can use the '/asset_report/refresh' endpoint to create a new Asset Report based on the old one, but with the most recent data available.
The new Asset Report will contain the same Items as the original Report, as well as the same filters applied by any call to '/asset_report/filter'. By default, the new Asset Report will also use the same parameters you submitted with your original '/asset_report/create' request, but the original days_requested value and the values of any parameters in the options object can be overridden with new values. To change these arguments, simply supply new values for them in your request to '/asset_report/refresh'. Submit an empty string ("") for any previously-populated fields you would like set as empty.
Field | Sub-Field | Type | Description |
---|---|---|---|
client_id | string | Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. | |
secret | string | Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. | |
asset_report_token | stringrequired | The asset_report_token returned by the original call to /asset_report/create | |
days_requested | number | The maximum number of days of history to include in the Asset Report. Must be an integer. If not specified, the value from the original call to /asset_report/create will be used.
Minimum: 0
Maximum: 731 | |
options | object | An optional object to filter /asset_report/refresh results. If provided, cannot be null. If not specified, the options from the original call to /asset_report/create will be used. | |
client_report | string | Client-generated identifier, which can be used by lenders to track loan applications. | |
webhook | string | URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready. | |
user | object | The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program. | |
client_user_id | string | An identifier you determine and submit for the user. | |
first_name | string | The user's first name. Required for the Fannie Mae Day 1 Certainty™ program. | |
middle_name | string | The user's middle name. | |
last_name | string | The user's last name. Required for the Fannie Mae Day 1 Certainty™ program. | |
ssn | string | The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd" | |
phone_number | string | The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis. | |
email | string | The user's email address. |
const request: AssetReportRefreshRequest = {
asset_report_token: assetReportToken,
daysRequested: 60,
options: {
client_report_id: '123',
webhook: 'https://www.example.com',
user: {
client_user_id: '7f57eb3d2a9j6480121fx361',
first_name: 'Jane',
middle_name: 'Leah',
last_name: 'Doe',
ssn: '123-45-6789',
phone_number: '(555) 123-4567',
email: 'jane.doe@example.com',
},
},
};
try {
const response = await plaidClient.assetReportRefresh(request);
const assetReportId = response.data.asset_report_id;
} catch (error) {
// handle error
}
Field | Type | Description |
---|---|---|
asset_report_id | string | A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. |
asset_report_token | string | A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
request_id | string | A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
{
"asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
"asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
"request_id": "NBZaq"
}
Filter Asset Report
Endpoint: '/asset_report/filter'
By default, an Asset Report will contain all of the accounts on a given Item. In some cases, you may not want the Asset Report to contain all accounts. For example, you might have the end user choose which accounts are relevant in Link using the Account Select view, which you can enable in the dashboard. Or, you might always exclude certain account types or subtypes, which you can identify by using the '/accounts/get' endpoint. To narrow an Asset Report to only a subset of accounts, use the '/asset_report/filter' endpoint.
To exclude certain Accounts from an Asset Report, first use the '/asset_report/create' endpoint to create the report, then send the asset_report_token along with a list of account_ids to exclude to the '/asset_report/filter' endpoint, to create a new Asset Report which contains only a subset of the original Asset Report's data.
Because Asset Reports are immutable, calling '/asset_report/filter' does not alter the original Asset Report in any way; rather, '/asset_report/filter' creates a new Asset Report with a new token and id. Asset Reports created via '/asset_report/filter' do not contain new Asset data, and are not billed.
Plaid will fire a PRODUCT_READY webhook once generation of the filtered Asset Report has completed.
Field | Type | Description |
---|---|---|
client_id | string | Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secret | string | Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_token | stringrequired | A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
account_ids_to_exclude | stringrequired | The accounts to exclude from the Asset Report, identified by account_id. |
const request: AssetReportFilterRequest = {
asset_report_token: assetReportToken,
account_ids_to_exclude: ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'],
};
try {
const reponse = await plaidClient.assetReportFilter(request);
const assetReportId = response.data.asset_report_id;
} catch (error) {
// handle error
}
Field | Type | Description |
---|---|---|
asset_report_token | string | A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
asset_report_id | string | A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. |
request_id | string | A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
{
"asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
"asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
"request_id": "qEg07"
}
Delete and Asset Report
Endpoint: '/asset_report/remove'
The '/item/remove' endpoint allows you to invalidate an access_token, meaning you will not be able to create new Asset Reports with it. Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove them specifically.
The '/asset_report/remove' endpoint allows you to remove an Asset Report. Removing an Asset Report invalidates its asset_report_token, meaning you will no longer be able to use it to access Report data or create new Audit Copies. Removing an Asset Report does not affect the underlying Items, but does invalidate any audit_copy_tokens associated with the Asset Report.
Field | Type | Description |
---|---|---|
client_id | string | Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secret | string | Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_token | string | A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
const request: AssetReportRemoveRequest = {
asset_report_token: assetReportToken,
};
try {
const response = await plaidClient.assetReportRemove(request);
const removed = response.data.removed;
} catch (error) {
// handle error
}
Field | Type | Description |
---|---|---|
removed | boolean | true if the Asset Report was successfully removed. |
request_id | string | A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
{
"removed": true,
"request_id": "I6zHN"
}
Create an Asset Report Audit Copy
Endpoint: '/asset_report/audit_copy/create'
Plaid can provide an Audit Copy of any Asset Report directly to a participating third party on your behalf. For example, Plaid can supply an Audit Copy directly to Fannie Mae on your behalf if you participate in the Day 1 Certainty™ program. An Audit Copy contains the same underlying data as the Asset Report.
To grant access to an Audit Copy, use the '/asset_report/audit_copy/create' endpoint to create an audit_copy_token and then pass that token to the third party who needs access. Each third party has its own auditor_id, for example 'fannie_mae'. You’ll need to create a separate Audit Copy for each third party to whom you want to grant access to the Report.
Field | Type | Description |
---|---|---|
client_id | string | Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secret | string | Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
asset_report_token | stringrequired | A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report. |
auditor_id | stringrequired | The auditor_id of the third party with whom you would like to share the Asset Report. |
// The auditor ID corresponds to the third party with which you want to share
// the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.
const request: AssetReportAuditCopyCreateRequest = {
asset_report_token: createResponse.data.asset_report_token,
auditor_id: 'fannie_mae',
};
try {
const response = await plaidClient.assetReportAuditCopyCreate(request);
const auditCopyToken = response.data.audit_copy_token;
} catch (error) {
// handle error
}
Field | Type | Description |
---|---|---|
audit_copy_token | string | A token that can be shared with a third party auditor to allow them to obtain access to the Asset Report. This token should be stored securely. |
request_id | string | A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
{
"audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
"request_id": "Iam3b"
}
Remove Asset Report Audit Copy
Endpoint: '/asset_report/audit_copy/remove'
The /asset_report/audit_copy/remove endpoint allows you to remove an Audit Copy. Removing an Audit Copy invalidates the audit_copy_token associated with it, meaning both you and any third parties holding the token will no longer be able to use it to access Report data. Items associated with the Asset Report, the Asset Report itself and other Audit Copies of it are not affected and will remain accessible after removing the given Audit Copy.
Field | Type | Description |
---|---|---|
client_id | string | Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body. |
secret | string | Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body. |
audit_copy_token | stringrequired | The audit_copy_token granting access to the Audit Copy you would like to revoke. |
// auditCopyToken is the token from the createAuditCopy response.
const request: AssetReportAuditCopyRemoveRequest = {
audit_copy_token: auditCopyToken,
};
try {
const response = await plaidClient.assetReportAuditCopyRemove(request);
const removed = response.data.removed;
} catch (error) {
// handle error
}
Field | Type | Description |
---|---|---|
removed | boolean | true if the Audit Copy was successfully removed. |
request_id | string | A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
{
"removed": true,
"request_id": "m8MDnv9okwxFNBV"
}
Endpoint | Description |
---|---|
/item/get | Returns information about the status of an item. |
/item/remove | Removes a specific Item. |
/item/webhook/update | Updates the webhooks associated with an item. |
/institutions/get | Gets a list of institutions available through Link Money API. |
/institutions/get_by_id | Gets an institution with a particular ID in the Link Money API. |
/institutions/search | Search for a particular institution. |
/accounts/get | Get all the accounts associated with a single item. |
/transactions/get | Get all the transactions associated with a single item. |
/transactions/refresh | Request a refresh on transactions associated with a single item. |
/categories/get | Get all the categories supported by the Link Money API. |
/accounts/balance/get | Get the balances of accounts associated with a single item. |
/asset_report/create | |
/asset_report/get | |
/asset_report/pdf/get | |
/asset_report/refresh | |
/asset_report/filter | |
/asset_report/remove | |
/asset_report/audit_copy/create | |
/asset_report/audit_copy/remove | |
/investments/holdings/get | Get a list of user-authorized stock position data for investment-type accounts. |
/investments/transactions/get | Retrieve user-authorized transaction data for investment accounts. |
/liabilities/get | Retrieve various details about an Item with loan or credit accounts. |
Name | Description |
---|---|
Plaid Endpoints | Plaid endpoints are for developers who have been using Plaid as an aggregator. Developers can find near clones of the Plaid routes they were previously using. |
MX Endpoints | MX endpoints are for developers who have been using MX as an aggregator. Developers can find near clones of the MX routes they were previously using. |
Yodlee Endpoints | Yodlee endpoints are for developers who have been using Yodlee as an aggregator. Developers can find near clones of the Yodlee routes they were previously using. |
Developer Configuration Routes | Developer configurations are how Link Money stores details about particular developer accounts, including their data type and webhook preferences. |
Link Money Data Routes | Link Money API provides more than the traditional aggregation function suite. Any additional custom features may live here. |
Plaid Webhooks
Link Money API uses Webhooks to send updates to developers that lets developer applications know about data changes for new transactions, account balance updates, new account connections, and anything else worth sending a real-time update. This functionality also lets developers who use it skip having to pull data from the Link Money API on regular intervals to keep their applications abreast of the freshest user data.
Different aggregators have different webhook methodologies, schemas, and approaches. Link Money API offers webhooks in a variety of formats to make migrating from another aggregator's webhook system.
Plaid offers developers a robust series of events that trigger webhooks for a variety of reasons. Developers use these webhooks to keep their user data current with their user's accounts. Plaid's webhooks follow a specific model. Developers must write code that adheres to this model, and changing webhook reception code can be tedious and painstaking. Link Money therefore offers webhook subscriptions for Plaid-specific webhook integrations so that developers don't need to change their backend code in any way.
Item Webhooks
Item webhooks communicate changes or errors with Items. Often, errors with item webhooks describe account linking problems that the end user must take action to remediate.
Item webhooks also communicate changes with particular items that are not erroneous, such as intentional unlinking of accounts.
An Item Has Encountered An Error.
The developer can subscribe to receive a notification whenever there is a problem with an Item that the developer has access to.
Subscribing
Receiving
Parameters
Field | Type | Description | Required |
---|---|---|---|
webhook_type | string | Indicates the type of the webhook. For this webhook, it will always be ITEM . | |
webhook_code | string | Indicates the code of the webhook. For this webhook, it will always be ERROR . | |
item_id | string | The identifier for which item the error refers to. | |
error | Error | An error object describing the particular problem that has occurred (see the Plaid Error Reference |
Example Webhook
{
"webhook_type": "ITEM",
"webhook_code": "ERROR",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": {
"display_message": null,
"error_code": "ITEM_LOGIN_REQUIRED",
"error_message": "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",
"error_type": "ITEM_ERROR",
"status": 400
}
}
An Item Is Approaching Expiration
Some institutions require users coming from the LinkMoney experience to periodically resupply their credentials to keep an account connection active. LinkMoney supplies developers with advance warning that such an expiration is approaching.
Subscribing
Receiving
Parameters
Name | Tags | Description |
---|---|---|
webhook_type | string | Describes the type of webhook that is being sent. In this case, it will always be ITEM . |
webhook_code | string | Describes the code of the webhook that is being sent. In this case, it will always be PENDING_EXPIRATION |
item_id | string | The identifier for which item the error refers to. |
consent_expiration_time | string | The date and time at which the Item's access will expire, in ISO 8601 format. |
Example Webhook
{
"webhook_type": "ITEM",
"webhook_code": "PENDING_EXPIRATION",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"consent_expiration_time": "2020-01-15T13:25:17.766Z"
}
A User Has Revoked Permission to Access an Item.
End users of LinkMoney have the right and the ability to unlink their accounts from the LinkMoneyAPI. For developer experience, LinkMoney lets developers know when one of their subscribed user's items will no longer be linked.
Subscribing
Receiving
Parameters
Name | Tags | Description |
---|---|---|
webhook_type | string | Describes the type of webhook that is being sent. In this case, it will always be ITEM . |
webhook_code | string | Describes the code of the webhook that is being sent. In this case, it will always be USER_PERMISSION_REVOKED . |
item_id | string | The identifier for which item the error refers to. |
error | Error | An Error item, as described in the Plaid Error Reference USER_PERMISSION_REVOKED |
Example Webhook
{
"webhook_type": "ITEM",
"webhook_code": "USER_PERMISSION_REVOKED",
"error": {
"error_code": "USER_PERMISSION_REVOKED",
"error_message": "the holder of this account has revoked their permission for your application to access it",
"error_type": "ITEM_ERROR",
"status": 400
},
"item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ"
}
The Item Webhook Configuration has been updated.
Whenever the developer changes their configuration to select new options or a new webhook URL, LinkMoney will trigger a webhook to notify their server at the newly-configured webhook URL of the update.
Subscribing
Receiving
Parameters
Name | Tags | Description |
---|---|---|
webhook_type | string | Describes the type of webhook that is being sent. In this case, it will always be ITEM . |
webhook_code | string | Describes the code of the webhook that is being sent. In this case, it will always be WEBHOOK_UPDATE_ACKNOWLEDGED . |
item_id | string | The identifier for which item the error refers to. |
error | Error | An Error item, as described in the Plaid Error Reference null . |
new_webhook_url | string | The new webhook URL. |
Example Webhook
{
"webhook_type": "ITEM",
"webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_webhook_url": "https://plaid.com/example/webhook"
}
Transaction Webhooks
Transaction webhooks communicate changes in the transaction history for a particular item. This can include the removal of transactions, update to transactions, and new transactions associated with the account.
An Account Was Linked and Initial Transactions Are Available.
After an item is linked for the first time, a large amount of new transaction data for the last 30 days is retrieved for the newly-linked Item. This webhook lets developers know that the new data is now retrievable in the API.
Subscribing
Receiving
Parameters
Name | Tags | Description |
---|---|---|
webhook_type | string | Describes the type of webhook that is being sent. In this case, it will always be TRANSACTIONS . |
webhook_code | string | Describes the code of the webhook that is being sent. In this case, it will always be INITIAL_UPDATE . |
item_id | string | The identifier for which item the error refers to. |
error | Error | Unless the initial update encountered an error, this field will be null . Otherwise, it will be an error as described by the Plaid Error Reference |
new_transactions | number | The number of new, unfetched transactions available. |
Example Webhook
{
"webhook_type": "TRANSACTIONS",
"webhook_code": "INITIAL_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 19
}
Historical Transactions are Available.
After a developer asks for a large number of historical transactions, a webhook for the item the request was made on will fire, notifying the developer that the transactions are now available
Subscribing
Receiving
Parameters
Name | Tags | Description |
---|---|---|
webhook_type | string | Describes the type of webhook that is being sent. In this case, it will always be TRANSACTIONS . |
webhook_code | string | Describes the code of the webhook that is being sent. In this case, it will always be HISTORICAL_UPDATE . |
item_id | string | The identifier for which item the error refers to. |
error | Error | Unless the operation encountered an error, this field will be null . Otherwise, it will be an error as described by the Plaid Error Reference |
new_transactions | number | The number of new, unfetched transactions available. |
Example Webhook
{
"webhook_type": "TRANSACTIONS",
"webhook_code": "HISTORICAL_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 231
}
New Transactions are Available for an Item.
Several times a day, new transactions will become available for an item that a consumer spends regularly on. When this occurs, a new transactions webhook triggers.
Subscribing
Receiving
Parameters
Name | Tags | Description |
---|---|---|
webhook_type | string | Describes the type of webhook that is being sent. In this case, it will always be TRANSACTIONS . |
webhook_code | string | Describes the code of the webhook that is being sent. In this case, it will always be DEFAULT_UPDATE . |
item_id | string | The identifier for which item the error refers to. |
error | Error | Unless the operation encountered an error, this field will be null . Otherwise, it will be an error as described by the Plaid Error Reference |
new_transactions | number | The number of new, unfetched transactions available. |
Example Webhook
{
"webhook_type": "TRANSACTIONS",
"webhook_code": "DEFAULT_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_transactions": 3
}
Transactions have been Removed from an Item.
Sometimes transactions associated with an item are erroneous. If an institution subsequently deletes the transactions, LinkMoneyAPI fires a transaction removal webhook to the developer.
Subscribing
Receiving
Parameters
Name | Tags | Description |
---|---|---|
webhook_type | string | Describes the type of webhook that is being sent. In this case, it will always be ITEM . |
webhook_code | string | Describes the code of the webhook that is being sent. In this case, it will always be TRANSACTIONS_REMOVED . |
item_id | string | The identifier for which item the error refers to. |
removed_transactions | string[] | A list of the transaction_ids corresponding to the removed transactions. |
error | Error | Unless the operation encountered an error, this field will be null . Otherwise, it will be an error as described by the Plaid Error Reference |
Example Webhook
Investment Webhooks
Investment webhooks communicate changes in investment-type accounts. For changes in ordinary accounts, see Item Webhooks. For changes in liability-type accounts, see Liability Webhooks.
Updates to an Investment Account's Holdings
Whenever holdings are added to or updated in an investment account, LinkMoney API triggers a webhook to notify authorized developers of the change.
Subscribe
Receive
Parameters
Field | Type | Description |
---|---|---|
webhook_type | string | The type of this webhook. In this case, the value will always be HOLDINGS . |
webhook_code | string | The code for this webhook. In this case, the value will always be DEFAULT_UPDATE . |
item_id | string | The ID of the Item this update is for. |
error | Error | This field will be null if no error was encountered. If an error did occur, the error object is as described by the Plaid Error Reference |
new_holdings | number | The number of new holdings reported since the last time this webhook was fired. |
updated_holdings | number | The number of updated holdings reported since the last time this webhook was fired. |
Example Webhook
{
"webhook_type": "HOLDINGS",
"webhook_code": "DEFAULT_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_holdings": 19,
"updated_holdings": 0
}
New Transactions in an Investment Account.
Whenever new transactions are detected on an investment account, or whenever transactions are cancelled on an investment account, LinkMoneyAPI fires a webhook to notify authorized developers of the change.
Subscribe
Receive
Parameters
Field | Type | Description |
---|---|---|
webhook_type | string | The type of this webhook. In this case, the value will always be INVESTMENTS_TRANSACTIONS . |
webhook_code | string | The code for this webhook. In this case, the value will always be DEFAULT_UPDATE . |
item_id | string | The ID of the Item this update is for. |
error | Error | This field will be null if no error was encountered. If an error did occur, the error object is as described by the Plaid Error Reference |
new_investments_transactions | number | The number of new transactions reported since the last time this webhook was fired. |
canceled_investments_transactions | number | The number of canceled transactions reported since the last time this webhook was fired. |
Example Webhook
{
"webhook_type": "INVESTMENTS_TRANSACTIONS",
"webhook_code": "DEFAULT_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"new_investments_transactions": 16,
"canceled_investments_transactions": 0
}
Liability Webhooks
Liability webhooks communicate changes in liability-type accounts. For changes in ordinary accounts, see Item Webhooks. For changes in investment-type accounts, see Investment Webhooks.
Updates to an Liability Account's Holdings
Whenever new or updated liabilities are detected on a liabilities Item, LinkMoneyAPI triggers a webhook to notify authorized developers of the change.
Subscribe
Receive
Parameters
Field | Type | Description |
---|---|---|
webhook_type | string | The type of this webhook. In this case, the value will always be LIABILITIES . |
webhook_code | string | The code for this webhook. In this case, the value will always be DEFAULT_UPDATE . |
item_id | string | The ID of the Item this update is for. |
error | Error | This field will be null if no error was encountered. If an error did occur, the error object is as described by the Plaid Error Reference |
account_ids_with_new_liabilities | string[] | An array of account_ids for accounts that contain new liabilities. |
account_ids_with_updated_liabilities | Object | An object with keys of account_id s that are mapped to their respective liabilities field that changed. See the example webhook for the conventional format. |
Example Webhook
{
"webhook_type": "LIABILITIES",
"webhook_code": "DEFAULT_UPDATE",
"item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
"error": null,
"account_ids_with_new_liabilities": [
"XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
"BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
],
"account_ids_with_updated_liabilities": {
"XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": [
"past_amount_due"
]
}
}
Auth Webhooks
Auth webhooks communicate changes of verification status with Items. Attempting to retrieve an Item before micro deposit verification has succeeded will result in a response code of 400
and a Plaid error code of PRODUCT_NOT_READY
.
Automatically Verified
Sent when an item has been successfully verified via automated micro deposits
Name | Type | Description |
---|---|---|
webhook_type | String | Describes the type of webhook that is being sent. In this case, it will always be AUTH . |
webhook_code | String | Describes the code of the webhook that is being sent. In this case, it will always be AUTOMATICALLY_VERIFIED . |
account_id | String | The account_id of the account associated with the webhook |
item_id | String | The item_id
of the Item associated with this webhook, warning, or error |
Example Webhook
{
"webhook_type": "AUTH",
"webhook_code": "AUTOMATICALLY_VERIFIED",
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
"account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK"
}
Verification Expired
Sent when an item has not been verified via automated micro deposits after seven days from when the micro deposits were made.
Name | Type | Description |
---|---|---|
webhook_type | String | Describes the type of webhook that is being sent. In this case, it will always be AUTH . |
webhook_code | String | Describes the code of the webhook that is being sent. In this case, it will always be VERIFICATION_EXPIRED . |
account_id | String | The account_id of the account associated with the webhook |
item_id | String | The item_id
of the Item associated with this webhook, warning, or error |
Example Webhook
{
"webhook_type": "AUTH",
"webhook_code": "VERIFICATION_EXPIRED",
"item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
"account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
}
Verification
Webhooks can be observed to come from LinkMoney web and IP addresses, but sometimes this is not enough to to verify that the webhook's payload is secure. To work around this, LinkMoney uses a Webhook-Verification
header.
Note that the verification step is optional; LinkMoney webhooks can be used without the verification step.
express-jwt
package provided and maintained by Auth0. Walkthrough
1. Extract the Webhook Verification Header.
const jwt = require("express-jwt");
const { headers } = request;
const verificationHeader = request['Webhook-Verification'];
// yields JWT
const JWT = jwt.decode(verificationHeader);
2. Validate the Decoded JWT (header) fields.
{
"alg": "ES256",
"kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
"typ": "JWT"
}
- If the
alg
field is notES256
, reject the webhook. - If any of the above fields are missing, reject the webhook.
3. Use the kid
field to request a webhook verification key.
const { kid } = JWT; // see step one for getting JWT
const response = await request("/webhook__verification_key", {
method: "POST",
headers: {
"content-type": "application/json",
},
body: {
"client_id": {MY_CLIENT_ID},
"client_secret": {MY_CLIENT_SECRET),
"key_id": kid, // add the kid here.
},
});
if (response.ok) {
const data = await response.json();
const { key } = data;
return key;
} else {
// error
}
This call will yield a JSON payload containing a single property, key
. This key is a JWK.
{
"key": {
"alg": "ES256",
"created_at": 1560466150,
"crv": "P-256",
"expired_at": null,
"kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
"kty": "EC",
"use": "sig",
"x": "hKXLGIjWvCBv-cP5euCTxl8g9GLG9zHo_3pO5NN1DwQ",
"y": "shhexqPB7YffGn6fR6h2UhTSuCtPmfzQJ6ENVIoO4Ys"
},
"request_id": "RZ6Omi1bzzwDaLo"
}
If the request does not return a key, reject the webhook.
4. Use the JWK to validate the webhook signature.
const client = new JwksClient(options)
const key; // see above for deriving the JWK
const jwtCheck = expressJwt({
secret: key,
// audience
// issuer
algorithms: ["ES256"],
});
module.exports = jwtCheck;
If the call's signature is invalid, it will be rejected by the middleware.
5. Call the JWT Check as Middleware.
app.post("/my-api/webhook", jwtCheck, // my middlewares);
Full Example
//This example uses jose v2, not the latest version
const compare = require('secure-compare');
const jwt_decode = require('jwt-decode');
const JWT = require('jose');
const sha256 = require('js-sha256');
// Cache for webhook validation keys.
const KEY_CACHE = new Map();
const verify = async (body, headers) => {
const signedJwt = JSON.parse(headers)['webhook-verification'];
const decodedToken = jwt_decode(signedJwt);
const decodedTokenHeader = jwt_decode(signedJwt, { header: true });
const currentKeyID = decodedTokenHeader.kid;
//If key not in cache, update the key cache
if (!KEY_CACHE.has(currentKeyID)) {
const keyIDsToUpdate = [];
KEY_CACHE.forEach((keyID, key) => {
if (key.expired_at == null) {
keyIDsToUpdate.push(keyID);
}
});
keyIDsToUpdate.push(currentKeyID);
for (keyID of keyIDsToUpdate) {
UPDATE WITH REQUEST !!!!!
const verificationKeyResponse = await plaidClient
.getWebhookVerificationKey(keyID)
.catch((err) => {
// decide how you want to handle unexpected API errors,
// e.g. retry later
return false;
});
const key = verificationKeyResponse.key;
KEY_CACHE.set(keyID, key);
}
}
// If the key ID is not in the cache, the key ID may be invalid.
if (!KEY_CACHE.has(currentKeyID)) {
return false;
}
// Fetch the current key from the cache.
const key = KEY_CACHE.get(currentKeyID);
// Reject expired keys.
if (key.expired_at != null) {
return false;
}
// Validate the signature and iat
try {
JWT.verify(signedJwt, key, { maxTokenAge: '5 min' });
} catch (error) {
return false;
}
// Compare hashes
const bodyHash = sha256(body);
const claimedBodyHash = decodedToken.request_body_sha256;
return compare(bodyHash, claimedBodyHash);
};
Name | Description |
---|---|
Item Webhooks | Item Webhooks communicate changes to Items. |
Transaction Webhooks | Transaction Webhooks communicate changes to transaction data, including Initial Transaction Drops, New Transactions, Deleted Transactions, and Historical Data Pulls. |
Investment Webhooks | Investment Webhooks communicate changes in transaction data for investment-type accounts. |
Liability Webhooks | Liability Webhooks communicate changes in transaction data for loan-type accounts. |
Plaid Schemas
type: object
properties:
account_id:
type: string
description: Plaid's unique identifier for the account.
example:
balances:
type: object
description: A set of fields describing the balance for an account.
properties:
available:
type: number
description: The amount of funds available to be withdrawn from the account.
example:
current:
type: number
description: The total amount of funds in or owed by the accounts.
example:
limit:
type: number
description: For credit-type accounts, this represents the credit limit.
example:
iso_currency_code:
type: string
description: The ISO-4217 currency code of the balance.
example: "USD"
unofficial_currency_code:
type: string
description: The unofficial currency code associated with the balance.
example:
mask:
type: string
description: The last 2-4 alphanumeric characters of an account's official account number.
example: "2345"
name:
type: string
description: The name of the account, either assigned by the user or by the financial institution.
example: "Joe's Checking"
official_name:
type: string
description: The official name of the account as given by the financial institution.
example: "CHECKING"
type:
type: string
description: The variety of the account.
examples:
- credit
- loan
- investment
- depository
- brokerage
subtype:
type: string
description: The subvariety of the account, if applicable.
examples:
- 401a
- 401k
- savings account
- credit card
- roth
- mortgage
verification_status:
type: string
description: The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
example: pending_automatic_verification
type: object
properties:
transaction_id:
type: string
description: "The Plaid issued transactionID for this particular transaction."
example: "dfg74Fi3so8dRsw4378c"
required: true
account_id:
type: string
description: "The Plaid-issued accountID for the account this transaction was made under."
example: "F034jf439fSg09432pjegior"
required: true
account_owner:
type: string
description: The nickname of the owner of the account associated with this transaction.
example: "JACKRYAN"
amount:
type: number
description: "The amount of the transaction."
example: 25.50
required: true
authorized_date:
type: string
description: An ISO formatted data for the transaction if the transaction has posted.
example: "2020-12-30"
iso_currency_code:
type: string
description: "The official currency code for the transaction amount."
example: USD
required: true
unofficial_currency_code:
type: string
description: The unofficial currency code for the transaction amount.
category:
type: array
items:
type: string
description: An array of categories pertaining to this transaction.
example:
- Food and Beverage
- Coffee Shops
category_id:
type: string
description: A unique alphanumeric ID issued by Plaid referring to the ID of the main category.
date:
type: string
description: "An ISO date for the original date on which the transaction took place."
example: "2020-12-25"
required: true
location:
type: object
properties:
address:
type: string
description: The street address where the transaction took place.
example: "1234 South Street"
city:
type: string
description: The city where the transaction took place.
example: Lafayette
lat:
type: number
description: The latitude where the transaction took place.
example:
lon:
type: number
description: The longitude where the transaction took place.
example:
store_number:
type: number
description: The number of the specific store if the transaction took place at a brick-and-mortar chain.
example: 2243
region:
type: string
description: The broad region where the transaction took place. In the US, this is usually the state.
example: CO
postal_code:
type: string
description: The postal code where the transaction took place.
example: "80027"
country:
type: string
description: The country where the transaction took place.
example: USA
merchant_name:
type: string
description: The Plaid-issued name of the merchant where the transaction is from.
example: Otis Coffee Company
name:
type: string
description: "The main Plaid-issued name of the merchant where the transaction is from"
example: Otis Coffee Company
required: true
payment_channel:
type: string
description: The payment channel for the transaction.
example: Online
pending:
type: boolean
description: "Denotes whether the transaction is pending or posted."
example: false
required: true
pending_transaction_id:
type: string
description: "The Plaid-issued unique alphanumeric ID for the associated pending transaction record if this transaction has posted."
transaction_type:
type: string
description: Shows the type of the transaction.
example: debit
transaction_code:
type: string
description: The code of the transaction.
example: "yes"
uid:
type: string
description: "The unique alphanumeric ID of the user within either the client's system, or the unique user ID generated by Plaid."
example: 1pfmZehrgenWog4kfn3pI4sd
required: true
insight_text:
type: string
description: A short, descriptive test field describing the advice or deal that a fingineer has discovered for this transaction.
example: "sss"
insight_ctaurl:
type: string
description: The call to action URL for the advice. Sends the end user to a web page for actionable information to follow the advice.
finsight_image:
type: string
description: A url for a relevant image associated with the advice. Generally, this will be a logo for the merchant FinGoal recommends.
recommendation:
type: string
description: A short title for the Finsight. Generally this will be the name of the merchant that FinGoal recommends.
amountFound:
type: float
description: The amount of "found money" the fingineer estimates this advice will save the end user if it is followed.
type: object
properties:
transaction_id:
type: string
description: "The Plaid issued transactionID for this particular transaction."
example: "dfg74Fi3so8dRsw4378c"
required: true
account_id:
type: string
description: "The Plaid-issued accountID for the account this transaction was made under."
example: "F034jf439fSg09432pjegior"
required: true
account_owner:
type: string
description: The nickname of the owner of the account associated with this transaction.
example: "JACKRYAN"
amount:
type: number
description: "The amount of the transaction."
example: 25.50
required: true
authorized_date:
type: string
description: An ISO formatted data for the transaction if the transaction has posted.
example: "2020-12-30"
iso_currency_code:
type: string
description: "The official currency code for the transaction amount."
example: USD
required: true
unofficial_currency_code:
type: string
description: The unofficial currency code for the transaction amount.
category:
type: array
items:
type: string
description: An array of categories pertaining to this transaction.
example:
- Food and Beverage
- Coffee Shops
category_id:
type: string
description: A unique alphanumeric ID issued by Plaid referring to the ID of the main category.
date:
type: string
description: "An ISO date for the original date on which the transaction took place."
example: "2020-12-25"
required: true
location:
type: object
properties:
address:
type: string
description: The street address where the transaction took place.
example: "1234 South Street"
city:
type: string
description: The city where the transaction took place.
example: Lafayette
lat:
type: number
description: The latitude where the transaction took place.
example:
lon:
type: number
description: The longitude where the transaction took place.
example:
store_number:
type: number
description: The number of the specific store if the transaction took place at a brick-and-mortar chain.
example: 2243
region:
type: string
description: The broad region where the transaction took place. In the US, this is usually the state.
example: CO
postal_code:
type: string
description: The postal code where the transaction took place.
example: "80027"
country:
type: string
description: The country where the transaction took place.
example: USA
merchant_name:
type: string
description: The Plaid-issued name of the merchant where the transaction is from.
example: Otis Coffee Company
name:
type: string
description: "The main Plaid-issued name of the merchant where the transaction is from"
example: Otis Coffee Company
required: true
payment_channel:
type: string
description: The payment channel for the transaction.
example: Online
pending:
type: boolean
description: "Denotes whether the transaction is pending or posted."
example: false
required: true
pending_transaction_id:
type: string
description: "The Plaid-issued unique alphanumeric ID for the associated pending transaction record if this transaction has posted."
transaction_type:
type: string
description: Shows the type of the transaction.
example: place
transaction_code:
type: string
description: The code of the transaction.
example: "purchase"
uid:
type: string
description: "The unique alphanumeric ID of the user within either the client's system, or the unique user ID generated by Plaid."
example: 1pfmZehrgenWog4kfn3pI4sd
required: true
type: object
properties:
city:
type: string
description: The city where the user resides.
example: Malakoff
country:
type: string
description: The country where the user resides.
example: US
postal_code:
type: string
description: The zip code where the user resides.
example: "14326"
region:
type: string
description: The region (in the US, state) where the user resides.
example: "NY"
street:
type: string
description: The street address for the user.
example: "2992 Cameron Road"
emails:
type: array
description: An array of the emails associated with the account.
example:
- totally.fake.email@notreal.com
names:
type: string
description: The user's name.
example: Cameron Howe
phone_numbers:
type: array
description: An array of the user's phone numbers.
example:
- "1112223333"