User endpoints

API reference for User tokens

This page covers API endpoints related to user tokens, which are used by Plaid Check and Income, as well as by the Multi-Item Link flow.

Endpoints
/user/createCreate a user ID and token
/user/updateUpdate user data or enable an existing user token for Plaid Check
/user/removeRemove the user and their associated Items
/user/items/getReturn Items associated with a user
See also
/sandbox/user/reset_loginForce user into an error state for testing

/user/create

Create user

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.
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.

user/create
Request fields
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
requiredstring
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.

Max length: 128
Min length: 1
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
requiredstring
The user's first name
last_name
requiredstring
The user's last name
phone_numbers
required[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[string]
The user's emails
ssn_last_4
string
The last 4 digits of the user's social security number.

Max length: 4
Min length: 4
date_of_birth
string
To be provided in the format "yyyy-mm-dd". This field is required for any clients who became Plaid Check customers on or after Oct 1, 2024. This field will be required for all Plaid Check customers as of Feb 1, 2025.

Format: date
primary_address
requiredobject
Data about the components comprising an address.
city
requiredstring
The full city name
region
requiredstring
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
requiredstring
The full street address Example: "564 Main Street, APT 15"
postal_code
requiredstring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
requiredstring
The ISO 3166-1 alpha-2 country code
1const request = {
2  client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d',
3  consumer_report_user_identity: {
4    first_name: "Carmen",
5    last_name: "Berzatto",
6    phone_numbers: ["+13125551212"],
7    emails: ["carmy@example.com", "bear@example.com"],
8    ssn_last_4: "1234",
9    date_of_birth: "1987-01-31",
10    primary_address: {
11      city: "Chicago",
12      region: "IL",
13      street: "3200 W Armitage Ave",
14      postal_code: "60657",
15      country: "US"      
16    }
17  }
18};
19

20try {
21  const response = await client.userCreate(request);
22} catch (error) {
23  // handle error
24}
user/create

Response fields and example

user_token
string
The user token associated with the User data is being requested for.
user_id
string
The Plaid user_id of the User associated with this webhook, warning, or error.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
3  "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
4  "request_id": "Aim3b"
5}

/user/update

Update user information

This endpoint is used to update user information associated with an existing user_token. It can also be used to enable an existing user_token for use with Consumer Reports by Plaid Check, by adding a consumer_report_user_identity object to the user.

user/update
Request fields
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.
user_token
requiredstring
The user token associated with the User data is being requested for.
consumer_report_user_identity
requiredobject
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
requiredstring
The user's first name
last_name
requiredstring
The user's last name
phone_numbers
required[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[string]
The user's emails
ssn_last_4
string
The last 4 digits of the user's social security number.

Max length: 4
Min length: 4
date_of_birth
string
To be provided in the format "yyyy-mm-dd". This field is required for any clients who became Plaid Check customers on or after Oct 1, 2024. This field will be required for all Plaid Check customers as of Feb 1, 2025.

Format: date
primary_address
requiredobject
Data about the components comprising an address.
city
requiredstring
The full city name
region
requiredstring
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
requiredstring
The full street address Example: "564 Main Street, APT 15"
postal_code
requiredstring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
requiredstring
The ISO 3166-1 alpha-2 country code
1const request = {
2  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
3  consumer_report_user_identity: {
4    first_name: "Carmen",
5    last_name: "Berzatto",
6    phone_numbers: ["+13125551212"],
7    emails: ["carmy@example.com", "bear@example.com"],
8    ssn_last_4: "1234",
9    date_of_birth: "1987-01-31",
10    primary_address: {
11      city: "Chicago",
12      region: "IL",
13      street: "3200 W Armitage Ave",
14      postal_code: "60657",
15      country: "US"      
16    }
17  }
18};
19

20try {
21  const response = await client.userUpdate(request);
22} catch (error) {
23  // handle error
24}
user/update

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "Aim3b"
3}

/user/remove

Remove user

/user/remove deletes a user token and and associated information, including any Items associated with the token. Any subsequent calls to retrieve information using the same user token will result in an error stating the user does not exist.

user/remove
Request fields
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.
user_token
requiredstring
The user token associated with the User data is being requested for.
1const request = {
2  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab'
3};
4

5try {
6  const response = await client.userRemove(request);
7} catch (error) {
8  // handle error
9}
user/remove

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "Aim3b"
3}

/user/items/get

Get Items associated with a User

Returns Items associated with a User along with their corresponding statuses.

user/items/get
Request fields
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.
user_token
requiredstring
The user token associated with the User data is being requested for.
1const request = {
2  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab'
3};
4

5try {
6  const response = await client.userItemsGetRequest(request);
7} catch (error) {
8  // handle error
9}
user/items/get

Response fields and example

items
[object]
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
nullablestring
The Plaid Institution ID associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.
institution_name
nullablestring
The name of the institution associated with the Item. Field is null for Items created without an institution connection, such as Items created via Same Day Micro-deposits.
webhook
nullablestring
The URL registered to receive webhooks for the Item.
auth_method
nullablestring
The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be null otherwise. For info about the various flows, see our Auth coverage documentation.
INSTANT_AUTH: The Item's Auth data was provided directly by the user's institution connection.
INSTANT_MATCH: The Item's Auth data was provided via the Instant Match fallback flow.
AUTOMATED_MICRODEPOSITS: The Item's Auth data was provided via the Automated Micro-deposits flow.
SAME_DAY_MICRODEPOSITS: The Item's Auth data was provided via the Same Day Micro-deposits flow.
INSTANT_MICRODEPOSITS: The Item's Auth data was provided via the Instant Micro-deposits flow.
DATABASE_MATCH: The Item's Auth data was provided via the Database Match flow.
DATABASE_INSIGHTS: The Item's Auth data was provided via the Database Insights flow.
TRANSFER_MIGRATED: The Item's Auth data was provided via /transfer/migrate_account.
INVESTMENTS_FALLBACK: The Item's Auth data for Investments Move was provided via a fallback flow.

Possible values: INSTANT_AUTH, INSTANT_MATCH, AUTOMATED_MICRODEPOSITS, SAME_DAY_MICRODEPOSITS, INSTANT_MICRODEPOSITS, DATABASE_MATCH, DATABASE_INSIGHTS, TRANSFER_MIGRATED, INVESTMENTS_FALLBACK
error
nullableobject
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: 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, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
nullablestring
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullablestring
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In this product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullablestring
Suggested steps for resolving the error
available_products
[string]
A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with billed_products.

Possible values: assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
billed_products
[string]
A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with available_products. Note - billed_products is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as balance, will not appear here.

Possible values: assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
products
[string]
A list of products added to the Item. In almost all cases, this will be the same as the billed_products field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before /asset_report/create has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in products but not in billed_products.

Possible values: assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank
consented_products
[string]
A list of products that the user has consented to for the Item via Data Transparency Messaging. This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product.

Possible values: assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, transactions, income, income_verification, transfer, employment, recurring_transactions, signal, statements, processor_payments, processor_identity, cra_base_report, cra_income_insights, cra_partner_insights, cra_cashflow_insights, layer
consent_expiration_time
nullablestring
The date and time at which the Item's access consent will expire, in ISO 8601 format

Format: date-time
update_type
string
Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication.
background - Item can be updated in the background
user_present_required - Item requires user interaction to be updated

Possible values: background, user_present_required
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "items": [
3    {
4      "available_products": [
5        "balance",
6        "auth"
7      ],
8      "billed_products": [
9        "identity",
10        "transactions"
11      ],
12      "error": null,
13      "institution_id": "ins_109508",
14      "institution_name": "First Platypus Bank",
15      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
16      "update_type": "background",
17      "webhook": "https://plaid.com/example/hook",
18      "consent_expiration_time": null
19    },
20    {
21      "available_products": [
22        "balance",
23        "identity",
24        "payment_initiation",
25        "transactions"
26      ],
27      "billed_products": [
28        "assets",
29        "auth"
30      ],
31      "error": null,
32      "institution_id": "ins_109508",
33      "institution_name": "First Platypus Bank",
34      "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
35      "update_type": "background",
36      "webhook": "https://plaid.com/example/hook",
37      "consent_expiration_time": null
38    }
39  ],
40  "request_id": "m8MDnv9okwxFNBV"
41}