Factset Batch Result API

openapi: 3.2.0
info:
  version: 2.1.0
  title: FactSet Fundamentals Batch Result API
  contact:
    name: FactSet Research Systems
    email: api@factset.com
    url: https://developer.factset.com/contact
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: Gain access to current, comprehensive, and comparative information on securities in worldwide developed and emerging markets. Composed of annual and interim/quarterly data, detailed historical financial statement content, per-share data, and calculated ratios, FactSet Fundamentals provides you with the information you need for a global investment perspective.
servers:
- url: https://api.factset.com/content/factset-fundamentals/v2
  description: Production
security:
- FactSetApiKey: []
- FactSetOAuth2: []
tags:
- name: Batch Result
paths:
  /batch-result:
    get:
      tags:
      - Batch Result
      summary: Factset Returns the response for a Batch Request
      description: 'Returns the response data for the underlying batch request that is specified by the id.


        By default, this endpoint will return data as JSON. If you wish to receive your data in CSV format, you can edit the header to have the "accept" parameter as "text/csv" instead of "application/json".'
      operationId: getBatchData
      parameters:
      - $ref: '#/components/parameters/batchId'
      responses:
        '200':
          description: Request Response Object when the batch request has been completed and the response is created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchResultResponse'
              examples:
                Fundamentals endpoint response of Single Company (FDS-US), and Multiple Metrics (FF_SALES, FF_PE):
                  $ref: '#/components/examples/resultOfSingleIdwithMultipleMetricItem'
                Segments endpoint response of Single Company (AAPL-US), sales(SALES) details for the given period:
                  $ref: '#/components/examples/resultOfSingleIdwithSingleMetricItemSegment'
        '202':
          description: The batch Request has not finished and the result has NOT been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Request Queued:
                  $ref: '#/components/examples/BatchStatusQueuedResponse'
                Batch Request Executing:
                  $ref: '#/components/examples/BatchStatusExecutingResponse'
        '404':
          $ref: '#/components/responses/404'
      deprecated: false
components:
  schemas:
    BatchStatus:
      title: Batch Status
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: the id of batch request.
        startTime:
          type: string
          format: date-time
          description: Time when the batch request is started. This is in Eastern Time Zone. The date-time format is expressed as [YYYY-MM-DD]T[HH:MM:SSS], following ISO 8601.
        endTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Time when the batch request is ended. This is in Eastern Time Zone. The date-time format is expressed as [YYYY-MM-DD]T[HH:MM:SSS], following ISO 8601.
        status:
          type: string
          enum:
          - queued
          - executing
          - created
          - failed
        error:
          $ref: '#/components/schemas/batchErrorObject'
    fundamental:
      title: Fundamental Object
      type: object
      required:
      - fiscalPeriod
      description: FactSet Fundamentals Response item
      properties:
        requestId:
          description: Identifier that was used for the request.
          type: string
          example: IBM-US
        fsymId:
          description: FactSet Regional Security Identifier. Six alpha-numeric characters, excluding vowels, with an -R suffix (XXXXXX-R). Identifies the security's best regional security data series per currency. For equities, all primary listings per region and currency are allocated a regional-level permanent identifier. The regional-level permanent identifier will be available once a SEDOL representing the region/currency has been allocated and the identifiers are on FactSet.
          type:
          - string
          - 'null'
          example: SJY281-R
        metric:
          description: The requested `metric` input, representing the Fundamental Data Item. For a definition of the item please use the /fundamentals/v#/metrics endpoint.
          type:
          - string
          - 'null'
          example: FF_SALES
        periodicity:
          description: Periodicity or frequency of the fiscal periods, where ANN = Annual Original, ANN_R = Annual Latest, QTR = Quarterly Original, QTR_R = Quarterly Latest, SEMI = Semi-Annual Original, SEMI_R = Semi-Annual Latest, LTM = Last Twelve Months Original, LTM_R = Last Twelve Months Latest, LTMSG = Last Twelve Months Global, [OA17959](https://my.apps.factset.com/oa/pages/17959), LTM_SEMI = Last Twelve Months - Semi-Annual Data and YTD = Year-to-date. Please note that the coverage for SEMI_R and LTM_R may be limited as fewer companies report with these periodicities.
          type:
          - string
          - 'null'
          example: QTR
          enum:
          - ANN
          - ANN_R
          - QTR
          - QTR_R
          - SEMI
          - SEMI_R
          - CAL
          - LTM
          - LTM_R
          - LTMSG
          - LTM_SEMI
          - YTD
        fiscalPeriod:
          description: 'Fiscal Period indicator. Returns an integer representing the fiscal period for the requested item and periodicity. QUARTERLY CODE: 1-Fist Quarter; 2-Second Quarter; 3-Third Quarter; 4-Fourth Quarter. SEMI-CODE: 1-First Semi-annual Period; 2-Second Semi-annual Period.'
          type:
          - integer
          - 'null'
          example: 4
        fiscalYear:
          description: Fiscal year of the reported period in YYYY format.
          type:
          - integer
          - 'null'
          example: 2018
        fiscalPeriodLength:
          description: Length of the fiscal period in days.
          type:
          - integer
          - 'null'
          example: 91
        fiscalEndDate:
          description: The normalized data the fiscal period ended.
          type:
          - string
          - 'null'
          format: date
          example: '2017-12-31'
        reportDate:
          description: The date the reported fiscal period ended.
          type:
          - string
          - 'null'
          format: date
          example: '2017-12-30'
        epsReportDate:
          description: The date the EPS was reported for the requested periodicity. In YYYY-MM-DD format. Unavailable data returned as 0001-01-01.
          type:
          - string
          - 'null'
          format: date
          example: '2018-02-24'
        updateType:
          description: 'Update Type: Preliminary - The period is updated from a report that usually contains limited or only key information., Final - The period is updated from a report where detailed information is available in financial statements including the notes to the line items.'
          type:
          - string
          - 'null'
          example: Preliminary
          enum:
          - Preliminary
          - Final
        currency:
          description: 'Currency code for the data. For a list of currency ISO codes, visit [Online Assistant Page #1470](https://oa.apps.factset.com/pages/1470).'
          type:
          - string
          - 'null'
          example: USD
        value:
          $ref: '#/components/schemas/fundamentalValue'
    batchResult:
      title: Batch Data
      oneOf:
      - $ref: '#/components/schemas/fundamental'
      - $ref: '#/components/schemas/segment'
    segment:
      title: Segment Object
      type: object
      required:
      - label
      properties:
        requestId:
          description: Identifier that was used for the request.
          type: string
          example: AAPL-US
        fsymId:
          description: FactSet Regional Security Identifier. Six alpha-numeric characters, excluding vowels, with an -R suffix (XXXXXX-R). Identifies the security's best regional security data series per currency. For equities, all primary listings per region and currency are allocated a regional-level permanent identifier. The regional-level permanent identifier will be available once a SEDOL representing the region/currency has been allocated and the identifiers are on FactSet.
          type:
          - string
          - 'null'
          example: MH33D6-R
        metric:
          description: The requested `metric` input, representing the Fundamental Data Item. For a definition of the item please use the /fundamentals/v#/metrics endpoint.
          type:
          - string
          - 'null'
          example: SALES
        label:
          description: Report labels of the segment type requested.
          type:
          - string
          - 'null'
          example: iPhone
        date:
          description: Date for the period requested expressed in YYYY-MM-DD format
          type:
          - string
          - 'null'
          format: date
          example: '2022-09-30'
        value:
          $ref: '#/components/schemas/segmentValue'
    errorResponse:
      type: object
      title: Error Response
      description: Error Default Response
      properties:
        errors:
          type: array
          description: An array containing errors
          items:
            $ref: '#/components/schemas/errorObject'
    batchErrorObject:
      type:
      - object
      - 'null'
      properties:
        id:
          description: A UUID for this particular occurrence of the problem.
          type: string
          example: adb01824-252f-4420-b0c6-35a1e3507ef5
        code:
          description: status
          type: string
          example: GenericError
        title:
          description: The plain text error message
          type: string
          example: Validation Error
    segmentValue:
      description: 'Value of the data metric requested. Note that the type of value is ''object'', and depending on the data metric requested, the value could be an object representation of a string or double. '
      oneOf:
      - type:
        - string
        - 'null'
      - type:
        - number
        - 'null'
        format: double
    batchResultResponse:
      title: Batch Data Response
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/batchResult'
    BatchStatusResponse:
      title: Batch Status Response
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BatchStatus'
    errorObject:
      type: object
      properties:
        id:
          description: A UUID for this particular occurrence of the problem.
          type: string
          example: adb01824-252f-4420-b0c6-35a1e3507ef5
        code:
          description: status
          type: string
          example: Bad Request
        links:
          description: The Endpoint path {package}/version/{endpoint}
          type: object
          properties:
            about:
              description: details.
              type: string
              example: /factset-fundamentals/v1/{endpoint}
        title:
          description: The plain text error message
          type: string
          example: Validation Error
    fundamentalValue:
      description: 'Value of the data metric requested. Note that the type of value is ''object'', and depending on the data metric requested, the value could be an object representation of a string or double. '
      oneOf:
      - type:
        - string
        - 'null'
      - type:
        - number
        - 'null'
        format: double
  examples:
    resultOfSingleIdwithMultipleMetricItem:
      summary: Result of Single Company and Multiple Metrics [FF_SALES, FF_PE]
      description: 'Results of the FDS-US Quarterly Sales and Price to Earnings data as of 2020-05-31

        '
      value:
        data:
        - requestId: FDS
          fsymId: SQFMK3-R
          metric: FF_SALES
          periodicity: QTR
          fiscalPeriod: 3
          fiscalYear: 2020
          fiscalPeriodLength: 92
          fiscalEndDate: '2020-05-31'
          reportDate: '2020-05-31'
          epsReportDate: '2020-06-25'
          updateType: Final
          currency: USD
          value: 374.083
        - requestId: FDS
          fsymId: SQFMK3-R
          metric: FF_PE
          periodicity: QTR
          fiscalPeriod: 3
          fiscalYear: 2020
          fiscalPeriodLength: 92
          fiscalEndDate: '2020-05-31'
          reportDate: '2020-05-31'
          epsReportDate: '2020-06-25'
          updateType: Final
          currency: USD
          value: 31.6769162623484
    resultOfSingleIdwithSingleMetricItemSegment:
      summary: Result of Single Company single metric item [SALES] details.
      description: 'Results of the AAPL-US sales data for the period 2012-01-01 to 2014-01-01 on an annual basis with the preliminary data Values.

        '
      value:
        data:
        - requestId: AAPL-US
          fsymId: MH33D6-R
          metric: SALES
          date: 2012-09-28 00:00:00+00:00
          label: iPhone
          value: 141319
        - requestId: AAPL-US
          fsymId: MH33D6-R
          metric: SALES
          date: 2012-09-28 00:00:00+00:00
          label: iPad
          value: 19222
    notFound:
      summary: Not Found
      description: The requested item was not found.
      value:
        status: Not Found
        timestamp: '2020-06-12T16:08:51.731Z'
        path: /factset-fundamentals/v2/{endpoint}
        message: The Batch Request was not found. It has probably expired.
        subErrors: null
    BatchStatusQueuedResponse:
      description: Batch Status Queued Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: queued
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: null
          error: null
    BatchStatusExecutingResponse:
      description: Batch Status Executing Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: executing
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: null
          error: null
  responses:
    '404':
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Batch Request Not Found:
              $ref: '#/components/examples/notFound'
  parameters:
    batchId:
      name: id
      in: query
      description: Batch Request identifier.
      schema:
        type: string
        format: uuid
      required: true
      allowEmptyValue: false
  securitySchemes:
    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/factset-fundamentals-api