{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/plaid/main/json-schema/plaid-signal-evaluate-request-schema.json",
  "title": "SignalEvaluateRequest",
  "description": "SignalEvaluateRequest defines the request schema for `/signal/evaluate`",
  "x-generated": "2026-09-23",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/plaid-plaid-api-openapi.yml#/components/schemas/SignalEvaluateRequest",
  "type": "object",
  "properties": {
    "client_id": {
      "$ref": "#/$defs/APIClientID"
    },
    "secret": {
      "$ref": "#/$defs/APISecret"
    },
    "access_token": {
      "$ref": "#/$defs/AccessToken"
    },
    "account_id": {
      "type": "string",
      "description": "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.\n\nThis 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_id": {
      "type": "string",
      "description": "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.",
      "minLength": 1,
      "maxLength": 36
    },
    "amount": {
      "type": "number",
      "format": "double",
      "description": "The transaction amount, in USD (e.g. `102.05`)"
    },
    "user_present": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "`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.",
      "deprecated": true,
      "x-hidden-from-docs": true
    },
    "client_user_id": {
      "type": "string",
      "description": "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_recurring": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "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_method": {
      "type": [
        "string",
        "null"
      ],
      "description": "The default ACH payment method to complete the transaction. When using a Balance-only ruleset, this field is ignored.\n\n`SAME_DAY_ACH`: Same Day ACH by Nacha. The debit transaction is processed and settled on the same day.\n\n`STANDARD_ACH`: Standard ACH by Nacha.\n\n`MULTIPLE_PAYMENT_METHODS`: If there is no default debit rail or there are multiple payment methods.\n\nPossible values:  `SAME_DAY_ACH`, `STANDARD_ACH`, `MULTIPLE_PAYMENT_METHODS`"
    },
    "user": {
      "$ref": "#/$defs/SignalUser"
    },
    "device": {
      "$ref": "#/$defs/SignalDevice"
    },
    "risk_profile_key": {
      "deprecated": true,
      "x-hidden-from-docs": true,
      "type": [
        "string",
        "null"
      ],
      "description": "Specifying `risk_profile_key` is deprecated. Please provide `ruleset` instead."
    },
    "ruleset_key": {
      "type": [
        "string",
        "null"
      ],
      "description": "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/)."
    }
  },
  "required": [
    "access_token",
    "account_id",
    "client_transaction_id",
    "amount"
  ],
  "$defs": {
    "APIClientID": {
      "title": "ClientID",
      "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."
    },
    "APISecret": {
      "title": "APISecret",
      "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."
    },
    "AccessToken": {
      "title": "AccessToken",
      "type": "string",
      "description": "The access token associated with the Item for which data is being requested."
    },
    "SignalAddressData": {
      "title": "AddressData",
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "Data about the components comprising an address.",
      "properties": {
        "city": {
          "type": "string",
          "description": "The full city name"
        },
        "region": {
          "type": [
            "string",
            "null"
          ],
          "description": "The region or state\nExample: `\"NC\"`"
        },
        "street": {
          "type": "string",
          "description": "The full street address\nExample: `\"564 Main Street, APT 15\"`"
        },
        "postal_code": {
          "type": [
            "string",
            "null"
          ],
          "description": "The postal code"
        },
        "country": {
          "type": [
            "string",
            "null"
          ],
          "description": "The ISO 3166-1 alpha-2 country code"
        }
      }
    },
    "SignalDevice": {
      "title": "SignalEvaluateDevice",
      "type": "object",
      "description": "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.",
      "properties": {
        "ip_address": {
          "type": [
            "string",
            "null"
          ],
          "description": "The IP address of the device that initiated the transaction"
        },
        "user_agent": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user agent of the device that initiated the transaction (e.g. \"Mozilla/5.0\")"
        }
      }
    },
    "SignalPersonName": {
      "title": "SignalPersonName",
      "type": [
        "object",
        "null"
      ],
      "description": "The user's legal name",
      "properties": {
        "prefix": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's name prefix (e.g. \"Mr.\")"
        },
        "given_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's given name. If the user has a one-word name, it should be provided in this field."
        },
        "middle_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's middle name"
        },
        "family_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's family name / surname"
        },
        "suffix": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's name suffix (e.g. \"II\")"
        }
      }
    },
    "SignalUser": {
      "title": "SignalUser",
      "type": "object",
      "description": "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.",
      "properties": {
        "name": {
          "$ref": "#/$defs/SignalPersonName"
        },
        "phone_number": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's phone number, in E.164 format: +{countrycode}{number}. For example: \"+14151234567\""
        },
        "email_address": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's email address."
        },
        "address": {
          "$ref": "#/$defs/SignalAddressData"
        }
      }
    }
  }
}