Sample - Plaid API
POST/processor/signal/evaluate

Evaluate a planned ACH transaction

Evaluates a planned ACH transaction and returns a return-risk assessment with additional risk signals. Supply processor_token, client_transaction_id, and amount, and optionally provide user, device, payment-method, and ruleset details to support the evaluation. Latency may be higher when Signal Transaction Scores is first added to an Item or when using a Balance-only ruleset.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

12 body fields

Details of the planned ACH transaction and the user, device, and ruleset context used for risk evaluation.

client_idstringoptional
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.
secretstringoptional
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.
processor_tokenstringrequired
The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor-<environment>-<identifier>`
client_transaction_idstringrequired
The unique ID that you would like to use to refer to this transaction. For your convenience mapping your internal data, you could use your internal ID/identifier for this transaction. The max length for this field is 36 characters.
amountnumberrequired
The transaction amount, in USD (e.g. `102.05`)
user_presentbooleanoptional
`true` if the end user is present while initiating the ACH transfer and the endpoint is being called; `false` otherwise (for example, when the ACH transfer is scheduled and the end user is not present, or you call this endpoint after the ACH transfer but before submitting the Nacha file for ACH processing).
client_user_idstringoptional
A unique ID that identifies the end user in your system. This ID is used to correlate requests by a user with multiple Items. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`.
is_recurringbooleanoptional
**true** if the ACH transaction is a recurring transaction; **false** otherwise.
default_payment_methodstringoptional
The default ACH payment method to complete the transaction. `SAME_DAY_ACH`: Same Day ACH by Nacha. The debit transaction is processed and settled on the same day. `STANDARD_ACH`: Standard ACH by Nacha. `MULTIPLE_PAYMENT_METHODS`: If there is no default debit rail or there are multiple payment methods. Possible values: `SAME_DAY_ACH`, `STANDARD_ACH`, `MULTIPLE_PAYMENT_METHODS`
userobjectoptional
Details about the end user initiating the transaction (i.e., the account holder). These fields are optional, but strongly recommended to increase the accuracy of results when using Signal Transaction Scores. When using a Balance-only ruleset, if the Signal Addendum has been signed, these fields are ignored; if the Addendum has not been signed, using these fields will result in an error.
deviceobjectoptional
Details about the end user's device. These fields are optional, but strongly recommended to increase the accuracy of results when using Signal Transaction Scores. When using a Balance-only Ruleset, these fields are ignored if the Signal Addendum has been signed; if it has not been signed, using these fields will result in an error.
ruleset_keystringoptional
The key of the ruleset to use for this transaction. You can configure a ruleset using the Plaid Dashboard, under [Signal->Rules](https://dashboard.plaid.com/signal/risk-profiles). If not provided, for customers who began using Signal Transaction Scores before October 15, 2025, by default, no ruleset will be used; for customers who began using Signal Transaction Scores after that date, or for Balance customers, the `default` ruleset will be used. For more details, or to opt out of using a ruleset, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/).

2 status codes
200Returns a `request_id`, risk `scores` when provided by the selected ruleset, core attributes, ruleset results, and any warnings about missing or stale bank information.
request_idstringrequired
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
scoresobjectrequired
Risk scoring details broken down by risk category. When using a Balance-only ruleset, this object will not be returned.
core_attributesobjectoptional
The core attributes object contains additional data that can be used to assess the ACH return risk. If using a Balance-only ruleset, only `available_balance` and `current_balance` will be returned as core attributes. If using a Signal Transaction Scores ruleset, over 80 core attributes will be returned. Examples of attributes include: `available_balance` and `current_balance`: The balance in the ACH transaction funding account `days_since_first_plaid_connection`: The number of days since the first time the Item was connected to an application via Plaid `plaid_connections_count_7d`: The number of times the Item has been connected to applications via Plaid over the past 7 days `plaid_connections_count_30d`: The number of times the Item has been connected to applications via Plaid over the past 30 days `total_plaid_connections_count`: The number of times the Item has been connected to applications via Plaid `is_savings_or_money_market_account`: Indicates whether the ACH transaction funding account is a savings/money market account For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact sales or your Plaid account manager.
rulesetobjectoptional
Details about the transaction result after evaluation by the requested Ruleset. If a `ruleset_key` is not provided, for customers who began using Signal Transaction Scores before October 15, 2025, by default, this field will be omitted. To learn more, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/).
warningsarray<SignalWarning>optional
If bank information was not available to be used in the Signal Transaction Scores model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of scores in the case of missing bank data, file a support ticket or contact your Plaid account manager.
defaultError response.
error_typestringrequired
A broad categorization of the error. Safe for programmatic use.
Allowed:INVALID_REQUESTINVALID_RESULTINVALID_INPUTINSTITUTION_ERRORRATE_LIMIT_EXCEEDEDAPI_ERRORITEM_ERRORASSET_REPORT_ERRORBASE_REPORT_ERRORRECAPTCHA_ERROROAUTH_ERRORPAYMENT_ERROR
error_codestringrequired
The particular error code. Safe for programmatic use.
error_code_reasonstringoptional
The specific reason for the error code. Currently, reasons are only supported for 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_messagestringrequired
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagestringrequired
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_idstringoptional
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causesarrayoptional
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.
statusintegeroptional
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_urlstringoptional
The URL of a Plaid documentation page with more information about the error
suggested_actionstringoptional
Suggested steps for resolving the error
required_account_subtypesarray<string>optional
A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.
provided_account_subtypesarray<string>optional
A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.

Error handling

processor_token, client_transaction_id, and amount are required. client_transaction_id must contain 1 to 36 characters, and default_payment_method must use the payment-method value supported by your configuration, such as SAME_DAY_ACH, STANDARD_ACH, or MULTIPLE_PAYMENT_METHODS. If supplied, user.phone_number must use E.164 format.