POST/signal/evaluate

Evaluate an ACH transaction

Evaluates a planned ACH transaction and returns a return-risk assessment with additional risk signals. Supply access_token, account_id, client_transaction_id, and amount, and select the ruleset that determines whether Signal Transaction Scores or Balance is used. Create the required ruleset before calling this endpoint, and allow additional time for Balance-only evaluations because they can take 30 seconds or more.

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

14 body fields

Planned ACH transaction and optional end-user, device, and ruleset details 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.

access_tokenstringrequired

The access token associated with the Item for which data is being requested.

account_idstringrequired

The Plaid `account_id` of the account that is the funding source for the proposed transaction. The `account_id` is returned in the `/accounts/get` endpoint as well as the [`onSuccess`](https://plaid.com/docs/link/ios/#link-ios-onsuccess-linkSuccess-metadata-accounts-id) callback metadata. This will return an [`INVALID_ACCOUNT_ID`](https://plaid.com/docs/errors/invalid-input/#invalid_account_id) error if the account has been removed at the bank or if the `account_id` is no longer valid.

client_transaction_idstringrequired

The unique ID that you would like to use to refer to this evaluation attempt - for example, a payment attempt ID. You will use this later to debug this evaluation, and/or report an ACH return, etc. The max length for this field is 36 characters. The `client_transaction_id` also functions as an idempotency key; calling `/signal/evaluate` with a previously used `client_transaction_id` will return the results of the previous evaluation rather than triggering a fresh evaluation.

amountnumberrequired

The transaction amount, in USD (e.g. `102.05`)

user_presentbooleandeprecatedoptional

`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). When using a Balance-only ruleset, this field is ignored. This field is not currently used as part of Signal Transaction Score evaluations, but may be used in the future.

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

Use `true` if the ACH transaction is a part of recurring schedule (for example, a monthly repayment); `false` otherwise. When using a Balance-only ruleset, this field is ignored.

default_payment_methodstringoptional

The default ACH payment method to complete the transaction. When using a Balance-only ruleset, this field is ignored. `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.

risk_profile_keystringdeprecatedoptional

Specifying `risk_profile_key` is deprecated. Please provide `ruleset` instead.

ruleset_keystringoptional

The key of the ruleset to use for evaluating this transaction. You can create a ruleset using the Plaid Dashboard, under [Signal->Rules](https://dashboard.plaid.com/signal/risk-profiles). If not provided, for all new customers as of October 15, 2025, the `default` ruleset will be used. For existing Signal Transaction Scores customers as of October 15, 2025, by default, no ruleset will be used if the `ruleset_key` is not provided. For more information, or to opt out of using rulesets, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/).

2 status codes

200Returns a `request_id`, risk `scores` when applicable, `core_attributes`, ruleset results when applicable, and `warnings` describing 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.

risk_profileobjectdeprecatedoptional

RiskProfile is deprecated, use `ruleset` instead.

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>required

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 results in the case of missing bank data, file a support ticket or contact your Plaid account manager.

defaultReturned when the request cannot be processed; inspect `error_code`, `error_type`, and `error_message` to identify the problem.

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

access_token, account_id, client_transaction_id, and amount are required. client_transaction_id must contain between 1 and 36 characters, and ruleset_key must identify a ruleset configured for the account when you do not want the applicable default ruleset. If supplied, user.phone_number must use E.164 format.

import { Client } from "acme-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
  auth: { apiKey: process.env.API_KEY },
  retry: {
    maxAttempts: 3,
    retryOn: [
      408,
      425,
      429,
      500,
      502,
      503,
      504,
    ],
    backoffMs: 500,
    maxBackoffMs: 8000,
  },
  timeoutMs: 30000,
});

const result = await client.evaluate.create({
  accessToken: "sk_live_4eC39Hq",
  accountId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  clientTransactionId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  amount: 1999,
  clientId: "c0a80123-4567-89ab-cdef-0123456789ab",
});

{
  "scores": {
    "customer_initiated_return_risk": {
      "score": 9
    },
    "bank_initiated_return_risk": {
      "score": 82
    }
  },
  "core_attributes": {
    "available_balance": 2200,
    "current_balance": 2000
  },
  "ruleset": {
    "ruleset_key": "onboarding_flow",
    "result": "REROUTE",
    "triggered_rule_details": {
      "internal_note": "Rerouting customer to different payment method, since bank risk score is too high"
    }
  },
  "warnings": [],
  "request_id": "mdqfuVxeoza6mhu"
}

Request

Response

Errors