openapi: 3.0.3 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 accepted countries 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: 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 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 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