MX investment holdings 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 investment holdings API
  version: '20250224'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: investment holdings
  description: 'Investment Data Enhancement lets you connect to an end user''s financial institution and retrieve cleansed and enhanced investment data. By combining investment data with retail banking information, you get comprehensive insights into customer financial behaviors, risk tolerance, and investment strategies.


    You can [read a user''s holding](docs.mx.com/api-reference/platform-api/reference/read-holding), [list all their holdings](docs.mx.com/api-reference/platform-api/reference/list-holdings), or list their holdings by [account](docs.mx.com/api-reference/platform-api/reference/list-holdings-by-account) or [member](docs.mx.com/api-reference/platform-api/reference/list-holdings-by-member).


    You can also [deactivate a user](docs.mx.com/api-reference/platform-api/reference/deactivate-user) from the Investment Data Enhancement. This is non-billable.

    '
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/acceptVersion'
      - $ref: '#/components/parameters/memberGuid'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/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/acceptVersion'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/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/acceptVersion'
      - $ref: '#/components/parameters/holdingGuid'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/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/acceptVersion'
      - $ref: '#/components/parameters/accountGuid'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/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/acceptVersion'
      - $ref: '#/components/parameters/userGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestmentHoldingsDeactivation'
          description: OK
      summary: Deactivate user from Investment Holdings
      tags:
      - investment holdings
components:
  parameters:
    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
    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
    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
    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
    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
  schemas:
    InvestmentHoldingsResponseBody:
      properties:
        investment_holdings:
          items:
            $ref: '#/components/schemas/InvestmentHoldingResponse'
          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
    InvestmentHoldingResponse:
      properties:
        account_guid:
          description: The unique identifier for an account. Defined by MX.
          example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1
          type: string
        cost_basis:
          description: The original value of an asset for tax purposes, usually the purchase price, used to calculate capital gains or losses. Accumulated price.
          example: 827
          type:
          - number
          - 'null'
        coupon_yield:
          description: The rate of return the bonds coupon rate generates.
          example: null
          type:
          - string
          - 'null'
        currency_code:
          description: The three-character ISO 4217 currency code, for example, `USD`.
          example: USD
          type:
          - string
          - 'null'
        current_price:
          description: The present market price of a single unit of the holding (for example, stock price per share).
          example: 15
          type:
          - number
          - 'null'
        daily_change:
          description: The daily change in the `current_price` of the holding since the previous trading day.
          example: 2.5
          type:
          - number
          - 'null'
        description:
          description: A brief description of the holding, such as the company name for stocks or the bond type for bonds.
          example: Guggenheim Defensive Equity ETF
          type:
          - string
          - 'null'
        expiration:
          description: The expiration date associated with the holding.
          example: null
          type:
          - string
          - 'null'
        face_value:
          description: The nominal value of a bond or fixed-income security, paid to the holder at maturity.
          example: 1000
          type:
          - number
          - 'null'
        frequency:
          description: The frequency of the interest paid on the bond (i.e. Annually, Monthly, etc.)
          example: ANNUALLY
          type:
          - string
          - 'null'
        guid:
          description: The unique identifier for the holding. Defined by MX.
          example: HOL-d65683e8-9eab-26bb-bcfd-ced159c9abe2
          type:
          - string
          - 'null'
        market_value:
          description: The current market value of the holding, calculated as the current price times the number of units (shares) owned.
          example: 989.5
          type:
          - number
          - 'null'
        maturity_date:
          description: The maturity date associated with the holding.
          example: null
          type:
          - string
          - 'null'
        percentage_change:
          description: The percent change in the `current_price` of the holding compared to a previous time period. It is the percentage change that reflects the `daily_change`.
          example: 0.2
          type:
          - number
          - 'null'
        purchase_price:
          description: The average price paid for the holding.
          example: 26.3
          type:
          - number
          - 'null'
        quantity:
          description: The number of units of the holding owned (for example, number of shares of stock).
          example: '5000.0'
          type:
          - string
          - 'null'
        rate:
          description: The interest on the bond, subject to determining the payout amount of the bond.
          example: null
          type:
          - number
          - 'null'
        strike_price:
          description: The strike price associated to the option.
          example: null
          type:
          - number
          - 'null'
        symbol:
          description: The ticker symbol or unique identifier of the holding, used in stock exchanges.
          example: DEF
          type:
          - string
          - 'null'
        term:
          description: The length of time until the bond's principal amount is due to be repaid. It is the period from when the bond is issued until it reaches its maturity date.
          example: null
          type:
          - string
          - 'null'
        today_ugl_amount:
          description: The unrealized gain/loss amount for today.
          example: 200
          type:
          - number
          - 'null'
        today_ugl_percentage:
          description: The unrealized gain/loss percentage for today.
          example: 0.27
          type:
          - number
          - 'null'
        total_ugl_amount:
          description: The total unrealized gain/loss amount for an investment.
          example: 20000
          type:
          - number
          - 'null'
        total_ugl_percentage:
          description: The total unrealized gain/loss for the holding since it was acquired.
          example: 26.67
          type:
          - number
          - 'null'
        unvested_quantity:
          description: The number of units (for example, shares) of the holding that are not yet vested or owned outright by the holder.
          example: null
          type:
          - number
          - 'null'
        unvested_value:
          description: The value of the portion of the holding that is unvested.
          example: null
          type:
          - number
          - 'null'
        user_guid:
          description: The unique identifier for the user. Defined by MX.
          example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
          type:
          - string
          - 'null'
        vested_quantity:
          description: The number of units (for example, shares) of the holding that are vested and fully owned by the holder.
          example: null
          type:
          - number
          - 'null'
        vested_value:
          description: The value of the portion of the holding that is vested and fully owned by the holder.
          example: null
          type:
          - number
          - 'null'
        created_at:
          description: The date and time the investment holding was created, represented in ISO 8601 format with a timestamp.
          example: '2025-02-13T18:08:00+00:00'
          type:
          - string
          - 'null'
        current_price_as_of:
          description: The date and time when the current price was last updated, represented in ISO 8601 format with a timestamp.
          example: '2023-11-06T00:00:00Z'
          type:
          - string
          - 'null'
        issue_date:
          description: The date on which a security was issued or made available for sale.
          example: '2015-08-15'
          type:
          - string
          - 'null'
        vesting_start_date:
          description: The date from which the vesting schedule for a holding begins.
          example: null
          type:
          - string
          - 'null'
        vesting_end_date:
          description: The date from which the vesting schedule for a holding ends.
          example: null
          type:
          - string
          - 'null'
        put_or_call:
          description: States whether the option is a `PUT` or `CALL`.
          example: null
          type:
          - string
          - 'null'
        holding_type:
          description: The type of investment (e.g., equity, fixed income, mutual fund, etc.)
          example: MUTUAL_FUND
          type:
          - string
          - 'null'
        term_unit:
          description: The unit type of the term associated to the bond. (Year, Month, etc.)
          example: null
          type:
          - string
          - 'null'
      type: object
    InvestmentHoldingsDeactivation:
      properties:
        message:
          example: Successfully deactivated user from billing
        status:
          example: 200
    InvestmentHoldingResponseBody:
      properties:
        investment_holding:
          $ref: '#/components/schemas/InvestmentHoldingResponse'
      type: object
  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