Factset Search API

openapi: 3.2.0
info:
  title: Factset Global Filings Search API
  version: 0.0.0
  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: The Filings API provides a comprehensive set of functionalities for searching and retrieving filing documents from various sources.
servers:
- url: https://api.factset.com/global-filings/v0
security:
- FactSetApiKey: []
- FactSetOAuth2: []
tags:
- name: Search
paths:
  /search:
    get:
      summary: Returns the filings documents and related metadata within FactSet coverage
      tags:
      - Search
      responses:
        '200':
          description: Array of downloadable URLs consisting of Filings documents with related metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestmentResearch'
              examples:
                Sample Response:
                  value:
                    data:
                    - headline: Zukin's Next Week Today 4/7/2023 (Wolfe Research) 97 pages
                      source: EDG
                      allIds:
                      - IBM-US
                      primaryIds:
                      - IBM-US
                      filingsDate: '20230307'
                      filingsTime: '194026'
                      categories:
                      - CN:US,DT:AN-FILNS,DT:FILNS, DT:FILNS
                      filingsLink: https://api.factset.com/v0/filings?report=story&key=U2FsdGVkX18b15tR%2bV9L1xvjo6Vnz7C7PhIbUvoMrgF%2f43aEWomYlhVruC6G6874fEX
                      documentId: 20230307-5b36f2cf-49bd-ed11-abc3-12bc89a8f273_0
                    meta:
                      pagination:
                        isEstimatedTotal: false
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                default400ResponseExample:
                  $ref: '#/components/examples/ErrorDetails'
        '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:
                default401ResponseExample:
                  $ref: '#/components/examples/AuthErrorDetails'
        '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:
                default403ResponseExample:
                  $ref: '#/components/examples/AuthorizationErrorDetails'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                default500ResponseExample:
                  $ref: '#/components/examples/ServerErrorDetails'
      operationId: getFilings
      description: Returns the filings documents within FactSet coverage along with other response fields
      parameters:
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/paginationLimit'
      - $ref: '#/components/parameters/paginationOffset'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/sourcesOne'
      - $ref: '#/components/parameters/categories'
      - $ref: '#/components/parameters/primaryId'
      - $ref: '#/components/parameters/searchText'
      - $ref: '#/components/parameters/formType'
      - $ref: '#/components/parameters/accession'
components:
  schemas:
    InvestmentResearchObject:
      type: object
      properties:
        headline:
          type: string
          description: Headline of the story, actual time and date of the event.
        source:
          type: string
          description: Provides source of the document.
        primaryIds:
          type: array
          items:
            type: string
          description: Refers to the main company a particular document refers to.
        allIds:
          type: array
          items:
            type: string
          description: Refers to all companies mentioned in the document. This could also include the primary company id as well.
        filingsDate:
          type: string
          description: Publish date of the latest version (in ET).
        filingsTime:
          type: string
          description: Publish time of the latest version (in ET).
        categories:
          type: array
          items:
            type: string
          description: Categories are country, industry, and subject codes. This is a comma-separated list.
        filingsLink:
          type: string
          description: The link to download the document.
        documentId:
          type: string
          description: Unique identifier for a document.
    ErrorExample:
      type: object
      description: Error Example Object
      properties:
        code:
          description: Specifies the error code.
          type: string
        title:
          description: ' Specifies the error message.'
          type: string
        id:
          description: Specifies the id.
          type: string
    ErrorResponse:
      type: object
      description: Error Response Object
      properties:
        errors:
          type: array
          description: Errors Array Object
          items:
            $ref: '#/components/schemas/ErrorExample'
    InvestmentResearch:
      description: Filings Response Object
      type: object
      properties:
        data:
          type: array
          description: Data Array Object
          items:
            $ref: '#/components/schemas/InvestmentResearchObject'
        meta:
          type: object
          description: Meta Object
          properties:
            pagination:
              type: object
              description: Pagination Object
              properties:
                isEstimatedTotal:
                  type: boolean
                  description: This field acts as a flag for the exact count of results and is defaulted to false as the API should always return the exact count of results.
  parameters:
    paginationOffset:
      schema:
        type: integer
        format: int32
      in: query
      name: paginationOffset
      description: Page number of the results to return.
    categories:
      schema:
        type: array
        items:
          type: string
      in: query
      name: categories
      example:
      - CN:US
      - LN:EN
      description: 'Code for categories to include.  This is a comma-separated list. Use the ```/helper``` endpoint to get the list of available categories.


        Default = All categories.'
      explode: false
    paginationLimit:
      schema:
        type: integer
        format: int32
        default: 25
      in: query
      name: paginationLimit
      example: 20
      description: Number of results to return per page.
    searchText:
      schema:
        type: string
      in: query
      name: searchText
      example: Updates
      description: Restricts the search to include only document stories which include the text searched.
    primaryId:
      schema:
        type: string
        enum:
        - Y
        - N
        default: N
      in: query
      name: primaryId
      description: 'Type of identifier search

        * Y - Returns headlines of stories that have the search ID(s) as the Primary ID.

        * N - Returns headlines of stories that mention/refer to the ID(s).'
    sort:
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
      in: query
      name: sort
      description: "Sorting the results in chronological (oldest to newest) or reverse chronological (newest to oldest) order. \n\n *  desc - sorting results in reverse chronological (descending) order. This is the default value if\n    the sort parameter isn’t used in the query\n    \n *   asc - sorting results in chronological (ascending) order. If a start date is not specified, the\n   API has a 10-year searching limitation. "
    ids:
      schema:
        type: array
        items:
          type: string
      in: query
      name: ids
      examples:
        oneId:
          summary: One identifier
          value:
          - MODN-US
        multipleIds:
          summary: Multiple Identifiers
          value:
          - MODN-US
          - OSIS-US
      description: Requested symbols or securities.  This is a comma-separated list with a maximum limit of 1000.  Each symbol can be a FactSet exchange symbol, CUSIP, or SEDOL.
      explode: false
    accession:
      schema:
        type: string
      in: query
      description: A unique identifier given to each EDGAR filings document. e.g. accession=0001013237-21-000069&sources=EDG
      name: accession
      required: false
    endDate:
      schema:
        type: string
        default: '0'
      in: query
      name: endDate
      example: '20231223'
      description: End Date. Format is YYYYMMDD or relative +/- days (0,-1,etc).
    startDate:
      schema:
        type: string
        default: '0'
      in: query
      name: startDate
      example: '20231222'
      description: Start Date. Format is YYYYMMDD or relative +/- days (0,-1,etc).
    sourcesOne:
      schema:
        type: array
        items:
          type: string
      in: query
      name: sources
      required: true
      examples:
        oneSource:
          summary: One Source
          value:
          - EDG
        multipleSources:
          summary: Multiple Sources
          value:
          - EDG
          - FFR
      description: Code for document source to include.  This is a comma-separated list. Use the ```/helper``` endpoint to get the list of available sources.
      explode: false
    formType:
      schema:
        type: string
      in: query
      description: Restricts the search to include any form types of EDGAR.
      name: formType
      required: false
    timezone:
      schema:
        type: string
        default: America/New_York
      in: query
      name: timezone
      description: Time zone to return story dates and times. Time zones are in POSIX format and automatically adjusted for daylight savings.
  examples:
    AuthErrorDetails:
      summary: Sample Error Response
      value:
        errors:
        - code: Not Authenticated
          title: Unauthenticated USERNAME-SERIAL.
          id: fd5a51ff-02cf-48ec-b9b1-913d64863b0
    ErrorDetails:
      summary: Sample Error Response
      value:
        errors:
        - code: Bad Request
          title: parameterError:['_paginationLimit'] is not a valid parameter(s).
          id: 7af3d86ca5954503b9244f2620fcf5eb
    ServerErrorDetails:
      summary: Sample Error Response
      value:
        errors:
        - code: Internal Server Error
          title: An unexpected error happened.
          id: 7af3d86ca5954503b9244f2620fcf5eb
    AuthorizationErrorDetails:
      summary: Sample Error Response
      value:
        errors:
        - code: Forbidden
          title: USERNAME-SERIAL does not have permission.
          id: 7af3d86ca5954503b9244f2620fcf5eb
  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/global-filings-api