Refresh user items for Financial-Insights bundle

POST /user/financial_data/refresh

/user/financial_data/refresh is an optional endpoint that initiates an on-demand extraction to fetch the newest transactions for a User using the Financial Insights bundle. This bundle refreshes the Transactions, Investments, and Liabilities product data. This endpoint is for clients who use the Transactions Insights bundle and want to proactively update all linked Items under a user. The refresh may succeed or fail on a per-Item basis. Use the results array in the response to understand the outcome for each Item.

This endpoint is distinct from /transactions/refresh, which triggers a refresh for a single Item. Use /user/financial_data/refresh to target all Items for a user instead.

Request Body

Required

UserFinancialDataRefreshRequest defines the request schema for user/financial_data/refresh

Parameters

user_id
required, string
A Plaid-generated ID that identifies the end user.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.

Response

UserFinancialDataRefreshResponse defines the response schema for user/financial_data/refresh

Response Properties

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
user_id
string
The user ID associated with the refresh request.
results
array[object]
item_id
string
A unique identifier for the Plaid Item.
product
string
The product for which the refresh was attempted.
error
object
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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
required, string
A broad categorization of the error. Safe for programmatic use.
error_code
required, string
The particular error code. Safe for programmatic use.
error_code_reason
string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use. Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated. OAUTH_CONSENT_EXPIRED: The user’s access consent for this OAuth connection to this institution has expired. OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
error_message
required, string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
required, 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.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In this 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 be provided for the error_type ASSET_REPORT_ERROR or CHECK_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error