Users | DevDocs Portal

The users resource represents a person who accesses Marqeta-administered funds via a Marqeta card (whether physical or virtual). This endpoint enables you to create and manage users on the Marqeta platform.

This resource stores user attributes such as name, address, and date of birth, as well as financial information such as balances. By default, every user automatically has a general purpose account (GPA) that is used for the funding of transfers and is therefore an account holder. Note that account balances reside at the account holder level — there are no separate account or balance objects.

You can use the /users endpoint to create parent-child relationships between two users (where one user is the parent and the other is the child) or between a business and a user (where the business is the parent and the user is the child). This relationship provides reporting to the parent about how cards of children are used and enables the parent to monitor and even restrict card usage.

Note
A user can simultaneously be a child of a business and a parent of other users if the user is not configured to use a parent’s account balances and the user’s child is configured to use a parent’s account balances. For more information on account holders, see About Account Holders.

Create user

Action: POST
Endpoint: /users

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

Mirrored from the Marqeta reference and truncated here so the MDX compile stays cheap while we demo the devdocs.dev skin. The full parameter table / response schema for this endpoint will be rendered from OpenAPI once the fumadocs-openapi integration lands.