/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:POSTEndpoint:
/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 Field | Description | User Limitations |
|---|---|---|
UNVERIFIED | Initial 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 |
LIMITED | Initial 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 |
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. Allowable Transitions: SUSPENDED, CLOSED, UNVERIFIED | None. user.active Field: true |
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.Allowable Transitions: ACTIVE, LIMITED, UNVERIFIED, CLOSED, TERMINATED | Cannot activate cards, load funds, or transact. user.active Field: false |
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.Allowable Transitions: ACTIVE, LIMITED, UNVERIFIED, SUSPENDED, TERMINATED | Cannot activate cards, load funds, or transact. user.active Field: false |
TERMINATED | The 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
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
| Fields | Description |
|---|---|
| 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
| Fields | Description |
|---|---|
| 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:GETEndpoint:
/usertransitions/user/{user_token}
List all transitions for a given user.
URL path parameters
| Fields | Description |
|---|---|
| user_token string Required | Unique identifier of the user resource. Allowable Values: Existing user resource token |
URL query parameters
| Fields | Description |
|---|---|
| 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 modelDefault value: -id |
Response body
| Fields | Description |
|---|---|
| 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:GETEndpoint:
/usertransitions/{token}
Retrieve a user transition.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the user transition you want to retrieve. Allowable Values: Existing user transition 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 |
|---|---|
| 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"
}
}