---
title: "Create a Beacon User"
method: POST
path: "/beacon/user/create"
tags: ["plaid"]
---

# Create a Beacon User

`POST /beacon/user/create`

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.

## 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. This endpoint can also be used to import historical fraud cases into the Beacon Network without being charged for creating a Beacon User. To import historical fraud cases, embed the fraud report in the optional `report` section of the request payload.
  - `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. 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.
    - `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` BeaconUserRequestAddress, required — 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.
      - `street2` string, nullable — Extra street information, like an apartment or suite number.
      - `city` string, required — City from the end user's address
      - `region` string, nullable — An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
      - `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.
    - `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 identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
      - `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' | '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 [Hybrid Input Validation](https://plaid.com/docs/identity-verification/hybrid-input-validation).
    - `ip_address` string, nullable — An IPv4 or IPV6 address.
  - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
  - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.

## Response `200`

OK

- BeaconUserCreateResponse — A Beacon User represents an end user that has been scanned against the Beacon Network.
  - `id` string, required — ID of the associated Beacon User.
  - `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. 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.
      - `street2` string, nullable, required — Extra street information, like an apartment or suite number.
      - `city` string, required — City from the end user's address
      - `region` string, nullable, required — An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc.
      - `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.
    - `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 identity document value typed in by user. Alpha-numeric, with all formatting characters stripped.
      - `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' | '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 [Hybrid Input Validation](https://plaid.com/docs/identity-verification/hybrid-input-validation).
    - `ip_address` string, nullable, required — An IPv4 or IPV6 address.
  - `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.
  - `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.

## Changes

- **2024-02-21** `5de70cc1e6ca` — 10 breaking, 2 warning, 1 info
  - the request property `user/address` became not nullable
  - the request property `user/address` became required
  - the request property `user/date_of_birth` became required
  - removed the enum value `in_epic` of the request property `user/id_number/type`
  - …9 more

[Change history](https://skmtc.dev/plaid/apis/the-plaid-api/changes/beacon/user/create/post.md)

---

[API](https://skmtc.dev/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.dev/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/5de70cc1e6ca/schema)