Signal endpoints

API Reference guide for the Signal product

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 a newly linked 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

/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 and example

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.
access_token
requiredstring
The access token associated with the Item data is being requested for.
account_id
requiredstring
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
requiredstring
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.

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

Format: double
user_present
boolean
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
string
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
boolean
true if the ACH transaction is a recurring transaction; false otherwise
default_payment_method
string
The default ACH or non-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 NEXT_DAY_ACH: Next Day ACH settlement for debit transactions, offered by some payment processors STANDARD_ACH: standard ACH by NACHA REAL_TIME_PAYMENTS: real-time payments such as RTP and FedNow DEBIT_CARD: if the default payment is over debit card networks MULTIPLE_PAYMENT_METHODS: if there is no default debit rail or there are multiple payment methods Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS
user
object
Details about the end user initiating the transaction (i.e., the account holder).
name
object
The user's legal name
prefix
string
The user's name prefix (e.g. "Mr.")
given_name
string
The user's given name. If the user has a one-word name, it should be provided in this field.
middle_name
string
The user's middle name
family_name
string
The user's family name / surname
suffix
string
The user's name suffix (e.g. "II")
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567"
email_address
string
The user's email address.
address
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code
country
string
The ISO 3166-1 alpha-2 country code
device
object
Details about the end user's device
ip_address
string
The IP address of the device that initiated the transaction
user_agent
string
The user agent of the device that initiated the transaction (e.g. "Mozilla/5.0")
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:"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",
28  },
29  user_present: true,
30};
31
32try {
33  const eval_response = await plaidClient.signalEvaluate(eval_request);
34  const core_attributes = eval_response.data.core_attributes;
35  const scores = eval_response.data.scores;
36} catch (error) {
37  // handle error
38}
signal/evaluate

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
scores
object
Risk scoring details broken down by risk category.
customer_initiated_return_risk
object
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
integer
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
risk_tier
integer
A tier corresponding to the projected likelihood that the transaction, if initiated, will be subject to a return.
In the customer_initiated_return_risk object, there are five risk tiers corresponding to the scores: 1: Predicted customer-initiated return incidence rate between 0.00% - 0.02% 2: Predicted customer-initiated return incidence rate between 0.02% - 0.05% 3: Predicted customer-initiated return incidence rate between 0.05% - 0.1% 4: Predicted customer-initiated return incidence rate between 0.1% - 0.5% 5: Predicted customer-initiated return incidence rate greater than 0.5%

Minimum: 1
Maximum: 5
bank_initiated_return_risk
object
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
integer
A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood.

Minimum: 1
Maximum: 99
risk_tier
integer
In the bank_initiated_return_risk object, there are eight risk tiers corresponding to the scores: 1: Predicted bank-initiated return incidence rate between 0.0% - 0.5% 2: Predicted bank-initiated return incidence rate between 0.5% - 1.5% 3: Predicted bank-initiated return incidence rate between 1.5% - 3% 4: Predicted bank-initiated return incidence rate between 3% - 5% 5: Predicted bank-initiated return incidence rate between 5% - 10% 6: Predicted bank-initiated return incidence rate between 10% - 15% 7: Predicted bank-initiated return incidence rate between 15% and 50% 8: Predicted bank-initiated return incidence rate greater than 50%

Minimum: 1
Maximum: 8
core_attributes
object
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
warnings
[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
string
A broad categorization of the warning. Safe for programmatic use.
warning_code
string
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
string
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      "risk_tier": 1
6    },
7    "bank_initiated_return_risk": {
8      "score": 72,
9      "risk_tier": 7
10    }
11  },
12  "core_attributes": {
13    "days_since_first_plaid_connection": 510,
14    "plaid_connections_count_7d": 6,
15    "plaid_connections_count_30d": 7,
16    "total_plaid_connections_count": 15,
17    "is_savings_or_money_market_account": false
18  },
19  "warnings": [],
20  "request_id": "mdqfuVxeoza6mhu"
21}

/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 and example

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.
client_transaction_id
requiredstring
Must be the same as the client_transaction_id supplied when calling /signal/evaluate

Min length: 1
Max length: 36
initiated
requiredboolean
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
integer
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
string
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

Possible values: APPROVE, REVIEW, REJECT, TAKE_OTHER_RISK_MEASURES, NOT_EVALUATED
payment_method
string
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
NEXT_DAY_ACH: Next Day ACH settlement for debit transactions, offered by some payment processors
STANDARD_ACH: standard ACH by NACHA
REAL_TIME_PAYMENTS: real-time payments such as RTP and FedNow
DEBIT_CARD: if the default payment is over debit card networks
MULTIPLE_PAYMENT_METHODS: if there is no default debit rail or there are multiple payment methods
Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS

Possible values: SAME_DAY_ACH, NEXT_DAY_ACH, STANDARD_ACH, REAL_TIME_PAYMENTS, DEBIT_CARD, MULTIPLE_PAYMENT_METHODS
amount_instantly_available
number
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(decision_report_request);
9  const decision_request_id = decision_report_response.data.request_id;
10} catch (error) {
11  // handle error
12}
signal/decision/report

Response fields and example

request_id
string
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 and example

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.
client_transaction_id
requiredstring
Must be the same as the client_transaction_id supplied when calling /signal/evaluate

Min length: 1
Max length: 36
return_code
requiredstring
Must be a valid ACH return code (e.g. "R01")
If formatted incorrectly, this will result in an INVALID_FIELD error.
returned_at
string
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(return_report_request);
8  const request_id = return_report_response.data.request_id;
9  console.log(request_id)
10} catch (error) {
11  // handle error
12}
signal/return/report

Response fields and example

request_id
string
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 Link is not initialized with Signal, call /signal/prepare to opt-in that Item to the Signal data collection process, developing a Signal score.
If you are using other Plaid products after Link, e.g. Identity or Assets, call /signal/prepare after those product calls are complete.
Example flow: Link is initialized with Auth, call /auth/get for the account and routing number, call /identity/get to retrieve bank ownership details, then call /signal/prepare to begin Signal data collection. Later, once you have obtained details about the proposed transaction from the user, call /signal/evaluate for a Signal score. For more information please see Recommendations for initializing Link with specific product combinations.
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 and example

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.
access_token
requiredstring
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
string
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}