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

# Create user

> This endpoint enables you to create a user.

POST/users

This endpoint enables you to create a user. A new user's initial status depends on the [Know Your Customer (KYC) requirements](https://www.marqeta.com/docs/core-api/kyc-verification/) of the program or associated [account holder group](https://www.marqeta.com/docs/core-api/account-holder-groups/).

| KYC Required | Initial User Status | User Active on Creation | User Limitations |
| - | - | - | - |
| Always | `UNVERIFIED` | Optional | Cannot load funds; cannot activate cards. |
| Conditionally | `LIMITED` | Optional | Restricted by rules in `accountholdergroups.pre_kyc_controls`. |
| Never | `ACTIVE` | Required | None. |

> [!NOTE]
>
> **Note**\
> Use the `/usertransitions` endpoints to transition user resources between statuses and to view the history of a user's status. Do not set the value of the `user.active` field directly. For more information on status changes, see [Create User Transition](https://www.marqeta.com/docs/core-api/user-transitions/create-user-transition.md).

To perform KYC verification on users, the user object must have the following fields configured:

* `first_name` (legal first name only, no prefixes)
* `last_name` (legal last name only, no suffixes)
* `address1` (cannot be a PO Box)
* `city`
* `state`
* `postal_code`
* `country`
* `birth_date`
* `identifications`
* `phone` (required in some cases)
* `email` (required in some cases)

> [!NOTE]
>
> **Note**\
> The `identifications` requirement depends on your program's configuration. To determine if you should provide a full or abbreviated identification number, contact your Marqeta representative. KYC verification requires the full Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN) of the user.

To create a child user, you must identify the parent user or business and determine whether the child user shares an account with the parent.

The parent must be an existing user or business. On the child user, set the `parent_token` field to the value of the parent's `token` field. If either the parent or the grandparent is a business, a `business_token` field is added to the user. This field's value is set to the token of either the parent or grandparent (whichever is the business).

The `uses_parent_account` field determines whether the child shares balances with the parent (`true`) or whether the child balances are independent of the parent (`false`). If you do not specify a value for `uses_parent_account`, it is set to `false` by default (the user does not share the parent's balance) and returned in the response body. This field cannot be updated, so you must decide upon creation whether the child user shares the parent balance.

Sharing an account with a parent user affects how the child user interacts with cards as follows:

* A child user cannot spend funds if its parent is not active.
* An active child user can activate cards, whether the parent is active or not.

## Request body

| Fields | Description |
| - | - |
| account\_holder\_group\_token string  Optional | 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 |
| active boolean  Optional | 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](https://www.marqeta.com/docs/core-api/user-transitions/create-user-transition.md). **Allowable Values:**  `true`, `false` |
| address1 string  Optional | 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 |
| address2 string  Optional | Additional address information for the cardholder. **NOTE:** Cannot perform KYC if set to a PO Box. **Allowable Values:**  255 char max |
| birth\_date string  Optional | Cardholder's date of birth. **NOTE:** Required for KYC verification (US-based cardholders only). **Allowable Values:**  Format: yyyy-MM-dd |
| birth\_place string  Optional | 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). |
| city string  Optional | City where the cardholder resides. **NOTE:** Required for KYC verification (US-based cardholders only). **Allowable Values:**  40 char max |
| company string  Optional | Company name. **Allowable Values:**  255 char max |
| corporate\_card\_holder boolean  Optional | Specifies if the cardholder holds a corporate card. **Allowable Values:**  `true`, `false` **Default value:** `false` |
| country string  Optional | 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](https://www.iso.org/iso-3166-country-codes.html) required for KYC verification. `US`, for example. |
| email string  Optional | 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 |
| first\_name string  Optional | Cardholder's first name. **NOTE:** Required for KYC verification (US-based cardholders only). **Allowable Values:**  40 char max |
| gender string  Optional | Gender of the cardholder. **Allowable Values:**  `F`, `M` |
| honorific string  Optional | Cardholder's title or prefix: Dr., Miss, Mr., Ms., and so on. **Allowable Values:**  10 char max |
| id\_card\_expiration\_date string  Optional | Expiration date of the cardholder's identification card. **Allowable Values:**  Format: yyyy-MM-dd |
| id\_card\_number string  Optional | Cardholder's identification card number. **Allowable Values:**  255 char max |
| identifications array of objects  Optional | One or more objects containing identifications associated with the cardholder. **Allowable Values:**  Valid array of one or more `identifications` objects |
| identifications\[].**expiration\_date** string  Optional | Expiration date of the identification, if applicable. **Allowable Values:**  Format: yyyy-MM-dd |
| identifications\[].**type** string  Required | 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` |
| identifications\[].**value** string  Optional | Number associated with the identification. **Allowable Values:**  255 char max **NOTE:** Digits only, do not use separators. For example: 123456789 |
| ip\_address string  Optional | Cardholder's IP address. **Allowable Values:**  39 char max |
| last\_name string  Optional | Cardholder's last name. **NOTE:** Required for KYC verification (US-based cardholders only). **Allowable Values:**  40 char max |
| metadata object  Optional | 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  Optional | Cardholder's middle name. **Allowable Values:**  40 char max |
| nationality string  Optional | Cardholder's nationality. **Allowable Values:**  255 char max |
| notes string  Optional | Any additional information pertaining to the cardholder. **Allowable Values:**  255 char max |
| parent\_token string  Optional | 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 |
| passport\_expiration\_date string  Optional | Expiration date of the cardholder's passport. **Allowable Values:**  Format: yyyy-MM-dd |
| passport\_number string  Optional | Cardholder's passport number. **Allowable Values:**  40 char max |
| password string  Optional | 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 |
| phone string  Optional | 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 |
| postal\_code string  Optional | Postal code of the cardholder's address. **NOTE:** Required for KYC verification (US-based cardholders only). **Allowable Values:**  10 char max |
| ssn string  Optional | Cardholder's Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN). **Allowable Values:**  Nine digits only, no delimiters. `123456789`, for example. |
| state string  Optional | State or province where the cardholder resides. **NOTE:**[Valid two-character abbreviation](https://www.marqeta.com/docs/core-api/kyc-verification/perform.md#_valid_state_provincial_territorial_and_federal_abbreviations) required for KYC verification (US-based cardholders only). **Allowable Values:**  32 char max |
| title string  Optional | 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 |
| token string  Optional | 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 |
| uses\_parent\_account boolean  Optional | 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` |

## Sample request body

```json JSON expandable lines wrap theme={null}
{
  "first_name": "Jane",
  "last_name": "Doe",
  "token": "my_user_01",
  "email": "jane.doe@company.com",
  "title": "Chief Comptroller",
  "birth_place": "US",
  "password": "P@ssw0rd",
  "identifications": [
    {
      "type": "SSN",
      "value": "111234444"
    }
  ],
  "birth_date": "1991-01-01",
  "address1": "1234 Grove Street",
  "city": "Berkeley",
  "state": "CA",
  "country": "USA",
  "postal_code": "94702",
  "phone": "15105551212",
  "gender": "F",
  "uses_parent_account": false,
  "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"
  }
}
```

## 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.doe6@company.com",
  "title": "Chief Comptroller",
  "birth_place": "US",
  "address1": "1234 Grove Street",
  "city": "Berkeley",
  "state": "CA",
  "zip": "94702",
  "country": "USA",
  "phone": "15105551212",
  "uses_parent_account": false,
  "ssn": "5555",
  "corporate_card_holder": false,
  "password": "P@ssw0rd",
  "created_time": "2023-03-26T20:21:24Z",
  "last_modified_time": "2023-03-26T20:21:24Z",
  "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",
  "birth_date": "1991-01-01"
}
```


## Related topics

- [Create user transition](https://www.marqeta.com/docs/core-api/user-transitions/create-user-transition.md)
- [Users Overview](https://www.marqeta.com/docs/core-api/users.md)
- [User Transitions Overview](https://www.marqeta.com/docs/core-api/user-transitions.md)
- [About Powered By Marqeta in Europe](https://www.marqeta.com/docs/developer-guides/about-powered-by-marqeta-in-europe.md)
- [Businesses Overview](https://www.marqeta.com/docs/core-api/businesses.md)