action plaid_credit_bank_employment_get { label: "Retrieve information from the bank accounts used for employment verification" description: "`/credit/bank_employment/get` returns the employment report(s) derived from bank transaction data for a specified user." provider: plaid method: POST path: "/beta/credit/v1/bank_employment/get" encoding: json input: { type: "object" description: "CreditBankEmploymentGetRequest defines the request schema for `/beta/credit/v1/bank_employment/get`." required: ["user_token"] 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." } 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: "CreditBankEmploymentGetResponse defines the response schema for `/beta/credit/v1/bank_employment/get`." required: ["bank_employment_reports", "request_id"] properties: { bank_employment_reports: { type: "array" description: "Bank Employment data. Each entry in the array will be a distinct bank employment report." items: { type: "object" description: "The report of the Bank Employment data for an end user." required: ["bank_employment_report_id", "generated_time", "days_requested", "items", "warnings"] properties: { bank_employment_report_id: { type: "string" description: "The unique identifier associated with the Bank Employment Report." } days_requested: { type: "integer" description: "The number of days requested by the customer for the Bank Employment Report." } generated_time: { type: "string" format: "date-time" description: "The time when the Bank Employment Report was generated, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (e.g. \"2018-04-12T03:32:11Z\")." } 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." required: ["item_id", "last_updated_time", "institution_id", "institution_name", "bank_employments", "bank_employment_accounts"] properties: { bank_employment_accounts: { type: "array" description: "The Item's accounts that have Bank Employment 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_employments: { type: "array" description: "The bank employment information for this Item. Each entry in the array is a different employer found." items: { type: "object" description: "Detailed information for the bank employment." required: ["bank_employment_id", "account_id", "employer", "latest_deposit_date", "earliest_deposit_date"] properties: { account_id: { type: "string" description: "Plaid's unique identifier for the account." } bank_employment_id: { type: "string" description: "A unique identifier for the bank employment." } earliest_deposit_date: { type: "string" format: "date" description: "The date of the earliest deposit from this employer from within the period of the days requested." } employer: { type: "object" description: "Object containing employer data." required: ["name"] properties: { name: { type: "object" additionalProperties: true } } } latest_deposit_date: { type: "string" format: "date" description: "The date of the most recent deposit from this employer." } } } } 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, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (e.g. \"2018-04-12T03:32:11Z\")." } } } } warnings: { type: "array" description: "If data from the Bank Employment 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 Employment Report." required: ["warning_type", "warning_code", "cause"] 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_EMPLOYMENT_WARNING`." enum: ["BANK_EMPLOYMENT_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." } } } }