Signal Transaction Scores and Balance endpoints

Use /signal/evaluate to evaluate a planned ACH transaction to get a return risk assessment and additional risk signals.
Before using /signal/evaluate, you must first create a ruleset in the Dashboard under Signal->Rules.
/signal/evaluate can be used with either Signal Transaction Scores or the Balance product. Which product is used will be determined by the ruleset_key that you provide. For more details, see Signal Rules.
Note: This request may have higher latency when using a Balance-only ruleset. This is because Plaid must communicate directly with the institution to request data. Balance-only rulesets may have latency of up to 30 seconds or more; if you encounter errors, you may find it necessary to adjust your timeout period when making requests.

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}

After you call /signal/evaluate, Plaid will normally infer the outcome from your Signal Rules. However, if you are not using Signal Rules, if the Signal Rules outcome was REVIEW, or if you take a different action than the one determined by the Signal Rules, you will need to call /signal/decision/report. This helps improve Signal Transaction Score accuracy for your account and is necessary for proper functioning of the rule performance and rule tuning capabilities in the Dashboard. If your effective decision changes after calling /signal/decision/report (for example, you indicated that you accepted a transaction, but later on, your payment processor rejected it, so it was never initiated), call /signal/decision/report again for the transaction to correct Plaid's records.
If you are using Plaid Transfer as your payment processor, you also do not need to call /signal/decision/report, as Plaid can infer outcomes from your Transfer activity.
If using a Balance-only ruleset, this endpoint will not impact scores (Balance does not use scores), but is necessary to view accurate transaction outcomes and tune rule logic in the Dashboard.

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}

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 trends into your scores and tune rule logic. If using a Balance-only ruleset, this endpoint will not impact scores (as Balance does not use scores), but is necessary to view accurate transaction outcomes and tune rule logic in the Dashboard.

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}

When an Item is not initialized with signal, call /signal/prepare to opt-in that Item to the data collection process used to develop a Signal Transaction 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 Plaid will have access to less data for computing the Signal Transaction Score.
If your integration is purely Balance-only, this endpoint will have no effect, as Balance-only rulesets do not calculate a Signal Transaction 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.

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}

The /accounts/balance/get endpoint returns the real-time balance for each of an Item's accounts. While other endpoints, such as /accounts/get, return a balance object, /accounts/balance/get forces the available and current balance fields to be refreshed rather than cached. This endpoint can be used for existing Items that were added via any of Plaid’s other products. This endpoint can be used as long as Link has been initialized with any other product, balance itself is not a product that can be used to initialize Link. As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests.
Note: If you are getting real-time balance for the purpose of assessing the return risk of a proposed ACH transaction, it is recommended to use /signal/evaluate instead of /accounts/balance/get. /signal/evaluate returns the same real-time balance information and also provides access to Signal Rules, which provides no-code transaction business logic configuration, backtesting and recommendations for tuning your transaction acceptance logic, and the ability to easily switch between Balance and Signal Transaction Scores as needed for ultra-low-latency, ML-powered risk assessments. For more details, see the Balance documentation.

1// Pull real-time balance information for each account associated
2// with the Item
3const request: AccountsGetRequest = {
4  access_token: accessToken,
5};
6try {
7  const response = await plaidClient.accountsBalanceGet(request);
8  const accounts = response.data.accounts;
9} catch (error) {
10  // handle error
11}