Income

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.

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.

string

The user token associated with the User data is being requested for.

options

object

An optional object for /credit/bank_income/get request options.

count

integer

How many Bank Income Reports should be fetched. Multiple reports may be available if the report has been re-created or refreshed. If more than one report is available, the most recent reports will be returned first.

Default: 1

/credit/bank_income/get
Select Language
1const request: CreditBankIncomeGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  options: {
4    count: 1,
5  },
6};
7
8try {
9  const response = await client.creditBankIncomeGet(request);
10} catch (error) {
11  // handle error
12}

credit/bank_income/get

Response fields and example

bank_income

[object]

bank_income_id

string

The unique identifier associated with the Bank Income Report.

generated_time

string

The time when the Bank Income Report was generated.

Format: date-time

days_requested

integer

The number of days requested by the customer for the Bank Income Report.

items

[object]

The list of Items in the report along with the associated metadata about the Item.

bank_income_accounts

[object]

The Item's accounts that have Bank Income data.

string

Plaid's unique identifier for the account.

mask

nullablestring

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 bank account.

official_name

nullablestring

The official name of the bank account.

subtype

string

Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see Account schemas.

Possible values: checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, all

type

string

The account type. This will always be depository.

Possible values: depository

owners

[object]

Data returned by the financial institution about the account owner or owners. Identity information is optional, so field may return an empty array.

names

[string]

A list of names associated with the account by the financial institution. 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

string

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

nullablestring

The full city name

nullablestring

The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

string

The full street address Example: "564 Main Street, APT 15"

nullablestring

The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

nullablestring

The ISO 3166-1 alpha-2 country code

primary

boolean

When true, identifies the address as the primary address on an account.

bank_income_sources

[object]

The income sources for this Item. Each entry in the array is a single income source.

income_source_id

string

A unique identifier for an income source.

income_description

string

The most common name or original description for the underlying income transactions.

income_category

string

The income category. Note that the CASH value has been deprecated and is used only for existing legacy implementations. It has been replaced by the new categories CASH_DEPOSIT (representing cash or check deposits) and TRANSFER_FROM_APPLICATION (representing cash transfers originating from apps, such as Zelle or Venmo).

Possible values: SALARY, UNEMPLOYMENT, CASH, GIG_ECONOMY, RENTAL, CHILD_SUPPORT, MILITARY, RETIREMENT, LONG_TERM_DISABILITY, BANK_INTEREST, CASH_DEPOSIT, TRANSFER_FROM_APPLICATION, TAX_REFUND, BENEFIT_OTHER, OTHER

string

Plaid's unique identifier for the account.

string

Minimum of all dates within the specific income sources in the user's bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date

string

Maximum of all dates within the specific income sources in the user’s bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date

pay_frequency

string

The income pay frequency.

Possible values: WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, DAILY, UNKNOWN

number

Total amount of earnings in the user’s bank account for the specific income source for days requested by the client.

transaction_count

integer

Number of transactions for the income source within the start and end date.

historical_summary

[object]

deprecatednumber

Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.

deprecatednullablestring

The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.

deprecatednullablestring

The unofficial currency code associated with the amount or 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. Please use total_amounts instead.

total_amounts

[object]

Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.

number

Value of amount with up to 2 decimal places.

nullablestring

The ISO 4217 currency code of the amount or balance.

nullablestring

The unofficial currency code associated with the amount or 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.

string

The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date

string

The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date

transactions

[object]

number

The settled value of the transaction, denominated in the transactions'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, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.

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

name

string

The merchant name or transaction description.

original_description

nullablestring

The string returned by the financial institution to describe the transaction.

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.

check_number

nullablestring

The check number of the transaction. This field is only populated for check transactions.

nullablestring

The ISO 4217 currency code of the amount or balance.

nullablestring

The unofficial currency code associated with the amount or 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_time

string

The time when this Item's data was last retrieved from the financial institution.

Format: date-time

institution_id

string

The unique identifier of the institution associated with the Item.

institution_name

string

The name of the institution associated with the Item.

string

The unique identifier for the Item.

bank_income_summary

object

Summary for bank income across all income sources and items (max history of 730 days).

deprecatednumber

Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.

deprecatednullablestring

The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.

deprecatednullablestring

The unofficial currency code associated with the amount or 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. Please use total_amounts instead.

total_amounts

[object]

Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This can contain multiple amounts, with each amount denominated in one unique currency.

number

Value of amount with up to 2 decimal places.

nullablestring

The ISO 4217 currency code of the amount or balance.

nullablestring

The unofficial currency code associated with the amount or 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.

string

The earliest date within the days requested in which all income sources identified by Plaid appear in a user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date

income_categories_count

string

The latest date in which all income sources identified by Plaid appear in the user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date

income_sources_count

integer

Number of income sources per end user.

integer

Number of income categories per end user.

income_transactions_count

integer

Number of income transactions per end user.

historical_summary

[object]

deprecatednumber

Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.

deprecatednullablestring

The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.

deprecatednullablestring

The unofficial currency code associated with the amount or 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. Please use total_amounts instead.

total_amounts

[object]

Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.

number

Value of amount with up to 2 decimal places.

nullablestring

The ISO 4217 currency code of the amount or balance.

nullablestring

The unofficial currency code associated with the amount or 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.

string

The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date

string

The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date

transactions

[object]

number

The settled value of the transaction, denominated in the transactions'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, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.

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

name

string

The merchant name or transaction description.

original_description

nullablestring

The string returned by the financial institution to describe the transaction.

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.

check_number

nullablestring

The check number of the transaction. This field is only populated for check transactions.

nullablestring

The ISO 4217 currency code of the amount or balance.

nullablestring

The unofficial currency code associated with the amount or 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.

warnings

[object]

If data from the Bank Income report was unable to be retrieved, the warnings will contain information about the error that caused the data to be incomplete.

warning_type

string

The warning type which will always be BANK_INCOME_WARNING.

Possible values: BANK_INCOME_WARNING

warning_code

string

The warning code identifies a specific kind of warning. IDENTITY_UNAVAILABLE: Unable to extract identity for the Item TRANSACTIONS_UNAVAILABLE: Unable to extract transactions for the Item ITEM_UNAPPROVED: User exited flow before giving permission to share data for the Item REPORT_DELETED: Report deleted due to customer or consumer request DATA_UNAVAILABLE: No relevant data was found for the Item

Possible values: IDENTITY_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE, ITEM_UNAPPROVED, REPORT_DELETED, DATA_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.

error_type

string

A broad categorization of the error. Safe for programmatic use.

Possible values: INTERNAL_SERVER_ERROR, INSUFFICIENT_CREDENTIALS, ITEM_LOCKED, USER_SETUP_REQUIRED, COUNTRY_NOT_SUPPORTED, INSTITUTION_DOWN, INSTITUTION_NO_LONGER_SUPPORTED, INSTITUTION_NOT_RESPONDING, INVALID_CREDENTIALS, INVALID_MFA, INVALID_SEND_METHOD, ITEM_LOGIN_REQUIRED, MFA_NOT_SUPPORTED, NO_ACCOUNTS, ITEM_NOT_SUPPORTED, ACCESS_NOT_GRANTED

error_code

string

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_message

string

A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

display_message

string

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.

string

The item_id of the Item associated with this warning.

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Object
1{
"request_id": "LhQf0THi8SH1yJm",
"bank_income": [
  {
    "bank_income_id": "abc123",
    "generated_time": "2022-01-31T22:47:53Z",
    "days_requested": 90,
    "items": [
      {
        "last_updated_time": "2022-01-31T22:47:53Z",
        "institution_id": "ins_0",
        "institution_name": "Plaid Bank",
        "item_id": "“eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6”",
        "bank_income_accounts": [
          {
            "account_id": "“GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9”",
            "mask": "8888",
            "name": "Plaid Checking Account",
            "official_name": "Plaid Checking Account",
            "type": "depository",
            "subtype": "checking",
            "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"
                  }
                ]
              }
            ]
          }
        ],
        "bank_income_sources": [
          {
            "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
            "income_source_id": "“f17efbdd-caab-4278-8ece-963511cd3d51”",
            "income_description": "“PLAID_INC_DIRECT_DEP_PPD”",
            "income_category": "SALARY",
            "start_date": "2021-11-15",
            "end_date": "2022-01-15",
            "pay_frequency": "MONTHLY",
            "total_amount": 300,
            "transaction_count": 1,
            "historical_summary": [
              {
                "start_date": "2021-11-02",
                "end_date": "2021-11-30",
                "total_amount": 100,
                "iso_currency_code": "USD",
                "unofficial_currency_code": null,
                "total_amounts": [
                  {
                    "amount": 100,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ],
                "transactions": [
                  {
                    "amount": -100,
                    "date": "2021-11-15",
                    "name": "“PLAID_INC_DIRECT_DEP_PPD”",
                    "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
                    "pending": false,
                    "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",
                    "check_number": null,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ]
              },
              {
                "start_date": "2021-12-01",
                "end_date": "2021-12-31",
                "total_amount": 100,
                "iso_currency_code": "USD",
                "unofficial_currency_code": null,
                "total_amounts": [
                  {
                    "amount": 100,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ],
                "transactions": [
                  {
                    "amount": -100,
                    "date": "2021-12-15",
                    "name": "“PLAID_INC_DIRECT_DEP_PPD”",
                    "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
                    "pending": false,
                    "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",
                    "check_number": null,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ]
              },
              {
                "start_date": "2022-01-01",
                "end_date": "2021-01-31",
                "total_amount": 100,
                "iso_currency_code": "USD",
                "unofficial_currency_code": null,
                "total_amounts": [
                  {
                    "amount": 100,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ],
                "transactions": [
                  {
                    "amount": -100,
                    "date": "2022-01-31",
                    "name": "“PLAID_INC_DIRECT_DEP_PPD”",
                    "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
                    "pending": false,
                    "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",
                    "check_number": null,
                    "iso_currency_code": "USD",
                    "unofficial_currency_code": null
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "bank_income_summary": {
      "total_amount": 300,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "total_amounts": [
        {
          "amount": 300,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null
        }
      ],
      "start_date": "2021-11-15",
      "end_date": "2022-01-15",
      "income_sources_count": 1,
      "income_categories_count": 1,
      "income_transactions_count": 1,
      "historical_summary": [
        {
          "start_date": "2021-11-02",
          "end_date": "2021-11-30",
          "total_amount": 100,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null,
          "total_amounts": [
            {
              "amount": 100,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ],
          "transactions": [
            {
              "amount": -100,
              "date": "2021-11-15",
              "name": "“PLAID_INC_DIRECT_DEP_PPD”",
              "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
              "pending": false,
              "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",
              "check_number": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ]
        },
        {
          "start_date": "2021-12-01",
          "end_date": "2021-12-31",
          "total_amount": 100,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null,
          "total_amounts": [
            {
              "amount": 100,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ],
          "transactions": [
            {
              "amount": -100,
              "date": "2021-12-15",
              "name": "“PLAID_INC_DIRECT_DEP_PPD”",
              "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
              "pending": false,
              "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",
              "check_number": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ]
        },
        {
          "start_date": "2022-01-01",
          "end_date": "2021-01-31",
          "total_amount": 100,
          "iso_currency_code": "USD",
          "unofficial_currency_code": null,
          "total_amounts": [
            {
              "amount": 100,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ],
          "transactions": [
            {
              "amount": -100,
              "date": "2022-01-31",
              "name": "“PLAID_INC_DIRECT_DEP_PPD”",
              "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
              "pending": false,
              "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",
              "check_number": null,
              "iso_currency_code": "USD",
              "unofficial_currency_code": null
            }
          ]
        }
      ]
    },
    "warnings": []
  }
]
288}

Was this helpful?

Retrieve information from the bank accounts used for income verification in PDF format

/credit/bank_income/pdf/get returns the most recent bank income report for a specified user in PDF format.

credit/bank_income/pdf/get

Request fields and example

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.

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.

requiredstring

The user token associated with the User data is being requested for.

/credit/bank_income/pdf/get
Select Language
1const request: CreditBankIncomePDFGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditBankIncomePdfGet(request, {
7    responseType: 'arraybuffer',
8  });
9  const pdf = response.buffer.toString('base64');
10} catch (error) {
11  // handle error
12}

Refresh a user's bank income information

/credit/bank_income/refresh refreshes the bank income report data for a specific user.

credit/bank_income/refresh

Request fields and example

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.

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.

requiredstring

The user token associated with the User data is being requested for.

options

object

An optional object for /credit/bank_income/refresh request options.

days_requested

integer

How many days of data to include in the refresh. If not specified, this will default to the days requested in the most recently generated bank income report for the user.

/credit/bank_income/refresh
Select Language
1const request: CreditBankIncomeRefreshRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  options: {
4    days_requested: 90,
5  },
6};
7
8try {
9  const response = await client.creditBankIncomeRefresh(request);
10} catch (error) {
11  // handle error
12}

credit/bank_income/refresh

Response fields and example

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Object
1{
2  "request_id": "LhQf0THi8SH1yJm"
3}

Was this helpful?

Subscribe and unsubscribe to proactive notifications for a user's income profile

/credit/bank_income/webhook/update allows you to subscribe or unsubscribe a user for income webhook notifications.
If a user is subscribed, on significant changes to the user's income profile, you will receive a BANK_INCOME_REFRESH_UPDATE webhook, prompting you to refresh bank income data for the user.

credit/bank_income/webhook/update

Request fields and example

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.

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.

requiredstring

The user token associated with the User data is being requested for.

enable_webhooks

requiredboolean

Whether the user should be enabled for proactive webhook notifications when their income changes

/credit/bank_income/webhook/update
Select Language
1const request: CreditBankIncomeWebhookUpdateRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  enable_webhooks: true,
4};
5
6try {
7  const response = await client.creditBankIncomeWebhookUpdateRequest(request);
8} catch (error) {
9  // handle error
10}

credit/bank_income/webhook/update

Response fields and example

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Object
1{
2  "request_id": "LhQf0THi8SH1yJm"
3}

Was this helpful?

Retrieve data for a user's uploaded bank statements

/credit/bank_statements/uploads/get returns data from user-uploaded bank statements.

credit/bank_statements/uploads/get

Request fields and example

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.

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.

requiredstring

The user token associated with the User data is being requested for.

/credit/bank_statements/uploads/get
Select Language
1const request: CreditBankStatementsUploadsGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditBankStatementsUploadsGet(request);
7} catch (error) {
8  // handle error
9}

credit/bank_statements/uploads/get

Response fields and example

items

[object]

Array of bank statement upload items.

string

The item_id of the Item associated with this webhook, warning, or error

bank_statements

[object]

transactions

[object]

An array of transactions appearing on the bank statement.

nullablenumber

The value of the transaction. A negative amount indicates that money moved into the account (such as a paycheck being deposited).

date

nullablestring

The date of when the transaction was made, in ISO 8601 format (YYYY-MM-DD).

Format: date

original_description

nullablestring

The raw description of the transaction as it appears on the bank statement.

nullablestring

The unique id of the bank account that this transaction occurs in

object

Object representing metadata pertaining to the document.

name

string

The name of the document.

nullablestring

The type of document.
PAYSTUB: A paystub.
BANK_STATEMENT: A bank statement.
US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE

nullablestring

Signed URL to retrieve the underlying file. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.

nullablestring

The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.

Possible values: UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, null

nullableinteger

The number of pages of the uploaded document (if available).

nullablestring

An identifier of the document referenced by the document metadata.

bank_accounts

[object]

An array of bank accounts associated with the uploaded bank statement.

name

nullablestring

The name of the bank account

bank_name

nullablestring

The name of the bank institution.

account_type

nullablestring

The type of the bank account.

account_number

nullablestring

The bank account number.

owner

object

An object containing data about the owner of the bank account for the uploaded bank statement.

name

nullablestring

The name of the account owner

object

Address on the uploaded bank statement

city

nullablestring

The full city name.

nullablestring

The ISO 3166-1 alpha-2 country code.

nullablestring

The postal code of the address.

nullablestring

The region or state. Example: "NC"

nullablestring

The full street address.

periods

[object]

An array of period objects, containing more data on the overall period of the statement.

nullablestring

The start date of the statement period in ISO 8601 format (YYYY-MM-DD).

Format: date

nullablestring

The end date of the statement period in ISO 8601 format (YYYY-MM-DD).

Format: date

starting_balance

nullablenumber

The starting balance of the bank account for the period.

ending_balance

nullablenumber

The ending balance of the bank account for the period.

nullablestring

The unique id of the bank account

nullableobject

Details about the status of the payroll item.

processing_status

nullablestring

Denotes the processing status for the verification.
UNKNOWN: The processing status could not be determined.
PROCESSING_COMPLETE: The processing has completed and the user has approved for sharing. The data is available to be retrieved.
PROCESSING: The verification is still processing. The data is not available yet.
FAILED: The processing failed to complete successfully.
APPROVAL_STATUS_PENDING: The processing has completed but the user has not yet approved the sharing of the data.

Possible values: UNKNOWN, PROCESSING_COMPLETE, PROCESSING, FAILED, APPROVAL_STATUS_PENDING

updated_at

nullablestring

Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated.

Format: date-time

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Object
1{
"items": [
  {
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "bank_statements": [
      {
        "transactions": [
          {
            "amount": -1000,
            "date": "2023-01-01",
            "original_description": "PAYCHECK",
            "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d"
          }
        ],
        "document_metadata": {
          "document_type": "BANK_STATEMENT",
          "name": "statement_01.pdf",
          "status": "PROCESSING_COMPLETE",
          "download_url": null,
          "page_count": 2
        },
        "document_id": "2jkflanbd",
        "bank_accounts": [
          {
            "name": "CHASE CHECKING",
            "bank_name": "CHASE",
            "account_type": "CHECKING",
            "account_number": "000009752",
            "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d",
            "owner": {
              "name": "JANE DOE",
              "address": {
                "postal_code": "94133",
                "country": "US",
                "region": "CA",
                "city": "SAN FRANCISCO",
                "street": "2140 TAYLOR ST"
              }
            },
            "periods": [
              {
                "start_date": "2023-01-01",
                "end_date": "2023-02-01",
                "starting_balance": 2500,
                "ending_balance": 3500
              }
            ]
          }
        ]
      }
    ],
    "status": {
      "processing_status": "PROCESSING_COMPLETE"
    },
    "updated_at": "2023-02-01T21:14:54Z"
  }
],
"request_id": "LhQf0THi8SH1yJm"
59}

Was this helpful?

Retrieve a user's payroll information

This endpoint gets payroll income information for a specific user, either as a result of the user connecting to their payroll provider or uploading a pay related document.

credit/payroll_income/get

Request fields and example

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.

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.

string

The user token associated with the User data is being requested for.

/credit/payroll_income/get
Select Language
1const request: CreditPayrollIncomeGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditPayrollIncomeGet(request);
7} catch (error) {
8  // handle error
9}

credit/payroll_income/get

Response fields and example

items

[object]

Array of payroll items.

string

The item_id of the Item associated with this webhook, warning, or error

institution_id

string

The unique identifier of the institution associated with the Item.

institution_name

string

The name of the institution associated with the Item.

accounts

[object]

nullablestring

ID of the payroll provider account.

rate_of_pay

object

An object representing the rate at which an individual is paid.

pay_rate

nullablestring

The rate at which an employee is paid.

Possible values: ANNUAL, HOURLY, CONTRACT, WEEKLY, BI_WEEKLY, MONTHLY, SEMI_MONTHLY, DAILY, COMMISSION, OTHER, null

pay_amount

nullablenumber

The amount at which an employee is paid.

Format: double

pay_frequency

nullablestring

The frequency at which an individual is paid.

Possible values: DAILY, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, CONTRACT, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, OTHER, null

payroll_income

[object]

nullablestring

ID of the payroll provider account.

pay_stubs

[object]

Array of pay stubs for the user.

deductions

object

An object with the deduction information found on a pay stub.

breakdown

[object]

nullablenumber

Raw amount of the deduction

Format: double

description

nullablestring

Description of the deduction line item

nullablestring

The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.

nullablestring

The unofficial currency code associated with the line item. 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.

nullablenumber

The year-to-date amount of the deduction

Format: double

total

object

An object representing the total deductions for the pay period

nullablenumber

Raw amount of the deduction

Format: double

nullablestring

The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.

nullablestring

The unofficial currency code associated with the line item. 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.

nullablenumber

The year-to-date total amount of the deductions

Format: double

nullablestring

An identifier of the document referenced by the document metadata.

object

Object representing metadata pertaining to the document.

name

string

The name of the document.

nullablestring

The type of document.
PAYSTUB: A paystub.
BANK_STATEMENT: A bank statement.
US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE

nullablestring

Signed URL to retrieve the underlying file. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.

nullablestring

The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.

Possible values: UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, null

nullableinteger

The number of pages of the uploaded document (if available).

earnings

object

An object representing both a breakdown of earnings on a pay stub and the total earnings.

breakdown

[object]

canonical_description

nullablestring

Commonly used term to describe the earning line item.

Possible values: BONUS, COMMISSION, OVERTIME, PAID_TIME_OFF, REGULAR_PAY, VACATION, BASIC_ALLOWANCE_HOUSING, BASIC_ALLOWANCE_SUBSISTENCE, OTHER, ALLOWANCE, BEREAVEMENT, HOLIDAY_PAY, JURY_DUTY, LEAVE, LONG_TERM_DISABILITY_PAY, MILITARY_PAY, PER_DIEM, REFERRAL_BONUS, REIMBURSEMENTS, RETENTION_BONUS, RETROACTIVE_PAY, SEVERANCE_PAY, SHIFT_DIFFERENTIAL, SHORT_TERM_DISABILITY_PAY, SICK_PAY, SIGNING_BONUS, TIPS_INCOME, null

nullablenumber

Raw amount of the earning line item.

Format: double

description

nullablestring

Description of the earning line item.

hours

nullablenumber

Number of hours applicable for this earning.

nullablestring

The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.

rate

nullablenumber

Hourly rate applicable for this earning.

Format: double

nullablestring

The unofficial currency code associated with the line item. 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.

nullablenumber

The year-to-date amount of the deduction.

Format: double

total

object

An object representing both the current pay period and year to date amount for an earning category.

nullablenumber

Total amount of the earnings for this pay period.

Format: double

hours

nullablenumber

Total number of hours worked for this pay period.

nullablestring

The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.

nullablestring

The unofficial currency code associated with the security. 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.

nullablenumber

The total year-to-date amount of the earnings.

Format: double

employee

object

Data about the employee.

object

Address on the pay stub.

city

nullablestring

The full city name.

nullablestring

The ISO 3166-1 alpha-2 country code.

nullablestring

The postal code of the address.

nullablestring

The region or state. Example: "NC"

nullablestring

The full street address.

name

nullablestring

The name of the employee.

marital_status

nullablestring

Marital status of the employee - either SINGLE or MARRIED or NOT LISTED.

Possible values: SINGLE, MARRIED, NOT LISTED, null

taxpayer_id

object

Taxpayer ID of the individual receiving the paystub.

id_type

nullablestring

Type of ID, e.g. 'SSN'.

id_mask

nullablestring

ID mask; i.e. last 4 digits of the taxpayer ID.

employer

object

Information about the employer on the pay stub.

object

Address on the pay stub.

city

nullablestring

The full city name.

nullablestring

The ISO 3166-1 alpha-2 country code.

nullablestring

The postal code of the address.

nullablestring

The region or state. Example: "NC"

nullablestring

The full street address.

name

nullablestring

The name of the employer on the pay stub.

net_pay

object

An object representing information about the net pay amount on the pay stub.

nullablenumber

Raw amount of the net pay for the pay period.

Format: double

description

nullablestring

Description of the net pay.

nullablestring

The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.

nullablestring

The unofficial currency code associated with the net pay. 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.

nullablenumber

The year-to-date amount of the net pay.

Format: double

pay_period_details

object

Details about the pay period.

pay_amount

nullablenumber

The amount of the paycheck.

Format: double

distribution_breakdown

[object]

account_name

nullablestring

Name of the account for the given distribution.

bank_name

nullablestring

The name of the bank that the payment is being deposited to.

nullablenumber

The amount distributed to this account.

Format: double

nullablestring

The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.

mask

nullablestring

The last 2-4 alphanumeric characters of an account's official account number.

type

nullablestring

Type of the account that the paystub was sent to (e.g. 'checking').

nullablestring

The unofficial currency code associated with the net pay. 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.

nullablestring

The date on which the pay period ended, in ISO 8601 format ("yyyy-mm-dd").

Format: date

gross_earnings

nullablenumber

Total earnings before tax/deductions.

Format: double

nullablestring

The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.

pay_date

nullablestring

The date on which the pay stub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date

pay_frequency

nullablestring

The frequency at which an individual is paid.

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, null

pay_basis

string

The explicit pay basis on the paystub (if present).

Possible values: SALARY, HOURLY, COMMISSION

nullablestring

The date on which the pay period started, in ISO 8601 format ("yyyy-mm-dd").

Format: date

nullablestring

The unofficial currency code associated with the net pay. 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.

w2s

[object]

Array of tax form W-2s.

object

Object representing metadata pertaining to the document.

name

string

The name of the document.

nullablestring

The type of document.
PAYSTUB: A paystub.
BANK_STATEMENT: A bank statement.
US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE

nullablestring

Signed URL to retrieve the underlying file. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.

nullablestring

The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.

Possible values: UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, null

nullableinteger

The number of pages of the uploaded document (if available).

string

An identifier of the document referenced by the document metadata.

employer

object

Information about the employer on the pay stub.

object

Address on the pay stub.

city

nullablestring

The full city name.

nullablestring

The ISO 3166-1 alpha-2 country code.

nullablestring

The postal code of the address.

nullablestring

The region or state. Example: "NC"

nullablestring

The full street address.

name

nullablestring

The name of the employer on the pay stub.

employee

object

Data about the employee.

object

Address on the pay stub.

city

nullablestring

The full city name.

nullablestring

The ISO 3166-1 alpha-2 country code.

nullablestring

The postal code of the address.

nullablestring

The region or state. Example: "NC"

federal_income_tax_withheld

nullablestring

The full street address.

name

nullablestring

The name of the employee.

marital_status

nullablestring

Marital status of the employee - either SINGLE or MARRIED or NOT LISTED.

Possible values: SINGLE, MARRIED, NOT LISTED, null

taxpayer_id

object

Taxpayer ID of the individual receiving the paystub.

id_type

nullablestring

Type of ID, e.g. 'SSN'.

id_mask

nullablestring

ID mask; i.e. last 4 digits of the taxpayer ID.

tax_year

nullablestring

The tax year of the W2 document.

employer_id_number

nullablestring

An employee identification number or EIN.

wages_tips_other_comp

nullablestring

Wages from tips and other compensation.

nullablestring

Federal income tax withheld for the tax year.

social_security_wages

nullablestring

Wages from social security.

social_security_tax_withheld

nullablestring

Social security tax withheld for the tax year.

medicare_wages_and_tips

nullablestring

Wages and tips from medicare.

medicare_tax_withheld

nullablestring

Medicare tax withheld for the tax year.

social_security_tips

nullablestring

Tips from social security.

allocated_tips

nullablestring

Allocated tips.

box_9

nullablestring

Contents from box 9 on the W2.

dependent_care_benefits

nullablestring

Dependent care benefits.

nonqualified_plans

nullablestring

Nonqualified plans.

box_12

[object]

code

nullablestring

W2 Box 12 code.

employer_state_id_number

nullablestring

W2 Box 12 amount.

statutory_employee

nullablestring

Statutory employee.

retirement_plan

nullablestring

Retirement plan.

third_party_sick_pay

nullablestring

Third party sick pay.

other

nullablestring

Other.

state_and_local_wages

[object]

state

nullablestring

State associated with the wage.

nullablestring

State identification number of the employer.

state_wages_tips

nullablestring

Wages and tips from the specified state.

state_income_tax

nullablestring

Income tax from the specified state.

local_wages_tips

nullablestring

Wages and tips from the locality.

local_income_tax

nullablestring

Income tax from the locality.

locality_name

nullablestring

Name of the locality.

form1099s

[object]

Array of tax form 1099s.

nullablestring

An identifier of the document referenced by the document metadata.

object

Object representing metadata pertaining to the document.

name

string

The name of the document.

nullablestring

The type of document.
PAYSTUB: A paystub.
BANK_STATEMENT: A bank statement.
US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE

nullablestring

Signed URL to retrieve the underlying file. This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.

nullablestring

The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.

Possible values: UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, null

nullableinteger

The number of pages of the uploaded document (if available).

form_1099_type

string

Form 1099 Type

Possible values: FORM_1099_TYPE_UNKNOWN, FORM_1099_TYPE_MISC, FORM_1099_TYPE_K

recipient

object

An object representing a recipient used in both 1099-K and 1099-MISC tax documents.

object

Address on the pay stub.

city

nullablestring

The full city name.

nullablestring

The ISO 3166-1 alpha-2 country code.

nullablestring

The postal code of the address.

nullablestring

The region or state. Example: "NC"

facta_filing_requirement

nullablestring

The full street address.

name

nullablestring

Name of recipient.

tin

nullablestring

Tax identification number of recipient.

account_number

nullablestring

Account number number of recipient.

nullablestring

Checked if FACTA is a filing requirement.

Possible values: CHECKED, NOT CHECKED

second_tin_exists

nullablestring

Checked if 2nd TIN exists.

Possible values: CHECKED, NOT CHECKED

payer

object

An object representing a payer used by 1099-MISC tax documents.

object

Address on the pay stub.

city

nullablestring

The full city name.

nullablestring

The ISO 3166-1 alpha-2 country code.

nullablestring

The postal code of the address.

nullablestring

The region or state. Example: "NC"

nullablestring

The full street address.

name

nullablestring

Name of payer.

tin

nullablestring

Tax identification number of payer.

telephone_number

nullablestring

Telephone number of payer.

filer

object

An object representing a filer used by 1099-K tax documents.

object

Address on the pay stub.

city

nullablestring

The full city name.

nullablestring

The ISO 3166-1 alpha-2 country code.

nullablestring

The postal code of the address.

nullablestring

The region or state. Example: "NC"

federal_income_tax_withheld

nullablestring

The full street address.

name

nullablestring

Name of filer.

tin

nullablestring

Tax identification number of filer.

type

nullablestring

One of the following values will be provided: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party

Possible values: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party

tax_year

nullablestring

Tax year of the tax form.

rents

nullablenumber

Amount in rent by payer.

Format: double

royalties

nullablenumber

Amount in royalties by payer.

Format: double

other_income

nullablenumber

Amount in other income by payer.

Format: double

nullablenumber

Amount of federal income tax withheld from payer.

Format: double

fishing_boat_proceeds

nullablenumber

Amount of fishing boat proceeds from payer.

Format: double

medical_and_healthcare_payments

nullablenumber

Amount of medical and healthcare payments from payer.

Format: double

nonemployee_compensation

nullablenumber

Amount of nonemployee compensation from payer.

Format: double

substitute_payments_in_lieu_of_dividends_or_interest

nullablenumber

Amount of substitute payments made by payer.

Format: double

payer_made_direct_sales_of_5000_or_more_of_consumer_products_to_buyer

nullablestring

Whether or not payer made direct sales over $5000 of consumer products.

crop_insurance_proceeds

nullablenumber

Amount of crop insurance proceeds.

Format: double

excess_golden_parachute_payments

nullablenumber

Amount of golden parachute payments made by payer.

Format: double

gross_proceeds_paid_to_an_attorney

nullablenumber

Amount of gross proceeds paid to an attorney by payer.

Format: double

section_409a_deferrals

nullablenumber

Amount of 409A deferrals earned by payer.

Format: double

section_409a_income

nullablenumber

Amount of 409A income earned by payer.

Format: double

state_tax_withheld

nullablenumber

Amount of state tax withheld of payer for primary state.

Format: double

state_tax_withheld_lower

nullablenumber

Amount of state tax withheld of payer for secondary state.

Format: double

payer_state_number

nullablestring

Primary state ID.

payer_state_number_lower

nullablestring

Secondary state ID.

state_income

nullablenumber

State income reported for primary state.

Format: double

state_income_lower

nullablenumber

State income reported for secondary state.

Format: double

transactions_reported

nullablestring

One of the values will be provided Payment card Third party network

Possible values: Payment card, Third party network

pse_name

nullablestring

Name of the PSE (Payment Settlement Entity).

pse_telephone_number

nullablestring

Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity).

gross_amount

nullablenumber

Gross amount reported.

Format: double

card_not_present_transaction

nullablenumber

Amount in card not present transactions.

Format: double

merchant_category_code

nullablestring

Merchant category of filer.

number_of_payment_transactions

nullablestring

Number of payment transactions made.

january_amount

nullablenumber

Amount reported for January.

Format: double

february_amount

nullablenumber

Amount reported for February.

Format: double

march_amount

nullablenumber

Amount reported for March.

Format: double

april_amount

nullablenumber

Amount reported for April.

Format: double

may_amount

nullablenumber

Amount reported for May.

Format: double

june_amount

nullablenumber

Amount reported for June.

Format: double

july_amount

nullablenumber

Amount reported for July.

Format: double

august_amount

nullablenumber

Amount reported for August.

Format: double

september_amount

nullablenumber

Amount reported for September.

Format: double

october_amount

nullablenumber

Amount reported for October.

Format: double

november_amount

nullablenumber

Amount reported for November.

Format: double

december_amount

nullablenumber

Amount reported for December.

Format: double

primary_state

nullablestring

Primary state of business.

secondary_state

nullablestring

Secondary state of business.

primary_state_id

nullablestring

Primary state ID.

secondary_state_id

nullablestring

Secondary state ID.

primary_state_income_tax

nullablenumber

State income tax reported for primary state.

Format: double

secondary_state_income_tax

nullablenumber

State income tax reported for secondary state.

Format: double

nullableobject

Details about the status of the payroll item.

processing_status

nullablestring

Denotes the processing status for the verification.
UNKNOWN: The processing status could not be determined.
PROCESSING_COMPLETE: The processing has completed and the user has approved for sharing. The data is available to be retrieved.
PROCESSING: The verification is still processing. The data is not available yet.
FAILED: The processing failed to complete successfully.
APPROVAL_STATUS_PENDING: The processing has completed but the user has not yet approved the sharing of the data.

Possible values: UNKNOWN, PROCESSING_COMPLETE, PROCESSING, FAILED, APPROVAL_STATUS_PENDING

updated_at

nullablestring

Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated.

Format: date-time

error

nullableobject

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. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.

error_type

string

A broad categorization of the error. Safe for programmatic 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, MICRODEPOSITS_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

nullablestring

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.

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. causes will also not be populated inside an error nested within a warning object.

nullableinteger

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

nullablestring

Suggested steps for resolving the error

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Object
1{
"items": [
  {
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "institution_id": "ins_92",
    "institution_name": "ADP",
    "accounts": [
      {
        "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
        "rate_of_pay": {
          "pay_amount": 100000,
          "pay_rate": "ANNUAL"
        },
        "pay_frequency": "BIWEEKLY"
      }
    ],
    "payroll_income": [
      {
        "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
        "pay_stubs": [
          {
            "deductions": {
              "breakdown": [
                {
                  "current_amount": 123.45,
                  "description": "taxes",
                  "iso_currency_code": "USD",
                  "unofficial_currency_code": null,
                  "ytd_amount": 246.9
                }
              ],
              "total": {
                "current_amount": 123.45,
                "iso_currency_code": "USD",
                "unofficial_currency_code": null,
                "ytd_amount": 246.9
              }
            },
            "document_metadata": {
              "document_type": "PAYSTUB",
              "name": "paystub.pdf",
              "status": "PROCESSING_COMPLETE",
              "download_url": null
            },
            "document_id": "2jkflanbd",
            "earnings": {
              "breakdown": [
                {
                  "canonical_description": "REGULAR_PAY",
                  "current_amount": 200.22,
                  "description": "salary earned",
                  "hours": 80,
                  "iso_currency_code": "USD",
                  "rate": null,
                  "unofficial_currency_code": null,
                  "ytd_amount": 400.44
                },
                {
                  "canonical_description": "BONUS",
                  "current_amount": 100,
                  "description": "bonus earned",
                  "hours": null,
                  "iso_currency_code": "USD",
                  "rate": null,
                  "unofficial_currency_code": null,
                  "ytd_amount": 100
                }
              ],
              "total": {
                "current_amount": 300.22,
                "hours": 160,
                "iso_currency_code": "USD",
                "unofficial_currency_code": null,
                "ytd_amount": 500.44
              }
            },
            "employee": {
              "address": {
                "city": "SAN FRANCISCO",
                "country": "US",
                "postal_code": "94133",
                "region": "CA",
                "street": "2140 TAYLOR ST"
              },
              "name": "ANNA CHARLESTON",
              "marital_status": "SINGLE",
              "taxpayer_id": {
                "id_type": "SSN",
                "id_mask": "3333"
              }
            },
            "employer": {
              "name": "PLAID INC",
              "address": {
                "city": "SAN FRANCISCO",
                "country": "US",
                "postal_code": "94111",
                "region": "CA",
                "street": "1098 HARRISON ST"
              }
            },
            "net_pay": {
              "current_amount": 123.34,
              "description": "TOTAL NET PAY",
              "iso_currency_code": "USD",
              "unofficial_currency_code": null,
              "ytd_amount": 253.54
            },
            "pay_period_details": {
              "distribution_breakdown": [
                {
                  "account_name": "Big time checking",
                  "bank_name": "bank of plaid",
                  "current_amount": 176.77,
                  "iso_currency_code": "USD",
                  "mask": "1223",
                  "type": "checking",
                  "unofficial_currency_code": null
                }
              ],
              "end_date": "2020-12-15",
              "gross_earnings": 4500,
              "iso_currency_code": "USD",
              "pay_amount": 1490.21,
              "pay_date": "2020-12-15",
              "pay_frequency": "BIWEEKLY",
              "start_date": "2020-12-01",
              "unofficial_currency_code": null
            }
          }
        ],
        "w2s": [
          {
            "allocated_tips": "1000",
            "box_12": [
              {
                "amount": "200",
                "code": "AA"
              }
            ],
            "box_9": "box9",
            "dependent_care_benefits": "1000",
            "document_metadata": {
              "document_type": "US_TAX_W2",
              "download_url": null,
              "name": "w_2.pdf",
              "status": "PROCESSING_COMPLETE"
            },
            "document_id": "1pkflebk4",
            "employee": {
              "address": {
                "city": "San Francisco",
                "country": "US",
                "postal_code": "94103",
                "region": "CA",
                "street": "1234 Grand St"
              },
              "name": "Josie Georgia Harrison",
              "marital_status": "SINGLE",
              "taxpayer_id": {
                "id_type": "SSN",
                "id_mask": "1234"
              }
            },
            "employer": {
              "address": {
                "city": "New York",
                "country": "US",
                "postal_code": "10010",
                "region": "NY",
                "street": "456 Main St"
              },
              "name": "Acme Inc"
            },
            "employer_id_number": "12-1234567",
            "federal_income_tax_withheld": "1000",
            "medicare_tax_withheld": "1000",
            "medicare_wages_and_tips": "1000",
            "nonqualified_plans": "1000",
            "other": "other",
            "retirement_plan": "CHECKED",
            "social_security_tax_withheld": "1000",
            "social_security_tips": "1000",
            "social_security_wages": "1000",
            "state_and_local_wages": [
              {
                "employer_state_id_number": "11111111111AAA",
                "local_income_tax": "200",
                "local_wages_and_tips": "200",
                "locality_name": "local",
                "state": "UT",
                "state_income_tax": "200",
                "state_wages_tips": "200"
              }
            ],
            "statutory_employee": "CHECKED",
            "tax_year": "2020",
            "third_party_sick_pay": "CHECKED",
            "wages_tips_other_comp": "1000"
          }
        ],
        "form1099s": [
          {
            "april_amount": null,
            "august_amount": null,
            "card_not_present_transaction": null,
            "crop_insurance_proceeds": 1000,
            "december_amount": null,
            "document_id": "mvMZ59Z2a5",
            "document_metadata": {
              "document_type": "US_TAX_1099_MISC",
              "download_url": null,
              "name": "form_1099_misc.pdf",
              "status": "PROCESSING_COMPLETE"
            },
            "excess_golden_parachute_payments": 1000,
            "feburary_amount": null,
            "federal_income_tax_withheld": 1000,
            "filer": {
              "address": {
                "city": null,
                "country": null,
                "postal_code": null,
                "region": null,
                "street": null
              },
              "name": null,
              "tin": null,
              "type": null
            },
            "fishing_boat_proceeds": 1000,
            "form_1099_type": "FORM_1099_TYPE_MISC",
            "gross_amount": 1000,
            "gross_proceeds_paid_to_an_attorney": 1000,
            "january_amount": null,
            "july_amount": null,
            "june_amount": null,
            "march_amount": null,
            "may_amount": null,
            "medical_and_healthcare_payments": 1000,
            "merchant_category_code": null,
            "nonemployee_compensation": 1000,
            "november_amount": null,
            "number_of_payment_transactions": null,
            "october_amount": null,
            "other_income": 1000,
            "payer": {
              "address": {
                "city": "SAN FRANCISCO",
                "country": "US",
                "postal_code": "94111",
                "region": "CA",
                "street": "1098 HARRISON ST"
              },
              "name": "PLAID INC",
              "telephone_number": "(123)456-7890",
              "tin": "12-3456789"
            },
            "payer_made_direct_sales_of_500_or_more_of_consumer_products_to_buyer": null,
            "payer_state_number": "CA 12345",
            "payer_state_number_lower": null,
            "primary_state": null,
            "primary_state_id": "CA 12345",
            "primary_state_income_tax": 1000,
            "pse_name": null,
            "pse_telephone_number": null,
            "recipient": {
              "account_number": "45678",
              "address": {
                "city": "SAN FRANCISCO",
                "country": "US",
                "postal_code": "94133",
                "region": "CA",
                "street": "2140 TAYLOR ST"
              },
              "facta_filing_requirement": "CHECKED",
              "name": "Josie Georgia Harrison",
              "second_tin_exists": "NOT CHECKED",
              "tin": "12-3456789"
            },
            "rents": 1000,
            "royalties": 1000,
            "secondary_state": null,
            "secondary_state_id": null,
            "secondary_state_income_tax": null,
            "section_409a_deferrals": 1000,
            "section_409a_income": 1000,
            "september_amount": null,
            "state_income": 1000,
            "state_income_lower": null,
            "state_tax_withheld": 1000,
            "state_tax_withheld_lower": null,
            "substitute_payments_in_lieu_of_dividends_or_interest": null,
            "tax_year": "2022",
            "transactions_reported": null
          }
        ]
      }
    ],
    "status": {
      "processing_status": "PROCESSING_COMPLETE"
    },
    "updated_at": "2022-08-02T21:14:54Z"
  }
],
"request_id": "2pxQ59buGdsHRef"
307}

Was this helpful?

Check income verification eligibility and optimize conversion

/credit/payroll_income/precheck is an optional endpoint that can be called before initializing a Link session for income verification. It evaluates whether a given user is supportable by digital income verification. If the user is eligible for digital verification, that information will be associated with the user token, and in this way will generate a Link UI optimized for the end user and their specific employer. If the user cannot be confirmed as eligible, the user can still use the income verification flow, but they may be required to manually upload a paystub to verify their income.
While all request fields are optional, providing employer data will increase the chance of receiving a useful result.
When testing in Sandbox, you can control the results by providing special test values in the employer and access_tokens fields. employer_good and employer_bad will result in HIGH and LOW confidence values, respectively. employer_multi will result in a HIGH confidence with multiple payroll options. Likewise, access_good and access_bad will result in HIGH and LOW confidence values, respectively. Any other value for employer and access_tokens in Sandbox will result in UNKNOWN confidence.

credit/payroll_income/precheck

Request fields and example

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.

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.

string

The user token associated with the User data is being requested for.

access_tokens

[string]

An array of access tokens corresponding to Items belonging to the user whose eligibility is being checked. Note that if the Items specified here are not already initialized with transactions, providing them in this field will cause these Items to be initialized with (and billed for) the Transactions product.

employer

object

Information about the end user's employer

name

string

The employer's name

object

Data about the components comprising an address.

city

string

The full city name

string

The ISO 3166-1 alpha-2 country code

string

The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

string

The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

string

The full street address Example: "564 Main Street, APT 15"

tax_id

string

The employer's tax id

url

string

The URL for the employer's public website

us_military_info

object

Data about military info in the income verification precheck.

is_active_duty

boolean

Is the user currently active duty in the US military

branch

string

If the user is currently serving in the US military, the branch of the military in which they are serving Valid values: 'AIR FORCE', 'ARMY', 'COAST GUARD', 'MARINES', 'NAVY', 'UNKNOWN'

payroll_institution

object

Information about the end user's payroll institution

name

string

The name of payroll institution

/credit/payroll_income/precheck
Select Language
1const request: CreditPayrollIncomePrecheckRequest = {
user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
employer: {
  name: 'Elm Publishing',
  address: {
    city: 'New York',
    country: 'US',
    postal_code: '10012',
    region: 'NY',
    street: '123 Main Street',
  },
  tax_id: '12-3456789',
  url: 'https://elmpublishing.com',
},
us_military_info: {
  is_active_duty: true,
  branch: 'ARMY',
},
19};
20
21try {
const response = await client.creditPayrollIncomePrecheck(request);
23} catch (error) {
// handle error
25}

credit/payroll_income/precheck

Response fields and example

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

confidence

string

The confidence that Plaid can support the user in the digital income verification flow instead of requiring a manual paystub upload. One of the following:
"HIGH": It is very likely that this user can use the digital income verification flow.
"LOW": It is unlikely that this user can use the digital income verification flow.
"UNKNOWN": It was not possible to determine if the user is supportable with the information passed.

Possible values: HIGH, LOW, UNKNOWN

API Object
1{
2  "request_id": "lMjeOeu9X1VUh1F",
3  "confidence": "HIGH"
4}

Was this helpful?

Retrieve fraud insights for a user's manually uploaded document(s).

/credit/payroll_income/risk_signals/get can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering. It returns a risk score for each uploaded document that indicates the likelihood of the document being fraudulent, in addition to details on the individual risk signals contributing to the score. /credit/payroll_income/risk_signals/get can be called at any time after the INCOME_VERIFICATION_RISK_SIGNALS webhook has been fired.
/credit/payroll_income/risk_signals/get is offered as an add-on to Document Income and is billed separately. To request access to this endpoint, submit a product access request or contact your Plaid account manager.

credit/payroll_income/risk_signals/get

Request fields and example

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.

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.