Beacon 
=======

#### API reference for Beacon endpoints and webhooks 

Add and report users on the Plaid Beacon network.

| Endpoints |  |
| --- | --- |
| [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) | Create and scan a Beacon User against a Beacon Program |
| [/beacon/user/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserget) | Fetch a Beacon User |
| [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) | Update and rescan a Beacon User |
| [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) | Fetch a Beacon User's account insights |
| [/beacon/user/history/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserhistorylist) | List a Beacon User's history |
| [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) | Create a fraud report for a given Beacon User |
| [/beacon/report/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportget) | Fetch a Beacon Report |
| [/beacon/report/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportlist) | List Beacon Reports for a given Beacon User |
| [/beacon/report\_syndication/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationget) | Fetch a Beacon Report Syndication |
| [/beacon/report\_syndication/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationlist) | List Beacon Report Syndications for a given Beacon User |
| [/beacon/duplicate/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconduplicateget) | Fetch a Beacon duplicate |

| See also |  |
| --- | --- |
| [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about a dashboard user |
| [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List dashboard users |

| Webhooks |  |
| --- | --- |
| [USER\_STATUS\_UPDATED](https://plaid.com/docs/api/products/beacon/index.html.md#user_status_updated) | Beacon User status has changed |
| [REPORT\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_created) | Beacon Report has been created |
| [REPORT\_UPDATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_updated) | Beacon Report has been updated |
| [REPORT\_SYNDICATION\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_syndication_created) | New Network Report matches one of your Users |
| [DUPLICATE\_DETECTED](https://plaid.com/docs/api/products/beacon/index.html.md#duplicate_detected) | Duplicate Beacon User was created |

\=\*=\*=\*=

#### /beacon/user/create 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### 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](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , 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.

#### Request fields 

required, string

ID of the associated Beacon Program.

required, string

A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. 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`.

required, object

A Beacon User's data which is used to check against duplicate records and the Beacon Fraud Network.

In order to create a Beacon User, in addition to the `name`, \_either\_ the `date_of_birth` \_or\_ the `depository_accounts` field must be provided.

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

required, object

The full name for a given Beacon User.

required, string

A string with at least one non-whitespace character, with a max length of 100 characters.

required, string

A string with at least one non-whitespace character, with a max length of 100 characters.

object

Home address for the associated user. For more context on this field, see [Input Validation by Country](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#input-validation-by-country) .

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.

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.

required, string

City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.

string

A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field.

string

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

required, string

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

string

A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) .

Format: `email`

string

A phone number in E.164 format.

object

The ID number associated with a Beacon User.

required, string

Value of the identity document typed in by the user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

required, string

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

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`

string

An IPv4 or IPv6 address.

\[object\]

Provide a list of bank accounts that are associated with this Beacon User. These accounts will be scanned across the Beacon Network and used to find duplicate records.

Note: These accounts will not have Bank Account Insights. To receive Bank Account Insights please supply `access_tokens`.

required, string

Must be a valid US Bank Account Number

required, string

The routing number of the account.

\[string\]

Send this array of access tokens to link accounts to the Beacon User and have them evaluated for Account Insights. A maximum of 50 accounts total can be added to a single Beacon User.

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.

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.

```ruby
request = Plaid::BeaconUserCreateRequest.new(
  {
    program_id: 'becprg_11111111111111',
    client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
    access_tokens: [access_token],
    user: Plaid::BeaconUserRequestData.new(
      {
        email_address: 'user@example.com',
        date_of_birth: '1975-01-18',
        name: Plaid::BeaconUserName.new(
          {
            given_name: 'Leslie',
            family_name: 'Knope'
          }
        ),
        address: Plaid::BeaconUserAddress.new(
          {
            street: '123 Main St.',
            street2: 'Unit 42',
            city: 'Pawnee',
            region: 'IN',
            postal_code: '46001',
            country: 'US'
          }
        )
      }
    )
  }
)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/user/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "program_id": "becprg_11111111111111",
  "client_user_id": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "access_tokens": ["${ACCESS_TOKEN}"],
  "user": {
    "email_address": "user@example.com",
    "date_of_birth": "1975-01-18",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    }
  }
}'

```

```node
const request: BeaconUserCreateRequest = {
  program_id: 'becprg_11111111111111',
  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
  access_tokens: [access_token],
  user: {
    email_address: 'user@example.com',
    date_of_birth: '1975-01-18',
    name: {
      given_name: 'Leslie',
      family_name: 'Knope',
    },
    address: {
      street: '123 Main St.',
      street2: 'Unit 42',
      city: 'Pawnee',
      region: 'IN',
      postal_code: '46001',
      country: 'US',
    },
  },
};

try {
  const response = await plaidClient.beaconUserCreate(request);
  console.log(response.status.value);
} catch (error) {
  // handle error
}

```

```java
LocalDate dobBeacon = LocalDate.parse("1975-01-18");

BeaconUserName beaconUserName = new BeaconUserName()
    .givenName("Leslie")
    .familyName("Knope");

BeaconUserAddress beaconUserAddress = new BeaconUserAddress()
    .street("123 Main St.")
    .street2("Unit 42")
    .city("Pawnee")
    .region("IN")
    .postalCode("46001")
    .country("US");

BeaconUserRequestData beaconUserRequestData = new BeaconUserRequestData()
    .emailAddress("user@example.com")
    .dateOfBirth(dobBeacon)
    .name(beaconUserName)
    .address(beaconUserAddress);

BeaconUserCreateRequest beaconUserCreateRequest = new BeaconUserCreateRequest()
    .programId("becprg_11111111111111")
    .clientUserId("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d")
    .accessTokens(accessTokens)
    .user(beaconUserRequestData);

Response beaconResponse = client.beaconUserCreate(beaconUserCreateRequest).execute();

String statusValue = beaconResponse.body().getStatus().getValue();

```

```python
client = create_client()
request = BeaconUserCreateRequest(
    program_id='becprg_11111111111111',
    client_user_id='user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
    access_tokens=[access_token],
    user=BeaconUserRequestData(
        email_address='user@example.com',
        date_of_birth='1975-01-18',
        name=BeaconUserName(
            given_name='Leslie',
            family_name='Knope'
        ),
        address=BeaconUserAddress(
            street='123 Main St.',
            street2='Unit 42',
            city='Pawnee',
            region='IN',
            postal_code='46001',
            country='US'
        )
    )
)
response = client.beacon_user_create(request)
response.status.value

```

```go
user := plaid.NewBeaconUserRequestData(
  *plaid.NewBeaconUserName(
    "Leslie",
    "Knope",
  ),
)
user.SetEmailAddress("user@example.com")
user.SetDateOfBirth("1975-01-18")
user.SetAddress(
  *plaid.NewBeaconUserAddress(
    "123 Main St.",
    "Unit 42",
    "Pawnee",
    "IN",
    "46001",
    "US",
  ),
)

request := plaid.NewBeaconUserCreateRequest(
  "becprg_11111111111111",
  "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  *user,
)
request.SetAccessTokens(*accessTokens)

response, _, err := client.PlaidApi.
  BeaconUserCreate(ctx).
  BeaconUserCreateRequest(*request).
  Execute()

statusValue := response.GetStatus().GetValue()

```

#### Response fields 

\[string\]

An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.

string

ID of the associated Beacon User.

integer

The `version` field begins with 1 and increments each time the user is updated.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: `date-time`

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`

string

ID of the associated Beacon Program.

string

A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. 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`.

object

A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

object

The full name for a given Beacon User.

string

A string with at least one non-whitespace character, with a max length of 100 characters.

string

A string with at least one non-whitespace character, with a max length of 100 characters.

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

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.

nullable, 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.

string

City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.

nullable, string

A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field.

nullable, string

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

string

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

nullable, string

A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) .

Format: `email`

nullable, string

A phone number in E.164 format.

nullable, object

The ID number associated with a Beacon User.

string

Value of the identity document typed in by the user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

string

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

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`

nullable, string

An IPv4 or IPv6 address.

\[object\]

string

The last 2-4 numeric characters of this account's account number.

string

The routing number of the account.

string

An ISO8601 formatted timestamp.

Format: `date-time`

object

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

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`

nullable, 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`.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "item_ids": [
    "515cd85321d3649aecddc015"
  ],
  "id": "becusr_42cF1MNo42r9Xj",
  "version": 1,
  "created_at": "2020-07-24T03:26:02Z",
  "updated_at": "2020-07-24T03:26:02Z",
  "status": "cleared",
  "program_id": "becprg_11111111111111",
  "client_user_id": "your-db-id-3b24110",
  "user": {
    "date_of_birth": "1990-05-29",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "email_address": "user@example.com",
    "phone_number": "+19876543212",
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    },
    "ip_address": "192.0.2.42",
    "depository_accounts": [
      {
        "account_mask": "4000",
        "routing_number": "021000021",
        "added_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/user/get 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### 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.

#### Request fields 

required, string

ID of the associated Beacon User.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconUserGetRequest.new(
  {
    beacon_user_id: 'becusr_11111111111111'
  }
)
response = client.beacon_user_get(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/user/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_user_id": "becusr_11111111111111"
}'

```

```node
const request: BeaconUserGetRequest = {
  beacon_user_id: 'becusr_11111111111111',
};

try {
  const response = await plaidClient.beaconUserGet(request);
} catch (error) {
  // handle error
}

```

```java
BeaconUserGetRequest request = new BeaconUserGetRequest().beaconUserId("becusr_11111111111111");
Response response = client.beaconUserGet(request).execute();

```

```python
client = create_client()
request = BeaconUserGetRequest(beacon_user_id='becusr_11111111111111')
response = client.beacon_user_get(request)

```

```go
request := plaid.NewBeaconUserGetRequest("becusr_11111111111111")

response, _, err := client.PlaidApi.
    BeaconUserGet(ctx).
    BeaconUserGetRequest(*request).
    Execute()

```

#### Response fields 

\[string\]

An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.

string

ID of the associated Beacon User.

integer

The `version` field begins with 1 and increments each time the user is updated.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: `date-time`

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`

string

ID of the associated Beacon Program.

string

A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. 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`.

object

A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

object

The full name for a given Beacon User.

string

A string with at least one non-whitespace character, with a max length of 100 characters.

string

A string with at least one non-whitespace character, with a max length of 100 characters.

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

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.

nullable, 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.

string

City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.

nullable, string

A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field.

nullable, string

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

string

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

nullable, string

A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) .

Format: `email`

nullable, string

A phone number in E.164 format.

nullable, object

The ID number associated with a Beacon User.

string

Value of the identity document typed in by the user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

string

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

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`

nullable, string

An IPv4 or IPv6 address.

\[object\]

string

The last 2-4 numeric characters of this account's account number.

string

The routing number of the account.

string

An ISO8601 formatted timestamp.

Format: `date-time`

object

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

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`

nullable, 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`.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "item_ids": [
    "515cd85321d3649aecddc015"
  ],
  "id": "becusr_42cF1MNo42r9Xj",
  "version": 1,
  "created_at": "2020-07-24T03:26:02Z",
  "updated_at": "2020-07-24T03:26:02Z",
  "status": "cleared",
  "program_id": "becprg_11111111111111",
  "client_user_id": "your-db-id-3b24110",
  "user": {
    "date_of_birth": "1990-05-29",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "email_address": "user@example.com",
    "phone_number": "+19876543212",
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    },
    "ip_address": "192.0.2.42",
    "depository_accounts": [
      {
        "account_mask": "4000",
        "routing_number": "021000021",
        "added_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/user/update 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Update the identity data of a Beacon User 

Update the identity data for a Beacon User in your Beacon Program or add new accounts to the Beacon User.

Similar to [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , several checks are performed immediately when you submit an identity data change to [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) :

*   The user's updated PII 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 updated 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.

Plaid maintains a version history for each Beacon User, so the Beacon User's identity data before and after the update is retained as separate versions.

#### Request fields 

required, string

ID of the associated Beacon User.

object

A subset of a Beacon User's data which is used to patch the existing identity data associated with a Beacon User. At least one field must be provided. If left unset or null, user data will not be patched.

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

object

The full name for a given Beacon User.

required, string

A string with at least one non-whitespace character, with a max length of 100 characters.

required, string

A string with at least one non-whitespace character, with a max length of 100 characters.

object

Home address for the associated user. For more context on this field, see [Input Validation by Country](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#input-validation-by-country) .

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.

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.

required, string

City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.

string

A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field.

string

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

required, string

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

string

A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) .

Format: `email`

string

A phone number in E.164 format.

object

The ID number associated with a Beacon User.

required, string

Value of the identity document typed in by the user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

required, string

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

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`

string

An IPv4 or IPv6 address.

\[object\]

required, string

Must be a valid US Bank Account Number

required, string

The routing number of the account.

\[string\]

Send this array of access tokens to add accounts to this user for evaluation. This will add accounts to this Beacon User. If left null only existing accounts will be returned in response. A maximum of 50 accounts total can be added to a Beacon User.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconUserUpdateRequest.new(
  {
    beacon_user_id: 'becusr_11111111111111',
    user: Plaid::BeaconUserUpdateRequestData.new(
      {
        email_address: 'user@example.com',
        date_of_birth: '1975-01-18',
        name: Plaid::BeaconUserName.new(
          {
            given_name: 'Leslie',
            family_name: 'Knope'
          }
        ),
        address: Plaid::BeaconUserAddress.new(
          {
            street: '123 Main St.',
            street2: 'Unit 42',
            city: 'Pawnee',
            region: 'IN',
            postal_code: '46001',
            country: 'US'
          }
        )
      }
    )
  }
)
response = client.beacon_user_update(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/user/update \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_user_id": "becusr_11111111111111",
  "user": {
    "email_address": "user@example.com",
    "date_of_birth": "1975-01-18",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    }
  }
}'

```

```node
const request: BeaconUserUpdateRequest = {
  beacon_user_id: 'becusr_11111111111111',
  user: {
    email_address: 'user@example.com',
    date_of_birth: '1975-01-18',
    name: {
      given_name: 'Leslie',
      family_name: 'Knope',
    },
    address: {
      street: '123 Main St.',
      street2: 'Unit 42',
      city: 'Pawnee',
      region: 'IN',
      postal_code: '46001',
      country: 'US',
    },
  },
};

try {
  const response = await plaidClient.beaconUserUpdate(request);
  console.log(response.status.value);
} catch (error) {
  // handle error
}

```

```java
BeaconUserName beaconUserName = new BeaconUserName()
    .givenName("Leslie")
    .familyName("Knope");

BeaconUserAddress beaconUserAddress = new BeaconUserAddress()
    .street("123 Main St.")
    .street2("Unit 42")
    .city("Pawnee")
    .region("IN")
    .postalCode("46001")
    .country("US");

BeaconUserUpdateRequestData beaconUserUpdateRequestData = new BeaconUserUpdateRequestData()
    .emailAddress("user@example.com")
    .dateOfBirth("1975-01-18")
    .name(beaconUserName)
    .address(beaconUserAddress);

BeaconUserUpdateRequest beaconUserUpdateRequest = new BeaconUserUpdateRequest()
    .beaconUserId("becusr_11111111111111")
    .user(beaconUserUpdateRequestData);

Response beaconResponse = client.beaconUserUpdate(beaconUserUpdateRequest).execute();

// You can access the response data here
// For example:
// String statusValue = beaconResponse.body().getStatus().getValue();

```

```python
client = create_client()
request = BeaconUserUpdateRequest(
    beacon_user_id='becusr_11111111111111',
    user=BeaconUserUpdateRequestData(
        email_address='user@example.com',
        date_of_birth='1975-01-18',
        name=BeaconUserName(
            given_name='Leslie',
            family_name='Knope'
        ),
        address=BeaconUserAddress(
            street='123 Main St.',
            street2='Unit 42',
            city='Pawnee',
            region='IN',
            postal_code='46001',
            country='US'
        )
    )
)
response = client.beacon_user_update(request)

```

```go
user := plaid.NewBeaconUserUpdateRequestData()
user.SetEmailAddress("user@example.com")
user.SetDateOfBirth("1975-01-18")
user.SetName(
  *plaid.NewBeaconUserName(
    "Leslie",
    "Knope",
  ),
)
user.SetAddress(
  *plaid.NewBeaconUserAddress(
    "123 Main St.",
    "Unit 42",
    "Pawnee",
    "IN",
    "46001",
    "US",
  ),
)

request := plaid.NewBeaconUserUpdateRequest(
  "becusr_11111111111111",
)
request.SetUser(*user)

response, _, err := client.PlaidApi.
  BeaconUserUpdate(ctx).
  BeaconUserUpdateRequest(*request).
  Execute()

// You can access the response data here
// For example:
// statusValue := response.GetStatus().GetValue()

```

#### Response fields 

\[string\]

An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.

string

ID of the associated Beacon User.

integer

The `version` field begins with 1 and increments each time the user is updated.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: `date-time`

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`

string

ID of the associated Beacon Program.

string

A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. 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`.

object

A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

object

The full name for a given Beacon User.

string

A string with at least one non-whitespace character, with a max length of 100 characters.

string

A string with at least one non-whitespace character, with a max length of 100 characters.

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

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.

nullable, 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.

string

City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.

nullable, string

A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field.

nullable, string

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

string

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

nullable, string

A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) .

Format: `email`

nullable, string

A phone number in E.164 format.

nullable, object

The ID number associated with a Beacon User.

string

Value of the identity document typed in by the user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

string

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

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`

nullable, string

An IPv4 or IPv6 address.

\[object\]

string

The last 2-4 numeric characters of this account's account number.

string

The routing number of the account.

string

An ISO8601 formatted timestamp.

Format: `date-time`

object

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

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`

nullable, 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`.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "item_ids": [
    "515cd85321d3649aecddc015"
  ],
  "id": "becusr_42cF1MNo42r9Xj",
  "version": 1,
  "created_at": "2020-07-24T03:26:02Z",
  "updated_at": "2020-07-24T03:26:02Z",
  "status": "cleared",
  "program_id": "becprg_11111111111111",
  "client_user_id": "your-db-id-3b24110",
  "user": {
    "date_of_birth": "1990-05-29",
    "name": {
      "given_name": "Leslie",
      "family_name": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "region": "IN",
      "postal_code": "46001",
      "country": "US"
    },
    "email_address": "user@example.com",
    "phone_number": "+19876543212",
    "id_number": {
      "value": "123456789",
      "type": "us_ssn"
    },
    "ip_address": "192.0.2.42",
    "depository_accounts": [
      {
        "account_mask": "4000",
        "routing_number": "021000021",
        "added_at": "2020-07-24T03:26:02Z"
      }
    ]
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/user/account\_insights/get 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Get Account Insights for a Beacon User 

Get Account Insights for all Accounts linked to this Beacon User. The insights for each account are computed based on the information that was last retrieved from the financial institution.

#### Request fields 

required, string

ID of the associated Beacon User.

required, string

The access token associated with the Item for which data is being requested.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconUserAccountInsightsGetRequest.new(
  {
    beacon_user_id: 'becusr_11111111111111',
    access_token: 'access-sandbox-12345678',
    client_id: ENV['PLAID_CLIENT_ID'],
    secret: ENV['PLAID_SECRET']
  }
)
response = client.beacon_user_account_insights_get(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/user/account_insights/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_user_id": "becusr_11111111111111",
  "access_token": "access-sandbox-12345678"
}'

```

```node
const request: BeaconUserAccountInsightsGetRequest = {
  beacon_user_id: 'becusr_11111111111111',
  access_token: 'access-sandbox-12345678',
  client_id: process.env.PLAID_CLIENT_ID,
  secret: process.env.PLAID_SECRET,
};

try {
  const response = await plaidClient.beaconUserAccountInsightsGet(request);
  console.log(response.status.value);
} catch (error) {
  // handle error
}

```

```java
BeaconUserAccountInsightsGetRequest request = new BeaconUserAccountInsightsGetRequest()
    .beaconUserId("becusr_11111111111111")
    .accessToken("access-sandbox-12345678")
    .clientId(System.getenv("PLAID_CLIENT_ID"))
    .secret(System.getenv("PLAID_SECRET"));

Response response = client.beaconUserAccountInsightsGet(request).execute();

```

```python
client = create_client()
request = BeaconUserAccountInsightsGetRequest(
    beacon_user_id='becusr_11111111111111',
    access_token='access-sandbox-12345678',
    client_id=os.getenv('PLAID_CLIENT_ID'),
    secret=os.getenv('PLAID_SECRET')
)
response = client.beacon_user_account_insights_get(request)

```

```go
request := plaid.NewBeaconUserAccountInsightsGetRequest(
    "becusr_11111111111111",
    "access-sandbox-12345678",
)
request.SetClientId(os.Getenv("PLAID_CLIENT_ID"))
request.SetSecret(os.Getenv("PLAID_SECRET"))

response, _, err := client.PlaidApi.
    BeaconUserAccountInsightsGet(ctx).
    BeaconUserAccountInsightsGetRequest(*request).
    Execute()

statusValue := response.GetStatus().GetValue()

```

#### Response fields 

string

ID of the associated Beacon User.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: `date-time`

object

A collection of Bank Accounts linked to an Item that is associated with this Beacon User.

string

The Plaid Item ID the Bank Accounts belong to.

\[object\]

string

The Plaid `account_id`

string

`investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead.

`credit:` Credit card

`depository:` Depository account

`loan:` Loan account

`other:` Non-specified account type

See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes.

Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other`

nullable, string

See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes.

Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity`

object

The attributes object contains data that can be used to assess account risk. Examples of data include: `days_since_first_plaid_connection`: The number of days since the first time the Item was connected to an application via Plaid `plaid_connections_count_7d`: The number of times the Item has been connected to applications via Plaid over the past 7 days `plaid_connections_count_30d`: The number of times the Item has been connected to applications via Plaid over the past 30 days `total_plaid_connections_count`: The number of times the Item has been connected to applications via Plaid For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact sales or your Plaid account manager

nullable, integer

The number of days since the first time the Item was connected to an application via Plaid

nullable, boolean

Indicates if the account has been closed by the financial institution or the consumer, or is at risk of being closed

nullable, boolean

Indicates whether the account has withdrawals and transfers disabled or if access to the account is restricted. This could be due to a freeze by the credit issuer, legal restrictions (e.g., sanctions), or regulatory requirements limiting monthly withdrawals, among other reasons

nullable, integer

The total number of times the Item has been connected to applications via Plaid

nullable, integer

The number of times the Item has been connected to applications via Plaid over the past 7 days

nullable, integer

The number of times the Item has been connected to applications via Plaid over the past 30 days

nullable, integer

The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 3 days

nullable, integer

The number of non-OAuth authentication attempts via Plaid for this bank account over the past 3 days

nullable, integer

The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 7 days

nullable, integer

The number of non-OAuth authentication attempts via Plaid for this bank account over the past 7 days

nullable, integer

The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 30 days

nullable, integer

The number of non-OAuth authentication attempts via Plaid for this bank account over the past 30 days

nullable, integer

The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 3 days

nullable, integer

The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 7 days

nullable, integer

The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 30 days

nullable, integer

The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 90 days

nullable, integer

The number of distinct user agents linked to the same bank account during Plaid authentication in the last 3 days

nullable, integer

The number of distinct user agents linked to the same bank account during Plaid authentication in the last 7 days

nullable, integer

The number of distinct user agents linked to the same bank account during Plaid authentication in the last 30 days

nullable, integer

The number of distinct user agents linked to the same bank account during Plaid authentication in the last 90 days

nullable, integer

The number of times the account's addresses on file have changed over the past 28 days

nullable, integer

The number of times the account's email addresses on file have changed over the past 28 days

nullable, integer

The number of times the account's phone numbers on file have changed over the past 28 days

nullable, integer

The number of times the account's addresses on file have changed over the past 90 days

nullable, integer

The number of times the account's email addresses on file have changed over the past 90 days

nullable, integer

The number of times the account's phone numbers on file have changed over the past 90 days

nullable, integer

The number of days since the bank account was opened, as reported by the financial institution

nullable, integer

The number of days since the oldest transaction available to Plaid for this account. This measure, combined with Plaid connection history, can be used to infer the age of the account

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "created_at": "2020-07-24T03:26:02Z",
  "updated_at": "2020-07-24T03:26:02Z",
  "bank_account_insights": {
    "item_id": "515cd85321d3649aecddc015",
    "accounts": [
      {
        "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
        "type": "depository",
        "subtype": "checking",
        "attributes": {
          "days_since_first_plaid_connection": 1,
          "is_account_closed": false,
          "is_account_frozen_or_restricted": false,
          "total_plaid_connections_count": 1,
          "plaid_connections_count_7d": 1,
          "plaid_connections_count_30d": 1,
          "failed_plaid_non_oauth_authentication_attempts_count_3d": 1,
          "plaid_non_oauth_authentication_attempts_count_3d": 1,
          "failed_plaid_non_oauth_authentication_attempts_count_7d": 1,
          "plaid_non_oauth_authentication_attempts_count_7d": 1,
          "failed_plaid_non_oauth_authentication_attempts_count_30d": 1,
          "plaid_non_oauth_authentication_attempts_count_30d": 1,
          "distinct_ip_addresses_count_3d": 1,
          "distinct_ip_addresses_count_7d": 1,
          "distinct_ip_addresses_count_30d": 1,
          "distinct_ip_addresses_count_90d": 1,
          "distinct_user_agents_count_3d": 1,
          "distinct_user_agents_count_7d": 1,
          "distinct_user_agents_count_30d": 1,
          "distinct_user_agents_count_90d": 1,
          "address_change_count_28d": 1,
          "email_change_count_28d": 2,
          "phone_change_count_28d": 1,
          "address_change_count_90d": 3,
          "email_change_count_90d": 4,
          "phone_change_count_90d": 2,
          "days_since_account_opening": 365,
          "days_since_first_observed_transaction": 180
        }
      }
    ]
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/user/history/list 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### List a Beacon User's history 

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

#### Request fields 

required, string

ID of the associated Beacon User.

string

An identifier that determines which page of results you receive.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconUserHistoryListRequest.new(
  {
    beacon_user_id: 'becusr_11111111111111'
  }
)
response = client.beacon_user_history_list(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/user/history/list \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_user_id": "becusr_11111111111111"
}'

```

```node
const request: BeaconUserHistoryListRequest = {
  beacon_user_id: 'becusr_11111111111111',
};

try {
  const response = await plaidClient.beaconUserHistoryList(request);
} catch (error) {
  // handle error
}

```

```java
BeaconUserHistoryListRequest request = new BeaconUserHistoryListRequest().beaconUserId("becusr_11111111111111");
Response response = client.beaconUserHistoryList(request).execute();

```

```python
client = create_client()
request = BeaconUserHistoryListRequest(beacon_user_id='becusr_11111111111111')
response = client.beacon_user_history_list(request)

```

```go
request := plaid.NewBeaconUserHistoryListRequest("becusr_11111111111111")

response, _, err := client.PlaidApi.
    BeaconUserHistoryList(ctx).
    BeaconUserHistoryListRequest(*request).
    Execute()

```

#### Response fields 

\[object\]

\[string\]

An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.

string

ID of the associated Beacon User.

integer

The `version` field begins with 1 and increments each time the user is updated.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.

Format: `date-time`

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`

string

ID of the associated Beacon Program.

string

A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. 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`.

object

A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

object

The full name for a given Beacon User.

string

A string with at least one non-whitespace character, with a max length of 100 characters.

string

A string with at least one non-whitespace character, with a max length of 100 characters.

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

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.

nullable, 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.

string

City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.

nullable, string

A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field.

nullable, string

The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.

string

Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.

nullable, string

A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) .

Format: `email`

nullable, string

A phone number in E.164 format.

nullable, object

The ID number associated with a Beacon User.

string

Value of the identity document typed in by the user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

string

A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) .

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`

nullable, string

An IPv4 or IPv6 address.

\[object\]

string

The last 2-4 numeric characters of this account's account number.

string

The routing number of the account.

string

An ISO8601 formatted timestamp.

Format: `date-time`

object

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

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`

nullable, 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`.

string

An ISO8601 formatted timestamp.

Format: `date-time`

nullable, string

An identifier that determines which page of results you receive.

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "beacon_users": [
    {
      "item_ids": [
        "515cd85321d3649aecddc015"
      ],
      "id": "becusr_42cF1MNo42r9Xj",
      "version": 1,
      "created_at": "2020-07-24T03:26:02Z",
      "updated_at": "2020-07-24T03:26:02Z",
      "status": "cleared",
      "program_id": "becprg_11111111111111",
      "client_user_id": "your-db-id-3b24110",
      "user": {
        "date_of_birth": "1990-05-29",
        "name": {
          "given_name": "Leslie",
          "family_name": "Knope"
        },
        "address": {
          "street": "123 Main St.",
          "street2": "Unit 42",
          "city": "Pawnee",
          "region": "IN",
          "postal_code": "46001",
          "country": "US"
        },
        "email_address": "user@example.com",
        "phone_number": "+19876543212",
        "id_number": {
          "value": "123456789",
          "type": "us_ssn"
        },
        "ip_address": "192.0.2.42",
        "depository_accounts": [
          {
            "account_mask": "4000",
            "routing_number": "021000021",
            "added_at": "2020-07-24T03:26:02Z"
          }
        ]
      },
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report/create 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Create a Beacon Report 

Create a fraud report for a given Beacon User.

#### Request fields 

required, string

ID of the associated Beacon User.

required, 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`

required, string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

object

The amount and currency of the fraud or attempted fraud. `fraud_amount` should be omitted to indicate an unknown fraud amount.

required, string

An ISO-4217 currency code.

Possible values: `USD`

required, 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`

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconReportCreateRequest.new(
  {
    beacon_user_id: 'becusr_11111111111111',
    type: Plaid::BeaconReportType::FIRST_PARTY,
    fraud_date: '1975-01-18'
  }
)
response = client.beacon_report_create(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/report/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_user_id": "becusr_11111111111111",
  "type": "first_party",
  "fraud_date": "1975-01-18"
}'

```

```node
const request: BeaconReportCreateRequest = {
  beacon_user_id: 'becusr_11111111111111',
  type: 'first_party',
  fraud_date: '1975-01-18',
};

try {
  const response = await plaidClient.beaconReportCreate(request);
} catch (error) {
  // handle error
}

```

```java
Client client = createClient();
BeaconReportType reportType = BeaconReportType.FIRST_PARTY;
BeaconReportCreateRequest request = new BeaconReportCreateRequest()
    .beaconUserId("becusr_11111111111111")
    .type(reportType)
    .fraudDate("1975-01-18");
Response response = client.beaconReportCreate(request).execute();

```

```python
client = create_client()
request = BeaconReportCreateRequest(
    beacon_user_id='becusr_11111111111111',
    type=BeaconReportType('first_party'),
    fraud_date='1975-01-18'
)
response = client.beacon_report_create(request)

```

```go
request := plaid.NewBeaconReportCreateRequest(
    "becusr_11111111111111",
    plaid.BEACONREPORTTYPE_FIRST_PARTY,
    "1975-01-18",
)

response, _, err := client.PlaidApi.
    BeaconReportCreate(ctx).
    BeaconReportCreateRequest(*request).
    Execute()

```

#### Response fields 

string

ID of the associated Beacon Report.

string

ID of the associated Beacon User.

string

An ISO8601 formatted timestamp.

Format: `date-time`

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.

`data_breach`: If this individual's data was compromised in a breach.

`unknown`: If you aren't sure who committed the fraud.

Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown`

nullable, string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

nullable, object

The amount and currency of the fraud or attempted fraud. `fraud_amount` should be omitted to indicate an unknown fraud amount.

string

An ISO-4217 currency code.

Possible values: `USD`

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`

object

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

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`

nullable, 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`.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "id": "becrpt_11111111111111",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "created_at": "2020-07-24T03:26:02Z",
  "type": "first_party",
  "fraud_date": "1990-05-29",
  "event_date": "1990-05-29",
  "fraud_amount": {
    "iso_currency_code": "USD",
    "value": 100
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report/get 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Get a Beacon Report 

Returns a Beacon Report for a given Beacon Report ID.

#### Request fields 

required, string

ID of the associated Beacon Report.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconReportGetRequest.new(
  {
    beacon_report_id: 'becrpt_11111111111111'
  }
)
response = client.beacon_report_get(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/report/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_report_id": "becrpt_11111111111111"
}'

```

```node
const request: BeaconReportGetRequest = {
  beacon_report_id: 'becrpt_11111111111111',
};

try {
  const response = await plaidClient.beaconReportGet(request);
} catch (error) {
  // handle error
}

```

```java
BeaconReportGetRequest request = new BeaconReportGetRequest()
    .beaconReportId("becrpt_11111111111111");
Response response = client.beaconReportGet(request).execute();

```

```python
client = create_client()
request = BeaconReportGetRequest(
    beacon_report_id='becrpt_11111111111111'
)
response = client.beacon_report_get(request)

```

```go
request := plaid.NewBeaconReportGetRequest("becrpt_11111111111111")

response, _, err := client.PlaidApi.
    BeaconReportGet(ctx).
    BeaconReportGetRequest(*request).
    Execute()

```

#### Response fields 

string

ID of the associated Beacon Report.

string

ID of the associated Beacon User.

string

An ISO8601 formatted timestamp.

Format: `date-time`

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.

`data_breach`: If this individual's data was compromised in a breach.

`unknown`: If you aren't sure who committed the fraud.

Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown`

nullable, string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

nullable, object

The amount and currency of the fraud or attempted fraud. `fraud_amount` should be omitted to indicate an unknown fraud amount.

string

An ISO-4217 currency code.

Possible values: `USD`

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`

object

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

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`

nullable, 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`.

string

An ISO8601 formatted timestamp.

Format: `date-time`

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "id": "becrpt_11111111111111",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "created_at": "2020-07-24T03:26:02Z",
  "type": "first_party",
  "fraud_date": "1990-05-29",
  "event_date": "1990-05-29",
  "fraud_amount": {
    "iso_currency_code": "USD",
    "value": 100
  },
  "audit_trail": {
    "source": "dashboard",
    "dashboard_user_id": "54350110fedcbaf01234ffee",
    "timestamp": "2020-07-24T03:26:02Z"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report/list 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### List Beacon Reports for a Beacon User 

Use the [/beacon/report/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportlist) 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.

#### Request fields 

required, string

ID of the associated Beacon User.

string

An identifier that determines which page of results you receive.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconReportListRequest.new(
  {
    beacon_user_id: 'becusr_11111111111111'
  }
)
response = client.beacon_report_list(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/report/list \
-H 'Content-Type: application/json' \
-d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "secret": "${PLAID_SECRET}",
    "beacon_user_id": "becusr_11111111111111"
}'

```

```node
const request: BeaconReportListRequest = {
  beacon_user_id: 'becusr_11111111111111',
};

try {
  const response = await plaidClient.beaconReportList(request);
} catch (error) {
  // handle error
}

```

```java
Client client = createClient();
BeaconReportListRequest request = new BeaconReportListRequest()
    .beaconUserId("becusr_11111111111111");
Response response = client.beaconReportList(request).execute();

```

```python
client = create_client()
request = BeaconReportListRequest(
    beacon_user_id='becusr_11111111111111'
)
response = client.beacon_report_list(request)

```

```go
request := plaid.NewBeaconReportListRequest(
    "becusr_11111111111111",
)

response, _, err := client.PlaidApi.
    BeaconReportList(ctx).
    BeaconReportListRequest(*request).
    Execute()

```

#### Response fields 

\[object\]

string

ID of the associated Beacon Report.

string

ID of the associated Beacon User.

string

An ISO8601 formatted timestamp.

Format: `date-time`

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.

`data_breach`: If this individual's data was compromised in a breach.

`unknown`: If you aren't sure who committed the fraud.

Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown`

nullable, string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

nullable, object

The amount and currency of the fraud or attempted fraud. `fraud_amount` should be omitted to indicate an unknown fraud amount.

string

An ISO-4217 currency code.

Possible values: `USD`

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`

object

Information about the last change made to the parent object specifying what caused the change as well as when it occurred.

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`

nullable, 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`.

string

An ISO8601 formatted timestamp.

Format: `date-time`

nullable, string

An identifier that determines which page of results you receive.

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "beacon_reports": [
    {
      "id": "becrpt_11111111111111",
      "beacon_user_id": "becusr_42cF1MNo42r9Xj",
      "created_at": "2020-07-24T03:26:02Z",
      "type": "first_party",
      "fraud_date": "1990-05-29",
      "event_date": "1990-05-29",
      "fraud_amount": {
        "iso_currency_code": "USD",
        "value": 100
      },
      "audit_trail": {
        "source": "dashboard",
        "dashboard_user_id": "54350110fedcbaf01234ffee",
        "timestamp": "2020-07-24T03:26:02Z"
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report\_syndication/get 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### Get a Beacon Report Syndication 

Returns a Beacon Report Syndication for a given Beacon Report Syndication id.

#### Request fields 

required, string

ID of the associated Beacon Report Syndication.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconReportSyndicationGetRequest.new(
  {
    beacon_report_syndication_id: 'becrsn_11111111111111'
  }
)
response = client.beacon_report_syndication_get(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/report_syndication/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_report_syndication_id": "becrsn_11111111111111"
}'

```

```node
const request: BeaconReportSyndicationGetRequest = {
  beacon_report_syndication_id: 'becrsn_11111111111111',
};

try {
  const response = await plaidClient.beaconReportSyndicationGet(request);
} catch (error) {
  // handle error
}

```

```java
BeaconReportSyndicationGetRequest request = new BeaconReportSyndicationGetRequest()
    .beaconReportSyndicationId("becrsn_11111111111111");
Response response = client.beaconReportSyndicationGet(request).execute();

```

```go
request := plaid.NewBeaconReportSyndicationGetRequest("becrsn_11111111111111")

response, _, err := client.PlaidApi.
    BeaconReportSyndicationGet(ctx).
    BeaconReportSyndicationGetRequest(*request).
    Execute()

```

```python
client = create_client()
request = BeaconReportSyndicationGetRequest(
    beacon_report_syndication_id='becrsn_11111111111111'
)
response = client.beacon_report_syndication_get(request)

```

#### Response fields 

string

ID of the associated Beacon Report Syndication.

string

ID of the associated Beacon User.

object

A subset of information from a Beacon Report that has been syndicated to a matching Beacon User in your program.

The `id` field in the response is the ID of the original report that was syndicated. If the original report was created by your organization, the field will be filled with the ID of the report. Otherwise, the field will be `null` indicating that the original report was created by another Beacon customer.

nullable, string

ID of the associated Beacon Report.

string

An ISO8601 formatted timestamp.

Format: `date-time`

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.

`data_breach`: If this individual's data was compromised in a breach.

`unknown`: If you aren't sure who committed the fraud.

Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown`

nullable, string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

object

Analysis of which fields matched between the originally reported Beacon User and the Beacon User that the report was syndicated to.

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`

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`

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`

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`

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`

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`

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`

\[object\]

string

The last 2-4 numeric characters of this account's account number.

string

The routing number of the account.

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`

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "id": "becrsn_11111111111111",
  "beacon_user_id": "becusr_42cF1MNo42r9Xj",
  "report": {
    "id": "becrpt_11111111111111",
    "created_at": "2020-07-24T03:26:02Z",
    "type": "first_party",
    "fraud_date": "1990-05-29",
    "event_date": "1990-05-29"
  },
  "analysis": {
    "address": "match",
    "date_of_birth": "match",
    "email_address": "match",
    "name": "match",
    "id_number": "match",
    "ip_address": "match",
    "phone_number": "match",
    "depository_accounts": [
      {
        "account_mask": "4000",
        "routing_number": "021000021",
        "match_status": "match"
      }
    ]
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/report\_syndication/list 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### List Beacon Report Syndications for a Beacon User 

Use the [/beacon/report\_syndication/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationlist) endpoint to view all Beacon Reports that have been syndicated to a specific Beacon User. This endpoint returns Beacon Report Syndications which are references to Beacon Reports created either by you, or another Beacon customer, that matched the specified Beacon User. A Beacon User can have multiple active Beacon Report Syndications at once. 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.

#### Request fields 

required, string

ID of the associated Beacon User.

string

An identifier that determines which page of results you receive.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconReportSyndicationListRequest.new(
  {
    beacon_user_id: 'becusr_11111111111111'
  }
)
response = client.beacon_report_syndication_list(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/report_syndication/list \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_user_id": "becusr_11111111111111"
}'

```

```node
const request: BeaconReportSyndicationListRequest = {
  beacon_user_id: 'becusr_11111111111111',
};

try {
  const response = await plaidClient.beaconReportSyndicationList(request);
} catch (error) {
  // handle error
}

```

```java
BeaconReportSyndicationListRequest request = new BeaconReportSyndicationListRequest()
    .beaconUserId("becusr_11111111111111");
Response response = client.beaconReportSyndicationList(request).execute();

```

```go
request := plaid.NewBeaconReportSyndicationListRequest(
    "becusr_11111111111111",
)

response, _, err := client.PlaidApi.
    BeaconReportSyndicationList(ctx).
    BeaconReportSyndicationListRequest(*request).
    Execute()

```

```python
client = create_client()
request = BeaconReportSyndicationListRequest(
    beacon_user_id='becusr_11111111111111'
)
response = client.beacon_report_syndication_list(request)

```

#### Response fields 

\[object\]

string

ID of the associated Beacon Report Syndication.

string

ID of the associated Beacon User.

object

A subset of information from a Beacon Report that has been syndicated to a matching Beacon User in your program.

The `id` field in the response is the ID of the original report that was syndicated. If the original report was created by your organization, the field will be filled with the ID of the report. Otherwise, the field will be `null` indicating that the original report was created by another Beacon customer.

nullable, string

ID of the associated Beacon Report.

string

An ISO8601 formatted timestamp.

Format: `date-time`

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.

`data_breach`: If this individual's data was compromised in a breach.

`unknown`: If you aren't sure who committed the fraud.

Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown`

nullable, string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

string

A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

Format: `date`

object

Analysis of which fields matched between the originally reported Beacon User and the Beacon User that the report was syndicated to.

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`

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`

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`

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`

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`

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`

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`

\[object\]

string

The last 2-4 numeric characters of this account's account number.

string

The routing number of the account.

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`

nullable, string

An identifier that determines which page of results you receive.

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "beacon_report_syndications": [
    {
      "id": "becrsn_11111111111111",
      "beacon_user_id": "becusr_42cF1MNo42r9Xj",
      "report": {
        "id": "becrpt_11111111111111",
        "created_at": "2020-07-24T03:26:02Z",
        "type": "first_party",
        "fraud_date": "1990-05-29",
        "event_date": "1990-05-29"
      },
      "analysis": {
        "address": "match",
        "date_of_birth": "match",
        "email_address": "match",
        "name": "match",
        "id_number": "match",
        "ip_address": "match",
        "phone_number": "match",
        "depository_accounts": [
          {
            "account_mask": "4000",
            "routing_number": "021000021",
            "match_status": "match"
          }
        ]
      }
    }
  ],
  "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
  "request_id": "saKrIBuEB9qJZng"
}
```

\=\*=\*=\*=

#### /beacon/duplicate/get 

This feature is 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](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) .

#### 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`.

#### Request fields 

required, string

ID of the associated Beacon Duplicate.

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.

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.

```ruby
client = create_client()
request = Plaid::BeaconDuplicateGetRequest.new(
  {
    beacon_duplicate_id: 'becdup_11111111111111'
  }
)
response = client.beacon_duplicate_get(request)

```

```bash
curl -X POST https://sandbox.plaid.com/beacon/duplicate/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "beacon_duplicate_id": "becdup_11111111111111"
}'

```

```node
const request: BeaconDuplicateGetRequest = {
  beacon_duplicate_id: 'becdup_11111111111111',
};

try {
  const response = await plaidClient.beaconDuplicateGet(request);
} catch (error) {
  // handle error
}

```

```java
Client client = createClient();
BeaconDuplicateGetRequest request = new BeaconDuplicateGetRequest().beaconDuplicateId("becdup_11111111111111");
Response response = client.beaconDuplicateGet(request).execute();

```

```python
client = create_client()
request = BeaconDuplicateGetRequest(beacon_duplicate_id='becdup_11111111111111')
response = client.beacon_duplicate_get(request)

```

```go
request := plaid.NewBeaconDuplicateGetRequest("becdup_11111111111111")

response, _, err := client.PlaidApi.
    BeaconDuplicateGet(ctx).
    BeaconDuplicateGetRequest(*request).
    Execute()

```

#### Response fields 

string

ID of the associated Beacon Duplicate.

object

A Beacon User Revision identifies a Beacon User at some point in its revision history.

string

ID of the associated Beacon User.

integer

The `version` field begins with 1 and increments with each subsequent revision.

object

A Beacon User Revision identifies a Beacon User at some point in its revision history.

string

ID of the associated Beacon User.

integer

The `version` field begins with 1 and increments with each subsequent revision.

object

Analysis of which fields matched between one Beacon User and another.

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`

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`

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`

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`

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`

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`

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`

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object

```json
{
  "id": "becdup_11111111111111",
  "beacon_user1": {
    "id": "becusr_42cF1MNo42r9Xj",
    "version": 1
  },
  "beacon_user2": {
    "id": "becusr_42cF1MNo42r9Xj",
    "version": 1
  },
  "analysis": {
    "address": "match",
    "date_of_birth": "match",
    "email_address": "match",
    "name": "match",
    "id_number": "match",
    "ip_address": "match",
    "phone_number": "match"
  },
  "request_id": "saKrIBuEB9qJZng"
}
```

### 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.

#### Properties 

string

`BEACON`

string

`USER_STATUS_UPDATED`

string

The ID of the associated Beacon user.

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "USER_STATUS_UPDATED",
  "beacon_user_id": "becusr_4WciCrtbxF76T8",
  "environment": "production"
}
```

\=\*=\*=\*=

#### REPORT\_CREATED 

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

#### Properties 

string

`BEACON`

string

`REPORT_CREATED`

string

The ID of the associated Beacon Report.

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "REPORT_CREATED",
  "beacon_report_id": "becrpt_2zugxV6hWQZG91",
  "environment": "production"
}
```

\=\*=\*=\*=

#### REPORT\_UPDATED 

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

#### Properties 

string

`BEACON`

string

`REPORT_UPDATED`

string

The ID of the associated Beacon Report.

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "REPORT_UPDATED",
  "beacon_report_id": "becrpt_2zugxV6hWQZG91",
  "environment": "production"
}
```

\=\*=\*=\*=

#### REPORT\_SYNDICATION\_CREATED 

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

#### Properties 

string

`BEACON`

string

`REPORT_SYNDICATION_CREATED`

string

The ID of the associated Beacon Report Syndication.

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "REPORT_SYNDICATION_CREATED",
  "beacon_report_syndication_id": "becrsn_eZPgiiv3JH8rfT",
  "environment": "production"
}
```

\=\*=\*=\*=

#### DUPLICATE\_DETECTED 

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

#### Properties 

string

`BEACON`

string

`DUPLICATE_DETECTED`

string

The ID of the associated Beacon Duplicate.

string

The Plaid environment the webhook was sent from

Possible values: `sandbox`, `production`

API Object

```json
{
  "webhook_type": "BEACON",
  "webhook_code": "DUPLICATE_DETECTED",
  "beacon_duplicate_id": "becdup_erJcFn97r9sugZ",
  "environment": "production"
}
```