---
title: "Create user"
method: POST
path: "/user/create"
tags: ["plaid"]
---

# Create user

`POST /user/create`

For Plaid products and flows that use the user object, `/user/create` provides you a single token to access all data associated with the user. You must call this endpoint before calling `/link/token/create` if you are using any of the following: Plaid Check, Income Verification, Multi-Item Link, or Plaid Protect (Identity). If you are using Plaid Protect Link session scoring, you do not need to call `/user/create` first; Plaid will resolve or create the user when `user.client_user_id` is provided in `/link/token/create`.
For customers who began using this endpoint on or after December 10, 2025, this endpoint takes a `client_user_id` and an `identity` object and will return a `user_id`. For customers who began using it before that date, the endpoint takes a `client_user_id` and a `consumer_report_user_identity` object and will return a `user_token` and `user_id`. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis).
In order to create a Plaid Check Consumer Report for a user, the `identity` (new) or `consumer_report_user_identity` (legacy) object must be present. If it is not provided during the `/user/create` call, it can be added later by calling `/user/update`.


In order to generate a Plaid Check Consumer Report, the following `identity` fields, at minimum, are required and must be non-empty: `name`, `date_of_birth`, `emails`, `phone_numbers`, and `addresses` (with at least one email, phone number, and address designated as `primary`). Plaid Check Consumer Reports can only be created for US-based users; the user's address country must be `US`. If creating a report for sharing with a GSE such as Fannie or Freddie, the user's full SSN must be provided via the `id_numbers` field. Providing at least a partial SSN is also strongly recommended for all use cases, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests.


When using Plaid Protect, it is highly recommended that you provide an `identity` object to better identify and block fraud across your Link sessions.


Plaid will normalize identity fields before storing them and utilize the same identity across different user-based products.

## Headers

- `Plaid-New-User-API-Enabled` boolean

## Request body

- UserCreateRequest — UserCreateRequest defines the request schema for `/user/create`
  - `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.
  - `client_user_id` string, required — A unique ID representing the end user. Maximum of 128 characters. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`.
  - `identity` ClientUserIdentity, nullable — The identity fields associated with a user. For a user to be eligible for a Plaid Check Consumer Report, all fields are required except `id_number`. Providing a partial SSN is strongly recommended, and improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. If creating a report that will be shared with GSEs such as Fannie or Freddie, a full Social Security Number must be provided via the `id_number` field.
    - `name` ClientUserIdentityName, nullable — User name information.
      - `given_name` string, required — User's given name.
      - `family_name` string, required — User's family name.
    - `date_of_birth` string, date, nullable — The user's date of birth, to be provided in the format "yyyy-mm-dd".
    - `emails` ClientUserIdentityEmail[] — The user's emails.
      - `data` string, required — User's email.
      - `primary` boolean, required — Indicates whether this is the primary email for the User.
    - `phone_numbers` ClientUserIdentityPhoneNumber[] — The user's phone numbers, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.
      - `data` string, required — User's phone number.
      - `primary` boolean, required — Indicates whether this is the primary phone number for the User.
    - `addresses` ClientUserIdentityAddress[] — The user's addresses.
      - `street_1` string, nullable — First line of street address.
      - `street_2` string, nullable — Second line of street address.
      - `city` string, nullable — City name.
      - `region` string, nullable — State, province or region.
      - `country` string, required — Country code.
      - `postal_code` string, nullable — Postal or ZIP code.
      - `primary` boolean, required — Indicates whether this is the primary address for the User.
    - `id_numbers` UserIDNumber[] — The user's ID numbers.
      - `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).
  - `end_customer` string — A unique ID representing a CRA reseller's end customer. Maximum of 128 characters.
  - `consumer_report_user_identity` ConsumerReportUserIdentity, nullable — This field is only used by integrations created before December 10, 2025. All other integrations must use the `identity` object instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis). To create a Plaid Check Consumer Report for a user when using a `user_token`, this field must be present. If this field is not provided during user token creation, you can add it to the user later by calling `/user/update`. Once the field has been added to the user, you will be able to call `/link/token/create` with a non-empty `consumer_report_permissible_purpose` (which will automatically create a Plaid Check Consumer Report), or call `/cra/check_report/create` for that user.
    - `first_name` string, required — The user's first name
    - `last_name` string, required — The user's last name
    - `phone_numbers` string[], required — The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment.
    - `emails` string[], required — The user's emails
    - `ssn_full` string, nullable — The user's full Social Security number. This field should only be provided by lenders intending to share the resulting consumer report with a Government-Sponsored Enterprise (GSE), such as Fannie Mae or Freddie Mac. Format: "ddd-dd-dddd"
    - `ssn_last_4` string, nullable — The last 4 digits of the user's Social Security number.
    - `date_of_birth` string, date, nullable, required — To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers.
    - `primary_address` AddressData, required — Data about the components comprising an address.
      - `city` string, nullable, required — The full city name
      - `region` string, nullable, required — The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"`
      - `street` string, required — The full street address Example: `"564 Main Street, APT 15"`
      - `postal_code` string, nullable, required — The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`.
      - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code
  - `with_upgraded_user` boolean — If your integration with the User API predates December 10, 2025, set this field to `true` to opt into the [New User APIs](https://plaid.com/docs/api/users/user-apis/). When enabled, you can use the `identity` field instead of `consumer_report_user_identity`.

## Response `200`

OK

- UserCreateResponse — UserCreateResponse defines the response schema for `/user/create`
  - `user_token` string — The user token associated with the user for which data is being requested. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis).
  - `user_id` string, required — A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis).
  - `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.

## Other responses

- `201` — Created
- `default` — Error response

---

[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)