// Conditional snippet for beta or internal content include::../../maturity-admonition-banner.adoc[] // This source file is used by InfoDev to generate API reference documentation. // File location in GitHub is: // https://github.marqeta.com/openapi/coreapi/blob/main/openapi/usertransitions/openapi.yaml Use the `/usertransitions` endpoints to transition user resources between statuses, as well as to retrieve and list status changes for a user resource.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/marqeta:marqeta-user-transitions-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
contact:
email: support@marqeta.com
name: Marqeta
description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta.
termsOfService: https://www.marqeta.com/api-terms
title: Core User Transitions API
version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- description: '// Conditional snippet for beta or internal content
include::../../maturity-admonition-banner.adoc[]
// This source file is used by InfoDev to generate API reference documentation.
// File location in GitHub is:
// https://github.marqeta.com/openapi/coreapi/blob/main/openapi/usertransitions/openapi.yaml
Use the `/usertransitions` endpoints to transition user resources between statuses, as well as to retrieve and list status changes for a user resource.'
name: User Transitions
paths:
/usertransitions:
post:
description: '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.
[cols="2a,4a,3a"]
|===
| 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.'
operationId: postUsertransitions
requestBody:
content:
application/json:
example:
channel: API
reason: Activating user
reason_code: '00'
status: ACTIVE
token: activate_05
user_token: my_user_01
schema:
$ref: '#/components/schemas/UserTransitionRequest'
required: false
responses:
'201':
content:
application/json:
example:
channel: API
created_time: 2025-03-15 00:00:00+00:00
metadata:
my_name_1: my_value_1
my_name_2: my_value_2
reason: Activating user
reason_code: '00'
status: ACTIVE
token: activate_05
user_token: my_user_01
schema:
$ref: '#/components/schemas/UserTransitionResponse'
description: Success
'400':
content: {}
description: User input error/Bad request
'409':
content: {}
description: Request already processed with a different payload
'412':
content: {}
description: Pre-condition setup issue
'500':
content: {}
description: Server error
summary: Create user transition
tags:
- User Transitions
/usertransitions/user/{user_token}:
get:
description: List all transitions for a given user.
operationId: getUsertransitionsUserUsertoken
parameters:
- description: Unique identifier of the user resource.
explode: false
in: path
name: user_token
required: true
schema:
type: string
style: simple
- description: Number of user transitions to retrieve.
explode: true
in: query
name: count
required: false
schema:
default: 5
format: int32
type: integer
style: form
- description: Sort order index of the first resource in the returned array.
explode: true
in: query
name: start_index
required: false
schema:
default: 0
format: int32
type: integer
style: form
- description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on).
Leave blank to return all fields.'
explode: true
in: query
name: fields
required: false
schema:
type: string
style: form
- description: '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.'
explode: true
in: query
name: sort_by
required: false
schema:
default: -id
type: string
style: form
responses:
'200':
content:
application/json:
example:
count: 1
data:
- channel: API
created_time: 2025-03-15 00:00:00+00:00
metadata:
my_name_1: my_value_1
my_name_2: my_value_2
reason: Activating user
reason_code: '00'
status: ACTIVE
token: activate_05
user_token: my_user_01
end_index: 0
is_more: false
start_index: 0
schema:
$ref: '#/components/schemas/UserTransitionListResponse'
description: Success
'400':
content: {}
description: Bad request
'500':
content: {}
description: Server error
summary: List transitions for user
tags:
- User Transitions
/usertransitions/{token}:
get:
description: Retrieve a user transition.
operationId: getUsertransitionsToken
parameters:
- description: Unique identifier of the user transition you want to retrieve.
explode: false
in: path
name: token
required: true
schema:
type: string
style: simple
- description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on).
Leave blank to return all fields.'
explode: true
in: query
name: fields
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
example:
channel: API
created_time: 2025-03-15 00:00:00+00:00
metadata:
my_name_1: my_value_1
my_name_2: my_value_2
reason: Activating user
reason_code: '00'
status: ACTIVE
token: activate_05
user_token: my_user_01
schema:
$ref: '#/components/schemas/UserTransitionResponse'
description: Success
'400':
content: {}
description: Bad request
'404':
content: {}
description: Cardholder not found
'500':
content: {}
description: Server error
summary: Retrieve user transition
tags:
- User Transitions
components:
schemas:
UserTransitionResponse:
properties:
channel:
description: Mechanism by which the transaction was initiated.
enum:
- API
- IVR
- FRAUD
- ADMIN
- SYSTEM
type: string
created_time:
description: Date and time when the resource was created, in UTC.
format: date-time
type: string
created_timestamp:
description: 'Date and time when the resource was created.
Expressed in UTC, with millisecond precision.'
format: date-time
type: string
last_modified_time:
description: Date and time when the resource was last modified, in UTC.
format: date-time
type: string
metadata:
additionalProperties:
type: string
description: 'Associates customer-injected metadata with the user.
Returned if part of the call to `POST /users`.'
type: object
reason:
description: Additional information about the status change.
type: string
reason_code:
description: '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.'
enum:
- '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'
- '32'
- '86'
type: string
status:
description: Specifies the new status of the user.
enum:
- UNVERIFIED
- LIMITED
- ACTIVE
- SUSPENDED
- CLOSED
- TERMINATED
type: string
token:
description: Unique identifier of the user transition.
type: string
user_token:
description: Unique identifier of the user whose status was transitioned.
type: string
required:
- channel
- reason_code
- status
- token
type: object
UserTransitionListResponse:
properties:
count:
description: 'Number of resources retrieved.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
data:
description: 'Array of user transition resources.
Resources are returned as appropriate to your query.'
items:
$ref: '#/components/schemas/UserTransitionResponse'
type: array
end_index:
description: 'Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
is_more:
default: false
description: '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.'
type: boolean
start_index:
description: 'Sort order index of the first resource in the returned array.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
type: object
UserTransitionRequest:
properties:
channel:
description: Mechanism by which the transaction was initiated.
enum:
- API
- IVR
- FRAUD
- ADMIN
- SYSTEM
type: string
idempotentHash:
description: Unique hashed value that identifies subsequent submissions of the user transition request.
type: string
reason:
description: Additional information about the status change.
maxLength: 255
minLength: 0
type: string
reason_code:
description: '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.'
enum:
- '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'
- '32'
- '86'
type: string
status:
description: Specifies the new status of the user.
enum:
- UNVERIFIED
- LIMITED
- ACTIVE
- SUSPENDED
- CLOSED
- TERMINATED
type: string
token:
description: '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.'
type: string
user_token:
description: Unique identifier of the user whose status you want to transition.
type: string
required:
- channel
- reason_code
- status
- user_token
type: object
securitySchemes:
mqAppAndAccessToken:
scheme: basic
type: http
x-provenance:
method: harvested
publisher: Marqeta
source: https://raw.githubusercontent.com/marqeta/marqeta-openapi/HEAD/yaml/CoreAPI-3.0.39.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)