Factset Universe API

openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Universe 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: Universe
paths:
  /factset-private-markets/v1/universe:
    get:
      summary: Factset Get Entity Candidates and Matches for a Single Name and Attributes.
      description: 'Finds the best candidate entities matching the given entity name. Country code can also be supplied to narrow the search. <p>**Max of 1 Name permitted in a single GET request.** Use the POST method for /entity-match to fetch up to 25 names.</p><p>

        '
      tags:
      - Universe
      operationId: getUniverse
      parameters:
      - $ref: '#/components/parameters/name'
      - $ref: '#/components/parameters/country'
      responses:
        '200':
          $ref: '#/components/responses/EntityMatchResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Factset Get a List of Entity Candidates and Matches for a Requested List of up to 25 Names and Attributes.
      description: 'Finds the best candidate entities matching the given entity name. Country code can also be supplied to narrow the search. Finds the best candidate entities matching the given company name. <p>**Max of 25 Names inputted.**</p><p>

        '
      tags:
      - Universe
      operationId: getUniverseForList
      requestBody:
        required: true
        description: A request to match an Entity.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityMatchRequest'
      responses:
        '200':
          $ref: '#/components/responses/EntityMatchResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  examples:
    EntityMatches:
      description: Entity Matches
      value:
        data:
        - entityId: 00161G-E
          entityName: Cargill, Inc.
          countryCode: US
          entityTypeCode: PVT
    badRequestInvalidParameters:
      summary: Bad Request - Passing Invalid Parameter
      description: This error message occurs when user is passing an Invalid Parameter
      value:
        status: Bad Request
        timestamp: '2020-07-23 11:03:40.765'
        path: /factset-private-markets/v1/{endpoint}
        message: 'Invalid Parameter (s): fakeParameter. Please modify your request to use parameters outlined in the specification for this endpoint.'
        subErrors: null
    badRequestDateFormat:
      summary: Bad Request - Date Format
      description: This bad request occurs when a request doesn't use the YYYY-MM-DD in the date parameters. To resolve, convert your date to YYYY-MM-DD.
      value:
        status: Bad Request
        timestamp: '2020-07-02 11:52:36.464'
        path: /factset-private-markets/v1/{endpoint}
        message: 'The date parameter must be in the following date format: YYYY-MM-DD'
        subErrors: null
    notWritable:
      summary: Internal Server Error - Not Writable
      description: This error may be returned when the server encounters an error writing the JSON response.
      value:
        status: Internal Server Error
        timestamp: '2020-07-02 09:48:29.18'
        path: /factset-private-markets/v1/{endpoint}
        message: Error writing JSON output
        subErrors: null
    unsupportedMediaType:
      summary: Unsupported Media Type
      description: This bad request occurs when the media type passed in the request is not supported. Currently the APIs only support 'application/json'.
      value:
        status: Unsupported Media Type
        timestamp: '2020-07-02 09:42:27.237'
        path: /factset-private-markets/v1/{endpoint}
        message: text/html media type is not supported. Supported media types are application/json.
        subErrors: null
    generalException:
      summary: Internal Server Error - General Exception
      description: This is the most general error that can be returned to by the service. Please `Report Issue` to FactSet.
      value:
        status: Internal Server Error
        timestamp: '2020-07-02 10:36:01.944'
        path: /factset-private-markets/v1/{endpoint}
        message: Unexpected error
        subErrors: null
    badRequestReadTimeout:
      summary: Bad Request - Read Timeout
      description: This error may be returned if it takes more than 29 seconds to hear back from the data fetch service.
      value:
        status: Bad Request
        timestamp: '2020-07-02 16:18:38.949'
        path: /factset-private-markets/v1/{endpoint}
        message: The request took too long. Try again with a smaller request.
        subErrors: null
    forbidden:
      summary: Forbidden
      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.
      value:
        status: Forbidden
        timestamp: '2020-07-02 17:21:52.197'
        path: /factset-private-markets/v1/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-private-markets/v1/{endpoint}
        subErrors: null
    unauthenticated:
      summary: User Authentication Failed
      description: This occurs when a user is not properly authenticated or recognized by the service. Please double check the USERNAME-SERIAL and API-Key used to request and ensure you are within the IP range specified for the Key. Report Issue under 401 error for help with troubleshooting.
      value:
        status: User Authentication Failed
        timestamp: '2020-07-02 16:08:07.945'
        path: /factset-private-markets/v1/{endpoint}
        message: User Authentication Failed.
        subErrors: null
    badRequestMalformedJSON:
      summary: Bad Request - Malformed JSON Request
      description: This error may be returned when the request body is specified as JSON, but is not in proper JSON format.
      value:
        status: Bad Request
        timestamp: '2020-07-02 11:59:09.649'
        path: /factset-private-markets/v1/{endpoint}
        message: Malformed JSON Request
        subErrors: null
    badRequestRequiredParameter:
      summary: Bad Request - Required Parameter Missing
      description: This error message occurs when the request does not include the required parameters. Required parameters are indicated with a red asterisks symbol in the specification file.
      value:
        status: Bad Request
        timestamp: '2020-06-30 13:22:09.053'
        path: /factset-private-markets/v1/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        subErrors: null
  parameters:
    country:
      name: country
      description: ISO2 country code corresponding to the entity name that is used when evaluating candidates for a match. For a list of ISO2 Country codes, visit [OA 8754](https://my.apps.factset.com/oa/pages/8754).
      in: query
      schema:
        type: string
        maxLength: 2
        minLength: 2
      example: US
    name:
      name: name
      description: Name of Entity to match.
      in: query
      schema:
        type: string
        minLength: 1
        maxLength: 200
      required: true
      example: Cargill
  responses:
    '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:
            Bad Request - Date Format:
              $ref: '#/components/examples/unauthenticated'
    '415':
      description: Unsupported Media Type. This error may be returned when the caller sends a resource in a format that is not accepted by the server. This can be fixed by ensuring that Content-Type header is set to the correct value. In this instance, "application/json" would be the appropriate value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Unsupported Media Type:
              $ref: '#/components/examples/unsupportedMediaType'
    '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:
            Bad Request - Forbidden:
              $ref: '#/components/examples/forbidden'
    EntityMatchResponse:
      description: Response containing Entity Match results.
      content:
        application/json;charset=utf-8:
          schema:
            $ref: '#/components/schemas/EntityMatchesResponse'
          examples:
            Entity Matches:
              $ref: '#/components/examples/EntityMatches'
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Internal Server Error - Not Writable:
              $ref: '#/components/examples/notWritable'
            Internal Server Error - General Exception:
              $ref: '#/components/examples/generalException'
    '400':
      description: Bad Request. This can occur for several reasons. Please review the "message" for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/badRequestDateFormat'
            Bad Request - Missing Required Parameter:
              $ref: '#/components/examples/badRequestRequiredParameter'
            Bad Request - Invalid Parameter:
              $ref: '#/components/examples/badRequestInvalidParameters'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/badRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/badRequestReadTimeout'
  schemas:
    EntityMatchesResponse:
      title: Entity Matches Response
      description: Response object for Entity Matches.
      type: object
      properties:
        data:
          description: Candidate list of `Entity Match` objects.
          type: array
          items:
            $ref: '#/components/schemas/EntityMatch'
          example: []
    EntityMatch:
      title: Entity Match
      description: 'Entity Match object showing the decision reached for each Entity.

        '
      type: object
      properties:
        entityId:
          description: 'FactSet Entity Identifier of the entity matched respective to the requested Name submitted. For more detail, visit [FactSet Permanent Security Identifier](https://oa.apps.factset.com/cms/oaAttachment/64c3213a-f415-4c27-a336-92c73a72deed/24881)

            '
          type: string
          nullable: true
          example: '500123'
        entityName:
          description: Full name corresponding to the matched entity.
          type: string
          example: FactSet Research Systems, Inc.
          nullable: true
        countryCode:
          description: ISO2 country code corresponding to the location of the matched entity.
          type: string
          example: US
          nullable: true
        entityTypeCode:
          description: Code representing the entity type of the matched entity. See the related request parameter for a table of all Codes and their respective descriptions.
          type: string
          example: PUB
          nullable: true
    errorResponse:
      type: object
      description: error description
      title: Error Response
      properties:
        status:
          description: status
          type: string
          example: Bad Request
        timestamp:
          description: timestamp in YYYY-MM-DD HH:MM:SS.SSS
          type: string
          example: '2019-11-01 11:09:41.918'
          format: date-time
        path:
          description: The Endpoint path {package}/version/{endpoint}
          type: string
          example: /factset-private-markets/v1/{end-point}
        message:
          description: The plain text error message
          type: string
          example: Validation Error
        subErrors:
          description: subErrors related to the error message. Null if not applicable.
          type: object
          properties:
            object:
              description: the operation ID
              type: string
            field:
              description: Parameter Field Name
              type: string
            message:
              description: Error message
              type: string
            rejectedValue:
              description: Rejected Values in an Array
              type: array
              items:
                type: string
          example: example_value
    EntityMatchRequest:
      title: Entity Match Request
      description: Request object for a requesting multiple Entity Matches.
      type: object
      properties:
        input:
          type: array
          items:
            type: object
            properties:
              name:
                description: The Name of the entity to match.
                type: string
                minLength: 1
                maxLength: 200
                example: Cargill
              country:
                description: 'ISO2 country code corresponding to the entity name that is used when evaluating candidates for a match. For a list of ISO Country codes, visit [OA 8754](https://my.apps.factset.com/oa/pages/8754).

                  '
                type: string
                maxLength: 2
                minLength: 2
                example: US
            required:
            - name
          minItems: 1
          maxItems: 25
          example: []
      required:
      - input
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation