GET//
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. |
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, 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
{
"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"
}