Users
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
Copy section link
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 |
|
Optional |
Cannot load funds; cannot activate cards. |
Conditionally |
|
Optional |
Restricted by rules in |
Never |
|
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 -
last_name -
address1(cannot be a PO Box) -
city -
state -
postal_code -
country -
birth_date -
identifications
Note
Theidentifications 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) 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
Copy section link
| Fields | Description |
|---|---|
account_holder_group_token
string
|
Associates the specified account holder group with the cardholder. Send a Allowable Values: 36 char max |
active
boolean
|
Specifies if the cardholder is in the NOTE: Do not set the value of the Allowable Values:
|
address1
string
|
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
|
Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max |
birth_date
string
|
Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd |
city
string
|
City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
company
string
|
Company name. Allowable Values: 255 char max |
corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
Default value: |
country
string
|
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.
|
email
string
|
Valid email address of the cardholder. This value must be unique among users. Allowable Values: 1–255 chars |
first_name
string
|
Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
gender
string
|
Gender of the cardholder. Allowable Values:
|
honorific
string
|
Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
id_card_expiration_date
string
|
Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd |
id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
identifications[].expiration_date
string
|
Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
identifications[].type
string
|
Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification.
Nine digits only, no delimiters.
Allowable Values:
|
identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789 |
ip_address
string
|
Cardholder’s IP address. Allowable Values: 39 char max |
last_name
string
|
Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
metadata
object
|
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 |
middle_name
string
|
Cardholder’s middle name. Allowable Values: 40 char max |
nationality
string
|
Cardholder’s nationality. Allowable Values: 255 char max |
notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
parent_token
string
|
Unique identifier of the parent user or business resource.
Send a Required if Allowable Values: 1–36 chars |
passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
passport_number
string
|
Cardholder’s passport number. Allowable Values: 40 char max |
password
string
|
Password to the cardholder’s user account on the Marqeta platform.
Allowable Values: 255 char max |
phone
string
|
Telephone number of the cardholder (including area code), prepended by the Allowable Values: 255 char max Format: +15105551212 or +35552260859 |
postal_code
string
|
Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max |
ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
NOTE: Required for KYC verification (US-based cardholders only). |
state
string
|
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 |
token
string
|
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
|
Indicates whether the child shares balances with the parent ( If set to Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
account_holder_group_token
string
|
Associates the specified account holder group with the cardholder. Allowable Values: 36 char max |
active
boolean
|
Specifies if the cardholder is in the Allowable Values:
|
address1
string
|
Cardholder’s address. Allowable Values: 255 char max |
address2
string
|
Additional address information for the cardholder. Allowable Values: 255 char max |
authentication
object
|
Contains the cardholder’s email address and password information. Allowable Values:
|
authentication.email_verified
boolean
|
Specifies whether the email address has been verified. Allowable Values:
|
authentication.email_verified_time
datetime
|
Date and time when the email address was verified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
authentication.last_password_update_channel
string
|
Specifies the channel through which the password was last changed. Allowable Values:
|
authentication.last_password_update_time
datetime
|
Date and time when the password was last changed. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
birth_date
string
|
Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd |
business_token
string
|
Unique identifier of the business resource. Allowable Values: Existing business resource token |
city
string
|
City where the cardholder resides. Allowable Values: 40 char max |
company
string
|
Company name. Allowable Values: 255 char max |
corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
|
country
string
|
Country where the cardholder resides. Allowable Values: 40 char max |
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
email
string
|
Valid email address of the cardholder. Allowable Values: 1–255 chars |
first_name
string
|
Cardholder’s first name. Allowable Values: 40 char max |
gender
string
|
Gender of the cardholder. Allowable Values:
|
honorific
string
|
Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
id_card_expiration_date
string
|
Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd |
id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
identifications[].expiration_date
string
|
Expiration date for the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
identifications[].type
string
|
Type of identification. Allowable Values:
|
identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max |
ip_address
string
|
Cardholder’s IP address. Allowable Values: 39 char max |
last_modified_time
datetime
|
Date and time when the resource was last updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_name
string
|
Cardholder’s last name. Allowable Values: 40 char max |
metadata
object
|
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 |
middle_name
string
|
Cardholder’s middle name. Allowable Values: 40 char max |
nationality
string
|
Cardholder’s nationality. Allowable Values: 255 char max |
notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
parent_token
string
|
Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars |
passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
passport_number
string
|
Cardholder’s passport number. Allowable Values: 40 char max |
password
string
|
Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
phone
string
|
Cardholder’s telephone number. Allowable Values: 255 char max |
postal_code
string
|
Postal code of the cardholder’s address. Allowable Values: 10 char max |
ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters. |
state
string
|
State or province where the cardholder resides. Allowable Values: 2 char max |
status
string
|
Specifies the status of the cardholder on the Marqeta platform. Allowable Values:
|
token
string
|
Unique identifier of the cardholder. Allowable Values: 1–36 chars |
uses_parent_account
boolean
|
Indicates whether the child shares balances with the parent ( Allowable Values:
|
zip
string
|
United States ZIP code of the cardholder’s address. Allowable Values: 10 char max |
List users
Copy section link
Action: GET
Endpoint: /users
To return an array of all of a program’s users, send a GET request to the /users endpoint.
This endpoint supports field filtering and pagination.
To narrow your result set to users that match certain criteria, see the Search users endpoint.
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 |
Populated; matches |
User’s parent is a business. |
Populated; does not match |
Populated; does not match |
User’s parent is a user and their grandparent is a business. |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of user resources to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
search_type
string
|
Search type. Allowable Values:
|
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
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
|
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
|
Associates the specified account holder group with the cardholder. Send a Allowable Values: 36 char max |
data[].active
boolean
|
Specifies if the cardholder is in the NOTE: Do not set the value of the Allowable Values:
|
data[].address1
string
|
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
|
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
|
Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd |
data[].city
string
|
City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].company
string
|
Company name. Allowable Values: 255 char max |
data[].corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
Default value: |
data[].country
string
|
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.
|
data[].email
string
|
Valid email address of the cardholder. This value must be unique among users. Allowable Values: 1–255 chars |
data[].first_name
string
|
Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].gender
string
|
Gender of the cardholder. Allowable Values:
|
data[].honorific
string
|
Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
data[].id_card_expiration_date
string
|
Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd |
data[].id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
data[].identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
data[].identifications[].expiration_date
string
|
Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
data[].identifications[].type
string
|
Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification.
Nine digits only, no delimiters.
Allowable Values:
|
data[].identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789 |
data[].ip_address
string
|
Cardholder’s IP address. Allowable Values: 39 char max |
data[].last_name
string
|
Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].metadata
object
|
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 |
data[].middle_name
string
|
Cardholder’s middle name. Allowable Values: 40 char max |
data[].nationality
string
|
Cardholder’s nationality. Allowable Values: 255 char max |
data[].notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
data[].parent_token
string
|
Unique identifier of the parent user or business resource.
Send a Required if Allowable Values: 1–36 chars |
data[].passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
data[].passport_number
string
|
Cardholder’s passport number. Allowable Values: 40 char max |
data[].password
string
|
Password to the cardholder’s user account on the Marqeta platform.
Allowable Values: 255 char max |
data[].phone
string
|
Telephone number of the cardholder (including area code), prepended by the Allowable Values: 255 char max Format: +15105551212 or +35552260859 |
data[].postal_code
string
|
Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max |
data[].ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
NOTE: Required for KYC verification (US-based cardholders only). |
data[].state
string
|
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[].token
string
|
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
|
Indicates whether the child shares balances with the parent ( If set to Allowable Values:
Default value: |
end_index
integer
|
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
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
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 |
Retrieve user
Copy section link
Action: GET
Endpoint: /users/{token}
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 |
Populated; matches |
User’s parent is a business. |
Populated; does not match |
Populated; does not match |
User’s parent is a user and their grandparent is a business. |
This endpoint supports field filtering.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the user resource. Allowable Values: Existing user resource token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
Response body
Copy section link
| Fields | Description |
|---|---|
account_holder_group_token
string
|
Associates the specified account holder group with the cardholder. Allowable Values: 36 char max |
active
boolean
|
Specifies if the cardholder is in the Allowable Values:
|
address1
string
|
Cardholder’s address. Allowable Values: 255 char max |
address2
string
|
Additional address information for the cardholder. Allowable Values: 255 char max |
authentication
object
|
Contains the cardholder’s email address and password information. Allowable Values:
|
authentication.email_verified
boolean
|
Specifies whether the email address has been verified. Allowable Values:
|
authentication.email_verified_time
datetime
|
Date and time when the email address was verified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
authentication.last_password_update_channel
string
|
Specifies the channel through which the password was last changed. Allowable Values:
|
authentication.last_password_update_time
datetime
|
Date and time when the password was last changed. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
birth_date
string
|
Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd |
business_token
string
|
Unique identifier of the business resource. Allowable Values: Existing business resource token |
city
string
|
City where the cardholder resides. Allowable Values: 40 char max |
company
string
|
Company name. Allowable Values: 255 char max |
corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
|
country
string
|
Country where the cardholder resides. Allowable Values: 40 char max |
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
email
string
|
Valid email address of the cardholder. Allowable Values: 1–255 chars |
first_name
string
|
Cardholder’s first name. Allowable Values: 40 char max |
gender
string
|
Gender of the cardholder. Allowable Values:
|
honorific
string
|
Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
id_card_expiration_date
string
|
Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd |
id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
identifications[].expiration_date
string
|
Expiration date for the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
identifications[].type
string
|
Type of identification. Allowable Values:
|
identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max |
ip_address
string
|
Cardholder’s IP address. Allowable Values: 39 char max |
last_modified_time
datetime
|
Date and time when the resource was last updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_name
string
|
Cardholder’s last name. Allowable Values: 40 char max |
metadata
object
|
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 |
middle_name
string
|
Cardholder’s middle name. Allowable Values: 40 char max |
nationality
string
|
Cardholder’s nationality. Allowable Values: 255 char max |
notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
parent_token
string
|
Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars |
passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
passport_number
string
|
Cardholder’s passport number. Allowable Values: 40 char max |
password
string
|
Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
phone
string
|
Cardholder’s telephone number. Allowable Values: 255 char max |
postal_code
string
|
Postal code of the cardholder’s address. Allowable Values: 10 char max |
ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters. |
state
string
|
State or province where the cardholder resides. Allowable Values: 2 char max |
status
string
|
Specifies the status of the cardholder on the Marqeta platform. Allowable Values:
|
token
string
|
Unique identifier of the cardholder. Allowable Values: 1–36 chars |
uses_parent_account
boolean
|
Indicates whether the child shares balances with the parent ( Allowable Values:
|
zip
string
|
United States ZIP code of the cardholder’s address. Allowable Values: 10 char max |
Update user
Copy section link
Action: PUT
Endpoint: /users/{token}
To update a specific user resource, send a PUT request to the /users/{token} endpoint.
Include the user token path parameter to specify the user to update.
To unlink a child user account from a parent account, pass a null value to the parent_token field of the child user resource.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Unique identifier of the user resource you want to update. Allowable Values: Existing user resource token |
Request body
Copy section link
| Fields | Description |
|---|---|
account_holder_group_token
string
|
Associates the specified account holder group with the cardholder.
Send a Allowable Values: 36 char max |
address1
string
|
Cardholder 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
|
Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max |
birth_date
string
|
Cardholder date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd |
city
string
|
The city that corresponds to the address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
company
string
|
Company name. Allowable Values: 255 char max |
corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
|
country
string
|
Country in which the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max NOTE: ISO alpha-2 country code is required for KYC verification.
|
email
string
|
Valid email address for the cardholder. This value must be unique among cardholders. Allowable Values: 1–255 chars |
first_name
string
|
Cardholder first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
gender
string
|
Gender of the cardholder. Allowable Values:
|
honorific
string
|
Cardholder title or prefix: Ms., Mr., Miss, Mrs. Allowable Values: 10 char max |
id_card_expiration_date
string
|
Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd |
id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
identifications[].expiration_date
string
|
Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
identifications[].type
string
|
Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification.
Nine digits only, no delimiters.
Allowable Values:
|
identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789 |
ip_address
string
|
Cardholder IP address. Allowable Values: 39 char max |
last_name
string
|
Cardholder last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
metadata
object
|
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 |
middle_name
string
|
Cardholder middle name. Allowable Values: 40 char max |
nationality
string
|
Cardholder nationality. Allowable Values: 255 char max |
notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
parent_token
string
|
Unique identifier of an existing user or business resource. Required if To unlink a child account from a parent account, update this field to a null value. Allowable Values: 1–36 chars |
passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
passport_number
string
|
Cardholder passport number. Allowable Values: 40 char max |
password
string
|
Cardholder’s user account password on the Marqeta platform. Allowable Values: 255 char max |
phone
string
|
Cardholder telephone number (including area code), prepended by the Allowable Values: 255 char max Format: +15105551212 or +35552260859 |
postal_code
string
|
Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max |
ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
NOTE: Required for KYC verification (US-based cardholders only). |
state
string
|
State where the cardholder resides. NOTE: Valid two-character abbreviation required for KYC verification (US-based cardholders only). Allowable Values: 32 char max |
token
string
|
Unique identifier of the cardholder. Allowable Values: 1–36 chars |
uses_parent_account
boolean
|
Indicates whether the child shares balances with the parent ( If set to Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
account_holder_group_token
string
|
Associates the specified account holder group with the cardholder. Send a Allowable Values: 36 char max |
active
boolean
|
Specifies if the cardholder is in the NOTE: Do not set the value of the Allowable Values:
|
address1
string
|
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
|
Additional address information for the cardholder. NOTE: Cannot perform KYC if set to a PO Box. Allowable Values: 255 char max |
birth_date
string
|
Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd |
city
string
|
City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
company
string
|
Company name. Allowable Values: 255 char max |
corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
Default value: |
country
string
|
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.
|
email
string
|
Valid email address of the cardholder. This value must be unique among users. Allowable Values: 1–255 chars |
first_name
string
|
Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
gender
string
|
Gender of the cardholder. Allowable Values:
|
honorific
string
|
Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
id_card_expiration_date
string
|
Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd |
id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
identifications[].expiration_date
string
|
Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
identifications[].type
string
|
Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification.
Nine digits only, no delimiters.
Allowable Values:
|
identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789 |
ip_address
string
|
Cardholder’s IP address. Allowable Values: 39 char max |
last_name
string
|
Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
metadata
object
|
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 |
middle_name
string
|
Cardholder’s middle name. Allowable Values: 40 char max |
nationality
string
|
Cardholder’s nationality. Allowable Values: 255 char max |
notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
parent_token
string
|
Unique identifier of the parent user or business resource.
Send a Required if Allowable Values: 1–36 chars |
passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
passport_number
string
|
Cardholder’s passport number. Allowable Values: 40 char max |
password
string
|
Password to the cardholder’s user account on the Marqeta platform.
Allowable Values: 255 char max |
phone
string
|
Telephone number of the cardholder (including area code), prepended by the Allowable Values: 255 char max Format: +15105551212 or +35552260859 |
postal_code
string
|
Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max |
ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
NOTE: Required for KYC verification (US-based cardholders only). |
state
string
|
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 |
token
string
|
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
|
Indicates whether the child shares balances with the parent ( If set to Allowable Values:
Default value: |
Update user password
Copy section link
Action: POST
Endpoint: /users/auth/changepassword
To change a user password, send a POST request to the /users/auth/changepassword endpoint and include the current_password and new_password in JSON format in the body of the request.
This endpoint operates in the context of a currently logged-in user.
A successful password change returns an empty response body with a response code of 204 No Content.
Request body
Copy section link
| Fields | Description |
|---|---|
current_password
string
|
Current password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
new_password
string
|
New password to the cardholder’s user account on the Marqeta platform.
Allowable Values: 1–255 chars |
Create client access token
Copy section link
Action: POST
Endpoint: /users/auth/clientaccesstoken
Each time you want to display a virtual card’s sensitive data (for example, when using marqeta.js), you must first request a new, single-use client access token from the Marqeta platform by sending a POST request to the /users/auth/clientaccesstoken endpoint.
Unredeemed client access tokens expire after five minutes.
Request body
Copy section link
| Fields | Description |
|---|---|
application_token
string
|
Unique identifier of the Allowable Values: 1–255 chars |
card_token
string
|
Unique identifier of the card whose sensitive information you want to display. Allowable Values: 1–255 chars |
Response body
Copy section link
| Fields | Description |
|---|---|
application
object
|
Contains client application information. Allowable Values: Existing |
application.access_code
string
|
Access code of the client application. Allowable Values: 255 char max |
application.assets_url
string
|
URL of the client application assets. Allowable Values: 255 char max |
application.client_api_base_url
string
|
Base URL of the client API. Allowable Values: 255 char max |
application.environment
string
|
Client application’s environment. Allowable Values: 255 char max |
application.program
string
|
Name of the program on the Marqeta platform. Allowable Values: 255 char max |
application.program_short_code
string
|
Short code of the program on the Marqeta platform. Allowable Values: 255 char max |
application.token
string
|
Unique identifier of the Allowable Values: 36 char max |
card_token
string
|
Unique identifier of the card whose sensitive information you want to display. Allowable Values: Existing card token |
created
datetime
|
Date and time that the client access token was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
expires
datetime
|
Date and time that the client access token expires, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
Value of the client access token to redeem when displaying sensitive card data. Allowable Values: Existing client access token |
Retrieve client access token
Copy section link
Action: GET
Endpoint: /users/auth/clientaccesstoken/{token}
To retrieve application and card information using a client access token, send a GET request to the /users/auth/clientaccesstoken/{token} endpoint.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Client access token. Allowable Values: Existing client access token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
application_token
string
|
Unique identifier of the Allowable Values: Existing application token |
Response body
Copy section link
| Fields | Description |
|---|---|
application
object
|
Contains client application information. Allowable Values: Existing |
application.access_code
string
|
Access code of the client application. Allowable Values: 255 char max |
application.assets_url
string
|
URL of the client application assets. Allowable Values: 255 char max |
application.client_api_base_url
string
|
Base URL of the client API. Allowable Values: 255 char max |
application.environment
string
|
Client application’s environment. Allowable Values: 255 char max |
application.program
string
|
Name of the program on the Marqeta platform. Allowable Values: 255 char max |
application.program_short_code
string
|
Short code of the program on the Marqeta platform. Allowable Values: 255 char max |
application.token
string
|
Unique identifier of the Allowable Values: 36 char max |
card_token
string
|
Unique identifier of the card whose sensitive information you want to display. Allowable Values: Existing card token |
created
datetime
|
Date and time that the client access token was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
expires
datetime
|
Date and time that the client access token expires, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
token
string
|
Value of the client access token to redeem when displaying sensitive card data. Allowable Values: Existing client access token |
Log in user
Copy section link
Action: POST
Endpoint: /users/auth/login
To log in a user and return a user access token, send a POST request to the /users/auth/login endpoint and include the user details in JSON format in the body of the request.
Tip
To check a user’s credentials without logging out the user, call the/users/auth/onetime endpoint.
Request body
Copy section link
| Fields | Description |
|---|---|
email
string
|
Cardholder email address. Allowable Values: 255 char max |
password
string
|
Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
user_token
string
|
Identifies the cardholder to log in. Send a Allowable Values: 1–36 chars |
Response body
Copy section link
| Fields | Description |
|---|---|
access_token
object
|
Contains a cardholder’s login access information. Allowable Values: Existing |
access_token.application
object
|
Contains client application information. Allowable Values: Existing |
access_token.application.access_code
string
|
Access code of the client application. Allowable Values: 255 char max |
access_token.application.assets_url
string
|
URL of the client application assets. Allowable Values: 255 char max |
access_token.application.client_api_base_url
string
|
Base URL of the client API. Allowable Values: 255 char max |
access_token.application.environment
string
|
Client application’s environment. Allowable Values: 255 char max |
access_token.application.program
string
|
Name of the program on the Marqeta platform. Allowable Values: 255 char max |
access_token.application.program_short_code
string
|
Short code of the program on the Marqeta platform. Allowable Values: 255 char max |
access_token.application.token
string
|
Unique identifier of the Allowable Values: 36 char max |
access_token.expires
datetime
|
Date and time when the access token expires. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
access_token.master_roles
array of strings
|
Array of master roles. Allowable Values: Valid array of one or more |
access_token.one_time
boolean
|
Indicates whether the access token is a single-use token. Allowable Values:
|
access_token.token
string
|
Unique identifier of the access token. Allowable Values: 36 char max |
access_token.token_type
string
|
Specifies the type of access token. Allowable Values:
|
access_token.user_token
string
|
Unique identifier of the user resource. Allowable Values: 36 char max |
user
object
|
Contains information about a cardholder. Allowable Values:
|
user.account_holder_group_token
string
|
Associates the specified account holder group with the cardholder. Allowable Values: 36 char max |
user.active
boolean
|
Specifies if the cardholder is in the Allowable Values:
|
user.address1
string
|
Cardholder’s address. Allowable Values: 255 char max |
user.address2
string
|
Additional address information for the cardholder. Allowable Values: 255 char max |
user.authentication
object
|
Contains the cardholder’s email address and password information. Allowable Values:
|
user.authentication.email_verified
boolean
|
Specifies whether the email address has been verified. Allowable Values:
|
user.authentication.email_verified_time
datetime
|
Date and time when the email address was verified. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
user.authentication.last_password_update_channel
string
|
Specifies the channel through which the password was last changed. Allowable Values:
|
user.authentication.last_password_update_time
datetime
|
Date and time when the password was last changed. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
user.birth_date
string
|
Cardholder’s date of birth. Allowable Values: Format: yyyy-MM-dd |
user.business_token
string
|
Unique identifier of the business resource. Allowable Values: Existing business resource token |
user.city
string
|
City where the cardholder resides. Allowable Values: 40 char max |
user.company
string
|
Company name. Allowable Values: 255 char max |
user.corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
|
user.country
string
|
Country where the cardholder resides. Allowable Values: 40 char max |
user.created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
user.email
string
|
Valid email address of the cardholder. Allowable Values: 1–255 chars |
user.first_name
string
|
Cardholder’s first name. Allowable Values: 40 char max |
user.gender
string
|
Gender of the cardholder. Allowable Values:
|
user.honorific
string
|
Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
user.id_card_expiration_date
string
|
Expiration date of the cardholder’s identification. Allowable Values: Format: yyyy-MM-dd |
user.id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
user.identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
user.identifications[].expiration_date
string
|
Expiration date for the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
user.identifications[].type
string
|
Type of identification. Allowable Values:
|
user.identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max |
user.ip_address
string
|
Cardholder’s IP address. Allowable Values: 39 char max |
user.last_modified_time
datetime
|
Date and time when the resource was last updated, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
user.last_name
string
|
Cardholder’s last name. Allowable Values: 40 char max |
user.metadata
object
|
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 |
user.middle_name
string
|
Cardholder’s middle name. Allowable Values: 40 char max |
user.nationality
string
|
Cardholder’s nationality. Allowable Values: 255 char max |
user.notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
user.parent_token
string
|
Unique identifier of the parent user or business resource. Allowable Values: 1–36 chars |
user.passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
user.passport_number
string
|
Cardholder’s passport number. Allowable Values: 40 char max |
user.password
string
|
Password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
user.phone
string
|
Cardholder’s telephone number. Allowable Values: 255 char max |
user.postal_code
string
|
Postal code of the cardholder’s address. Allowable Values: 10 char max |
user.ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters. |
user.state
string
|
State or province where the cardholder resides. Allowable Values: 2 char max |
user.status
string
|
Specifies the status of the cardholder on the Marqeta platform. Allowable Values:
|
user.token
string
|
Unique identifier of the cardholder. Allowable Values: 1–36 chars |
user.uses_parent_account
boolean
|
Indicates whether the child shares balances with the parent ( Allowable Values:
|
user.zip
string
|
United States ZIP code of the cardholder’s address. Allowable Values: 10 char max |
Log out user
Copy section link
Action: POST
Endpoint: /users/auth/logout
To log out a user, send a POST request to the /users/auth/logout endpoint.
A successful logout returns an empty response body with a response code of 204 No Content.
Create single-use token
Copy section link
Action: POST
Endpoint: /users/auth/onetime
This endpoint returns a single-use access token.
This type of token authorizes a single request to access API endpoints and data associated with a particular user.
A single-use access token differs from a user access token (as returned by POST /users/auth/login) only in the number of times it can be used.
To return a single-use access token, send a POST request to the /users/auth/onetime endpoint.
Provide one of these sets of input data:
-
Case #1 – Application token and user access token
-
Case #2 – Application token, admin access token, and user token
-
Case #3 – Application token, user’s Marqeta password, and user’s email address
In each case, provide the application token as the HTTP Basic Authentication username in the request header’s Authorization field. When applicable, provide the user access token or admin access token as the HTTP Basic Authentication password. When applicable, provide the user token or user’s Marqeta password and email address in JSON format in the request body.
Before instantiating an embedded Marqeta widget, call this endpoint to obtain the single-use access token required as input (cases #1 and #2).
This endpoint is also useful when you want to check a user’s credentials before performing a sensitive operation without having to log out the user (case #3).
Note
Calling this endpoint and returning a single-use access token does not invalidate the user’s current user access token.
Request body
Copy section link
| Fields | Description |
|---|---|
email
string
|
Cardholder email address. Required when neither the user token nor the admin access token is provided as the Basic Authentication password (case #3). Allowable Values: 1–255 chars |
password
string
|
Password to the cardholder’s user account on the Marqeta platform. Required when neither the user token nor the admin access token is provided as the Basic Authentication password (case #3). Allowable Values: 1–255 chars |
user_token
string
|
Identifies the cardholder whose data is accessed.
Send a Required when the Basic Authentication password is set to an admin access token (case #2). Allowable Values: 1–36 chars |
Sample request body
Copy section link
Case 1: Authorization: Basic my_application_token:my_user_access_token
Case 2: Authorization: Basic my_application_token:my_admin_access_token
Case 3: Authorization: Basic my_application_token
Response body
Copy section link
| Fields | Description |
|---|---|
application
object
|
Contains client application information. Allowable Values: Existing |
application.access_code
string
|
Access code of the client application. Allowable Values: 255 char max |
application.assets_url
string
|
URL of the client application assets. Allowable Values: 255 char max |
application.client_api_base_url
string
|
Base URL of the client API. Allowable Values: 255 char max |
application.environment
string
|
Client application’s environment. Allowable Values: 255 char max |
application.program
string
|
Name of the program on the Marqeta platform. Allowable Values: 255 char max |
application.program_short_code
string
|
Short code of the program on the Marqeta platform. Allowable Values: 255 char max |
application.token
string
|
Unique identifier of the Allowable Values: 36 char max |
expires
datetime
|
Date and time when the access token expires. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
master_roles
array of strings
|
Array of master roles. Allowable Values: Valid array of one or more |
one_time
boolean
|
Indicates whether the access token is a single-use token. Allowable Values:
|
token
string
|
Unique identifier of the access token. Allowable Values: 36 char max |
token_type
string
|
Specifies the type of access token. Allowable Values:
|
user_token
string
|
Unique identifier of the user resource. Allowable Values: 36 char max |
Request user password reset token
Copy section link
Action: POST
Endpoint: /users/auth/resetpassword
Use this endpoint to generate a password reset token for a user.
Send a POST request to the /users/auth/resetpassword endpoint and include the user’s email address in JSON format in the body of the request.
This request generates and sends an email message containing the user_token and password_reset_token to the user’s email address.
You must customize the email message with a link that passes the user_token and password_reset_token to a web page where a subsequent request updates the password.
A successful request returns an empty response body with a response code of 204 No Content.
Request body
Copy section link
| Fields | Description |
|---|---|
email
string
|
Cardholder email address. Allowable Values: 1–255 chars |
Reset user password
Copy section link
Action: POST
Endpoint: /users/auth/resetpassword/{token}
To reset the user’s password, send a POST request to the /users/auth/resetpassword/{token} endpoint that includes a password reset token generated using the POST /users/auth/resetpassword operation.
Include the user_token and new_password in JSON format in the body of the request.
Include the password_reset_token as a path parameter.
A successful password reset returns an empty response body with a response code of 204 No Content.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Password reset token generated using the Allowable Values: Existing password reset token |
Request body
Copy section link
| Fields | Description |
|---|---|
new_password
string
|
New password to the cardholder’s user account on the Marqeta platform. Allowable Values: 1–255 chars |
user_token
string
|
Unique identifier of the cardholder. Allowable Values: 1–36 chars |
Request email verification token
Copy section link
Action: POST
Endpoint: /users/auth/verifyemail
Send a POST request to the /users/auth/verifyemail endpoint to request an email verification token.
No input parameters are required because this operation is performed in the context of an authenticated user.
This initial request generates and sends an email message containing the email verification token to the cardholder’s email address. This email message must include a link that passes the email verification token to a web page where a subsequent request verifies the email address.
A successful request returns an empty response body with a response code of 204 No Content.
Verify email address
Copy section link
Action: POST
Endpoint: /users/auth/verifyemail/{token}
To verify a user’s email address, send a POST request to the /users/auth/verifyemail/{email_verification_token} endpoint that includes an email_verification_token generated using the POST /users/auth/verifyemail operation.
Include the email_verification_token as a path parameter.
A successful email verification returns an empty response body with a response code of 204 No Content.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Email verification token generated using the Allowable Values: Existing email verification token |
Search users
Copy section link
Action: POST
Endpoint: /users/lookup
To search for one or more users, send a POST request to the /users/lookup endpoint.
Include in the message body any parameters by which you want to query.
This endpoint supports field filtering and pagination.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of user resources to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
search_type
string
|
Search type. Allowable Values:
|
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Request body
Copy section link
| Fields | Description |
|---|---|
dda
string
|
Performs a match on the specified deposit account number.
Send a Allowable Values: Existing deposit account number |
email
string
|
Performs a non-case-sensitive, exact match on the cardholder’s Allowable Values: 1–255 chars |
first_name
string
|
Performs a non-case-sensitive match on the cardholder’s Allowable Values: 40 char max |
last_name
string
|
Performs a non-case-sensitive match on the cardholder’s Allowable Values: 40 char max |
phone
string
|
Performs a match on the cardholder’s Allowable Values: 255 char max |
ssn
string
|
Performs a match on the cardholder’s identification number. Allowable Values: Either a complete identification number or the last four digits. Digits only, no delimiters. |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
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
|
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
|
Associates the specified account holder group with the cardholder. Send a Allowable Values: 36 char max |
data[].active
boolean
|
Specifies if the cardholder is in the NOTE: Do not set the value of the Allowable Values:
|
data[].address1
string
|
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
|
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
|
Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd |
data[].city
string
|
City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].company
string
|
Company name. Allowable Values: 255 char max |
data[].corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
Default value: |
data[].country
string
|
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.
|
data[].email
string
|
Valid email address of the cardholder. This value must be unique among users. Allowable Values: 1–255 chars |
data[].first_name
string
|
Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].gender
string
|
Gender of the cardholder. Allowable Values:
|
data[].honorific
string
|
Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
data[].id_card_expiration_date
string
|
Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd |
data[].id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
data[].identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
data[].identifications[].expiration_date
string
|
Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
data[].identifications[].type
string
|
Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification.
Nine digits only, no delimiters.
Allowable Values:
|
data[].identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789 |
data[].ip_address
string
|
Cardholder’s IP address. Allowable Values: 39 char max |
data[].last_name
string
|
Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].metadata
object
|
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 |
data[].middle_name
string
|
Cardholder’s middle name. Allowable Values: 40 char max |
data[].nationality
string
|
Cardholder’s nationality. Allowable Values: 255 char max |
data[].notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
data[].parent_token
string
|
Unique identifier of the parent user or business resource.
Send a Required if Allowable Values: 1–36 chars |
data[].passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
data[].passport_number
string
|
Cardholder’s passport number. Allowable Values: 40 char max |
data[].password
string
|
Password to the cardholder’s user account on the Marqeta platform.
Allowable Values: 255 char max |
data[].phone
string
|
Telephone number of the cardholder (including area code), prepended by the Allowable Values: 255 char max Format: +15105551212 or +35552260859 |
data[].postal_code
string
|
Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max |
data[].ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
NOTE: Required for KYC verification (US-based cardholders only). |
data[].state
string
|
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[].token
string
|
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
|
Indicates whether the child shares balances with the parent ( If set to Allowable Values:
Default value: |
end_index
integer
|
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
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
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 |
List user child accounts
Copy section link
Action: GET
Endpoint: /users/{parent_token}/children
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 |
Populated; matches |
User’s parent is a business. |
Populated; does not match |
Populated; does not match |
User’s parent is a user and their grandparent is a business. |
This endpoint supports field filtering.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
parent_token
string
|
Unique identifier of the parent account holder. Allowable Values: Existing user or business resource token |
URL query parameters
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of user resources to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
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
|
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
|
Associates the specified account holder group with the cardholder. Send a Allowable Values: 36 char max |
data[].active
boolean
|
Specifies if the cardholder is in the NOTE: Do not set the value of the Allowable Values:
|
data[].address1
string
|
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
|
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
|
Cardholder’s date of birth. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: Format: yyyy-MM-dd |
data[].city
string
|
City where the cardholder resides. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].company
string
|
Company name. Allowable Values: 255 char max |
data[].corporate_card_holder
boolean
|
Specifies if the cardholder holds a corporate card. Allowable Values:
Default value: |
data[].country
string
|
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.
|
data[].email
string
|
Valid email address of the cardholder. This value must be unique among users. Allowable Values: 1–255 chars |
data[].first_name
string
|
Cardholder’s first name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].gender
string
|
Gender of the cardholder. Allowable Values:
|
data[].honorific
string
|
Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on. Allowable Values: 10 char max |
data[].id_card_expiration_date
string
|
Expiration date of the cardholder’s identification card. Allowable Values: Format: yyyy-MM-dd |
data[].id_card_number
string
|
Cardholder’s identification card number. Allowable Values: 255 char max |
data[].identifications
array of objects
|
One or more objects containing identifications associated with the cardholder. Allowable Values: Valid array of one or more |
data[].identifications[].expiration_date
string
|
Expiration date of the identification, if applicable. Allowable Values: Format: yyyy-MM-dd |
data[].identifications[].type
string
|
Type of identification. NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification.
Nine digits only, no delimiters.
Allowable Values:
|
data[].identifications[].value
string
|
Number associated with the identification. Allowable Values: 255 char max NOTE: Digits only, do not use separators. For example: 123456789 |
data[].ip_address
string
|
Cardholder’s IP address. Allowable Values: 39 char max |
data[].last_name
string
|
Cardholder’s last name. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 40 char max |
data[].metadata
object
|
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 |
data[].middle_name
string
|
Cardholder’s middle name. Allowable Values: 40 char max |
data[].nationality
string
|
Cardholder’s nationality. Allowable Values: 255 char max |
data[].notes
string
|
Any additional information pertaining to the cardholder. Allowable Values: 255 char max |
data[].parent_token
string
|
Unique identifier of the parent user or business resource.
Send a Required if Allowable Values: 1–36 chars |
data[].passport_expiration_date
string
|
Expiration date of the cardholder’s passport. Allowable Values: Format: yyyy-MM-dd |
data[].passport_number
string
|
Cardholder’s passport number. Allowable Values: 40 char max |
data[].password
string
|
Password to the cardholder’s user account on the Marqeta platform.
Allowable Values: 255 char max |
data[].phone
string
|
Telephone number of the cardholder (including area code), prepended by the Allowable Values: 255 char max Format: +15105551212 or +35552260859 |
data[].postal_code
string
|
Postal code of the cardholder’s address. NOTE: Required for KYC verification (US-based cardholders only). Allowable Values: 10 char max |
data[].ssn
string
|
Cardholder’s Social Security Number (SSN). Allowable Values: Nine digits only, no delimiters.
NOTE: Required for KYC verification (US-based cardholders only). |
data[].state
string
|
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[].token
string
|
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
|
Indicates whether the child shares balances with the parent ( If set to Allowable Values:
Default value: |
end_index
integer
|
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
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
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 |
Retrieve user identification number
Copy section link
Action: GET
Endpoint: /users/{token}/ssn