Signal endpoints

API Reference guide for the Signal product

For how-to guidance, see the Signal documentation.

Endpoints
/signal/evaluateRetrieve Signal scores
/signal/decision/reportReport whether you initiated an ACH transaction
/signal/return/reportReport a return for an ACH transaction
/signal/prepareAdd Signal to an existing Item
See also
/processor/token/createCreate a token for using Signal with a processing partner
/processor/signal/evaluateRetrieve Signal scores as a processor partner
/processor/signal/decision/reportReport whether you initiated an ACH transaction as a processor partner
/processor/signal/return/reportReport a return for an ACH transaction as a processor partner
/processor/signal/preparePrepare a processor token for Signal
=*=*=*=

/signal/evaluate

Evaluate a planned ACH transaction

Use /signal/evaluate to evaluate a planned ACH transaction to get a return risk assessment (such as a risk score and risk tier) and additional risk signals.
In order to obtain a valid score for an ACH transaction, Plaid must have an access token for the account, and the Item must be healthy (receiving product updates) or have recently been in a healthy state. If the transaction does not meet eligibility requirements, an error will be returned corresponding to the underlying cause. If /signal/evaluate is called on the same transaction multiple times within a 24-hour period, cached results may be returned. For more information please refer to the error documentation on Item errors and Link in Update Mode.
Note: This request may take some time to complete if Signal is being added to an existing Item. This is because Plaid must communicate directly with the institution when retrieving the data for the first time.

signal/evaluate

Request fields

client_id
stringstring
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
stringstring
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_token
requiredstringrequired, string
The access token associated with the Item data is being requested for.
account_id
requiredstringrequired, string
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 callback metadata.
This will return an 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
requiredstringrequired, string
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.

Min length: 1
Max length: 36
amount
requirednumberrequired, number
The transaction amount, in USD (e.g. 102.05)

Format: double
user_present
booleanboolean
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_id
stringstring
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
booleanboolean
Use true if the ACH transaction is a part of recurring schedule (for example, a monthly repayment); false otherwise
default_payment_method
stringstring
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
user
objectobject
Details about the end user initiating the transaction (i.e., the account holder). When calling /signal/evaluate or /signal/processor/evaluate, this field is optional, but strongly recommended to increase the accuracy of Signal results.
name
objectobject
The user's legal name
prefix
stringstring
The user's name prefix (e.g. "Mr.")
given_name
stringstring
The user's given name. If the user has a one-word name, it should be provided in this field.
middle_name
stringstring
The user's middle name
family_name
stringstring
The user's family name / surname
suffix
stringstring
The user's name suffix (e.g. "II")
phone_number
stringstring
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567"
email_address
stringstring
The user's email address.
address
objectobject
Data about the components comprising an address.
city
stringstring
The full city name
region
stringstring
The region or state Example: "NC"
street
stringstring
The full street address Example: "564 Main Street, APT 15"
postal_code
stringstring
The postal code
country
stringstring
The ISO 3166-1 alpha-2 country code
device
objectobject
Details about the end user's device. When calling /signal/evaluate or /signal/processor/evaluate, this field is optional, but strongly recommended to increase the accuracy of Signal results.
ip_address
stringstring
The IP address of the device that initiated the transaction
user_agent
stringstring
The user agent of the device that initiated the transaction (e.g. "Mozilla/5.0")
ruleset_key
stringstring
The key of the ruleset to use for evaluating this transaction. You can configure a ruleset using the Signal dashboard located within the Plaid Dashboard. If not provided, no ruleset will be used.
1const eval_request = {
2  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
3  account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',
4  client_transaction_id: 'txn12345',
5  amount: 123.45,
6  client_user_id: 'user1234',
7  user: {
8    name: {
9      prefix: 'Ms.',
10      given_name: 'Jane',
11      middle_name: 'Leah',
12      family_name: 'Doe',
13      suffix: 'Jr.',
14    },
15    phone_number: '+14152223333',
16    email_address: 'jane.doe@example.com',
17    address: {
18      street: '2493 Leisure Lane',
19      city: 'San Matias',
20      region: 'CA',
21      postal_code: '93405-2255',
22      country: 'US',
23    },
24  },
25  device: {
26    ip_address: '198.30.2.2',
27    user_agent:
28      'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1',
29  },
30  user_present: true,
31};
32

33try {
34  const eval_response = await plaidClient.signalEvaluate(eval_request);
35  const core_attributes = eval_response.data.core_attributes;
36  const scores = eval_response.data.scores;
37} catch (error) {
38  // handle error
39}
signal/evaluate

Response fields and example

request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
scores
nullableobjectnullable, object
Risk scoring details broken down by risk category.
customer_initiated_return_risk
objectobject
The object contains a risk score and a risk tier that evaluate the transaction return risk of an unauthorized debit. Common return codes in this category include: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized.
score
integerinteger
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
bank_initiated_return_risk
objectobject
The object contains a risk score and a risk tier that evaluate the transaction return risk because an account is overdrawn or because an ineligible account is used. Common return codes in this category include: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days.
score
integerinteger
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
core_attributes
objectobject
The core attributes object contains additional data that can be used to assess the ACH return risk. Examples of data include:
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
ruleset
nullableobjectnullable, object
Details about the transaction result after evaluated by the requested Ruleset. If a ruleset_key is not provided, this field will be omitted. This feature is currently in closed beta; to request access, contact your account manager.
ruleset_key
stringstring
The key of the Ruleset used for this transaction.
result
stringstring
The result of the rule that was triggered for this transaction.
ACCEPT: Accept the transaction for processing. REROUTE: Reroute the transaction to a different payment method, as this transaction is too risky. REVIEW: Review the transaction before proceeding.

Possible values: ACCEPT, REROUTE, REVIEW
triggered_rule_details
nullableobjectnullable, object
Rules are run in numerical order. The first rule with a logic match is triggered. These are the details of that rule.
internal_note
stringstring
An optional message attached to the triggered rule, defined within the Dashboard, for your internal use. Useful for debugging, such as “Account appears to be closed.”
custom_action_key
stringstring
A string key, defined within the Dashboard, used to trigger programmatic behavior for a certain result. For instance, you could optionally choose to define a "3-day-hold" custom_action_key for an ACCEPT result.
outcome
deprecatedstringdeprecated, string
The evaluated outcome for this transaction. This field is deprecated, use result or triggered_rule_details.custom_action_key instead.
warnings
[object][object]
If bank information was not available to be used in the Signal model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of Signal scores in the case of missing bank data, file a support ticket or contact your Plaid account manager.
warning_type
stringstring
A broad categorization of the warning. Safe for programmatic use.
warning_code
stringstring
The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. If you receive the ITEM_LOGIN_REQUIRED warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.
warning_message
stringstring
A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use.
1{
2  "scores": {
3    "customer_initiated_return_risk": {
4      "score": 9
5    },
6    "bank_initiated_return_risk": {
7      "score": 82
8    }
9  },
10  "core_attributes": {
11    "days_since_first_plaid_connection": 510,
12    "plaid_connections_count_7d": 6,
13    "plaid_connections_count_30d": 7,
14    "total_plaid_connections_count": 15,
15    "is_savings_or_money_market_account": false
16  },
17  "ruleset": {
18    "ruleset_key": "onboarding_flow",
19    "result": "REROUTE",
20    "triggered_rule_details": {
21      "internal_note": "Rerouting customer to different payment method, since bank risk score is too high"
22    }
23  },
24  "warnings": [],
25  "request_id": "mdqfuVxeoza6mhu"
26}
=*=*=*=

/signal/decision/report

Report whether you initiated an ACH transaction

After calling /signal/evaluate, call /signal/decision/report to report whether the transaction was initiated.

signal/decision/report

Request fields

client_id
stringstring
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
stringstring
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.
client_transaction_id
requiredstringrequired, string
Must be the same as the client_transaction_id supplied when calling /signal/evaluate

Min length: 1
Max length: 36
initiated
requiredbooleanrequired, boolean
true if the ACH transaction was initiated, false otherwise.
This field must be returned as a boolean. If formatted incorrectly, this will result in an INVALID_FIELD error.
days_funds_on_hold
integerinteger
The actual number of days (hold time) since the ACH debit transaction that you wait before making funds available to your customers. The holding time could affect the ACH return rate.
For example, use 0 if you make funds available to your customers instantly or the same day following the debit transaction, or 1 if you make funds available the next day following the debit initialization.

Minimum: 0
decision_outcome
stringstring
The payment decision from the risk assessment.
APPROVE: approve the transaction without requiring further actions from your customers. For example, use this field if you are placing a standard hold for all the approved transactions before making funds available to your customers. You should also use this field if you decide to accelerate the fund availability for your customers.
REVIEW: the transaction requires manual review
REJECT: reject the transaction
TAKE_OTHER_RISK_MEASURES: for example, placing a longer hold on funds than those approved transactions or introducing customer frictions such as step-up verification/authentication
NOT_EVALUATED: if only logging the Signal results without using them

Possible values: APPROVE, REVIEW, REJECT, TAKE_OTHER_RISK_MEASURES, NOT_EVALUATED
payment_method
stringstring
The payment method to complete the transaction after the risk assessment. It may be different from the default payment method.
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
amount_instantly_available
numbernumber
The amount (in USD) made available to your customers instantly following the debit transaction. It could be a partial amount of the requested transaction (example: 102.05).

Format: double 
1const decision_report_request = {
2  client_transaction_id: 'txn12345',
3  initiated: true,
4  days_funds_on_hold: 3,
5};
6

7try {
8  const decision_report_response = await plaidClient.signalDecisionReport(
9    decision_report_request,
10  );
11  const decision_request_id = decision_report_response.data.request_id;
12} catch (error) {
13  // handle error
14}
signal/decision/report

Response fields and example

request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
=*=*=*=

/signal/return/report

Report a return for an ACH transaction

Call the /signal/return/report endpoint to report a returned transaction that was previously sent to the /signal/evaluate endpoint. Your feedback will be used by the model to incorporate the latest risk trend in your portfolio.

signal/return/report

Request fields

client_id
stringstring
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
stringstring
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.
client_transaction_id
requiredstringrequired, string
Must be the same as the client_transaction_id supplied when calling /signal/evaluate or /accounts/balance/get.

Min length: 1
Max length: 36
return_code
requiredstringrequired, string
Must be a valid ACH return code (e.g. "R01")
If formatted incorrectly, this will result in an INVALID_FIELD error.
returned_at
stringstring
Date and time when you receive the returns from your payment processors, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ).

Format: date-time 
1const return_report_request = {
2  client_transaction_id: 'txn12345',
3  return_code: 'R01',
4};
5

6try {
7  const return_report_response = await plaidClient.signalReturnReport(
8    return_report_request,
9  );
10  const request_id = return_report_response.data.request_id;
11  console.log(request_id);
12} catch (error) {
13  // handle error
14}
signal/return/report

Response fields and example

request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}
=*=*=*=

/signal/prepare

Opt-in an Item to Signal

When an Item is not initialized with Signal, call /signal/prepare to opt-in that Item to the Signal data collection process, developing a Signal score. This should be done on Items where Signal was added in the additional_consented_products array but not in the products, optional_products, or required_if_supported_products array. If /signal/prepare is skipped on an Item that is not initialized with Signal, the initial call to /signal/evaluate on that Item will be less accurate, because Signal will have access to less data for computing the Signal score.
If run on an Item that is already initialized with Signal, this endpoint will return a 200 response and will not modify the Item.

signal/prepare

Request fields

client_id
stringstring
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
stringstring
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_token
requiredstringrequired, string
The access token associated with the Item data is being requested for.
1const prepare_request = {
2  client_id: '7f57eb3d2a9j6480121fx361',
3  secret: '79g03eoofwl8240v776r2h667442119',
4  access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',
5};
6

7try {
8  const prepare_response = await plaidClient.signalPrepare(prepare_request);
9  const request_id = prepare_response.data.request_id;
10  console.log(request_id);
11} catch (error) {
12  // handle error
13}
signal/prepare

Response fields and example

request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "mdqfuVxeoza6mhu"
3}