openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Summary API
  description: Allow clients to fetch precalculated Analytics through predeterministic URLs.
  contact:
    name: FactSet Research Systems
    url: https://developer.factset.com/contact
    email: api@factset.com
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
servers:
- url: https://api.factset.com
  description: Production
- url: https://api-sandbox.factset.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Summary
paths:
  /factset-funds/v1/summary:
    get:
      tags:
      - Summary
      summary: Factset Get Basic Reference Summary Data for a Fund.
      operationId: getFundsSummary
      description: "Fetch basic reference data for the requested fund(s), including countryDomicile, shrClass, shrClassInceptDate, etc. \n"
      parameters:
      - $ref: '#/components/parameters/ids'
      responses:
        '200':
          description: The Fund Summaries response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summariesResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Summary
      summary: Factset Get Basic Reference Data for a Large List of Fund Ids.
      description: "Fetch basic reference data for the requested fund(s), including countryDomicile, shrClass, shrClassInceptDate, etc. \n"
      operationId: getFundsSummaryForList
      requestBody:
        required: true
        description: The Funds Summary request body, allowing the user to specify a list of ids.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/summariesRequest'
      responses:
        '200':
          description: The Funds Summary response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summariesResponse'
        '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
components:
  schemas:
    summaries:
      title: Funds Summary 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
          example: FNK7XP-S
          x-fds-fql-formula: FSYM_SECURITY_PERM_ID('SECURITY')
          nullable: true
        fsymEntityId:
          description: FactSet Entity Identifier. Six alpha-numeric characters, excluding vowels, with a -E suffix (XXXXXX-E), resolved from the requestId of the Fund requested.
          type: string
          example: 04BFG7-E
          x-fds-fql-formula: FSYM_ENTITY_ID
          nullable: true
        fsymRegionalId:
          description: FactSet Regional Identifier. Six alpha-numeric characters, excluding vowels, with a -R suffix (XXXXXX-R), resolved from the requestId of the Fund requested.
          type: string
          example: SJY03Z-R
          x-fds-fql-formula: FSYM_SECURITY_PERM_ID('REGIONAL_NEW')
          nullable: true
        fsymTickerRegion:
          description: FactSet Ticker-Region for the requested fund.
          type: string
          example: MABAX-US
          x-fds-fql-formula: FSYM_TICKER_REGION
          nullable: true
        fsymUltimateParentId:
          description: The FactSet Ultimate Parent Entity Identifer, with a -E suffix (XXXXXX-E).
          type: string
          example: 002HJD-E
          x-fds-fql-formula: FSYM_ULTIMATE_PARENT_ID
          nullable: true
        requestId:
          description: The requested Id sent as input.
          type: string
          example: MABAX
        activeFlag:
          description: Binary flag to indicate whether the fund is currently active, where 1 is active and 0 is inactive.
          type: integer
          example: 1
          x-fds-fql-formula: FFD_ACTIVE
          nullable: true
        activelyManagedFlag:
          description: Binary indicator of whether the fund is actively managed, where 1 is active and 0 is inactive.
          type: integer
          example: 1
          x-fds-fql-formula: FFD_ACTM
          nullable: true
        brand:
          description: The Funds Brand Name in proper format.
          type: string
          example: BlackRock
          x-fds-fql-formula: FFD_BRAND
          nullable: true
        countryDomicile:
          description: Returns the fund's country of domicile in ISO2 format. Only available for Mutual Funds.
          type: string
          example: US
          nullable: true
        currency:
          description: The fund's currency.
          type: string
          example: USD
          x-fds-fql-formula: FFD_CURRENCY
          nullable: true
        descInfo:
          description: The Fund's Investment Strategy short description.
          type: string
          example: The investment objective of the BlackRock Basic Value Fund, Inc. (the Fund) is to seek capital appreciation and, secondarily, income by investing in securities, primarily equity securities, that management of the Fund believes are undervalued and therefore represent basic investment value.
          x-fds-fql-formula: FFD_DESC_INFO
          nullable: true
        fundOfFundsId:
          description: The fund of fund's id if applicable. Will provide plain Fund of Funds text.
          type: string
          example: null
          x-fds-fql-formula: FFD_FUND_OF_FUNDS_ID
          nullable: true
        inceptionDate:
          description: The fund's inception date in YYYY-MM-DD format.
          type: string
          format: date
          example: '1977-07-01'
          x-fds-fql-formula: FFD_INCEPT_DATE
          nullable: true
        insight:
          description: The fund's investment strategy long description. Use `descInfo` if needing short description.
          type: string
          example: null
          x-fds-fql-formula: FFD_INSIGHT
          nullable: true
        issuerId:
          description: The Issuer Identifier.
          type: string
          example: null
          x-fds-fql-formula: FFD_ISSUER('ID')
          nullable: true
        issuerName:
          description: The Issuer Name in proper format.
          type: string
          example: BlackRock Inc.
          x-fds-fql-formula: FFD_ISSUER('NAME')
          nullable: true
        legalStructure:
          description: The legal structure of the fund, e.g. Open-Ended Fund, close-ended fund
          type: string
          example: Open-Ended Fund
          x-fds-fql-formula: FFD_LEG
          nullable: true
        leverageFactor:
          description: The leverage factor of the fund.
          type: number
          format: double
          example: 0
          x-fds-fql-formula: FFD_LEV_FACTOR
          nullable: true
        leverageInverse:
          description: Indicates whether the fund is leveraged, inverse, or neither in proper format.
          type: string
          example: Neither
          x-fds-fql-formula: FFD_LEV_INV
          nullable: true
        name:
          description: The Fund security's name in proper format.
          type: string
          example: BlackRock Basic Value Fund Incorporated
          x-fds-fql-formula: FFD_NAME
          nullable: true
        navCurrency:
          description: The NAV currency for the specified share class.
          type: string
          example: USD
          x-fds-fql-formula: FFD_DATA_CURR
          nullable: true
        objective:
          description: The Fund's objective long description.
          type: string
          example: The Fund invests primarily in equity securities that Fund management believes are undervalued, which means that their prices are less than Fund management believes they are worth. Equity securities primarily consist of common stock, preferred stock, securities convertible into common stock, or securities or other instruments whose price is linked to the value of common stock. Fund management places particular emphasis on companies with below average price/earnings ratios that may pay above average dividends. The Fund invests primarily in common stock of U.S. companies, but the Fund may invest up to 25% of its total assets in the securities of foreign companies. The Fund focuses primarily on companies with market capitalizations of over $5 billion.
          x-fds-fql-formula: FFD_OBJECTIVE
          nullable: true
        priceFirstDate:
          description: 'The fund''s first available date for prices (NAV) in YYYY-MM-DD format. This can be used to fetch the first available price from FactSet. *NOTE: This is not the inception date of fund.*'
          type: string
          format: date
          example: '2018-04-18'
          x-fds-fql-formula: FFD_PRICE_START_DATE
          nullable: true
        priceRecentDate:
          description: The fund's most recent available date for prices (NAV) in YYYY-MM-DD format.
          type: string
          format: date
          example: '2021-03-26'
          x-fds-fql-formula: FFD_PRICE_RCNT_DATE
          nullable: true
        shrClass:
          description: The Funds Share class type name in proper format.
          example: Institutional Class
          type: string
          x-fds-fql-formula: FFD_SHR_CLS
          nullable: true
        shrClassActiveFlag:
          description: Returns a binary indicator of whether the specified share class is currently active, where 1 is active and 0 is inactive.
          type: integer
          example: 1
          x-fds-fql-formula: FFD_SHR_CLS_ACTIVE
          nullable: true
        shrClsActivelyManagedFlag:
          description: Returns a binary indicator of whether the specified share class is actively managed, where 1 is active and 0 is inactive.
          type: integer
          example: 1
          x-fds-fql-formula: FFD_SHR_CLS_ACTM
          nullable: true
        shrClsCurrency:
          description: The currency for the specified share class.
          type: string
          example: USD
          x-fds-fql-formula: FFD_SHR_CLS_CURRENCY
          nullable: true
        shrClsInceptDate:
          description: The specified share class's inception date in YYYY-MM-DD format.
          type: string
          format: date
          example: '1977-07-01'
          x-fds-fql-formula: FFD_SHR_CLS_INCEPT_DATE
          nullable: true
        shrClsName:
          description: The specified share class name for the fund in proper format.
          type: string
          example: BlackRock Basic Value I
          x-fds-fql-formula: FFD_SHR_CLS_NAME
          nullable: true
        shrClsTermDate:
          description: The Share class Termination Date in YYYY-MM-DD format. If still active, value will be null.
          type: string
          format: date
          example: null
          x-fds-fql-formula: FFD_SHR_CLS_TERM_DATE
          nullable: true
        terminationDate:
          description: The Termination Date in YYYY-MM-DD format. If still active, value will be null.
          type: string
          format: date
          example: null
          x-fds-fql-formula: FFD_TERM_DATE
          nullable: true
        type:
          description: The Type of Fund, e.g. Mutual Fund, Unit Investment Trust
          type: string
          example: Mutual Fund
          x-fds-fql-formula: FFD_TYPE
          nullable: true
        webSite:
          description: The URL of the Fund.
          type: string
          example: https://www.blackrock.com/investing/products/227716/blackrock-basic-value-class-a-fund
          x-fds-fql-formula: FFD_WEB
          nullable: true
    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
    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
    summariesResponse:
      type: object
      title: Summaries Response
      properties:
        data:
          description: Array of Summaries Objects
          type: array
          items:
            $ref: '#/components/schemas/summaries'
          example: []
    summariesRequest:
      title: Summaries Request Body
      description: Summaries Request Body
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/ids'
      required:
      - ids
  examples:
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
  responses:
    '401':
      description: Unauthenticated USERNAME-SERIAL. Ensure you are logged in and have successfully generated an API KEY for the IP range you are connecting from. For more help, select the **Report Issue** in the top right corner of this Developer Portal specification card and choose Connectivity 401 or 403 Responses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/unauthenticated'
    '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'
    '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'
    '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'
  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
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation