Beacon

API reference for Beacon endpoints and webhooks

Add and report users on the Plaid Beacon network.

Endpoints
/beacon/user/createCreate and scan a Beacon User against a Beacon Program
/beacon/user/getFetch a Beacon User
/beacon/user/history/listList a Beacon User's history
/beacon/report/createCreate a fraud report for a given Beacon User
/beacon/report/listList Beacon Reports for a given Beacon User
/beacon/duplicate/getFetch a Beacon Duplicate
Webhooks
USER_STATUS_UPDATEDBeacon User status has changed
REPORT_CREATEDBeacon Report has been created
REPORT_UPDATEDBeacon Report has been updated
REPORT_SYNDICATION_CREATEDNew Network Report matches one of your Users
DUPLICATE_DETECTEDDuplicate Beacon User was created

/beacon/user/create

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

Create a Beacon User

Create and scan a Beacon User against your Beacon Program, according to your program's settings.
When you submit a new user to /beacon/user/create, several checks are performed immediately:
- The user's PII (provided within the user object) is searched against all other users within the Beacon Program you specified. If a match is found that violates your program's "Duplicate Information Filtering" settings, the user will be returned with a status of pending_review.
- The user's PII is also searched against all fraud reports created by your organization across all of your Beacon Programs. If the user's data matches a fraud report that your team created, the user will be returned with a status of rejected.
- Finally, the user's PII is searched against all fraud report shared with the Beacon Network by other companies. If a matching fraud report is found, the user will be returned with a pending_review status if your program has enabled automatic flagging based on network fraud.

beacon/user/create

Request fields and example

program_id
requiredstring
ID of the associated Beacon Program.
client_user_id
requiredstring
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.

Min length: 1
user
requiredobject
A Beacon User's data which is used to check against duplicate records and the Beacon Fraud Network.
date_of_birth
requiredstring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
requiredobject
The full name for a given Beacon User.
given_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
requiredstring
A string with at least one non-whitespace character, with a max length of 100 characters.
address
object
Home address for the associated user. For more context on this field, see Input Validation by Country.
street
requiredstring
The primary street portion of an address. If an address is provided, this field will always be filled.
street2
string
Extra street information, like an apartment or suite number.
city
requiredstring
City from the end user's address
region
string
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
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
requiredstring
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
email_address
string
A valid email address.

Format: email
phone_number
string
A phone number in E.164 format.
id_number
object
The ID number associated with a Beacon User.
value
requiredstring
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
requiredstring
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.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
ip_address
string
An IPv4 or IPV6 address.
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.
1const request: BeaconUserCreateRequest = {
2  program_id: 'becprg_11111111111111',
3  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
4  user: {
5    email_address: 'user@example.com',
6    date_of_birth: '1975-01-18',
7    name: {
8      given_name: 'Leslie',
9      family_name: 'Knope',
10    },
11    address: {
12      street: '123 Main St.',
13      street2: 'Unit 42',
14      city: 'Pawnee',
15      region: 'IN',
16      postal_code: '46001',
17      country: 'US',
18    },
19  },
20};
21
22try {
23  const response = await plaidClient.beaconUserCreate(request);
24  console.log(response.status.value);
25} catch (error) {
26  // handle error
27}
beacon/user/create

Response fields and example

id
string
ID of the associated Beacon User.
version
integer
The version field begins with 1 and increments each time the user is updated.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
updated_at
string
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: date-time
status
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.

Possible values: rejected, pending_review, cleared
program_id
string
ID of the associated Beacon Program.
client_user_id
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.

Min length: 1
user
object
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
object
The full name for a given Beacon User.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
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
string
The primary street portion of an address. If an address is provided, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
string
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
email_address
nullablestring
A valid email address.

Format: email
phone_number
nullablestring
A phone number in E.164 format.
id_number
nullableobject
The ID number associated with a Beacon User.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
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.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
ip_address
nullablestring
An IPv4 or IPV6 address.
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
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.

Possible values: dashboard, api, system, bulk_import
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "becusr_42cF1MNo42r9Xj",
3  "version": 1,
4  "created_at": "2020-07-24T03:26:02Z",
5  "updated_at": "2020-07-24T03:26:02Z",
6  "status": "cleared",
7  "program_id": "becprg_11111111111111",
8  "client_user_id": "your-db-id-3b24110",
9  "user": {
10    "date_of_birth": "1990-05-29",
11    "name": {
12      "given_name": "Leslie",
13      "family_name": "Knope"
14    },
15    "address": {
16      "street": "123 Main St.",
17      "street2": "Unit 42",
18      "city": "Pawnee",
19      "region": "IN",
20      "postal_code": "46001",
21      "country": "US"
22    },
23    "email_address": "user@example.com",
24    "phone_number": "+19876543212",
25    "id_number": {
26      "value": "123456789",
27      "type": "us_ssn"
28    },
29    "ip_address": "192.0.2.42"
30  },
31  "audit_trail": {
32    "source": "dashboard",
33    "dashboard_user_id": "54350110fedcbaf01234ffee",
34    "timestamp": "2020-07-24T03:26:02Z"
35  },
36  "request_id": "saKrIBuEB9qJZng"
37}

/beacon/user/get

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

Get a Beacon User

Fetch a Beacon User.
The Beacon User is returned with all of their associated information and a status based on the Beacon Network duplicate record and fraud checks.

beacon/user/get

Request fields and example

beacon_user_id
requiredstring
ID of the associated Beacon User.
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.
1const request: BeaconUserGetRequest = {
2  beacon_user_id: 'becusr_11111111111111',
3};
4
5try {
6  const response = await plaidClient.beaconUserGet(request);
7} catch (error) {
8  // handle error
9}
beacon/user/get

Response fields and example

id
string
ID of the associated Beacon User.
version
integer
The version field begins with 1 and increments each time the user is updated.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
updated_at
string
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: date-time
status
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.

Possible values: rejected, pending_review, cleared
program_id
string
ID of the associated Beacon Program.
client_user_id
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.

Min length: 1
user
object
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
object
The full name for a given Beacon User.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
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
string
The primary street portion of an address. If an address is provided, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
string
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
email_address
nullablestring
A valid email address.

Format: email
phone_number
nullablestring
A phone number in E.164 format.
id_number
nullableobject
The ID number associated with a Beacon User.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
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.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
ip_address
nullablestring
An IPv4 or IPV6 address.
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
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.

Possible values: dashboard, api, system, bulk_import
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "becusr_42cF1MNo42r9Xj",
3  "version": 1,
4  "created_at": "2020-07-24T03:26:02Z",
5  "updated_at": "2020-07-24T03:26:02Z",
6  "status": "cleared",
7  "program_id": "becprg_11111111111111",
8  "client_user_id": "your-db-id-3b24110",
9  "user": {
10    "date_of_birth": "1990-05-29",
11    "name": {
12      "given_name": "Leslie",
13      "family_name": "Knope"
14    },
15    "address": {
16      "street": "123 Main St.",
17      "street2": "Unit 42",
18      "city": "Pawnee",
19      "region": "IN",
20      "postal_code": "46001",
21      "country": "US"
22    },
23    "email_address": "user@example.com",
24    "phone_number": "+19876543212",
25    "id_number": {
26      "value": "123456789",
27      "type": "us_ssn"
28    },
29    "ip_address": "192.0.2.42"
30  },
31  "audit_trail": {
32    "source": "dashboard",
33    "dashboard_user_id": "54350110fedcbaf01234ffee",
34    "timestamp": "2020-07-24T03:26:02Z"
35  },
36  "request_id": "saKrIBuEB9qJZng"
37}

/beacon/user/history/list

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

List a Beacon User's history

List all changes to the Beacon User in reverse-chronological order.

beacon/user/history/list

Request fields and example

beacon_user_id
requiredstring
ID of the associated Beacon User.
cursor
string
An identifier that determines which page of results you receive.
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.
1const request: BeaconUserHistoryListRequest = {
2  beacon_user_id: 'becusr_11111111111111',
3};
4
5try {
6  const response = await plaidClient.beaconUserHistoryList(request);
7} catch (error) {
8  // handle error
9}
beacon/user/history/list

Response fields and example

beacon_users
[object]
id
string
ID of the associated Beacon User.
version
integer
The version field begins with 1 and increments each time the user is updated.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
updated_at
string
An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: date-time
status
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.

Possible values: rejected, pending_review, cleared
program_id
string
ID of the associated Beacon Program.
client_user_id
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.

Min length: 1
user
object
A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
date_of_birth
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
name
object
The full name for a given Beacon User.
given_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
family_name
string
A string with at least one non-whitespace character, with a max length of 100 characters.
address
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
string
The primary street portion of an address. If an address is provided, this field will always be filled.
street2
nullablestring
Extra street information, like an apartment or suite number.
city
string
City from the end user's address
region
nullablestring
An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
postal_code
nullablestring
The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
country
string
Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

Min length: 2
email_address
nullablestring
A valid email address.

Format: email
phone_number
nullablestring
A phone number in E.164 format.
id_number
nullableobject
The ID number associated with a Beacon User.
value
string
Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
type
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.

Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
ip_address
nullablestring
An IPv4 or IPV6 address.
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
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.

Possible values: dashboard, api, system, bulk_import
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "beacon_users": [
3    {
4      "id": "becusr_42cF1MNo42r9Xj",
5      "version": 1,
6      "created_at": "2020-07-24T03:26:02Z",
7      "updated_at": "2020-07-24T03:26:02Z",
8      "status": "cleared",
9      "program_id": "becprg_11111111111111",
10      "client_user_id": "your-db-id-3b24110",
11      "user": {
12        "date_of_birth": "1990-05-29",
13        "name": {
14          "given_name": "Leslie",
15          "family_name": "Knope"
16        },
17        "address": {
18          "street": "123 Main St.",
19          "street2": "Unit 42",
20          "city": "Pawnee",
21          "region": "IN",
22          "postal_code": "46001",
23          "country": "US"
24        },
25        "email_address": "user@example.com",
26        "phone_number": "+19876543212",
27        "id_number": {
28          "value": "123456789",
29          "type": "us_ssn"
30        },
31        "ip_address": "192.0.2.42"
32      },
33      "audit_trail": {
34        "source": "dashboard",
35        "dashboard_user_id": "54350110fedcbaf01234ffee",
36        "timestamp": "2020-07-24T03:26:02Z"
37      }
38    }
39  ],
40  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
41  "request_id": "saKrIBuEB9qJZng"
42}

/beacon/report/create

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

Create a Beacon Report

Create a fraud report for a given Beacon User.

beacon/report/create

Request fields and example

beacon_user_id
requiredstring
ID of the associated Beacon User.
type
requiredstring
The type of Beacon Report.
first_party: If this is the same individual as the one who submitted the KYC.
stolen: If this is a different individual from the one who submitted the KYC.
synthetic: If this is an individual using fabricated information.
account_takeover: If this individual's account was compromised.
unknown: If you aren't sure who committed the fraud.

Possible values: first_party, stolen, synthetic, account_takeover, unknown
fraud_date
requiredstring
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
fraud_amount
object
The amount and currency of the fraud or attempted fraud. fraud_amount should be omitted to indicate an unknown fraud amount.
iso_currency_code
requiredstring
An ISO-4217 currency code.

Possible values: USD
Min length: 3
value
requirednumber
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23).

Format: double
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.
1const request: BeaconReportCreateRequest = {
2  beacon_user_id: 'becusr_11111111111111',
3  type: 'first_party',
4  fraud_date: '1975-01-18',
5};
6
7try {
8  const response = await plaidClient.beaconReportCreate(request);
9} catch (error) {
10  // handle error
11}
beacon/report/create

Response fields and example

id
string
ID of the associated Beacon Report.
beacon_user_id
string
ID of the associated Beacon User.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
type
string
The type of Beacon Report.
first_party: If this is the same individual as the one who submitted the KYC.
stolen: If this is a different individual from the one who submitted the KYC.
synthetic: If this is an individual using fabricated information.
account_takeover: If this individual's account was compromised.
unknown: If you aren't sure who committed the fraud.

Possible values: first_party, stolen, synthetic, account_takeover, unknown
fraud_date
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
fraud_amount
nullableobject
The amount and currency of the fraud or attempted fraud. fraud_amount should be omitted to indicate an unknown fraud amount.
iso_currency_code
string
An ISO-4217 currency code.

Possible values: USD
Min length: 3
value
number
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23).

Format: double
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
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.

Possible values: dashboard, api, system, bulk_import
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "becrpt_11111111111111",
3  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
4  "created_at": "2020-07-24T03:26:02Z",
5  "type": "first_party",
6  "fraud_date": "1990-05-29",
7  "fraud_amount": {
8    "iso_currency_code": "USD",
9    "value": 100
10  },
11  "audit_trail": {
12    "source": "dashboard",
13    "dashboard_user_id": "54350110fedcbaf01234ffee",
14    "timestamp": "2020-07-24T03:26:02Z"
15  },
16  "request_id": "saKrIBuEB9qJZng"
17}

/beacon/report/list

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

List Beacon Reports for a Beacon User

Use the /beacon/report/list endpoint to view all Beacon Reports you created for a specific Beacon User. The reports returned by this endpoint are exclusively reports you created for a specific user. A Beacon User can only have one active report at a time, but a new report can be created if a previous report has been deleted. The results from this endpoint are paginated; the next_cursor field will be populated if there is another page of results that can be retrieved. To fetch the next page, pass the next_cursor value as the cursor parameter in the next request.

beacon/report/list

Request fields and example

beacon_user_id
requiredstring
ID of the associated Beacon User.
cursor
string
An identifier that determines which page of results you receive.
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.
1const request: BeaconReportListRequest = {
2  beacon_user_id: 'becusr_11111111111111',
3};
4
5try {
6  const response = await plaidClient.beaconReportList(request);
7} catch (error) {
8  // handle error
9}
beacon/report/list

Response fields and example

beacon_reports
[object]
id
string
ID of the associated Beacon Report.
beacon_user_id
string
ID of the associated Beacon User.
created_at
string
An ISO8601 formatted timestamp.

Format: date-time
type
string
The type of Beacon Report.
first_party: If this is the same individual as the one who submitted the KYC.
stolen: If this is a different individual from the one who submitted the KYC.
synthetic: If this is an individual using fabricated information.
account_takeover: If this individual's account was compromised.
unknown: If you aren't sure who committed the fraud.

Possible values: first_party, stolen, synthetic, account_takeover, unknown
fraud_date
string
A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: date
fraud_amount
nullableobject
The amount and currency of the fraud or attempted fraud. fraud_amount should be omitted to indicate an unknown fraud amount.
iso_currency_code
string
An ISO-4217 currency code.

Possible values: USD
Min length: 3
value
number
The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., 1.23).

Format: double
audit_trail
object
Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
source
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.

Possible values: dashboard, api, system, bulk_import
dashboard_user_id
nullablestring
ID of the associated user.
timestamp
string
An ISO8601 formatted timestamp.

Format: date-time
next_cursor
nullablestring
An identifier that determines which page of results you receive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "beacon_reports": [
3    {
4      "id": "becrpt_11111111111111",
5      "beacon_user_id": "becusr_42cF1MNo42r9Xj",
6      "created_at": "2020-07-24T03:26:02Z",
7      "type": "first_party",
8      "fraud_date": "1990-05-29",
9      "fraud_amount": {
10        "iso_currency_code": "USD",
11        "value": 100
12      },
13      "audit_trail": {
14        "source": "dashboard",
15        "dashboard_user_id": "54350110fedcbaf01234ffee",
16        "timestamp": "2020-07-24T03:26:02Z"
17      }
18    }
19  ],
20  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
21  "request_id": "saKrIBuEB9qJZng"
22}

/beacon/duplicate/get

This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or submit a product access Support ticket.

Get a Beacon Duplicate

Returns a Beacon Duplicate for a given Beacon Duplicate id.
A Beacon Duplicate represents a pair of similar Beacon Users within your organization.
Two Beacon User revisions are returned for each Duplicate record in either the beacon_user1 or beacon_user2 response fields.
The analysis field in the response indicates which fields matched between beacon_user1 and beacon_user2.

beacon/duplicate/get

Request fields and example

beacon_duplicate_id
requiredstring
ID of the associated Beacon Duplicate.
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.
1const request: BeaconDuplicateGetRequest = {
2  beacon_duplicate_id: 'becdup_11111111111111',
3};
4
5try {
6  const response = await plaidClient.beaconDuplicateGet(request);
7} catch (error) {
8  // handle error
9}
beacon/duplicate/get

Response fields and example

id
string
ID of the associated Beacon Duplicate.
beacon_user1
object
A Beacon User Revision identifies a Beacon User at some point in its revision history.
id
string
ID of the associated Beacon User.
version
integer
The version field begins with 1 and increments with each subsequent revision.
beacon_user2
object
A Beacon User Revision identifies a Beacon User at some point in its revision history.
id
string
ID of the associated Beacon User.
version
integer
The version field begins with 1 and increments with each subsequent revision.
analysis
object
Analysis of which fields matched between one Beacon User and another.
address
string
An enum indicating the match type between two Beacon Users.
match indicates that the provided input data was a strong match against the other Beacon User.
partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.

Possible values: match, partial_match, no_match, no_data
date_of_birth
string
An enum indicating the match type between two Beacon Users.
match indicates that the provided input data was a strong match against the other Beacon User.
partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.

Possible values: match, partial_match, no_match, no_data
email_address
string
An enum indicating the match type between two Beacon Users.
match indicates that the provided input data was a strong match against the other Beacon User.
partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.

Possible values: match, partial_match, no_match, no_data
name
string
An enum indicating the match type between two Beacon Users.
match indicates that the provided input data was a strong match against the other Beacon User.
partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.

Possible values: match, partial_match, no_match, no_data
id_number
string
An enum indicating the match type between two Beacon Users.
match indicates that the provided input data was a strong match against the other Beacon User.
partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.

Possible values: match, partial_match, no_match, no_data
ip_address
string
An enum indicating the match type between two Beacon Users.
match indicates that the provided input data was a strong match against the other Beacon User.
partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.

Possible values: match, partial_match, no_match, no_data
phone_number
string
An enum indicating the match type between two Beacon Users.
match indicates that the provided input data was a strong match against the other Beacon User.
partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.

Possible values: match, partial_match, no_match, no_data
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "id": "becdup_11111111111111",
3  "beacon_user1": {
4    "id": "becusr_42cF1MNo42r9Xj",
5    "version": 1
6  },
7  "beacon_user2": {
8    "id": "becusr_42cF1MNo42r9Xj",
9    "version": 1
10  },
11  "analysis": {
12    "address": "match",
13    "date_of_birth": "match",
14    "email_address": "match",
15    "name": "match",
16    "id_number": "match",
17    "ip_address": "match",
18    "phone_number": "match"
19  },
20  "request_id": "saKrIBuEB9qJZng"
21}

Webhooks

A user in cleared status may change to a pending_review status after a Beacon Report Syndication is received, which would trigger both a USER_STATUS_UPDATED as well as a REPORT_SYNDICATION_CREATED webhook. New Beacon Users may also be flagged as duplicates of another user, which triggers a DUPLICATE_DETECTED webhook. Beacon Reports created and managed by your account will trigger REPORT_CREATED and REPORT_UPDATED webhooks, and may also result in a USER_STATUS_UPDATED if the user status is changed from cleared to rejected at that time.

USER_STATUS_UPDATED

Fired when a Beacon User status has changed, which can occur manually via the dashboard or when information is reported to the Beacon network.

webhook_type
string
BEACON
webhook_code
string
USER_STATUS_UPDATED
beacon_user_id
string
The ID of the associated Beacon user.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "BEACON",
3  "webhook_code": "USER_STATUS_UPDATED",
4  "beacon_user_id": "becusr_4WciCrtbxF76T8",
5  "environment": "production"
6}

REPORT_CREATED

Fired when one of your Beacon Users is first reported to the Beacon network.

webhook_type
string
BEACON
webhook_code
string
REPORT_CREATED
beacon_report_id
string
The ID of the associated Beacon Report.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "BEACON",
3  "webhook_code": "REPORT_CREATED",
4  "beacon_report_id": "becrpt_2zugxV6hWQZG91",
5  "environment": "production"
6}

REPORT_UPDATED

Fired when one of your existing Beacon Reports has been modified or removed from the Beacon Network.

webhook_type
string
BEACON
webhook_code
string
REPORT_UPDATED
beacon_report_id
string
The ID of the associated Beacon Report.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "BEACON",
3  "webhook_code": "REPORT_UPDATED",
4  "beacon_report_id": "becrpt_2zugxV6hWQZG91",
5  "environment": "production"
6}

REPORT_SYNDICATION_CREATED

Fired when a report created on the Beacon Network matches with one of your Beacon Users.

webhook_type
string
BEACON
webhook_code
string
REPORT_SYNDICATION_CREATED
beacon_report_syndication_id
string
The ID of the associated Beacon Report Syndication.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "BEACON",
3  "webhook_code": "REPORT_SYNDICATION_CREATED",
4  "beacon_report_syndication_id": "becrsn_eZPgiiv3JH8rfT",
5  "environment": "production"
6}

DUPLICATE_DETECTED

Fired when a Beacon User created within your organization matches one of your existing users.

webhook_type
string
BEACON
webhook_code
string
DUPLICATE_DETECTED
beacon_duplicate_id
string
The ID of the associated Beacon Duplicate.
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
1{
2  "webhook_type": "BEACON",
3  "webhook_code": "DUPLICATE_DETECTED",
4  "beacon_duplicate_id": "becdup_erJcFn97r9sugZ",
5  "environment": "production"
6}