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