Introduction to Beacon (beta)

Learn how to fight fraud with the Plaid Beacon network

API Reference
View Beacon requests, responses, and example code

The Beacon beta program is now closed. Customers who are not already using Beacon should instead use the newer Plaid Protect, which incorporates Beacon's capabilities and enhances them with additional fraud insights.

Beacon (US only) helps prevent fraud by detecting data associated with stolen or synthetic identities, account takeover fraud, or breaches. You can create blocklists based on data reported by the Beacon network, or based on first-party fraud attempts on your own app. Beacon is available free of charge.

An optional paid feature, Beacon Account Insights, is available to customers who want to build their own risk analysis on top of Plaid's Beacon data. Beacon Account Insights includes risk-related details such as account age, recent PII changes on the account, and recent failed login attempts. For a full list of data reported by Beacon Account Insights, see the /beacon/user/account_insights/get response schema.

Integration setup

  1. Create a Beacon program via the Dashboard.
    • For best results, disable "auto flag reported user" under the "data breach hits" section, unless you have a specific business reason to enable it. Because so many users have been exposed to data breaches, enabling auto-flagging for data breach hits will result in a large number of users entering the review queue. All other automatically-selected options should be left enabled for most use cases.
  2. Take note of the Beacon program ID, which is the portion of the URL after the / when viewing the program in the Dashboard, e.g. becprg_7Fn5XcPhXnJJyU. You will need this ID when calling /beacon/user/create and other endpoints.
  3. (Optional) For best results, backfill six months of existing data into Beacon. This should include both known-good and known-fraudulent users. To backfill, call /beacon/user/create for each user, making sure to include any known instances of fraud in the report object.

Make sure to always use the same client_user_id when referring to the same end user, whenever you call /beacon/user/create, /beacon/user/update, or /link/token/create.

User creation

  1. To create a new user, call /beacon/user/create.
  2. (Optional) To be alerted for the accidental creation of potential duplicate users, listen for the DUPLICATE_DETECTED webhook. You can investigate potential duplicates via the Dashboard or by calling /beacon/duplicate/get.

Reviewing and reporting fraud signals

  1. Review any Beacon hits via the Dashboard, to clear or reject the user.
  2. If you become aware of any fraud committed by a user, report it to the network by clicking the "Report Fraud" button in the Beacon Dashboard or by calling /beacon/report/create. To learn more about how to properly categorize fraud, see the Fraud Reporting Guide.
  3. (Optional) To monitor for fraud on an ongoing basis, listen for the REPORT_SYNDICATION_CREATED webhook to be alerted to new fraud reports for any Beacon user in your system. When this webhook fires, to get more details on the report, use the Dashboard or call /beacon/report_syndication/get.
  4. (Optional) Call /beacon/user/update when changes to user data occur or if the user links a new account. This will immediately re-run fraud checks for the user and may generate Beacon hits.

Using Beacon Account Insights (optional)

Beacon Account Insights is an optional paid feature that allows you to build your own risk analysis on top of Plaid-reported risk signals. Reported risk signals include account age, recent PII changes on the account, and recent failed login attempts. For a full list of returned fields, see the API Reference for /beacon/user/account_insights/get.

  1. Create a Link token and use it to launch Link, following the Link documentation for your platform. Include beacon in the products array when calling /link/token/create.
  2. The end user will then complete a Link session, resulting in a public_token, which can be obtained by either the onSuccess client-side callback or by calling /link/token/get.
  3. Use /item/public_token/exchange to exchange the public_token for an access_token.
  4. Call /beacon/user/update to associate the access_token with the Beacon user.
  5. Call /beacon/user/account_insights/get to get account insights.