MX Categories API

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 Categories API
  version: '20250224'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: categories
  description: "A `transaction` can have its `category` set to one of MX’s default categories or a custom category for a specific `user`. \n\nSee [Default Categories and Subcategories](docs.mx.com/api-reference/platform-api/reference/categories#default-categories-and-subcategories) for a complete list.\n"
paths:
  /categories/default:
    get:
      description: Use this endpoint to retrieve a list of all the default categories and subcategories offered within the MX Platform API. In other words, each item in the returned list will have its `is_default` field set to `true`. There are currently 119 default categories and subcategories. Both the _list default categories_ and _list default categories by user_ endpoints return the same results. The different routes are provided for convenience.
      operationId: listDefaultCategories
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPage'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponseBody'
          description: OK
      summary: List default categories
      tags:
      - categories
  /categories/{category_guid}:
    get:
      description: Use this endpoint to read the attributes of a default category.
      operationId: readDefaultCategory
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/categoryGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponseBody'
          description: OK
      summary: Read a default category
      tags:
      - categories
  /users/{user_guid}/accounts/{account_guid}/date_range_category_totals:
    get:
      tags:
      - categories
      summary: List category totals by account
      operationId: listDateRangeCategoryTotalsByAccount
      description: Returns a list of categories that have transactions dated within the provided date range, and the total of all transactions that belong to each category.
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/userGuid'
      - $ref: '#/components/parameters/accountGuid'
      - $ref: '#/components/parameters/fromDateRequired'
      - $ref: '#/components/parameters/toDateRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DateRangeCategoryTotalsResponseBody'
  /users/{user_guid}/date_range_category_totals:
    get:
      tags:
      - categories
      summary: List category totals by user
      operationId: listCategoryTotalsByUser
      description: Returns a list of categories that have transactions dated within the provided date range, and the total of all transactions that belong to each category.
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/userGuid'
      - $ref: '#/components/parameters/fromDateRequired'
      - $ref: '#/components/parameters/toDateRequired'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DateRangeCategoryTotalsResponseBody'
  /users/{user_guid}/categories:
    get:
      description: Use this endpoint to list all categories associated with a `user`, including both default and custom categories.
      operationId: listCategories
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponseBody'
          description: OK
      summary: List categories
      tags:
      - categories
    post:
      description: Use this endpoint to create a new custom category for a specific `user`.
      operationId: createCategory
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/userGuid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryCreateRequestBody'
        description: Custom category object to be created
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponseBody'
          description: OK
      summary: Create category
      tags:
      - categories
  /users/{user_guid}/categories/default:
    get:
      description: Use this endpoint to retrieve a list of all the default categories and subcategories, scoped by user, offered within the MX Platform API. In other words, each item in the returned list will have its `is_default` field set to `true`. There are currently 119 default categories and subcategories. Both the _list default categories_ and _list default categories by user_ endpoints return the same results. The different routes are provided for convenience.
      operationId: listDefaultCategoriesByUser
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponseBody'
          description: OK
      summary: List default categories by user
      tags:
      - categories
  /users/{user_guid}/categories/{category_guid}:
    delete:
      description: Use this endpoint to delete a specific custom category according to its unique GUID. The API will respond with an empty object and a status of `204 No Content`.
      operationId: deleteCategory
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/categoryGuid'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '204':
          description: No Content
      summary: Delete category
      tags:
      - categories
    get:
      description: Use this endpoint to read the attributes of either a default category or a custom category.
      operationId: readCategory
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/categoryGuid'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponseBody'
          description: OK
      summary: Read a custom category
      tags:
      - categories
    put:
      description: Use this endpoint to update the attributes of a custom category according to its unique GUID.
      operationId: updateCategory
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/categoryGuid'
      - $ref: '#/components/parameters/userGuid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryUpdateRequestBody'
        description: Category object to be updated (While no single parameter is required, the `category` object cannot be empty)
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponseBody'
          description: OK
      summary: Update category
      tags:
      - categories
components:
  schemas:
    CategoryCreateRequest:
      properties:
        metadata:
          description: Additional information you can store on the `category`.
          example: some metadata
          type: string
        name:
          example: Online Shopping
          type: string
          description: The name of the category.
        parent_guid:
          example: CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f
          type: string
          description: The unique identifier for the parent category.
      required:
      - name
      - parent_guid
      type: object
    CategoryUpdateRequest:
      properties:
        metadata:
          description: Additional information you can store on the `category`.
          example: some metadata
          type: string
        name:
          example: Web shopping
          type: string
          description: The name of the category.
      type: object
    CategoryResponse:
      properties:
        created_at:
          description: The date and time the category was created, represented in ISO 8601 format with a timestamp.
          example: '2025-02-13T18:08:00+00:00'
          type:
          - string
          - 'null'
        guid:
          description: The unique identifier for the category. Defined by MX.
          example: CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874
          type:
          - string
          - 'null'
        is_default:
          description: Indicates whether the category is an MX-created default category. This will always be `false` for custom categories.
          example: true
          type:
          - boolean
          - 'null'
        is_income:
          description: Indicates whether the transaction is income.
          example: false
          type:
          - boolean
          - 'null'
        metadata:
          description: Additional information you stored on the `category`.
          example: some metadata
          type:
          - string
          - 'null'
        name:
          example: Auto Insurance
          type:
          - string
          - 'null'
          description: The name of the category.
        parent_guid:
          description: The unique identifier for the parent category. Defined by MX.
          example: CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874
          type:
          - string
          - 'null'
        updated_at:
          description: 'The date and time the resource was last updated in ISO 8601 format with a timestamp.


            For categories, this field will always be `null` when `is_default` is `true`.

            '
          example: '2025-02-13T18:09:00+00:00'
          type:
          - string
          - 'null'
      type: object
    DateRangeCategoryTotalsResponse:
      properties:
        category_guid:
          type: string
          description: The unique identifier for the category. Defined by MX.
          example: CAT-bf9f3294-4c40-1677-d269-54fbc189faf3
        end_date:
          type: integer
          description: The Unix timestamp for the end date of the date range.
          example: 1466056800
        start_date:
          type: integer
          description: The Unix timestamp for the start date of the date range.
          example: 1459490400
        total:
          type: number
          description: The total amount for the category within the date range.
          example: 155.72
        user_guid:
          type: string
          description: The unique identifier for the user. Defined by MX.
          example: USR-d8843e3e-7153-ce05-db54-fb3241c15d94
    CategoryUpdateRequestBody:
      properties:
        category:
          $ref: '#/components/schemas/CategoryUpdateRequest'
      type: object
    CategoryResponseBody:
      properties:
        category:
          $ref: '#/components/schemas/CategoryResponse'
      type: object
    CategoriesResponseBody:
      properties:
        categories:
          items:
            $ref: '#/components/schemas/CategoryResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      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
    DateRangeCategoryTotalsResponseBody:
      type: object
      properties:
        date_range_category_totals:
          items:
            $ref: '#/components/schemas/DateRangeCategoryTotalsResponse'
          type: array
    CategoryCreateRequestBody:
      properties:
        category:
          $ref: '#/components/schemas/CategoryCreateRequest'
      type: object
  parameters:
    toDateRequired:
      description: Filter transactions to this date (at midnight). This only supports ISO 8601 format without timestamp (YYYY-MM-DD). Defaults to 5 days forward from the day the request is made to capture pending transactions.
      example: '2024-08-28'
      in: query
      required: true
      name: to_date
      schema:
        type: string
    recordsPerPage:
      description: This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `100`. If the value exceeds `100`, the default value of `25` will be used instead.
      example: 10
      in: query
      name: records_per_page
      schema:
        type: integer
    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
    accountGuid:
      description: The unique id for an `account`.
      example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
      in: path
      name: account_guid
      required: true
      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
    fromDateRequired:
      description: Filter transactions from this date. This only supports ISO 8601 format without timestamp (YYYY-MM-DD). Defaults to 120 days ago if not provided.
      example: '2024-02-01'
      required: true
      in: query
      name: from_date
      schema:
        type: string
    userGuid:
      description: The unique identifier for a `user`, beginning with the prefix `USR-`.
      example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
      in: path
      name: user_guid
      required: true
      schema:
        type: string
    categoryGuid:
      name: category_guid
      description: The unique id for a `category`.
      in: path
      required: true
      schema:
        type: string
        example: CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874
  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