> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create user transition

> This endpoint enables you to change a user's status, depending on your role and the previous status change.

POST/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]
>
> **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

| 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. Send a `GET` request to the `/users` endpoint to obtain a user token. **Allowable Values:**  Existing user token. |

## Sample request body

```json JSON lines wrap theme={null}
{
  "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 JSON lines wrap theme={null}
{
  "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

- [User Transitions Overview](https://www.marqeta.com/docs/core-api/user-transitions.md)
- [Create user](https://www.marqeta.com/docs/core-api/users/create-user.md)
- [Create card transition](https://www.marqeta.com/docs/core-api/card-transitions/create-card-transition.md)
- [Create dispute case transition](https://www.marqeta.com/docs/core-api/disputes-mastercard/dispute-case-transitions-mastercard/create-dispute-case-transition-mastercard.md)
- [Create account transition](https://www.marqeta.com/docs/core-api/deposit-accounts-v4/account-transitions-v4/create-account-transition.md)