Plaid logo
Docs
ALL DOCS

Signal

  • Introduction to Signal
  • Add Signal to your app
Plaid logo
Docs
Close search modal
Experimental
Ask Finn!Ask a question to get started
Note: Finn isn't perfect. He's just a chatbot that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Finn any PII -- he's scared of intimacy. All chats with Finn are subject to Plaid's Privacy Policy.
Plaid.com
Get API keys
Open nav

Introduction to Signal

Assess the return risk of an ACH debit transaction

Explore API

API Reference

View Signal requests, responses, and example code

View Signal API

Quickstart

Learn about Plaid's key concepts and run starter code

Get started

Overview

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.

Prefer to learn by watching? Get an overview of how Signal works in just 3 minutes!

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): This endpoint is intended for customers who use Signal alongside Identity. In the specific scenario when /identity/get is called immediately after linking an Item, but the Item was not configured with Signal or Identity upon its creation, calling /signal/prepare immediately after /identity/get can reduce latency.

Sample flow

  1. Using /link/token/create, create a Link token initialized with the auth and signal products, and use this token to launch Link.
  2. The end user completes the Link flow by logging into their financial institution.
  3. Use /item/public_token/exchange to exchange the public_token returned from Link's onSuccess callback for an access_token.
  4. Call /accounts/get using the access_token returned in the previous step to obtain the account_id of the account you will be evaluating.
  5. Call /signal/evaluate using the access_token and account_id obtained in the previous steps.
  6. 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 the core_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.
  7. If you decide to proceed with the transfer, initiate it as you normally would using Plaid Auth endpoints. For more details, see Auth.
  8. Report your decision following the risk assessment and whether or not to proceed with the transfer by calling /signal/decision/report.
  9. 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": 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 },
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.

Image of Plaid Signal Dashboard
Home page of Signal dashboard
Image of Plaid Signal Performance Dashboard
Signal Dashboard performance screen

Testing Signal

You can test Signal in the Sandbox and Development environments. 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.

Next steps

To request access to Signal in Production, contact Sales.

If you're ready to launch to Production, see the Launch checklist.

Launch checklist

Recommended steps to take before launching in Production

Launch
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord