Search users - Marqeta Docs

POST//

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

URL query parameters

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

Request body

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

Sample request body

JSON

{
  "first_name": "Jane"
}

Response body

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

Sample response body

JSON

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