> ## 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.

# Retrieve user

> To retrieve a specific user, send a GET request to the /users/{token} endpoint.

GET/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](https://www.marqeta.com/docs/core-api/field-filtering.md).

## 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](https://www.iso.org/iso-3166-country-codes.html). |
| 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`, `TERMINATED` |
| 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"
}
```


## Related topics

- [Users](https://www.marqeta.com/docs/diva-api/users.md)
- [Retrieve user transition](https://www.marqeta.com/docs/core-api/user-transitions/retrieve-user-transition.md)
- [Retrieve user identification number](https://www.marqeta.com/docs/core-api/users/get-ssn.md)
- [User Counts](https://www.marqeta.com/docs/diva-api/user-counts.md)
- [Users Overview](https://www.marqeta.com/docs/core-api/users.md)