Factset Financial Statements API

openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Financial Statements 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: Financial Statements
  description: Retrieve standardized financial statement data including income statements, balance sheets, and cash flow statements. Access annual, quarterly, and interim data for companies worldwide.
paths:
  /fundamentals:
    get:
      tags:
      - Financial Statements
      operationId: getFundamentals
      summary: Factset Returns Company Fundamental Data.
      description: 'Retrieves FactSet Fundamental standardized data for specified securities. Use the `/metrics` endpoint to retrieve a full list of valid metrics or data items.


        The `/fundamentals` endpoint currently supports Long Running asynchronous requests up to **20 minutes** via batch parameter. Id limits are increased to 2000 ids per request when using batch capability. This 2000 id limit has been derived based on single metric for one day.'
      parameters:
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/metrics'
      - $ref: '#/components/parameters/periodicity'
      - $ref: '#/components/parameters/fiscalPeriodStart'
      - $ref: '#/components/parameters/fiscalPeriodEnd'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/updateType'
      - $ref: '#/components/parameters/batch'
      responses:
        '200':
          description: Fundamental data items returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundamentalsResponse'
              examples:
                singleCompanySingleMetric:
                  summary: Single company (FDS-US) with FF_SALES metric
                  value:
                    data:
                    - requestId: FDS-US
                      fsymId: SQFMK3-R
                      metric: FF_SALES
                      periodicity: QTR
                      fiscalPeriod: 1
                      fiscalYear: 2024
                      fiscalPeriodLength: 91
                      fiscalEndDate: '2024-02-29'
                      reportDate: '2024-02-28'
                      epsReportDate: '2024-03-21'
                      updateType: Final
                      currency: USD
                      value: 547200000
                multipleCompaniesMultipleMetrics:
                  summary: Multiple companies with multiple metrics
                  value:
                    data:
                    - requestId: FDS-US
                      fsymId: SQFMK3-R
                      metric: FF_SALES
                      periodicity: ANN
                      fiscalPeriod: 0
                      fiscalYear: 2023
                      fiscalPeriodLength: 365
                      fiscalEndDate: '2023-08-31'
                      reportDate: '2023-08-31'
                      epsReportDate: '2023-09-19'
                      updateType: Final
                      currency: USD
                      value: 2072800000
                    - requestId: AAPL-US
                      fsymId: MH33D6-R
                      metric: FF_SALES
                      periodicity: ANN
                      fiscalPeriod: 0
                      fiscalYear: 2023
                      fiscalPeriodLength: 365
                      fiscalEndDate: '2023-09-30'
                      reportDate: '2023-09-30'
                      epsReportDate: '2023-11-02'
                      updateType: Final
                      currency: USD
                      value: 383285000000
        '202':
          $ref: '#/components/responses/BatchAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Financial Statements
      operationId: postFundamentals
      summary: Factset Returns Company Fundamental Data for a List of Identifiers.
      description: 'Retrieves FactSet Fundamental standardized data for specified securities using a POST request body. Use the `/metrics` endpoint to retrieve a full list of valid metrics or data items.


        The `/fundamentals` endpoint currently supports Long Running asynchronous requests up to **20 minutes** via batch parameter. Id limits are increased to 30,000 ids per request when using batch capability. This 30,000 id limit has been derived based on single metric for one day.'
      requestBody:
        required: true
        description: Request object for fundamentals data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FundamentalsRequest'
            examples:
              singleCompanySingleMetric:
                summary: Single company with single metric
                value:
                  data:
                    ids:
                    - FDS-US
                    metrics:
                    - FF_SALES
                    periodicity: QTR
                    fiscalPeriod:
                      start: '2023-01-01'
                      end: '2024-01-01'
              multipleCompaniesMultipleMetrics:
                summary: Multiple companies with multiple metrics
                value:
                  data:
                    ids:
                    - FDS-US
                    - AAPL-US
                    - MSFT-US
                    metrics:
                    - FF_SALES
                    - FF_EPS
                    - FF_PE
                    periodicity: ANN
                    fiscalPeriod:
                      start: '2020-01-01'
                      end: '2024-01-01'
                    currency: USD
              batchRequest:
                summary: Batch request for large ID set
                value:
                  data:
                    ids:
                    - FDS-US
                    - AAPL-US
                    metrics:
                    - FF_SALES
                    - FF_PE
                    periodicity: ANN
                    batch: Y
      responses:
        '200':
          description: Fundamental data items returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundamentalsResponse'
        '202':
          $ref: '#/components/responses/BatchAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /financial-statements:
    get:
      tags:
      - Financial Statements
      operationId: getFinancialStatements
      summary: Factset Returns Financial Statement Line Items.
      description: 'Retrieves detailed financial statement data organized by statement type (income statement, balance sheet, cash flow). Use the `category` parameter to filter by statement type, and the `metrics` parameter to request specific line items.


        Available statement categories include INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW, and FINANCIAL_SERVICES for financial institutions.'
      parameters:
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/metrics'
      - $ref: '#/components/parameters/statementCategory'
      - $ref: '#/components/parameters/periodicity'
      - $ref: '#/components/parameters/fiscalPeriodStart'
      - $ref: '#/components/parameters/fiscalPeriodEnd'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/updateType'
      responses:
        '200':
          description: Financial statement data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundamentalsResponse'
              examples:
                incomeStatement:
                  summary: Income statement data for AAPL-US
                  value:
                    data:
                    - requestId: AAPL-US
                      fsymId: MH33D6-R
                      metric: FF_SALES
                      periodicity: ANN
                      fiscalPeriod: 0
                      fiscalYear: 2023
                      fiscalPeriodLength: 365
                      fiscalEndDate: '2023-09-30'
                      reportDate: '2023-09-30'
                      epsReportDate: '2023-11-02'
                      updateType: Final
                      currency: USD
                      value: 383285000000
                    - requestId: AAPL-US
                      fsymId: MH33D6-R
                      metric: FF_GROSS_INC
                      periodicity: ANN
                      fiscalPeriod: 0
                      fiscalYear: 2023
                      fiscalPeriodLength: 365
                      fiscalEndDate: '2023-09-30'
                      reportDate: '2023-09-30'
                      epsReportDate: '2023-11-02'
                      updateType: Final
                      currency: USD
                      value: 169148000000
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Financial Statements
      operationId: postFinancialStatements
      summary: Factset Returns Financial Statement Line Items for a List of Identifiers.
      description: Retrieves detailed financial statement data via POST for large identifier sets. Supports up to 30,000 ids per batch request.
      requestBody:
        required: true
        description: Request object for financial statement data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinancialStatementsRequest'
      responses:
        '200':
          description: Financial statement data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundamentalsResponse'
        '202':
          $ref: '#/components/responses/BatchAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ErrorResponse:
      type: object
      title: Error Response
      description: Standard error response wrapper.
      properties:
        errors:
          type: array
          description: An array containing error details.
          items:
            $ref: '#/components/schemas/Error'
          example: []
    FundamentalsRequestBody:
      type: object
      title: Fundamentals Request Body
      description: Core request parameters for fundamentals data.
      required:
      - ids
      - metrics
      properties:
        ids:
          $ref: '#/components/schemas/SecurityIds'
        metrics:
          $ref: '#/components/schemas/MetricsList'
        periodicity:
          $ref: '#/components/schemas/Periodicity'
        fiscalPeriod:
          $ref: '#/components/schemas/FiscalPeriod'
        currency:
          $ref: '#/components/schemas/Currency'
        updateType:
          $ref: '#/components/schemas/UpdateType'
        batch:
          $ref: '#/components/schemas/BatchFlag'
    FiscalPeriod:
      type: object
      title: Fiscal Period
      description: Fiscal period date range specification. Calendar dates that will fall back to the most recently completed period during resolution.
      properties:
        start:
          type: string
          format: date
          description: The fiscal period start expressed as YYYY-MM-DD.
          examples:
          - '2023-01-01'
        end:
          type: string
          format: date
          description: The fiscal period end expressed as YYYY-MM-DD.
          examples:
          - '2024-01-01'
    BatchStatus:
      type: object
      title: Batch Status
      description: Status information for an asynchronous batch request.
      properties:
        id:
          type: string
          format: uuid
          description: The batch request identifier.
          example: abc123
        startTime:
          type: string
          format: date-time
          description: Time when the batch request started (Eastern Time Zone).
          example: '2026-01-15T10:30:00Z'
        endTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Time when the batch request ended. Null if still processing.
          example: '2026-01-15T10:30:00Z'
        status:
          type: string
          description: Current batch processing status.
          enum:
          - queued
          - executing
          - created
          - failed
          example: queued
        error:
          $ref: '#/components/schemas/BatchError'
    Error:
      type: object
      title: Error
      description: A single error detail object.
      properties:
        id:
          type: string
          description: A UUID for this particular occurrence of the problem.
          examples:
          - adb01824-252f-4420-b0c6-35a1e3507ef5
        code:
          type: string
          description: Error status code description.
          examples:
          - Bad Request
        title:
          type: string
          description: The plain text error message.
          examples:
          - Validation Error
        links:
          type: object
          description: The endpoint path for reference.
          properties:
            about:
              type: string
              description: API path that generated the error.
              examples:
              - /factset-fundamentals/v2/fundamentals
          example: example_value
    FinancialStatementsRequestBody:
      type: object
      title: Financial Statements Request Body
      description: Request parameters for financial statement data.
      required:
      - ids
      - metrics
      properties:
        ids:
          $ref: '#/components/schemas/SecurityIds'
        metrics:
          $ref: '#/components/schemas/MetricsList'
        category:
          type: string
          description: Financial statement type filter.
          enum:
          - INCOME_STATEMENT
          - BALANCE_SHEET
          - CASH_FLOW
          - FINANCIAL_SERVICES
          example: INCOME_STATEMENT
        periodicity:
          $ref: '#/components/schemas/Periodicity'
        fiscalPeriod:
          $ref: '#/components/schemas/FiscalPeriod'
        currency:
          $ref: '#/components/schemas/Currency'
        updateType:
          $ref: '#/components/schemas/UpdateType'
        batch:
          $ref: '#/components/schemas/BatchFlag'
    Periodicity:
      type: string
      title: Periodicity
      description: Periodicity or frequency of the fiscal periods. ANN = Annual, QTR = Quarterly, SEMI = Semi-Annual, LTM = Last Twelve Months, YTD = Year-to-date. Suffix _R includes restatements.
      enum:
      - ANN
      - ANN_R
      - QTR
      - QTR_R
      - SEMI
      - SEMI_R
      - LTM
      - LTM_R
      - LTMSG
      - LTM_SEMI
      - YTD
      default: ANN
    BatchError:
      type:
      - object
      - 'null'
      title: Batch Error
      description: Error information for a failed batch request.
      properties:
        id:
          type: string
          description: A UUID for this particular occurrence of the problem.
          example: abc123
        code:
          type: string
          description: Error code.
          example: example_value
        title:
          type: string
          description: The plain text error message.
          example: Example Title
    UpdateType:
      type: string
      title: Update Type
      description: Update status flag. RP = Include preliminary data, RF = Only final data.
      enum:
      - RP
      - RF
      default: RP
    FundamentalsRequest:
      type: object
      title: Fundamentals Request
      description: Wrapper for fundamentals request body.
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/FundamentalsRequestBody'
    Currency:
      type: string
      title: Currency
      description: ISO 4217 currency code. Use "DOC" for reporting currency. Defaults to LOCAL.
      default: LOCAL
      examples:
      - USD
      - EUR
      - LOCAL
    Fundamental:
      type: object
      title: Fundamental
      description: A single fundamental data point representing a metric value for a specific security, fiscal period, and periodicity.
      properties:
        requestId:
          type: string
          description: Identifier that was used for the request.
          examples:
          - FDS-US
        fsymId:
          type:
          - string
          - 'null'
          description: FactSet Regional Security Identifier. Six alpha-numeric characters, excluding vowels, with an -R suffix (XXXXXX-R).
          examples:
          - SQFMK3-R
        metric:
          type:
          - string
          - 'null'
          description: The requested metric input, representing the Fundamental Data Item.
          examples:
          - FF_SALES
        periodicity:
          type:
          - string
          - 'null'
          description: Periodicity or frequency of the fiscal periods.
          enum:
          - ANN
          - ANN_R
          - QTR
          - QTR_R
          - SEMI
          - SEMI_R
          - CAL
          - LTM
          - LTM_R
          - LTMSG
          - LTM_SEMI
          - YTD
          examples:
          - QTR
        fiscalPeriod:
          type:
          - integer
          - 'null'
          description: 'Fiscal period indicator. QUARTERLY: 1-4, SEMI-ANNUAL: 1-2, ANNUAL: 0.'
          examples:
          - 4
        fiscalYear:
          type:
          - integer
          - 'null'
          description: Fiscal year of the reported period in YYYY format.
          examples:
          - 2023
        fiscalPeriodLength:
          type:
          - integer
          - 'null'
          description: Length of the fiscal period in days.
          examples:
          - 91
        fiscalEndDate:
          type:
          - string
          - 'null'
          format: date
          description: The normalized date the fiscal period ended in YYYY-MM-DD format.
          examples:
          - '2023-12-31'
        reportDate:
          type:
          - string
          - 'null'
          format: date
          description: The date the reported fiscal period ended.
          examples:
          - '2023-12-30'
        epsReportDate:
          type:
          - string
          - 'null'
          format: date
          description: The date the EPS was reported for the requested periodicity.
          examples:
          - '2024-02-24'
        updateType:
          type:
          - string
          - 'null'
          description: Update type. Preliminary indicates limited data; Final indicates full financial statement data.
          enum:
          - Preliminary
          - Final
          examples:
          - Final
        currency:
          type:
          - string
          - 'null'
          description: ISO 4217 currency code for the data values.
          examples:
          - USD
        value:
          description: Value of the data metric requested. The type varies depending on the metric - may be a number (double) or string.
          oneOf:
          - type: 'null'
          - type: string
          - type: number
            format: double
          example: example_value
    BatchStatusResponse:
      type: object
      title: Batch Status Response
      description: Wrapper for batch request status.
      properties:
        data:
          $ref: '#/components/schemas/BatchStatus'
    BatchFlag:
      type: string
      title: Batch Flag
      description: Enable asynchronous batch processing. Y = Enable, N = Disable.
      enum:
      - Y
      - N
      default: N
    SecurityIds:
      type: array
      title: Security Identifiers
      description: List of security identifiers. Accepted types include Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids. Limit of 1,000 per non-batch request / 30,000 per batch request.
      items:
        type: string
      minItems: 1
      maxItems: 30000
      examples:
      - - FDS-US
      - - FDS-US
        - AAPL-US
        - MSFT-US
    FinancialStatementsRequest:
      type: object
      title: Financial Statements Request
      description: Wrapper for financial statements request body.
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/FinancialStatementsRequestBody'
    MetricsList:
      type: array
      title: Metrics List
      description: List of fundamental metric identifiers. Use the /metrics endpoint for a complete catalog of available items.
      items:
        type: string
      minItems: 1
      maxItems: 1600
      examples:
      - - FF_SALES
      - - FF_SALES
        - FF_EPS
        - FF_PE
    FundamentalsResponse:
      type: object
      title: Fundamentals Response
      description: Response wrapper containing an array of fundamental data items.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Fundamental'
          example: []
  responses:
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthenticated USERNAME-SERIAL. Ensure you are logged in and have successfully generated an API KEY for the IP range you are connecting from.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: Unsupported Media Type. Ensure that the Content-Type header is set to "application/json".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request. This can occur for several reasons. Please review the error message for details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The USERNAME-SERIAL attempted to request the endpoint is not authorized to access. Please reach out to FactSet Account Team for assistance with authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BatchAccepted:
      description: Batch request has been accepted for processing.
      headers:
        Location:
          description: Path to batch request status endpoint.
          schema:
            type: string
          example: batch-status?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BatchStatusResponse'
  parameters:
    statementCategory:
      name: category
      in: query
      required: false
      description: Filter financial statements by type. INCOME_STATEMENT for revenue and earnings data, BALANCE_SHEET for assets and liabilities, CASH_FLOW for cash flow activities, FINANCIAL_SERVICES for financial institution specific items.
      schema:
        type: string
        enum:
        - INCOME_STATEMENT
        - BALANCE_SHEET
        - CASH_FLOW
        - FINANCIAL_SERVICES
    fiscalPeriodStart:
      name: fiscalPeriodStart
      in: query
      required: false
      description: The fiscal period start expressed as YYYY-MM-DD. Calendar date that will fall back to the most recent completed period during resolution.
      schema:
        type: string
        format: date
        examples:
        - '2023-01-01'
    periodicity:
      name: periodicity
      in: query
      required: false
      description: Periodicity or frequency of the fiscal periods. ANN = Annual Original, ANN_R = Annual Latest (includes restatements), QTR = Quarterly Original, QTR_R = Quarterly Latest, SEMI = Semi-Annual, SEMI_R = Semi-Annual Latest, LTM = Last Twelve Months, LTM_R = Last Twelve Months Latest, LTMSG = Last Twelve Months Global, LTM_SEMI = Last Twelve Months Semi-Annual, YTD = Year-to-date.
      schema:
        type: string
        enum:
        - ANN
        - ANN_R
        - QTR
        - QTR_R
        - SEMI
        - SEMI_R
        - LTM
        - LTM_R
        - LTMSG
        - LTM_SEMI
        - YTD
        default: ANN
    metrics:
      name: metrics
      in: query
      required: true
      explode: false
      description: Requested list of Financial Statement Items or Ratios. Use the `/metrics` endpoint for a complete list of available FF_* metric items. When requesting multiple metrics, you cannot mix metric data types (e.g. strings and floats). Limit of 1,600 per request.
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 1600
        examples:
        - - FF_SALES
        - - FF_SALES
          - FF_EPS
          - FF_PE
    currency:
      name: currency
      in: query
      required: false
      description: Currency code for currency values. For a list of currency ISO codes, visit Online Assistant Page 1470. Use "DOC" for reporting currency. Defaults to LOCAL.
      schema:
        type: string
        default: LOCAL
        examples:
        - USD
        - EUR
        - GBP
    fiscalPeriodEnd:
      name: fiscalPeriodEnd
      in: query
      required: false
      description: The fiscal period end expressed as YYYY-MM-DD. Calendar date that will fall back to the most recently completed period during resolution.
      schema:
        type: string
        format: date
        examples:
        - '2024-01-01'
    updateType:
      name: updateType
      in: query
      required: false
      description: Update status flag. RP = Include preliminary data, RF = Only final data.
      schema:
        type: string
        enum:
        - RP
        - RF
        default: RP
    batch:
      name: batch
      in: query
      required: false
      description: Enables asynchronous batch processing, supporting long-running requests up to 20 minutes. Upon requesting batch=Y, the service will respond with HTTP 202. Use batch-status to check completion and batch-result to retrieve results.
      schema:
        type: string
        enum:
        - Y
        - N
        default: N
    ids:
      name: ids
      in: query
      required: true
      explode: false
      description: The requested list of security identifiers. Accepted ID types include Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids. Limit of 1,000 per non-batch request / 2,000 per batch request (GET) or 30,000 per batch request (POST).
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 2000
      examples:
        singleId:
          summary: One equity identifier
          value:
          - AAPL-US
        multipleIds:
          summary: Multiple equity identifiers
          value:
          - FDS-US
          - AAPL-US
          - MSFT-US
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation