openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Holders API
  description: Allow clients to fetch precalculated Analytics through predeterministic URLs.
  contact:
    name: FactSet Research Systems
    url: https://developer.factset.com/contact
    email: api@factset.com
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
servers:
- url: https://api.factset.com
  description: Production
- url: https://api-sandbox.factset.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Holders
paths:
  /factset-ownership/v1/security-holders:
    get:
      tags:
      - Holders
      summary: Factset Get Security Ownership Data for Requested Security Identifers.
      operationId: getSecurityHolders
      description: 'Gets security ownership details and activity for the requested security identifiers. The services allows filtering by "Topn" holders and by holder "type", such as Institutions, Insiders, and Stakeholders.

        '
      parameters:
      - $ref: '#/components/parameters/idHolders'
      - $ref: '#/components/parameters/holderType'
      - $ref: '#/components/parameters/topn'
      - $ref: '#/components/parameters/requestedDate'
      - $ref: '#/components/parameters/currency'
      responses:
        '200':
          description: Security Holders Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/securityHoldersResponse'
              examples:
                Single identifier request for Top 1 holder of FDS-US securities as of 2020-06-31:
                  $ref: '#/components/examples/singleSecurityHolder'
                Top 5 Insiders and Stakeholders of TSLA-US as of 2020-02-14:
                  $ref: '#/components/examples/insiderTop5Holders'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Holders
      summary: Factset Get Security Ownership Data for a List of Requested Securities.
      description: 'Gets security ownership details and activity for the requested security identifiers. The services allows filtering by "Topn" holders and by holder "type", such as Institutions, Insiders, and Stakeholders.

        '
      operationId: postSecurityHolders
      requestBody:
        required: true
        description: Requesting Security Holders for a list of Fund Identifiers.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/securityHoldersRequest'
            examples:
              Request the Top Institutional holder of FDS-US as of 2020-06-30:
                $ref: '#/components/examples/singleSecurityHolderPostRequest'
              Request Latest Top 5 Insiders for TSLA-US:
                $ref: '#/components/examples/top5InsidersRequest'
      responses:
        '200':
          description: Security Holders Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/securityHoldersResponse'
              examples:
                Single identifier request for Top 1 holder of FDS-US securities as of 2020-06-30:
                  $ref: '#/components/examples/singleSecurityHolder'
                Top 5 Insiders and Stakeholders of TSLA-US as of 2020-02-14:
                  $ref: '#/components/examples/insiderTop5Holders'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /holders:
    get:
      tags:
      - Holders
      operationId: getOwnershipHolders
      summary: Factset Holders of a Company or Fund
      description: Holders of a company or fund
      parameters:
      - name: id
        in: query
        description: Company or Fund Identifier
        required: true
        schema:
          type: string
          example: FDS
      - name: asset_type
        in: query
        description: Controls the Asset Type of the data returned
        required: false
        schema:
          type: string
          enum:
          - EQUITY
          - DEBT
          default: EQUITY
      - name: holder_type
        in: query
        description: Controls the Holder Type of the data returned
        required: false
        schema:
          type: string
          enum:
          - ALL_HOLDERS
          - BENEFICIAL_OWNERS
          - FUNDS
          - INSTITUTIONS
          - INSTITUTIONS_INSIDERS
          - INSIDERS_STAKEHOLDERS
          default: INSTITUTIONS
      - name: topn
        in: query
        description: "Limits the number of holders returned based on their Market Value position in the security.  \nDefault is ALL, otherwise use a valid number above 0.\n"
        schema:
          type: string
          example: ALL
      - name: date
        in: query
        description: Top Holders as of date expressed in YYYY-MM-DD format. Defaults to latest month-end close; non-month-end dates are converted to month-end dates.
        required: false
        schema:
          type: string
          example: '2019-12-31'
      responses:
        '200':
          $ref: '#/components/responses/200OKStach'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Meta:
      type: object
      additionalProperties:
        type: string
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
          example: []
        meta:
          $ref: '#/components/schemas/Meta'
    holderType:
      type: string
      enum:
      - F
      - M
      - S
      - FS
      - B
      default: F
      description: "Controls the Holder Type of the data returned. By default, the service will return Institutional Holders. Requesting All Holders is not currently supported. Only a single Holder Type is allowed per request.\n  * **F** = Institutions\n  * **M** = Mutual Funds\n  * **S** =  Insiders/Stakeholders\n  * **FS** = Institutions/Insiders\n  * **B** = Beneficial Owners\n"
    Response:
      type: object
      properties:
        data:
          title: STACH
          description: Returns a STACH 2.0 row organized package
          example: example_value
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorObject:
      type: object
      properties:
        id:
          type: string
          example: abc123
        code:
          type: string
          example: example_value
        title:
          type: string
          example: Example Title
        links:
          type: object
          properties:
            about:
              type: string
          example: example_value
        detail:
          type: string
          example: example_value
        source:
          type: object
          properties:
            parameter:
              type: string
          example: example_value
    idHolders:
      description: Security Requested for Holders information.
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 1
      example:
      - FDS-US
    requestedDate:
      description: Date of holdings expressed in YYYY-MM-DD format.
      type: string
      example: '2019-09-30'
    securityHoldersRequest:
      title: Security Holders Request
      description: Security Holders Request
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/idHolders'
        holderType:
          $ref: '#/components/schemas/holderType'
        date:
          $ref: '#/components/schemas/requestedDate'
        topn:
          $ref: '#/components/schemas/topn'
        currency:
          $ref: '#/components/schemas/currency'
      required:
      - ids
    securityHoldersResponse:
      title: Security Holders Response
      type: object
      description: securityHolders response
      properties:
        data:
          description: Array of Security Holders
          type: array
          items:
            $ref: '#/components/schemas/securityHolders'
          example: []
    securityHolders:
      title: Security Holders
      description: Security Holders response object
      type: object
      properties:
        holderId:
          description: FactSet Ownership Holders ID that corresponds to the requested security holder.
          type: string
          example: M4004630
          nullable: true
        fsymId:
          description: FactSet Security Identifier of security requested. This does not represent the FactSet permanent identifier for the holder, but rather the requested id. Six alpha-numeric characters, excluding vowels, with an -S suffix (XXXXXX-S). All equity and fixed income securities that exist on FactSet are allocated a security-level permanent identifier.
          type: string
          example: SQFMK3-R
          nullable: true
        holderEntityId:
          description: FactSet Entity ID that corresponds to the specified holder ID.
          type: string
          example: 07JGQN-E
          nullable: true
        holderName:
          description: Name of the holder for the requested security identifier.
          type: string
          example: Vanguard Total Stock Market Index Fund
          nullable: true
        date:
          description: 'Date of the reported holding in YYYY-MM-DD format. For more details regarding date resolution, visit [Online Assistant Page #11262](https://oa.apps.factset.com/pages/11262).'
          type: string
          format: date
          example: '2020-06-30'
          nullable: true
        currency:
          description: 'Currency code. The service will default to the local currency if the currency is not requested. For a list of currency ISO codes, visit [Online Assistant Page #1470](https://oa.apps.factset.com/pages/1470).'
          type: string
          example: USD
          nullable: true
        investorType:
          description: 'FactSet Ownership Institution, Mutual Fund, and Insider/Stakeholder investor types. To learn more about the different investor types, visit [Online Assistant Page #11656](https://my.apps.factset.com/oa/pages/11656).'
          type: string
          example: Open-End Fund
          nullable: true
        holderType:
          description: 'Holder Type name of the respective holder object. The name will align to the holderType requested. '
          type: string
          example: Mutual Fund
          nullable: true
        adjHolding:
          description: 'Adjusted number of shares held. All positions and prices are adjusted for splits and name changes, but they are not adjusted for spinoffs or mergers. If a given company announces a split today, FactSet''s Ownership data will reflect that split either tomorrow or the day after, depending upon the time in which the FactSet Symbology team makes record of the change. For more details, visit [Online Assistant Page #11262](https://oa.apps.factset.com/pages/11262).'
          type: number
          format: double
          example: 1066876
          nullable: true
        adjMarketValue:
          description: 'Adjusted market values of shares held. Market Value. All positions and prices are adjusted for splits and name changes, but they are not adjusted for spinoffs or mergers. If a given company announces a split today, FactSet''s Ownership data will reflect that split either tomorrow or the day after, depending upon the time in which the FactSet Symbology team makes record of the change. For more details, visit [Online Assistant Page #11262](https://oa.apps.factset.com/pages/11262).'
          type: number
          format: double
          example: 373833350.4
          nullable: true
        weightClose:
          description: '"Closing weight of the security for the holders of the requested security (percent). To learn more about how ownership weight is calculated please visit [Online Assistant Page #11247](https://my.apps.factset.com/oa/pages/11247)."

            '
          type: number
          format: double
          example: 0.0356
          nullable: true
        percentOutstanding:
          description: 'The percent of the outstanding common shares held by a particular filing institution. To learn more, visit [Online Assistant Page #11041](https://my.apps.factset.com/oa/pages/11041).'
          type: number
          format: double
          example: 2.808
          nullable: true
        source:
          description: Either the 13F Form or ND-30D report filed where the security holdings data was sourced from. To learn more about source, please visit https://my.apps.factset.com/oa/pages/11260
          type: string
          example: US Fund (N-30D)
          nullable: true
        requestId:
          description: 'Security Identifier that was used in the request.

            '
          type: string
          example: FDS-US
    errorResponse:
      type: object
      description: error description
      title: Error Response
      properties:
        status:
          description: status
          type: string
          example: Bad Request
        timestamp:
          description: timestamp in YYYY-MM-DD HH:MM:SS.SSS
          type: string
          example: '2019-11-01 11:09:41.918'
          format: date-time
        path:
          description: The Endpoint path {package}/version/{endpoint}
          type: string
          example: /factset-ownership/v1/{end-point}
        message:
          description: The plain text error message
          type: string
          example: Validation Error
        subErrors:
          description: subErrors related to the error message. Null if not applicable.
          type: object
          properties:
            object:
              description: the operation ID
              type: string
            field:
              description: Parameter Field Name
              type: string
            message:
              description: Error message
              type: string
            rejectedValue:
              description: Rejected Values in an Array
              type: array
              items:
                type: string
          example: example_value
    topn:
      description: Limits number of holdings or holders displayed by the top *n* securities. Default is ALL, or use integer to limit number.
      type: string
      default: ALL
      example: 5
    currency:
      description: Currency code for adjusting prices. Default is Local. For a list of currency ISO codes, visit [Online Assistant Page 1470](https://oa.apps.factset.com/pages/1470).
      type: string
      example: USD
  examples:
    top5InsidersRequest:
      summary: Requesting the latest available top 5 insiders and stakeholders for TSLA-US
      description: Requesting the latest available top 5 insiders and stakeholders for TSLA-US
      value:
        ids:
        - TSLA-US
        topn: 5
        holderType: S
    badRequestInvalidParameters:
      summary: Bad Request - Invalid Parameters
      description: This error message occurs when a request parameter is used in which is not recognized by the service. Please revise your request to include only the parameters listed in the specification. Typical causes are spelling mistakes and use of improper casing.
      value:
        status: Bad Request
        timestamp: '2020-08-03 12:02:47.804'
        path: /factset-ownership/v1/{end-point}
        message: 'Invalid Parameter (s): dated. Please modify your request to use parameters outlined in the specification for this endpoint.'
        subErrors: null
    parameterErrorTopn:
      summary: topn parameter error
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: parameterError
          title: 'Invalid parameter: ''topn'''
    badRequestDateFormat:
      summary: Bad Request - Date Format
      description: This bad request occurs when a request doesn't use the YYYY-MM-DD in the date parameters. To resolve, convert your date to YYYY-MM-DD.
      value:
        status: Bad Request
        timestamp: '2020-08-03 12:00:31.777'
        path: /factset-ownership/v1/{end-point}
        message: 'The date parameter(s) must be in the following date format: YYYY-MM-DD. '
        subErrors: null
    notWritable:
      summary: Internal Server Error - Not Writable
      description: This error may be returned when the server encounters an error writing the JSON response.
      value:
        status: Internal Server Error
        timestamp: '2019-11-05 09:48:29.18'
        path: /factset-ownership/v1/{endpoint}
        message: Error writing JSON output
        subErrors: null
    notAuthorized:
      summary: not authorized
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: notAuthorized
          title: User is forbidden access with current credentials. For access, contact your FactSet sales representative
    parameterErrorAssetType:
      summary: asset type parameter error
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: parameterError
          title: 'Invalid parameter: ''asset_type'''
    default200Response:
      summary: (dummy data - equity holders)
      value:
        data:
          version: '2.0'
          tables:
            main:
              definition:
                columns:
                - id: holderName
                  type: string
                  isDimension: true
                - id: pctowns
                  type: real
                - id: position
                  type: real
                - id: postionchg
                  type: real
                - id: adj_mv
                  type: real
                - id: pcprt
                  type: real
                - id: actscore
                  type: string
                - id: reportdate
                  type: string
                - id: source
                  type: string
              headersDefinition:
                columns:
                - id: ownershipTableHeader
                  type: string
                  isDimension: true
              data:
                rows:
                - rowType: Header
                  cells:
                  - All Holders
                  - '%OS'
                  - Position (000)
                  - Pos Change (000)
                  - Mkt Val (MM)
                  - '% Port'
                  - Activism
                  - Report Date
                  - Source
                  headerCellDetails:
                    '0':
                      source: HEADERS
                      columnIndex: 0
                    '1':
                      source: HEADERS
                      columnIndex: 0
                    '2':
                      source: HEADERS
                      columnIndex: 0
                    '3':
                      source: HEADERS
                      columnIndex: 0
                    '4':
                      source: HEADERS
                      columnIndex: 0
                    '5':
                      source: HEADERS
                      columnIndex: 0
                    '6':
                      source: PRIMARY
                      columnIndex: 0
                    '7':
                      source: HEADERS
                      columnIndex: 0
                    '8':
                      source: HEADERS
                      columnIndex: 0
                - cells:
                  - The Vanguard Group, Inc.
                  - 9.8903
                  - 3757653
                  - -115462
                  - 1252876663.26
                  - 0.023711
                  - Very Low
                  - '2020-06-30'
                  - 13F Form
                  rowMetadata:
                    fsymId:
                      value: F72998
                - cells:
                  - ' Vanguard Total Stock Market Index Fund'
                  - 2.8321
                  - 1076021
                  - -17151
                  - 358766921.82
                  - 0.037892
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4004630'
                - cells:
                  - ' Vanguard Mid Cap Index Fund'
                  - 2.4459
                  - 929269
                  - -40861
                  - 309836869.98
                  - 0.273436
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4005398'
                - cells:
                  - ' Vanguard Extended Market Index Fund'
                  - 1.4185
                  - 538950
                  - 2048
                  - 179696709
                  - 0.239476
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4004539'
                - cells:
                  - ' Vanguard Growth Index Fund'
                  - 0.7859
                  - 298593
                  - 11429
                  - 99556878.06
                  - 0.075905
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4004567'
                - cells:
                  - ' Vanguard Dividend Appreciation Index Fund'
                  - 0.6763
                  - 256945
                  - -85496
                  - 85670601.9
                  - 0.151329
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4048126'
                - cells:
                  - ' Vanguard Mid Cap Growth Index Fund'
                  - 0.6734
                  - 255852
                  - -6960
                  - 85306173.84
                  - 0.500536
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4048682'
                - cells:
                  - ' Vanguard Financials Index Fund'
                  - 0.1994
                  - 75747
                  - 1346
                  - 25255564.74
                  - 0.377082
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4039461'
                - cells:
                  - ' Vanguard S&P Mid Cap 400 Index Fund'
                  - 0.1224
                  - 46523
                  - 114
                  - 15511698.66
                  - 0.74321
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4107013'
                - cells:
                  - ' Vanguard Strategic Equity Fund'
                  - 0.122
                  - 46359
                  - -2294
                  - 15457017.78
                  - 0.244843
                  - null
                  - '2020-06-30'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4007901'
                - cells:
                  - ' Vanguard Institutional Total Stock Market Index Fund'
                  - 0.1212
                  - 46046
                  - -1508
                  - 15352657.32
                  - 0.037833
                  - null
                  - '2020-07-31'
                  - US Fund (N-30D)
                  rowMetadata:
                    fsymId:
                      value: ' M4017307'
                columnMetadata:
                  pctowns:
                    items:
                      valueType:
                        value: PERCENTAGE
                  position:
                    items:
                      scale:
                        value: 3
                  postionchg:
                    items:
                      scale:
                        value: 3
                  adj_mv:
                    items:
                      scale:
                        value: 6
                      currencyCode:
                        value: USD
                      currencySymbol:
                        value: $
                  pcprt:
                    items:
                      valueType:
                        value: PERCENTAGE
        meta:
          requestId: FDS-US
          fsymId: SQFMK3-R
    unsupportedMediaType:
      summary: Unsupported Media Type
      description: This bad request occurs when the media type passed in the request is not supported. Currently the APIs only support 'application/json'.
      value:
        status: Unsupported Media Type
        timestamp: '2019-11-05 09:42:27.237'
        path: /factset-ownership/v1/{endpoint}
        message: text/html media type is not supported. Supported media types are application/json
        subErrors: null
    generalException:
      summary: Internal Server Error - General Exception
      description: This is the most general error that can be returned to by the service. Please `Report Issue` to FactSet.
      value:
        status: Internal Server Error
        timestamp: '2019-11-01 10:36:01.944'
        path: /factset-ownership/v1/{endpoint}
        message: Unexpected error
        subErrors: null
    badRequestReadTimeout:
      summary: Bad Request - Read Timeout
      description: This error may be returned if it takes more than 29 seconds to hear back from the data fetch service.
      value:
        status: Bad Request
        timestamp: '2019-11-04 16:18:38.949'
        path: /factset-ownership/v1/{end-point}
        message: The request took too long. Try again with a smaller request.
        subErrors: null
    parameterErrorDate:
      summary: date parameter error
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: parameterError
          title: 'Invalid parameter: ''date'''
    idInvalidParameterError:
      summary: generic parameter error (invalid parameter)
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: parameterError
          title: 'Invalid parameter(s): ''id'''
    badRequestFutureDate:
      summary: Bad Request - Future Date
      description: This error message occurs when a future date is requested in the date parameters. Please revise your request to include dates as of today's current date or any prior historical date.
      value:
        status: Bad Request
        timestamp: '2020-08-03 12:02:06.097'
        path: /factset-ownership/v1/{end-point}
        message: 'The use of future dates for date parameter(s) is not applicable. Please revise your request to include dates up to today''s current date. '
        subErrors: null
    forbidden:
      summary: Forbidden
      description: The USERNAME-SERIAL attempted to request the endpoint is not authorized to access. The request was a legal request, but the server is refusing to respond. Please reach out to FactSet Account Team for assistance with authorization.
      value:
        status: Forbidden
        timestamp: '2020-06-12 16:08:51.731'
        path: /factset-ownership/v1/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-ownership/v1/{endpoint}
        subErrors: null
    unauthenticated:
      summary: User Authentication Failed
      description: This occurs when a user is not properly authenticated or recognized by the service. Please double check the USERNAME-SERIAL and API-Key used to request and ensure you are within the IP range specified for the Key. Report Issue under 401 error for help with troubleshooting.
      value:
        status: User Authentication Failed
        timestamp: '2019-10-31 16:08:07.945'
        path: /factset-ownership/v1/{endpoint}
        message: User Authentication Failed.
        subErrors: null
    endpointNotFound:
      summary: endpoint not found
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: endpointNotFound
          title: The requested endpoint does not exist.
    debtHolders200Response:
      summary: (dummy data- debt holders)
      value:
        data:
          version: '2.0'
          tables:
            main:
              definition:
                columns:
                - id: holderName
                  type: string
                  isDimension: true
                - id: pctowns
                  type: real
                - id: position
                  type: real
              headersDefinition:
                columns:
                - id: ownershipTableHeader
                  type: string
                  isDimension: true
              data:
                rows:
                - rowType: Header
                  cells:
                  - Institutions
                  - '%OS'
                  - Position (MM)
                  headerCellDetails:
                    '0':
                      source: HEADERS
                      columnIndex: 0
                    '1':
                      source: HEADERS
                      columnIndex: 0
                    '2':
                      source: HEADERS
                      columnIndex: 0
                - cells:
                  - The Vanguard Group, Inc.
                  - 6.590663
                  - 4094.054
                  rowMetadata:
                    fsymId:
                      value: F72998
                - cells:
                  - Pacific Investment Management Co. LLC
                  - 5.969819
                  - 3708.391636
                  rowMetadata:
                    fsymId:
                      value: F5017088
                - cells:
                  - Lord, Abbett & Co. LLC
                  - 2.032207
                  - 1262.386837
                  rowMetadata:
                    fsymId:
                      value: F20448
                - cells:
                  - Capital Research & Management Co. (Fixed Income Investors)
                  - 1.628714
                  - 1011.741
                  rowMetadata:
                    fsymId:
                      value: F12947256
                - cells:
                  - Capital Research & Management Co. (World Investors)
                  - 1.605221
                  - 997.147
                  rowMetadata:
                    fsymId:
                      value: F6158007
                - cells:
                  - BlackRock Fund Advisors
                  - 1.502151
                  - 933.121
                  rowMetadata:
                    fsymId:
                      value: F7749421
                - cells:
                  - PGIM, Inc.
                  - 1.331821
                  - 827.314
                  rowMetadata:
                    fsymId:
                      value: F24891
                - cells:
                  - Western Asset Management Co. LLC
                  - 1.084589
                  - 673.736
                  rowMetadata:
                    fsymId:
                      value: F5112696
                - cells:
                  - Fidelity Management & Research Co. LLC
                  - 0.966759
                  - 600.540811
                  rowMetadata:
                    fsymId:
                      value: F16925
                - cells:
                  - Loomis, Sayles & Co. LP
                  - 0.923711
                  - 573.8
                  rowMetadata:
                    fsymId:
                      value: F20445
                columnMetadata:
                  pctowns:
                    items:
                      valueType:
                        value: PERCENTAGE
                  position:
                    items:
                      scale:
                        value: 6
                      currencyCode:
                        value: USD
                      currencySymbol:
                        value: $
        meta:
          requestId: BA-US
          fsymId: RXHN9P-R
    badRequestMalformedJSON:
      summary: Bad Request - Malformed JSON Request
      description: This error may be returned when the request body is specified as JSON, but is not in proper JSON format.
      value:
        status: Bad Request
        timestamp: '2020-08-03 12:03:34.409'
        path: /factset-ownership/v1/{end-point}
        message: Malformed JSON Request
        subErrors: null
    genericServerError:
      summary: generic server error
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: genericServerError
          title: Unexpected error processing request
    insiderTop5Holders:
      summary: Top 5 Institution holders for FDS-US as of 2020-06-30.
      description: Top 5 Institution holders for FDS-US as of 2020-06-30.
      value:
        data:
        - adjHolding: 3757653,
          adjMarketValue: 1258362836.64,
          currency: USD
          date: '2020-06-30'
          fsymId: SQFMK3-R
          holderEntityId: 002FYS-E
          holderId: F72998
          holderName: The Vanguard Group, Inc.
          holderType: Institution
          investorType: Mutual Fund Manager
          percentOutstanding: 9.8903
          requestId: FDS-US
          source: 13F Form
          weightClose: 0.035
        - adjHolding: 3631561
          adjMarketValue: 1216137147.68
          currency: USD
          date: '2020-06-30'
          fsymId: SQFMK3-R
          holderEntityId: 08D3XB-E
          holderId: F7749421
          holderName: BlackRock Fund Advisors
          holderType: Institution
          investorType: Investment Adviser
          percentOutstanding: 9.5584
          requestId: FDS-US
          source: 13F Form
          weightClose: 0.054
        - adjHolding: 2763901
          adjMarketValue: 925575166.88
          currency: USD
          date: '2020-06-30'
          fsymId: SQFMK3-R
          holderEntityId: 0024SV-E
          holderId: F64196
          holderName: BAMCO, Inc.
          holderType: Institution
          investorType: Investment Adviser
          percentOutstanding: 7.2747
          requestId: FDS-US
          source: 13F Form
          weightClose: 2.4906
        - adjHolding: 2703592
          adjMarketValue: 905378888.96
          currency: USD
          date: '2020-06-30'
          fsymId: SQFMK3-R
          holderEntityId: 000P8J-E
          holderId: F20445
          holderName: Loomis, Sayles & Co. LP
          holderType: Institution
          investorType: Investment Adviser
          percentOutstanding: 7.1159
          requestId: FDS-US
          source: 13F Form
          weightClose: 1.2433
        - adjHolding: 1617050
          adjMarketValue: 541517704
          currency: USD
          date: '2020-06-30'
          fsymId: SQFMK3-R
          holderEntityId: 002HTZ-E
          holderId: F74802
          holderName: Kayne Anderson Rudnick Investment Management LLC
          holderType: Institution
          investorType: Investment Adviser
          percentOutstanding: 4.2561
          requestId: FDS-US
          source: 13F Form
          weightClose: 1.8401
    parameterErrorHolderType:
      summary: holder type parameter error
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: parameterError
          title: 'Invalid parameter: ''holder_type'''
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: parameterError
          title: holderType parameter value is invalid with assetType DEBT. Only holderType INSTITUTIONS or FUNDS are valid when returning assetType DEBT.
    singleSecurityHolderPostRequest:
      summary: Requesting the Top Institution Holder of FDS-US as of 2020-06-30.
      description: Requesting the Top Institution Holder of FDS-US as of 2020-06-30.
      value:
        ids:
        - FDS-US
        date: '2020-06-30'
        topn: 1
        holderType: F
        currency: USD
    badRequestRequiredParameter:
      summary: Bad Request - Required Parameter Missing
      description: This error message occurs when the request does not include the required parameters. Required parameters are indicated with a red asterisks symbol in the specification file.
      value:
        status: Bad Request
        timestamp: '2020-08-03 12:01:06.553'
        path: /factset-ownership/v1/{end-point}
        message: The parameter 'ids' is required and may not be empty.
        subErrors: null
    idRequiredParameterError:
      summary: generic parameter error (missing parameter)
      value:
        errors:
        - id: 39314614-e607-465a-ba95-5bb79c362e23
          code: parameterError
          title: 'Missing required parameter(s): ''id'''
    singleSecurityHolder:
      summary: The Top 5 Mutual Fund holder of FDS-US as of 2020-06-30.
      description: The Top 5 Mutual Fund Holder of FDS-US as of 2020-06-30. Since the request specified mutual fund as the holder type, the response will include the mutual fund and its related mutual funds. To request other holder types change the holderType parameter.
      value:
        data:
        - adjHolding: 1240000,
          adjMarketValue: 415251200,
          currency: USD
          date: '2020-08-31'
          fsymId: SQFMK3-R
          holderEntityId: 04B8QD-E
          holderId: M4000376
          holderName: Baron Growth Fund
          holderType: Mutual Fund
          investorType: Open-End Fund
          percentOutstanding: 3.2637
          requestId: FDS-US
          source: US Fund (N-30D)
          weightClose: 5.6182
        - adjHolding: 1064539
          adjMarketValue: 356492820.32
          currency: USD
          date: '2020-09-30'
          fsymId: SQFMK3-R
          holderEntityId: 04BF4M-E
          holderId: M4004630
          holderName: Vanguard Total Stock Market Index Fund
          holderType: Mutual Fund
          investorType: Open-End Fund
          percentOutstanding: 2.8019
          requestId: FDS-US
          source: US Fund (N-30D)
          weightClose: 0.0382
        - adjHolding: 998453
          adjMarketValue: 334361940.64
          currency: USD
          date: '2020-09-30'
          fsymId: SQFMK3-R
          holderEntityId: 04BHCW-E
          holderId: M4006777
          holderName: iShares Core S&P Mid Cap ETF
          holderType: Mutual Fund
          investorType: Exchange Traded Fund
          percentOutstanding: 2.628
          requestId: FDS-US
          source: US Fund (N-30D)
          weightClose: 0.7701
        - adjHolding: 876793
          adjMarketValue: 293620439.84
          currency: USD
          date: '2020-09-30'
          fsymId: SQFMK3-R
          holderEntityId: 04BFYD-E
          holderId: M4005398
          holderName: Vanguard Mid Cap Index Fund
          holderType: Mutual Fund
          investorType: Open-End Fund
          percentOutstanding: 2.3077
          requestId: FDS-US
          source: US Fund (N-30D)
          weightClose: 0.2607
        - adjHolding: 728381
          adjMarketValue: 243920229.28
          currency: USD
          date: '2020-03-31'
          fsymId: SQFMK3-R
          holderEntityId: 04BSJN-E
          holderId: M4015574
          holderName: Morgan Stanley Invt. Fds. - Global Brands Fund
          holderType: Mutual Fund
          investorType: Open-End Fund
          percentOutstanding: 1.9171
          requestId: FDS-US
          source: Non-US portfolio
          weightClose: 1.4245
    noData200Response:
      summary: (debt holders - no data case)
      value:
        data:
          version: '2.0'
          tables:
            main:
              definition:
                columns:
                - id: holderName
                  type: string
                  isDimension: true
                - id: pctowns
                  type: real
                - id: position
                  type: real
              headersDefinition:
                columns:
                - id: ownershipTableHeader
                  type: string
                  isDimension: true
              data:
                rows:
                - rowType: Header
                  cells:
                  - Institutions
                  - '%OS'
                  - Position (MM)
                  headerCellDetails:
                    '0':
                      source: HEADERS
                      columnIndex: 0
                    '1':
                      source: HEADERS
                      columnIndex: 0
                    '2':
                      source: HEADERS
                      columnIndex: 0
                - cells:
                  - null
                  - null
                  - null
                  rowMetadata:
                    fsymId:
                      value: '@NA'
                columnMetadata:
                  pctowns:
                    items:
                      valueType:
                        value: PERCENTAGE
                  position:
                    items:
                      scale:
                        value: 6
                      currencyCode:
                        value: USD
                      currencySymbol:
                        value: $
        meta:
          requestId: YELP-US
          fsymId: DT59Y2-R
          noData: true
          message: There is no data for this request.
  responses:
    '401':
      description: Unauthenticated USERNAME-SERIAL. Ensure you are logged in and have successfully generated an API KEY for the IP range you are connecting from. For more help, select the **Report Issue** in the top right corner of this Developer Portal specification card and choose Connectivity 401 or 403 Responses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/unauthenticated'
    401Unauthorized:
      description: Missing or invalid authentication. Ensure you are logged in and have successfully generated an API KEY for the IP range you are connecting from. For further assistance, file an issue under "Connectivty - 401 or 403 Responses" using `Report Issue` at the top of this page, including the X-DataDirect-Request-Key from the header to assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
    '415':
      description: Unsupported Media Type. This error may be returned when the caller sends a resource in a format that is not accepted by the server. This can be fixed by ensuring that Content-Type header is set to the correct value. In this instance, "application/json" would be the appropriate value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/unsupportedMediaType'
    429TooManyRequests:
      description: Too many requests - this API is rate-limited to 20 requests per second. For further assistance, file an issue under "Workflow & Throttling - 400 or 429 Response" using `Report Issue` at the top of this page, including the X-DataDirect-Request-Key from the header to assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
    '403':
      description: The USERNAME-SERIAL attempted to request the endpoint is not authorized to access. The request was a legal request, but the server is refusing to respond. Please reach out to FactSet Account Team for assistance with authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/forbidden'
    200OKStach:
      description: Expected response; returns JSON data containing STACH 2.0 row organized package format
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
        Api-Supported-Versions:
          schema:
            type: string
          description: Supported API versions (semantic versioning)
        Api-Version:
          schema:
            type: string
          description: API version (semantic versioning)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response'
          examples:
            default200ResponseExample:
              $ref: '#/components/examples/default200Response'
            debtHolders200ResponseExample:
              $ref: '#/components/examples/debtHolders200Response'
            noData200ResponseExample:
              $ref: '#/components/examples/noData200Response'
    404NotFound:
      description: Not found. For further assistance, file an issue under "Performance - 404 and 500 Responses" using `Report Issue` at the top of this page, including the X-DataDirect-Request-Key from the header to assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            endpointNotFound:
              $ref: '#/components/examples/endpointNotFound'
    '400':
      description: Bad Request. This can occur for several reasons. Please review the "message" for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/badRequestDateFormat'
            Bad Request - Missing Required Parameter:
              $ref: '#/components/examples/badRequestRequiredParameter'
            Bad Request - Future Date:
              $ref: '#/components/examples/badRequestFutureDate'
            Bad Request - Invalid Parameter:
              $ref: '#/components/examples/badRequestInvalidParameters'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/badRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/badRequestReadTimeout'
    403Forbidden:
      description: User is forbidden access with current credentials. Reach out to your local FactSet Account Manager for assistance, or file an issue under "Connectivty - 401 or 403 Responses" using `Report Issue` at the top of this page, including the X-DataDirect-Request-Key from the header to assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            notAuthorized:
              $ref: '#/components/examples/notAuthorized'
    503ServiceUnavailable:
      description: Service unavailable. Typically a timeout, or result of a rejected request to prevent service overload. For further assistance, file an issue under "Performance - 404 and 500 Responses" using `Report Issue` at the top of this page, including the X-DataDirect-Request-Key from the header to assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Internal Server Error - Not Writable:
              $ref: '#/components/examples/notWritable'
            Internal Server Error - General Exception:
              $ref: '#/components/examples/generalException'
    400BadRequest:
      description: Bad Request. For further assistance, file an issue under "Workflow & Throttling - 400 or 429 Response" using `Report Issue` at the top of this page, including the X-DataDirect-Request-Key from the header to assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
        Api-Supported-Versions:
          schema:
            type: string
          description: Supported API versions
        Api-Version:
          schema:
            type: string
          description: API version (semantic versioning)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            idRequiredParameterError:
              $ref: '#/components/examples/idRequiredParameterError'
            idInvalidParameterError:
              $ref: '#/components/examples/idInvalidParameterError'
            parameterErrorAssetType:
              $ref: '#/components/examples/parameterErrorAssetType'
            parameterErrorHolderType:
              $ref: '#/components/examples/parameterErrorHolderType'
            parameterErrorTopn:
              $ref: '#/components/examples/parameterErrorTopn'
            parameterErrorDate:
              $ref: '#/components/examples/parameterErrorDate'
    500InternalServerError:
      description: Server error. For further assistance, file an issue under "Performance - 404 and 500 Responses" using `Report Issue` at the top of this page, including the X-DataDirect-Request-Key from the header to assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            genericServerError:
              $ref: '#/components/examples/genericServerError'
  parameters:
    idHolders:
      name: ids
      description: Requested list of security identifiers. <p>***ids limit** =  1 per request*</p>.
      in: query
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 1
      required: true
      explode: false
      examples:
        singleSecurityIdentifer:
          summary: Requesting Holders information for FDS-US
          value:
          - FDS-US
    requestedDate:
      name: date
      in: query
      schema:
        type: string
      required: false
      description: Date of holdings expressed in YYYY-MM-DD format. The fund-holdings endpoint will default to latest month-end close.
      example: '2019-12-31'
    currency:
      name: currency
      in: query
      schema:
        type: string
      description: Currency code for adjusting prices. Default is Local. For a list of currency ISO codes, visit [Online Assistant Page 1470](https://oa.apps.factset.com/pages/1470).
      example: USD
    topn:
      name: topn
      description: Limits number of holdings or holders displayed by the top *n* securities based on positions Market Value. Default is ALL, otherwise use number to limit number.
      in: query
      required: false
      schema:
        type: string
        default: ALL
      example: 5
    holderType:
      name: holderType
      in: query
      schema:
        type: string
        enum:
        - F
        - M
        - S
        - FS
        - B
        default: F
      description: "Controls the Holder Type of the data returned. By default, the service will return Institutional Holders. Requesting All Holders is not currently supported. Only a single Holder Type is allowed per request.\n  * **F** = Institutions\n  * **M** = Mutual Funds\n  * **S** =  Insiders/Stakeholders\n  * **FS** = Institutions/Insiders\n  * **B** = Beneficial Owners\n"
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation