Retrieve information from the bank accounts used for income verification

v1.0.0

/credit/bank_income/get returns the bank income report(s) for a specified user.

Input

{
  "type": "object",
  "description": "CreditBankIncomeGetRequest defines the request schema for `/credit/bank_income/get`.",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "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."
    },
    "options": {
      "type": "object",
      "description": "An optional object for `/credit/bank_income/get` request options.",
      "properties": {
        "count": {
          "type": "integer",
          "description": "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."
        }
      }
    },
    "secret": {
      "type": "string",
      "description": "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."
    },
    "user_token": {
      "type": "string",
      "description": "The user token associated with the User data is being requested for."
    }
  }
}

Output

{
  "type": "object",
  "description": "CreditBankIncomeGetResponse defines the response schema for `/credit/bank_income/get`",
  "required": [
    "request_id"
  ],
  "properties": {
    "bank_income": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "The report of the Bank Income data for an end user.",
        "properties": {
          "bank_income_id": {
            "type": "string",
            "description": "The unique identifier associated with the Bank Income Report."
          },
          "bank_income_summary": {
            "type": "object",
            "description": "Summary for bank income across all income sources and items (max history of 730 days).",
            "properties": {
              "end_date": {
                "type": "string",
                "format": "date",
                "description": "The latest date in which all income sources identified by Plaid appear in the user's account.\nThe date will be returned in an ISO 8601 format (YYYY-MM-DD)."
              },
              "historical_summary": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "The end user's monthly summary for the income source(s).",
                  "properties": {
                    "end_date": {
                      "type": "string",
                      "format": "date",
                      "description": "The end date of the period included in this monthly summary.\nThis 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.\nThe date will be returned in an ISO 8601 format (YYYY-MM-DD)."
                    },
                    "iso_currency_code": {
                      "type": "string",
                      "description": "The ISO 4217 currency code of the amount or balance.\nPlease use [`total_amounts`](https://plaid.com/docs/api/products/income/#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead."
                    },
                    "start_date": {
                      "type": "string",
                      "format": "date",
                      "description": "The start date of the period covered in this monthly summary.\nThis 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.\nThe date will be returned in an ISO 8601 format (YYYY-MM-DD)."
                    },
                    "total_amount": {
                      "type": "number",
                      "description": "Total amount of earnings for the income source(s) of the user for the month in the summary.\nThis may return an incorrect value if the summary includes income sources in multiple currencies.\nPlease use [`total_amounts`](https://plaid.com/docs/api/products/income/#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead."
                    },
                    "total_amounts": {
                      "type": "array",
                      "description": "Total amount of earnings for the income source(s) of the user for the month in the summary.\nThis can contain multiple amounts, with each amount denominated in one unique currency.",
                      "items": {
                        "type": "object",
                        "description": "This contains an amount, denominated in the currency specified by either `iso_currency_code` or `unofficial_currency_code`",
                        "properties": {
                          "amount": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "iso_currency_code": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "unofficial_currency_code": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    },
                    "transactions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "The transactions data for the end user's income source(s).",
                        "properties": {
                          "amount": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "check_number": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "date": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "iso_currency_code": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "original_description": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "pending": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "transaction_id": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "unofficial_currency_code": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    },
                    "unofficial_currency_code": {
                      "type": "string",
                      "description": "The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null.\nUnofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.\nPlease use [`total_amounts`](https://plaid.com/docs/api/products/income/#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead."
                    }
                  }
                }
              },
              "income_categories_count": {
                "type": "integer",
                "description": "Number of income categories per end user."
              },
              "income_sources_count": {
                "type": "integer",
                "description": "Number of income sources per end user."
              },
              "income_transactions_count": {
                "type": "integer",
                "description": "Number of income transactions per end user."
              },
              "iso_currency_code": {
                "type": "string",
                "description": "The ISO 4217 currency code of the amount or balance.\nPlease use [`total_amounts`](https://plaid.com/docs/api/products/income/#credit-bank_income-get-response-bank-income-bank-income-summary-total-amounts) instead."
              },
              "start_date": {
                "type": "string",
                "format": "date",
                "description": "The earliest date within the days requested in which all income sources identified by Plaid appear in a user's account.\nThe date will be returned in an ISO 8601 format (YYYY-MM-DD)."
              },
              "total_amount": {
                "type": "number",
                "description": "Total amount of earnings across all the income sources in the end user's Items for the days requested by the client.\nThis may return an incorrect value if the summary includes income sources in multiple currencies.\nPlease use [`total_amounts`](https://plaid.com/docs/api/products/income/#credit-bank_income-get-response-bank-income-bank-income-summary-total-amounts) instead."
              },
              "total_amounts": {
                "type": "array",
                "description": "Total amount of earnings across all the income sources in the end user's Items for the days requested by the client.\nThis can contain multiple amounts, with each amount denominated in one unique currency.",
                "items": {
                  "type": "object",
                  "description": "This contains an amount, denominated in the currency specified by either `iso_currency_code` or `unofficial_currency_code`",
                  "properties": {
                    "amount": {
                      "type": "number",
                      "description": "Value of amount with up to 2 decimal places."
                    },
                    "iso_currency_code": {
                      "type": "string",
                      "description": "The ISO 4217 currency code of the amount or balance."
                    },
                    "unofficial_currency_code": {
                      "type": "string",
                      "description": "The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null.\nUnofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries."
                    }
                  }
                }
              },
              "unofficial_currency_code": {
                "type": "string",
                "description": "The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null.\nUnofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.\nPlease use [`total_amounts`](https://plaid.com/docs/api/products/income/#credit-bank_income-get-response-bank-income-bank-income-summary-total-amounts) instead."
              }
            }
          },
          "days_requested": {
            "type": "integer",
            "description": "The number of days requested by the customer for the Bank Income Report."
          },
          "generated_time": {
            "type": "string",
            "format": "date-time",
            "description": "The time when the Bank Income Report was generated."
          },
          "items": {
            "type": "array",
            "description": "The list of Items in the report along with the associated metadata about the Item.",
            "items": {
              "type": "object",
              "description": "The details and metadata for an end user's Item.",
              "properties": {
                "bank_income_accounts": {
                  "type": "array",
                  "description": "The Item's accounts that have Bank Income data.",
                  "items": {
                    "type": "object",
                    "description": "The Item's bank accounts that have the selected data.",
                    "required": [
                      "account_id",
                      "mask",
                      "name",
                      "official_name",
                      "subtype",
                      "type",
                      "owners"
                    ],
                    "properties": {
                      "account_id": {
                        "type": "string",
                        "description": "Plaid's unique identifier for the account."
                      },
                      "mask": {
                        "type": "string",
                        "description": "The last 2-4 alphanumeric characters of an account's official account number.\nNote 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": {
                        "type": "string",
                        "description": "The name of the bank account."
                      },
                      "official_name": {
                        "type": "string",
                        "description": "The official name of the bank account."
                      },
                      "owners": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "subtype": {
                        "type": "string",
                        "description": "Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see [Account schemas](https://plaid.com/docs/api/accounts/#StandaloneAccountType-depository).",
                        "enum": [
                          "checking",
                          "savings",
                          "hsa",
                          "cd",
                          "money market",
                          "paypal",
                          "prepaid",
                          "cash management",
                          "ebt",
                          "all"
                        ]
                      },
                      "type": {
                        "type": "string",
                        "description": "The account type. This will always be `depository`.",
                        "enum": [
                          "depository"
                        ]
                      }
                    }
                  }
                },
                "bank_income_sources": {
                  "type": "array",
                  "description": "The income sources for this Item. Each entry in the array is a single income source.",
                  "items": {
                    "type": "object",
                    "description": "Detailed information for the income source.",
                    "properties": {
                      "account_id": {
                        "type": "string",
                        "description": "Plaid's unique identifier for the account."
                      },
                      "end_date": {
                        "type": "string",
                        "format": "date",
                        "description": "Maximum of all dates within the specific income sources in the user’s bank account for days requested by the client.\nThe date will be returned in an ISO 8601 format (YYYY-MM-DD)."
                      },
                      "historical_summary": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "income_category": {
                        "type": "string",
                        "description": "The income category.",
                        "enum": [
                          "SALARY",
                          "UNEMPLOYMENT",
                          "CASH",
                          "GIG_ECONOMY",
                          "RENTAL",
                          "CHILD_SUPPORT",
                          "MILITARY",
                          "RETIREMENT",
                          "LONG_TERM_DISABILITY",
                          "BANK_INTEREST",
                          "CASH_DEPOSIT",
                          "TRANSFER_FROM_APPLICATION",
                          "TAX_REFUND",
                          "OTHER"
                        ]
                      },
                      "income_description": {
                        "type": "string",
                        "description": "The most common name or original description for the underlying income transactions."
                      },
                      "income_source_id": {
                        "type": "string",
                        "description": "A unique identifier for an income source."
                      },
                      "pay_frequency": {
                        "type": "string",
                        "description": "The income pay frequency.",
                        "enum": [
                          "WEEKLY",
                          "BIWEEKLY",
                          "SEMI_MONTHLY",
                          "MONTHLY",
                          "UNKNOWN"
                        ]
                      },
                      "start_date": {
                        "type": "string",
                        "format": "date",
                        "description": "Minimum of all dates within the specific income sources in the user's bank account for days requested by the client.\nThe date will be returned in an ISO 8601 format (YYYY-MM-DD)."
                      },
                      "total_amount": {
                        "type": "number",
                        "description": "Total amount of earnings in the user’s bank account for the specific income source for days requested by the client."
                      },
                      "transaction_count": {
                        "type": "integer",
                        "description": "Number of transactions for the income source within the start and end date."
                      }
                    }
                  }
                },
                "institution_id": {
                  "type": "string",
                  "description": "The unique identifier of the institution associated with the Item."
                },
                "institution_name": {
                  "type": "string",
                  "description": "The name of the institution associated with the Item."
                },
                "item_id": {
                  "type": "string",
                  "description": "The unique identifier for the Item."
                },
                "last_updated_time": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The time when this Item's data was last retrieved from the financial institution."
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "description": "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.",
            "items": {
              "type": "object",
              "description": "The warning associated with the data that was unavailable for the Bank Income Report.",
              "properties": {
                "cause": {
                  "type": "object",
                  "description": "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.",
                  "required": [
                    "error_type",
                    "error_code",
                    "error_message",
                    "display_message",
                    "item_id"
                  ],
                  "properties": {
                    "display_message": {
                      "type": "string",
                      "description": "A user-friendly representation of the error code. null if the error is not related to user action.\nThis may change over time and is not safe for programmatic use."
                    },
                    "error_code": {
                      "type": "string",
                      "description": "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": {
                      "type": "string",
                      "description": "A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use."
                    },
                    "error_type": {
                      "type": "string",
                      "description": "A broad categorization of the error. Safe for programmatic use.",
                      "enum": [
                        "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"
                      ]
                    },
                    "item_id": {
                      "type": "string",
                      "description": "The `item_id` of the Item associated with this warning."
                    }
                  }
                },
                "warning_code": {
                  "type": "string",
                  "description": "The warning code identifies a specific kind of warning.\n`IDENTITY_UNAVAILABLE`: Unable to extract identity for the Item\n`TRANSACTIONS_UNAVAILABLE`: Unable to extract transactions for the Item\n`ITEM_UNAPPROVED`: User did not grant permission to share data for the Item\n`REPORT_DELETED`: Report deleted due to customer or consumer request\n`DATA_UNAVAILABLE`: No relevant data was found for the Item",
                  "enum": [
                    "IDENTITY_UNAVAILABLE",
                    "TRANSACTIONS_UNAVAILABLE",
                    "ITEM_UNAPPROVED",
                    "REPORT_DELETED",
                    "DATA_UNAVAILABLE"
                  ]
                },
                "warning_type": {
                  "type": "string",
                  "description": "The warning type which will always be `BANK_INCOME_WARNING`.",
                  "enum": [
                    "BANK_INCOME_WARNING"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "request_id": {
      "type": "string",
      "description": "A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive."
    }
  }
}