List users

GET/

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

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

URL query parameters

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

Response body

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

Sample response body

JSON

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

Getting Started

Testing

Card Issuing

Card Processing

Accounts & Money Movement

Risk, Fraud, and Disputes

Cardholder User Experience

URL query parameters

Response body

Sample response body

​URL query parameters

​Response body

​Sample response body

URL query parameters

Response body

Sample response body