---
title: "Create a watchlist screening for an entity"
method: POST
path: "/watchlist_screening/entity/create"
tags: ["plaid"]
---

# Create a watchlist screening for an entity

`POST /watchlist_screening/entity/create`

Create a new entity watchlist screening to check your customer against watchlists defined in the associated entity watchlist program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time.

## Request body

- WatchlistScreeningEntityCreateRequest — Request input for creating an entity watchlist screening
  - `search_terms` EntityWatchlistSearchTerms, required — Search inputs for creating an entity watchlist screening
    - `entity_watchlist_program_id` string, required — ID of the associated entity program.
    - `legal_name` string, required — The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.
    - `document_number` string, nullable — The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.
    - `email_address` string, email, nullable — 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).
    - `country` string, nullable — Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    - `phone_number` string, nullable — A phone number in E.164 format.
    - `url` string, uri, nullable — An 'http' or 'https' URL (must begin with either of those).
  - `client_user_id` string — A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`.
  - `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

- WatchlistScreeningEntityCreateResponse — The entity screening object allows you to represent an entity in your system, update its profile, and search for it on various watchlists. Note: Rejected entity screenings will not receive new hits, regardless of entity program configuration.
  - `id` string, required — ID of the associated entity screening.
  - `search_terms` EntityWatchlistScreeningSearchTerms, required — Search terms associated with an entity used for searching against watchlists
    - `entity_watchlist_program_id` string, required — ID of the associated entity program.
    - `legal_name` string, required — The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces.
    - `document_number` string, nullable, required — The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces.
    - `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).
    - `country` string, nullable, required — Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form.
    - `phone_number` string, nullable, required — A phone number in E.164 format.
    - `url` string, uri, nullable, required — An 'http' or 'https' URL (must begin with either of those).
    - `version` integer, required — The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`.
  - `assignee` 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`.
  - `status` 'rejected' | 'pending_review' | 'cleared', required — A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared.
  - `client_user_id` string, nullable, 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`.
  - `audit_trail` WatchlistScreeningAuditTrail, required — Information about the last change made to the parent object specifying what caused the change as well as when it occurred.
    - `source` 'dashboard' | 'link' | 'api' | 'system' | 'retro', required — A type indicating who or what last touched this object. `dashboard`, `link`, and `api` indicate the originating surface; `system` indicates Plaid. `retro` indicates a screening created retroactively via a bulk screening creation.
    - `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/revisions/64c4514ea59b/schema)