Plaid logo
Docs
ALL DOCS

Signal

  • Introduction to Signal
  • Add Signal to your app
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
    Note: Bill isn't perfect. He's just a robot platypus 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 Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
    Plaid.com
    Log in
    Get API Keys
    Open nav

    Add Signal to your app

    Learn how to add Signal support to your application

    In this guide, we'll start from scratch and walk through how to use Signal to perform risk analysis on proposed ACH transactions. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to fetching Signal data.

    Get Plaid API keys and complete application and company profile

    If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

    You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

    Install and initialize Plaid libraries

    You can use our official server-side client libraries to connect to the Plaid API from your application:

    Select Language
    1// Install via npm
    2npm install --save plaid

    After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

    Select Language
    1// Using Express
    2const express = require('express');
    3const app = express();
    4app.use(express.json());
    5
    6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
    7
    8const configuration = new Configuration({
    9 basePath: PlaidEnvironments.sandbox,
    10 baseOptions: {
    11 headers: {
    12 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
    13 'PLAID-SECRET': process.env.PLAID_SECRET,
    14 },
    15 },
    16});
    17
    18const client = new PlaidApi(configuration);

    Create an Item in Link

    Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

    Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the Dashboard.

    Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

    Create a link_token
    Select Language
    1app.post('/api/create_link_token', async function (request, response) {
    2 // Get the client_user_id by searching for the current user
    3 const user = await User.find(...);
    4 const clientUserId = user.id;
    5 const request = {
    6 user: {
    7 // This should correspond to a unique id for the current user.
    8 client_user_id: clientUserId,
    9 },
    10 client_name: 'Plaid Test App',
    11 products: ['auth, signal'],
    12 language: 'en',
    13 webhook: 'https://webhook.example.com',
    14 redirect_uri: 'https://domainname.com/oauth-page.html',
    15 country_codes: ['US'],
    16 };
    17 try {
    18 const createTokenResponse = await client.linkTokenCreate(request);
    19 response.json(createTokenResponse.data);
    20 } catch (error) {
    21 // handle error
    22 }
    23});
    Install Link dependency
    Select Language
    1<head>
    2 <title>Connect a bank</title>
    3 <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
    4</head>
    Configure the client-side Link handler
    1const linkHandler = Plaid.create({
    2 token: (await $.post('/create_link_token')).link_token,
    3 onSuccess: (public_token, metadata) => {
    4 // Send the public_token to your app server.
    5 $.post('/exchange_public_token', {
    6 public_token: public_token,
    7 });
    8 },
    9 onExit: (err, metadata) => {
    10 // Optionally capture when your user exited the Link flow.
    11 // Storing this information can be helpful for support.
    12 },
    13 onEvent: (eventName, metadata) => {
    14 // Optionally capture Link flow events, streamed through
    15 // this callback as your users connect an Item to Plaid.
    16 },
    17});
    18
    19linkHandler.open();

    Get a persistent access_token

    Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

    Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

    Select group for content switcher
    Select Language
    1app.post('/api/exchange_public_token', async function (
    2 request,
    3 response,
    4 next,
    5) {
    6 const publicToken = request.body.public_token;
    7 try {
    8 const response = await client.itemPublicTokenExchange({
    9 public_token: publicToken,
    10 });
    11
    12 // These values should be saved to a persistent database and
    13 // associated with the currently signed-in user
    14 const accessToken = response.data.access_token;
    15 const itemID = response.data.item_id;
    16
    17 res.json({ public_token_exchange: 'complete' });
    18 } catch (error) {
    19 // handle error
    20 }
    21});

    Fetching Signal data

    Now that the authentication step is out of the way, we can begin using Signal to analyze proposed transactions.

    Evaluating a proposed transaction
    Select Language
    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}

    Example response data is below. (The core_attributes in the example have been truncated. In actual usage, /signal/evaluate returns over 65 core attributes.)

    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}

    If the transaction is high risk, you may also want to make a second check using Balance. Balance can retrieve real-time balance data, although it does not return data as quickly as Signal does.

    If you decide to proceed with the transfer, initiate it as you normally would using Plaid Auth endpoints.

    After evaluating the transfer, report your decision about whether you proceeded with the transfer back to Plaid. This will help continually improve Signal's accuracy.

    Select Language
    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}

    Finally, if you allow a transfer that does end up returned, you can report that result back to Plaid as well:

    Select Language
    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}

    Next steps

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

    Launch checklist

    Recommended steps to take before launching in Production

    Launch

    Launch checklist

    Recommended steps to take before launching in Production

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