Create user

POST/

This endpoint enables you to create a user. A new user’s initial status depends on the Know Your Customer (KYC) requirements of the program or associated account holder group.

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

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

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

Getting Started

Testing

Card Issuing

Card Processing

Accounts & Money Movement

Risk, Fraud, and Disputes

Cardholder User Experience

Request body

Sample request body

Response body

Sample response body

​Request body

​Sample request body

​Response body

​Sample response body

Request body

Sample request body

Response body

Sample response body