Review a Beacon User

POST /beacon/user/review

Update the status of a Beacon User.

When updating a Beacon User's status via this endpoint, Plaid validates that the status change is consistent with the related state for this Beacon User. Specifically, we will check:

  1. Whether there are any associated Beacon Reports connected to the Beacon User, and
  2. Whether there are any confirmed Beacon Report Syndications connected to the Beacon User.

When updating a Beacon User's status to rejected, we enforce that either a Beacon Report has been created for the Beacon User or a Beacon Report Syndication has been confirmed. When updating a Beacon User's status to cleared, we enforce that there are no active Beacon Reports or confirmed Beacon Report Syndications associated with the user. If you previously created a Beacon Report for this user, you must delete it before updating the Beacon User's status to cleared. There are no restrictions on updating a Beacon User's status to pending_review.

If these conditions are not met, the request will be rejected with an error explaining the issue.

Request Body

Required

Request input for updating the status of a Beacon User

Parameters

beacon_user_id
required, string
ID of the associated Beacon User.
status
required, string
A status of a Beacon User. rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. pending_review: The Beacon User has been marked for review. cleared: The Beacon User has been cleared of fraud.
client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.

Response

A Beacon User represents an end user that has been scanned against the Beacon Network.

Response Properties

item_ids
required, array[string]
An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.
id
required, string
ID of the associated Beacon User.
version
required, integer
The version field begins with 1 and increments each time the user is updated.
created_at
required, string
An ISO8601 formatted timestamp.
updated_at
required, string
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.
status
required, string
A status of a Beacon User. rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. pending_review: The Beacon User has been marked for review. cleared: The Beacon User has been cleared of fraud.
program_id
required, string
ID of the associated Beacon Program.
client_user_id
required, string
A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.
user
required, object
A Beacon User’s data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
date_of_birth
required, string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).
name
required, object
The full name for a given Beacon User.
given_name
required, string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
required, string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
required, object
Even if an address has been collected, some fields may be null depending on the region’s addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code
street
required, string
The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.
street2
required, string
Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.
city
required, string
City from the end user’s address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."
region
required, string
An ISO 3166-2 subdivision code. Related terms would be “state”, “province”, “prefecture”, “zone”, “subdivision”, etc.
postal_code
required, string
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
required, string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
email_address
required, string
A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696.
phone_number
required, string
A phone number in E.164 format.
id_number
required, object
The ID number associated with a Beacon User.
value
required, string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.
type
required, string
A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.
ip_address
required, string
An IPv4 or IPV6 address.
depository_accounts
required, array[object]
account_mask
required, string
The last 2-4 numeric characters of this account’s account number.
routing_number
required, string
The routing number of the account.
added_at
required, string
An ISO8601 formatted timestamp.
audit_trail
required, object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
required, string
A type indicating what caused a resource to be changed or updated. dashboard - The resource was created or updated by a member of your team via the Plaid dashboard. api - The resource was created or updated via the Plaid API. system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user’s status would automatically be updated and the audit trail source would be system. bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.
dashboard_user_id
required, string
ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard_user/get.
timestamp
required, string
An ISO8601 formatted timestamp.
request_id
required, string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.