openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Convertible 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: Convertible
paths:
  /factset-terms-and-conditions/v1/convertible-details:
    get:
      summary: Factset Return Convertible Details for a List of Convertible Fixed Income Securities.
      description: "Returns Convertible Details for a list of securities, such as -\n  * Convertible Currency\n  * Convertible Effective Date\n  * Convertible Notice Days Max and Min\n  * Convertible Payment Form\n  * Convertible Payment Details\n  * Convertible Payment Form Election\n  * Convertible Price Method\n  * Convertible Type\n  * Convertibles Ratio\n  * More\n"
      tags:
      - Convertible
      operationId: getConvertibleDetails
      parameters:
      - $ref: '#/components/parameters/ids'
      responses:
        '200':
          description: Convertible Details Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/convertibleDetailsResponse'
              examples:
                Convertible Details Response:
                  $ref: '#/components/examples/fixedIncomeConvertibleDetailsResponse'
        '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 Return Convertible Details Data for a Large List of Fixed Income Securities.
      description: "Returns Convertible Details for a list of securities, such as -\n  * Convertible Currency\n  * Convertible Effective Date\n  * Convertible Notice Days Max and Min\n  * Convertible Payment Form\n  * Convertible Payment Details\n  * Convertible Payment Form Election\n  * Convertible Price Method\n  * Convertible Type\n  * Convertibles Ratio\n  * More\n"
      tags:
      - Convertible
      operationId: getConvertibleDetailsForList
      requestBody:
        description: Request object for Fixed Income Convertible Details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/termsAndConditionsScalarRequest'
            examples:
              Convertible Request:
                $ref: '#/components/examples/FixedIncomeConvertibleRequest'
        required: true
      responses:
        '200':
          description: Convertible Details Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/convertibleDetailsResponse'
              examples:
                Convertible Details Response:
                  $ref: '#/components/examples/fixedIncomeConvertibleDetailsResponse'
        '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
  /factset-terms-and-conditions/v1/convertible-history:
    get:
      summary: Factset Return Convertible History Data for a List of Fixed Income Securities.
      description: 'Returns Convertible History data for the Fixed Income security, including - * Convertibles Price * Convertibles Effective Date

        '
      tags:
      - Convertible
      operationId: getConvertibleHistory
      parameters:
      - $ref: '#/components/parameters/ids'
      responses:
        '200':
          description: Convertible History Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/convertibleHistoryResponse'
              examples:
                Convertible History:
                  $ref: '#/components/examples/fixedIncomeConvertibleHistoryResponse'
        '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 Return Convertible History Data for a Large List of Fixed Income Securities.
      description: 'Returns Convertible History data for a list of Fixed Income securities.

        '
      tags:
      - Convertible
      operationId: getConvertibleHistoryForList
      requestBody:
        description: Request object for Fixed Income Issue Size.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/termsAndConditionsScalarRequest'
            examples:
              Convertible Request:
                $ref: '#/components/examples/FixedIncomeConvertibleRequest'
        required: true
      responses:
        '200':
          description: Convertible History Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/convertibleHistoryResponse'
              examples:
                Fixed Income Issue Size:
                  $ref: '#/components/examples/fixedIncomeConvertibleHistoryResponse'
        '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
  /factset-terms-and-conditions/v1/convertible-triggers:
    get:
      summary: Factset Return Convertible Triggers Data for a List of Fixed Income Securities.
      description: 'Returns Convertible Triggers data for the Fixed Income security including the Convertible Trigger Id, Event, and Description.

        '
      tags:
      - Convertible
      operationId: getConvertibleTriggers
      parameters:
      - $ref: '#/components/parameters/ids'
      responses:
        '200':
          description: Convertible Triggers Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/convertibleTriggersResponse'
              examples:
                Convertible Triggers:
                  $ref: '#/components/examples/fixedIncomeConvertibleTriggersResponse'
        '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 Return Convertible Trigger Data for a Large List of Fixed Income Securities.
      description: 'Returns Convertible Triggers data for the Fixed Income security including the Convertible Trigger Id, Event, and Description.

        '
      tags:
      - Convertible
      operationId: getConvertibleTriggersForList
      requestBody:
        description: Request object for Fixed Income Issue Size.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/termsAndConditionsScalarRequest'
            examples:
              Convertible Request:
                $ref: '#/components/examples/FixedIncomeConvertibleRequest'
        required: true
      responses:
        '200':
          description: Convertible Triggers Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/convertibleTriggersResponse'
              examples:
                Convertible Triggers:
                  $ref: '#/components/examples/fixedIncomeConvertibleTriggersResponse'
        '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:
    badRequestInvalidParameters:
      summary: Bad Request - Invalid Parameters
      description: This error message occurs when a request parameter is used in which is not recognized by the service. Please revise your request to include only the parameters listed in the specification. Typical causes are spelling mistakes and use of improper casing.
      value:
        status: Bad Request
        timestamp: '2020-06-12 15:58:54.068'
        path: /factset-terms-and-conditions/v1/{endpoint}
        message: 'Invalid Parameter (s): fakeParameterName1 fakeParameterName2. Please modify your request to use parameters outlined in the specification for this endpoint.'
        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: '2019-11-05 09:48:29.18'
        path: /factset-terms-and-conditions/v1/{endpoint}
        message: Error writing JSON output
        subErrors: null
    fixedIncomeConvertibleDetailsResponse:
      description: Fixed Income Convertible Details Response
      value:
        data:
        - convCurr: USD
          convEffDate: '2025-08-01'
          convEndDate: '2026-01-29'
          convFrequency: Continuous on Schedule
          convId: 28654
          convIdentification: Whole or Part
          convNoticeDaysMax: null
          convNoticeDaysMin: null
          convPayForm: Cash or Physical or (Physical and Cash)
          convPayFormDet: null
          convPayFormElect: By Issuer
          convPremChgControl: null
          convPriceMethod: Fixed
          convRatio: 18.3574
          convRatioDesc: null
          convType: Optional by Holder
          fsymId: SMH439-S
          requestId: 90138VAA
        - convCurr: USD
          convEffDate: '2021-01-26'
          convEndDate: '2025-07-31'
          convFrequency: Continuous on Schedule
          convId: 29550
          convIdentification: Whole or Part
          convNoticeDaysMax: null
          convNoticeDaysMin: null
          convPayForm: Cash or Physical or (Physical and Cash)
          convPayFormDet: null
          convPayFormElect: By Issuer
          convPremChgControl: null
          convPriceMethod: Fixed
          convRatio: 18.3574
          convRatioDesc: null
          convType: Triggered Optional
          fsymId: SMH439-S
          requestId: 90138VAA
        - convCurr: USD
          convEffDate: '2021-01-26'
          convEndDate: '2026-01-30'
          convFrequency: Continuous on Schedule
          convId: 29551
          convIdentification: Whole or Part
          convNoticeDaysMax: null
          convNoticeDaysMin: null
          convPayForm: Cash or Physical or (Physical and Cash)
          convPayFormDet: null
          convPayFormElect: By Issuer
          convPremChgControl: null
          convPriceMethod: Variable
          convRatio: 18.3574
          convRatioDesc: null
          convType: Triggered Optional
          fsymId: SMH439-S
          requestId: 90138VAA
        - convCurr: USD
          convEffDate: '2021-07-01'
          convEndDate: '2025-07-31'
          convFrequency: Continuous on Schedule
          convId: 29549
          convIdentification: Whole or Part
          convNoticeDaysMax: null
          convNoticeDaysMin: null
          convPayForm: Cash or Physical or (Physical and Cash)
          convPayFormDet: null
          convPayFormElect: By Issuer
          convPremChgControl: null
          convPriceMethod: Fixed
          convRatio: 18.3574
          convRatioDesc: null
          convType: Triggered Optional
          fsymId: SMH439-S
          requestId: 90138VAA
    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: '2019-11-05 09:42:27.237'
        path: /factset-terms-and-conditions/v1/{endpoint}
        message: text/html media type is not supported. Supported media types are application/json
        subErrors: null
    fixedIncomeConvertibleTriggersResponse:
      description: Fixed Income Convertible Triggers Response
      value:
        data:
        - convTriggerEvent: Price of Convertible Instrument
          convTriggerEventDesc: null
          fsymId: SMH439-S
          requestId: 90138VAA
          triggerId: 21161
        - convTriggerEvent: Announced Redemption
          convTriggerEventDesc: null
          fsymId: SMH439-S
          requestId: 90138VAA
          triggerId: 21162
        - convTriggerEvent: Distribution of Entitlements
          convTriggerEventDesc: null
          fsymId: SMH439-S
          requestId: 90138VAA
          triggerId: 21163
        - convTriggerEvent: Fundamental Change
          convTriggerEventDesc: Make-Whole
          fsymId: SMH439-S
          requestId: 90138VAA
          triggerId: 21164
        - convTriggerEvent: Commodity Price Performance
          convTriggerEventDesc: null
          fsymId: SMH439-S
          requestId: 90138VAA
          triggerId: 21160
    fixedIncomeConvertibleHistoryResponse:
      description: Fixed Income Convertible History Response
      value:
        data:
        - convEffDate: '2025-08-01'
          convPrice: 54.47
          fsymId: SMH439-S
          requestId: 90138VAA
        - convEffDate: '2021-01-26'
          convPrice: 54.47
          fsymId: SMH439-S
          requestId: 90138VAA
        - convEffDate: '2021-01-26'
          convPrice: 54.47
          fsymId: SMH439-S
          requestId: 90138VAA
        - convEffDate: '2021-07-01'
          convPrice: 54.47
          fsymId: SMH439-S
          requestId: 90138VAA
    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: '2019-11-01 10:36:01.944'
        path: /factset-terms-and-conditions/v1/{endpoint}
        message: Unexpected error
        subErrors: null
    FixedIncomeConvertibleRequest:
      description: Fixed Income Convertible Request
      value:
        ids:
        - 90138VAA
        - E0002VAA
    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: '2019-11-04 16:18:38.949'
        path: /factset-terms-and-conditions/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-06-12 16:08:51.731'
        path: /factset-terms-and-conditions/v1/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-terms-and-conditions/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: '2019-10-31 16:08:07.945'
        path: /factset-terms-and-conditions/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: '2019-11-05 09:48:29.18'
        path: /factset-terms-and-conditions/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-12 15:48:42.016'
        path: /factset-terms-and-conditions/v1/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        subErrors: null
  parameters:
    ids:
      name: ids
      description: 'List of Fixed Income Security identifiers. Supported symbol types include CUSIP, SEDOL, ISIN, and FactSet Security Permanent Identifier (-S).


        **ID LIMIT = 250** *per request*.

        '
      in: query
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 250
      required: true
      explode: false
      example:
      - 30231GBJ
      - 88579EAA
  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 - Date Format:
              $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 - Date Format:
              $ref: '#/components/examples/forbidden'
    '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 - 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:
    convertibleHistoryResponse:
      title: Convertible History Response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/convertibleHistory'
          example: []
    convertibleDetailsResponse:
      title: Convertible Details Response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/convertibleDetails'
          example: []
    errorResponse:
      type: object
      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-georev/v1/superRegion
        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
    convertibleTriggers:
      title: Convertible Triggers
      type: object
      description: Convertible Triggers for a Fixed Income security.
      properties:
        requestId:
          description: Security identifier used in the request.
          type: string
          example: '500123'
        fsymId:
          description: FactSet Permanent Security Identifier.
          type: string
          example: '500123'
        convTriggerEvent:
          description: Convertible Trigger Event
          type: string
          example: example_value
        convTriggerEventDesc:
          description: Convertible Trigger Event Description
          type: string
          example: example_value
        triggerId:
          description: Convertible Trigger Id
          type: integer
          example: '500123'
    convertibleTriggersResponse:
      title: Convertible Triggers Response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/convertibleTriggers'
          example: []
    convertibleHistory:
      title: Convertible History
      type: object
      description: Convertible Details for a Fixed Income security.
      properties:
        requestId:
          description: Security identifier used in the request.
          type: string
          example: '500123'
        fsymId:
          description: FactSet Permanent Security Identifier.
          type: string
          example: '500123'
        convEffDate:
          description: Convertible Effective Date
          type: string
          format: date
          example: '2026-01-15'
        convPrice:
          description: Convertibles Price
          type: number
          format: double
          example: 42.5
        convRatio:
          description: Convertibles Ratio
          type: number
          format: double
          example: 42.5
        convUlyFsymId:
          description: Convertibles Underlying FactSet Permanent Identifier
          type: string
          example: '500123'
    convertibleDetails:
      title: Convertible Details
      type: object
      description: Convertible Details for a Fixed Income security.
      properties:
        requestId:
          description: Security identifier used in the request.
          type: string
          example: '500123'
        fsymId:
          description: FactSet Permanent Security Identifier.
          type: string
          example: '500123'
        convCurr:
          description: Convertible Currency
          type: string
          example: example_value
        convEffDate:
          description: Convertible Effective Date
          type: string
          format: date
          example: '2026-01-15'
        convEndDate:
          description: Convertible End Date
          type: string
          format: date
          example: '2026-01-15'
        convFrequency:
          description: Convertible Frequency
          type: string
          example: example_value
        convId:
          description: Convertible Type Id
          type: integer
          example: '500123'
        convIdentification:
          description: Convertible Identification
          type: string
          example: example_value
        convNoticeDaysMax:
          description: Convertible Notice Max
          type: integer
          example: 10
        convNoticeDaysMin:
          description: Convertible Notice Min
          type: integer
          example: 10
        convPayForm:
          description: Convertible Payment Form
          type: string
          example: example_value
        convPayFormDet:
          description: Convertible Payment Form Detail
          type: string
          example: example_value
        convPayFormElect:
          description: Convertible Payment Form Election
          type: string
          example: example_value
        convPremChgControl:
          description: Convertible Premium Change Control
          type: number
          format: double
          example: 42.5
        convPriceMethod:
          description: Convertible Price Method
          type: string
          example: example_value
        convRatio:
          description: Convertibles Ratio
          type: number
          format: double
          example: 42.5
        convRatioDesc:
          description: Convertible Ratio Form Description
          type: string
          example: example_value
        convType:
          description: Convertible Type
          type: string
          example: example_value
    termsAndConditionsScalarRequest:
      title: General Ids Request
      type: object
      properties:
        ids:
          description: 'List of Fixed Income Security identifiers. Supported symbol types include CUSIP, SEDOL, ISIN, and FactSet Security Permanent Identifier (-S).


            **ID LIMIT = 250** *per request*.

            '
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 250
          example:
          - 30231GBJ
          - 88579EAA
      required:
      - ids
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation