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.

Request Body

Required

UserCreateRequest defines the request schema for /user/create

Parameters

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
required, string
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
object
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
required, string
The user’s first name
last_name
required, string
The user’s last name
phone_numbers
required, array[string]
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
required, array[string]
The user’s emails
ssn_full
string
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
The last 4 digits of the user’s social security number.
date_of_birth
required, string
To be provided in the format “yyyy-mm-dd”. This field is required for all Plaid Check customers.
primary_address
required, object
Data about the components comprising an address.
city
required, string
The full city name
region
required, string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
required, string
The full street address Example: "564 Main Street, APT 15"
postal_code
required, string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
required, string
The ISO 3166-1 alpha-2 country code
identity
object
ClientUserIdentity is the shared user identity construct across /user/* routes.
name
object
User name information.
given_name
required, string
User’s given name.
family_name
required, string
User’s family name.
date_of_birth
string
The user’s date of birth, to be provided in the format “yyyy-mm-dd”.
emails
array[string]
The user’s emails.
phone_numbers
array[string]
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.
addresses
array[object]
The user’s addresses.
street_1
required, string
First line of street address.
street_2
string
Second line of street address.
city
required, string
City name.
region
required, string
State, province or region.
country
required, string
Country code.
postal_code
required, string
Postal or ZIP code.
type
required, string
Type of address.
id_numbers
array[object]
The user’s ID numbers.
value
required, string
The ID number value.
category
required, string
Category of ID number.
type
required, string
Specific type of ID number.
country_code
required, string
Country code for the ID number.

Response

UserCreateResponse defines the response schema for /user/create

Response Properties

user_token
string
The user token associated with the User data is being requested for.
user_id
required, string
The Plaid user_id of the User associated with this webhook, warning, or error.
request_id
required, string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
identity_creation_result
object
The result of creating an identity, indicating success or failure with optional error details.
result
required, string
The outcome of the identity creation operation.
error_type
object
error_code
string
Specific error code indicating the nature of the failure. Safe for programmatic use.
error_message
string
Human-readable error message providing details about the failure.