Marqeta User Transitions API

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