MX Platform Insights 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 Insights API
  version: 0.1.0
servers:
- url: https://api.mx.com
- url: https://int-api.mx.com
security:
- basicAuth: []
tags:
- name: Insights
paths:
  /users/{user_guid}/accounts/{account_guid}/insights:
    get:
      description: Use this endpoint to list all insights associated with a specified account GUID.
      operationId: listInsightsByAccount
      parameters:
      - description: The unique id for the `account`.
        example: ACT-7c6f361b-e582-15b6-60c0-358f12466b4b
        in: path
        name: account_guid
        required: true
        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 the `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/InsightsResponseBody'
          description: OK
      summary: List insights by account
      tags:
      - Insights
  /users/{user_guid}/insights:
    get:
      description: Use this endpoint to list all the insights associated with the user.
      operationId: listInsightsUser
      parameters:
      - description: The unique identifier for the user. Defined by MX.
        example: USR-1234-abcd
        in: path
        name: user_guid
        required: true
        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
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InsightsResponseBody'
          description: OK
      summary: List all insights for a user.
      tags:
      - Insights
  /users/{user_guid}/insights/{insight_guid}/categories:
    get:
      description: Use this endpoint to list all the categories associated with the insight.
      operationId: listCategoriesInsight
      parameters:
      - description: The unique identifier for the user. Defined by MX.
        example: USR-1234-abcd
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      - description: The unique identifier for the insight. Defined by MX.
        example: BET-1234-abcd
        in: path
        name: insight_guid
        required: true
        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
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/CategoriesResponseBody'
          description: OK
      summary: List all categories associated with an insight.
      tags:
      - Insights
  /users/{user_guid}/insights/{insight_guid}/accounts:
    get:
      description: Use this endpoint to list all the accounts associated with the insight.
      operationId: listAccountsInsight
      parameters:
      - description: The unique identifier for the user. Defined by MX.
        example: USR-1234-abcd
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      - description: The unique identifier for the insight. Defined by MX.
        example: BET-1234-abcd
        in: path
        name: insight_guid
        required: true
        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
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/AccountsResponseBody'
          description: OK
      summary: List all accounts associated with an insight.
      tags:
      - Insights
  /users/{user_guid}/insights/{insight_guid}/merchants:
    get:
      description: Use this endpoint to list all the merchants associated with the insight.
      operationId: listMerchantsInsight
      parameters:
      - description: The unique identifier for the user. Defined by MX.
        example: USR-1234-abcd
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      - description: The unique identifier for the insight. Defined by MX.
        example: BET-1234-abcd
        in: path
        name: insight_guid
        required: true
        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
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/MerchantsResponseBody'
          description: OK
      summary: List all merchants associated with an insight.
      tags:
      - Insights
  /users/{user_guid}/insights/{insight_guid}/scheduled_payments:
    get:
      description: Use this endpoint to list all the scheduled payments associated with the insight.
      operationId: listScheduledPaymentsInsight
      parameters:
      - description: The unique identifier for the user. Defined by MX.
        example: USR-1234-abcd
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      - description: The unique identifier for the insight. Defined by MX.
        example: BET-1234-abcd
        in: path
        name: insight_guid
        required: true
        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
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/ScheduledPaymentsResponseBody'
          description: OK
      summary: List all scheduled payments associated with an insight
      tags:
      - Insights
  /users/{user_guid}/insights/{insight_guid}/transactions:
    get:
      description: Use this endpoint to list all the transactions associated with the insight.
      operationId: listTransactionsInsight
      parameters:
      - description: The unique identifier for the user. Defined by MX.
        example: USR-1234-abcd
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      - description: The unique identifier for the insight. Defined by MX.
        example: BET-1234-abcd
        in: path
        name: insight_guid
        required: true
        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
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/TransactionsResponseBody'
          description: OK
      summary: List all transactions associated with an insight.
      tags:
      - Insights
  /users/{user_guid}/insights{insight_guid}:
    get:
      description: Use this endpoint to read the attributes of a specific insight according to its unique GUID.
      operationId: readInsightsUser
      parameters:
      - description: The unique identifier for the user. Defined by MX.
        example: USR-1234-abcd
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      - description: The unique identifier for the insight. Defined by MX.
        example: BET-1234-abcd
        in: path
        name: insight_guid
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InsightResponseBody'
          description: OK
      summary: Read a specific insight.
      tags:
      - Insights
    put:
      description: Use this endpoint to update the attributes of a particular insight according to its unique GUID.
      operationId: updateInsight
      parameters:
      - description: The unique identifier for the user. Defined by MX.
        example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
        in: path
        name: user_guid
        required: true
        schema:
          type: string
      - description: The unique identifier for the insight. Defined by MX.
        example: BET-1234-abcd
        in: path
        name: insight_guid
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightUpdateRequest'
        description: The insight to be updated (None of these parameters are required, but the user object cannot be empty.)
        required: true
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InsightResponse'
          description: OK
      summary: Update insight
      tags:
      - Insights
components:
  schemas:
    AccountResponse:
      properties:
        account_number:
          example: '5366'
          nullable: true
          type: string
        account_ownership:
          example: INDIVIDUAL
          nullable: true
          type: string
        annuity_policy_to_date:
          example: '2016-10-13T17:57:37.000Z'
          nullable: true
          type: string
        annuity_provider:
          example: Metlife
          nullable: true
          type: string
        annuity_term_year:
          example: 2048
          nullable: true
          type: number
        apr:
          example: 1
          nullable: true
          type: number
        apy:
          example: 1
          nullable: true
          type: number
        available_balance:
          example: 1000
          nullable: true
          type: number
        available_credit:
          example: 1000
          nullable: true
          type: number
        balance:
          example: 10000
          nullable: true
          type: number
        cash_balance:
          example: 1000
          nullable: true
          type: number
        cash_surrender_value:
          example: 1000
          nullable: true
          type: number
        created_at:
          example: '2023-07-25T17:14:46Z'
          nullable: false
          type: string
        credit_limit:
          example: 100
          nullable: true
          type: number
        currency_code:
          example: USD
          nullable: true
          type: string
        day_payment_is_due:
          example: 20
          nullable: true
          type: integer
        death_benefit:
          example: 1000
          nullable: true
          type: integer
        federal_insurance_status:
          example: INSURED
          nullable: true
          type: string
        guid:
          example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
          nullable: true
          type: string
        holdings_value:
          example: 1000
          nullable: true
          type: number
        id:
          example: '1040434698'
          nullable: true
          type: string
        imported_at:
          example: '2015-10-13T17:57:37.000Z'
          nullable: true
          type: string
        institution_code:
          example: 3af3685e-05d9-7060-359f-008d0755e993
          nullable: true
          type: string
        insured_name:
          example: Tommy Shelby
          nullable: true
          type: string
        interest_rate:
          example: 1
          nullable: true
          type: number
        is_closed:
          example: false
          nullable: true
          type: boolean
        is_hidden:
          example: false
          nullable: true
          type: boolean
        is_manual:
          example: false
          nullable: true
          type: boolean
        last_payment:
          example: 100
          nullable: true
          type: number
        last_payment_at:
          example: '2023-07-25T17:14:46Z'
          nullable: true
          type: string
        loan_amount:
          example: 1000
          nullable: true
          type: number
        margin_balance:
          example: 1000
          nullable: true
          type: number
        matures_on:
          example: '2015-10-13T17:57:37.000Z'
          nullable: true
          type: string
        member_guid:
          example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
          nullable: true
          type: string
        member_id:
          example: member123
          nullable: true
          type: string
        member_is_managed_by_user:
          example: false
          nullable: true
          type: boolean
        metadata:
          example: some metadata
          nullable: true
          type: string
        minimum_balance:
          example: 100
          nullable: true
          type: number
        minimum_payment:
          example: 10
          nullable: true
          type: number
        name:
          example: Test account 2
          nullable: true
          type: string
        nickname:
          example: My Checking
          nullable: true
          type: string
        original_balance:
          example: 10
          nullable: true
          type: number
        pay_out_amount:
          example: 10
          nullable: true
          type: number
        payment_due_at:
          example: '2015-10-13T17:57:37.000Z'
          nullable: true
          type: string
        payoff_balance:
          example: 10
          nullable: true
          type: number
        premium_amount:
          example: 1
          nullable: true
          type: number
        property_type:
          example: VEHICLE
          nullable: true
          type: string
        routing_number:
          example: '68899990000000'
          nullable: true
          type: string
        started_on:
          example: '2015-10-13T17:57:37.000Z'
          nullable: true
          type: string
        statement_balance:
          example: 100.1
          nullable: true
          type: number
        subtype:
          example: NONE
          nullable: true
          type: string
        today_ugl_amount:
          example: 1000.5
          nullable: true
          type: number
        today_ugl_percentage:
          example: 6.9
          nullable: true
          type: number
        total_account_value:
          example: 1
          nullable: true
          type: number
        total_account_value_ugl:
          example: 1.1
          nullable: true
          type: number
        type:
          example: SAVINGS
          nullable: true
          type: string
        updated_at:
          example: '2016-10-13T18:08:00.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
    CategoryResponse:
      properties:
        created_at:
          example: '2015-04-13T18:01:23.000Z'
          nullable: true
          type: string
        guid:
          example: CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874
          nullable: true
          type: string
        is_default:
          example: true
          nullable: true
          type: boolean
        is_income:
          example: false
          nullable: true
          type: boolean
        metadata:
          example: some metadata
          nullable: true
          type: string
        name:
          example: Auto Insurance
          nullable: true
          type: string
        parent_guid:
          example: CAT-7829f71c-2e8c-afa5-2f55-fa3634b89874
          nullable: true
          type: string
        updated_at:
          example: '2015-05-13T18:01:23.000Z'
          nullable: true
          type: string
      type: object
    MerchantsResponseBody:
      properties:
        merchants:
          items:
            $ref: '#/components/schemas/MerchantResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    InsightResponse:
      properties:
        active_at:
          example: '2022-01-07T12:00:00Z'
          nullable: true
          type: string
        client_guid:
          example: CLT-abcd-1234
          nullable: true
          type: string
        created_at:
          example: '2022-01-12T18:16:51Z'
          nullable: true
          type: string
        cta_clicked_at:
          example: '2022-01-12T18:16:51Z'
          nullable: true
          type: string
        description:
          example: Gold's Gym charged you $36.71 more this month than normal. Did you upgrade your service?
          nullable: true
          type: string
        guid:
          example: BET-abcd-1234
          nullable: true
          type: string
        has_associated_accounts:
          example: false
          nullable: true
          type: boolean
        has_associated_merchants:
          example: false
          nullable: true
          type: boolean
        has_associated_scheduled_payments:
          example: false
          nullable: true
          type: boolean
        has_associated_transactions:
          example: true
          nullable: true
          type: boolean
        has_been_displayed:
          example: true
          nullable: true
          type: boolean
        is_dismissed:
          example: false
          nullable: true
          type: boolean
        micro_call_to_action:
          example: Learn more
          nullable: true
          type: string
        micro_description:
          example: Netflix charged you $5.00 more this month than normal.
          nullable: true
          type: string
        micro_title:
          example: Price increase
          nullable: true
          type: string
        template:
          example: SubscriptionPriceIncrease
          nullable: true
          type: string
        title:
          example: Price increase
          nullable: true
          type: string
        updated_at:
          example: '2022-01-12T18:16:51Z'
          nullable: true
          type: string
        user_guid:
          example: USR-1234-abcd
          type: string
        user_id:
          example: user-partner-defined-1234
      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
    ScheduledPaymentResponse:
      properties:
        amount:
          example: 13.54
          type: number
        created_at:
          example: '2023-04-27T23:14:16.000Z'
          type: string
        description:
          example: Netflix
          type: string
        guid:
          example: SPA-c76e4a85-b2c4-4335-82b7-8f8b8f28c35a
          type: string
        is_completed:
          example: false
          type: boolean
        is_recurring:
          example: true
          type: boolean
        merchant_guid:
          example: MCH-b8a2624c-2176-59ec-c150-37854bc38aa8
          type: string
        occurs_on:
          example: '2022-01-15T00:00:00.000Z'
          type: string
        recurrence_day:
          example: 15
          type: integer
        recurrence_type:
          example: EVERY_MONTH
          type: string
        transaction_type:
          example: DEBIT
          type: string
        updated_at:
          example: '2023-04-27T23:14:16.000Z'
          type: string
        user_guid:
          example: USR-72086f59-6684-4adf-8f29-c4d32db43cd7
          type: string
      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
    InsightResponseBody:
      properties:
        insight:
          items:
            $ref: '#/components/schemas/InsightResponse'
          type: object
      type: object
    InsightsResponseBody:
      properties:
        insights:
          items:
            $ref: '#/components/schemas/InsightResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    CategoriesResponseBody:
      properties:
        categories:
          items:
            $ref: '#/components/schemas/CategoryResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    AccountsResponseBody:
      properties:
        accounts:
          items:
            $ref: '#/components/schemas/AccountResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    ScheduledPaymentsResponseBody:
      properties:
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
        scheduled_payments:
          items:
            $ref: '#/components/schemas/ScheduledPaymentResponse'
          type: array
      type: object
    MerchantResponse:
      properties:
        created_at:
          example: '2017-04-20T19:30:12.000Z'
          nullable: true
          type: string
        guid:
          example: MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b
          nullable: true
          type: string
        logo_url:
          example: https://s3.amazonaws.com/MD_Assets/merchant_logos/comcast.png
          nullable: true
          type: string
        name:
          example: Comcast
          nullable: true
          type: string
        updated_at:
          example: '2018-09-28T21:13:53.000Z'
          nullable: true
          type: string
        website_url:
          example: https://www.xfinity.com
          nullable: true
          type: string
      type: object
    InsightUpdateRequest:
      properties:
        has_been_displayed:
          example: false
          type: boolean
        is_dismissed:
          example: false
          type: boolean
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http