MX transaction rules 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 transaction rules API
  version: '20250224'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: transaction rules
  description: 'Transaction Rules allow users to automatically recategorize or rename all similar transactions according to their preferences. This only applies to future transactions.


    When recategorizing or renaming a transaction, the user will be asked whether they want the new data to apply to the selected transaction or to all future transactions. If they choose to apply it to all future transactions, it will create a transaction rule which will automatically apply the changes going forward.

    '
paths:
  /users/{user_guid}/transaction_rules:
    get:
      description: Use this endpoint to read the attributes of all existing transaction rules belonging to the user.
      operationId: listTransactionRules
      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/TransactionRulesResponseBody'
          description: OK
      summary: List transaction rules
      tags:
      - transaction rules
    post:
      description: 'Use this endpoint to create a new transaction rule. The newly-created `transaction_rule` object will be returned if successful.


        For more information about transaction rules, see the [Transaction Rules Guide](/products/experience/pfm/integration-guides/personalization/transaction-rules).

        '
      operationId: createTransactionRule
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/userGuid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRuleCreateRequestBody'
        description: TransactionRule object to be created with optional parameters (description) and required parameters (category_guid and match_description)
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRuleResponseBody'
          description: OK
      summary: Create transaction rule
      tags:
      - transaction rules
  /users/{user_guid}/transaction_rules/{transaction_rule_guid}:
    get:
      description: Use this endpoint to read the attributes of an existing transaction rule based on the rule’s unique GUID.
      operationId: readTransactionRule
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/transactionRuleGuid'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRuleResponseBody'
          description: OK
      summary: Read transaction rule
      tags:
      - transaction rules
    put:
      description: 'Use this endpoint to update the attributes of a specific transaction rule based on its unique GUID. The API will respond with the updated transaction_rule object. Any attributes not provided will be left unchanged.


        For more information about transaction rules, see the [Transaction Rules Guide](/products/experience/pfm/integration-guides/personalization/transaction-rules).

        '
      operationId: updateTransactionRule
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/transactionRuleGuid'
      - $ref: '#/components/parameters/userGuid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRuleUpdateRequestBody'
        description: TransactionRule object to be updated
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionRuleResponseBody'
          description: OK
      summary: Update transaction rule
      tags:
      - transaction rules
components:
  schemas:
    TransactionRuleCreateRequest:
      properties:
        category_guid:
          description: The unique identifier for the category. Defined by MX.
          example: CAT-b6d61a19-30a7-e852-2703-bdfb4072289e
          type:
          - string
          - 'null'
        description:
          example: Wal-mart food storage
          type: string
        match_description:
          example: Wal-mart
          type: string
      required:
      - category_guid
      - match_description
      type: object
    TransactionRuleResponseBody:
      properties:
        transaction_rule:
          $ref: '#/components/schemas/TransactionRuleResponse'
      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
    TransactionRuleUpdateRequestBody:
      properties:
        transaction_rule:
          $ref: '#/components/schemas/TransactionRuleUpdateRequest'
      type: object
    TransactionRuleResponse:
      properties:
        category_guid:
          description: The unique identifier for the category. Defined by MX.
          example: CAT-b6d61a19-30a7-e852-2703-bdfb4072289e
          type:
          - string
          - 'null'
        created_at:
          description: The date and time the resource was created, represented in ISO 8601 format with a timestamp.
          example: '2025-02-13T18:08:00+00:00'
          type:
          - string
          - 'null'
        description:
          description: The matched transaction's `description` will be updated to the string provided here.
          example: Wal-mart food storage
          type:
          - string
          - 'null'
        guid:
          description: A unique identifier for the `transaction_rule`. Defined by MX.
          example: TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3
          type:
          - string
          - 'null'
        match_description:
          description: A string used to find a transaction to which the rule will be applied. Transaction matching is based on a comparison of `match_description` to a transaction's cleansed description.
          example: Wal-mart
          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'
        user_guid:
          description: The unique identifier for the user. Defined by MX.
          example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
          type:
          - string
          - 'null'
      type: object
    TransactionRuleCreateRequestBody:
      properties:
        transaction_rule:
          $ref: '#/components/schemas/TransactionRuleCreateRequest'
      type: object
    TransactionRuleUpdateRequest:
      properties:
        category_guid:
          description: The unique identifier for the category. Defined by MX.
          example: CAT-b6d61a19-30a7-e852-2703-bdfb4072289e
          type:
          - string
          - 'null'
        description:
          description: The matched transaction's `description` will be updated to the string provided here.
          example: Wal-mart food storage
          type: string
        match_description:
          description: A string used to find a transaction to which the rule will be applied. Transaction matching is based on a comparison of `match_description` to a transaction's cleansed description.
          example: Wal-mart
          type: string
      type: object
    TransactionRulesResponseBody:
      properties:
        transaction_rules:
          items:
            $ref: '#/components/schemas/TransactionRuleResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
  parameters:
    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
    page:
      description: Results are paginated. Specify current page.
      example: 1
      in: query
      name: page
      schema:
        type: integer
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: string
        default: v20250224
        example: v20250224
      description: MX Platform API version.
    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
    transactionRuleGuid:
      description: The unique id for a `transaction_rule`.
      example: TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3
      in: path
      name: transaction_rule_guid
      required: true
      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