---
title: "(Deprecated) Create a Beacon User"
method: POST
path: "/beacon/user/create"
tags: ["plaid"]
deprecated: true
---

# (Deprecated) Create a Beacon User

`POST /beacon/user/create`

> **Deprecated.**

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 reports shared with the Beacon Network by other companies. If a matching fraud report is found, the user will be returned with a `pending_review` status if your program has enabled automatic flagging based on network fraud.

## Request body

- BeaconUserCreateRequest — Request input for creating a Beacon User. The primary use for this endpoint is to add a new end user to Beacon for fraud and duplicate scanning. Some fields are optional, but it is recommended to provide as much information as possible to improve the accuracy of the fraud and duplicate scanning.
  - `program_id` string, required — ID of the associated Beacon Program.
  - `client_user_id` string, required — A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`.
  - `user` BeaconUserRequestData, required — 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` string, date — A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).
    - `name` BeaconUserName, required — The full name for a given Beacon User.
      - `given_name` string, required — A string with at least one non-whitespace character, with a max length of 100 characters.
      - `family_name` string, required — A string with at least one non-whitespace character, with a max length of 100 characters.
    - `address` BeaconUserRequestAddress, nullable — Home address for the associated user. For more context on this field, see [Input Validation by Country](https://plaid.com/docs/identity-verification/hybrid-input-validation/#input-validation-by-country).
      - `street` string, required — 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` string, nullable — 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` string, required — City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.
      - `region` string, nullable — A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json). Country prefixes are omitted, since they are inferred from the `country` field.
      - `postal_code` string, nullable — The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
      - `country` string, required — Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    - `email_address` string, email — A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696).
    - `phone_number` string, nullable — A phone number in E.164 format.
    - `id_number` BeaconUserIDNumber, nullable — The ID number associated with a Beacon User.
      - `value` string, required — Value of the identity document typed in by the user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/#id-numbers).
      - `type` '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' | 'in_epic' | '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', required — A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/#id-numbers).
    - `ip_address` string, nullable — An IPv4 or IPv6 address.
    - `depository_accounts` BeaconUserRequestDepositoryAccount[] — 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` string, required — Must be a valid US Bank Account Number
      - `routing_number` string, required — The routing number of the account.
  - `access_tokens` AccessToken[], nullable — 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` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
  - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.

## Response `200`

OK

- BeaconUserCreateResponse — A Beacon User represents an end user that has been scanned against the Beacon Network.
  - `item_ids` string[], required — An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User.
  - `id` string, required — ID of the associated Beacon User.
  - `version` integer, required — The `version` field begins with 1 and increments each time the user is updated.
  - `created_at` string, date-time, required — An ISO8601 formatted timestamp.
  - `updated_at` string, date-time, required — An ISO8601 formatted timestamp. This field indicates the last time the resource was modified.
  - `status` 'rejected' | 'pending_review' | 'cleared', required — A status of a Beacon User. `rejected`: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. `pending_review`: The Beacon User has been marked for review. `cleared`: The Beacon User has been cleared of fraud.
  - `program_id` string, required — ID of the associated Beacon Program.
  - `client_user_id` string, required — A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`.
  - `user` BeaconUserData, required — A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network.
    - `date_of_birth` string, date, required — A date in the format YYYY-MM-DD (RFC 3339 Section 5.6).
    - `name` BeaconUserName, required — The full name for a given Beacon User.
      - `given_name` string, required — A string with at least one non-whitespace character, with a max length of 100 characters.
      - `family_name` string, required — A string with at least one non-whitespace character, with a max length of 100 characters.
    - `address` BeaconUserAddress, required — Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code
      - `street` string, required — 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` string, nullable, required — 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` string, required — City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters.
      - `region` string, nullable, required — A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json). Country prefixes are omitted, since they are inferred from the `country` field.
      - `postal_code` string, nullable, required — The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits.
      - `country` string, required — Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    - `email_address` string, email, nullable, required — A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696).
    - `phone_number` string, nullable, required — A phone number in E.164 format.
    - `id_number` BeaconUserIDNumber, nullable, required — The ID number associated with a Beacon User.
      - `value` string, required — Value of the identity document typed in by the user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/#id-numbers).
      - `type` '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' | 'in_epic' | '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', required — A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/#id-numbers).
    - `ip_address` string, nullable, required — An IPv4 or IPv6 address.
    - `depository_accounts` BeaconUserDepositoryAccount[], required
      - `account_mask` string, required — The last 2-4 numeric characters of this account's account number.
      - `routing_number` string, required — The routing number of the account.
      - `added_at` string, date-time, required — An ISO8601 formatted timestamp.
  - `audit_trail` BeaconAuditTrail, required — Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    - `source` 'dashboard' | 'api' | 'system' | 'bulk_import', required — A type indicating what caused a resource to be changed or updated. `dashboard` - The resource was created or updated by a member of your team via the Plaid dashboard. `api` - The resource was created or updated via the Plaid API. `system` - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be `system`. `bulk_import` - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be `bulk_import`.
    - `dashboard_user_id` string, nullable, required — 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` string, date-time, required — An ISO8601 formatted timestamp.
  - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

---

[API](https://skmtc.net/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.net/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/versions/64c4514ea59b/schema)