openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Idsearch 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: Idsearch
paths:
  /v1/idsearch:
    post:
      tags:
      - Idsearch
      summary: Search Funtionality to Return Tickers, Company Names and Unique Identifiers for Factset Data
      description: 'Service will accept request in JSON formatted request body. The request is sent by passing a query which is an array conitaining search query objects with parameters. The parameters contain search term and filters defined by the end user. This would display a specific set of identifiers based on the request.

        '
      operationId: search companyname
      requestBody:
        description: Post body to lookup any FactSet identifiers
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lookup_request'
            examples:
              ID search Basic Example (equities):
                $ref: '#/components/examples/lookup_basicrequest_equities'
              ID search Basic Example (bonds):
                $ref: '#/components/examples/lookup_basicrequest_bonds'
              ID search Basic Example (private companies):
                $ref: '#/components/examples/lookup_basicrequest_private_companies'
              ID search Example using Filters:
                $ref: '#/components/examples/lookup_filtersrequest'
              Sample query using OR logic:
                $ref: '#/components/examples/lookup_orlogicrequest'
              Sample query using both OR & AND:
                $ref: '#/components/examples/lookup_orandlogicrequest'
        required: true
      responses:
        '200':
          description: A list of securities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lookup_response'
              examples:
                ID search Basic Response (equities):
                  $ref: '#/components/examples/lookup_basicresponse_equities'
                ID search Basic Response (bonds):
                  $ref: '#/components/examples/lookup_basicresponse_bonds'
                ID search Basic Response (private companies):
                  $ref: '#/components/examples/lookup_basicresponse_private_companies'
                ID search Response using filters:
                  $ref: '#/components/examples/lookup_filtersresponse'
                Sample response using OR logic:
                  $ref: '#/components/examples/lookup_orlogicresponse'
                Sample response using both OR & AND:
                  $ref: '#/components/examples/lookup_orandlogicresponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    lookup_response:
      title: Lookup Response
      type: object
      properties:
        typeahead:
          $ref: '#/components/schemas/lookup_count'
      description: Response object for a lookup request
    lookup_request:
      title: Lookup Request
      type: object
      properties:
        query:
          $ref: '#/components/schemas/lookup_object'
        settings:
          $ref: '#/components/schemas/lookup_limit'
      description: Lookup Request comprised of a single lookup object
    response_details:
      title: Response Details
      type: object
      properties:
        index:
          type: string
          description: Type of Asset Class
          example: equities
        symbol:
          type: string
          description: 'Symbol is the only value that should be passed back to any FactSet services to retrieve data

            '
          example: FDS-US
        name:
          type: string
          description: Name of the related entity
          example: Factset Research Systems Inc
        entity_id:
          type: string
          description: 'Displays Entity ID''s for public companies and only if the asset class is equities

            '
          example: 00BDWZ-E
    lookup_object:
      title: Lookup Object
      type: object
      properties:
        pattern:
          title: Search term
          type: string
          description: 'The string or keyword being searched on. Concurrent searches for multiple patterns is NOT supported

            '
          example: US
        entities:
          title: Asset Class
          type: array
          description: Asset class that is being searched against
          example:
          - bonds
          items:
            type: string
        filters:
          $ref: '#/components/schemas/filter_params'
    errorResponse:
      type: object
      title: Error Response
      properties:
        description:
          type: string
          example: A sample description.
        RequestKey:
          type: string
          example: example_value
    filter_params:
      title: Filter Parameters
      type: object
      properties:
        include:
          type: array
          description: This parameter filter objects to be included in the results
          items:
            $ref: '#/components/schemas/include_exclude_object'
          example: []
        exclude:
          type: array
          description: This parameter filter objects to be excluded from the results
          example: []
          items:
            $ref: '#/components/schemas/include_exclude_object'
      description: 'The filters parameter (if used) must contain one or both of theinlcude and exclude filters

        '
    lookup_assettype:
      title: Lookup Asset Type
      type: object
      properties:
        people:
          type: integer
          example: 10
      description: returns the count of assest classes
    lookup_limit:
      title: Lookup Limit
      type: object
      properties:
        result_limit:
          type: integer
          example: 25
      description: 'This parameters takes the value for number of results to be returnedby search. Maximum number of results returned are 25 and default value is 10.

        '
    include_exclude_object:
      title: Include Exclude Object
      type: object
      properties:
        field:
          type: string
          description: 'String containing the field name to filter on. Each asset class has its own set of field (i.e. equity_type, is_primary, region,etc)

            '
          example: maturity_year
        entity:
          type: string
          description: 'String containing the asset class for the filter to be applied on. If not included or left empty, it will apply the filter against all asset classes

            '
          example: bonds
        values:
          type: array
          description: 'Values you wish to filter on, as a comma-separated list. The values within this list are tied by an OR operation.

            '
          items:
            type: object
            example: '2021'
          example: []
      description: 'Filters securities based on asset classes and other fields depending on the asset classes.

        '
    lookup_count:
      title: Lookup Count
      type: object
      properties:
        result_count:
          $ref: '#/components/schemas/lookup_assettype'
        error:
          type: string
          example: null
        is_success:
          type: integer
          example: 1
        results:
          type: array
          description: Array of Lookup details for the query
          items:
            $ref: '#/components/schemas/response_details'
          example: []
      description: Returns the count of on entities
  examples:
    lookup_filtersrequest:
      summary: ID search Example using Filters
      description: ID search Example using Filters
      value:
        query:
          pattern: us
          entities:
          - bonds
          filters:
            include:
            - field: maturity_year
              entity: bonds
              values:
              - 2021
            exclude: []
        settings:
          result_limit: 25
    lookup_orandlogicresponse:
      summary: sample response using both OR & AND logic
      description: sample response using both OR & AND logic
      value:
        typeahead:
          result_count:
            equities: 10
          error: 'null'
          is_succes: 1
          results:
          - index: equities
            symbol: CPIC-GB
            name: China pacific Insurance (Group) co.,Ltd.Sponsored GDR Class A RegS
            entity_id: 06BF43-E
          - index: equities
            symbol: PJP-DE
            name: XS Retail Group N.V. Sponsored GDR RegS
            entity_id: 06L75Z-E
    lookup_basicresponse_equities:
      summary: ID search Basic Response for entity type as equities
      description: ID search Basic Response for entity type as equities
      value:
        typeahead:
          result_count:
            equities: 25
          error: 'null'
          is_success: 1
          results:
          - index: equities
            symbol: A-US
            name: Agilent Technologies,Inc.
            entity_id: 002LV5-E
          - index: equities
            symbol: AAPL-US
            name: Apple Inc.
            entity_id: 000C7F-E
    lookup_basicrequest_private_companies:
      summary: ID search Basic Example for entity type as private_companies
      description: ID search Basic Example for entity type as private_companies
      value:
        query:
          pattern: group
          entities:
          - private_companies
        settings:
          result_limit: 25
    lookup_basicrequest_equities:
      summary: ID search Basic Example for entity type as equities
      description: ID search Basic Example for entity type as equities
      value:
        query:
          pattern: A
          entities:
          - equities
        settings:
          result_limit: 25
    lookup_basicresponse_private_companies:
      summary: ID search Basic Response for entity type as private_companies
      description: ID search Basic Response for entity type as private_companies
      value:
        typeahead:
          result_count:
            private_companies: 25
          error: 'null'
          is_success: 1
          results:
          - index: private_companies
            symbol: 0DRWHW-E
            name: BEWiSynbra Group AB
            fds_id: 0DRWHW-E
          - index: private_companies
            symbol: 0DD45D-E
            name: Shawbrook Group Plc
            fds_id: 0DD45D-E
    lookup_orlogicrequest:
      summary: Sample query using OR logic
      description: Sample query using OR logic
      value:
        query:
          pattern: air
          entities:
          - equities
          - private_companies
    badRequest:
      summary: Bad Request
      value:
        description: Bad Request. Please check your query again.
    generalException:
      summary: Internal Server Error
      value:
        description: The service you have requested has encountered an error. If the problem persists, please contact the FactSet support representative with the following request key
        Requestkey: ACBL05BJKLYNBGY-L
    forbidden:
      summary: Forbidden
      value:
        description: The user does not have permission to search. Please try again.
    unauthenticated:
      summary: User Authentication Failed
      value:
        description: User Authentication Failed
    lookup_basicrequest_bonds:
      summary: ID search Basic Example for entity type as  bonds
      description: ID search Basic Example for entity type as bonds
      value:
        query:
          pattern: Bank
          entities:
          - bonds
        settings:
          result_limit: 25
    lookup_basicresponse_bonds:
      summary: ID search Basic Response for entity type as bonds
      description: ID search Basic Response for entity type as bonds
      value:
        typeahead:
          result_count:
            bonds: 25
          error: 'null'
          is_success: 1
          results:
          - index: bonds
            symbol: XS2027359756
            name: Vietnam Prosperity Joint-Stock Commercial Bank 6.25% 17-JUL-2022
            ticker: XS2027359756
          - index: bonds
            symbol: XS2058731717
            name: Shinhan Bank Co., Ltd. 0.25% 16-OCT-2024
            ticker: XS2058731717
    lookup_orlogicresponse:
      summary: sample response using OR logic
      description: sample response using OR logic
      value:
        typeahead:
          result_count:
            private_companies: 10
            equities: 10
          error: 'null'
          is_success: 1
          results:
          - index: equities
            symbol: AIR-US
            name: AAR CORP
            entity_id: 000BFS-E
          - index: private_companies
            name: Air Products GmbH
            entity_id: 05MR9R-E
    lookup_orandlogicrequest:
      summary: Sample query using both OR & AND logic
      description: Sample query using both OR & And logic
      value:
        query:
          pattern: group
          entities:
          - equities
          filters:
            include:
            - field: equity_type
              entity: equities
              values:
              - EQ_DR_GDR
            - field: region
              values:
              - GB
              - DE
            exclude: []
    lookup_filtersresponse:
      summary: ID search response using Filters
      description: ID search response using Filters
      value:
        typeahead:
          result_count:
            bonds: 10
          error: 'null'
          is_succes: 1
          results:
          - index: bonds
            symbol: FDS-US
            name: Factset Research Systems Inc
            entity_id: 00BDWZ-E
  responses:
    '401':
      description: Authentication issue
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Authentication:
              $ref: '#/components/examples/unauthenticated'
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Authorization:
              $ref: '#/components/examples/forbidden'
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Internal Server Error - General Exception:
              $ref: '#/components/examples/generalException'
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request:
              $ref: '#/components/examples/badRequest'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation