Skip to main content
Use the /usertransitions endpoints to transition user resources between statuses, as well as to retrieve and list status changes for a user resource.

​
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. Do not set the value of the user.active field directly.
The user.status FieldDescriptionUser Limitations
UNVERIFIEDInitial status of a new user belonging to an account holder group where KYC is always required.

Allowable Transitions:
ACTIVE, CLOSED, TERMINATED		Cannot activate cards or load funds.

user.active Field:
false
LIMITEDInitial status of a new user belonging to an account holder group where KYC is conditionally required.

Allowable Transitions:
ACTIVE, SUSPENDED, CLOSED		Restricted by rules in accountholdergroups.pre_kyc_controls.

user.active Field:
true
ACTIVEStatus 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.

Allowable Transitions:
SUSPENDED, CLOSED, UNVERIFIED		None.

user.active Field:
true
SUSPENDEDThe 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.

Allowable Transitions:
ACTIVE, LIMITED, UNVERIFIED, CLOSED, TERMINATED		Cannot activate cards, load funds, or transact.

user.active Field:
false
CLOSEDThe 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.

Allowable Transitions:
ACTIVE, LIMITED, UNVERIFIED, SUSPENDED, TERMINATED		Cannot activate cards, load funds, or transact.

user.active Field:
false
TERMINATEDThe user account is permanently closed. Use the TERMINATED state to comply with regulatory requirements, such as the requirement that a user account be irreversibly closed when it does not pass Know Your Customer (KYC) verification.

NOTE:TERMINATED is a terminal status. You must have the Admin or Program Manager role to transition a user to the TERMINATED state. You cannot transition a user from TERMINATED to any other state. Contact your Marqeta representative for more information.

Allowable Transitions:
None		Cannot load funds, activate cards, or transact.

The user.active field:
false
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.

​
Request body

FieldsDescription
channel

string

Required		Mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM
idempotentHash

string

Optional		Unique hashed value that identifies subsequent submissions of the user transition request.

Allowable Values:

255 char max
reason

string

Optional		Additional information about the status change.

Allowable Values:

255 char max
reason_code

string

Required		Identifies the standardized reason for the transition:

00: Object activated for the first time.

01: Requested by you.

02: Inactivity over time.

03: This address cannot accept mail or the addressee is unknown.

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.

19: Changed to ACTIVE because account activity was properly validated.

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.

24: Address issue.

25: Name issue.

26: SSN issue.

27: DOB issue.

28: Email issue.

29: Phone issue.

30: Account/fulfillment mismatch.

31: Other reason.

86: Notification of death.

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 86
status

string

Required		Specifies the new status of the user.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED, TERMINATED
token

string

Optional		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		Unique identifier of the user whose status you want to transition.

Allowable Values:

Existing user token.

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

​
Sample request body

JSON
{
  "token": "activate_05",
  "user_token": "my_user_01",
  "status": "ACTIVE",
  "reason_code": "00",
  "reason": "Activating user",
  "channel": "API"
}

​
Response body

FieldsDescription
channel

string

Returned		Mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM
created_time

datetime

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

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
created_timestamp

datetime

Conditionally returned		Date and time when the resource was created. Expressed in UTC, with millisecond precision.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ss:SSSZ
last_modified_time

datetime

Conditionally returned		Date and time when the resource was last modified, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
reason

string

Conditionally returned		Additional information about the status change.

Allowable Values:

255 char max
reason_code

string

Returned		Identifies the standardized reason for the transition:

00: Object activated for the first time.

01: Requested by you.

02: Inactivity over time.

03: This address cannot accept mail or the addressee is unknown.

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.

19: Changed to ACTIVE because account activity was properly validated.

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.

24: Address issue.

25: Name issue.

26: SSN issue.

27: DOB issue.

28: Email issue.

29: Phone issue.

30: Account/fulfillment mismatch.

31: Other reason.

86: Notification of death.

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 86
status

string

Returned		Specifies the new status of the user.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED, TERMINATED
token

string

Returned		Unique identifier of the user transition.

Allowable Values:

Existing user transition token
user_token

string

Conditionally returned		Unique identifier of the user whose status was transitioned.

Allowable Values:

Existing user token
metadata

object

Conditionally returned		Associates customer-injected metadata with the user. Returned if part of the call to POST /users.

Allowable Values:

The names and values of up to 20 fields

​
Sample response body

JSON
{
  "token": "activate_05",
  "user_token": "my_user_01",
  "status": "ACTIVE",
  "reason_code": "00",
  "reason": "Activating user",
  "channel": "API",
  "created_time": "2025-03-15T00:00:00Z",
  "metadata": {
    "my_name_1": "my_value_1",
    "my_name_2": "my_value_2"
  }
}

​
List transitions for user

Action: GET
Endpoint: /usertransitions/user/{user_token} List all transitions for a given user.

​
URL path parameters

FieldsDescription
user_token

string

Required		Unique identifier of the user resource.

Allowable Values:

Existing user resource token

​
URL query parameters

FieldsDescription
count

integer

Optional		Number of user transitions 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:
-id

​
Response body

FieldsDescription
count

integer

Conditionally returned		Number of resources retrieved.

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

Resources are returned as appropriate to your query.

Allowable Values:

Valid array of one or more user transition resources
data[].channel

string

Returned		Mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM
data[].created_time

datetime

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

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
data[].created_timestamp

datetime

Conditionally returned		Date and time when the resource was created. Expressed in UTC, with millisecond precision.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ss:SSSZ
data[].last_modified_time

datetime

Conditionally returned		Date and time when the resource was last modified, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
data[].reason

string

Conditionally returned		Additional information about the status change.

Allowable Values:

255 char max
data[].reason_code

string

Returned		Identifies the standardized reason for the transition:

00: Object activated for the first time.

01: Requested by you.

02: Inactivity over time.

03: This address cannot accept mail or the addressee is unknown.

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.

19: Changed to ACTIVE because account activity was properly validated.

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.

24: Address issue.

25: Name issue.

26: SSN issue.

27: DOB issue.

28: Email issue.

29: Phone issue.

30: Account/fulfillment mismatch.

31: Other reason.

86: Notification of death.

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 86
data[].status

string

Returned		Specifies the new status of the user.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED, TERMINATED
data[].token

string

Returned		Unique identifier of the user transition.

Allowable Values:

Existing user transition token
data[].user_token

string

Conditionally returned		Unique identifier of the user whose status was transitioned.

Allowable Values:

Existing user token
data[].metadata

object

Conditionally returned		Associates customer-injected metadata with the user. Returned if part of the call to POST /users.

Allowable Values:

The names and values of up to 20 fields
end_index

integer

Conditionally returned		Sort order index of the last 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
{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "activate_05",
      "user_token": "my_user_01",
      "status": "ACTIVE",
      "reason_code": "00",
      "reason": "Activating user",
      "channel": "API",
      "created_time": "2025-03-15T00:00:00Z",
      "metadata": {
        "my_name_1": "my_value_1",
        "my_name_2": "my_value_2"
      }
    }
  ]
}

​
Retrieve user transition

Action: GET
Endpoint: /usertransitions/{token} Retrieve a user transition.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the user transition you want to retrieve.

Allowable Values:

Existing user transition token

​
URL query parameters

FieldsDescription
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

FieldsDescription
channel

string

Returned		Mechanism by which the transaction was initiated.

Allowable Values:

API, IVR, FRAUD, ADMIN, SYSTEM
created_time

datetime

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

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
created_timestamp

datetime

Conditionally returned		Date and time when the resource was created. Expressed in UTC, with millisecond precision.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ss:SSSZ
last_modified_time

datetime

Conditionally returned		Date and time when the resource was last modified, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
reason

string

Conditionally returned		Additional information about the status change.

Allowable Values:

255 char max
reason_code

string

Returned		Identifies the standardized reason for the transition:

00: Object activated for the first time.

01: Requested by you.

02: Inactivity over time.

03: This address cannot accept mail or the addressee is unknown.

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.

19: Changed to ACTIVE because account activity was properly validated.

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.

24: Address issue.

25: Name issue.

26: SSN issue.

27: DOB issue.

28: Email issue.

29: Phone issue.

30: Account/fulfillment mismatch.

31: Other reason.

86: Notification of death.

Allowable Values:

00, 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 86
status

string

Returned		Specifies the new status of the user.

Allowable Values:

UNVERIFIED, LIMITED, ACTIVE, SUSPENDED, CLOSED, TERMINATED
token

string

Returned		Unique identifier of the user transition.

Allowable Values:

Existing user transition token
user_token

string

Conditionally returned		Unique identifier of the user whose status was transitioned.

Allowable Values:

Existing user token
metadata

object

Conditionally returned		Associates customer-injected metadata with the user. Returned if part of the call to POST /users.

Allowable Values:

The names and values of up to 20 fields

​
Sample response body

JSON
{
  "token": "activate_05",
  "user_token": "my_user_01",
  "status": "ACTIVE",
  "reason_code": "00",
  "reason": "Activating user",
  "channel": "API",
  "created_time": "2025-03-15T00:00:00Z",
  "metadata": {
    "my_name_1": "my_value_1",
    "my_name_2": "my_value_2"
  }
}

Related topics

Account TransitionsBusiness TransitionsCard TransitionsUsersApplications