Liabilities
API reference for Liabilities endpoints and webhooks
Endpoints | |
---|---|
/liabilities/get | Fetch liabilities data |
Webhooks | |
---|---|
DEFAULT_UPDATE | New or updated liabilities available |
Endpoints
/liabilities/get
Retrieve Liabilities data
The /liabilities/get
endpoint returns various details about an Item with loan or credit accounts. Liabilities data is available primarily for US financial institutions, with some limited coverage of Canadian institutions. Currently supported account types are account type credit
with account subtype credit card
or paypal
, and account type loan
with account subtype student
or mortgage
. To limit accounts listed in Link to types and subtypes supported by Liabilities, you can use the account_filters
parameter when creating a Link token.
The types of information returned by Liabilities can include balances and due dates, loan terms, and account details such as original loan amount and guarantor. Data is refreshed approximately once per day; the latest data can be retrieved by calling /liabilities/get
.
Note: This request may take some time to complete if liabilities
was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the additional data.
Request fields and example
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_token requiredstring The access token associated with the Item data is being requested for. | |
options object An optional object to filter /liabilities/get results. If provided, options cannot be null.
|
1// Retrieve Liabilities data for an Item2const request: LiabilitiesGetRequest = {3 access_token: accessToken,4};5try {6 const response = await plaidClient.liabilitiesGet(request);7 const liabilities = response.data.liabilities;8} catch (error) {9 // handle error10}
Response fields and example
accounts [object] An array of accounts associated with the Item
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
item object Metadata about the Item.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
liabilities object An object containing liability accounts
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
request_id string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1{2 "accounts": [3 {4 "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",5 "balances": {6 "available": 100,7 "current": 110,8 "iso_currency_code": "USD",9 "limit": null,10 "unofficial_currency_code": null11 },12 "mask": "0000",13 "name": "Plaid Checking",14 "official_name": "Plaid Gold Standard 0% Interest Checking",15 "subtype": "checking",16 "type": "depository"17 },18 {19 "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",20 "balances": {21 "available": null,22 "current": 410,23 "iso_currency_code": "USD",24 "limit": 2000,25 "unofficial_currency_code": null26 },27 "mask": "3333",28 "name": "Plaid Credit Card",29 "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",30 "subtype": "credit card",31 "type": "credit"32 },33 {34 "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",35 "balances": {36 "available": null,37 "current": 65262,38 "iso_currency_code": "USD",39 "limit": null,40 "unofficial_currency_code": null41 },42 "mask": "7777",43 "name": "Plaid Student Loan",44 "official_name": null,45 "subtype": "student",46 "type": "loan"47 },48 {49 "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",50 "balances": {51 "available": null,52 "current": 56302.06,53 "iso_currency_code": "USD",54 "limit": null,55 "unofficial_currency_code": null56 },57 "mask": "8888",58 "name": "Plaid Mortgage",59 "official_name": null,60 "subtype": "mortgage",61 "type": "loan"62 }63 ],64 "item": {65 "available_products": [66 "balance",67 "investments"68 ],69 "billed_products": [70 "assets",71 "auth",72 "identity",73 "liabilities",74 "transactions"75 ],76 "consent_expiration_time": null,77 "error": null,78 "institution_id": "ins_3",79 "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",80 "update_type": "background",81 "webhook": "https://www.genericwebhookurl.com/webhook"82 },83 "liabilities": {84 "credit": [85 {86 "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",87 "aprs": [88 {89 "apr_percentage": 15.24,90 "apr_type": "balance_transfer_apr",91 "balance_subject_to_apr": 1562.32,92 "interest_charge_amount": 130.2293 },94 {95 "apr_percentage": 27.95,96 "apr_type": "cash_apr",97 "balance_subject_to_apr": 56.22,98 "interest_charge_amount": 14.8199 },100 {101 "apr_percentage": 12.5,102 "apr_type": "purchase_apr",103 "balance_subject_to_apr": 157.01,104 "interest_charge_amount": 25.66105 },106 {107 "apr_percentage": 0,108 "apr_type": "special",109 "balance_subject_to_apr": 1000,110 "interest_charge_amount": 0111 }112 ],113 "is_overdue": false,114 "last_payment_amount": 168.25,115 "last_payment_date": "2019-05-22",116 "last_statement_issue_date": "2019-05-28",117 "last_statement_balance": 1708.77,118 "minimum_payment_amount": 20,119 "next_payment_due_date": "2020-05-28"120 }121 ],122 "mortgage": [123 {124 "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",125 "account_number": "3120194154",126 "current_late_fee": 25,127 "escrow_balance": 3141.54,128 "has_pmi": true,129 "has_prepayment_penalty": true,130 "interest_rate": {131 "percentage": 3.99,132 "type": "fixed"133 },134 "last_payment_amount": 3141.54,135 "last_payment_date": "2019-08-01",136 "loan_term": "30 year",137 "loan_type_description": "conventional",138 "maturity_date": "2045-07-31",139 "next_monthly_payment": 3141.54,140 "next_payment_due_date": "2019-11-15",141 "origination_date": "2015-08-01",142 "origination_principal_amount": 425000,143 "past_due_amount": 2304,144 "property_address": {145 "city": "Malakoff",146 "country": "US",147 "postal_code": "14236",148 "region": "NY",149 "street": "2992 Cameron Road"150 },151 "ytd_interest_paid": 12300.4,152 "ytd_principal_paid": 12340.5153 }154 ],155 "student": [156 {157 "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",158 "account_number": "4277075694",159 "disbursement_dates": [160 "2002-08-28"161 ],162 "expected_payoff_date": "2032-07-28",163 "guarantor": "DEPT OF ED",164 "interest_rate_percentage": 5.25,165 "is_overdue": false,166 "last_payment_amount": 138.05,167 "last_payment_date": "2019-04-22",168 "last_statement_issue_date": "2019-04-28",169 "loan_name": "Consolidation",170 "loan_status": {171 "end_date": "2032-07-28",172 "type": "repayment"173 },174 "minimum_payment_amount": 25,175 "next_payment_due_date": "2019-05-28",176 "origination_date": "2002-08-28",177 "origination_principal_amount": 25000,178 "outstanding_interest_amount": 6227.36,179 "payment_reference_number": "4277075694",180 "pslf_status": {181 "estimated_eligibility_date": "2021-01-01",182 "payments_made": 200,183 "payments_remaining": 160184 },185 "repayment_plan": {186 "description": "Standard Repayment",187 "type": "standard"188 },189 "sequence_number": "1",190 "servicer_address": {191 "city": "San Matias",192 "country": "US",193 "postal_code": "99415",194 "region": "CA",195 "street": "123 Relaxation Road"196 },197 "ytd_interest_paid": 280.55,198 "ytd_principal_paid": 271.65199 }200 ]201 },202 "request_id": "dTnnm60WgKGLnKL"203}
Was this helpful?
Webhooks
Liabilities webhooks are sent to indicate that new loans or updated loan fields for existing accounts are available.
DEFAULT_UPDATE
The webhook of type LIABILITIES
and code DEFAULT_UPDATE
will be fired when new or updated liabilities have been detected on a liabilities item.
webhook_type string LIABILITIES | |||||||||
webhook_code string DEFAULT_UPDATE | |||||||||
item_id string The item_id of the Item associated with this webhook, warning, or error | |||||||||
error object 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.
| |||||||||
account_ids_with_new_liabilities [string] An array of account_id 's 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 fields that changed.Example: { "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": ["past_amount_due"] } |
1{2 "webhook_type": "LIABILITIES",3 "webhook_code": "DEFAULT_UPDATE",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "error": null,6 "account_ids_with_new_liabilities": [7 "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",8 "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"9 ],10 "account_ids_with_updated_liabilities": {11 "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": [12 "past_amount_due"13 ]14 }15}