Factset Security API

openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Security 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: Security
paths:
  /factset-global-prices/v1/security-shares:
    get:
      tags:
      - Security
      summary: Factset Gets Shares Outstanding Information for Securities.
      operationId: getSharesOutstanding
      description: Returns security level shares outstanding data for the given ids and dates. At this time, all values returned are split adjusted.
      parameters:
      - $ref: '#/components/parameters/idsBatchMax1000'
      - $ref: '#/components/parameters/startDateSS'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/frequency'
      - $ref: '#/components/parameters/calendar'
      - $ref: '#/components/parameters/batch'
      responses:
        '200':
          description: Array of security shares outstanding information for a given date range and list of securities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sharesOutstandingResponse'
              examples:
                Shares Outstanding:
                  $ref: '#/components/examples/sharesOutstanding'
        '202':
          description: Batch request has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Request Accepted:
                  $ref: '#/components/examples/BatchStatusAcceptedResponse'
          headers:
            Location:
              description: Path to Batch Request status.
              schema:
                type: string
              example: batch-status?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
        '400':
          $ref: '#/components/responses/SO400'
        '401':
          $ref: '#/components/responses/SO401'
        '403':
          $ref: '#/components/responses/SO403'
        '415':
          $ref: '#/components/responses/SO415'
        '500':
          $ref: '#/components/responses/SO500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Security
      summary: Factset Gets Shares Outstanding Information for Securities.
      description: Returns security level shares outstanding data for the given ids and dates. At this time, all values returned are split adjusted.
      operationId: postSharesOutstanding
      requestBody:
        required: true
        description: Request object for `Shares Outstanding`.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sharesOutstandingRequest'
      responses:
        '200':
          description: Array of shares outstanding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sharesOutstandingResponse'
        '202':
          description: Batch request has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Request Accepted:
                  $ref: '#/components/examples/BatchStatusAcceptedResponse'
          headers:
            Location:
              description: Path to Batch Request status.
              schema:
                type: string
              example: batch-status?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
        '400':
          $ref: '#/components/responses/SO400'
        '401':
          $ref: '#/components/responses/SO401'
        '403':
          $ref: '#/components/responses/SO403'
        '415':
          $ref: '#/components/responses/SO415'
        '500':
          $ref: '#/components/responses/SO500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /analytics/security-modeling/v3/securities/retrieve:
    post:
      tags:
      - Security
      summary: Factset Get Existing Securities
      description: This endpoint gets all existing securities.
      operationId: getSecurities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMRetrieveParametersRoot'
      responses:
        '200':
          description: Expected response, returns a list of existing securities.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMRetrieveResponseRoot'
        '401':
          description: Missing or invalid authentication.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
        '403':
          description: User is forbidden with current credentials
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
        '406':
          description: Unsupported Accept header. Header needs to be set to application/json.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
        '429':
          description: Rate limit reached. Wait till the time specified in Retry-After header value to make further requests.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            Retry-After:
              description: Time to wait in seconds before making a new request as the rate limit has reached.
              schema:
                type: string
        '500':
          description: Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
        '503':
          description: Request timed out. Retry the request in sometime.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /analytics/security-modeling/v3/securities/upsert:
    post:
      tags:
      - Security
      summary: Factset Create or Update Securities
      description: This endpoint is to create or update existing securities.
      operationId: upsertSecurities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMCreateParametersRoot'
      responses:
        '200':
          description: Expected response, returns a status of operation along with errors and warnings if found any.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMCreateResponseRoot'
        '401':
          description: Missing or invalid authentication.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
        '403':
          description: User is forbidden with current credentials
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
        '406':
          description: Unsupported Accept header. Header needs to be set to application/json.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
        '429':
          description: Rate limit reached. Wait till the time specified in Retry-After header value to make further requests.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            Retry-After:
              description: Time to wait in seconds before making a new request as the rate limit has reached.
              schema:
                type: string
        '500':
          description: Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
        '503':
          description: Request timed out. Retry the request in sometime.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /analytics/security-modeling/v3/securities/delete:
    post:
      tags:
      - Security
      summary: Factset Delete Existing Securities
      description: This endpoint deletes existing securities.
      operationId: deleteSecurities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMDeleteParametersRoot'
      responses:
        '200':
          description: Expected response, deletes existing securities.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMDeleteResponseRoot'
        '401':
          description: Missing or invalid authentication.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
        '403':
          description: User is forbidden with current credentials
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
        '406':
          description: Unsupported Accept header. Header needs to be set to application/json.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            X-FactSet-Api-RateLimit-Limit:
              description: Number of allowed requests for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Remaining:
              description: Number of requests left for the time window.
              schema:
                type: string
            X-FactSet-Api-RateLimit-Reset:
              description: Number of seconds remaining till rate limit resets.
              schema:
                type: string
        '429':
          description: Rate limit reached. Wait till the time specified in Retry-After header value to make further requests.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
            Retry-After:
              description: Time to wait in seconds before making a new request as the rate limit has reached.
              schema:
                type: string
        '500':
          description: Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
        '503':
          description: Request timed out. Retry the request in sometime.
          headers:
            X-DataDirect-Request-Key:
              description: FactSet's request key header.
              schema:
                type: string
                description: FactSet's request key header.
            X-FactSet-Api-Request-Key:
              description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
              schema:
                type: string
                description: Key to uniquely identify an Analytics API request. Only available after successful authentication.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    SO401:
      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/soErrorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/sounauthenticated'
    SO400:
      description: Bad Request. This can occur for several reasons. Please review the "message" for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/soErrorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/sobadRequestDateFormat'
            Bad Request - Missing Required Parameter:
              $ref: '#/components/examples/sobadRequestRequiredParameter'
            Bad Request - Future Date:
              $ref: '#/components/examples/sobadRequestFutureDate'
            Bad Request - Invalid Parameter:
              $ref: '#/components/examples/sobadRequestInvalidParameters'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/sobadRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/sobadRequestReadTimeout'
    SO500:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/soErrorResponse'
          examples:
            Internal Server Error - Not Writable:
              $ref: '#/components/examples/sonotWritable'
            Internal Server Error - General Exception:
              $ref: '#/components/examples/sogeneralException'
    SO403:
      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/soErrorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/soforbidden'
    SO415:
      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/soErrorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/sounsupportedMediaType'
  schemas:
    SMRetrieveResponseRoot:
      required:
      - data
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SMRetrieveResponse'
          example: []
        meta:
          type: object
          nullable: true
          example: example_value
    batchErrorObject:
      type: object
      nullable: true
      properties:
        id:
          description: A UUID for this particular occurrence of the problem.
          type: string
          nullable: true
          example: adb01824-252f-4420-b0c6-35a1e3507ef5
        code:
          description: status
          type: string
          nullable: true
          example: GenericError
        links:
          description: The Endpoint path {package}/version/{endpoint}
          type: object
          properties:
            about:
              description: details.
              type: string
              example: /factset-global-prices/v1/{endpoint}
          example: example_value
        title:
          description: The plain text error message
          type: string
          nullable: true
          example: Validation Error
    sharesOutstandingResponseObject:
      type: object
      title: Shares Outstanding Object
      properties:
        fsymId:
          description: Security-level FactSet Permanent Identifier associated with the identifier.
          type: string
          example: C6J726-S
          nullable: true
        date:
          description: Date of the record in YYYY-MM-DD format.
          type: string
          format: date
          example: '2022-08-10'
          nullable: true
        documentId:
          description: Unique Identifier for each document or filing which contains the outstanding shares position.
          type: string
          example: '956881'
          nullable: true
        requestId:
          description: FactSet Security Permanent Identifier that was used for the request.
          type: string
          example: C6J726-S
          nullable: true
        reportDate:
          description: Reporting date of the position.
          type: string
          format: date
          example: '2022-08-02'
          nullable: true
        publicationDate:
          description: Exact date that results have been communicated to the market.
          type: string
          format: date
          example: '2022-08-04'
          nullable: true
        fiscalYear:
          description: The company's fiscal year corresponding to the report.
          type: integer
          example: 2022
          nullable: true
        reportingPeriodDescription:
          description: Textual description of the reporting period.
          type: string
          example: 2nd Quarter
          nullable: true
        reportingPeriod:
          description: 'Code representing the unique reporting period. Options are as follows:

            - 1 - 1st Quarter

            - 2 - 2nd Quarter

            - 3 - 3rd Quarter

            - 4 - 4th Quarter

            - 6 - Mid-Year

            '
          type: integer
          example: 3
          nullable: true
        description:
          description: Different stock types based on the rights and benefits from ownership.
          type: string
          example: Class A Shares
          nullable: true
        adrDescription:
          description: Different stock types based on the rights and benefits from ownership for the ADR.
          type: string
          example: Class A Shares
          nullable: true
        adrRatio:
          description: Number of common or ordinary shares that are equivalent to one American Depositary Receipt (ADR).
          type: number
          example: 0.5
          nullable: true
        adrFsymId:
          description: Unique FactSet generated identifier assigned to a security, representing the ADR security.
          type: string
          example: V9GGRZ-S
          nullable: true
        totalOutstanding:
          description: Number of shares outstanding as of `date`.
          type: number
          example: 1351.828
          nullable: true
        adrTotalOutstanding:
          description: Number of shares outstanding for the ADR as of `date`.
          type: nu

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/factset/refs/heads/main/openapi/factset-security-api-openapi.yml