openapi: 3.0.0
info:
version: 1.1.0
title: FactSet Ownership API
contact:
name: FactSet Research Systems
email: [email protected]
description: >
FactSet's Fund Ownership API gives access to both **Holdings** and
**Holders** data.<p> Factset's Holdings endpoints gives access to all the
underlying securities and their position detils held within a given fund.
Fund Types supported include Open-End Mutual Funds, Closed-end Mutual Funds,
and Exchange Traded Funds. Security Holders information retrieves all
"holder types" and their positions across institutions, funds, insiders, and
stakeholders.</p><p>The FactSet Ownership and Mutual Funds database collects
global equity ownership data for approximately 50,000 institutions, 60,000
unique Mutual Fund portfolios, and 400,000 Insider/Stake holders from around
110 countries. For more details review our [Data
Collection](https://my.apps.factset.com/oa/cms/oaAttachment/87e162be-f2d1-4f40-a85b-bfb1b020d270/20079)
methodology. </p>
servers:
- url: https://api.factset.com/content
description: Production
security:
- BasicAuth: []
paths:
/factset-ownership/v1/fund-holdings:
get:
tags:
- Factset Ownership
summary: Factset Get underlying holdings information for a requested fund identifer.
operationId: getOwnershipHoldings
description: >
Gets holdings information for list of fund identifiers. The service
allows you to filter by the TopN holdings and Asset Type.
parameters:
- $ref: '#/components/parameters/idFundHoldings'
- $ref: '#/components/parameters/requestedDate'
- $ref: '#/components/parameters/topn'
- $ref: '#/components/parameters/assetType'
- $ref: '#/components/parameters/currency'
responses:
'200':
description: Fund Holdings Response.
content:
application/json:
schema:
$ref: '#/components/schemas/fundHoldingsResponse'
examples:
VTI-US Top 5 Equities Held as of 2019-12-31:
$ref: '#/components/examples/singleIdentifer'
Top 5 Equity Holdings for VTI-USA, MABAX, and NZF as of 2019-12-31:
$ref: '#/components/examples/multipleIdentifiers'
'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'
post:
tags:
- Factset Ownership
summary: Factset Get holdings for a list of funds.
description: Gets Holding information for a long list of Fund objects.
operationId: postOwnershipHoldings
requestBody:
required: true
description: Requesting Underlying Holdings for a list of Fund Identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/fundHoldingsRequest'
examples:
Request to fetch the VTI-US Equity Fund-Holdings Details:
$ref: '#/components/examples/singleIdentiferPostRequest'
Request to fetch the Equity Fund-Holdings Details:
$ref: '#/components/examples/MultipleIdentifiersPostRequest'
responses:
'200':
description: Fund Holdings Response.
content:
application/json:
schema:
$ref: '#/components/schemas/fundHoldingsResponse'
examples:
Single identifier request for Top 5 Equity holdings as of 2019-12-31:
$ref: '#/components/examples/singleIdentifer'
Multiple identifier request for Top 5 Equity holdings as of 2019-12-31:
$ref: '#/components/examples/multipleIdentifiers'
'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'
/factset-ownership/v1/security-holders:
get:
tags:
- Factset Ownership
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'
post:
tags:
- Factset Ownership
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'
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
parameters:
idFundHoldings:
name: ids
description: >-
List of requested fund identifiers. <p>***ids limit** = 10 per
request*</p>
in: query
schema:
type: array
items:
type: string
minItems: 1
maxItems: 10
required: true
explode: false
examples:
singleIdentifer:
summary: One identifier to know the fund holding details
value:
- VTI-USA
multipleIdentifers:
summary: Multiple identifiers to know the fund holding details
value:
- VTI-USA
- MABAX
- NZF
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'
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
assetType:
name: assetType
schema:
type: string
default: EQ
enum:
- ALL
- EQ
- FI
description: |
Filter holdings by the following major asset classes -
* **EQ** = Equity
* **FI** = Fixed Income
* **ALL** = ALL
in: query
required: false
example: EQ
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
frequency:
name: frequency
in: query
schema:
type: string
enum:
- M
- MTD
- CQ
- CQTD
- CY
- CYTD
default: M
description: |
Controls the display frequency of the data returned.
* **M** = Monthly, based on the last trading day of the month.
* **MTD** = Month-to-date
* **CQ** = Quarterly based on the last trading day of the calendar quarter (March, June, September, or December).
* **CQTD** = Calendar quarter-to-date
* **CY** = Calendar Annual, based on the last trading day of the calendar year.
* **CYTD** = Calendar Year-to-date.
examples:
Monthly:
summary: M - Monthly - based on the last trading day of the month.
value: M
Month To Date:
summary: MTD - Month-to-date
value: MTD
Calendar Quarterly:
summary: >-
CQ - Calendar Quarterly - based on the last day of the week of the
startDate
value: CQ
Calendar quarter-to-date:
summary: CQTD - Calendar quarter-to-date
value: CQTD
Calendar Annual:
summary: >-
CY - Calendar Annual - based on the last trading day of the calendar
year.
value: CY
Calendar Year-to-date:
summary: CYTD - Calendar Year-to-date
value: CYTD
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
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.
* **F** = Institutions
* **M** = Mutual Funds
* **S** = Insiders/Stakeholders
* **FS** = Institutions/Insiders
* **B** = Beneficial Owners
schemas:
fundHoldingsRequest:
title: Holdings Request
description: Holdings Request
type: object
properties:
ids:
$ref: '#/components/schemas/idFundHoldings'
date:
$ref: '#/components/schemas/requestedDate'
topn:
$ref: '#/components/schemas/topn'
assetType:
$ref: '#/components/schemas/assetType'
currency:
$ref: '#/components/schemas/currency'
required:
- ids
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
fundHolding:
title: Fund Holding
description: fundHolding response object
type: object
properties:
requestId:
description: Fund Identifier that was used in the request.
type: string
example: VTI-US
fsymId:
description: >-
FactSet Security Identifier of Fund. Identifies the security level
id of the Fund requested (not-representing the underlying holding).
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: K7ZVMR-S
nullable: true
date:
description: >-
Date of the reported holding in YYYY-MM-DD format. For more details,
visit [Online Assistant Page
#11262](https://oa.apps.factset.com/pages/11262).
type: string
format: date
example: '2018-06-30'
nullable: true
currency:
description: >-
Currency code. The service will default to the funds local currency.
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
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: 60036157
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: 120078159
nullable: true
weightClose:
description: >-
Closing weight of security in the fund for the requested asset type
(percent).
type: number
format: double
example: 1.6639
nullable: true
issueType:
description: >-
Issue type of held security. For more details, visit [Online
Assistant Page #11262](https://oa.apps.factset.com/pages/11262).
type: string
example: Equity
nullable: true
fsymSecurityId:
description: >-
Represents the security id for the underlying holding, not the
parent holding. 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: BHM9TN-S
nullable: true
fsymRegionalId:
description: >-
FactSet Regional Security identifier of the security held in the
fund.
type: string
example: QLGSL2-R
nullable: true
securityName:
description: Name of held security.
type: string
example: FACEBOOK INC CL A
nullable: true
securityTicker:
description: Ticker of held security.
type: string
example: FB-US
nullable: true
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
fundHoldingsResponse:
title: Fund Holding Response
type: object
description: fundHolding response
properties:
data:
description: Array of Fund holdings
type: array
items:
$ref: '#/components/schemas/fundHolding'
securityHoldersResponse:
title: Security Holders Response
type: object
description: securityHolders response
properties:
data:
description: Array of Security Holders
type: array
items:
$ref: '#/components/schemas/securityHolders'
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
idFundHoldings:
description: List of Fund identifiers.
type: array
items:
type: string
minItems: 1
maxItems: 10
example:
- FDIVX-US
requestedDate:
description: Date of holdings expressed in YYYY-MM-DD format.
type: string
example: '2019-09-30'
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
assetType:
description: >-
Select type of assets returned, whereby EQ = Equity, FI = Fixed Income,
and ALL = all asset types.
type: string
enum:
- ALL
- EQ
- FI
default: EQ
idHolders:
description: Security Requested for Holders information.
type: array
items:
type: string
minItems: 1
maxItems: 1
example:
- FDS-US
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
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.
* **F** = Institutions
* **M** = Mutual Funds
* **S** = Insiders/Stakeholders
* **FS** = Institutions/Insiders
* **B** = Beneficial Owners
responses:
'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'
'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'
'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'
'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'
'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'
examples:
singleIdentifer:
summary: VTI-US Top 5 Equities Held as of 2019-12-31
description: >-
Underlying Fund Holdings for the Vanguard Total Stock Index ETF (VTI-US)
filtered by the Top 5 Equities Held as of 2020-01-01.
value:
data:
- requestId: VTI-US
fsymId: K7ZVMR-S
date: '2019-12-31'
currency: USD
adjHolding: 214894399
adjMarketValue: 33888846722.3
weightClose: 3.78696130582374
issueType: Equity
fsymSecurityId: DF3K29-S
fsymRegionalId: P8R3C2-R
securityName: MICROSOFT CORP COM
securityTicker: MSFT-US
- requestId: VTI-US
fsymId: K7ZVMR-S
date: '2019-12-31'
currency: USD
adjHolding: 112647486
adjMarketValue: 33078934263.9
weightClose: 3.6964563923282
issueType: Equity
fsymSecurityId: R85KLC-S
fsymRegionalId: MH33D6-R
securityName: APPLE INC COM
securityTicker: AAPL-US
- requestId: VTI-US
fsymId: K7ZVMR-S
date: '2019-12-31'
currency: USD
adjHolding: 11871374
adjMarketValue: 21936399732.16
weightClose: 2.45131673129814
issueType: Equity
fsymSecurityId: RMCVZ9-S
fsymRegionalId: MCNYYL-R
securityName: AMAZON COM INC COM
securityTicker: AMZN-US
- requestId: VTI-US
fsymId: K7ZVMR-S
date: '2019-12-31'
currency: USD
adjHolding: 67790793
adjMarketValue: 13914060263.25
weightClose: 1.55484806714164
issueType: Equity
fsymSecurityId: BHM9TN-S
fsymRegionalId: QLGSL2-R
securityName: FACEBOOK INC CL A
securityTicker: FB-US
- requestId: VTI-US
fsymId: K7ZVMR-S
date: '2019-12-31'
currency: USD
adjHolding: 53368129
adjMarketValue: 12087881218.5
weightClose: 1.35077888070268
issueType: Equity
fsymSecurityId: N138TY-S
fsymRegionalId: DBNXVB-R
securityName: BERKSHIRE HATHAWAY INC CL B
securityTicker: BRK.B-US
multipleIdentifiers:
summary: Top 5 Equity Holdings for VTI-US, MABAX, and NZF as of 2019-12-31
description: The Top 5 Equity Holdings of VTI-US, MABAX, and NZF as of 2019-12-31.
value:
data:
- requestId: VTI-USA
fsymId: K7ZVMR-S
date: '2019-12-31'
currency: USD
adjHolding: 214894399
adjMarketValue: 33888846722.3
weightClose: 3.78696130582374
issueType: Equity
fsymSecurityId: DF3K29-
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/factset/refs/heads/main/openapi/ownership-openapi-original.yml