> ## 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.
# User Transitions
> Use this endpoint to manage and view state transitions for your cardholders.
export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
text: "mint-text-green-700 dark:mint-text-green-400",
border: "mint-border-green-300 dark:mint-border-green-700"
},
POST: {
bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
text: "mint-text-blue-700 dark:mint-text-blue-400"
},
PUT: {
bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
text: "mint-text-yellow-700 dark:mint-text-yellow-400"
},
PATCH: {
bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
text: "mint-text-orange-700 dark:mint-text-orange-400"
},
DELETE: {
bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
text: "mint-text-red-700 dark:mint-text-red-400"
},
API: {
bg: "mint-bg-black",
text: "mint-text-white"
}
};
const MethodBadge = ({method}) => {
const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
return
{method?.toUpperCase()}
;
};
const content =
{}
{}
{title}
{children &&
{children}
}
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 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 `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 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"
}
}
```
List transitions for user
**Action:** `GET`\
**Endpoint:** `/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 model
**Default 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 JSON expandable lines wrap theme={null}
{
"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
| 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 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"
}
}
```