Ask Bill!

User endpoints

API reference for user management endpoints

This page covers API endpoints related to user ids and user tokens, which are used by Plaid Check, Plaid Protect, Income, Guaranteed Payments, and Payment Initiation (including Variable Recurring Payments and Virtual Accounts), as well as by the Multi-Item Link flow.

Guides
New User APIsOverview of changes introduced in the new User APIs
Migrate to new User APIsMigration guide for existing Consumer Report and Income integrations on legacy User APIs
Endpoints
/user/createCreate a user ID
/user/getGet user details
/user/updateUpdate user data or enable an existing user for Plaid Check
/user/items/getReturn Items associated with a user
/user/items/associateAssociate Items with a user
/user/items/removeRemove Items associated with a User
/user/products/terminateTerminate user-based products
/user/transfer/limits/getRetrieve a user's guarantee limits
See also
/sandbox/user/reset_loginForce user into an error state for testing

Plaid introduced user_id-based APIs for new Plaid Check and Multi-Item Link integrations on December 10, 2025, and for new Income integrations on August 17, 2026. If you have an existing integration that uses user_token, you can continue to use it. Plaid Check, Multi-Item Link, and Income customers can also optionally migrate to the new User APIs to begin using user_id. New customers must use user_id.

To accommodate both flows, many Plaid API endpoints use either a user_id or a user_token. In these API requests, you should provide a user_token only if you have one; otherwise, provide a user_id. You do not need to provide both fields.

For more details on this change, see New User APIs.

User identifiers

There are three identifiers Plaid uses when working with users:

client_user_id: The unique identifier you provide to Plaid for each end user in your application. This is determined by you and will typically correspond to your application's primary key for a user record. It must not contain PII, such as a phone number, Social Security number, or email address.

user_id: Plaid-generated identifier, prefixed by usr_ and returned in responses from the User APIs and /link/token/create. Each user_id corresponds to a single client_user_id; calling /user/create repeatedly with the same client_user_id returns the same user_id. The user_id is used by new Plaid Check and Multi-Item Link customers who integrated on or after December 10, 2025, and new Income customers who integrated on or after August 17, 2026.

user_token — A Plaid-generated token for accessing the user. Applicable to Plaid Check and Multi-Item Link customers who integrated with /user/create before December 10, 2025, and Income customers who integrated before August 17, 2026. Note that user_tokens can also have corresponding legacy user_ids; these are not equivalent to the new usr_*-prefixed user_ids mentioned above. For more details, see New User APIs.

=*=*=*=

/user/create

Create user

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. In order to create a Plaid Check Consumer Report for a user, or to use Payment Initiation, Variable Recurring Payments, or Virtual Accounts, 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.

When using Payment Initiation, Variable Recurring Payments, or Virtual Accounts, the identity object must contain a name and either an email address or a phone number.

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.

/user/create

Request fields

client_id
stringstring

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
stringstring

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

Max length: 128
Min length: 1
identity
objectobject

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

name
objectobject

User name information.

given_name
requiredstringrequired, string

User's given name.

family_name
requiredstringrequired, string

User's family name.

date_of_birth
stringstring

The user's date of birth, to be provided in the format "yyyy-mm-dd".

Format: date
emails
[object][object]

The user's emails.

data
requiredstringrequired, string

User's email.

primary
requiredbooleanrequired, boolean

Indicates whether this is the primary email for the User.

phone_numbers
[object][object]

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
requiredstringrequired, string

User's phone number.

primary
requiredbooleanrequired, boolean

Indicates whether this is the primary phone number for the User.

addresses
[object][object]

The user's addresses.

street_1
stringstring

First line of street address.

street_2
stringstring

Second line of street address.

city
stringstring

City name.

region
stringstring

State, province or region.

country
requiredstringrequired, string

Country code.

postal_code
stringstring

Postal or ZIP code.

primary
requiredbooleanrequired, boolean

Indicates whether this is the primary address for the User.

id_numbers
[object][object]

The user's ID numbers.

value
requiredstringrequired, string

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.

type
requiredstringrequired, string

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.

Possible values: 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
consumer_report_user_identity
objectobject

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. 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
requiredstringrequired, string

The user's first name

last_name
requiredstringrequired, string

The user's last name

phone_numbers
required[string]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]required, [string]

The user's emails

ssn_full
stringstring

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
stringstring

The last 4 digits of the user's Social Security number.

Max length: 4
Min length: 4
date_of_birth
requiredstringrequired, string

To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers.

Format: date
primary_address
requiredobjectrequired, object

Data about the components comprising an address.

city
requiredstringrequired, string

The full city name

region
requiredstringrequired, string

The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

street
requiredstringrequired, string

The full street address Example: "564 Main Street, APT 15"

postal_code
requiredstringrequired, string

The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

country
requiredstringrequired, string

The ISO 3166-1 alpha-2 country code

with_upgraded_user
booleanboolean

If your integration with the User API predates December 10, 2025, set this field to true to opt into the New User APIs. When enabled, you can use the identity field instead of consumer_report_user_identity.

/user/create
const request = {
  client_user_id: "c0e2c4ee-b763-4af5-cfe9-46a46bce883d",
  identity: {
    name: {
      given_name: "Carmen",
      family_name: "Berzatto"
    },
    date_of_birth: "1987-01-31",
    emails: [
      { data: "carmy@example.com", primary: true },
      { data: "bear@example.com", primary: false }
    ],
    phone_numbers: [
      { data: "+13125551212", primary: true }
    ],
    addresses: [
      {
        street_1: "3200 W Armitage Ave",
        street_2: null,
        city: "Chicago",
        region: "IL",
        country: "US",
        postal_code: "60657",
        primary: true
      }
    ],
    id_numbers: [
      {
        value: "1234",
        type: "us_ssn_last_4"
      }
    ]
  }
};

try {
  const response = await client.userCreate(request);
} catch (error) {
}
/user/create

Response fields

user_token
stringstring

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.

user_id
stringstring

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.

request_id
stringstring

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object
{
  "user_id": "usr_9nSp2KuZ2x4JDw",
  "request_id": "Aim3b"
}
=*=*=*=

/user/get

Retrieve user identity and information

Get user details using a user_id. This endpoint only supports users that were created on the new user API flow, without a user_token. For more details, see New User APIs.

/user/get

Request fields

client_id
stringstring

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
stringstring

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_id
requiredstringrequired, string

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.

/user/get
const request = {
  user_id: "usr_9nSp2KuZ2x4JDw"
};

try {
  const response = await client.userGet(request);
} catch (error) {
}
/user/get

Response fields

request_id
stringstring

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

user_id
stringstring

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.

client_user_id
nullablestringnullable, string

Client provided user ID.

created_at
stringstring

Timestamp of user creation.

Format: date-time
updated_at
stringstring

Timestamp of last user update.

Format: date-time
identity
nullableobjectnullable, object

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

name
nullableobjectnullable, object

User name information.

given_name
stringstring

User's given name.

family_name
stringstring

User's family name.

date_of_birth
nullablestringnullable, string

The user's date of birth, to be provided in the format "yyyy-mm-dd".

Format: date
emails
[object][object]

The user's emails.

data
stringstring

User's email.

primary
booleanboolean

Indicates whether this is the primary email for the User.

phone_numbers
[object][object]

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
stringstring

User's phone number.

primary
booleanboolean

Indicates whether this is the primary phone number for the User.

addresses
[object][object]

The user's addresses.

street_1
nullablestringnullable, string

First line of street address.

street_2
nullablestringnullable, string

Second line of street address.

city
nullablestringnullable, string

City name.

region
nullablestringnullable, string

State, province or region.

country
stringstring

Country code.

postal_code
nullablestringnullable, string

Postal or ZIP code.

primary
booleanboolean

Indicates whether this is the primary address for the User.

id_numbers
[object][object]

The user's ID numbers.

value
stringstring

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.

type
stringstring

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.

Possible values: 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
Response Object
{
  "user_id": "usr_8c6ZbDAYjacUXF",
  "client_user_id": "uid_12345",
  "created_at": "2019-02-15T15:51:39Z",
  "updated_at": "2019-02-15T15:52:39Z",
  "request_id": "m8MDnv9okwxFNBV",
  "identity": {
    "name": {
      "given_name": "Alice",
      "family_name": "Johnson"
    },
    "date_of_birth": "1988-07-22",
    "emails": [
      {
        "data": "alice.johnson@example.com",
        "primary": true
      },
      {
        "data": "alice.j@workmail.com",
        "primary": false
      }
    ],
    "phone_numbers": [
      {
        "data": "+15551234567",
        "primary": true
      },
      {
        "data": "+15559876543",
        "primary": false
      }
    ],
    "addresses": [
      {
        "street_1": "123 Main St",
        "street_2": "Apt 4B",
        "city": "Anytown",
        "region": "CA",
        "country": "US",
        "postal_code": "90210",
        "primary": true
      }
    ],
    "id_numbers": [
      {
        "value": "1234",
        "type": "us_ssn_last_4"
      }
    ]
  }
}
=*=*=*=

/user/update

Update user information

This endpoint updates user information for an existing user_id or user_token. If an existing user_id or user_token is missing fields required for a given use case (e.g. creating a Consumer Report) use /user/update to add values for those fields.

Identity updates use merge semantics: provided fields overwrite existing ones; omitted fields remain unchanged.

/user/update

Request fields

client_id
stringstring

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
stringstring

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_id
stringstring

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.

identity
objectobject

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

name
objectobject

User name information.

given_name
requiredstringrequired, string

User's given name.

family_name
requiredstringrequired, string

User's family name.

date_of_birth
stringstring

The user's date of birth, to be provided in the format "yyyy-mm-dd".

Format: date
emails
[object][object]

The user's emails.

data
requiredstringrequired, string

User's email.

primary
requiredbooleanrequired, boolean

Indicates whether this is the primary email for the User.

phone_numbers
[object][object]

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
requiredstringrequired, string

User's phone number.

primary
requiredbooleanrequired, boolean

Indicates whether this is the primary phone number for the User.

addresses
[object][object]

The user's addresses.

street_1
stringstring

First line of street address.

street_2
stringstring

Second line of street address.

city
stringstring

City name.

region
stringstring

State, province or region.

country
requiredstringrequired, string

Country code.

postal_code
stringstring

Postal or ZIP code.

primary
requiredbooleanrequired, boolean

Indicates whether this is the primary address for the User.

id_numbers
[object][object]

The user's ID numbers.

value
requiredstringrequired, string

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.

type
requiredstringrequired, string

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.

Possible values: 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
user_token
stringstring

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.

consumer_report_user_identity
objectobject

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. 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
requiredstringrequired, string

The user's first name

last_name
requiredstringrequired, string

The user's last name

phone_numbers
required[string]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]required, [string]

The user's emails

ssn_full
stringstring

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
stringstring

The last 4 digits of the user's Social Security number.

Max length: 4
Min length: 4
date_of_birth
requiredstringrequired, string

To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers.

Format: date
primary_address
requiredobjectrequired, object

Data about the components comprising an address.

city
requiredstringrequired, string

The full city name

region
requiredstringrequired, string

The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

street
requiredstringrequired, string

The full street address Example: "564 Main Street, APT 15"

postal_code
requiredstringrequired, string

The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

country
requiredstringrequired, string

The ISO 3166-1 alpha-2 country code

/user/update
const request = {
  user_id: 'usr_9nSp2KuZ2x4JDw',
  identity: {
    name: {
      given_name: "Carmen",
      family_name: "Berzatto"
    },
    date_of_birth: "1987-01-31",
    emails: [
      { data: "carmy@example.com", primary: true },
      { data: "bear@example.com", primary: false }
    ],
    phone_numbers: [
      { data: "+13125551212", primary: true }
    ],
    addresses: [
      {
        street_1: "3200 W Armitage Ave",
        street_2: null,
        city: "Chicago",
        region: "IL",
        country: "US",
        postal_code: "60657",
        primary: true
      }
    ],
    id_numbers: [
      {
        value: "1234",
        type: "us_ssn_last_4"
      }
    ]
  }
};

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

Response fields

request_id
stringstring

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object
{
  "request_id": "Aim3b"
}
=*=*=*=

/user/items/get

Get Items associated with a User

Returns Items associated with a user_id, along with their corresponding statuses. Plaid associates an Item with a User when it has been successfully connected within a Link session initialized with that user_id.

/user/items/get

Request fields

client_id
stringstring

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
stringstring

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
stringstring

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.

user_id
stringstring

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.

/user/items/get
const request = {
  user_id: 'usr_9nSp2KuZ2x4JDw'
};

try {
  const response = await client.userItemsGet(request);
} catch (error) {
  // handle error
}
/user/items/get

Response fields

items
[object][object]
item_id
stringstring

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
nullablestringnullable, string

The Plaid Institution ID associated with the Item. Field is omitted for Items created without an institution connection, such as Items created via Same-Day Micro-deposits.

institution_name
nullablestringnullable, string

The name of the institution associated with the Item. Field is omitted for Items created without an institution connection, such as Items created via Same-Day Micro-deposits.

webhook
nullablestringnullable, string

The URL registered to receive webhooks for the Item. Empty string if no webhook is set.

auth_method
nullablestringnullable, string

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 their accounts, and will be omitted 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, null
error
nullableobjectnullable, object

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
stringstring

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, BASE_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, USER_ERROR, IDEMPOTENCY_ERROR, ASSETS_ERROR, CRA_MONITORING_ERROR, CREDIT_PROFILE_REPORT_ERROR, ENCOMPASS_ERROR, ENRICH_ERROR, FRAUD_INSIGHTS_ERROR, FREDDIE_MAC_ERROR, LINK_DELIVERY_ERROR, PROFILE_ERROR, RECURRING_TRANSACTIONS_ERROR, STATEMENTS_ERROR, TRANSFER_RECURRING_ERROR, TRANSFER_REFUND_ERROR, CRA_REPORT_ERROR, CRA_PARTNER_INSIGHTS_ERROR
error_code
stringstring

The particular error code. Safe for programmatic use.

error_code_reason
nullablestringnullable, string

The specific reason for the error code. Currently, reasons are only supported for OAuth-based item errors; the field is omitted 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
stringstring

A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

display_message
nullablestringnullable, string

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
stringstring

A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.

causes
arrayarray

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 be provided for the error_type ASSET_REPORT_ERROR or CHECK_REPORT_ERROR, and for the USER_ERROR codes USER_ITEM_ASSOCIATION_FAILED and USER_ITEM_REMOVAL_FAILED. causes will also not be populated inside an error nested within a warning object.

status
nullableintegernullable, integer

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
stringstring

The URL of a Plaid documentation page with more information about the error

suggested_action
nullablestringnullable, string

Suggested steps for resolving the error

required_account_subtypes
[string][string]

A list of the account subtypes that were requested via the account_filters parameter in /link/token/create. Currently only populated for NO_ACCOUNTS errors from Items with investments_auth as an enabled product.

provided_account_subtypes
[string][string]

A list of the account subtypes that were extracted but did not match the requested subtypes via the account_filters parameter in /link/token/create. Currently only populated for NO_ACCOUNTS errors from Items with investments_auth as an enabled product.

available_products
[string][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, cra_monitoring, cra_lend_score, cra_plaid_credit_score, cra_qualify, cra_home_lending, cra_lend_score_complete, cra_income_complete, layer, pay_by_bank, protect_linked_bank, protect_transactions
billed_products
[string][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, cra_monitoring, cra_lend_score, cra_plaid_credit_score, cra_qualify, cra_home_lending, cra_lend_score_complete, cra_income_complete, layer, pay_by_bank, protect_linked_bank, protect_transactions
products
[string][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, cra_monitoring, cra_lend_score, cra_plaid_credit_score, cra_qualify, cra_home_lending, cra_lend_score_complete, cra_income_complete, layer, pay_by_bank, protect_linked_bank, protect_transactions
consented_products
[string][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_lend_score, cra_partner_insights, cra_cashflow_insights, cra_monitoring, cra_lend_score_complete, cra_income_complete, layer
consent_expiration_time
nullablestringnullable, string

The date and time at which the Item's access consent will expire, in ISO 8601 format. If the Item does not have consent expiration scheduled, this field will be null. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the OAuth Guide.

Format: date-time
update_type
stringstring

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
paired_item_id
nullablestringnullable, string

The item_id of the Item that was created alongside this one when a single Link session used both Plaid Inc and Plaid Check products (see Using Plaid Check products alongside Plaid products). For a Plaid Inc Item, this is the paired Plaid Check Item, and the reverse for a Plaid Check Item. The field is omitted for Items that have no paired Item. It is also omitted if Plaid cannot look up the paired Item at request time, so do not treat its absence as proof that an Item is unpaired.

request_id
stringstring

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object
{
  "items": [
    {
      "available_products": [
        "balance",
        "auth"
      ],
      "billed_products": [
        "identity",
        "transactions"
      ],
      "error": null,
      "institution_id": "ins_109508",
      "institution_name": "First Platypus Bank",
      "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
      "update_type": "background",
      "webhook": "https://plaid.com/example/hook",
      "consent_expiration_time": null
    },
    {
      "available_products": [
        "balance",
        "identity",
        "payment_initiation",
        "transactions"
      ],
      "billed_products": [
        "assets",
        "auth"
      ],
      "error": null,
      "institution_id": "ins_109508",
      "institution_name": "First Platypus Bank",
      "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
      "update_type": "background",
      "webhook": "https://plaid.com/example/hook",
      "consent_expiration_time": null
    }
  ],
  "request_id": "m8MDnv9okwxFNBV"
}
=*=*=*=

/user/items/associate

This endpoint is currently in early availability. To request access, contact your account manager or submit a product access support ticket.

Associate Items to a User

Associates Items with a user_id. If an Item is already associated with a different user_id, calling this endpoint will disassociate it from that User and reassociate it with the target User instead. A single request can associate up to 100 Items.

/user/items/associate

Request fields

client_id
stringstring

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
stringstring

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_id
requiredstringrequired, string

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.

item_ids
required[string]required, [string]

An array of item_ids to be associated with the user_id.

/user/items/associate
const request = {
  user_id: 'usr_9nSp2KuZ2x4JDw',
  item_ids: ['eVBnVMp7zdTJLkRNr33Rs6zr27KeyPMNPqfX1'],
};

try {
  const response = await client.userItemsAssociate(request);
} catch (error) {
}
/user/items/associate

Response fields

request_id
stringstring

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object
{
  "request_id": "m8MDnv9okwxFNBV"
}
=*=*=*=

/user/items/remove

This endpoint is currently in early availability. To request access, contact your account manager or submit a product access support ticket.

Remove Items from a User

Removes specific Items associated with a user. It is equivalent to calling /item/remove on each Item individually, but supports use cases (such as Plaid Check) where access tokens are not available. All specified Items must belong to the user or the entire operation fails. Similar to /item/remove, this deletes Item product data and terminates billing on the Item's products. Once removed, Items cannot be reconnected without going through Link again. This endpoint is not intended to remove all data for a user, as it will only remove Items and no other data for the user. If the user has any user-based recurring subscription products (Financial Management, Plaid Protect, or CRA Servicing) and is deleting their account with your product, also call /user/products/terminate to end those subscriptions; per-Item billing is already terminated by this endpoint. For a user initiated data deletion request, see the Consumer Service Center to revoke access to data.

/user/items/remove

Request fields

client_id
stringstring

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
stringstring

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
stringstring

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.

user_id
stringstring

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.

item_ids
required[string]required, [string]

An array of item_ids to be deleted. All Items for removal must be currently associated with the provided user_id or user_token. Otherwise, the entire operation will error and no Items will be deleted.

/user/items/remove
const request = {
  user_id: 'usr_9nSp2KuZ2x4JDw',
  item_ids: ['eVBnVMp7zdTJLkRNr33Rs6zr27KeyPMNPqfX1'],
};

try {
  const response = await client.userItemsRemove(request);
} catch (error) {
}
/user/items/remove

Response fields

request_id
stringstring

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object
{
  "request_id": "m8MDnv9okwxFNBV"
}
=*=*=*=

/user/products/terminate

Terminate products for a user

Terminates Financial Management, Plaid Protect, and Servicing products associated with a user_id. Use this endpoint when offboarding a user or ending their subscriptions. Item access tokens are not required.

For Financial Management products, including Transactions, Liabilities, and Investments, this endpoint removes each associated Item that contains one of these products. Removal makes the Item inaccessible, initiates deletion of its product data, and terminates its per-Item subscription billing. The entire Item is removed, including access to any other products on that Item. To connect the accounts again, the user must complete Link to create a new Item.

If the user has at least one associated Item and every associated Item contains a Financial Management product, this endpoint also removes the associated Plaid user. The removed user_id can no longer be used to access the user.

For Plaid Protect, this endpoint terminates Protect products. For Servicing, it cancels the subscription and preserves CRA Items and historical data for future report requests.

To learn how terminating products affects billing, see Billing.

/user/products/terminate

Request fields

client_id
stringstring

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
stringstring

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_id
requiredstringrequired, string

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.

reason_code
requiredstringrequired, string

The reason for terminating products.

FRAUD_FIRST_PARTY: The end user who owns the connected bank account committed fraud using their real identity

FRAUD_FALSE_IDENTITY: The connection was created using a false or stolen identity

FRAUD_ABUSE: The end user is abusing the client's service or platform (for example, automation or excessive retries) through their connected account

FRAUD_OTHER: Fraud-related, but not covered by the specific fraud categories above; reason_note should clarify

FRAUD_TRANSACTION: Fraud occurred at the transaction level, such as an unauthorized transaction, card testing, chargeback, ACH return, or dispute

CONSUMER_LOAN_PAID_OFF: The end user paid off their loan and no longer needs the product

CONSUMER_ACCOUNT_CLOSED: The end user closed their account with the client and no longer needs the product

CONSUMER_CHARGE_OFF: The end user's account has been charged off

CONSUMER_PAYMENT_METHOD_SWITCHED: The end user switched to a different payment method and no longer needs the product

USER_OFFBOARDING: The user is offboarding from the client's service or platform

DUPLICATE_ITEM: This Item is a duplicate of another active Item for the same user

BILLING_TERMINATION: The client's billing or subscription relationship with the end user has ended

OTHER: None of the above; reason_note should clarify

Possible values: FRAUD_FIRST_PARTY, FRAUD_FALSE_IDENTITY, FRAUD_ABUSE, FRAUD_OTHER, FRAUD_TRANSACTION, CONSUMER_LOAN_PAID_OFF, CONSUMER_ACCOUNT_CLOSED, CONSUMER_CHARGE_OFF, CONSUMER_PAYMENT_METHOD_SWITCHED, USER_OFFBOARDING, DUPLICATE_ITEM, BILLING_TERMINATION, OTHER
reason_note
stringstring

Additional context or details about the reason for terminating user-based products. Personally identifiable information, such as an email address or phone number, should not be included in the reason_note.

Max length: 512
/user/products/terminate
const request = {
  user_id: 'usr_9nSp2KuZ2x4JDw',
  reason_code: 'CONSUMER_ACCOUNT_CLOSED',
  reason_note: 'User closed account with client.',
};

try {
  const response = await client.userProductsTerminate(request);
} catch (error) {
}
/user/products/terminate

Response fields

request_id
stringstring

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object
{
  "request_id": "TxlxEcCmP9HTTT"
}
=*=*=*=

/user/transfer/limits/get

For integration guidance, see User limits for Guaranteed Payments.

Retrieve a user's transfer limits

Retrieve the user's current Guaranteed ACH per-transaction limit and configured daily, weekly, and monthly ceilings. Amounts are returned as decimal strings in dollars with two decimal places and an ISO currency code. Access to this endpoint must be enabled for your client.

/user/transfer/limits/get

Request fields

client_id
stringstring

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
stringstring

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_id
requiredstringrequired, string

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.

/user/transfer/limits/get
curl -X POST https://production.plaid.com/user/transfer/limits/get \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "${PLAID_CLIENT_ID}",
    "secret": "${PLAID_SECRET}",
    "user_id": "usr_8c3ZbDBYjaqUXZ"
  }'
/user/transfer/limits/get

Response fields

guarantee_limits
objectobject

The user's Guaranteed ACH debit limits. Daily, weekly, and monthly limits are configured ceilings, not remaining capacity. Each rolling limit is null when no ceiling is enabled for that window.

transaction_limit
objectobject

The user's current per-transaction guarantee limit. A zero-dollar limit is returned with a value of "0.00".

value
stringstring

The limit in dollars, formatted as a decimal string with two digits of precision (for example, "150.25" represents $150.25).

iso_currency_code
stringstring

The ISO-4217 currency code of the limit. Currently always USD.

daily_limit
nullableobjectnullable, object

A transfer limit amount and its currency, or null when the limit is not configured.

value
stringstring

The limit in dollars, formatted as a decimal string with two digits of precision (for example, "150.25" represents $150.25).

iso_currency_code
stringstring

The ISO-4217 currency code of the limit. Currently always USD.

weekly_limit
nullableobjectnullable, object

A transfer limit amount and its currency, or null when the limit is not configured.

value
stringstring

The limit in dollars, formatted as a decimal string with two digits of precision (for example, "150.25" represents $150.25).

iso_currency_code
stringstring

The ISO-4217 currency code of the limit. Currently always USD.

monthly_limit
nullableobjectnullable, object

A transfer limit amount and its currency, or null when the limit is not configured.

value
stringstring

The limit in dollars, formatted as a decimal string with two digits of precision (for example, "150.25" represents $150.25).

iso_currency_code
stringstring

The ISO-4217 currency code of the limit. Currently always USD.

request_id
stringstring

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Response Object
{
  "guarantee_limits": {
    "transaction_limit": {
      "value": "150.25",
      "iso_currency_code": "USD"
    },
    "daily_limit": {
      "value": "5000.00",
      "iso_currency_code": "USD"
    },
    "weekly_limit": {
      "value": "10000.00",
      "iso_currency_code": "USD"
    },
    "monthly_limit": null
  },
  "request_id": "mdqfuVxeoza6mhu"
}