MX Platform Tags API

openapi: 3.0.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.'
  title: MX Platform Tags API
  version: 0.1.0
servers:
- url: https://api.mx.com
- url: https://int-api.mx.com
security:
- basicAuth: []
tags:
- name: Tags
paths:
  /users/{user_guid}/tags:
    get:
      description: Use this endpoint to list all tags associated with the specified `user`. Each user includes the `Business` tag by default.
      operationId: listTags
      parameters:
      - description: Specify current page.
        example: 1
        in: query
        name: page
        schema:
          type: integer
      - description: Specify records per page.
        example: 10
        in: query
        name: records_per_page
        schema:
          type: integer
      - description: The unique id for a `user`.
        example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/TagsResponseBody'
          description: OK
      summary: List tags
      tags:
      - Tags
    post:
      description: Use this endpoint to create a new custom tag.
      operationId: createTag
      parameters:
      - description: The unique id for a `user`.
        example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagCreateRequestBody'
        description: Tag object to be created with required parameters (tag_guid)
        required: true
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/TagResponseBody'
          description: OK
      summary: Create tag
      tags:
      - Tags
  /users/{user_guid}/tags/{tag_guid}:
    delete:
      description: Use this endpoint to permanently delete a specific tag based on its unique GUID. If successful, the API will respond with status of `204 No Content`.
      operationId: deleteTag
      parameters:
      - description: The unique id for a `tag`.
        example: TAG-aef36e72-6294-4c38-844d-e573e80aed52
        in: path
        name: tag_guid
        required: true
        schema:
          type: string
      - description: The unique id for a `user`.
        example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
      summary: Delete tag
      tags:
      - Tags
    get:
      description: Use this endpoint to read the attributes of a particular tag according to its unique GUID.
      operationId: readTag
      parameters:
      - description: The unique id for a `tag`.
        example: TAG-aef36e72-6294-4c38-844d-e573e80aed52
        in: path
        name: tag_guid
        required: true
        schema:
          type: string
      - description: The unique id for a `user`.
        example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/TagResponseBody'
          description: OK
      summary: Read tag
      tags:
      - Tags
    put:
      description: Use this endpoint to update the name of a specific tag according to its unique GUID.
      operationId: updateTag
      parameters:
      - description: The unique id for a `tag`.
        example: TAG-aef36e72-6294-4c38-844d-e573e80aed52
        in: path
        name: tag_guid
        required: true
        schema:
          type: string
      - description: The unique id for a `user`.
        example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagUpdateRequestBody'
        description: Tag object to be updated with required parameter (tag_guid)
        required: true
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/TagResponseBody'
          description: OK
      summary: Update tag
      tags:
      - Tags
  /users/{user_guid}/tags/{tag_guid}/transactions:
    get:
      description: Use this endpoint to get a list of all transactions associated with a particular tag according to the tags unique GUID. In other words, a list of all transactions that have been assigned to a particular tag using the create a tagging endpoint.
      operationId: listTransactionsByTag
      parameters:
      - description: Filter transactions from this date.
        example: '2015-09-20'
        in: query
        name: from_date
        schema:
          type: string
      - description: Specify current page.
        example: 1
        in: query
        name: page
        schema:
          type: integer
      - description: Specify records per page.
        example: 10
        in: query
        name: records_per_page
        schema:
          type: integer
      - description: The unique id for a `tag`.
        example: TAG-aef36e72-6294-4c38-844d-e573e80aed52
        in: path
        name: tag_guid
        required: true
        schema:
          type: string
      - description: Filter transactions to this date.
        example: '2019-10-20'
        in: query
        name: to_date
        schema:
          type: string
      - description: The unique id for a `user`.
        example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/TransactionsResponseBody'
          description: OK
      summary: List transactions by tag
      tags:
      - Tags
components:
  schemas:
    TagsResponseBody:
      properties:
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
        tags:
          items:
            $ref: '#/components/schemas/TagResponse'
          type: array
      type: object
    TagUpdateRequest:
      properties:
        name:
          example: MY TAG
          type: string
      required:
      - name
      type: object
    TagUpdateRequestBody:
      properties:
        tag:
          $ref: '#/components/schemas/TagUpdateRequest'
      type: object
    TagResponseBody:
      properties:
        tag:
          $ref: '#/components/schemas/TagResponse'
      type: object
    TagCreateRequest:
      properties:
        name:
          example: MY TAG
          type: string
      required:
      - name
      type: object
    TagCreateRequestBody:
      properties:
        tag:
          $ref: '#/components/schemas/TagCreateRequest'
      type: object
    PaginationResponse:
      properties:
        current_page:
          example: 1
          type: integer
        per_page:
          example: 25
          type: integer
        total_entries:
          example: 1
          type: integer
        total_pages:
          example: 1
          type: integer
      type: object
    TransactionsResponseBody:
      properties:
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
        transactions:
          items:
            $ref: '#/components/schemas/TransactionResponse'
          type: array
      type: object
    TransactionResponse:
      properties:
        account_guid:
          example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
          nullable: true
          type: string
        account_id:
          example: account123
          nullable: true
          type: string
        amount:
          example: 61.11
          nullable: true
          type: number
        category:
          example: Groceries
          nullable: true
          type: string
        category_guid:
          example: CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8
          nullable: true
          type: string
        check_number_string:
          example: '6812'
          nullable: true
          type: string
        created_at:
          example: '2016-10-06T09:43:42.000Z'
          nullable: true
          type: string
        currency_code:
          example: USD
          nullable: true
          type: string
        date:
          example: '2013-09-23T00:00:00.000Z'
          nullable: true
          type: string
        description:
          example: Whole foods
          nullable: true
          type: string
        extended_transaction_type:
          example: partner_transaction_type
          nullable: true
          type: string
        guid:
          example: TRN-265abee9-889b-af6a-c69b-25157db2bdd9
          nullable: true
          type: string
        id:
          example: transaction-265abee9-889b-af6a-c69b-25157db2bdd9
          nullable: true
          type: string
        is_bill_pay:
          example: false
          nullable: true
          type: boolean
        is_direct_deposit:
          example: false
          nullable: true
          type: boolean
        is_expense:
          example: true
          nullable: true
          type: boolean
        is_fee:
          example: false
          nullable: true
          type: boolean
        is_income:
          example: false
          nullable: true
          type: boolean
        is_international:
          example: false
          nullable: true
          type: boolean
        is_overdraft_fee:
          example: false
          nullable: true
          type: boolean
        is_payroll_advance:
          example: false
          nullable: true
          type: boolean
        is_recurring:
          example: false
          nullable: true
          type: boolean
        is_subscription:
          example: false
          nullable: true
          type: boolean
        latitude:
          example: -43.2075
          nullable: true
          type: number
        localized_description:
          example: This is a localized_description
          nullable: true
          type: string
        localized_memo:
          example: This is a localized_memo
          nullable: true
          type: string
        longitude:
          example: 139.691706
          nullable: true
          type: number
        member_guid:
          example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
          nullable: true
          type: string
        member_is_managed_by_user:
          example: false
          nullable: true
          type: boolean
        memo:
          example: This is a memo
          nullable: true
          type: string
        merchant_category_code:
          example: 5411
          nullable: true
          type: integer
        merchant_guid:
          example: MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b
          nullable: true
          type: string
        merchant_location_guid:
          example: MCL-00024e59-18b5-4d79-b879-2a7896726fea
          nullable: true
          type: string
        metadata:
          example: some metadata
          nullable: true
          type: string
        original_description:
          example: WHOLEFDS TSQ 102
          nullable: true
          type: string
        posted_at:
          example: '2016-10-07T06:00:00.000Z'
          nullable: true
          type: string
        status:
          example: POSTED
          nullable: true
          type: string
        top_level_category:
          example: Food & Dining
          nullable: true
          type: string
        transacted_at:
          example: '2016-10-06T13:00:00.000Z'
          nullable: true
          type: string
        type:
          example: DEBIT
          nullable: true
          type: string
        updated_at:
          example: '2016-10-07T05:49:12.000Z'
          nullable: true
          type: string
        user_guid:
          example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
          nullable: true
          type: string
        user_id:
          example: user123
          nullable: true
          type: string
      type: object
    TagResponse:
      properties:
        guid:
          example: TAG-aef36e72-6294-4c38-844d-e573e80aed52
          nullable: true
          type: string
        name:
          example: MY TAG
          nullable: true
          type: string
        user_guid:
          example: USR-11141024-90b3-1bce-cac9-c06ced52ab4c
          nullable: true
          type: string
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http