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.


    Just getting started? See our [use case guides](/use-cases/).

    '
  title: MX Platform accounts investment holdings API
  version: '20111101'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: investment holdings
paths:
  /users/{user_guid}/members/{member_guid}/investment_holdings:
    get:
      description: This endpoint lists all holdings associated with the specified member.
      operationId: listHoldingsByMember
      parameters:
      - $ref: '#/components/parameters/memberGuid'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InvestmentHoldingsResponseBody'
          description: OK
      summary: List holdings by member
      tags:
      - investment holdings
  /users/{user_guid}/investment_holdings:
    get:
      description: This endpoint lists all holdings associated with the user across all accounts.
      operationId: listHoldings
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InvestmentHoldingsResponseBody'
          description: OK
      summary: List holdings by user
      tags:
      - investment holdings
  /users/{user_guid}/investment_holdings/{holding_guid}:
    get:
      description: Use this endpoint to read the attributes of a specific `holding`.
      operationId: readHolding
      parameters:
      - $ref: '#/components/parameters/holdingGuid'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InvestmentHoldingResponseBody'
          description: OK
      summary: Read holding
      tags:
      - investment holdings
  /users/{user_guid}/accounts/{account_guid}/investment_holdings:
    get:
      description: This endpoint lists all holdings associated with the particular account defined.
      operationId: listHoldingsByAccount
      parameters:
      - $ref: '#/components/parameters/accountGuid'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InvestmentHoldingsResponseBody'
          description: OK
      summary: List holdings by account
      tags:
      - investment holdings
  /users/{user_guid}/investment_holdings_deactivate:
    get:
      description: This endpoint deactivates the specific user from the `/investment_holdings` product. To reactivate a user, use any of the current `/investment_holding` endpoints.
      operationId: deactivateUser
      parameters:
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InvestmentHoldingsDeactivation'
          description: OK
      summary: Deactivate user from Investment Holdings
      tags:
      - investment holdings
components:
  parameters:
    holdingGuid:
      description: The unique id for a `holding`.
      example: HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2
      in: path
      name: holding_guid
      required: true
      schema:
        type: string
    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
    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
    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
    page:
      description: Results are paginated. Specify current page.
      example: 1
      in: query
      name: page
      schema:
        type: integer
    memberGuid:
      description: The unique id for a `member`.
      example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b
      in: path
      name: member_guid
      required: true
      schema:
        type: string
  schemas:
    InvestmentHoldingsDeactivation:
      properties:
        message:
          example: Successfully deactivated user from billing
        status:
          example: 200
    InvestmentHoldingResponseBody:
      properties:
        investment_holding:
          $ref: '#/components/schemas/InvestmentHoldingResponse'
      type: object
    InvestmentHoldingsResponseBody:
      properties:
        investment_holdings:
          items:
            $ref: '#/components/schemas/InvestmentHoldingResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      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
    InvestmentHoldingResponse:
      properties:
        account_guid:
          example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
          nullable: true
          type: string
        cost_basis:
          example: 827
          nullable: true
          type: number
        coupon_yield:
          example: null
          nullable: true
          type: string
        currency_code:
          example: USD
          nullable: true
          type: string
        current_price:
          example: 15
          nullable: true
          type: number
        daily_change:
          example: 2.5
          nullable: true
          type: number
        description:
          example: Guggenheim Defensive Equity ETF
          nullable: true
          type: string
        expiration:
          example: null
          nullable: true
          type: string
        face_value:
          example: null
          nullable: true
          type: number
        frequency:
          example: null
          nullable: true
          type: string
        guid:
          example: HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2
          nullable: true
          type: string
        market_value:
          example: 989.5
          nullable: true
          type: number
        maturity_date:
          example: null
          nullable: true
          type: string
        percentage_change:
          example: 0.2
          nullable: true
          type: number
        purchase_price:
          example: 26.3
          nullable: true
          type: number
        quantity:
          example: '5000.0'
          nullable: true
          type: string
        rate:
          example: null
          nullable: true
          type: number
        strike_price:
          example: null
          nullable: true
          type: number
        symbol:
          example: DEF
          nullable: true
          type: string
        term:
          example: null
          nullable: true
          type: string
        today_ugl_amount:
          example: 200
          nullable: true
          type: number
        today_ugl_percentage:
          example: 0.27
          nullable: true
          type: number
        total_ugl_amount:
          example: 20000
          nullable: true
          type: number
        total_ugl_percentage:
          example: 26.67
          nullable: true
          type: number
        unvested_quantity:
          example: null
          nullable: true
          type: number
        unvested_value:
          example: null
          nullable: true
          type: number
        user_guid:
          example: USR-743e5d7f-1116-28fa-5de1-d3ba02e41d8d
          nullable: true
          type: string
        vested_quantity:
          example: null
          nullable: true
          type: number
        vested_value:
          example: null
          nullable: true
          type: number
        created_at:
          example: '2015-04-13T18:01:23.000Z'
          nullable: true
          type: string
        current_price_as_of:
          example: '2023-11-06T00:00:00Z'
          nullable: true
          type: string
        issue_date:
          example: '2015-08-15'
          nullable: true
          type: string
        vesting_start_date:
          example: null
          nullable: true
          type: string
        vesting_end_date:
          example: null
          nullable: true
          type: string
        put_or_call:
          example: null
          nullable: true
          type: string
        holding_type:
          example: MUTUAL_FUND
          nullable: true
          type: string
        term_unit:
          example: null
          nullable: true
          type: string
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      scheme: basic
      type: http