> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Users
> Use this endpoint to create and manage resources that represent your individual cardholders.
export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
text: "mint-text-green-700 dark:mint-text-green-400",
border: "mint-border-green-300 dark:mint-border-green-700"
},
POST: {
bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
text: "mint-text-blue-700 dark:mint-text-blue-400"
},
PUT: {
bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
text: "mint-text-yellow-700 dark:mint-text-yellow-400"
},
PATCH: {
bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
text: "mint-text-orange-700 dark:mint-text-orange-400"
},
DELETE: {
bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
text: "mint-text-red-700 dark:mint-text-red-400"
},
API: {
bg: "mint-bg-black",
text: "mint-text-white"
}
};
const MethodBadge = ({method}) => {
const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
return
{method?.toUpperCase()}
;
};
const content =
{}
{}
{title}
{children &&
{children}
}
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](/core-api/kyc-verification/) of the program or associated [account holder group](/core-api/account-holder-groups/).
| 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](/core-api/user-transitions/#post_usertransitions).
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 JSON expandable lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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](/core-api/field-filtering/) and [pagination](/core-api/sorting-and-pagination/). To narrow your result set to users that match certain criteria, see the [Search users](#post_users_lookup) 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 JSON expandable lines wrap theme={null}
{
"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](/core-api/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 JSON expandable lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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](http://www.json.org/) 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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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](http://www.json.org/) 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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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](http://www.json.org/) 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 JSON lines wrap theme={null}
{}
```
**Case 2:** Authorization: Basic `my_application_token:my_admin_access_token`
```json JSON lines wrap theme={null}
{
"user_token": "my_user_token"
}
```
**Case 3:** Authorization: Basic `my_application_token`
```json JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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](http://www.json.org/) 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 JSON lines wrap theme={null}
{
"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](http://www.json.org/) 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 JSON lines wrap theme={null}
{
"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](/core-api/field-filtering/) and [pagination](/core-api/sorting-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 JSON lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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](/core-api/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 JSON expandable lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"ssn": "5555"
}
```
## Related topics
- [Users](/docs/diva-api/users.md)
- [User Transitions](/docs/core-api/user-transitions.md)
- [User Counts](/docs/diva-api/user-counts.md)