/
75 minute read
April 20, 2023

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

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

  • last_name

  • address1 (cannot be a PO Box)

  • city

  • state

  • postal_code

  • country

  • birth_date

  • identifications

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

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.

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 cardholder KYC verification. 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.

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

Allowable Values:

Nine digits only, no delimiters. 123456789, for example.

NOTE: Required for KYC verification (US-based cardholders only).

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

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
Copied

Is this helpful?

Yes
No

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:

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:

Format: yyyy-MM-ddThh:mm:ssZ

birth_date

string
Conditionally returned

Cardholder’s date of birth.

Allowable Values:

Format: yyyy-MM-dd

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:

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 for 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:

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

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
Copied

Is this helpful?

Yes
No

List users

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 business_token

Populated; matches parent_token

User’s parent is a business.

Populated; does not match business_token

Populated; does not match parent_token

User’s parent is a user and their grandparent is a business.

URL query parameters

Fields Description

count

integer
Optional

Number of user resources to retrieve.

Allowable Values:

1-10

Default value:
5

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

search_type

string
Optional

Search type.

Allowable Values:

query_then_fetch, dfs_query_then_fetch

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-lastModifiedTime

Response body

Fields Description

count

integer
Conditionally returned

Number of resources to retrieve.

This field is returned if there are resources in your returned array.

Allowable Values:

1-10

data

array of objects
Conditionally returned

Array of user objects.

Objects are returned as appropriate to your query.

Allowable Values:

Valid array of one or more user objects

data[].account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the cardholder.

Send a GET request to /accountholdergroups to retrieve account holder group tokens.

Allowable Values:

36 char max

data[].active

boolean
Conditionally returned

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

NOTE: Do not set the value of the user.active field directly. Instead, use the /usertransitions endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition.

Allowable Values:

true, false

data[].address1

string
Conditionally returned

Cardholder’s address.

NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

data[].address2

string
Conditionally returned

Additional address information for the cardholder.

NOTE: Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

data[].birth_date

string
Conditionally returned

Cardholder’s date of birth.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

Format: yyyy-MM-dd

data[].city

string
Conditionally returned

City where the cardholder resides.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].company

string
Conditionally returned

Company name.

Allowable Values:

255 char max

data[].corporate_card_holder

boolean
Conditionally returned

Specifies if the cardholder holds a corporate card.

Allowable Values:

true, false

Default value:
false

data[].country

string
Conditionally returned

Country where the cardholder resides.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

NOTE: ISO alpha-2 country code required for KYC verification. US, for example.

data[].email

string
Conditionally returned

Valid email address of the cardholder.

This value must be unique among users.

Allowable Values:

1–255 chars

data[].first_name

string
Conditionally returned

Cardholder’s first name.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].gender

string
Conditionally returned

Gender of the cardholder.

Allowable Values:

F, M

data[].honorific

string
Conditionally returned

Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.

Allowable Values:

10 char max

data[].id_card_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s identification card.

Allowable Values:

Format: yyyy-MM-dd

data[].id_card_number

string
Conditionally returned

Cardholder’s identification card number.

Allowable Values:

255 char max

data[].identifications

array of objects
Conditionally returned

One or more objects containing identifications associated with the cardholder.

Allowable Values:

Valid array of one or more identifications objects

data[].identifications[].expiration_date

string
Conditionally returned

Expiration date of the identification, if applicable.

Allowable Values:

Format: yyyy-MM-dd

data[].identifications[].type

string
Returned

Type of identification.

NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification. Nine digits only, no delimiters. 123456789, for example.

Allowable Values:

SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE

data[].identifications[].value

string
Conditionally returned

Number associated with the identification.

Allowable Values:

255 char max

NOTE: Digits only, do not use separators. For example: 123456789

data[].ip_address

string
Conditionally returned

Cardholder’s IP address.

Allowable Values:

39 char max

data[].last_name

string
Conditionally returned

Cardholder’s last name.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].metadata

object
Conditionally returned

Associates any additional metadata you provide with the cardholder.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1".

data[].middle_name

string
Conditionally returned

Cardholder’s middle name.

Allowable Values:

40 char max

data[].nationality

string
Conditionally returned

Cardholder’s nationality.

Allowable Values:

255 char max

data[].notes

string
Conditionally returned

Any additional information pertaining to the cardholder.

Allowable Values:

255 char max

data[].parent_token

string
Conditionally returned

Unique identifier of the parent user or business resource. Send a GET request to /users to retrieve user resource tokens or to /businesses to retrieve business resource tokens.

Required if uses_parent_account = true. This user or business is configured as the parent of the current user.

Allowable Values:

1–36 chars

data[].passport_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s passport.

Allowable Values:

Format: yyyy-MM-dd

data[].passport_number

string
Conditionally returned

Cardholder’s passport number.

Allowable Values:

40 char max

data[].password

string
Conditionally returned

Password to the cardholder’s user account on the Marqeta platform.

  • Must contain at least one numeral

  • Must contain at least one lowercase letter

  • Must contain at least one uppercase letter

  • Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

Allowable Values:

255 char max

data[].phone

string
Conditionally returned

Telephone number of the cardholder (including area code), prepended by the + symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses.

Allowable Values:

255 char max

Format: +15105551212 or +35552260859

data[].postal_code

string
Conditionally returned

Postal code of the cardholder’s address.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

10 char max

data[].ssn

string
Conditionally returned

Cardholder’s Social Security Number (SSN).

Allowable Values:

Nine digits only, no delimiters. 123456789, for example.

NOTE: Required for KYC verification (US-based cardholders only).

data[].state

string
Conditionally returned

State or province where the cardholder resides.

NOTE: Valid two-character abbreviation required for KYC verification (US-based cardholders only).

Allowable Values:

32 char max

data[].token

string
Conditionally returned

Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars

data[].uses_parent_account

boolean
Conditionally returned

Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).

If set to true, you must also include a parent_token in the request. This value cannot be updated.

Allowable Values:

true, false

Default value:
false

end_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false

start_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve user

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 business_token

Populated; matches parent_token

User’s parent is a business.

Populated; does not match business_token

Populated; does not match parent_token

User’s parent is a user and their grandparent is a business.

This endpoint supports field filtering.

URL path parameters

Fields Description

token

string
Required

Unique identifier of the user resource.

Allowable Values:

Existing user resource token

URL query parameters

Fields Description

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

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:

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:

Format: yyyy-MM-ddThh:mm:ssZ

birth_date

string
Conditionally returned

Cardholder’s date of birth.

Allowable Values:

Format: yyyy-MM-dd

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:

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 for 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:

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

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
Copied

Is this helpful?

Yes
No

Update user

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

Fields Description

token

string
Required

Unique identifier of the user resource you want to update.

Allowable Values:

Existing user resource token

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

address1

string
Optional

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
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 date of birth.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

Format: yyyy-MM-dd

city

string
Optional

The city that corresponds to the address.

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

country

string
Optional

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. US, for example.

email

string
Optional

Valid email address for the cardholder.

This value must be unique among cardholders.

Allowable Values:

1–255 chars

first_name

string
Optional

Cardholder 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 title or prefix: Ms., Mr., Miss, Mrs.

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 cardholder KYC verification. 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 IP address.

Allowable Values:

39 char max

last_name

string
Optional

Cardholder 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 middle name.

Allowable Values:

40 char max

nationality

string
Optional

Cardholder 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 an existing user or business resource.

Required if uses_parent_account = true. This account holder is configured as the parent of the current cardholder.

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
Optional

Expiration date of the cardholder’s passport.

Allowable Values:

Format: yyyy-MM-dd

passport_number

string
Optional

Cardholder passport number.

Allowable Values:

40 char max

password

string
Optional

Cardholder’s user account password on the Marqeta platform.

Allowable Values:

255 char max

phone

string
Optional

Cardholder telephone number (including area code), prepended by the + symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses.

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

Allowable Values:

Nine digits only, no delimiters. 123456789, for example.

NOTE: Required for KYC verification (US-based cardholders only).

state

string
Optional

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
Optional

Unique identifier of the cardholder.

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
Copied

Is this helpful?

Yes
No

Response body

Fields Description

account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the cardholder.

Send a GET request to /accountholdergroups to retrieve account holder group tokens.

Allowable Values:

36 char max

active

boolean
Conditionally returned

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

NOTE: Do not set the value of the user.active field directly. Instead, use the /usertransitions endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition.

Allowable Values:

true, false

address1

string
Conditionally returned

Cardholder’s address.

NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

address2

string
Conditionally returned

Additional address information for the cardholder.

NOTE: Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

birth_date

string
Conditionally returned

Cardholder’s date of birth.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

Format: yyyy-MM-dd

city

string
Conditionally returned

City where the cardholder resides.

NOTE: Required for KYC verification (US-based cardholders only).

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

Default value:
false

country

string
Conditionally returned

Country where the cardholder resides.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

NOTE: ISO alpha-2 country code required for KYC verification. US, for example.

email

string
Conditionally returned

Valid email address of the cardholder.

This value must be unique among users.

Allowable Values:

1–255 chars

first_name

string
Conditionally returned

Cardholder’s first name.

NOTE: Required for KYC verification (US-based cardholders only).

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

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
Returned

Type of identification.

NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification. 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
Conditionally returned

Number associated with the identification.

Allowable Values:

255 char max

NOTE: Digits only, do not use separators. For example: 123456789

ip_address

string
Conditionally returned

Cardholder’s IP address.

Allowable Values:

39 char max

last_name

string
Conditionally returned

Cardholder’s last name.

NOTE: Required for KYC verification (US-based cardholders only).

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

  • 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
Conditionally returned

Telephone number of the cardholder (including area code), prepended by the + symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses.

Allowable Values:

255 char max

Format: +15105551212 or +35552260859

postal_code

string
Conditionally returned

Postal code of the cardholder’s address.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

10 char max

ssn

string
Conditionally returned

Cardholder’s Social Security Number (SSN).

Allowable Values:

Nine digits only, no delimiters. 123456789, for example.

NOTE: Required for KYC verification (US-based cardholders only).

state

string
Conditionally returned

State or province where the cardholder resides.

NOTE: Valid two-character abbreviation required for KYC verification (US-based cardholders only).

Allowable Values:

32 char max

token

string
Conditionally returned

Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars

uses_parent_account

boolean
Conditionally returned

Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).

If set to true, you must also include a parent_token in the request. This value cannot be updated.

Allowable Values:

true, false

Default value:
false

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Update user password

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

Fields Description

current_password

string
Required

Current password to the cardholder’s user account on the Marqeta platform.

Allowable Values:

1–255 chars

new_password

string
Required

New 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:

1–255 chars

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Create client access token

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

Fields Description

application_token

string
Optional

Unique identifier of the application object.

Allowable Values:

1–255 chars

card_token

string
Required

Unique identifier of the card whose sensitive information you want to display.

Allowable Values:

1–255 chars

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

application

object
Conditionally returned

Contains client application information.

Allowable Values:

Existing application object

application.access_code

string
Conditionally returned

Access code of the client application.

Allowable Values:

255 char max

application.assets_url

string
Conditionally returned

URL of the client application assets.

Allowable Values:

255 char max

application.client_api_base_url

string
Conditionally returned

Base URL of the client API.

Allowable Values:

255 char max

application.environment

string
Conditionally returned

Client application’s environment.

Allowable Values:

255 char max

application.program

string
Conditionally returned

Name of the program on the Marqeta platform.

Allowable Values:

255 char max

application.program_short_code

string
Conditionally returned

Short code of the program on the Marqeta platform.

Allowable Values:

255 char max

application.token

string
Conditionally returned

Unique identifier of the application object.

Allowable Values:

36 char max

card_token

string
Conditionally returned

Unique identifier of the card whose sensitive information you want to display.

Allowable Values:

Existing card token

created

datetime
Returned

Date and time that the client access token was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

expires

datetime
Returned

Date and time that the client access token expires, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

token

string
Conditionally returned

Value of the client access token to redeem when displaying sensitive card data.

Allowable Values:

Existing client access token

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Retrieve client access token

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

Fields Description

token

string
Required

Client access token.

Allowable Values:

Existing client access token

URL query parameters

Fields Description

application_token

string
Optional

Unique identifier of the application object.

Allowable Values:

Existing application token

Response body

Fields Description

application

object
Conditionally returned

Contains client application information.

Allowable Values:

Existing application object

application.access_code

string
Conditionally returned

Access code of the client application.

Allowable Values:

255 char max

application.assets_url

string
Conditionally returned

URL of the client application assets.

Allowable Values:

255 char max

application.client_api_base_url

string
Conditionally returned

Base URL of the client API.

Allowable Values:

255 char max

application.environment

string
Conditionally returned

Client application’s environment.

Allowable Values:

255 char max

application.program

string
Conditionally returned

Name of the program on the Marqeta platform.

Allowable Values:

255 char max

application.program_short_code

string
Conditionally returned

Short code of the program on the Marqeta platform.

Allowable Values:

255 char max

application.token

string
Conditionally returned

Unique identifier of the application object.

Allowable Values:

36 char max

card_token

string
Conditionally returned

Unique identifier of the card whose sensitive information you want to display.

Allowable Values:

Existing card token

created

datetime
Returned

Date and time that the client access token was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

expires

datetime
Returned

Date and time that the client access token expires, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

token

string
Conditionally returned

Value of the client access token to redeem when displaying sensitive card data.

Allowable Values:

Existing client access token

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Log in user

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

Fields Description

email

string
Optional

Cardholder email address.

Allowable Values:

255 char max

password

string
Optional

Password to the cardholder’s user account on the Marqeta platform.

Allowable Values:

1–255 chars

user_token

string
Optional

Identifies the cardholder to log in.

Send a GET request to /users to retrieve user tokens.

Allowable Values:

1–36 chars

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

access_token

object
Conditionally returned

Contains a cardholder’s login access information.

Allowable Values:

Existing access_token

access_token.application

object
Conditionally returned

Contains client application information.

Allowable Values:

Existing application object

access_token.application.access_code

string
Conditionally returned

Access code of the client application.

Allowable Values:

255 char max

access_token.application.assets_url

string
Conditionally returned

URL of the client application assets.

Allowable Values:

255 char max

access_token.application.client_api_base_url

string
Conditionally returned

Base URL of the client API.

Allowable Values:

255 char max

access_token.application.environment

string
Conditionally returned

Client application’s environment.

Allowable Values:

255 char max

access_token.application.program

string
Conditionally returned

Name of the program on the Marqeta platform.

Allowable Values:

255 char max

access_token.application.program_short_code

string
Conditionally returned

Short code of the program on the Marqeta platform.

Allowable Values:

255 char max

access_token.application.token

string
Conditionally returned

Unique identifier of the application object.

Allowable Values:

36 char max

access_token.expires

datetime
Returned

Date and time when the access token expires.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

access_token.master_roles

array of strings
Conditionally returned

Array of master roles.

Allowable Values:

Valid array of one or more master_roles strings

access_token.one_time

boolean
Conditionally returned

Indicates whether the access token is a single-use token.

Allowable Values:

true, false

access_token.token

string
Conditionally returned

Unique identifier of the access token.

Allowable Values:

36 char max

access_token.token_type

string
Conditionally returned

Specifies the type of access token.

Allowable Values:

single_use, user, admin

access_token.user_token

string
Conditionally returned

Unique identifier of the user resource.

Allowable Values:

36 char max

user

object
Conditionally returned

Contains information about a cardholder.

Allowable Values:

account_holder_group_token, active, address1, address2, authentication, birth_date, business_token, city, company, corporate_card_holder, country, created_time, email, first_name, gender, honorific, id_card_expiration_date, id_card_number, identifications, ip_address, last_modified_time, last_name, metadata, middle_name, nationality, notes, parent_token, passport_expiration_date, passport_number, password, phone, postal_code, ssn, state, status, token, uses_parent_account, zip

user.account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the cardholder.

Allowable Values:

36 char max

user.active

boolean
Conditionally returned

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

Allowable Values:

true, false

user.address1

string
Conditionally returned

Cardholder’s address.

Allowable Values:

255 char max

user.address2

string
Conditionally returned

Additional address information for the cardholder.

Allowable Values:

255 char max

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

user.authentication.email_verified

boolean
Conditionally returned

Specifies whether the email address has been verified.

Allowable Values:

true, false

user.authentication.email_verified_time

datetime
Conditionally returned

Date and time when the email address was verified.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

user.authentication.last_password_update_channel

string
Conditionally returned

Specifies the channel through which the password was last changed.

Allowable Values:

USER_CHANGE, USER_RESET

user.authentication.last_password_update_time

datetime
Conditionally returned

Date and time when the password was last changed.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

user.birth_date

string
Conditionally returned

Cardholder’s date of birth.

Allowable Values:

Format: yyyy-MM-dd

user.business_token

string
Conditionally returned

Unique identifier of the business resource.

Allowable Values:

Existing business resource token

user.city

string
Conditionally returned

City where the cardholder resides.

Allowable Values:

40 char max

user.company

string
Conditionally returned

Company name.

Allowable Values:

255 char max

user.corporate_card_holder

boolean
Conditionally returned

Specifies if the cardholder holds a corporate card.

Allowable Values:

true, false

user.country

string
Conditionally returned

Country where the cardholder resides.

Allowable Values:

40 char max

user.created_time

datetime
Returned

Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

user.email

string
Conditionally returned

Valid email address of the cardholder.

Allowable Values:

1–255 chars

user.first_name

string
Conditionally returned

Cardholder’s first name.

Allowable Values:

40 char max

user.gender

string
Conditionally returned

Gender of the cardholder.

Allowable Values:

F, M

user.honorific

string
Conditionally returned

Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.

Allowable Values:

10 char max

user.id_card_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s identification.

Allowable Values:

Format: yyyy-MM-dd

user.id_card_number

string
Conditionally returned

Cardholder’s identification card number.

Allowable Values:

255 char max

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

user.identifications[].expiration_date

string
Conditionally returned

Expiration date for the identification, if applicable.

Allowable Values:

Format: yyyy-MM-dd

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

user.identifications[].value

string
Conditionally returned

Number associated with the identification.

Allowable Values:

255 char max

user.ip_address

string
Conditionally returned

Cardholder’s IP address.

Allowable Values:

39 char max

user.last_modified_time

datetime
Returned

Date and time when the resource was last updated, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

user.last_name

string
Conditionally returned

Cardholder’s last name.

Allowable Values:

40 char max

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

user.middle_name

string
Conditionally returned

Cardholder’s middle name.

Allowable Values:

40 char max

user.nationality

string
Conditionally returned

Cardholder’s nationality.

Allowable Values:

255 char max

user.notes

string
Conditionally returned

Any additional information pertaining to the cardholder.

Allowable Values:

255 char max

user.parent_token

string
Conditionally returned

Unique identifier of the parent user or business resource.

Allowable Values:

1–36 chars

user.passport_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s passport.

Allowable Values:

Format: yyyy-MM-dd

user.passport_number

string
Conditionally returned

Cardholder’s passport number.

Allowable Values:

40 char max

user.password

string
Conditionally returned

Password to the cardholder’s user account on the Marqeta platform.

Allowable Values:

1–255 chars

user.phone

string
Conditionally returned

Cardholder’s telephone number.

Allowable Values:

255 char max

user.postal_code

string
Conditionally returned

Postal code of the cardholder’s address.

Allowable Values:

10 char max

user.ssn

string
Conditionally returned

Cardholder’s Social Security Number (SSN).

Allowable Values:

Nine digits only, no delimiters.

user.state

string
Conditionally returned

State or province where the cardholder resides.

Allowable Values:

2 char max

user.status

string
Conditionally returned

Specifies the status of the cardholder on the Marqeta platform.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED

user.token

string
Conditionally returned

Unique identifier of the cardholder.

Allowable Values:

1–36 chars

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

user.zip

string
Conditionally returned

United States ZIP code of the cardholder’s address.

Allowable Values:

10 char max

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Log out user

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

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

Fields Description

email

string
Optional

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
Optional

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
Optional

Identifies the cardholder whose data is accessed. Send a GET request to /users to retrieve cardholder tokens.

Required when the Basic Authentication password is set to an admin access token (case #2).

Allowable Values:

1–36 chars

Sample request body

Case 1: Authorization: Basic my_application_token:my_user_access_token

JSON
Copied

Is this helpful?

Yes
No

Case 2: Authorization: Basic my_application_token:my_admin_access_token

JSON
Copied

Is this helpful?

Yes
No

Case 3: Authorization: Basic my_application_token

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

application

object
Conditionally returned

Contains client application information.

Allowable Values:

Existing application object

application.access_code

string
Conditionally returned

Access code of the client application.

Allowable Values:

255 char max

application.assets_url

string
Conditionally returned

URL of the client application assets.

Allowable Values:

255 char max

application.client_api_base_url

string
Conditionally returned

Base URL of the client API.

Allowable Values:

255 char max

application.environment

string
Conditionally returned

Client application’s environment.

Allowable Values:

255 char max

application.program

string
Conditionally returned

Name of the program on the Marqeta platform.

Allowable Values:

255 char max

application.program_short_code

string
Conditionally returned

Short code of the program on the Marqeta platform.

Allowable Values:

255 char max

application.token

string
Conditionally returned

Unique identifier of the application object.

Allowable Values:

36 char max

expires

datetime
Returned

Date and time when the access token expires.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ

master_roles

array of strings
Conditionally returned

Array of master roles.

Allowable Values:

Valid array of one or more master_roles strings

one_time

boolean
Conditionally returned

Indicates whether the access token is a single-use token.

Allowable Values:

true, false

token

string
Conditionally returned

Unique identifier of the access token.

Allowable Values:

36 char max

token_type

string
Conditionally returned

Specifies the type of access token.

Allowable Values:

single_use, user, admin

user_token

string
Conditionally returned

Unique identifier of the user resource.

Allowable Values:

36 char max

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Request user password reset token

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

Fields Description

email

string
Required

Cardholder email address.

Allowable Values:

1–255 chars

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Reset user password

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

Fields Description

token

string
Required

Password reset token generated using the POST /users/auth/resetpassword operation.

Allowable Values:

Existing password reset token

Request body

Fields Description

new_password

string
Required

New password to the cardholder’s user account on the Marqeta platform.

Allowable Values:

1–255 chars

user_token

string
Required

Unique identifier of the cardholder.

Allowable Values:

1–36 chars

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Request email verification token

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

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

Fields Description

token

string
Required

Email verification token generated using the POST /users/auth/verifyemail operation.

Allowable Values:

Existing email verification token

Search users

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

Fields Description

count

integer
Optional

Number of user resources to retrieve.

Allowable Values:

1-10

Default value:
5

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

search_type

string
Optional

Search type.

Allowable Values:

query_then_fetch, dfs_query_then_fetch

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-lastModifiedTime

Request body

Fields Description

dda

string
Optional

Performs a match on the specified deposit account number. Send a GET request to /directdeposits/accounts/{user_token} to retrieve the deposit account number for a specific cardholder.

Allowable Values:

Existing deposit account number

email

string
Optional

Performs a non-case-sensitive, exact match on the cardholder’s email field.

Allowable Values:

1–255 chars

first_name

string
Optional

Performs a non-case-sensitive match on the cardholder’s first_name field. Matching is partial on the beginning of the name. For example, a match on "Alex" returns both "Alex" and "Alexander".

Allowable Values:

40 char max

last_name

string
Optional

Performs a non-case-sensitive match on the cardholder’s last_name field. Matching is partial on the beginning of the name. For example, a match on "Smith" returns both "Smith" and "Smithfield".

Allowable Values:

40 char max

phone

string
Optional

Performs a match on the cardholder’s phone field.

Allowable Values:

255 char max

ssn

string
Optional

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.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Response body

Fields Description

count

integer
Conditionally returned

Number of resources to retrieve.

This field is returned if there are resources in your returned array.

Allowable Values:

1-10

data

array of objects
Conditionally returned

Array of user objects.

Objects are returned as appropriate to your query.

Allowable Values:

Valid array of one or more user objects

data[].account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the cardholder.

Send a GET request to /accountholdergroups to retrieve account holder group tokens.

Allowable Values:

36 char max

data[].active

boolean
Conditionally returned

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

NOTE: Do not set the value of the user.active field directly. Instead, use the /usertransitions endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition.

Allowable Values:

true, false

data[].address1

string
Conditionally returned

Cardholder’s address.

NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

data[].address2

string
Conditionally returned

Additional address information for the cardholder.

NOTE: Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

data[].birth_date

string
Conditionally returned

Cardholder’s date of birth.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

Format: yyyy-MM-dd

data[].city

string
Conditionally returned

City where the cardholder resides.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].company

string
Conditionally returned

Company name.

Allowable Values:

255 char max

data[].corporate_card_holder

boolean
Conditionally returned

Specifies if the cardholder holds a corporate card.

Allowable Values:

true, false

Default value:
false

data[].country

string
Conditionally returned

Country where the cardholder resides.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

NOTE: ISO alpha-2 country code required for KYC verification. US, for example.

data[].email

string
Conditionally returned

Valid email address of the cardholder.

This value must be unique among users.

Allowable Values:

1–255 chars

data[].first_name

string
Conditionally returned

Cardholder’s first name.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].gender

string
Conditionally returned

Gender of the cardholder.

Allowable Values:

F, M

data[].honorific

string
Conditionally returned

Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.

Allowable Values:

10 char max

data[].id_card_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s identification card.

Allowable Values:

Format: yyyy-MM-dd

data[].id_card_number

string
Conditionally returned

Cardholder’s identification card number.

Allowable Values:

255 char max

data[].identifications

array of objects
Conditionally returned

One or more objects containing identifications associated with the cardholder.

Allowable Values:

Valid array of one or more identifications objects

data[].identifications[].expiration_date

string
Conditionally returned

Expiration date of the identification, if applicable.

Allowable Values:

Format: yyyy-MM-dd

data[].identifications[].type

string
Returned

Type of identification.

NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification. Nine digits only, no delimiters. 123456789, for example.

Allowable Values:

SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE

data[].identifications[].value

string
Conditionally returned

Number associated with the identification.

Allowable Values:

255 char max

NOTE: Digits only, do not use separators. For example: 123456789

data[].ip_address

string
Conditionally returned

Cardholder’s IP address.

Allowable Values:

39 char max

data[].last_name

string
Conditionally returned

Cardholder’s last name.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].metadata

object
Conditionally returned

Associates any additional metadata you provide with the cardholder.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1".

data[].middle_name

string
Conditionally returned

Cardholder’s middle name.

Allowable Values:

40 char max

data[].nationality

string
Conditionally returned

Cardholder’s nationality.

Allowable Values:

255 char max

data[].notes

string
Conditionally returned

Any additional information pertaining to the cardholder.

Allowable Values:

255 char max

data[].parent_token

string
Conditionally returned

Unique identifier of the parent user or business resource. Send a GET request to /users to retrieve user resource tokens or to /businesses to retrieve business resource tokens.

Required if uses_parent_account = true. This user or business is configured as the parent of the current user.

Allowable Values:

1–36 chars

data[].passport_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s passport.

Allowable Values:

Format: yyyy-MM-dd

data[].passport_number

string
Conditionally returned

Cardholder’s passport number.

Allowable Values:

40 char max

data[].password

string
Conditionally returned

Password to the cardholder’s user account on the Marqeta platform.

  • Must contain at least one numeral

  • Must contain at least one lowercase letter

  • Must contain at least one uppercase letter

  • Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

Allowable Values:

255 char max

data[].phone

string
Conditionally returned

Telephone number of the cardholder (including area code), prepended by the + symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses.

Allowable Values:

255 char max

Format: +15105551212 or +35552260859

data[].postal_code

string
Conditionally returned

Postal code of the cardholder’s address.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

10 char max

data[].ssn

string
Conditionally returned

Cardholder’s Social Security Number (SSN).

Allowable Values:

Nine digits only, no delimiters. 123456789, for example.

NOTE: Required for KYC verification (US-based cardholders only).

data[].state

string
Conditionally returned

State or province where the cardholder resides.

NOTE: Valid two-character abbreviation required for KYC verification (US-based cardholders only).

Allowable Values:

32 char max

data[].token

string
Conditionally returned

Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars

data[].uses_parent_account

boolean
Conditionally returned

Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).

If set to true, you must also include a parent_token in the request. This value cannot be updated.

Allowable Values:

true, false

Default value:
false

end_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false

start_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

Sample response body

JSON
Copied

Is this helpful?

Yes
No

List user child accounts

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 business_token

Populated; matches parent_token

User’s parent is a business.

Populated; does not match business_token

Populated; does not match parent_token

User’s parent is a user and their grandparent is a business.

This endpoint supports field filtering.

URL path parameters

Fields Description

parent_token

string
Required

Unique identifier of the parent account holder.

Allowable Values:

Existing user or business resource token

URL query parameters

Fields Description

count

integer
Optional

Number of user resources to retrieve.

Allowable Values:

1-10

Default value:
5

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

Comma-delimited list of fields, or blank

sort_by

string
Optional

Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-lastModifiedTime

Response body

Fields Description

count

integer
Conditionally returned

Number of resources to retrieve.

This field is returned if there are resources in your returned array.

Allowable Values:

1-10

data

array of objects
Conditionally returned

Array of user objects.

Objects are returned as appropriate to your query.

Allowable Values:

Valid array of one or more user objects

data[].account_holder_group_token

string
Conditionally returned

Associates the specified account holder group with the cardholder.

Send a GET request to /accountholdergroups to retrieve account holder group tokens.

Allowable Values:

36 char max

data[].active

boolean
Conditionally returned

Specifies if the cardholder is in the ACTIVE state on the Marqeta platform.

NOTE: Do not set the value of the user.active field directly. Instead, use the /usertransitions endpoints to transition user resources between statuses. For more information on status changes, see Create User Transition.

Allowable Values:

true, false

data[].address1

string
Conditionally returned

Cardholder’s address.

NOTE: Required for KYC verification (US-based cardholders only). Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

data[].address2

string
Conditionally returned

Additional address information for the cardholder.

NOTE: Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

data[].birth_date

string
Conditionally returned

Cardholder’s date of birth.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

Format: yyyy-MM-dd

data[].city

string
Conditionally returned

City where the cardholder resides.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].company

string
Conditionally returned

Company name.

Allowable Values:

255 char max

data[].corporate_card_holder

boolean
Conditionally returned

Specifies if the cardholder holds a corporate card.

Allowable Values:

true, false

Default value:
false

data[].country

string
Conditionally returned

Country where the cardholder resides.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

NOTE: ISO alpha-2 country code required for KYC verification. US, for example.

data[].email

string
Conditionally returned

Valid email address of the cardholder.

This value must be unique among users.

Allowable Values:

1–255 chars

data[].first_name

string
Conditionally returned

Cardholder’s first name.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].gender

string
Conditionally returned

Gender of the cardholder.

Allowable Values:

F, M

data[].honorific

string
Conditionally returned

Cardholder’s title or prefix: Dr., Miss, Mr., Ms., and so on.

Allowable Values:

10 char max

data[].id_card_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s identification card.

Allowable Values:

Format: yyyy-MM-dd

data[].id_card_number

string
Conditionally returned

Cardholder’s identification card number.

Allowable Values:

255 char max

data[].identifications

array of objects
Conditionally returned

One or more objects containing identifications associated with the cardholder.

Allowable Values:

Valid array of one or more identifications objects

data[].identifications[].expiration_date

string
Conditionally returned

Expiration date of the identification, if applicable.

Allowable Values:

Format: yyyy-MM-dd

data[].identifications[].type

string
Returned

Type of identification.

NOTE: Full Social Security Number (SSN) is required for US-based cardholder KYC verification. Nine digits only, no delimiters. 123456789, for example.

Allowable Values:

SSN, TIN, SIN, NIN, PASSPORT_NUMBER, DRIVERS_LICENSE, BUSINESS_NUMBER, BUSINESS_TAX_ID, TAXPAYER_REFERENCE

data[].identifications[].value

string
Conditionally returned

Number associated with the identification.

Allowable Values:

255 char max

NOTE: Digits only, do not use separators. For example: 123456789

data[].ip_address

string
Conditionally returned

Cardholder’s IP address.

Allowable Values:

39 char max

data[].last_name

string
Conditionally returned

Cardholder’s last name.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

40 char max

data[].metadata

object
Conditionally returned

Associates any additional metadata you provide with the cardholder.

Allowable Values:

You can define the names and values of up to 20 fields in the format "my_name_1": "my_value_1".

data[].middle_name

string
Conditionally returned

Cardholder’s middle name.

Allowable Values:

40 char max

data[].nationality

string
Conditionally returned

Cardholder’s nationality.

Allowable Values:

255 char max

data[].notes

string
Conditionally returned

Any additional information pertaining to the cardholder.

Allowable Values:

255 char max

data[].parent_token

string
Conditionally returned

Unique identifier of the parent user or business resource. Send a GET request to /users to retrieve user resource tokens or to /businesses to retrieve business resource tokens.

Required if uses_parent_account = true. This user or business is configured as the parent of the current user.

Allowable Values:

1–36 chars

data[].passport_expiration_date

string
Conditionally returned

Expiration date of the cardholder’s passport.

Allowable Values:

Format: yyyy-MM-dd

data[].passport_number

string
Conditionally returned

Cardholder’s passport number.

Allowable Values:

40 char max

data[].password

string
Conditionally returned

Password to the cardholder’s user account on the Marqeta platform.

  • Must contain at least one numeral

  • Must contain at least one lowercase letter

  • Must contain at least one uppercase letter

  • Must contain at least one of these symbols: @ # $ % ! ^ & * ( ) \ _ + ~ ` - = [ ] { } , ; : ' " , . / < > ?

Allowable Values:

255 char max

data[].phone

string
Conditionally returned

Telephone number of the cardholder (including area code), prepended by the + symbol and the 1- to 3-digit country calling code. Do not include hyphens, spaces, or parentheses.

Allowable Values:

255 char max

Format: +15105551212 or +35552260859

data[].postal_code

string
Conditionally returned

Postal code of the cardholder’s address.

NOTE: Required for KYC verification (US-based cardholders only).

Allowable Values:

10 char max

data[].ssn

string
Conditionally returned

Cardholder’s Social Security Number (SSN).

Allowable Values:

Nine digits only, no delimiters. 123456789, for example.

NOTE: Required for KYC verification (US-based cardholders only).

data[].state

string
Conditionally returned

State or province where the cardholder resides.

NOTE: Valid two-character abbreviation required for KYC verification (US-based cardholders only).

Allowable Values:

32 char max

data[].token

string
Conditionally returned

Unique identifier of the cardholder. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars

data[].uses_parent_account

boolean
Conditionally returned

Indicates whether the child shares balances with the parent (true), or the child’s balances are independent of the parent (false).

If set to true, you must also include a parent_token in the request. This value cannot be updated.

Allowable Values:

true, false

Default value:
false

end_index

integer
Conditionally returned

Sort order index of the first resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false