GET///
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. |
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 modelDefault 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, falseDefault 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, falseDefault 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": 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"
}
]
}
]
}