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

# Create user

`POST /user/create`

This endpoint should be called for each of your end users before they begin a Plaid Check or Income flow, or a Multi-Item Link flow. This provides you a single token to access all data associated with the user. You should only create one per end user.

The `consumer_report_user_identity` object must be present in order to create a Plaid Check Consumer Report for a user. If it is not provided during the `/user/create` call, it can be added later by calling `/user/update`. Plaid Check Consumer Reports can only be created for US-based users; the user's address country must be `US`.

If you call the endpoint multiple times with the same `client_user_id`, the first creation call will succeed and the rest will fail with an error message indicating that the user has been created for the given `client_user_id`.

Ensure that you store the `user_token` along with your user's identifier in your database, as it is not possible to retrieve a previously created `user_token`.

## 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`.
  - `end_customer` string — A unique ID representing a CRA reseller's end customer. Maximum of 128 characters.
  - `consumer_report_user_identity` ConsumerReportUserIdentity, nullable — To create a Plaid Check Consumer Report for a user, this field must be present on the user token. 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
  - `identity` ClientUserIdentity, nullable — ClientUserIdentity is the shared user identity construct across /user/* routes.
    - `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 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](https://plaid.com/docs/identity-verification/hybrid-input-validation/).
      - `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).

## Response `200`

OK

- UserCreateResponse — UserCreateResponse defines the response schema for `/user/create`
  - `user_token` string — The user token associated with the User data is being requested for.
  - `user_id` string, required — The Plaid `user_id` of the User associated with this webhook, warning, or error.
  - `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.
  - `identity_creation_result` IdentityCreationResult, nullable — The result of creating an identity, indicating success or failure with optional error details.
    - `result` 'SUCCEEDED' | 'FAILED' | 'NOT_PROVIDED', required — The outcome of the identity creation operation.
    - `error_type` 'INVALID_REQUEST' | 'INVALID_RESULT' | 'INVALID_INPUT' | 'INSTITUTION_ERROR' | 'RATE_LIMIT_EXCEEDED' | 'API_ERROR' | 'ITEM_ERROR' | 'ASSET_REPORT_ERROR' | 'RECAPTCHA_ERROR' | 'OAUTH_ERROR' | 'PAYMENT_ERROR' | 'BANK_TRANSFER_ERROR' | 'INCOME_VERIFICATION_ERROR' | 'MICRODEPOSITS_ERROR' | 'SANDBOX_ERROR' | 'PARTNER_ERROR' | 'SIGNAL_ERROR' | 'TRANSACTIONS_ERROR' | 'TRANSACTION_ERROR' | 'TRANSFER_ERROR' | 'CHECK_REPORT_ERROR' | 'CONSUMER_REPORT_ERROR' — A broad categorization of the error. Safe for programmatic use.
    - `error_code` string, nullable — Specific error code indicating the nature of the failure. Safe for programmatic use.
    - `error_message` string, nullable — Human-readable error message providing details about the failure.

## Changes

- **2025-10-22** `af4b6e71d87f` — 1 breaking, 1 warning, 9 info
  - the response property `identity_creation_result` became nullable for the status `200`
  - added the new `SIGNAL_ERROR` enum value to the `identity_creation_result/error_type/allOf[subschema #1: PlaidErrorType]/` response property for the response status `200`
  - the request property `identity/addresses/items/city` became nullable
  - the request property `identity/addresses/items/postal_code` became nullable
  - …7 more
- **2025-10-02** `83dc2757b74e` — 2 info
  - added the new optional request property `identity`
  - added the optional property `identity_creation_result` to the response with the `200` status
- **2025-06-12** `b0b8ac37e34d` — 1 info
  - added the new optional request property `consumer_report_user_identity/ssn_full`
- **2025-06-03** `b7200537f765` — 2 breaking
  - for the `header` request parameter `Plaid-New-User-API-Enabled`, default value `false` was added
  - for the `header` request parameter `Plaid-New-User-API-Enabled`, the type/format was changed from `string`/`` to `boolean`/``
- **2025-05-19** `02e6d58e95e9` — 1 breaking, 1 info
  - the response property `user_token` became optional for the status `200`
  - added the new optional `header` request parameter `Plaid-New-User-API-Enabled`

[Full history](https://skmtc.dev/plaid/apis/the-plaid-api/changes/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/af4b6e71d87f/schema)