Plaid logo
Docs
ALL DOCS

API

  • Overview
  • Libraries
  • API versioning
  • Postman Collection
  • Webhooks
Payments and Funding
  • Auth
  • Balance
  • Identity
  • Signal
  • Transfer
  • Investments Move
  • Payment Initiation
  • Virtual Accounts
Financial Insights
  • Transactions
  • Investments
  • Liabilities
  • Enrich
KYC/AML and anti-fraud
  • Look up Dashboard users
  • Identity Verification
  • Monitor
  • Beacon (beta)
Instant Onboarding
  • Layer
Credit and Underwriting
  • Consumer Report (by Plaid Check)
  • Assets
  • Statements
  • Income
Fundamentals
  • Items
  • Accounts
  • Institutions
  • Sandbox
  • Link
  • Users
  • Consent
  • Network
  • OAuth
Partnerships
  • Processor tokens
  • Processor partners
  • Reseller partners
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
    Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
    Plaid.com
    Log in
    Get API Keys
    Open nav

    Beacon

    API reference for Beacon endpoints and webhooks

    Add and report users on the Plaid Beacon network.

    Endpoints
    /beacon/user/createCreate and scan a Beacon User against a Beacon Program
    /beacon/user/getFetch a Beacon User
    /beacon/user/updateUpdate and rescan a Beacon User
    /beacon/user/account_insights/getFetch a Beacon User's account insights
    /beacon/user/history/listList a Beacon User's history
    /beacon/report/createCreate a fraud report for a given Beacon User
    /beacon/report/getFetch a Beacon Report
    /beacon/report/listList Beacon Reports for a given Beacon User
    /beacon/report_syndication/getFetch a Beacon Report Syndication
    /beacon/report_syndication/listList Beacon Report Syndications for a given Beacon User
    /beacon/duplicate/getFetch a Beacon duplicate
    See also
    /dashboard_user/getRetrieve information about a dashboard user
    /dashboard_user/listList dashboard users
    Webhooks
    USER_STATUS_UPDATEDBeacon User status has changed
    REPORT_CREATEDBeacon Report has been created
    REPORT_UPDATEDBeacon Report has been updated
    REPORT_SYNDICATION_CREATEDNew Network Report matches one of your Users
    DUPLICATE_DETECTEDDuplicate Beacon User was created

    /beacon/user/create

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

    Create a Beacon User

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

    beacon/user/create

    Request fields

    program_id
    requiredstringrequired, string
    ID of the associated Beacon Program.
    client_user_id
    requiredstringrequired, string
    A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.
    user
    requiredobjectrequired, 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.
    date_of_birth
    stringstring
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

    Format: date
    name
    requiredobjectrequired, object
    The full name for a given Beacon User.
    given_name
    requiredstringrequired, string
    A string with at least one non-whitespace character, with a max length of 100 characters.
    family_name
    requiredstringrequired, string
    A string with at least one non-whitespace character, with a max length of 100 characters.
    address
    objectobject
    Home address for the associated user. For more context on this field, see Input Validation by Country.
    street
    requiredstringrequired, string
    The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.
    street2
    stringstring
    Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.
    city
    requiredstringrequired, string
    City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."
    region
    stringstring
    An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
    postal_code
    stringstring
    The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
    country
    requiredstringrequired, string
    Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    email_address
    stringstring
    A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696.

    Format: email
    phone_number
    stringstring
    A phone number in E.164 format.
    id_number
    objectobject
    The ID number associated with a Beacon User.
    value
    requiredstringrequired, string
    Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.
    type
    requiredstringrequired, string
    A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

    Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
    ip_address
    stringstring
    An IPv4 or IPV6 address.
    depository_accounts
    [object][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.
    account_number
    requiredstringrequired, string
    Must be a valid US Bank Account Number
    routing_number
    requiredstringrequired, string
    The routing number of the account.
    access_tokens
    [string][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.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconUserCreateRequest = {
    2 program_id: 'becprg_11111111111111',
    3 client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
    4 access_tokens: [access_token],
    5 user: {
    6 email_address: 'user@example.com',
    7 date_of_birth: '1975-01-18',
    8 name: {
    9 given_name: 'Leslie',
    10 family_name: 'Knope',
    11 },
    12 address: {
    13 street: '123 Main St.',
    14 street2: 'Unit 42',
    15 city: 'Pawnee',
    16 region: 'IN',
    17 postal_code: '46001',
    18 country: 'US',
    19 },
    20 },
    21};
    22
    23try {
    24 const response = await plaidClient.beaconUserCreate(request);
    25 console.log(response.status.value);
    26} catch (error) {
    27 // handle error
    28}
    beacon/user/create

    Response fields and example

    item_ids
    [string][string]
    An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.
    id
    stringstring
    ID of the associated Beacon User.
    version
    integerinteger
    The version field begins with 1 and increments each time the user is updated.
    created_at
    stringstring
    An ISO8601 formatted timestamp.

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

    Format: date-time
    status
    stringstring
    A status of a Beacon User.
    rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected.
    pending_review: The Beacon User has been marked for review.
    cleared: The Beacon User has been cleared of fraud.


    Possible values: rejected, pending_review, cleared
    program_id
    stringstring
    ID of the associated Beacon Program.
    client_user_id
    stringstring
    A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.
    user
    objectobject
    A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
    date_of_birth
    stringstring
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

    Format: date
    name
    objectobject
    The full name for a given Beacon User.
    given_name
    stringstring
    A string with at least one non-whitespace character, with a max length of 100 characters.
    family_name
    stringstring
    A string with at least one non-whitespace character, with a max length of 100 characters.
    address
    objectobject
    Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
    Addresses from the United Kingdom will not include a region
    Addresses from Hong Kong will not include a postal code
    street
    stringstring
    The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.
    street2
    nullablestringnullable, string
    Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.
    city
    stringstring
    City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."
    region
    nullablestringnullable, string
    An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
    postal_code
    nullablestringnullable, string
    The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
    country
    stringstring
    Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    email_address
    nullablestringnullable, string
    A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696.

    Format: email
    phone_number
    nullablestringnullable, string
    A phone number in E.164 format.
    id_number
    nullableobjectnullable, object
    The ID number associated with a Beacon User.
    value
    stringstring
    Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.
    type
    stringstring
    A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

    Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
    ip_address
    nullablestringnullable, string
    An IPv4 or IPV6 address.
    depository_accounts
    [object][object]
    account_mask
    stringstring
    The last 2-4 numeric characters of this account’s account number.
    routing_number
    stringstring
    The routing number of the account.
    added_at
    stringstring
    An ISO8601 formatted timestamp.

    Format: date-time
    audit_trail
    objectobject
    Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    source
    stringstring
    A type indicating what caused a resource to be changed or updated.
    dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
    api - The resource was created or updated via the Plaid API.
    system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
    bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.


    Possible values: dashboard, api, system, bulk_import
    dashboard_user_id
    nullablestringnullable, string
    ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard_user/get.
    timestamp
    stringstring
    An ISO8601 formatted timestamp.

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

    /beacon/user/get

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

    Get a Beacon User

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

    beacon/user/get

    Request fields

    beacon_user_id
    requiredstringrequired, string
    ID of the associated Beacon User.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconUserGetRequest = {
    2 beacon_user_id: 'becusr_11111111111111',
    3};
    4
    5try {
    6 const response = await plaidClient.beaconUserGet(request);
    7} catch (error) {
    8 // handle error
    9}
    beacon/user/get

    Response fields and example

    item_ids
    [string][string]
    An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.
    id
    stringstring
    ID of the associated Beacon User.
    version
    integerinteger
    The version field begins with 1 and increments each time the user is updated.
    created_at
    stringstring
    An ISO8601 formatted timestamp.

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

    Format: date-time
    status
    stringstring
    A status of a Beacon User.
    rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected.
    pending_review: The Beacon User has been marked for review.
    cleared: The Beacon User has been cleared of fraud.


    Possible values: rejected, pending_review, cleared
    program_id
    stringstring
    ID of the associated Beacon Program.
    client_user_id
    stringstring
    A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.
    user
    objectobject
    A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
    date_of_birth
    stringstring
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

    Format: date
    name
    objectobject
    The full name for a given Beacon User.
    given_name
    stringstring
    A string with at least one non-whitespace character, with a max length of 100 characters.
    family_name
    stringstring
    A string with at least one non-whitespace character, with a max length of 100 characters.
    address
    objectobject
    Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
    Addresses from the United Kingdom will not include a region
    Addresses from Hong Kong will not include a postal code
    street
    stringstring
    The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.
    street2
    nullablestringnullable, string
    Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.
    city
    stringstring
    City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."
    region
    nullablestringnullable, string
    An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
    postal_code
    nullablestringnullable, string
    The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
    country
    stringstring
    Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    email_address
    nullablestringnullable, string
    A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696.

    Format: email
    phone_number
    nullablestringnullable, string
    A phone number in E.164 format.
    id_number
    nullableobjectnullable, object
    The ID number associated with a Beacon User.
    value
    stringstring
    Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.
    type
    stringstring
    A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

    Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
    ip_address
    nullablestringnullable, string
    An IPv4 or IPV6 address.
    depository_accounts
    [object][object]
    account_mask
    stringstring
    The last 2-4 numeric characters of this account’s account number.
    routing_number
    stringstring
    The routing number of the account.
    added_at
    stringstring
    An ISO8601 formatted timestamp.

    Format: date-time
    audit_trail
    objectobject
    Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    source
    stringstring
    A type indicating what caused a resource to be changed or updated.
    dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
    api - The resource was created or updated via the Plaid API.
    system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
    bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.


    Possible values: dashboard, api, system, bulk_import
    dashboard_user_id
    nullablestringnullable, string
    ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard_user/get.
    timestamp
    stringstring
    An ISO8601 formatted timestamp.

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

    /beacon/user/update

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

    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, several checks are performed immediately when you submit an identity data change to /beacon/user/update:
    - 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.

    beacon/user/update

    Request fields

    beacon_user_id
    requiredstringrequired, string
    ID of the associated Beacon User.
    user
    objectobject
    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.
    date_of_birth
    stringstring
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

    Format: date
    name
    objectobject
    The full name for a given Beacon User.
    given_name
    requiredstringrequired, string
    A string with at least one non-whitespace character, with a max length of 100 characters.
    family_name
    requiredstringrequired, string
    A string with at least one non-whitespace character, with a max length of 100 characters.
    address
    objectobject
    Home address for the associated user. For more context on this field, see Input Validation by Country.
    street
    requiredstringrequired, string
    The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.
    street2
    stringstring
    Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.
    city
    requiredstringrequired, string
    City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."
    region
    stringstring
    An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
    postal_code
    stringstring
    The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
    country
    requiredstringrequired, string
    Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    email_address
    stringstring
    A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696.

    Format: email
    phone_number
    stringstring
    A phone number in E.164 format.
    id_number
    objectobject
    The ID number associated with a Beacon User.
    value
    requiredstringrequired, string
    Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.
    type
    requiredstringrequired, string
    A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

    Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
    ip_address
    stringstring
    An IPv4 or IPV6 address.
    depository_accounts
    [object][object]
    account_number
    requiredstringrequired, string
    Must be a valid US Bank Account Number
    routing_number
    requiredstringrequired, string
    The routing number of the account.
    access_tokens
    [string][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.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconUserUpdateRequest = {
    2 beacon_user_id: 'becusr_11111111111111',
    3 user: {
    4 email_address: 'user@example.com',
    5 date_of_birth: '1975-01-18',
    6 name: {
    7 given_name: 'Leslie',
    8 family_name: 'Knope',
    9 },
    10 address: {
    11 street: '123 Main St.',
    12 street2: 'Unit 42',
    13 city: 'Pawnee',
    14 region: 'IN',
    15 postal_code: '46001',
    16 country: 'US',
    17 },
    18 },
    19};
    20
    21try {
    22 const response = await plaidClient.beaconUserUpdate(request);
    23 console.log(response.status.value);
    24} catch (error) {
    25 // handle error
    26}
    beacon/user/update

    Response fields and example

    item_ids
    [string][string]
    An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.
    id
    stringstring
    ID of the associated Beacon User.
    version
    integerinteger
    The version field begins with 1 and increments each time the user is updated.
    created_at
    stringstring
    An ISO8601 formatted timestamp.

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

    Format: date-time
    status
    stringstring
    A status of a Beacon User.
    rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected.
    pending_review: The Beacon User has been marked for review.
    cleared: The Beacon User has been cleared of fraud.


    Possible values: rejected, pending_review, cleared
    program_id
    stringstring
    ID of the associated Beacon Program.
    client_user_id
    stringstring
    A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.
    user
    objectobject
    A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
    date_of_birth
    stringstring
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

    Format: date
    name
    objectobject
    The full name for a given Beacon User.
    given_name
    stringstring
    A string with at least one non-whitespace character, with a max length of 100 characters.
    family_name
    stringstring
    A string with at least one non-whitespace character, with a max length of 100 characters.
    address
    objectobject
    Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
    Addresses from the United Kingdom will not include a region
    Addresses from Hong Kong will not include a postal code
    street
    stringstring
    The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.
    street2
    nullablestringnullable, string
    Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.
    city
    stringstring
    City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."
    region
    nullablestringnullable, string
    An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
    postal_code
    nullablestringnullable, string
    The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
    country
    stringstring
    Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    email_address
    nullablestringnullable, string
    A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696.

    Format: email
    phone_number
    nullablestringnullable, string
    A phone number in E.164 format.
    id_number
    nullableobjectnullable, object
    The ID number associated with a Beacon User.
    value
    stringstring
    Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.
    type
    stringstring
    A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

    Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
    ip_address
    nullablestringnullable, string
    An IPv4 or IPV6 address.
    depository_accounts
    [object][object]
    account_mask
    stringstring
    The last 2-4 numeric characters of this account’s account number.
    routing_number
    stringstring
    The routing number of the account.
    added_at
    stringstring
    An ISO8601 formatted timestamp.

    Format: date-time
    audit_trail
    objectobject
    Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    source
    stringstring
    A type indicating what caused a resource to be changed or updated.
    dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
    api - The resource was created or updated via the Plaid API.
    system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
    bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.


    Possible values: dashboard, api, system, bulk_import
    dashboard_user_id
    nullablestringnullable, string
    ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard_user/get.
    timestamp
    stringstring
    An ISO8601 formatted timestamp.

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

    /beacon/user/account_insights/get

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

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

    beacon/user/account_insights/get

    Request fields

    beacon_user_id
    requiredstringrequired, string
    ID of the associated Beacon User.
    access_token
    requiredstringrequired, string
    The access token associated with the Item data is being requested for.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconUserAccountInsightsGetRequest = {
    2 beacon_user_id: 'becusr_11111111111111',
    3 access_token: 'access-sandbox-12345678',
    4 client_id: process.env.PLAID_CLIENT_ID,
    5 secret: process.env.PLAID_SECRET,
    6};
    7
    8try {
    9 const response = await plaidClient.beaconUserAccountInsightsGet(request);
    10 console.log(response.status.value);
    11} catch (error) {
    12 // handle error
    13}
    beacon/user/account_insights/get

    Response fields and example

    beacon_user_id
    stringstring
    ID of the associated Beacon User.
    created_at
    stringstring
    An ISO8601 formatted timestamp.

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

    Format: date-time
    bank_account_insights
    objectobject
    A collection of Bank Accounts linked to an Item that is associated with this Beacon User.
    item_id
    stringstring
    The Plaid Item ID the Bank Accounts belong to.
    accounts
    [object][object]
    account_id
    stringstring
    The Plaid account_id
    type
    stringstring
    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 for a full listing of account types and corresponding subtypes.


    Possible values: investment, credit, depository, loan, brokerage, other
    subtype
    nullablestringnullable, string
    See the 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, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, 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, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity
    attributes
    objectobject
    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
    days_since_first_plaid_connection
    nullableintegernullable, integer
    The number of days since the first time the Item was connected to an application via Plaid
    is_account_closed
    nullablebooleannullable, boolean
    Indicates if the account has been closed by the financial institution or the consumer, or is at risk of being closed
    is_account_frozen_or_restricted
    nullablebooleannullable, 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
    total_plaid_connections_count
    nullableintegernullable, integer
    The total number of times the item has been connected to applications via Plaid
    plaid_connections_count_7d
    nullableintegernullable, integer
    The number of times the Item has been connected to applications via Plaid over the past 7 days
    plaid_connections_count_30d
    nullableintegernullable, integer
    The number of times the Item has been connected to applications via Plaid over the past 30 days
    failed_plaid_non_oauth_authentication_attempts_count_3d
    nullableintegernullable, integer
    The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 3 days
    plaid_non_oauth_authentication_attempts_count_3d
    nullableintegernullable, integer
    The number of non-OAuth authentication attempts via Plaid for this bank account over the past 3 days
    failed_plaid_non_oauth_authentication_attempts_count_7d
    nullableintegernullable, integer
    The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 7 days
    plaid_non_oauth_authentication_attempts_count_7d
    nullableintegernullable, integer
    The number of non-OAuth authentication attempts via Plaid for this bank account over the past 7 days
    failed_plaid_non_oauth_authentication_attempts_count_30d
    nullableintegernullable, integer
    The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 30 days
    plaid_non_oauth_authentication_attempts_count_30d
    nullableintegernullable, integer
    The number of non-OAuth authentication attempts via Plaid for this bank account over the past 30 days
    distinct_ip_addresses_count_3d
    nullableintegernullable, integer
    The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 3 days
    distinct_ip_addresses_count_7d
    nullableintegernullable, integer
    The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 7 days
    distinct_ip_addresses_count_30d
    nullableintegernullable, integer
    The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 30 days
    distinct_ip_addresses_count_90d
    nullableintegernullable, integer
    The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 90 days
    distinct_user_agents_count_3d
    nullableintegernullable, integer
    The number of distinct user agents linked to the same bank account during Plaid authentication in the last 3 days
    distinct_user_agents_count_7d
    nullableintegernullable, integer
    The number of distinct user agents linked to the same bank account during Plaid authentication in the last 7 days
    distinct_user_agents_count_30d
    nullableintegernullable, integer
    The number of distinct user agents linked to the same bank account during Plaid authentication in the last 30 days
    distinct_user_agents_count_90d
    nullableintegernullable, integer
    The number of distinct user agents linked to the same bank account during Plaid authentication in the last 90 days
    address_change_count_28d
    nullableintegernullable, integer
    The number of times the account's addresses on file have changed over the past 28 days
    email_change_count_28d
    nullableintegernullable, integer
    The number of times the account's email addresses on file have changed over the past 28 days
    phone_change_count_28d
    nullableintegernullable, integer
    The number of times the account's phone numbers on file have changed over the past 28 days
    address_change_count_90d
    nullableintegernullable, integer
    The number of times the account's addresses on file have changed over the past 90 days
    email_change_count_90d
    nullableintegernullable, integer
    The number of times the account's email addresses on file have changed over the past 90 days
    phone_change_count_90d
    nullableintegernullable, integer
    The number of times the account's phone numbers on file have changed over the past 90 days
    days_since_account_opening
    nullableintegernullable, integer
    The number of days since the bank account was opened, as reported by the financial institution
    days_since_first_observed_transaction
    nullableintegernullable, 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
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    1{
    2 "beacon_user_id": "becusr_42cF1MNo42r9Xj",
    3 "created_at": "2020-07-24T03:26:02Z",
    4 "updated_at": "2020-07-24T03:26:02Z",
    5 "bank_account_insights": {
    6 "item_id": "515cd85321d3649aecddc015",
    7 "accounts": [
    8 {
    9 "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
    10 "type": "depository",
    11 "subtype": "checking",
    12 "attributes": {
    13 "days_since_first_plaid_connection": 1,
    14 "is_account_closed": false,
    15 "is_account_frozen_or_restricted": false,
    16 "total_plaid_connections_count": 1,
    17 "plaid_connections_count_7d": 1,
    18 "plaid_connections_count_30d": 1,
    19 "failed_plaid_non_oauth_authentication_attempts_count_3d": 1,
    20 "plaid_non_oauth_authentication_attempts_count_3d": 1,
    21 "failed_plaid_non_oauth_authentication_attempts_count_7d": 1,
    22 "plaid_non_oauth_authentication_attempts_count_7d": 1,
    23 "failed_plaid_non_oauth_authentication_attempts_count_30d": 1,
    24 "plaid_non_oauth_authentication_attempts_count_30d": 1,
    25 "distinct_ip_addresses_count_3d": 1,
    26 "distinct_ip_addresses_count_7d": 1,
    27 "distinct_ip_addresses_count_30d": 1,
    28 "distinct_ip_addresses_count_90d": 1,
    29 "distinct_user_agents_count_3d": 1,
    30 "distinct_user_agents_count_7d": 1,
    31 "distinct_user_agents_count_30d": 1,
    32 "distinct_user_agents_count_90d": 1,
    33 "address_change_count_28d": 1,
    34 "email_change_count_28d": 2,
    35 "phone_change_count_28d": 1,
    36 "address_change_count_90d": 3,
    37 "email_change_count_90d": 4,
    38 "phone_change_count_90d": 2,
    39 "days_since_account_opening": 365,
    40 "days_since_first_observed_transaction": 180
    41 }
    42 }
    43 ]
    44 },
    45 "request_id": "saKrIBuEB9qJZng"
    46}
    Was this helpful?

    /beacon/user/history/list

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

    List a Beacon User's history

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

    beacon/user/history/list

    Request fields

    beacon_user_id
    requiredstringrequired, string
    ID of the associated Beacon User.
    cursor
    stringstring
    An identifier that determines which page of results you receive.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconUserHistoryListRequest = {
    2 beacon_user_id: 'becusr_11111111111111',
    3};
    4
    5try {
    6 const response = await plaidClient.beaconUserHistoryList(request);
    7} catch (error) {
    8 // handle error
    9}
    beacon/user/history/list

    Response fields and example

    beacon_users
    [object][object]
    item_ids
    [string][string]
    An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.
    id
    stringstring
    ID of the associated Beacon User.
    version
    integerinteger
    The version field begins with 1 and increments each time the user is updated.
    created_at
    stringstring
    An ISO8601 formatted timestamp.

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

    Format: date-time
    status
    stringstring
    A status of a Beacon User.
    rejected: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected.
    pending_review: The Beacon User has been marked for review.
    cleared: The Beacon User has been cleared of fraud.


    Possible values: rejected, pending_review, cleared
    program_id
    stringstring
    ID of the associated Beacon Program.
    client_user_id
    stringstring
    A unique ID that identifies the end user in your system. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the /link/token/create client_user_id to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.
    user
    objectobject
    A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
    date_of_birth
    stringstring
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

    Format: date
    name
    objectobject
    The full name for a given Beacon User.
    given_name
    stringstring
    A string with at least one non-whitespace character, with a max length of 100 characters.
    family_name
    stringstring
    A string with at least one non-whitespace character, with a max length of 100 characters.
    address
    objectobject
    Even if an address has been collected, some fields may be null depending on the region's addressing system. For example:
    Addresses from the United Kingdom will not include a region
    Addresses from Hong Kong will not include a postal code
    street
    stringstring
    The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters.
    street2
    nullablestringnullable, string
    Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters.
    city
    stringstring
    City from the end user's address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters."
    region
    nullablestringnullable, string
    An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
    postal_code
    nullablestringnullable, string
    The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
    country
    stringstring
    Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    email_address
    nullablestringnullable, string
    A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see RFC 3696.

    Format: email
    phone_number
    nullablestringnullable, string
    A phone number in E.164 format.
    id_number
    nullableobjectnullable, object
    The ID number associated with a Beacon User.
    value
    stringstring
    Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see Hybrid Input Validation.
    type
    stringstring
    A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see Hybrid Input Validation.

    Possible values: ar_dni, au_drivers_license, au_passport, br_cpf, ca_sin, cl_run, cn_resident_card, co_nit, dk_cpr, eg_national_id, es_dni, es_nie, hk_hkid, in_pan, it_cf, jo_civil_id, jp_my_number, ke_huduma_namba, kw_civil_id, mx_curp, mx_rfc, my_nric, ng_nin, nz_drivers_license, om_civil_id, ph_psn, pl_pesel, ro_cnp, sa_national_id, se_pin, sg_nric, tr_tc_kimlik, us_ssn, us_ssn_last_4, za_smart_id
    ip_address
    nullablestringnullable, string
    An IPv4 or IPV6 address.
    depository_accounts
    [object][object]
    account_mask
    stringstring
    The last 2-4 numeric characters of this account’s account number.
    routing_number
    stringstring
    The routing number of the account.
    added_at
    stringstring
    An ISO8601 formatted timestamp.

    Format: date-time
    audit_trail
    objectobject
    Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    source
    stringstring
    A type indicating what caused a resource to be changed or updated.
    dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
    api - The resource was created or updated via the Plaid API.
    system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
    bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.


    Possible values: dashboard, api, system, bulk_import
    dashboard_user_id
    nullablestringnullable, string
    ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard_user/get.
    timestamp
    stringstring
    An ISO8601 formatted timestamp.

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

    /beacon/report/create

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

    Create a Beacon Report

    Create a fraud report for a given Beacon User.

    beacon/report/create

    Request fields

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


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

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

    Possible values: USD
    value
    requirednumberrequired, 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
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconReportCreateRequest = {
    2 beacon_user_id: 'becusr_11111111111111',
    3 type: 'first_party',
    4 fraud_date: '1975-01-18',
    5};
    6
    7try {
    8 const response = await plaidClient.beaconReportCreate(request);
    9} catch (error) {
    10 // handle error
    11}
    beacon/report/create

    Response fields and example

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

    Format: date-time
    type
    stringstring
    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
    fraud_date
    nullablestringnullable, string
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

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

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

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

    Format: double
    audit_trail
    objectobject
    Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    source
    stringstring
    A type indicating what caused a resource to be changed or updated.
    dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
    api - The resource was created or updated via the Plaid API.
    system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
    bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.


    Possible values: dashboard, api, system, bulk_import
    dashboard_user_id
    nullablestringnullable, string
    ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard_user/get.
    timestamp
    stringstring
    An ISO8601 formatted timestamp.

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

    /beacon/report/get

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

    Get a Beacon Report

    Returns a Beacon report for a given Beacon report id.

    beacon/report/get

    Request fields

    beacon_report_id
    requiredstringrequired, string
    ID of the associated Beacon Report.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconReportGetRequest = {
    2 beacon_report_id: 'becrpt_11111111111111',
    3};
    4
    5try {
    6 const response = await plaidClient.beaconReportGet(request);
    7} catch (error) {
    8 // handle error
    9}
    beacon/report/get

    Response fields and example

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

    Format: date-time
    type
    stringstring
    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
    fraud_date
    nullablestringnullable, string
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

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

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

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

    Format: double
    audit_trail
    objectobject
    Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    source
    stringstring
    A type indicating what caused a resource to be changed or updated.
    dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
    api - The resource was created or updated via the Plaid API.
    system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
    bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.


    Possible values: dashboard, api, system, bulk_import
    dashboard_user_id
    nullablestringnullable, string
    ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard_user/get.
    timestamp
    stringstring
    An ISO8601 formatted timestamp.

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

    /beacon/report/list

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

    List Beacon Reports for a Beacon User

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

    beacon/report/list

    Request fields

    beacon_user_id
    requiredstringrequired, string
    ID of the associated Beacon User.
    cursor
    stringstring
    An identifier that determines which page of results you receive.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconReportListRequest = {
    2 beacon_user_id: 'becusr_11111111111111',
    3};
    4
    5try {
    6 const response = await plaidClient.beaconReportList(request);
    7} catch (error) {
    8 // handle error
    9}
    beacon/report/list

    Response fields and example

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

    Format: date-time
    type
    stringstring
    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
    fraud_date
    nullablestringnullable, string
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

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

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

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

    Format: double
    audit_trail
    objectobject
    Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    source
    stringstring
    A type indicating what caused a resource to be changed or updated.
    dashboard - The resource was created or updated by a member of your team via the Plaid dashboard.
    api - The resource was created or updated via the Plaid API.
    system - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be system.
    bulk_import - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be bulk_import.


    Possible values: dashboard, api, system, bulk_import
    dashboard_user_id
    nullablestringnullable, string
    ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use /dashboard_user/get.
    timestamp
    stringstring
    An ISO8601 formatted timestamp.

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

    /beacon/report_syndication/get

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

    Get a Beacon Report Syndication

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

    beacon/report_syndication/get

    Request fields

    beacon_report_syndication_id
    requiredstringrequired, string
    ID of the associated Beacon Report Syndication.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconReportSyndicationGetRequest = {
    2 beacon_report_syndication_id: 'becrsn_11111111111111',
    3};
    4
    5try {
    6 const response = await plaidClient.beaconReportSyndicationGet(request);
    7} catch (error) {
    8 // handle error
    9}
    beacon/report_syndication/get

    Response fields and example

    id
    stringstring
    ID of the associated Beacon Report Syndication.
    beacon_user_id
    stringstring
    ID of the associated Beacon User.
    report
    objectobject
    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.
    id
    nullablestringnullable, string
    ID of the associated Beacon Report.
    created_at
    stringstring
    An ISO8601 formatted timestamp.

    Format: date-time
    type
    stringstring
    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
    fraud_date
    nullablestringnullable, string
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

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

    Format: date
    analysis
    objectobject
    Analysis of which fields matched between the originally reported Beacon User and the Beacon User that the report was syndicated to.
    address
    stringstring
    An enum indicating the match type between two Beacon Users.
    match indicates that the provided input data was a strong match against the other Beacon User.
    partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
    no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
    no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.


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


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


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


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


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


    Possible values: match, partial_match, no_match, no_data
    phone_number
    stringstring
    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
    depository_accounts
    [object][object]
    account_mask
    stringstring
    The last 2-4 numeric characters of this account’s account number.
    routing_number
    stringstring
    The routing number of the account.
    match_status
    stringstring
    An enum indicating the match type between two Beacon Users.
    match indicates that the provided input data was a strong match against the other Beacon User.
    partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
    no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
    no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.


    Possible values: match, partial_match, no_match, no_data
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    1{
    2 "id": "becrsn_11111111111111",
    3 "beacon_user_id": "becusr_42cF1MNo42r9Xj",
    4 "report": {
    5 "id": "becrpt_11111111111111",
    6 "created_at": "2020-07-24T03:26:02Z",
    7 "type": "first_party",
    8 "fraud_date": "1990-05-29",
    9 "event_date": "1990-05-29"
    10 },
    11 "analysis": {
    12 "address": "match",
    13 "date_of_birth": "match",
    14 "email_address": "match",
    15 "name": "match",
    16 "id_number": "match",
    17 "ip_address": "match",
    18 "phone_number": "match",
    19 "depository_accounts": [
    20 {
    21 "account_mask": "4000",
    22 "routing_number": "021000021",
    23 "match_status": "match"
    24 }
    25 ]
    26 },
    27 "request_id": "saKrIBuEB9qJZng"
    28}
    Was this helpful?

    /beacon/report_syndication/list

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

    List Beacon Report Syndications for a Beacon User

    Use the /beacon/report_syndication/list 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.

    beacon/report_syndication/list

    Request fields

    beacon_user_id
    requiredstringrequired, string
    ID of the associated Beacon User.
    cursor
    stringstring
    An identifier that determines which page of results you receive.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconReportSyndicationListRequest = {
    2 beacon_user_id: 'becusr_11111111111111',
    3};
    4
    5try {
    6 const response = await plaidClient.beaconReportSyndicationList(request);
    7} catch (error) {
    8 // handle error
    9}
    beacon/report_syndication/list

    Response fields and example

    beacon_report_syndications
    [object][object]
    id
    stringstring
    ID of the associated Beacon Report Syndication.
    beacon_user_id
    stringstring
    ID of the associated Beacon User.
    report
    objectobject
    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.
    id
    nullablestringnullable, string
    ID of the associated Beacon Report.
    created_at
    stringstring
    An ISO8601 formatted timestamp.

    Format: date-time
    type
    stringstring
    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
    fraud_date
    nullablestringnullable, string
    A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).

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

    Format: date
    analysis
    objectobject
    Analysis of which fields matched between the originally reported Beacon User and the Beacon User that the report was syndicated to.
    address
    stringstring
    An enum indicating the match type between two Beacon Users.
    match indicates that the provided input data was a strong match against the other Beacon User.
    partial_match indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name.
    no_match indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data.
    no_data indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users.


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


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


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


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


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


    Possible values: match, partial_match, no_match, no_data
    phone_number
    stringstring
    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
    depository_accounts
    [object][object]
    account_mask
    stringstring
    The last 2-4 numeric characters of this account’s account number.
    routing_number
    stringstring
    The routing number of the account.
    match_status
    stringstring
    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
    next_cursor
    nullablestringnullable, string
    An identifier that determines which page of results you receive.
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    1{
    2 "beacon_report_syndications": [
    3 {
    4 "id": "becrsn_11111111111111",
    5 "beacon_user_id": "becusr_42cF1MNo42r9Xj",
    6 "report": {
    7 "id": "becrpt_11111111111111",
    8 "created_at": "2020-07-24T03:26:02Z",
    9 "type": "first_party",
    10 "fraud_date": "1990-05-29",
    11 "event_date": "1990-05-29"
    12 },
    13 "analysis": {
    14 "address": "match",
    15 "date_of_birth": "match",
    16 "email_address": "match",
    17 "name": "match",
    18 "id_number": "match",
    19 "ip_address": "match",
    20 "phone_number": "match",
    21 "depository_accounts": [
    22 {
    23 "account_mask": "4000",
    24 "routing_number": "021000021",
    25 "match_status": "match"
    26 }
    27 ]
    28 }
    29 }
    30 ],
    31 "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM",
    32 "request_id": "saKrIBuEB9qJZng"
    33}
    Was this helpful?

    /beacon/duplicate/get

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

    Get a Beacon Duplicate

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

    beacon/duplicate/get

    Request fields

    beacon_duplicate_id
    requiredstringrequired, string
    ID of the associated Beacon Duplicate.
    client_id
    stringstring
    Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
    secret
    stringstring
    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.
    Select Language
    1const request: BeaconDuplicateGetRequest = {
    2 beacon_duplicate_id: 'becdup_11111111111111',
    3};
    4
    5try {
    6 const response = await plaidClient.beaconDuplicateGet(request);
    7} catch (error) {
    8 // handle error
    9}
    beacon/duplicate/get

    Response fields and example

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


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


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


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


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


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


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


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

    Webhooks

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

    USER_STATUS_UPDATED

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

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

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

    REPORT_CREATED

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

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

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

    REPORT_UPDATED

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

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

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

    REPORT_SYNDICATION_CREATED

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

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

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

    DUPLICATE_DETECTED

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

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

    Possible values: sandbox, production
    1{
    2 "webhook_type": "BEACON",
    3 "webhook_code": "DUPLICATE_DETECTED",
    4 "beacon_duplicate_id": "becdup_erJcFn97r9sugZ",
    5 "environment": "production"
    6}
    Was this helpful?
    Developer community
    GitHub
    GitHub
    Stack Overflow
    Stack Overflow
    YouTube
    YouTube
    Discord
    Discord