FactSet Entity Report Builder API

openapi: 3.0.3
info:
  title: FactSet Entity Report Builder
  description: ''
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
servers:
  - url: https://api.factset.com/report/entity/v1
externalDocs:
  description: Read more about STACH 2.0's row organized schema
  url: https://factset.github.io/stachschema/#/v2/RowOrganized
tags:
  - name: Structure
paths:
  /structure:
    get:
      tags:
        - Structure
      operationId: getEntityStructureStructure
      summary: Factset Entity structure
      description: Returns full entity tree for table and tree display
      parameters:
        - $ref: '#/components/parameters/idParameter'
        - $ref: '#/components/parameters/schemaParameter'
      responses:
        '200':
          $ref: '#/components/responses/200OK'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
security:
  - basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  parameters:
    idParameter:
      name: id
      in: query
      description: Company ticker
      required: true
      schema:
        type: string
        example: FDS
    schemaParameter:
      name: schema
      in: query
      description: >
        The schema that the data is returned as. The following are descriptions
        for the accepted values:

        - table_group_level - STACH 2.0 row organized package format with
        parent-child relationships represented using STACH group level cell
        metadata

        - table_parent_child_columns - STACH 2.0 row organized package format
        with parent-child relationships represented using STACH parent-child
        columns

        - tree - Entities are represented as tree nodes returned in a flat
        structure, where each parent node contains a children attribute pointing
        to its child nodes
      required: false
      schema:
        type: string
        enum:
          - table_group_level
          - table_parent_child_columns
          - tree
        default: table_parent_child_columns
  responses:
    200OK:
      description: Expected response
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
        Api-Supported-Versions:
          schema:
            type: string
          description: Supported API major versions
        Api-Version:
          schema:
            type: string
          description: API version (semantic versioning)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Response'
          examples:
            groupLevelResponse:
              $ref: '#/components/examples/groupLevelResponse'
            parentChildColumnsResponse:
              $ref: '#/components/examples/parentChildColumnsResponse'
            treeResponse:
              $ref: '#/components/examples/treeResponse'
    400BadRequest:
      description: >-
        Bad Request. For further assistance, file an issue under "Workflow &
        Throttling - 400 or 429 Response" using `Report Issue` at the top of
        this page, including the X-DataDirect-Request-Key from the header to
        assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
        Api-Supported-Versions:
          schema:
            type: string
          description: Supported API versions (semantic versioning)
        Api-Version:
          schema:
            type: string
          description: API version (semantic versioning)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            idRequiredParameterError:
              $ref: '#/components/examples/idRequiredParameterError'
            idInvalidParameterError:
              $ref: '#/components/examples/idInvalidParameterError'
            schemaInvalidParameterError:
              $ref: '#/components/examples/schemaInvalidParameterError'
    401Unauthorized:
      description: >-
        Missing or invalid authentication. Ensure you are logged in and have
        successfully generated an API KEY for the IP range you are connecting
        from. For further assistance, file an issue under "Connectivty - 401 or
        403 Responses" using `Report Issue` at the top of this page, including
        the X-DataDirect-Request-Key from the header to assist in
        troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
    403Forbidden:
      description: >-
        User is forbidden access with current credentials. Reach out to your
        local FactSet Account Manager for assistance, or file an issue under
        "Connectivty - 401 or 403 Responses" using `Report Issue` at the top of
        this page, including the X-DataDirect-Request-Key from the header to
        assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            notAuthorized:
              $ref: '#/components/examples/notAuthorized'
    404NotFound:
      description: >-
        Not found. For further assistance, file an issue under "Performance -
        404 and 500 Responses" using `Report Issue` at the top of this page,
        including the X-DataDirect-Request-Key from the header to assist in
        troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            endpointNotFound:
              $ref: '#/components/examples/endpointNotFound'
    429TooManyRequests:
      description: >-
        Too many requests - this API is rate-limited to 20 requests per second.
        For further assistance, file an issue under "Workflow & Throttling - 400
        or 429 Response" using `Report Issue` at the top of this page, including
        the X-DataDirect-Request-Key from the header to assist in
        troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
    500InternalServerError:
      description: >-
        Server error. For further assistance, file an issue under "Performance -
        404 and 500 Responses" using `Report Issue` at the top of this page,
        including the X-DataDirect-Request-Key from the header to assist in
        troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            genericServerError:
              $ref: '#/components/examples/genericServerError'
    503ServiceUnavailable:
      description: >-
        Service unavailable. Typically a timeout, or result of a rejected
        request to prevent service overload. For further assistance, file an
        issue under "Performance - 404 and 500 Responses" using `Report Issue`
        at the top of this page, including the X-DataDirect-Request-Key from the
        header to assist in troubleshooting.
      headers:
        X-DataDirect-Request-Key:
          schema:
            type: string
          description: FactSet request ID
  examples:
    groupLevelResponse:
      summary: (sample table group level response)
      description: >-
        Subset of rows and columns for an example STACH 2.0 row organized
        package format table group level response
      value:
        data:
          version: '2.0'
          tables:
            main:
              definition:
                columns:
                  - id: entityID
                    type: string
                    isDimension: true
                  - id: name
                    type: string
                  - id: country
                    type: string
                  - id: entityType
                    type: string
              headersDefinition:
                columns:
                  - id: entityTableHeader
                    type: string
                    isDimension: true
              data:
                rows:
                  - rowType: Header
                    cells:
                      - ID
                      - Name
                      - Country
                      - Entity Type
                    headerCellDetails:
                      '0':
                        source: HEADERS
                        columnIndex: 0
                      '1':
                        source: HEADERS
                        columnIndex: 0
                      '2':
                        source: HEADERS
                        columnIndex: 0
                      '3':
                        source: HEADERS
                        columnIndex: 0
                  - cells:
                      - 0016YD-E
                      - FactSet Research Systems, Inc.
                      - United States
                      - PUB
                  - cells:
                      - 003S32-E
                      - P.A.N. Securities LP
                      - United States
                      - SUB
                    cellDetails:
                      '0':
                        groupLevel: '1'
                  - cells:
                      - 007F37-E
                      - Portware LLC
                      - United States
                      - SUB
                    cellDetails:
                      '0':
                        groupLevel: '1'
                  - cells:
                      - 0CK25T-E
                      - Aritas Group, Inc. /Technology & Analytical Business/
                      - United States
                      - COR
                    cellDetails:
                      '0':
                        groupLevel: '2'
                  - cells:
                      - 0DV5KG-E
                      - Long Ridge Portware Holdings, Inc.
                      - United States
                      - EXT
                    cellDetails:
                      '0':
                        groupLevel: '2'
                  - cells:
                      - 0GV04X-E
                      - Portware India Pvt Ltd.
                      - India
                      - SUB
                    cellDetails:
                      '0':
                        groupLevel: '2'
                  - cells:
                      - 0GV04Y-E
                      - Portware International LLC
                      - United States
                      - SUB
                    cellDetails:
                      '0':
                        groupLevel: '2'
                  - cells:
                      - 0G910J-E
                      - Portware International LLC (United Kingdom)
                      - United Kingdom
                      - SUB
                    cellDetails:
                      '0':
                        groupLevel: '3'
        meta:
          requestId: FDS-US
          fsymId: SQFMK3-R
          schema: table_group_level
    parentChildColumnsResponse:
      summary: (sample table parent child columns response)
      description: >-
        Subset of rows and columns for an example STACH 2.0 row organized
        package format table parent child columns response
      value:
        data:
          version: '2.0'
          tables:
            main:
              definition:
                columns:
                  - id: entityLevel0
                    type: string
                    isDimension: true
                  - id: entityLevel1
                    type: string
                    isDimension: true
                    parentId: entityLevel0
                  - id: entityLevel2
                    type: string
                    isDimension: true
                    parentId: entityLevel1
                  - id: entityLevel3
                    type: string
                    isDimension: true
                    parentId: entityLevel2
                  - id: name
                    type: string
                  - id: country
                    type: string
                  - id: entityType
                    type: string
              headersDefinition:
                columns:
                  - id: entityTableHeader
                    type: string
                    isDimension: true
              data:
                rows:
                  - rowType: Header
                    cells:
                      - 
                      - 
                      - 
                      - 
                      - Name
                      - Country
                      - Entity Type
                    headerCellDetails:
                      '0':
                        source: HEADERS
                        columnIndex: 0
                      '1':
                        source: HEADERS
                        columnIndex: 0
                      '2':
                        source: HEADERS
                        columnIndex: 0
                      '3':
                        source: HEADERS
                        columnIndex: 0
                      '4':
                        source: HEADERS
                        columnIndex: 0
                      '5':
                        source: HEADERS
                        columnIndex: 0
                      '6':
                        source: HEADERS
                        columnIndex: 0
                  - cells:
                      - 0016YD-E
                      - 
                      - 
                      - 
                      - FactSet Research Systems, Inc.
                      - United States
                      - PUB
                  - cells:
                      - 0016YD-E
                      - 003S32-E
                      - 
                      - 
                      - P.A.N. Securities LP
                      - United States
                      - SUB
                  - cells:
                      - 0016YD-E
                      - 007F37-E
                      - 
                      - 
                      - Portware LLC
                      - United States
                      - SUB
                  - cells:
                      - 0016YD-E
                      - 007F37-E
                      - 0CK25T-E
                      - 
                      - Aritas Group, Inc. /Technology & Analytical Business/
                      - United States
                      - COR
                  - cells:
                      - 0016YD-E
                      - 007F37-E
                      - 0DV5KG-E
                      - 
                      - Long Ridge Portware Holdings, Inc.
                      - United States
                      - EXT
                  - cells:
                      - 0016YD-E
                      - 007F37-E
                      - 0GV04X-E
                      - 
                      - Portware India Pvt Ltd.
                      - India
                      - SUB
                  - cells:
                      - 0016YD-E
                      - 007F37-E
                      - 0GV04Y-E
                      - 
                      - Portware International LLC
                      - United States
                      - SUB
                  - cells:
                      - 0016YD-E
                      - 007F37-E
                      - 0GV04Y-E
                      - 0G910J-E
                      - Portware International LLC (United Kingdom)
                      - United Kingdom
                      - SUB
        meta:
          requestId: FDS-US
          fsymId: SQFMK3-R
          schema: table_parent_child_columns
    treeResponse:
      summary: (sample tree response)
      description: Subset of rows and columns for an example response
      value:
        data:
          root: 0016YD-E
          0016YD-E:
            name: FactSet Research Systems, Inc.
            country: United States
            entityType: PUB
            parent:
            children:
              - 003S32-E
              - 007F37-E
              - 007FCX-E
          003S32-E:
            name: P.A.N. Securities LP
            country: United States
            entityType: SUB
            parent: 0016YD-E
          007F37-E:
            name: Portware LLC
            country: United States
            entityType: SUB
            parent: 0016YD-E
            children:
              - 0CK25T-E
              - 0DV5KG-E
              - 0GV04X-E
              - 0GV04Y-E
              - 0MLMTB-E
          0CK25T-E:
            name: Aritas Group, Inc. /Technology & Analytical Business/
            country: United States
            entityType: COR
            parent: 007F37-E
          0DV5KG-E:
            name: Long Ridge Portware Holdings, Inc.
            country: United States
            entityType: EXT
            parent: 007F37-E
          0GV04X-E:
            name: Portware India Pvt Ltd.
            country: India
            entityType: SUB
            parent: 007F37-E
          0GV04Y-E:
            name: Portware International LLC
            country: United States
            entityType: SUB
            parent: 007F37-E
            children:
              - 0G910J-E
              - 0GV051-E
          0G910J-E:
            name: Portware International LLC (United Kingdom)
            country: United Kingdom
            entityType: SUB
            parent: 0GV04Y-E
          0GV051-E:
            name: Portware International LLC (Hong Kong Branch)
            country: Hong Kong
            entityType: SUB
            parent: 0GV04Y-E
          0MLMTB-E:
            name: Portware Singapore
            country: Singapore
            entityType: SUB
            parent: 007F37-E
          007FCX-E:
            name: Code Red, Inc.
            country: United States
            entityType: SUB
            parent: 0016YD-E
        meta:
          requestId: FDS-US
          fsymId: SQFMK3-R
          schema: tree
    genericServerError:
      summary: generic server error
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: genericServerError
            title: Unexpected error processing request
    parameterError:
      summary: generic parameter error
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: Missing or invalid parameters
    parameterErrorMissing:
      summary: missing required parameter
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Missing required parameter(s): ''id'''
    notAuthorized:
      summary: not authorized
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: notAuthorized
            title: >-
              User is forbidden access with current credentials. For access,
              contact your FactSet sales representative
    endpointNotFound:
      summary: endpoint not found
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: endpointNotFound
            title: The requested endpoint does not exist.
    idRequiredParameterError:
      summary: missing id parameter
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Missing required parameter(s): ''id'''
    idInvalidParameterError:
      summary: invalid id parameter
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Invalid parameter(s): ''id'''
    schemaInvalidParameterError:
      summary: invalid schema parameter
      value:
        errors:
          - id: 39314614-e607-465a-ba95-5bb79c362e23
            code: parameterError
            title: 'Invalid parameter: ''schema'''
  schemas:
    Response:
      type: object
      properties:
        data:
          title: STACH
          description: Returns a STACH 2.0 row organized package
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      additionalProperties:
        type: string
        nullable: true
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorObject:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        title:
          type: string
        links:
          type: object
          properties:
            about:
              type: string
        detail:
          type: string
        source:
          type: object
          properties:
            parameter:
              type: string
    MetadataEntry:
      type: object
      description: >
        Restricted metadata entries. Restricts the possible key in the following
        STACH schema:

        - RowOrganizedPackage.CellDetail.CellMetadataEntry

        - RowOrganizedPackage.HeaderCellDetail.CellMetadataEntry

        - RowOrganizedPackage.MapOfMetadata.ItemsEntry

        - RowOrganizedPackage.Row.RowMetadataEntry

        - RowOrganizedPackage.TableData.TableMetadataEntry

        And sets restrictions on the possible values for a MetadataItem.
      oneOf:
        - $ref: '#/components/schemas/currencyCode'
        - $ref: '#/components/schemas/currencySymbol'
        - $ref: '#/components/schemas/category'
        - $ref: '#/components/schemas/valueType'
        - $ref: '#/components/schemas/scale'
        - $ref: '#/components/schemas/description'
        - $ref: '#/components/schemas/frequency'
    currencyCode:
      type: object
      properties:
        currencyCode:
          type: object
          description: Code for data currency
          properties:
            value:
              type: string
    currencySymbol:
      type: object
      properties:
        currencySymbol:
          type: object
          description: Symbol for data currency
          properties:
            value:
              type: string
    category:
      type: object
      properties:
        category:
          type: object
          description: >
            Describes data based on source or kind of value

            - ACTUAL - Historical data collected directly from a press release
            or a median consensus from brokers after a report date.

            - ESTIMATE - Forward looking average of broker estimates within a
            specific time horizon.

            - GUIDANCE - Forward looking indication or estimate of future
            performance issued by the company itself.

            - DETAIL - Indicates data that is more granular and may be secondary
            in focus.

            - MAIN - Indicates data is of more impactful or higher importance
            and may want to be emphasized.

            - SECTION - Indicates data that is used in sectioning rows in group
            level STACH format.
          properties:
            value:
              type: string
              enum:
                - ACTUAL
                - ESTIMATE
                - GUIDANCE
                - EXCLUDED
                - CHANGE
                - DETAIL
                - MAIN
                - SECTION
    valueType:
      type: object
      properties:
        valueType:
          type: object
          description: Describes how to interpret numbers
          properties:
            value:
              type: string
              enum:
                - PERCENTAGE
                - RATIO
                - TREND
                - RANGE
    scale:
      type: object
      properties:
        scale:
          type: object
          description: >
            Integer power of 10 to which numbers have been scaled. For example:
            6 implies millions.

            Default is 0.
          properties:
            value:
              type: integer
    description:
      type: object
      properties:
        description:
          type: object
          description: Text describing the data
          properties:
            value:
              type: string
    frequency:
      type: object
      properties:
        frequency:
          type: object
          description: |
            String with frequency of a data series. Allowed values:
            - "D" (daily)
            - "W" (weekly)
            - "AW" (actual weekly)
            - "M" (monthly)
            - "AM" (actual monthly)
            - "Q" (quarterly)
            - "FQ" (fiscal quarterly)
            - "CQ" (calendar quarterly)
            - "AQ" (actual quarterly)
            - "Y" (yearly)
            - "FY" (fiscal yearly)
            - "CY" (calendar yearly)
            - "AY" (actual yearly)
            - "MTD" (month-to-date)
            - "QTD" (quarter-to-date)
            - "YTD" (year-to-date)
            - "FYTD" (fiscal-year-to-date)
            - "CYTD" (calendar-year-to-date)
          properties:
            value:
              type: string
              enum:
                - D
                - W
                - AW
                - M
                - AM
                - Q
                - FQ
                - CQ
                - AQ
                - 'Y'
                - FY
                - CY
                - AY
                - MTD
                - QTD
                - YTD
                - FYTD
                - CYTD