Marqeta.com
Support
/
30 minute read
December 22, 2020

Users

The users resource represents a person who uses a Marqeta card (physical or virtual) to access Marqeta-administered funds. 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 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.

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.

To change or track the history of a user’s status, use the

/usertransitions
endpoint. For more information on status changes, see Create User Transition on this page.

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 decide 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 parent’s parent 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.

Body field details
Fields Description

token

string
Optional

The unique identifier of the user. 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:

36 char max

honorific

string
Optional

The user’s title/prefix: Ms., Mr., Miss, Mrs.

Allowable Values:

10 char max

gender

string
Optional

The gender of the user.

Allowable Values:

M, F

email

string
Optional

A valid email address for the user.

This value must be unique among users.

Allowable Values:

255 char max

address1

string
Conditionally required

The address of the user.

Note
Required for KYC verification. Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

address2

string
Optional

Additional address information for the user.

Note
Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

city

string
Conditionally required

The city that corresponds to the address.

Note
Required for KYC verification.

Allowable Values:

40 char max

state

string
Conditionally required

The state that corresponds to the address.

Note
Required for KYC verification.

Allowable Values:

32 char max

postal_code

string
Conditionally required

Postal code.

Note
Required for KYC verification.

Allowable Values:

10 char max

country

string
Conditionally required

Country in which user resides.

Note
Required for KYC verification.

Allowable Values:

40 char max

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

metadata

object
Optional

Associates customer-injected metadata with the user.

Allowable Values:

Existing

users.metadata
object.

nationality

string
Optional

Nationality of the user.

Allowable Values:

255 char max

notes

string
Optional

Any additional information pertaining to the user.

Allowable Values:

255 char max

phone

string
Optional

Telephone number of the user (including area code), prepended by the

+
symbol and the 1-3 digit country calling code. Do not include hyphens, spaces, or parentheses.

Allowable Values:

Format: +15105551212 or +35552260859

20 char max

middle_name

string
Optional

User’s middle name.

Allowable Values:

40 char max

first_name

string
Conditionally required

User’s first name.

Note
Required for KYC verification.

Allowable Values:

40 char max

birth_date

string
Conditionally required

The date of birth of the user.

Note
Required for KYC verification.

Allowable Values:

yyyy-MM-dd

last_name

string
Conditionally required

User’s last name.

Note
Required for KYC verification.

Allowable Values:

40 char max

uses_parent_account

boolean
Optional

Indicates whether the child shares balances with the parent (

true
), or whether the child balances are independent of the parent (
false
).

If set to

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

Allowable Values:

true
,
false

Default value:

false

parent_token

string
Conditionally required

The unique identifier of a user or business already in the system.

Required if

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

Allowable Values:

Existing user or business token.

Send a

GET
request to
/users
to retrieve user tokens or
/businesses
to retrieve business tokens.

password

string
Optional

Password for user account.

Allowable Values:

  • 8-20 characters

  • 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: @#$%!^&*()\_+~`-=[]{},;:'",./<>?

company

string
Optional

Company name.

Allowable Values:

255 char max

ip_address

string
Optional

The IP address of the user.

Allowable Values:

45 char max

account_holder_group_token

string
Optional

Associates the specified account holder group with the user.

Allowable Values:

Existing account holder group token.

Send a

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

identifications

array
Conditionally required

One or more objects containing identifying information about the user.

Note
Full SSN required for KYC verification.

Allowable Values:

Existing

users.identifications
array.

The identifications array

You can add one or more objects to the

identifications
array. Each identification in the array must be of a different type.

Only one of the following identification types can be associated with a user:

  • SSN
    – Social Security Number

  • SIN
    – Social Insurance Number

  • TIN
    – Taxpayer Identification Number

  • NIN
    – National Insurance Number

You can also include the following identification types:

  • PASSPORT_NUMBER
    – Passport number

  • DRIVERS_LICENSE
    – Driver’s license number

Fields Description

type

string
Required

The form of identification.

Note
Full SSN is required for KYC verification.

Allowable Values:

SSN
,
TIN
,
SIN
,
NIN
,
PASSPORT_NUMBER
,
DRIVERS_LICENSE

value

string
Required

The identification number associated with the form of identification.

Allowable Values:

255 char max

Note
Numerals only, do not use separators. For example: 123456789

expiration_date

string
Optional

The expiration date for the form of identification, if applicable.

Allowable Values:

yyyy-MM-dd

The metadata object
Fields Description

customer_defined_name_01

string
Optional

Associates customer-injected metadata with the user. You can define the names and values of up to 20 fields, for example:

Copied

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value

notification_email

string
Optional

Specifies the primary email address for 3DS one-time passcode (OTP) notifications. If both the

metadata.notification_email
field and the
user.email
field are populated, 3DS OTP notifications are sent to the
metadata.notification_email
address.

Allowable Values:

255 char max

notification_language

string
Optional

Specifies the language for 3D Secure and digital wallet token notifications sent to this user. By default, notifications are sent in English. You can send notifications to your cardholders in Czech, French, Italian, German, Polish, Spanish, and Swedish.

To specify the language for notifications at the card product level, see the config.transaction_controls object. Languages set at the user level take precedence over the language set at the card product level.

Allowable Values:

ces
,
deu
,
eng
,
fra
,
ita
,
pol
,
spa
,
swe

Leave this field blank to send OTP notifications in the language specified at the card product level.

Sample request body
Copied

Is this helpful?

Yes
No
Sample response body
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 the parent’s parent is a business.

This endpoint supports field filtering.

URL path parameters
Fields Description

token

string
Required

The token identifying the user you wish to retrieve.

Allowable Values:

Existing user token.

Send a

GET
request to
/users
to retrieve existing user tokens.

Sample response body
Copied

Is this helpful?

Yes
No

Update user

Action:

PUT

Endpoint:
/users/{token}

URL path parameters
Fields Description

token

string
Required

The token identifying the user to update.

Allowable Values:

Existing user token.

Issue

GET
to
/users
to retrieve an existing user token.

Body field details
Fields Description

honorific

string
Optional

The user’s title/prefix: Ms., Mr., Miss, Mrs.

Allowable Values:

10 char max

gender

string
Optional

The gender of the user.

Allowable Values:

M, F

email

string
Optional

A valid email address for the user.

This value must be unique among users.

Allowable Values:

255 char max

address1

string
Conditionally required

The address of the user.

Note
Required for KYC verification. Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

address2

string
Optional

Additional address information for the user.

Note
Cannot perform KYC if set to a PO Box.

Allowable Values:

255 char max

city

string
Conditionally required

The city that corresponds to the address.

Note
Required for KYC verification.

Allowable Values:

40 char max

state

string
Optional

The state that corresponds to the address.

Required for KYC verification.

Allowable Values:

32 char max

postal_code

string
Optional

Postal code.

Note
Required for KYC verification.

Allowable Values:

10 char max

country

string
Optional

Country in which user resides.

Note
Required for KYC verification.

Allowable Values:

40 char max

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

metadata

object
Optional

Associates customer-injected metadata with the user.

Allowable Values:

Existing

metadata
object

nationality

string
Optional

Nationality of the user.

Allowable Values:

255 char max

notes

string
Optional

Any additional information pertaining to the user.

Allowable Values:

255 char max

phone

string
Optional

Telephone number of the user (including area code), prepended by the

+
symbol and the 1-3 digit country calling code. Do not include hyphens, spaces, or parentheses.

Allowable Values:

+15105551212 or +35552260859

20 char max

middle_name

string
Optional

User’s middle name.

Allowable Values:

40 char max

first_name

string
Conditionally required

User’s first name.

Note
Required for KYC verification.

Allowable Values:

40 char max

last_name

string
Conditionally required

User’s last name.

Note
Required for KYC verification.

Allowable Values:

40 char max

birth_date

string
Conditionally required

The date of birth of the user.

Note
Required for KYC verification.

Allowable Values:

yyyy-MM-dd

parent_token

string
Conditionally required

The unique identifier of a user already in the system.

Required if

uses_parent_account = true
. This user is configured as the parent of the current user.

Allowable Values:

Existing user token

ip_address

string
Optional

The IP address of the user.

Allowable Values:

45 char max

company

string
Optional

Company name.

Allowable Values:

255 char max

account_holder_group_token

string
Optional

Associates the specified account holder group with the user.

Allowable Values:

Existing account holder group token.

Send a

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

identifications

array
Conditionally required

One or more objects containing identifying information about the user.

Note
Full SSN is required for KYC verification.

Allowable Values:

An array of objects

The identifications array

You can add one or more objects to the

identifications
array. Each identification in the array must be of a different type.

Only one of the following identification types can be associated with a user:

  • SSN
    – Social Security Number

  • SIN
    – Social Insurance Number

  • TIN
    – Taxpayer Identification Number

  • NIN
    – National Insurance Number

You can also include the following identification types:

  • PASSPORT_NUMBER
    – Passport number

  • DRIVERS_LICENSE
    – Driver’s license number

Fields Description

type

string
Required

The form of identification.

Note
Full SSN is required for KYC verification.

Allowable Values:

SSN
,
TIN
,
SIN
,
NIN
,
PASSPORT_NUMBER
,
DRIVERS_LICENSE

value

string
Required

The identification number associated with the form of identification.

Allowable Values:

255 char max

Note
Numerals only, do not use separators. For example: 123456789

expiration_date

string
Optional

The expiration date for the form of identification, if applicable.

Allowable Values:

yyyy-MM-dd

The metadata object
Fields Description

customer_defined_name_01

string
Optional

Associates customer-injected metadata with the user. You can define the names and values of up to 20 fields, for example:

Copied

The following samples show how to update, add, and delete fields. Existing fields are unaffected unless they are included in the request.

Update a field’s value:

Copied

Add a new field:

Copied

Delete an existing field:

Copied

Allowable Values:

  • Up to 20 name-value pairs

  • 255 char max per name

  • 255 char max per value

notification_email

string
Optional

Specifies the primary email address for 3DS one-time passcode (OTP) notifications. If both the

metadata.notification_email
field and the
user.email
field are populated, 3DS OTP notifications are sent to the
metadata.notification_email
address.

Allowable Values:

255 char max

notification_language

string
Optional

Specifies the language for 3D Secure and digital wallet token notifications sent to this user. By default, notifications are sent in English. You can send notifications to your cardholders in Czech, French, Italian, German, Polish, Spanish, and Swedish.

To specify the language for notifications at the card product level, see the config.transaction_controls object. Languages set at the user level take precedence over the language set at the card product level.

Allowable Values:

ces
,
deu
,
eng
,
fra
,
ita
,
pol
,
spa
,
swe

Leave this field blank to send OTP notifications in the language specified at the card product level.

Sample request body
Copied

Is this helpful?

Yes
No
Sample response body
Copied

Is this helpful?

Yes
No

List users

Action:

GET

Endpoint:
/users

To return an array of all 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 the parent’s parent is a business.

Sample response body
Copied

Is this helpful?

Yes
No

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.

Body field details
Fields Description

first_name

string
Optional

Performs a non-case-sensitive match on the users'

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 users'

last_name
field. Matching is partial on the beginning of the name. For example, a match on "Smith" returns both "Smith" and "Smithline".

Allowable Values:

40 char max

phone

string
Optional

Performs a match on the users'

phone
field.

Allowable Values:

A valid and complete user telephone number

email

string
Optional

Performs a non-case-sensitive, exact match on the users'

email
field.

Allowable Values:

A valid and complete user email address

ssn

string
Optional

Performs a match on the users' identification number.

Allowable Values:

Either a complete identification number or the last four digits.

Numerals only; do not use hyphens.

dda

string
Optional

Performs a match on the specified deposit account number.

Allowable Values:

Existing deposit account number

Send a

GET
request to
/directdeposits/accounts/{user_token}
to retrieve the deposit account number for a specific user.

direct_deposit_account

string
Optional

Performs a match on the specified direct deposit account number.

Allowable Values:

Existing direct deposit account number

Send a

GET
request to
/directdeposits/accounts/{user_token}
to retrieve the deposit account number for a specific user.

Sample request body
Copied

Is this helpful?

Yes
No
Sample response body
Copied

Is this helpful?

Yes
No

List user children

Action:

GET

Endpoint:
/users/{parent_token}/children

To retrieve users who are children of another user or of a business (the parent), 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 the parent’s parent is a business.

This endpoint supports field filtering.

URL path parameters
Fields Description

parent_token

string
Required

The token of the parent user or business.

Allowable Values:

Existing user or business token.

Send a

GET
request to
/users
to retrieve user tokens or to
/businesses
to retrieve business tokens.

Sample response body
Copied

Is this helpful?

Yes
No

Verify user email address

Verifying a user’s email address is a two-step process. First you request an email verification token, and then you use that token in a subsequent request to verify the email.

Step 1

Action:

POST

Endpoint:
/users/auth/verifyemail

To request an email verification token, send a

POST
request to the
/users/auth/verifyemail
endpoint. No input parameters are required because this operation is performed in the context of an authenticated user. This request generates and sends an email message containing the email verification token to the user’s email address. The email message must be customized with a link that passes the email verification token to a web page where a subsequent request verifies the email address. You set up the subsequent request in step 2.

A successful request returns an empty response body and a response code of

204 No Content
.

Step 2

Action:

POST

Endpoint:
/users/auth/verifyemail/{email_verification_token}

To verify the email address, send a

POST
request to the
/users/auth/verifyemail/{email_verification_token}
endpoint. Include
email_verification_token
as a path parameter.

A successful email verification returns an empty response body and a response code of

204 No Content
.

URL path parameters
Fields Description

email_verification_token

string
Required

Email verification token.

Allowable Values:

Generated from

POST /users/auth/verifyemail

Retrieve user identification number

Action:

GET

Endpoint:
/users/{token}/ssn

To retrieve the government-issued identification number for a user, send a

GET
request to the
/users/{token}/ssn
endpoint. Include the
token
path parameter to specify the user whose identification number (SSN, TIN, NIN, SIN) you wish to return. You can indicate whether to return the full number or the last four digits only.

URL path parameters
Fields Description

token

string
Required

Identifies the user whose identification number you want to retrieve.

Allowable Values:

Existing user token.

Send a

GET
request to
/users
to retrieve user tokens.

Query parameters
Fields Description

full_ssn

boolean
Required

To return the full identification number, set to

true
.
To return only the last 4 digits, set to
false
.

If the identifications array contains only the last four digits of the identification number, the

/users/{token}/ssn
endpoint will return only the last four digits, regardless of the
full_ssn
parameter.

Allowable Values:

true
,
false

Default value:

false

Sample response body
Copied

Is this helpful?

Yes
No

Change 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 change of password returns an empty response body and a response code of "204 No Content".

Body field details
Fields Description

new_password

string
Required

The new password.

Allowable Values:

40 char max

current_password

string
Required

The current password.

Allowable Values:

40 char max

Sample request body
Copied

Is this helpful?

Yes
No

Reset user password

Resetting a user’s password is a two-step process. First you request a password reset token, and then you use that token in a subsequent request to update the password.

Step 1

Action:

POST

Endpoint:
/users/auth/resetpassword

To request a reset password token, 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. (The email message must be customized with a link that passes the
user_token
and
password_reset_token
to a web page where a subsequent request updates the password.) You set up the subsequent request in Step 2.

A successful request returns an empty response body and a response code of "204 No Content".

Body field details
Fields Description

email

string
Required

Email address of the user.

Allowable Values:

255 char max

Sample request body
Copied

Is this helpful?

Yes
No
Step 2

Action:

POST

Endpoint:
/users/auth/resetpassword/{password_reset_token}

To reset the password, send a

POST
request to the
/users/auth/resetpassword/{password_reset_token}
endpoint. 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 reset of password returns an empty response body and a response code of "204 No Content".

URL path parameters
Fields Description

password_reset_token

string
Required

Password reset token.

Allowable Values:

Generated from

POST /users/auth/resetpassword

Body field details
Fields Description

user_token

string
Required

The token identifying the user whose password is reset.

Allowable Values:

255 char max

new_password

string
Required

New password.

Allowable Values:

255 char max

Sample request body
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 and a response code of "204 No Content".

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.

Note
To check a user’s credentials without logging out the user, utilize the
/users/auth/onetime
endpoint.
Body field details
Fields Description

email

string
Required

The user’s email address.

Allowable Values:

255 char max

password

string
Required

The user’s Marqeta password.

Allowable Values:

255 char max

user_token

string
Required

Identifies the user to log in.

Allowable Values:

Existing user token.

Send a

GET
request to
/users
to retrieve user tokens.

Sample request body
Copied

Is this helpful?

Yes
No
Sample response body
Copied

Is this helpful?

Yes
No

Return 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 that calling this endpoint and returning a single-use access token does not invalidate the user’s current user access token.

Body field details
Fields Description

user_token

string
Conditionally required

Identifies the user whose data is accessed.

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

Allowable Values:

Existing user token.

Send a

GET
request to
/users
to retrieve user tokens.

email

string
Conditionally required

User’s email address.

Required when Basic Authentication password is not specified (case #3).

Allowable Values:

255 char max

password

string
Conditionally required

User’s Marqeta password.

Required when basic Basic Authentication is not specified (case #3).

Allowable Values:

255 char max

Sample request body

Case #1 – Authorization: Basic my_application_token:my_user_access_token

Copied

Is this helpful?

Yes
No

Case #2 – Authorization: Basic my_application_token:my_admin_access_token

Copied

Is this helpful?

Yes
No

Case #3 – Authorization: Basic my_application_token

Copied

Is this helpful?

Yes
No
Sample response body
Copied

Is this helpful?

Yes
No

Create user transition

Action:

POST

Endpoint:
/usertransitions

This endpoint enables you to change a user’s status, depending on your role and the previous status change. By changing a user’s status, you can control the user’s capabilities and the setting of the

user.active
field. (You cannot control
user.active
directly.)

The user.status Field Description The user.active Field User Limitations Allowable Transitions

UNVERIFIED

Initial status of a new user belonging to an account holder group where KYC is always required.

false

Cannot load funds or activate cards.

ACTIVE
,
CLOSED

LIMITED

Initial status of a new user belonging to an account holder group where KYC is conditionally required.

true

Restricted by rules in

accountholdergroups.pre_kyc_controls
.

ACTIVE
,
SUSPENDED
,
CLOSED

ACTIVE

Status of a user who has passed KYC, or initial status of a new user belonging to an account holder group where KYC is never required.

true

None.

SUSPENDED
,
CLOSED

SUSPENDED

The user is temporarily inactive.

Transitioning a suspended user to the

ACTIVE
status is restricted based on your role and the details of the previous status change.

false

Cannot load funds or activate cards.

ACTIVE
,
LIMITED
,
UNVERIFIED
,
CLOSED

CLOSED

The user is permanently inactive.

In general, the

CLOSED
status should be terminal. For exceptional cases, you can transition a user to other statuses, depending on your role and the details of the previous status change. Contact your Marqeta representative for more information.

false

Cannot load funds or activate cards.

ACTIVE
,
LIMITED
,
UNVERIFIED
,
SUSPENDED

Note
The Marqeta platform transitions a user’s status in response to certain events. For example, a user in the
UNVERIFIED
status is transitioned to
ACTIVE
when the user passes KYC verification.
Body field details
Fields Description

token

string
Optional

The unique identifier of the user transition.

If you do not include a token, the system generates one automatically. This token is referenced in other API calls, so we recommend that you define a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

user_token

string
Required

Identifies the user whose status is transitioned.

Allowable Values:

Existing user token.

Send a

GET
request to the
/users
endpoint to obtain a user token.

status

string
Required

Specifies the new status of the user.

Allowable Values:

UNVERIFIED
,
LIMITED
,
ACTIVE
,
SUSPENDED
,
CLOSED

reason_code

string
Required

Identifies the standardized reason for the transition.

Allowable Values:

See The reason_code Field section.

reason

string
Optional

Additional information about the status change.

Allowable Values:

255 char max

channel

string
Required

The mechanism by which the transaction was initiated.

Allowable Values:

API
,
IVR
,
FRAUD
,
ADMIN
,
SYSTEM

The reason_code field
Value Description

00

Object activated for the first time.

01

Requested by you.

02

Inactivity over time.

03

Provided address either does not accept mail or the addressee is not known at the address.

04

Negative account balance.

05

Account under review.

06

Suspicious activity was identified.

07

Activity outside the program parameters was identified.

08

Confirmed fraud was identified.

09

Matched with an Office of Foreign Assets Control list.

10

Card was reported lost.

11

Card information was cloned.

12

Account or card information was compromised.

13

Temporary status change while on hold/leave.

14

Initiated by Marqeta.

15

Initiated by issuer.

16

Card expired.

17

Failed KYC.

18

Changed to

ACTIVE
because information was properly validated and confirmed.

19

Changed to

ACTIVE
because account activity was properly validated and confirmed.

20

Change occurred prior to the normalization of reason codes.

21

Initiated by a third party, often a digital wallet provider.

22

PIN retry limit reached.

23

Card was reported stolen.

Sample request body
Copied

Is this helpful?

Yes
No
Sample response body
Copied

Is this helpful?

Yes
No

Retrieve user transition

Action:

GET

Endpoint:
/usertransitions/{token}

Use this endpoint to retrieve a user transition.

URL path parameters
Fields Description

token

string
Required

Identifies the user transition to retrieve.

Allowable Values:

Existing user transition token.

Sample response body
Copied

Is this helpful?

Yes
No

List transitions for user

Action:

GET

Endpoint:
/usertransitions/user/{token}

Use this endpoint to list all transitions for a given user.

URL path parameters
Fields Description

token

string
Required

Identifies the user associated with the transitions to retrieve.

Allowable Values:

Existing user token.

Sample response body
Copied

Is this helpful?

Yes
No

Feedback on this page?

If you feel we can do anything better, please let our team know.