User Transitions
Use the /usertransitions
endpoints to transition user
resources between states, and to retrieve and list state changes for a user
resource.
Create user transition
Copy section link
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.)
user.status Field | Description | User Limitations |
---|---|---|
|
Initial status of a new user belonging to an account holder group where KYC is always required. |
Cannot load funds or activate cards. |
|
Initial status of a new user belonging to an account holder group where KYC is conditionally required. |
Restricted by rules in |
|
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. |
None. |
|
The user is temporarily inactive. Transitioning a suspended user to the |
Cannot load funds or activate cards. |
|
The user is permanently inactive. In general, the |
Cannot load funds or activate cards. |
Note
The Marqeta platform transitions a user’s status in response to certain events. For example, a user in theUNVERIFIED
status is transitioned to ACTIVE
when the user passes KYC verification.
Request body
Copy section link
Fields | Description |
---|---|
channel
string
|
The mechanism by which the transaction was initiated. Allowable Values:
|
reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
reason_code
string
|
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 19: Changed to 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. Allowable Values:
|
status
string
|
Specifies the new status of the user. Allowable Values:
|
token
string
|
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
|
The unique identifier of the user whose status is transitioned. Allowable Values: Existing user token. Send a |
Response body
Copy section link
Fields | Description |
---|---|
channel
string
|
The mechanism by which the transaction was initiated. Allowable Values:
|
created_time
datetime
|
The date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
The date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
reason_code
string
|
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 19: Changed to 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. Allowable Values:
|
status
string
|
Specifies the new status of the user. Allowable Values:
|
token
string
|
The unique identifier of the user transition. Allowable Values: Existing user transition token |
user_token
string
|
The unique identifier of the user whose status is transitioned. Allowable Values: Existing |
List transitions for user
Copy section link
Action: GET
Endpoint: /usertransitions/user/{user_token}
Use this endpoint to list all transitions for a given user.
URL path parameters
Copy section link
Fields | Description |
---|---|
user_token
string
|
The unique identifier of the Allowable Values: Existing |
URL query parameters
Copy section link
Fields | Description |
---|---|
count
integer
|
The number of user transitions to retrieve. Allowable Values: 1-10 |
start_index
integer
|
The sort order index of the first resource in the returned array. Allowable Values: Any integer |
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
|
Response body
Copy section link
Fields | Description |
---|---|
count
integer
|
The number of Allowable Values: 1-10 |
data
array of objects
|
An array of user transition objects. Allowable Values: Valid |
data[].channel
string
|
The mechanism by which the transaction was initiated. Allowable Values:
|
data[].created_time
datetime
|
The date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].last_modified_time
datetime
|
The date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
data[].reason_code
string
|
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 19: Changed to 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. Allowable Values:
|
data[].status
string
|
Specifies the new status of the user. Allowable Values:
|
data[].token
string
|
The unique identifier of the user transition. Allowable Values: Existing user transition token |
data[].user_token
string
|
The unique identifier of the user whose status is transitioned. Allowable Values: Existing |
end_index
integer
|
The sort order index of the last resource in the returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of Allowable Values:
|
start_index
integer
|
The sort order index of the first resource in the returned array. Allowable Values: Any integer |
Retrieve user transition
Copy section link
Action: GET
Endpoint: /usertransitions/{token}
Use this endpoint to retrieve a user transition.
URL path parameters
Copy section link
Fields | Description |
---|---|
token
string
|
The unique identifier of the user transition you want to retrieve. Allowable Values: Existing user transition token |
URL query parameters
Copy section link
Fields | Description |
---|---|
fields
string
|
Comma-delimited list of fields to return ( Allowable Values: Comma-delimited list of fields, or blank |
Response body
Copy section link
Fields | Description |
---|---|
channel
string
|
The mechanism by which the transaction was initiated. Allowable Values:
|
created_time
datetime
|
The date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
The date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
reason
string
|
Additional information about the status change. Allowable Values: 255 char max |
reason_code
string
|
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 19: Changed to 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. Allowable Values:
|
status
string
|
Specifies the new status of the user. Allowable Values:
|
token
string
|
The unique identifier of the user transition. Allowable Values: Existing user transition token |
user_token
string
|
The unique identifier of the user whose status is transitioned. Allowable Values: Existing |