Factset
FactSet Ownership Report Builder API

Returns top holders of company and fund equity.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.3
info:
  title: FactSet Ownership API
  description: ''
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
servers:
  - url: https://api.factset.com/report/ownership/v1
externalDocs:
  description: Read more about STACH 2.0's row organized schema
  url: https://factset.github.io/stachschema/#/v2/RowOrganized
tags:
  - name: Holders
paths:
  /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.  

            Default is ALL, otherwise use a valid number above 0.
          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'
security:
  - basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  responses:
    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'
    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'
    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
    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'
    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'
    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
    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'
    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
  examples:
    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
                      - 
                      - '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
                      - 
                      - '2020-07-31'
                      - US Fund (N-30D)
                    rowMetadata:
                      fsymId:
                        value: ' M4005398'
                  - cells:
                      - ' Vanguard Extended Market Index Fund'
                      - 1.4185
                      - 538950
                      - 2048
                      - 179696709
                      - 0.239476
                      - 
                      - '2020-07-31'
                      - US Fund (N-30D)
                    rowMetadata:
                      fsymId:
                        value: ' M4004539'
                  - cells:
                      - ' Vanguard Growth Index Fund'
                      - 0.7859
                      - 298593
                      - 11429
                      - 99556878.06
                      - 0.075905
                      - 
                      - '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
                      - 
                      - '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
                      - 
                      - '2020-07-31'
                      - US Fund (N-30D)
                    rowMetadata:
                      fsymId:
                        value: ' M4048682'
                  - cells:
                      - ' Vanguard Financials Index Fund'
                      - 0.1994
                      - 75747
                      - 1346
                      - 25255564.74
                      - 0.377082
                      - 
                      - '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
                      - 
                      - '2020-07-31'
                      - US Fund (N-30D)
                    rowMetadata:
                      fsymId:
                        value: ' M4107013'
                  - cells:
                      - ' Vanguard Strategic Equity Fund'
                      - 0.122
                      - 46359
                      - -2294
                      - 15457017.78
                      - 0.244843
                      - 
                      - '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
                      - 
                      - '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
    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
    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:
                      - 
                      - 
                      - 
                    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.
    genericServerError:
      summary: generic server error
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: genericServerError
            title: Unexpected error processing request
    idRequiredParameterError:
      summary: generic parameter error (missing parameter)
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Missing required parameter(s): ''id'''
    idInvalidParameterError:
      summary: generic parameter error (invalid parameter)
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Invalid parameter(s): ''id'''
    parameterErrorAssetType:
      summary: asset type parameter error
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Invalid parameter: ''asset_type'''
    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’.
    parameterErrorTopn:
      summary: topn parameter error
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Invalid parameter: ''topn'''
    parameterErrorDate:
      summary: date parameter error
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Invalid parameter: ''date'''
    endpointNotFound:
      summary: endpoint not found
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: endpointNotFound
            title: The requested endpoint does not exist.
    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
  schemas:
    Response:
      type: object
      properties:
        data:
          title: STACH
          description: Returns a STACH 2.0 row organized package
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      additionalProperties:
        type: string
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorObject:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        title:
          type: string
        links:
          type: object
          properties:
            about:
              type: string
        detail:
          type: string
        source:
          type: object
          properties:
            parameter:
              type: string
    MetadataEntry:
      type: object
      description: >
        Restricted metadata entries. Restricts the possible key in the following
        STACH schema:

        - RowOrganizedPackage.CellDetail.CellMetadataEntry

        - RowOrganizedPackage.HeaderCellDetail.CellMetadataEntry

        - RowOrganizedPackage.MapOfMetadata.ItemsEntry

        - RowOrganizedPackage.Row.RowMetadataEntry

        - RowOrganizedPackage.TableData.TableMetadataEntry

        And sets restrictions on the possible values for a MetadataItem.
      oneOf:
        - $ref: '#/components/schemas/fsymId'
        - $ref: '#/components/schemas/currencyCode'
        - $ref: '#/components/schemas/currencySymbol'
        - $ref: '#/components/schemas/category'
        - $ref: '#/components/schemas/valueType'
        - $ref: '#/components/schemas/scale'
        - $ref: '#/components/schemas/description'
        - $ref: '#/components/schemas/frequency'
    fsymId:
      type: object
      properties:
        fsymId:
          type: object
          description: Describes fund id or institution id
          properties:
            value:
              type: string
              nullable: true
    currencyCode:
      type: object
      properties:
        currencyCode:
          type: object
          description: Code for data currency
          properties:
            value:
              type: string
    currencySymbol:
      type: object
      properties:
        currencySymbol:
          type: object
          description: Symbol for data currency
          properties:
            value:
              type: string
    category:
      type: object
      properties:
        category:
          type: object
          description: >
            Describes data based on source or kind of value

            - ACTUAL - Historical data collected directly from a press release
            or a median consensus from brokers after a report date.

            - ESTIMATE - Forward looking average of broker estimates within a
            specific time horizon.

            - GUIDANCE - Forward looking indication or estimate of future
            performance issued by the company itself.

            - DETAIL - Indicates data that is more granular and may be secondary
            in focus.

            - MAIN - Indicates data is of more impactful or higher importance
            and may want to be emphasized.

            - SECTION - Indicates data that is used in sectioning rows in group
            level STACH format.
          properties:
            value:
              type: string
              enum:
                - ACTUAL
                - ESTIMATE
                - GUIDANCE
                - EXCLUDED
                - CHANGE
                - DETAIL
                - MAIN
                - SECTION
    valueType:
      type: object
      properties:
        valueType:
          type: object
          description: Describes how to interpret numbers
          properties:
            value:
              type: string
              enum:
                - PERCENTAGE
                - RATIO
                - TREND
                - RANGE
    scale:
      type: object
      properties:
        scale:
          type: object
          description: >
            Integer power of 10 to which numbers have been scaled. For example:
            6 implies millions.

            Default is 0.
          properties:
            value:
              type: integer
    description:
      type: object
      properties:
        description:
          type: object
          description: Text describing the data
          properties:
            value:
              type: string
    frequency:
      type: object
      properties:
        frequency:
          type: object
          description: |
            String with frequency of a data series. Allowed values:
            - "D" (daily)
            - "W" (weekly)
            - "AW" (actual weekly)
            - "M" (monthly)
            - "AM" (actual monthly)
            - "Q" (quarterly)
            - "FQ" (fiscal quarterly)
            - "CQ" (calendar quarterly)
            - "AQ" (actual quarterly)
            - "Y" (yearly)
            - "FY" (fiscal yearly)
            - "CY" (calendar yearly)
            - "AY" (actual yearly)
            - "MTD" (month-to-date)
            - "QTD" (quarter-to-date)
            - "YTD" (year-to-date)
            - "FYTD" (fiscal-year-to-date)
            - "CYTD" (calendar-year-to-date)
          properties:
            value:
              type: string
              enum:
                - D
                - W
                - AW
                - M
                - AM
                - Q
                - FQ
                - CQ
                - AQ
                - 'Y'
                - FY
                - CY
                - AY
                - MTD
                - QTD
                - YTD
                - FYTD
                - CYTD
FactSet Ownership Report Builder API

Documentation

Specifications

SDKs

Code Examples

Other Resources

OpenAPI Specification
