Users

The users resource represents a person who accesses Marqeta-administered funds via a Marqeta card (whether physical or virtual). This endpoint enables you to create and manage users on the Marqeta platform. This resource stores user attributes such as name, address, and date of birth, as well as financial information such as balances. By default, every user automatically has a general purpose account (GPA) that is used for the funding of transfers and is therefore an account holder. Note that account balances reside at the account holder level — there are no separate account or balance objects. You can use the /users endpoint to create parent-child relationships between two users (where one user is the parent and the other is the child) or between a business and a user (where the business is the parent and the user is the child). This relationship provides reporting to the parent about how cards of children are used and enables the parent to monitor and even restrict card usage.

Note
A user can simultaneously be a child of a business and a parent of other users if the user is not configured to use a parent’s account balances and the user’s child is configured to use a parent’s account balances. For more information on account holders, see About Account Holders.

Create user

Action: POST
Endpoint: /users This endpoint enables you to create a user. A new user’s initial status depends on the Know Your Customer (KYC) requirements of the program or associated account holder group.

KYC Required	Initial User Status	User Active on Creation	User Limitations
Always	`UNVERIFIED`	Optional	Cannot load funds; cannot activate cards.
Conditionally	`LIMITED`	Optional	Restricted by rules in `accountholdergroups.pre_kyc_controls`.
Never	`ACTIVE`	Required	None.

Note
Use the /usertransitions endpoints to transition user resources between statuses and to view the history of a user’s status. Do not set the value of the user.active field directly. For more information on status changes, see Create User Transition.

To perform KYC verification on users, the user object must have the following fields configured:

first_name (legal first name only, no prefixes)
last_name (legal last name only, no suffixes)
address1 (cannot be a PO Box)
city
state
postal_code
country
birth_date
identifications
phone (required in some cases)
email (required in some cases)

Note
The identifications requirement depends on your program’s configuration. To determine if you should provide a full or abbreviated identification number, contact your Marqeta representative. KYC verification requires the full Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN) of the user.

To create a child user, you must identify the parent user or business and determine whether the child user shares an account with the parent. The parent must be an existing user or business. On the child user, set the parent_token field to the value of the parent’s token field. If either the parent or the grandparent is a business, a business_token field is added to the user. This field’s value is set to the token of either the parent or grandparent (whichever is the business). The uses_parent_account field determines whether the child shares balances with the parent (true) or whether the child balances are independent of the parent (false). If you do not specify a value for uses_parent_account, it is set to false by default (the user does not share the parent’s balance) and returned in the response body. This field cannot be updated, so you must decide upon creation whether the child user shares the parent balance. Sharing an account with a parent user affects how the child user interacts with cards as follows:

A child user cannot spend funds if its parent is not active.
An active child user can activate cards, whether the parent is active or not.

Request body

Fields	Description
account_holder_group_token string Optional	Associates the specified account holder group with the cardholder. Send a `GET` request to `/accountholdergroups` to retrieve account holder group tokens. Allowable Values: 36 char max
active boolean Optional	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. NOTE: Do not set the value of the `user.active` field directly. Instead, use the `/usertransitions` endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition. Allowable Values: `true`, `false`
address1 string Optional	Cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
address2 string Optional	Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
birth_date string Optional	Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd
birth_place string Optional	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
city string Optional	City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
company string Optional	Company name. Allowable Values: 255 char max
corporate_card_holder boolean Optional	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false` Default value: `false`
country string Optional	Country where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max NOTE:ISO alpha-2 country code required for KYC verification. `US`, for example.
email string Optional	Valid email address of the cardholder. This value must be unique among users. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide an email address, contact your Marqeta representative. Allowable Values: 1–255 chars
first_name string Optional	Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
gender string Optional	Gender of the cardholder. Allowable Values: `F`, `M`
honorific string Optional	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
id_card_expiration_date string Optional	Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd
id_card_number string Optional	Cardholder’s identification card number. Allowable Values: 255 char max
identifications array of objects Optional	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
identifications[].expiration_date string Optional	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
identifications[].type string Required	Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based user cardholder KYC verification, using the `SSN` type. Full Employer Identification Number (EIN) is required for business cardholder KYC verification, using the `BUSINESS_TAX_ID` or `BUSINESS_NUMBER` type. For business directors, use one of SSN, TIN, SIN, or NIN. Nine digits only, no delimiters. `123456789`, for example. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
identifications[].value string Optional	Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789
ip_address string Optional	Cardholder’s IP address. Allowable Values: 39 char max
last_name string Optional	Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
metadata object Optional	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`.
middle_name string Optional	Cardholder’s middle name. Allowable Values: 40 char max
nationality string Optional	Cardholder’s nationality. Allowable Values: 255 char max
notes string Optional	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
parent_token string Optional	Unique identifier of the parent user or business resource. Send a `GET` request to `/users` to retrieve user resource tokens or to `/businesses` to retrieve business resource tokens. Required if `uses_parent_account = true`. This user or business is configured as the parent of the current user. Allowable Values: 1–36 chars
passport_expiration_date string Optional	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
passport_number string Optional	Cardholder’s passport number. Allowable Values: 40 char max
password string Optional	Password to the cardholder’s user account on the Marqeta platform. - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: @``#``$``%``!``^``&````(``) \\``_``+``~``-``=``[``]``\{``} ,``;``:``'``"``.``/``<``>``?` Allowable Values:* 255 char max
phone string Optional	Telephone number of the cardholder (including area code), prepended by the `+` symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide a phone number, contact your Marqeta representative. Allowable Values: 255 char max Format: +15105551212 or +35552260859
postal_code string Optional	Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max
ssn string Optional	Cardholder’s Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). Allowable Values: Nine digits only, no delimiters. `123456789`, for example.
state string Optional	State or province where the cardholder resides. NOTE:Valid two-character abbreviation required for KYC verification (US-based cardholders only). Allowable Values: 32 char max
title string Optional	Professional title of the cardholder, such as Chief Comptroller. NOTE: Do not use this field for honorific titles such as Mr., Mrs., Miss, Ms., Mx., Sir, or Dame. Instead, add these to the `honorific` field. Allowable Values: 255 char max
token string Optional	Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
uses_parent_account boolean Optional	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). If set to `true`, you must also include a `parent_token` in the request. This value cannot be updated. Allowable Values: `true`, `false` Default value: `false`

Sample request body

JSON

{
  "first_name": "Jane",
  "last_name": "Doe",
  "token": "my_user_01",
  "email": "jane.doe@company.com",
  "title": "Chief Comptroller",
  "birth_place": "US",
  "password": "P@ssw0rd",
  "identifications": [
    {
      "type": "SSN",
      "value": "111234444"
    }
  ],
  "birth_date": "1991-01-01",
  "address1": "1234 Grove Street",
  "city": "Berkeley",
  "state": "CA",
  "country": "USA",
  "postal_code": "94702",
  "phone": "15105551212",
  "gender": "F",
  "uses_parent_account": false,
  "metadata": {
    "notification_email": "jane.doe@home.com",
    "notification_language": "spa",
    "authentication_question1": "What was your first job?",
    "authentication_question2": "What make was your first car?",
    "authentication_question3": "What is your favorite color?",
    "authentication_answer1": "Cashier",
    "authentication_answer2": "Trabant",
    "authentication_answer3": "Blue"
  }
}

Response body

Fields	Description
account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Allowable Values: 36 char max
active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. Allowable Values: `true`, `false`
address1 string Conditionally returned	Cardholder’s address. Allowable Values: 255 char max
address2 string Conditionally returned	Additional address information for the cardholder. Allowable Values: 255 char max
authentication object Conditionally returned	Contains the cardholder’s email address and password information. Allowable Values: `email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time`
authentication.email_verified boolean Conditionally returned	Specifies whether the email address has been verified. Allowable Values: `true`, `false`
authentication.email_verified_time datetime Conditionally returned	Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
authentication.last_password_update_channel string Conditionally returned	Specifies the channel through which the password was last changed. Allowable Values: `USER_CHANGE`, `USER_RESET`
authentication.last_password_update_time datetime Conditionally returned	Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
birth_date string Conditionally returned	Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd
birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
business_token string Conditionally returned	Unique identifier of the business resource. Allowable Values: Existing business resource token
city string Conditionally returned	City where the cardholder resides. Allowable Values: 40 char max
company string Conditionally returned	Company name. Allowable Values: 255 char max
corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false`
country string Conditionally returned	Country where the cardholder resides. Allowable Values: 40 char max
created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
email string Conditionally returned	Valid email address of the cardholder. Allowable Values: 1–255 chars
first_name string Conditionally returned	Cardholder’s first name. Allowable Values: 40 char max
gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd
id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
identifications[].type string Conditionally returned	Type of identification. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max
ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
last_modified_time datetime Returned	Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
last_name string Conditionally returned	Cardholder’s last name. Allowable Values: 40 char max
metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`
middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars
passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
phone string Conditionally returned	Cardholder’s telephone number. Allowable Values: 255 char max
postal_code string Conditionally returned	Postal code of the cardholder’s address. Allowable Values: 10 char max
ssn string Conditionally returned	Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
state string Conditionally returned	State or province where the cardholder resides. Allowable Values: 2 char max
status string Conditionally returned	Specifies the status of the cardholder on the Marqeta platform. Allowable Values: `UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED`
title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier of the cardholder. Allowable Values: 1–36 chars
uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). Allowable Values: `true`, `false`
zip string Conditionally returned	United States ZIP code of the cardholder’s address. Allowable Values: 10 char max

Sample response body

JSON

{
  "token": "my_user_01",
  "active": true,
  "gender": "F",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe6@company.com",
  "title": "Chief Comptroller",
  "birth_place": "US",
  "address1": "1234 Grove Street",
  "city": "Berkeley",
  "state": "CA",
  "zip": "94702",
  "country": "USA",
  "phone": "15105551212",
  "uses_parent_account": false,
  "ssn": "5555",
  "corporate_card_holder": false,
  "password": "P@ssw0rd",
  "created_time": "2023-03-26T20:21:24Z",
  "last_modified_time": "2023-03-26T20:21:24Z",
  "metadata": {
    "notification_email": "jane.doe@home.com",
    "notification_language": "spa",
    "authentication_question1": "What was your first job?",
    "authentication_question2": "What make was your first car?",
    "authentication_question3": "What is your favorite color?",
    "authentication_answer1": "Cashier",
    "authentication_answer2": "Trabant",
    "authentication_answer3": "Blue"
  },
  "account_holder_group_token": "DEFAULT_AHG",
  "status": "ACTIVE",
  "birth_date": "1991-01-01"
}

List users

Action: GET
Endpoint: /users To return an array of all of a program’s users, send a GET request to the /users endpoint. This endpoint supports field filtering and pagination. To narrow your result set to users that match certain criteria, see the Search users endpoint. The business_token field is conditionally returned in the response (it cannot be set through the API). You can use this field in conjunction with the parent_token field to determine whether the user has a parent or grandparent that is a business:

parent_token	business_token	Description
Not populated	Not populated	User does not have a parent.
Populated	Not populated	User’s parent is a user.
Populated; matches `business_token`	Populated; matches `parent_token`	User’s parent is a business.
Populated; does not match `business_token`	Populated; does not match `parent_token`	User’s parent is a user and their grandparent is a business.

URL query parameters

Fields	Description
count integer Optional	Number of user resources to retrieve. Allowable Values: 1-10 Default value: 5
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0
search_type string Optional	Search type. Allowable Values: `query_then_fetch`, `dfs_query_then_fetch`
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-lastModifiedTime`

Response body

Fields	Description
count integer Conditionally returned	Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of user objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more user objects
data[].account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Send a `GET` request to `/accountholdergroups` to retrieve account holder group tokens. Allowable Values: 36 char max
data[].active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. NOTE: Do not set the value of the `user.active` field directly. Instead, use the `/usertransitions` endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition. Allowable Values: `true`, `false`
data[].address1 string Conditionally returned	Cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
data[].address2 string Conditionally returned	Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
data[].birth_date string Conditionally returned	Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd
data[].birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
data[].city string Conditionally returned	City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].company string Conditionally returned	Company name. Allowable Values: 255 char max
data[].corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false` Default value: `false`
data[].country string Conditionally returned	Country where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max NOTE:ISO alpha-2 country code required for KYC verification. `US`, for example.
data[].email string Conditionally returned	Valid email address of the cardholder. This value must be unique among users. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide an email address, contact your Marqeta representative. Allowable Values: 1–255 chars
data[].first_name string Conditionally returned	Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
data[].honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
data[].id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd
data[].id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
data[].identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
data[].identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
data[].identifications[].type string Returned	Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based user cardholder KYC verification, using the `SSN` type. Full Employer Identification Number (EIN) is required for business cardholder KYC verification, using the `BUSINESS_TAX_ID` or `BUSINESS_NUMBER` type. For business directors, use one of SSN, TIN, SIN, or NIN. Nine digits only, no delimiters. `123456789`, for example. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
data[].identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789
data[].ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
data[].last_name string Conditionally returned	Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`.
data[].middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
data[].nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
data[].notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
data[].parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Send a `GET` request to `/users` to retrieve user resource tokens or to `/businesses` to retrieve business resource tokens. Required if `uses_parent_account = true`. This user or business is configured as the parent of the current user. Allowable Values: 1–36 chars
data[].passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
data[].passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
data[].password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: @``#``$``%``!``^``&````(``) \\``_``+``~``-``=``[``]``\{``} ,``;``:``'``"``.``/``<``>``?` Allowable Values:* 255 char max
data[].phone string Conditionally returned	Telephone number of the cardholder (including area code), prepended by the `+` symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide a phone number, contact your Marqeta representative. Allowable Values: 255 char max Format: +15105551212 or +35552260859
data[].postal_code string Conditionally returned	Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max
data[].ssn string Conditionally returned	Cardholder’s Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). Allowable Values: Nine digits only, no delimiters. `123456789`, for example.
data[].state string Conditionally returned	State or province where the cardholder resides. NOTE:Valid two-character abbreviation required for KYC verification (US-based cardholders only). Allowable Values: 32 char max
data[].title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. NOTE: Do not use this field for honorific titles such as Mr., Mrs., Miss, Ms., Mx., Sir, or Dame. Instead, add these to the `honorific` field. Allowable Values: 255 char max
data[].token string Conditionally returned	Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
data[].uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). If set to `true`, you must also include a `parent_token` in the request. This value cannot be updated. Allowable Values: `true`, `false` Default value: `false`
end_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_user_01",
      "active": true,
      "gender": "F",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@company.com",
      "address1": "1234 Grove Street",
      "city": "Berkeley",
      "state": "CA",
      "postal_code": "94702",
      "country": "USA",
      "phone": "15105551212",
      "uses_parent_account": false,
      "password": "P@ssw0rd",
      "created_time": "2022-08-16T19:43:02Z",
      "last_modified_time": "2022-08-16T19:43:02Z",
      "metadata": {
        "notification_email": "jane.doe@home.com",
        "notification_language": "spa",
        "authentication_question1": "What was your first job?",
        "authentication_question2": "What make was your first car?",
        "authentication_question3": "What is your favorite color?",
        "authentication_answer1": "Cashier",
        "authentication_answer2": "Trabant",
        "authentication_answer3": "Blue"
      },
      "account_holder_group_token": "DEFAULT_AHG",
      "status": "ACTIVE",
      "identifications": [
        {
          "type": "SSN",
          "value": "5555"
        }
      ],
      "birth_date": "1991-01-01"
    },
    {
      "token": "my_user_02",
      "active": true,
      "gender": "M",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@company.com",
      "address1": "2345 Main Street",
      "city": "Berkeley",
      "state": "CA",
      "postal_code": "94702",
      "country": "USA",
      "phone": "15105551212",
      "uses_parent_account": false,
      "password": "my-password",
      "created_time": "2023-03-14T00:45:00Z",
      "last_modified_time": "2023-03-14T00:45:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "account_holder_group_token": "DEFAULT_AHG",
      "status": "ACTIVE",
      "identifications": [
        {
          "type": "SSN",
          "value": "4444"
        }
      ],
      "birth_date": "1992-02-02"
    }
  ]
}

Retrieve user

Action: GET
Endpoint: /users/{token} To retrieve a specific user, send a GET request to the /users/{token} endpoint. Include the user token path parameter to specify the user to return. The business_token field is conditionally returned in the response (it cannot be set through the API). You can use this field in conjunction with the parent_token field to determine whether the user has a parent or grandparent that is a business:

parent_token	business_token	Description
Not populated	Not populated	User does not have a parent.
Populated	Not populated	User’s parent is a user.
Populated; matches `business_token`	Populated; matches `parent_token`	User’s parent is a business.
Populated; does not match `business_token`	Populated; does not match `parent_token`	User’s parent is a user and their grandparent is a business.

This endpoint supports field filtering.

URL path parameters

Fields	Description
token string Required	Unique identifier of the user resource. Allowable Values: Existing user resource token

URL query parameters

Fields	Description
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank

Response body

Fields	Description
account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Allowable Values: 36 char max
active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. Allowable Values: `true`, `false`
address1 string Conditionally returned	Cardholder’s address. Allowable Values: 255 char max
address2 string Conditionally returned	Additional address information for the cardholder. Allowable Values: 255 char max
authentication object Conditionally returned	Contains the cardholder’s email address and password information. Allowable Values: `email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time`
authentication.email_verified boolean Conditionally returned	Specifies whether the email address has been verified. Allowable Values: `true`, `false`
authentication.email_verified_time datetime Conditionally returned	Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
authentication.last_password_update_channel string Conditionally returned	Specifies the channel through which the password was last changed. Allowable Values: `USER_CHANGE`, `USER_RESET`
authentication.last_password_update_time datetime Conditionally returned	Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
birth_date string Conditionally returned	Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd
birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
business_token string Conditionally returned	Unique identifier of the business resource. Allowable Values: Existing business resource token
city string Conditionally returned	City where the cardholder resides. Allowable Values: 40 char max
company string Conditionally returned	Company name. Allowable Values: 255 char max
corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false`
country string Conditionally returned	Country where the cardholder resides. Allowable Values: 40 char max
created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
email string Conditionally returned	Valid email address of the cardholder. Allowable Values: 1–255 chars
first_name string Conditionally returned	Cardholder’s first name. Allowable Values: 40 char max
gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd
id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
identifications[].type string Conditionally returned	Type of identification. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max
ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
last_modified_time datetime Returned	Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
last_name string Conditionally returned	Cardholder’s last name. Allowable Values: 40 char max
metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`
middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars
passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
phone string Conditionally returned	Cardholder’s telephone number. Allowable Values: 255 char max
postal_code string Conditionally returned	Postal code of the cardholder’s address. Allowable Values: 10 char max
ssn string Conditionally returned	Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
state string Conditionally returned	State or province where the cardholder resides. Allowable Values: 2 char max
status string Conditionally returned	Specifies the status of the cardholder on the Marqeta platform. Allowable Values: `UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED`
title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier of the cardholder. Allowable Values: 1–36 chars
uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). Allowable Values: `true`, `false`
zip string Conditionally returned	United States ZIP code of the cardholder’s address. Allowable Values: 10 char max

Sample response body

JSON

{
  "token": "my_user_01",
  "active": true,
  "gender": "F",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@company.com",
  "title": "Chief Comptroller",
  "birth_place": "US",
  "address1": "1234 Grove Street",
  "city": "Berkeley",
  "state": "CA",
  "postal_code": "94702",
  "country": "USA",
  "phone": "15105551212",
  "uses_parent_account": false,
  "password": "P@ssw0rd",
  "created_time": "2022-08-16T19:39:34Z",
  "last_modified_time": "2022-08-16T19:39:34Z",
  "metadata": {
    "notification_email": "jane.doe@home.com",
    "notification_language": "spa",
    "authentication_question1": "What was your first job?",
    "authentication_question2": "What make was your first car?",
    "authentication_question3": "What is your favorite color?",
    "authentication_answer1": "Cashier",
    "authentication_answer2": "Trabant",
    "authentication_answer3": "Blue"
  },
  "account_holder_group_token": "DEFAULT_AHG",
  "status": "ACTIVE",
  "identifications": [
    {
      "type": "SSN",
      "value": "5555"
    }
  ],
  "birth_date": "1991-01-01"
}

Update user

Action: PUT
Endpoint: /users/{token} To update a specific user resource, send a PUT request to the /users/{token} endpoint. Include the user token path parameter to specify the user to update. To unlink a child user account from a parent account, pass a null value to the parent_token field of the child user resource.

URL path parameters

Fields	Description
token string Required	Unique identifier of the user resource you want to update. Allowable Values: Existing user resource token

Request body

Fields	Description
account_holder_group_token string Optional	Associates the specified account holder group with the cardholder. Send a `GET` request to `/accountholdergroups` to retrieve account holder group tokens. Allowable Values: 36 char max
address1 string Optional	Cardholder address. NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
address2 string Optional	Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
birth_date string Optional	Cardholder date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd
birth_place string Optional	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
city string Optional	The city that corresponds to the address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
company string Optional	Company name. Allowable Values: 255 char max
corporate_card_holder boolean Optional	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false`
country string Optional	Country in which the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max NOTE:ISO alpha-2 country code is required for KYC verification. `US`, for example.
email string Optional	Valid email address for the cardholder. This value must be unique among cardholders. Allowable Values: 1–255 chars
first_name string Optional	Cardholder first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
gender string Optional	Gender of the cardholder. Allowable Values: `F`, `M`
honorific string Optional	Cardholder title or prefix: Ms., Mr., Miss, Mrs. Allowable Values: 10 char max
id_card_expiration_date string Optional	Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd
id_card_number string Optional	Cardholder’s identification card number. Allowable Values: 255 char max
identifications array of objects Optional	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
identifications[].expiration_date string Optional	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
identifications[].type string Required	Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based user cardholder KYC verification, using the `SSN` type. Full Employer Identification Number (EIN) is required for business cardholder KYC verification, using the `BUSINESS_TAX_ID` or `BUSINESS_NUMBER` type. For business directors, use one of SSN, TIN, SIN, or NIN. Nine digits only, no delimiters. `123456789`, for example. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
identifications[].value string Optional	Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789
ip_address string Optional	Cardholder IP address. Allowable Values: 39 char max
last_name string Optional	Cardholder last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
metadata object Optional	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`.
middle_name string Optional	Cardholder middle name. Allowable Values: 40 char max
nationality string Optional	Cardholder nationality. Allowable Values: 255 char max
notes string Optional	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
parent_token string Optional	Unique identifier of an existing user or business resource. Required if `uses_parent_account = true`. This account holder is configured as the parent of the current cardholder. To unlink a child account from a parent account, update this field to a null value. Allowable Values: 1–36 chars
passport_expiration_date string Optional	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
passport_number string Optional	Cardholder passport number. Allowable Values: 40 char max
password string Optional	Cardholder’s user account password on the Marqeta platform. Allowable Values: 255 char max
phone string Optional	Cardholder telephone number (including area code), prepended by the `+` symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses. Allowable Values: 255 char max Format: +15105551212 or +35552260859
postal_code string Optional	Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max
ssn string Optional	Cardholder’s Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). Allowable Values: Nine digits only, no delimiters. `123456789`, for example. NOTE: Required for KYC verification (US-based cardholders only).
state string Optional	State where the cardholder resides (`CA` for California, for example). NOTE:Two-character abbreviation required for KYC verification (US-based cardholders only). Allowable Values: 32 char max
title string Optional	Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max
token string Optional	Unique identifier of the cardholder. Allowable Values: 1–36 chars
uses_parent_account boolean Optional	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). If set to `true`, you must also include a `parent_token` in the request. This value cannot be updated. Allowable Values: `true`, `false` Default value: `false`

Sample request body

JSON

{
  "address1": "4321 Grove Street"
}

Response body

Fields	Description
account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Send a `GET` request to `/accountholdergroups` to retrieve account holder group tokens. Allowable Values: 36 char max
active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. NOTE: Do not set the value of the `user.active` field directly. Instead, use the `/usertransitions` endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition. Allowable Values: `true`, `false`
address1 string Conditionally returned	Cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
address2 string Conditionally returned	Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
birth_date string Conditionally returned	Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd
birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
city string Conditionally returned	City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
company string Conditionally returned	Company name. Allowable Values: 255 char max
corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false` Default value: `false`
country string Conditionally returned	Country where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max NOTE:ISO alpha-2 country code required for KYC verification. `US`, for example.
email string Conditionally returned	Valid email address of the cardholder. This value must be unique among users. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide an email address, contact your Marqeta representative. Allowable Values: 1–255 chars
first_name string Conditionally returned	Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd
id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
identifications[].type string Returned	Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based user cardholder KYC verification, using the `SSN` type. Full Employer Identification Number (EIN) is required for business cardholder KYC verification, using the `BUSINESS_TAX_ID` or `BUSINESS_NUMBER` type. For business directors, use one of SSN, TIN, SIN, or NIN. Nine digits only, no delimiters. `123456789`, for example. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789
ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
last_name string Conditionally returned	Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`.
middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Send a `GET` request to `/users` to retrieve user resource tokens or to `/businesses` to retrieve business resource tokens. Required if `uses_parent_account = true`. This user or business is configured as the parent of the current user. Allowable Values: 1–36 chars
passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: @``#``$``%``!``^``&````(``) \\``_``+``~``-``=``[``]``\{``} ,``;``:``'``"``.``/``<``>``?` Allowable Values:* 255 char max
phone string Conditionally returned	Telephone number of the cardholder (including area code), prepended by the `+` symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide a phone number, contact your Marqeta representative. Allowable Values: 255 char max Format: +15105551212 or +35552260859
postal_code string Conditionally returned	Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max
ssn string Conditionally returned	Cardholder’s Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). Allowable Values: Nine digits only, no delimiters. `123456789`, for example.
state string Conditionally returned	State or province where the cardholder resides. NOTE:Valid two-character abbreviation required for KYC verification (US-based cardholders only). Allowable Values: 32 char max
title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. NOTE: Do not use this field for honorific titles such as Mr., Mrs., Miss, Ms., Mx., Sir, or Dame. Instead, add these to the `honorific` field. Allowable Values: 255 char max
token string Conditionally returned	Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). If set to `true`, you must also include a `parent_token` in the request. This value cannot be updated. Allowable Values: `true`, `false` Default value: `false`

Sample response body

JSON

{
  "token": "my_user_01",
  "active": true,
  "address1": "4321 Grove Street",
  "uses_parent_account": false,
  "corporate_card_holder": false,
  "created_time": "2023-01-29T00:12:20Z",
  "last_modified_time": "2023-09-23T21:41:24Z",
  "metadata": {},
  "account_holder_group_token": "DEFAULT_AHG",
  "status": "ACTIVE"
}

Update user password

Action: POST
Endpoint: /users/auth/changepassword To change a user password, send a POST request to the /users/auth/changepassword endpoint and include the current_password and new_password in JSON format in the body of the request. This endpoint operates in the context of a currently logged-in user. A successful password change returns an empty response body with a response code of 204 No Content.

Request body

Fields	Description
current_password string Required	Current password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
new_password string Required	New password to the cardholder’s user account on the Marqeta platform. - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: @``#``$``%``!``^``&````(``) \\``_``+``~``-``=``[``]``\{``} ,``;``:``'``"``.``/``<``>``?` Allowable Values:* 1–255 chars

Sample request body

JSON

{
  "new_password": "my_new_password",
  "current_password": "my_old_password"
}

Create client access token

Action: POST
Endpoint: /users/auth/clientaccesstoken Each time you want to display a virtual card’s sensitive data (for example, when using marqeta.js), you must first request a new, single-use client access token from the Marqeta platform by sending a POST request to the /users/auth/clientaccesstoken endpoint. Unredeemed client access tokens expire after five minutes.

Request body

Fields	Description
application_token string Optional	Unique identifier of the `application` object. Allowable Values: 1–255 chars
card_token string Required	Unique identifier of the card whose sensitive information you want to display. Allowable Values: 1–255 chars

Sample request body

JSON

{
  "card_token": "my_card_01"
}

Response body

Fields	Description
application object Conditionally returned	Contains client application information. Allowable Values: Existing `application` object
application.access_code string Conditionally returned	Access code of the client application. Allowable Values: 255 char max
application.assets_url string Conditionally returned	URL of the client application assets. Allowable Values: 255 char max
application.client_api_base_url string Conditionally returned	Base URL of the client API. Allowable Values: 255 char max
application.environment string Conditionally returned	Client application’s environment. Allowable Values: 255 char max
application.program string Conditionally returned	Name of the program on the Marqeta platform. Allowable Values: 255 char max
application.program_short_code string Conditionally returned	Short code of the program on the Marqeta platform. Allowable Values: 255 char max
application.token string Conditionally returned	Unique identifier of the `application` object. Allowable Values: 36 char max
card_token string Conditionally returned	Unique identifier of the card whose sensitive information you want to display. Allowable Values: Existing card token
created datetime Conditionally returned	Date and time when the client access token was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
expires datetime Conditionally returned	Date and time when the client access token expires, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Conditionally returned	Value of the client access token to redeem when displaying sensitive card data. Allowable Values: Existing client access token

Sample response body

JSON

{
  "created": "2022-07-29T12:00:00Z",
  "expires": "2022-07-29T12:05:00Z",
  "token": "ewogICJ0b2tlbiI6ICI5NzIwMDkwNS00ODc0LTRkMWEtODEzMS1jMWI3NDAwNzJjM2MmYXBwbGljYXRpb25fdG9rZW49eW91cl9hcHBsaWNhdGlvbl90b2tlbiIsCiAgImFwcGxpY2F0aW9uIjogewogICAgInRva2VuIjogInlvdXJfYXBwbGljYXRpb25fdG9rZW4iLAogICAgImFjdGl2ZSI6IHRydWUsCiAgICAiY2xpZW50X2FwaV9iYXNlX3VybCI6ICJodHRwOi8vd2lkZ2V0cy1lbnYubWFycWV0YS5jb20vY2xpZW50L2FwaS92MSIsCiAgICAiYXNzZXRzX3VybCI6ICJodHRwOi8vd2lkZ2V0cy1lbnYubWFycWV0YS5jb20vY2xpZW50L2Fzc2V0cy8xLjAuMCIsCiAgICAiY2xpZW50dG9rZW5hcHBsaWNhdGlvbklkIjogIjU3MDI2OTJhMGI4ZGNlOTg1YWVmNTExMiIKICB9LAogICJhcHBsaWNhdGlvbl90b2tlbiI6IG51bGwsCiAgImV4cGlyZXMiOiAiMjAxOC0xMi0zMVQyMzo1OTo1OSswMDAwIiwKICAiY2FyZF90b2tlbiI6ICJ0b2tlbl9vZl90aGVfY2FyZF95b3VfbmVlZF90b19wcmVzZW50IiwKICAiYWNjZXNzZWQiOiBudWxsLAogICJjbGllbnR0b2tlbklkIjogIjU5MTc2Y2JlMGI4ZGNlOTg1YWVmNTEzMCIsCiAgImNyZWF0ZWQiOiAiMjAxOC0wMS0wMVQwMDowMDowMCswMDAwIgp9"
}

Retrieve client access token

Action: GET
Endpoint: /users/auth/clientaccesstoken/{token} To retrieve application and card information using a client access token, send a GET request to the /users/auth/clientaccesstoken/{token} endpoint.

URL path parameters

Fields	Description
token string Required	Client access token. Allowable Values: Existing client access token

URL query parameters

Fields	Description
application_token string Optional	Unique identifier of the `application` object. Allowable Values: Existing application token

Response body

Fields	Description
application object Conditionally returned	Contains client application information. Allowable Values: Existing `application` object
application.access_code string Conditionally returned	Access code of the client application. Allowable Values: 255 char max
application.assets_url string Conditionally returned	URL of the client application assets. Allowable Values: 255 char max
application.client_api_base_url string Conditionally returned	Base URL of the client API. Allowable Values: 255 char max
application.environment string Conditionally returned	Client application’s environment. Allowable Values: 255 char max
application.program string Conditionally returned	Name of the program on the Marqeta platform. Allowable Values: 255 char max
application.program_short_code string Conditionally returned	Short code of the program on the Marqeta platform. Allowable Values: 255 char max
application.token string Conditionally returned	Unique identifier of the `application` object. Allowable Values: 36 char max
card_token string Conditionally returned	Unique identifier of the card whose sensitive information you want to display. Allowable Values: Existing card token
created datetime Conditionally returned	Date and time when the client access token was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
expires datetime Conditionally returned	Date and time when the client access token expires, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
token string Conditionally returned	Value of the client access token to redeem when displaying sensitive card data. Allowable Values: Existing client access token

Sample response body

JSON

{
  "created": "2022-07-29T12:00:00Z",
  "expires": "2022-07-29T12:05:00Z",
  "token": "ewogICJ0b2tlbiI6ICI5NzIwMDkwNS00ODc0LTRkMWEtODEzMS1jMWI3NDAwNzJjM2MmYXBwbGljYXRpb25fdG9rZW49eW91cl9hcHBsaWNhdGlvbl90b2tlbiIsCiAgImFwcGxpY2F0aW9uIjogewogICAgInRva2VuIjogInlvdXJfYXBwbGljYXRpb25fdG9rZW4iLAogICAgImFjdGl2ZSI6IHRydWUsCiAgICAiY2xpZW50X2FwaV9iYXNlX3VybCI6ICJodHRwOi8vd2lkZ2V0cy1lbnYubWFycWV0YS5jb20vY2xpZW50L2FwaS92MSIsCiAgICAiYXNzZXRzX3VybCI6ICJodHRwOi8vd2lkZ2V0cy1lbnYubWFycWV0YS5jb20vY2xpZW50L2Fzc2V0cy8xLjAuMCIsCiAgICAiY2xpZW50dG9rZW5hcHBsaWNhdGlvbklkIjogIjU3MDI2OTJhMGI4ZGNlOTg1YWVmNTExMiIKICB9LAogICJhcHBsaWNhdGlvbl90b2tlbiI6IG51bGwsCiAgImV4cGlyZXMiOiAiMjAxOC0xMi0zMVQyMzo1OTo1OSswMDAwIiwKICAiY2FyZF90b2tlbiI6ICJ0b2tlbl9vZl90aGVfY2FyZF95b3VfbmVlZF90b19wcmVzZW50IiwKICAiYWNjZXNzZWQiOiBudWxsLAogICJjbGllbnR0b2tlbklkIjogIjU5MTc2Y2JlMGI4ZGNlOTg1YWVmNTEzMCIsCiAgImNyZWF0ZWQiOiAiMjAxOC0wMS0wMVQwMDowMDowMCswMDAwIgp9"
}

Log in user

Action: POST
Endpoint: /users/auth/login To log in a user and return a user access token, send a POST request to the /users/auth/login endpoint and include the user details in JSON format in the body of the request.

Tip
To check a user’s credentials without logging out the user, call the /users/auth/onetime endpoint.

Request body

Fields	Description
email string Optional	Cardholder email address. Allowable Values: 255 char max
password string Optional	Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
user_token string Optional	Identifies the cardholder to log in. Send a `GET` request to `/users` to retrieve user tokens. Allowable Values: 1–36 chars

Sample request body

JSON

{
  "email": "jane.doe@company.com",
  "password": "P@ssw0rd",
  "user_token": "my_user_01"
}

Response body

Fields	Description
access_token object Conditionally returned	Contains a cardholder’s login access information. Allowable Values: Existing `access_token`
access_token.application object Conditionally returned	Contains client application information. Allowable Values: Existing `application` object
access_token.application.access_code string Conditionally returned	Access code of the client application. Allowable Values: 255 char max
access_token.application.assets_url string Conditionally returned	URL of the client application assets. Allowable Values: 255 char max
access_token.application.client_api_base_url string Conditionally returned	Base URL of the client API. Allowable Values: 255 char max
access_token.application.environment string Conditionally returned	Client application’s environment. Allowable Values: 255 char max
access_token.application.program string Conditionally returned	Name of the program on the Marqeta platform. Allowable Values: 255 char max
access_token.application.program_short_code string Conditionally returned	Short code of the program on the Marqeta platform. Allowable Values: 255 char max
access_token.application.token string Conditionally returned	Unique identifier of the `application` object. Allowable Values: 36 char max
access_token.expires datetime Returned	Date and time when the access token expires. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
access_token.master_roles array of strings Conditionally returned	Array of master roles. Allowable Values: Valid array of one or more `master_roles` strings
access_token.one_time boolean Conditionally returned	Indicates whether the access token is a single-use token. Allowable Values: `true`, `false`
access_token.token string Conditionally returned	Unique identifier of the access token. Allowable Values: 36 char max
access_token.token_type string Conditionally returned	Specifies the type of access token. Allowable Values: `single_use`, `user`, `admin`
access_token.user_token string Conditionally returned	Unique identifier of the user resource. Allowable Values: 36 char max
user object Conditionally returned	Contains information about a cardholder. Allowable Values: `account_holder_group_token`, `active`, `address1`, `address2`, `authentication`, `birth_date`, `birth_place`, `business_token`, `city`, `company`, `corporate_card_holder`, `country`, `created_time`, `email`, `first_name`, `gender`, `honorific`, `id_card_expiration_date`, `id_card_number`, `identifications`, `ip_address`, `last_modified_time`, `last_name`, `metadata`, `middle_name`, `nationality`, `notes`, `parent_token`, `passport_expiration_date`, `passport_number`, `password`, `phone`, `postal_code`, `ssn`, `state`, `status`, `title`, `token`, `uses_parent_account`, `zip`
user.account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Allowable Values: 36 char max
user.active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. Allowable Values: `true`, `false`
user.address1 string Conditionally returned	Cardholder’s address. Allowable Values: 255 char max
user.address2 string Conditionally returned	Additional address information for the cardholder. Allowable Values: 255 char max
user.authentication object Conditionally returned	Contains the cardholder’s email address and password information. Allowable Values: `email_verified`, `email_verified_time`, `last_password_update_channel`, `last_password_update_time`
user.authentication.email_verified boolean Conditionally returned	Specifies whether the email address has been verified. Allowable Values: `true`, `false`
user.authentication.email_verified_time datetime Conditionally returned	Date and time when the email address was verified. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.authentication.last_password_update_channel string Conditionally returned	Specifies the channel through which the password was last changed. Allowable Values: `USER_CHANGE`, `USER_RESET`
user.authentication.last_password_update_time datetime Conditionally returned	Date and time when the password was last changed. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.birth_date string Conditionally returned	Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd
user.birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
user.business_token string Conditionally returned	Unique identifier of the business resource. Allowable Values: Existing business resource token
user.city string Conditionally returned	City where the cardholder resides. Allowable Values: 40 char max
user.company string Conditionally returned	Company name. Allowable Values: 255 char max
user.corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false`
user.country string Conditionally returned	Country where the cardholder resides. Allowable Values: 40 char max
user.created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.email string Conditionally returned	Valid email address of the cardholder. Allowable Values: 1–255 chars
user.first_name string Conditionally returned	Cardholder’s first name. Allowable Values: 40 char max
user.gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
user.honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
user.id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd
user.id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
user.identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
user.identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
user.identifications[].type string Conditionally returned	Type of identification. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
user.identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max
user.ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
user.last_modified_time datetime Returned	Date and time when the resource was last updated, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
user.last_name string Conditionally returned	Cardholder’s last name. Allowable Values: 40 char max
user.metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`
user.middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
user.nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
user.notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
user.parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars
user.passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
user.passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
user.password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
user.phone string Conditionally returned	Cardholder’s telephone number. Allowable Values: 255 char max
user.postal_code string Conditionally returned	Postal code of the cardholder’s address. Allowable Values: 10 char max
user.ssn string Conditionally returned	Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
user.state string Conditionally returned	State or province where the cardholder resides. Allowable Values: 2 char max
user.status string Conditionally returned	Specifies the status of the cardholder on the Marqeta platform. Allowable Values: `UNVERIFIED`, `LIMITED`, `ACTIVE`, `SUSPENDED`, `CLOSED`
user.title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. Allowable Values: 255 char max
user.token string Conditionally returned	Unique identifier of the cardholder. Allowable Values: 1–36 chars
user.uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). Allowable Values: `true`, `false`
user.zip string Conditionally returned	United States ZIP code of the cardholder’s address. Allowable Values: 10 char max

Sample response body

JSON

{
  "access_token": {
    "token": "e12b1f64-1444-4aa3-83d9-347800c68e94",
    "expires": "2027-03-01T21:02:04Z",
    "one_time": false
  },
  "user": {
    "token": "my_user_01",
    "active": true,
    "email": "jane.doe@company.com",
    "uses_parent_account": false,
    "password": "P@ssw0rd",
    "created_time": "2023-04-01T17:52:39Z",
    "last_modified_time": "2023-04-01T17:52:39Z"
  }
}

Log out user

Action: POST
Endpoint: /users/auth/logout To log out a user, send a POST request to the /users/auth/logout endpoint. A successful logout returns an empty response body with a response code of 204 No Content.

Create single-use token

Action: POST
Endpoint: /users/auth/onetime This endpoint returns a single-use access token. This type of token authorizes a single request to access API endpoints and data associated with a particular user. A single-use access token differs from a user access token (as returned by POST /users/auth/login) only in the number of times it can be used. To return a single-use access token, send a POST request to the /users/auth/onetime endpoint. Provide one of these sets of input data:

Case #1 – Application token and user access token
Case #2 – Application token, admin access token, and user token
Case #3 – Application token, user’s Marqeta password, and user’s email address

In each case, provide the application token as the HTTP Basic Authentication username in the request header’s Authorization field. When applicable, provide the user access token or admin access token as the HTTP Basic Authentication password. When applicable, provide the user token or user’s Marqeta password and email address in JSON format in the request body. Before instantiating an embedded Marqeta widget, call this endpoint to obtain the single-use access token required as input (cases #1 and #2). This endpoint is also useful when you want to check a user’s credentials before performing a sensitive operation without having to log out the user (case #3).

Note
Calling this endpoint and returning a single-use access token does not invalidate the user’s current user access token.

Request body

Fields	Description
email string Optional	Cardholder email address. Required when neither the user token nor the admin access token is provided as the Basic Authentication password (case #3). Allowable Values: 1–255 chars
password string Optional	Password to the cardholder’s user account on the Marqeta platform. Required when neither the user token nor the admin access token is provided as the Basic Authentication password (case #3). Allowable Values: 1–255 chars
user_token string Optional	Identifies the cardholder whose data is accessed. Send a `GET` request to `/users` to retrieve cardholder tokens. Required when the Basic Authentication password is set to an admin access token (case #2). Allowable Values: 1–36 chars

Sample request body

Case 1: Authorization: Basic my_application_token:my_user_access_token

JSON

{}

Case 2: Authorization: Basic my_application_token:my_admin_access_token

JSON

{
  "user_token": "my_user_token"
}

Case 3: Authorization: Basic my_application_token

JSON

{
  "email": "jane.doe@company.com",
  "password": "P@ssw0rd"
}

Response body

Fields	Description
application object Conditionally returned	Contains client application information. Allowable Values: Existing `application` object
application.access_code string Conditionally returned	Access code of the client application. Allowable Values: 255 char max
application.assets_url string Conditionally returned	URL of the client application assets. Allowable Values: 255 char max
application.client_api_base_url string Conditionally returned	Base URL of the client API. Allowable Values: 255 char max
application.environment string Conditionally returned	Client application’s environment. Allowable Values: 255 char max
application.program string Conditionally returned	Name of the program on the Marqeta platform. Allowable Values: 255 char max
application.program_short_code string Conditionally returned	Short code of the program on the Marqeta platform. Allowable Values: 255 char max
application.token string Conditionally returned	Unique identifier of the `application` object. Allowable Values: 36 char max
expires datetime Returned	Date and time when the access token expires. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
master_roles array of strings Conditionally returned	Array of master roles. Allowable Values: Valid array of one or more `master_roles` strings
one_time boolean Conditionally returned	Indicates whether the access token is a single-use token. Allowable Values: `true`, `false`
token string Conditionally returned	Unique identifier of the access token. Allowable Values: 36 char max
token_type string Conditionally returned	Specifies the type of access token. Allowable Values: `single_use`, `user`, `admin`
user_token string Conditionally returned	Unique identifier of the user resource. Allowable Values: 36 char max

Sample response body

JSON

{
  "token": "697e0bde-ea52-44bd-8150-0e0f83e9625d",
  "expires": "2024-04-01T00:00:00Z",
  "one_time": true
}

Request user password reset token

Action: POST
Endpoint: /users/auth/resetpassword Use this endpoint to generate a password reset token for a user. Send a POST request to the /users/auth/resetpassword endpoint and include the user’s email address in JSON format in the body of the request. This request generates and sends an email message containing the user_token and password_reset_token to the user’s email address. You must customize the email message with a link that passes the user_token and password_reset_token to a web page where a subsequent request updates the password. A successful request returns an empty response body with a response code of 204 No Content.

Request body

Fields	Description
email string Required	Cardholder email address. Allowable Values: 1–255 chars

Sample request body

JSON

{
  "email": "jane.doe@company.com"
}

Reset user password

Action: POST
Endpoint: /users/auth/resetpassword/{token} To reset the user’s password, send a POST request to the /users/auth/resetpassword/{token} endpoint that includes a password reset token generated using the POST /users/auth/resetpassword operation. Include the user_token and new_password in JSON format in the body of the request. Include the password_reset_token as a path parameter. A successful password reset returns an empty response body with a response code of 204 No Content.

URL path parameters

Fields	Description
token string Required	Password reset token generated using the `POST /users/auth/resetpassword` operation. Allowable Values: Existing password reset token

Request body

Fields	Description
new_password string Required	New password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars
user_token string Required	Unique identifier of the cardholder. Allowable Values: 1–36 chars

Sample request body

JSON

{
  "user_token": "my_user_01",
  "new_password": "newPassword123@"
}

Request email verification token

Action: POST
Endpoint: /users/auth/verifyemail Send a POST request to the /users/auth/verifyemail endpoint to request an email verification token. No input parameters are required because this operation is performed in the context of an authenticated user. This initial request generates and sends an email message containing the email verification token to the cardholder’s email address. This email message must include a link that passes the email verification token to a web page where a subsequent request verifies the email address. A successful request returns an empty response body with a response code of 204 No Content.

Verify email address

Action: POST
Endpoint: /users/auth/verifyemail/{token} To verify a user’s email address, send a POST request to the /users/auth/verifyemail/{email_verification_token} endpoint that includes an email_verification_token generated using the POST /users/auth/verifyemail operation. Include the email_verification_token as a path parameter. A successful email verification returns an empty response body with a response code of 204 No Content.

URL path parameters

Fields	Description
token string Required	Email verification token generated using the `POST /users/auth/verifyemail` operation. Allowable Values: Existing email verification token

Search users

Action: POST
Endpoint: /users/lookup To search for one or more users, send a POST request to the /users/lookup endpoint. Include in the message body any parameters by which you want to query. This endpoint supports field filtering and pagination.

URL query parameters

Fields	Description
count integer Optional	Number of user resources to retrieve. Allowable Values: 1-10 Default value: 5
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0
search_type string Optional	Search type. Allowable Values: `query_then_fetch`, `dfs_query_then_fetch`
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-lastModifiedTime`

Request body

Fields	Description
dda string Optional	Performs a match on the specified deposit account number. Send a `GET` request to `/directdeposits/accounts/{user_token}` to retrieve the deposit account number for a specific cardholder. Allowable Values: Existing deposit account number
email string Optional	Performs a non-case-sensitive, exact match on the cardholder’s `email` field. Allowable Values: 1–255 chars
first_name string Optional	Performs a non-case-sensitive match on the cardholder’s `first_name` field. Matching is partial on the beginning of the name. For example, a match on “Alex” returns both “Alex” and “Alexander”. Allowable Values: 40 char max
last_name string Optional	Performs a non-case-sensitive match on the cardholder’s `last_name` field. Matching is partial on the beginning of the name. For example, a match on “Smith” returns both “Smith” and “Smithfield”. Allowable Values: 40 char max
phone string Optional	Performs a match on the cardholder’s `phone` field. Allowable Values: 255 char max
ssn string Optional	Performs a match on the cardholder’s identification number. Allowable Values: Either a complete identification number or the last four digits. Digits only, no delimiters.

Sample request body

JSON

{
  "first_name": "Jane"
}

Response body

Fields	Description
count integer Conditionally returned	Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of user objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more user objects
data[].account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Send a `GET` request to `/accountholdergroups` to retrieve account holder group tokens. Allowable Values: 36 char max
data[].active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. NOTE: Do not set the value of the `user.active` field directly. Instead, use the `/usertransitions` endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition. Allowable Values: `true`, `false`
data[].address1 string Conditionally returned	Cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
data[].address2 string Conditionally returned	Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
data[].birth_date string Conditionally returned	Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd
data[].birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
data[].city string Conditionally returned	City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].company string Conditionally returned	Company name. Allowable Values: 255 char max
data[].corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false` Default value: `false`
data[].country string Conditionally returned	Country where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max NOTE:ISO alpha-2 country code required for KYC verification. `US`, for example.
data[].email string Conditionally returned	Valid email address of the cardholder. This value must be unique among users. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide an email address, contact your Marqeta representative. Allowable Values: 1–255 chars
data[].first_name string Conditionally returned	Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
data[].honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
data[].id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd
data[].id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
data[].identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
data[].identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
data[].identifications[].type string Returned	Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based user cardholder KYC verification, using the `SSN` type. Full Employer Identification Number (EIN) is required for business cardholder KYC verification, using the `BUSINESS_TAX_ID` or `BUSINESS_NUMBER` type. For business directors, use one of SSN, TIN, SIN, or NIN. Nine digits only, no delimiters. `123456789`, for example. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
data[].identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789
data[].ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
data[].last_name string Conditionally returned	Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`.
data[].middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
data[].nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
data[].notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
data[].parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Send a `GET` request to `/users` to retrieve user resource tokens or to `/businesses` to retrieve business resource tokens. Required if `uses_parent_account = true`. This user or business is configured as the parent of the current user. Allowable Values: 1–36 chars
data[].passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
data[].passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
data[].password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: @``#``$``%``!``^``&````(``) \\``_``+``~``-``=``[``]``\{``} ,``;``:``'``"``.``/``<``>``?` Allowable Values:* 255 char max
data[].phone string Conditionally returned	Telephone number of the cardholder (including area code), prepended by the `+` symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide a phone number, contact your Marqeta representative. Allowable Values: 255 char max Format: +15105551212 or +35552260859
data[].postal_code string Conditionally returned	Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max
data[].ssn string Conditionally returned	Cardholder’s Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). Allowable Values: Nine digits only, no delimiters. `123456789`, for example.
data[].state string Conditionally returned	State or province where the cardholder resides. NOTE:Valid two-character abbreviation required for KYC verification (US-based cardholders only). Allowable Values: 32 char max
data[].title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. NOTE: Do not use this field for honorific titles such as Mr., Mrs., Miss, Ms., Mx., Sir, or Dame. Instead, add these to the `honorific` field. Allowable Values: 255 char max
data[].token string Conditionally returned	Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
data[].uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). If set to `true`, you must also include a `parent_token` in the request. This value cannot be updated. Allowable Values: `true`, `false` Default value: `false`
end_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Sample response body

JSON

{
  "count": 1,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_user_01",
      "active": true,
      "gender": "F",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@company.com",
      "address1": "1234 Grove Street",
      "city": "Berkeley",
      "state": "CA",
      "postal_code": "94702",
      "country": "USA",
      "phone": "15105551212",
      "uses_parent_account": false,
      "password": "P@ssw0rd",
      "created_time": "2023-03-16T20:26:28Z",
      "last_modified_time": "2023-03-16T20:26:29Z",
      "metadata": {},
      "account_holder_group_token": "DEFAULT_AHG",
      "status": "ACTIVE",
      "identifications": [
        {
          "type": "DRIVERS_LICENSE",
          "value": "12345"
        }
      ],
      "birth_date": "1991-01-01"
    }
  ]
}

List user child accounts

Action: GET
Endpoint: /users/{parent_token}/children To retrieve users who are children of a parent user or business, send a GET request to the /users/{parent_token}/children endpoint. Include the parent’s user or business token as a URL path parameter. The business_token field is conditionally returned in the response (it cannot be set through the API). You can use this field in conjunction with the parent_token field to determine whether the user has a parent or grandparent that is a business:

parent_token	business_token	Description
Not populated	Not populated	User does not have a parent.
Populated	Not populated	User’s parent is a user.
Populated; matches `business_token`	Populated; matches `parent_token`	User’s parent is a business.
Populated; does not match `business_token`	Populated; does not match `parent_token`	User’s parent is a user and their grandparent is a business.

This endpoint supports field filtering.

URL path parameters

Fields	Description
parent_token string Required	Unique identifier of the parent account holder. Allowable Values: Existing user or business resource token

URL query parameters

Fields	Description
count integer Optional	Number of user resources to retrieve. Allowable Values: 1-10 Default value: 5
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-lastModifiedTime`

Response body

Fields	Description
count integer Conditionally returned	Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of user objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more user objects
data[].account_holder_group_token string Conditionally returned	Associates the specified account holder group with the cardholder. Send a `GET` request to `/accountholdergroups` to retrieve account holder group tokens. Allowable Values: 36 char max
data[].active boolean Conditionally returned	Specifies if the cardholder is in the `ACTIVE` state on the Marqeta platform. NOTE: Do not set the value of the `user.active` field directly. Instead, use the `/usertransitions` endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition. Allowable Values: `true`, `false`
data[].address1 string Conditionally returned	Cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
data[].address2 string Conditionally returned	Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max
data[].birth_date string Conditionally returned	Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd
data[].birth_place string Conditionally returned	Country where the cardholder was born. Allowable Values: 255 char max ISO 3166 two-character country codes. For example, the country code for the United States is `US`. The ISO maintains the full list of ISO-3166 country codes.
data[].city string Conditionally returned	City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].company string Conditionally returned	Company name. Allowable Values: 255 char max
data[].corporate_card_holder boolean Conditionally returned	Specifies if the cardholder holds a corporate card. Allowable Values: `true`, `false` Default value: `false`
data[].country string Conditionally returned	Country where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max NOTE:ISO alpha-2 country code required for KYC verification. `US`, for example.
data[].email string Conditionally returned	Valid email address of the cardholder. This value must be unique among users. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide an email address, contact your Marqeta representative. Allowable Values: 1–255 chars
data[].first_name string Conditionally returned	Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].gender string Conditionally returned	Gender of the cardholder. Allowable Values: `F`, `M`
data[].honorific string Conditionally returned	Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max
data[].id_card_expiration_date string Conditionally returned	Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd
data[].id_card_number string Conditionally returned	Cardholder’s identification card number. Allowable Values: 255 char max
data[].identifications array of objects Conditionally returned	One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more `identifications` objects
data[].identifications[].expiration_date string Conditionally returned	Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd
data[].identifications[].type string Returned	Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based user cardholder KYC verification, using the `SSN` type. Full Employer Identification Number (EIN) is required for business cardholder KYC verification, using the `BUSINESS_TAX_ID` or `BUSINESS_NUMBER` type. For business directors, use one of SSN, TIN, SIN, or NIN. Nine digits only, no delimiters. `123456789`, for example. Allowable Values: `SSN`, `TIN`, `SIN`, `NIN`, `PASSPORT_NUMBER`, `DRIVERS_LICENSE`, `BUSINESS_NUMBER`, `BUSINESS_TAX_ID`, `TAXPAYER_REFERENCE`
data[].identifications[].value string Conditionally returned	Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789
data[].ip_address string Conditionally returned	Cardholder’s IP address. Allowable Values: 39 char max
data[].last_name string Conditionally returned	Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max
data[].metadata object Conditionally returned	Associates any additional metadata you provide with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`.
data[].middle_name string Conditionally returned	Cardholder’s middle name. Allowable Values: 40 char max
data[].nationality string Conditionally returned	Cardholder’s nationality. Allowable Values: 255 char max
data[].notes string Conditionally returned	Any additional information pertaining to the cardholder. Allowable Values: 255 char max
data[].parent_token string Conditionally returned	Unique identifier of the parent user or business resource. Send a `GET` request to `/users` to retrieve user resource tokens or to `/businesses` to retrieve business resource tokens. Required if `uses_parent_account = true`. This user or business is configured as the parent of the current user. Allowable Values: 1–36 chars
data[].passport_expiration_date string Conditionally returned	Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd
data[].passport_number string Conditionally returned	Cardholder’s passport number. Allowable Values: 40 char max
data[].password string Conditionally returned	Password to the cardholder’s user account on the Marqeta platform. - Must contain at least one numeral - Must contain at least one lowercase letter - Must contain at least one uppercase letter - Must contain at least one of these symbols: @``#``$``%``!``^``&````(``) \\``_``+``~``-``=``[``]``\{``} ,``;``:``'``"``.``/``<``>``?` Allowable Values:* 255 char max
data[].phone string Conditionally returned	Telephone number of the cardholder (including area code), prepended by the `+` symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses. NOTE: Required for KYC verification by certain banks (US-based cardholders only). To determine if you must provide a phone number, contact your Marqeta representative. Allowable Values: 255 char max Format: +15105551212 or +35552260859
data[].postal_code string Conditionally returned	Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max
data[].ssn string Conditionally returned	Cardholder’s Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). Allowable Values: Nine digits only, no delimiters. `123456789`, for example.
data[].state string Conditionally returned	State or province where the cardholder resides. NOTE:Valid two-character abbreviation required for KYC verification (US-based cardholders only). Allowable Values: 32 char max
data[].title string Conditionally returned	Professional title of the cardholder, such as Chief Comptroller. NOTE: Do not use this field for honorific titles such as Mr., Mrs., Miss, Ms., Mx., Sir, or Dame. Instead, add these to the `honorific` field. Allowable Values: 255 char max
data[].token string Conditionally returned	Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars
data[].uses_parent_account boolean Conditionally returned	Indicates whether the child shares balances with the parent (`true`), or the child’s balances are independent of the parent (`false`). If set to `true`, you must also include a `parent_token` in the request. This value cannot be updated. Allowable Values: `true`, `false` Default value: `false`
end_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Sample response body

JSON

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "child_of_parent",
      "active": true,
      "gender": "M",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john_smith@company.com",
      "address1": "123 Main Street",
      "city": "Oakland",
      "state": "CA",
      "postal_code": "94601",
      "country": "USA",
      "phone": "15101111111",
      "parent_token": "my_user_01",
      "uses_parent_account": true,
      "password": "P@55word",
      "created_time": "2022-08-16T19:46:58Z",
      "last_modified_time": "2022-08-16T19:46:58Z",
      "metadata": {},
      "account_holder_group_token": "DEFAULT_AHG",
      "status": "ACTIVE",
      "identifications": [
        {
          "type": "SSN",
          "value": "7777",
          "birth_date": "1986-04-01"
        }
      ]
    }
  ]
}

Retrieve user identification number

Action: GET
Endpoint: /users/{token}/ssn To retrieve the government-issued identification number for a user, send a GET request to the /users/{token}/ssn endpoint. Include the token path parameter to specify the user whose identification number (SSN, ITIN, TIN, NIN, SIN) you wish to return. You can indicate whether to return the full number or the last four digits only.

URL path parameters

Fields	Description
token string Required	Unique identifier of the user resource. Allowable Values: Existing user resource token

URL query parameters

Fields	Description
full_ssn boolean Optional	To return the full identification number, set to `true`. To return only the last four digits, set to `false`. If the identifications array contains only the last four digits of the identification number, the `/users/{token}/ssn` endpoint will return only the last four digits, regardless of the `full_ssn` parameter. Allowable Values: 4 or 9 char

Response body

Fields	Description
nin string Conditionally returned	National Identification Number (NIN). Allowable Values: 255 char max
sin string Conditionally returned	Social Insurance Number (SIN). Allowable Values: 255 char max
ssn string Conditionally returned	United States Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). Allowable Values: 255 char max
tin string Conditionally returned	Taxpayer Identification Number (TIN). Allowable Values: 255 char max

Sample response body

JSON

{
  "ssn": "5555"
}

​Create user

​Request body

​Sample request body

​Response body

​Sample response body

​List users

​URL query parameters

​Response body

​Sample response body

​Retrieve user

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Update user

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​Update user password

​Request body

​Sample request body

​Create client access token

​Request body

​Sample request body

​Response body

​Sample response body

​Retrieve client access token

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Log in user

​Request body

​Sample request body

​Response body

​Sample response body

​Log out user

​Create single-use token

​Request body

​Sample request body

​Response body

​Sample response body

​Request user password reset token

​Request body

​Sample request body

​Reset user password

​URL path parameters

​Request body

​Sample request body

​Request email verification token

​Verify email address

​URL path parameters

​Search users

​URL query parameters

​Request body

​Sample request body

​Response body

​Sample response body

​List user child accounts

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve user identification number

​URL path parameters

​URL query parameters

​Response body

​Sample response body

Create user

Request body

Sample request body

Response body

Sample response body

List users

URL query parameters

Response body

Sample response body

Retrieve user

URL path parameters

URL query parameters

Response body

Sample response body

Update user

URL path parameters

Request body

Sample request body

Response body

Sample response body

Update user password

Request body

Sample request body

Create client access token

Request body

Sample request body

Response body

Sample response body

Retrieve client access token

URL path parameters

URL query parameters

Response body

Sample response body

Log in user

Request body

Sample request body

Response body

Sample response body

Log out user

Create single-use token

Request body

Sample request body

Response body

Sample response body

Request user password reset token

Request body

Sample request body

Reset user password

URL path parameters

Request body

Sample request body

Request email verification token

Verify email address

URL path parameters

Search users

URL query parameters

Request body

Sample request body

Response body

Sample response body

List user child accounts

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve user identification number

URL path parameters

URL query parameters

Response body

Sample response body