Introduction to Signal
Assess the return risk of an ACH debit to prevent NSFs and other returns
API Reference
View Signal requests, responses, and example code
View Signal APIQuickstart
Learn about Plaid's key concepts and run starter code
Get startedOverview
Plaid Signal allows you to evaluate the likelihood of a specific ACH transaction resulting in a return. Signal is powered by a machine learning model trained on Plaid’s consumer-permissioned data network, including over 1,000 risk factors, and is designed to provide a result in under one second. Signal provides two overall risk assessment scores, along with associated risk tiers and over 60 predictive insights that you can incorporate into your own risk assessment models. By using the Signal API, you can release funds earlier to optimize your user experience while managing the risk of ACH returns.
Usage
Signal is intended to be used alongside Auth.
The Signal API consists of three routes and one optional route:
/signal/evaluate
: Call this endpoint before initiating an ACH transaction to get the return risk assessment and additional risk signals.
/signal/decision/report
: After calling /signal/evaluate
, call this endpoint to inform Plaid of your risk and payment decision outcome and whether or not you executed the ACH transaction. Your decision feedback will help the model to optimize for your use case.
/signal/return/report
: Call this endpoint when you receive a return for the ACH transaction you previously called the /signal/evaluate
endpoint for. Your feedback allows the model to incorporate the latest risk trends into its assessments.
/signal/prepare
(optional): Call this endpoint to add Signal to a pre-existing Item that was not initialized with Signal.
Sample flow
- Using
/link/token/create
, create a Link token initialized with theauth
andsignal
products, and use this token to launch Link.
- To require Signal and reject all Link attempts at institutions that don't support Signal, include
signal
in theproducts
array. - To allow users to link accounts at institutions that don't support Signal, include
signal
in therequired_if_supported_products
oroptional_products
array. - If you add Signal to the
additional_consented_products
array instead, you may need to call/signal/prepare
later on; see Using/signal/prepare
for details.
- The end user completes the Link flow by logging into their financial institution.
- Use
/item/public_token/exchange
to exchange thepublic_token
returned from Link'sonSuccess
callback for anaccess_token
. - Call
/accounts/get
using theaccess_token
returned in the previous step to obtain theaccount_id
of the account you will be evaluating. - Call
/signal/evaluate
using theaccess_token
andaccount_id
obtained in the previous steps. - Based on the data returned by
/signal/evaluate
, decide whether to proceed directly with the transfer or apply an additional risk mitigation layer. You may either use the risk scoring and tier data returned by/signal/evaluate
or use thecore_attributes
and feed them into your own model, along with additional information you may have about the user and the proposed transaction. For potentially high-risk transactions, you can also call/accounts/balance/get
at this point to obtain real-time balance information and use it as another input into your decision. - If you decide to proceed with the transfer, initiate it as you normally would using Plaid Auth endpoints. For more details, see Auth.
- Report your decision following the risk assessment and whether or not to proceed with the transfer by calling
/signal/decision/report
. - If the transfer is later returned, call
/signal/return/report
.
Signal data
Signal provides two categories of risk -- customer-initiated return risk, which corresponds to ACH returns initiated by customers (unauthorized ACH returns), and bank-initiated return risk (primarily NSFs and administrative returns), which corresponds to ACH returns initiated by financial institutions. Each risk category has a score ranging from 1-99 and a corresponding risk tier to help you better understand the associated level of return risk.
In addition to the risk scores and tiers, Signal also provides more than 60 predictive insights to help provide even greater visibility into the factors contributing to a given score and tier. You may choose to incorporate these insights into your own risk models.
For more details on the data returned by Signal, see the Signal API reference.
1{2 "scores": {3 "customer_initiated_return_risk": {4 "score": 9,5 "risk_tier": 16 },7 "bank_initiated_return_risk": {8 "score": 72,9 "risk_tier": 710 }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 },20 "request_id": "mdqfuVxeoza6mhu"21}
Signal Dashboard
To help you monitor your ACH returns and performance, Plaid provides a Signal Dashboard within the Plaid Dashboard. You can access the Signal Dashboard after receiving Production access to Signal. On the Dashboard, you can view ACH returns and causes over time, as well as view the details of individual transactions. You can also use the Dashboard to model and backtest the impact of different Signal score risk thresholds on your return rates.
Signal Rules
With Signal Rules, you can configure your decision logic directly within the Signal Dashboard. Once integrated with Rules, you can tune your decisioning logic via our no-code UI and see the updated rules immediately applied to your transactions.
You can create new rules, monitor their ongoing performance, and use performance metrics to tailor your rules to your desired risk level.
Using the performance tools in the Signal Dashboard, you can analyze the impact of individual rules and determine the scores, attributes, and thresholds that allow you to best leverage Signal's risk assessment.
Signal Rules is currently in closed beta; to request access, contact your account manager.
Using Signal with micro-deposit or database Items
Items created via Same Day micro-deposits, Instant micro-deposits, Database Match, or Database Insights are not typically compatible with any other Plaid products besides Auth and Transfer. An exception is Signal, which can be used with manually verified Items that were previously seen on the Plaid network (approximately 30% of these Items). To use Signal with one of these Items:
- To enable the Item for Signal,
signal
must be included in theoptional_products
,required_if_supported_products
, oradditional_consented_products
array during the/link/token/create
call at Item creation. (For this flow,signal
should not be included in theproducts
array, since including any other product thanauth
in theproducts
array can prevent micro-deposit or database verification flows from activating.)- If this was not done during Item creation, you can Signal consent to an existing Item by sending it through update mode.
- Call
/signal/evaluate
.
If the Item is supported by Signal, you will receive results. If the Item was not previously seen on the Plaid network and therefore cannot be used with Signal, you will receive a PRODUCTS_NOT_SUPPORTED
error and will not be billed for the API call.
Testing Signal
In the Sandbox environment, values returned by /signal/evaluate
will be randomly generated. Note that the /sandbox/public_token/create
endpoint does not allow signal
in the initial_products
array; for testing with this endpoint, put auth
in the initial_products
array instead, then proceed to call the Signal endpoints as normal.
In the Sandbox environment, you can influence the score returned by /signal/evaluate
by providing particular values in the amount
request field. Use the values from the following table to control the returned score:
Amount | Score |
---|---|
3.53 | 10 |
12.17 | 60 |
27.53 | 90 |
The Signal Dashboard is not supported in Sandbox. To access the Signal Dashboard, request full Production access to Signal.
Signal is not supported in Limited Production. To access Signal, request full Production access.
Using /signal/prepare
The most common way to initialize an Item with Signal is at Item creation, by including signal
in the products
, optional_products
, or required_if_supported_products
arrays during the /link/token/create
call. If you do this, you do not need to call /signal/prepare
.
However, if you put Signal in the additional_consented_products
array, this will not add Signal to your Item, but will allow you to add it later. When using this approach, you should call /signal/prepare
before calling /signal/evaluate
for the first time on that Item. If you skip calling /signal/prepare
, your first call to /signal/evaluate
will be less accurate, because Signal will not have had the opportunity to pre-load certain data about the Item. Because /signal/evaluate
is designed to achieve low latency, it will not wait for this data and will instead return a Signal score using the limited information available. Subsequent calls to /signal/evaluate
on the Item will have higher accuracy.
Signal pricing
Signal is billed on a per-request model, based on the number of calls to the /signal/evaluate
endpoint. To view the exact pricing you may be eligible for, contact Sales. For more details about pricing and billing models, see Plaid billing.