openapi: 3.2.0
info:
  contact:
    name: MX Platform API
    url: https://www.mx.com/products/platform-api
  description: 'The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions.


    ## What''s Changed?


    Several endpoints, headers, and fields changed in `v20250224`. For more on breaking changes, refer to our [versioning](/api-reference/platform-api/overview/versioning#v20250224) and [migration](/api-reference/platform-api/overview/migration) guides.


    ## Version Header

    Versions are set in the `Accept-Version` header of API requests. Version numbers correspond with the date associated with that version.  The example below uses the version `v20250224`.


    ```

    -H ''Accept: application/json''

    -H ''Accept-Version: v20250224''

    ```


    ---

    '
  title: MX Platform Users API
  version: '20250224'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: users
  description: 'Users represent an end user using the Platform API through your web or mobile app.


    Users are created by MX clients and belong to a specific [client](docs.mx.com/products/connectivity/overview/data-architecture/#clients) on the platform.

    '
paths:
  /users:
    get:
      description: Use this endpoint to list every user you've created in the MX Platform API.
      operationId: listUsers
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/userEmail'
      - $ref: '#/components/parameters/userIsDisabled'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponseBody'
          description: OK
      summary: List users
      tags:
      - users
    post:
      description: Use this endpoint to create a new user. The API will respond with the newly-created user object if successful, containing a `guid` that you'll set as the `user_guid` in other requests when required. Disabling a user means that accounts and transactions associated with it will not be updated in the background by MX. It will also restrict access to that user’s data until they are no longer disabled.
      operationId: createUser
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequestBody'
        description: User object to be created. (None of these parameters are required, but the user object cannot be empty)
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponseBody'
          description: OK
      summary: Create user
      tags:
      - users
  /users/{user_identifier}:
    delete:
      description: 'Use this endpoint to delete the specified `user`. The response will have a status of `204 No Content` without an object.


        <Warning>

        Deleting a user is permanent. Deleted users can never be restored. For more info, see [Deleting Objects](/api-reference/platform-api/overview/deleting-objects).

        </Warning>

        '
      operationId: deleteUser
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/acceptHeader'
      - $ref: '#/components/parameters/userIdentifier'
      responses:
        '204':
          description: No Content
      summary: Delete user
      tags:
      - users
    get:
      description: Use this endpoint to read the attributes of a specific user.
      operationId: readUser
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/userIdentifier'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponseBody'
          description: OK
      summary: Read user
      tags:
      - users
    put:
      description: Use this endpoint to update the attributes of the specified user.
      operationId: updateUser
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/userIdentifier'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateRequestBody'
        description: User object to be updated (None of these parameters are required, but the user object cannot be empty.)
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponseBody'
          description: OK
      summary: Update user
      tags:
      - users
components:
  schemas:
    UserUpdateRequestBody:
      properties:
        user:
          $ref: '#/components/schemas/UserUpdateRequest'
      type: object
    PaginationResponse:
      properties:
        current_page:
          description: The page delivered by the current response.
          example: 1
          type: integer
        per_page:
          description: The number of records delivered with each page.
          example: 25
          type: integer
        total_entries:
          description: The total number of records available.
          example: 1
          type: integer
        total_pages:
          description: The total number of pages available.
          example: 1
          type: integer
      type: object
    UsersResponseBody:
      properties:
        users:
          items:
            $ref: '#/components/schemas/UserResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    UserCreateRequestBody:
      properties:
        user:
          $ref: '#/components/schemas/UserCreateRequest'
      type: object
    UserCreateRequest:
      properties:
        email:
          description: The email address associated with the account.
          example: example@example.com
          type: string
        id:
          description: The unique partner-defined identifier for the user.
          example: My-Unique-ID
          type: string
        is_disabled:
          description: Indicates whether the user has been disabled. Defaults to `false`.
          example: false
          type: boolean
        metadata:
          description: Additional information you can store about the `user`.
          example: '{\"type\": \"individual\", \"status\": \"preferred\"}'
          type: string
      type: object
    UserResponse:
      properties:
        email:
          description: The email address associated with the account.
          example: example@example.com
          type: string
        guid:
          description: The unique identifier for the user. Defined by MX.
          example: USR-d74cb14f-fd0a-449f-991b-e0362a63d9c6
          type:
          - string
          - 'null'
        id:
          description: The unique partner-defined identifier for the user.
          example: My-Unique-ID
          type:
          - string
          - 'null'
        is_disabled:
          description: Indicates whether the user has been disabled. Defaults to `false`.
          example: false
          type:
          - boolean
          - 'null'
        metadata:
          description: Additional information you stored about the `user`.
          example: '{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}'
          type:
          - string
          - 'null'
      type: object
    UserUpdateRequest:
      properties:
        email:
          description: The email address associated with the account.
          example: example@example.com
          type: string
        id:
          description: The unique partner-defined identifier for the user.
          example: My-Unique-ID
          type: string
        is_disabled:
          description: Indicates whether the user has been disabled. Defaults to `false`.
          example: false
          type: boolean
        metadata:
          description: Additional information you can store about the `user`.
          example: '{\"first_name\": \"Steven\", \"last_name\": \"Universe\"}'
          type: string
      type: object
    UserResponseBody:
      properties:
        user:
          $ref: '#/components/schemas/UserResponse'
      type: object
  parameters:
    userIsDisabled:
      description: Search for users that are disabled.
      example: true
      in: query
      name: is_disabled
      schema:
        type: boolean
    userId:
      description: The user `id` to search for.
      example: u-12324-abdc
      in: query
      name: id
      schema:
        type: string
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: string
        default: v20250224
        example: v20250224
      description: MX Platform API version.
    page:
      description: Results are paginated. Specify current page.
      example: 1
      in: query
      name: page
      schema:
        type: integer
    userEmail:
      description: The user `email` to search for.
      example: example@example.com
      in: query
      name: email
      schema:
        type: string
    recordsPerPageMax1000:
      description: This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `1000`. If the value exceeds `1000`, the default value of `25` will be used instead.
      example: 10
      in: query
      name: records_per_page
      schema:
        type: integer
    acceptHeader:
      description: Specifies the media type expected in the response.
      in: header
      name: Accept
      required: true
      schema:
        type: string
        example: application/json
    userIdentifier:
      description: Use either the user `id` you defined or the MX-defined user `guid`. See [MX-Defined GUIDs vs IDs Defined by You​](/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you).
      in: path
      required: true
      name: user_identifier
      schema:
        type: string
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http
      description: 'The MX Platform API requires basic access authentication using your `client_id` and `api_key`. These credentials must be Base64 encoded and included in the Authorization header of each API request to ensure secure access.


        Here''s an example using curl to access `v20250224`. Replace `https://int-api.mx.com/endpoint` with the actual API endpoint you wish to access and your Base64 encoded `client_id` and `api_key`.


        ```

        curl -L -X POST `https://int-api.mx.com/endpoint'' \

        -H ''Content-Type: application/json'' \

        -H ''Accept: application/json'' \

        -H ''Accept-Version: v20250224''

        -H ''Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}''

        ```

        '
    bearerAuth:
      type: http
      scheme: bearer