Factset Benchmark API

openapi: 3.2.0
info:
  title: Factset Benchmark API
  version: '1.0'
  description: 'Operations tagged Benchmark across 2 of this provider''s published API definitions: factset-funds-api-openapi.yml, factset-real-time-quotes-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.factset.com/content
  description: Production
- url: https://api.factset.com/wealth/v3
tags:
- name: Benchmark
paths:
  /factset-funds/v1/benchmark-details:
    get:
      tags:
      - Benchmark
      summary: Factset Get the Fund's Primary and Segment Benchmark Details
      operationId: getFundsBenchmarkDetails
      description: 'Fetch the Fund''s Benchmark and Segment Benchmark ids. These ids can be then used in the [Benchmarks API](https://developer.factset.com/api-catalog/factset-benchmarks-api) to fetch index-level prices, returns, constituents data.

        '
      parameters:
      - $ref: '#/components/parameters/ids'
      responses:
        '200':
          description: The Benchmark Details response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/benchmarkDetailsResponse'
        '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
      security:
      - BasicAuth: []
    post:
      tags:
      - Benchmark
      summary: Factset Get the Fund's Primary and Segment Benchmark Details for Large List of Ids.
      description: 'Fetch the Fund''s Benchmark and Segement Benchmark ids. These ids can be then used in the [Benchmarks API](https://developer.factset.com/api-catalog/factset-benchmarks-api) to fetch index-level prices, returns, constituents data.

        '
      operationId: getFundsBenchmarkDetailsForList
      requestBody:
        required: true
        description: The Benchmark Details request body, allowing the user to specify a list of ids.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/benchmarkDetailsRequest'
      responses:
        '200':
          description: The Benchmark Details response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/benchmarkDetailsResponse'
        '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
      security:
      - BasicAuth: []
    servers:
    - url: https://api.factset.com/content
      description: Production
  /instrument/benchmark/list:
    post:
      tags:
      - Benchmark
      operationId: post/instrument/benchmark/list
      x-supportsOffsetBasedPaging: false
      x-supportsOffsetBasedPagingWithoutTotal: false
      x-supportsCursorBasedPaging: false
      x-supportsCursorBasedPagingWithoutTotal: false
      x-supportsPush: false
      x-requiresUser: false
      x-requiresInternalClient: false
      x-disallowUser: false
      x-no-merge: false
      x-maxSortParameterCount: 10
      x-supportsPermissionDeniedResponse: false
      summary: Factset List of Benchmarks of a Financial Instrument.
      description: Provides a list of benchmark notations for a selected financial instrument, optionally restricted to specific benchmark types.
      requestBody:
        description: Request Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostInstrumentBenchmarkListRequest'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/PostInstrumentBenchmarkList200Response'
      parameters: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - FactSetApiKey: []
      - FactSetOAuth2: []
    servers:
    - url: https://api.factset.com/wealth/v3
components:
  examples:
    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-funds/v1/{endpoint}
        message: text/html media type is not supported. Supported media types are application/json
        subErrors: null
    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: '2019-10-31 16:08:07.945'
        path: /factset-funds/v1/{endpoint}
        message: 'The date parameter ''startDate'' must be in the following date format: YYYY-MM-DD'
        subErrors: null
    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: '2019-11-05 09:48:29.18'
        path: /factset-funds/v1/{endpoint}
        message: Malformed JSON Request
        subErrors: null
    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-06-12 15:58:54.068'
        path: /factset-funds/v1/{endpoint}
        message: 'Invalid Parameter (s): fakeParameterName1 fakeParameterName2. Please modify your request to use parameters outlined in the specification for this endpoint.'
        subErrors: null
    badRequestFutureDate:
      summary: Bad Request - Future Date
      description: This error message occurs when a future date is requested in the startDate and endDate 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-06-12 15:52:48.091'
        path: /factset-funds/v1/{endpoint}
        message: The use of future dates is not applicable in this endpoint. 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-funds/v1/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-funds /v1/{endpoint}
        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-funds/v1/{endpoint}
        message: Unexpected error
        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-funds/v1/{endpoint}
        message: Error writing JSON output
        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-funds/v1/{endpoint}
        message: User Authentication Failed.
        subErrors: null
    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-06-12 15:48:42.016'
        path: /factset-funds/v1/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        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-funds/v1/{endpoint}
        message: The request took too long. Try again with a smaller request.
        subErrors: null
  responses:
    '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'
    '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'
    '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'
    '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'
    '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'
    PostInstrumentBenchmarkList200Response:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  idInstrument:
                    type:
                    - string
                    - 'null'
                    format: id64
                    x-positive: true
                    description: MDG identifier of the instrument.
                  sourceIdentifier:
                    type:
                    - string
                    - 'null'
                    description: Identifier used in the request.
                  benchmarks:
                    description: List of benchmarks.
                    type: array
                    items:
                      type: object
                      x-property-sort:
                      - notation
                      - type
                      properties:
                        notation:
                          type: object
                          x-property-sort:
                          - id
                          - fsym
                          - instrument
                          description: Notation data of a benchmark.
                          properties:
                            id:
                              type:
                              - string
                              - 'null'
                              format: id64
                              x-positive: true
                              description: Identifier of the notation.
                            fsym:
                              type: object
                              x-property-sort:
                              - listing
                              - regional
                              description: Notation-level FactSet identifiers of the financial instrument used primarily in FactSet products other than the MDG.
                              properties:
                                listing:
                                  type: object
                                  x-property-sort:
                                  - permanentIdentifier
                                  - tickerExchange
                                  - isPrimary
                                  description: Listing-level identifiers.
                                  properties:
                                    permanentIdentifier:
                                      type:
                                      - string
                                      - 'null'
                                      description: FactSet Permanent Identifier for a notation. The format is six alpha numeric characters, excluding vowels, with an L suffix (XXXXXX-L).
                                    tickerExchange:
                                      type:
                                      - string
                                      - 'null'
                                      description: 'FactSet market symbol of the notation, usually consisting of the ticker (e.g. "DAI" for Daimler AG) and the three-character code of the exchange on which the listing is traded (example: DAI-ETR).'
                                    isPrimary:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Indicates whether the notation is the primary notation among all notations within the same region (`true`) or not (`false`).
                                regional:
                                  type: object
                                  x-property-sort:
                                  - permanentIdentifier
                                  - tickerRegion
                                  - isPrimary
                                  description: Regional-level identifiers.
                                  properties:
                                    permanentIdentifier:
                                      type:
                                      - string
                                      - 'null'
                                      description: FactSet Permanent Identifier for a set of one or more notations of the same region with the same value unit. The format is six alpha numeric characters, excluding vowels, with an R suffix (XXXXXX-R).
                                    tickerRegion:
                                      type:
                                      - string
                                      - 'null'
                                      description: 'FactSet regional symbol of the notation, consisting of the ticker and the two-character code of the country or region where the listing is traded (example: DAI-DE).'
                                    isPrimary:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Indicates whether the notation is in the primary region of the security (`true`) or not (`false`).
                            instrument:
                              type: object
                              x-property-sort:
                              - id
                              - name
                              - fsym
                              description: Instrument data of the benchmark.
                              properties:
                                id:
                                  type:
                                  - string
                                  - 'null'
                                  format: id64
                                  x-positive: true
                                  description: Identifier of the instrument.
                                name:
                                  type:
                                  - string
                                  - 'null'
                                  format: localizedString
                                  description: Name of the instrument.
                                fsym:
                                  type: object
                                  x-property-sort:
                                  - security
                                  description: Instrument-level FactSet identifier of the financial instrument used primarily in FactSet products other than the MDG.
                                  properties:
                                    security:
                                      type: object
                                      x-property-sort:
                                      - permanentIdentifier
                                      description: Security-level identifier.
                                      properties:
                                        permanentIdentifier:
                                          type:
                                          - string
                                          - 'null'
                                          description: FactSet Permanent Identifier for an instrument. The format is six alpha numeric characters, excluding vowels, with an S suffix (XXXXXX-S).
                        type:
                          type: object
                          x-property-sort:
                          - id
                          - name
                          description: Type of the benchmark. For possible values, see endpoint `/basic/benchmark/type/list`.
                          properties:
                            id:
                              type:
                              - number
                              - 'null'
                              format: id32
                              x-positive: true
                              description: Identifier of the type.
                            name:
                              type:
                              - string
                              - 'null'
                              format: localizedString
                              description: Name of the type.
                description: List of benchmarks of a financial instrument.
                x-property-sort:
                - idInstrument
                - sourceIdentifier
                - benchmarks
              meta:
                type: object
                description: The meta member contains the meta information of the response.
                properties:
                  status:
                    $ref: '#/components/schemas/StatusObject'
                x-property-sort:
                - status
            x-property-sort:
            - data
            - meta
  schemas:
    errorResponse:
      type: object
      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-funds/v1/superRegion
        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
    benchmarkDetailsResponse:
      type: object
      title: Benchmark Details Response
      properties:
        data:
          description: Array of Benchmark Details Objects
          type: array
          items:
            $ref: '#/components/schemas/benchmarkDetails'
          example: []
    benchmarkDetails:
      title: Benchmark Details Object
      type: object
      properties:
        fsymId:
          description: FactSet Security Identifier. Six alpha-numeric characters, excluding vowels, with a -S suffix (XXXXXX-S), resolved from the requestId of the Fund requested.
          type:
          - string
          - 'null'
          example: FNK7XP-S
          x-fds-fql-formula: FSYM_SECURITY_PERM_ID('SECURITY')
        benchmarkId:
          description: The Fund's primary Benchmark Identifier.
          type:
          - string
          - 'null'
          example: R.1000
          x-fds-fql-formula: FFD_BMK_ID
        benchmarkName:
          description: The proper name of the Benchmark Id.
          type:
          - string
          - 'null'
          example: Russell 1000 Index
          x-fds-fql-formula: FFD_BMK_NAME
        multipleBenchmarkFlag:
          description: Indicates if the Fund has a composite benchmark.
          type:
          - string
          - 'null'
          example: Non-Composite
          x-fds-fql-formula: FFD_BMK_MULT
        benchmarkChangeDate:
          description: The date in which the benchmark changed for the requested fund in YYYY-MM-DD. If no benchmark changes occurred, the response value will be null.
          type:
          - string
          - 'null'
          format: date
          example: null
          x-fds-fql-formula: FFD_BMK_CHG_DATE
        segment:
          description: The segment of the respective segment benchmark id.
          type:
          - string
          - 'null'
          example: 'Equity: U.S. - Total Market Value'
          x-fds-fql-formula: FFD_SEG
        segmentBenchmarkId:
          description: Segment Benchmark Identifier. Funds in the same segment match on all seven levels of FactSet's fund classification system.
          type:
          - string
          - 'null'
          example: MS664292
          x-fds-fql-formula: FFD_SEG_BMK
        segmentBenchmarkName:
          description: The segment benchmark's name in proper format. Funds in the same segment match on all seven levels of FactSet's fund classification system.
          type:
          - string
          - 'null'
          example: MSCI USA IMI Value Index
          x-fds-fql-formula: FFD_SEG_BMK_NAME
        segmentBenchmarkCurrency:
          description: The Segment Benchmark's currency in ISO3. Funds in the same segment match on all seven levels of FactSet's fund classification system.
          type:
          - string
          - 'null'
          example: USD
          x-fds-fql-formula: FFD_SEG_BMK_CURR
        segmentBenchmarkReturnType:
          description: The Segment benchmarks return type. Funds in the same segment match on all seven levels of FactSet's fund classification system.
          type:
          - string
          - 'null'
          example: GROSS_RETURN
          x-fds-fql-formula: FFD_SEG_BMK_RET
        requestId:
          description: The requested Id sent as input.
          type: string
          example: MABAX
    benchmarkDetailsRequest:
      title: Benchmark Details Request Body
      description: Benchmark Details Request Body
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/ids'
      required:
      - ids
    ids:
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 1000
      description: 'The requested Fund Identifier. FactSet Identifiers, tickers, CUSIP and SEDOL are accepted input. <p>***ids limit** =  1000 per request*</p> *<p>Make note, GET Method URL request lines are also limited to a total length of 8192 bytes (8KB). In cases where the service allows for thousands of ids, which may lead to exceeding this request line limit of 8KB, its advised for any requests with large request lines to be requested through the respective "POST" method.</p>*

        '
      example:
      - MABAX
      - FCNTX
    PostInstrumentBenchmarkListRequest:
      x-property-sort:
      - data
      - meta
      description: Request Body
      type: object
      properties:
        data:
          type: object
          x-property-sort:
          - identifier
          - filter
          description: The data member contains the request's primary data.
          properties:
            identifier:
              type: object
              x-property-sort:
              - value
              - type
              description: Identifier and type.
              properties:
                value:
                  type: string
                  pattern: ^[B-DF-HJ-NP-TV-Z0-9]{6}-[SLR]$|^[A-Z0-9.#&*+]{1,47}-[A-Z0-9]{2,4}$|^[0-9]{3,20}$|^[B-DF-HJ-NP-TV-Z0-9]{6}[0-9]$|^[A-Z]{2}[A-Z0-9]{9}[0-9]$|^[A-Z1-9][A-Z0-9]{5}$|^[0-9]{1,9}$|^[A-Z0-9]{8}[0-9]$
                  maxLength: 50
                  minLength: 3
                  description: Identifier to resolve.
                type:
                  type: string
                  description: Type of the identifier.
                  x-enum-description:
                  - MDG identifier of an instrument.
                  - MDG identifier of a listing.
                  - FactSet Permanent Identifier on security level.
                  - FactSet Permanent Identifier on listing level.
                  - Regional FactSet Permanent Identifier.
                  - FactSet market symbol of a listing.
                  - Regional FactSet ticker symbol.
                  - SEDOL or IDII of a listing.
                  - ISIN of an instrument.
                  - WKN of an instrument.
                  - Valor number of an instrument.
                  - CUSIP or CINS identifier of an instrument
                  enum:
                  - idInstrument
                  - idNotation
                  - fdsPermanentIdentifierSecurity
                  - fdsPermanentIdentifierListing
                  - fdsPermanentIdentifierRegional
                  - tickerExchange
                  - tickerRegion
                  - sedol
                  - isin
                  - wkn
                  - valor
                  - cusip
              required:
              - value
              - type
            filter:
              type: object
              x-property-sort:
              - types
              description: Criteria that filter the items in the response list; only items that match all of the criteria are returned.
              properties:
                types:
                  type: array
                  items:
                    type: number
                    format: id32
                    x-positive: true
                  uniqueItems: true
                  description: Set of benchmark types. See endpoint `/basic/benchmark/type/list` for valid values.
          required:
          - identifier
          example: example_value
        meta:
          type: object
          description: The meta member contains the meta information of the request.
          properties:
            attributes:
              $ref: '#/components/schemas/AttributesMember'
            language:
              $ref: '#/components/schemas/LanguageMember'
          x-property-sort:
          - attributes
          - language
          example: example_value
    StatusObject:
      type: object
      properties:
        code:
          type: number
          format: int32
          description: The HTTP status code of the response, mirroring the code from the Status-Line of the HTTP response message (see [RFC2616] section 6.1).
          example: 42.5
      description: The status member contains the status code of the response.
      required:
      - code
    AttributesMember:
      type: array
      description: Limit the attributes returned in the response to the specified set.
      items:
        type: string
        maxLength: 100
      maxItems: 50
      uniqueItems: true
    LanguageMember:
      type: string
      format: isoLanguage
      description: ISO 639-1 code of the language.
      maxLength: 2
      minLength: 2
  parameters:
    ids:
      name: ids
      in: query
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 1000
      required: true
      explode: false
      description: 'The requested fund identifier. FactSet Identifiers, tickers, CUSIP, SEDOL, and ISIN are accepted inputs. <p>***ids limit** =  1000 per request*</p> *<p>Make note, GET Method URL request lines are also limited to a total length of 8192 bytes (8KB). In cases where the service allows for thousands of ids, which may lead to exceeding this request line limit of 8KB, its advised for any requests with large request lines to be requested through the respective "POST" method.</p>*

        '
      examples:
        oneId:
          summary: One Market Identifier
          value:
          - MABAX-US
        multipleIds:
          summary: Multiple Market Identifiers
          value:
          - MABAX-US
          - FCNTX-US
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    FactSetOAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.factset.com/as/token.oauth2
          scopes: {}
    FactSetApiKey:
      type: http
      scheme: basic
externalDocs:
  description: API Documentation
  url: https://developer.factset.com/api-catalog/
x-refined-from:
- factset-funds-api-openapi.yml
- factset-real-time-quotes-api-openapi.yml