Factset Audio API

openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Audio 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: Audio
paths:
  /docs-distributor/audio/v1/history-files:
    get:
      summary: Retrieve Historical Audio Recordings and Related Metadata Within Factset Coverage.
      tags:
      - Audio
      responses:
        '200':
          description: Array of presigned downloadable URLs consisting of historical audio recordings with related metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Events-Audio-History'
              examples:
                Audio recordings and metadata of 2020:
                  value:
                    data:
                    - year: 2021
                      fileName: 2021_trimmed.tar.gz
                      fileSize: 191173623046875
                      trimmed: true
                      url: https://fdss3-cts-data-delivery-prod-1-us-east-1.s3.amazonaws.com/audiofiles/A512D0F2-4549-EC11-8124-8CDCD4AF21E4.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIASXWF7GTDZZHNXO4D%2F20211119%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20211119T143756Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEB4aCXVzLWVhc3QtMSJHMEUCIAZPE65Cyr2GFwHLDFiDWEj3aUW66s6HuKk3vMz7hWR1AiEAiLS3ce5AC1hsDkZWdf9WklbnGoXCD6JMNsYKZLSZtKoqmAII1%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARACGgwxODgzMjAwMDMyNzEiDIEOfxabmh%2FtadnmnirsAToraA%2BQJ8Hmg2YS03b7IpkX6W6FJDjnDJ9M6sCLN7Q0mUT60Jc1OV%2BzuJ5IbCKhZhDV24mKPSPkyYs4Eh1%2Bp5E2YeclzHqSn44zB5g9UkVHP1bCkFCxv12pqhdIJ5NX4xBIPhWfXDQyIFQm%2BstD1FL3AqugJb19s0o79N032dOX1H3wvfqfkP4av9wKYRFhc2yO7qHMLUHmYnL2IAcnGRq5ukvO2%2FIrmGVYTFGr4wAWMDQFZRX6%2FiYvC7V3f3smsoy2jrJ8UDDn599%2BH32Nh%2FKfTO8yYSnt1ky%2FFJb%2FmheEF9PWnf%2FZxuG6o9ajMInX3owGOpoBFurBn4Hwi3d1xuSsXNVMEuSj7vWPV6dc8tSynf8yH7wRVtVyfz%2BnWH4EYPh0l2qeHuGhzAeQtLVfJNApnSVfEeyaGo1DOpieFST9bxhQIBG8ZloD%2FlojRhJT5AEwcRTryXAXWb%2FeuLKcH9izcUGx80wBcc6L8I6YFFFwwqyA4mhhYYMDAL3o3p0QE1Q4s99PDYPR0YCH7UzThg%3D%3D&X-Amz-Signature=4b8ae68420f7cc87da7c7a797f683e85528b6a96add83ce19ba3ffac0359a938
                    meta:
                      pagination:
                        total: 1
                        isEstimatedTotal: false
                        limit: 25
                        offset: 1
                      partial:
                        isPartial: false
        '400':
          description: Bad Request. This can occur for several reasons. Please review the "details" for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Events-Audio-History-400-Response'
              examples:
                example-1:
                  value:
                    id: 7af3d86ca5954503b9244f2620fcf5eb
                    code: parameterError
                    title: '[''yr''] is not a valid parameter(s)'
                    details:
                      validParameters:
                        _paginationLimit:
                        - integer from 0 to 500
                        _paginationOffset:
                        - positive integer
                        year:
                        - positive integer greater than 2010
                        trimmed:
                        - boolean value
        '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/Error'
              examples:
                example-1:
                  value:
                    id: 7af3d86ca5954503b9244f2620fcf5eb
                    code: notAuthenticated
                    title: There were either no, invalid, or expired credentials present in the request.
        '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/Error'
              examples:
                example-1:
                  value:
                    id: 7af3d86ca5954503b9244f2620fcf5eb
                    code: notAuthorized
                    title: ' {USERNAME}-{SERIAL} does not have permission to use this endpoint.'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example-1:
                  value:
                    id: 7af3d86ca5954503b9244f2620fcf5eb
                    code: genericServerError
                    title: An unexpected error happened.
      operationId: get-docs-distributor-audio-v1-history-files
      description: '

        * Returns the **untrimmed** historical audio recordings and related metadata dating back from May 10, 2011 to Sep 30, 2022.


        * Returns the **trimmed** historical audio recordings and related metadata dating back from May 10, 2011 to Dec 31, 2022.




        Query parameters can be used to filter and narrow down the results.

        '
      parameters:
      - $ref: '#/components/parameters/eventspaginationLimit'
      - $ref: '#/components/parameters/paginationOffset'
      - $ref: '#/components/parameters/year'
      - $ref: '#/components/parameters/trimmed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /docs-distributor/audio/v1/list-files:
    get:
      summary: Retrieve Latest Audio Recordings and Related Metadata Within Factset Coverage.
      tags:
      - Audio
      responses:
        '200':
          description: Array of URLs consisting of latest audio recordings and related metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Events-Audio'
              examples:
                example-1:
                  value:
                    data:
                    - url: https://fdss3-cts-data-delivery-prod-1-us-east-1.s3.amazonaws.com/audiofiles/A512D0F2-4549-EC11-8124-8CDCD4AF21E4.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIASXWF7GTDZZHNXO4D%2F20211119%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20211119T143756Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEB4aCXVzLWVhc3QtMSJHMEUCIAZPE65Cyr2GFwHLDFiDWEj3aUW66s6HuKk3vMz7hWR1AiEAiLS3ce5AC1hsDkZWdf9WklbnGoXCD6JMNsYKZLSZtKoqmAII1%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARACGgwxODgzMjAwMDMyNzEiDIEOfxabmh%2FtadnmnirsAToraA%2BQJ8Hmg2YS03b7IpkX6W6FJDjnDJ9M6sCLN7Q0mUT60Jc1OV%2BzuJ5IbCKhZhDV24mKPSPkyYs4Eh1%2Bp5E2YeclzHqSn44zB5g9UkVHP1bCkFCxv12pqhdIJ5NX4xBIPhWfXDQyIFQm%2BstD1FL3AqugJb19s0o79N032dOX1H3wvfqfkP4av9wKYRFhc2yO7qHMLUHmYnL2IAcnGRq5ukvO2%2FIrmGVYTFGr4wAWMDQFZRX6%2FiYvC7V3f3smsoy2jrJ8UDDn599%2BH32Nh%2FKfTO8yYSnt1ky%2FFJb%2FmheEF9PWnf%2FZxuG6o9ajMInX3owGOpoBFurBn4Hwi3d1xuSsXNVMEuSj7vWPV6dc8tSynf8yH7wRVtVyfz%2BnWH4EYPh0l2qeHuGhzAeQtLVfJNApnSVfEeyaGo1DOpieFST9bxhQIBG8ZloD%2FlojRhJT5AEwcRTryXAXWb%2FeuLKcH9izcUGx80wBcc6L8I6YFFFwwqyA4mhhYYMDAL3o3p0QE1Q4s99PDYPR0YCH7UzThg%3D%3D&X-Amz-Signature=4b8ae68420f7cc87da7c7a797f683e85528b6a96add83ce19ba3ffac0359a938
                      fileName: 835A1FD9-3CE1-EC11-8128-8CDCD4AF21E4.mp3
                      durationSecs: 5022
                      endOffsetSeconds: 4379
                      startOffsetSeconds: 1717
                      sourceCode: W
                      startTime: '2022-05-31T22:26:58Z'
                      endTime: '2022-05-31T23:50:42Z'
                      uploadTime: '2022-05-31T23:57:01'
                      fileSize: 20090671
                      reportId: 2666621
                      ticker: SPWH-US
                      entityId: 0CT2ZZ-E
                      trimmed: false
                      sampleRate: 22
                      bitrate: 32
                      audioSourceId: 3256781
                    meta:
                      sort:
                      - -startDate
                      pagination:
                        total: 1
                        isEstimatedTotal: false
                        limit: 25
                        offset: 1
                      partial:
                        isPartial: false
        '400':
          description: Bad Request. This can occur for several reasons. Please review the "details" for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Events-Audio-400-Response'
              examples:
                example-1:
                  value:
                    code: parameterError
                    title: uploadTme is not a valid parameter
                    id: 7af3d86ca5954503b9244f2620fcf5eb
                    details:
                      validParameters:
                        _sort:
                        - startDate
                        - -startDate
                        - uploadTime
                        _paginationLimit:
                        - integer from 0 to 500
                        _paginationOffset:
                        - positive integer
                        reportId:
                        - integer
                        startDate:
                        - integer offset less than 0
                        - date
                        - datetime
                        endDate:
                        - integer offset less than 0
                        - date
                        - datetime
                        ids:
                        - comma separated string of tickers or entityIds or combination of both
                        sourceCode:
                        - file source code
                        fileName:
                        - mp3 file name
                        trimmed:
                        - true/false
                        uploadTime:
                        - integer from -1 to -168
                        audioSourceId:
                        - integer
        '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/Error'
              examples:
                example-1:
                  value:
                    id: 7af3d86ca5954503b9244f2620fcf5eb
                    code: notAuthenticated
                    title: There were either no, invalid, or expired credentials present in the request.
        '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/Error'
              examples:
                example-1:
                  value:
                    id: 7af3d86ca5954503b9244f2620fcf5eb
                    code: notAuthorized
                    title: ' {USERNAME}-{SERIAL} does not have permission to use this endpoint.'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                example-1:
                  value:
                    id: 7af3d86ca5954503b9244f2620fcf5eb
                    code: genericServerError
                    title: An unexpected error happened.
      operationId: get-docs-distributor-audio-v1-list-files
      description: Returns the latest audio recordings. Query parameters can be used to filter and narrow down the results.
      parameters:
      - schema:
          type: string
          enum:
          - -startDate
          - uploadTime
          - startDate
          default: -startDate
        in: query
        name: _sort
        description: Sorts results in chronological order, reverse chronological order and by uploadTime(latest uploaded first). Results are in reverse chronological order by default.
      - schema:
          type: integer
          format: int32
          minimum: 0
          maximum: 500
          default: 25
        in: query
        name: _paginationLimit
        description: Specifies the number of results to return per page. [ Min=0 ; Max=500 ]
      - schema:
          type: string
        in: query
        example: '2022-01-01T00:00:00.000Z'
        name: startDate
        description: 'Used in conjuction with endDate. The earliest date of the audio file the API should fetch for (can be in absolute: **YYYY-MM-DD** or relative date: **-1** for yesterday).'
      - schema:
          type: integer
          format: int32
          default: 0
        in: query
        name: _paginationOffset
        description: Specifies the starting point for pagination. This parameter is used to identify the beginning of next set of results.
      - schema:
          type: string
        in: query
        name: endDate
        example: '2022-06-01T00:00:00.000Z'
        description: 'Used in conjuction with startDate. The latest date of the audio file the API should fetch for (can be in absolute: **YYYY-MM-DD** or relative date: **0** for today).'
      - schema:
          type: integer
          format: int32
        in: query
        name: reportId
        example: 2666621
        description: Unique identifier for fetching the audio file for an event. The same ID is used for the transcript of the same event.
      - schema:
          type: integer
          format: int32
        in: query
        name: audioSourceId
        description: Unique ID for an Internal recording specific to reportID. For example, ReportID X would have multiple recordings from different source (phone or webcast or vendor or replay). One ReportID can have multiple AudioSourceIDs.
      - schema:
          type: array
          items:
            type: string
        in: query
        name: ids
        explode: false
        examples:
          oneId:
            summary: One identifier
            value:
            - SPWH-US
          noId:
            summary: No identifier
            value: []
          multipleIds:
            summary: Multiple Identifiers
            value:
            - FDS-US
            - AAPL-US
            - MSFT-US
        description: This parameter filters the results based on ticker-region or Entity ID or the combination of both. A comma is used to separate each identifier.
      - schema:
          type: string
          enum:
          - P
          - W
          - V
          - F
          - I
          - R
        in: query
        name: sourceCode
        description: 'This parameter filters the results based on Source of the Audio file. Below are the descriptions for each Source Code -

          * P = Phone

          * W = Webcast

          * V = Vendor

          * I = Webcast Replay

          * F = Flash - identical to webcast; can merge with "W" in the future

          * R = Replay (Phone Replay)'
      - schema:
          type: string
        in: query
        name: fileName
        example: 835A1FD9-3CE1-EC11-8128-8CDCD4AF21E4.mp3
        description: This parameter is used to filter the data on based on the file name.
      - schema:
          type: boolean
        in: query
        name: trimmed
        description: This parameters helps to search trimmed audio files.
      - schema:
          type: integer
          minimum: -168
          maximum: -1
          format: int32
        in: query
        name: uploadTime
        description: 'This parameter filters data based on uploadTime relative to the current time, in hours. For example:- uploadTime = -15 (fetches audio files between 15 hours ago and now)


          Minimum is 1 hour i.e., uploadTime= -1


          Maximum is 1 week/168 hours i.e., uploadTime=-168


          While using uploadTime, the startDate and endDate parameters will be ignored.'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Events-Audio-History:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              year:
                type: integer
                description: The year corresponding to the file containing historical audio recordings that can be downloaded via presigned url.
              trimmed:
                type: boolean
                description: 'True  indicates that the pre-signed downloadable URL contains trimmed historical audio recordings and related metadata of a specific year.


                  False  indicates that the pre-signed downloadable URL contains untrimmed historical audio recordings and related metadata of a specific year.'
              fileName:
                type: string
                description: The name of the file.
              fileSize:
                type: integer
                description: The size of the file, in bytes.
              url:
                type: string
                description: Pre-signed downloadable URL containing the historical audio recordings and related metadata of a specific year. The pre-signed URL in the response will expire after 3 hours.
          example: []
        meta:
          type: object
          properties:
            pagination:
              type: object
              description: "\t\nList of pagination objects"
              properties:
                total:
                  type: integer
                  description: Total number of files the API returns for a particular query.
                isEstimatedTotal:
                  type: boolean
                  description: Boolean value that represents whether the total count of files returned is exact or an estimate. This is defaulted to False as the API should always return the exact count.
                limit:
                  type: integer
                  description: Number of results returned per page
                offset:
                  type: integer
                  description: The flag indicating the position in the results array if additional results are available beyond the default value or the value in paginationLimit parameter (if used). This value is passed in the _paginationOffset parameter to retrieve subsequent results.
            partial:
              type: object
              description: ''
              properties:
                isPartial:
                  type: boolean
                  description: If the value is True, it indicates additional results are available. False represents that this is the last set of results for this request.
          example: example_value
    Events-Audio:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                description: Download link for the audio file.
              fileName:
                type: string
                description: The filename of the audio file.
              durationSecs:
                type: number
                nullable: true
                description: Total duration of the recording in seconds based on startOffsetSeconds to endOffsetSeconds.
              endOffsetSeconds:
                type: number
                nullable: true
                description: The delta in seconds between startTime to when FactSet marks the end of the call.
              startOffsetSeconds:
                type: number
                nullable: true
                description: The delta in seconds between start of audio file to when FactSet marks the beginning of the call.
              sourceCode:
                type: string
                description: 'Identifies the method of how the event is recorded Below are the descriptions for each Source Code -

                  * P = Phone

                  * W = Webcast

                  * V = Vendor

                  * I = Webcast Replay

                  * F = Flash - identical to webcast; can merge with "W" in the future

                  * R = Replay (Phone Replay)'
              startTime:
                type: string
                nullable: true
                description: 'The official timestamp when FactSet begins the recording.


                  Note:- All the vendor and trimmed files would have default 1900-0101T00:00:00Z time stamp.'
              endTime:
                type: string
                nullable: true
                description: 'The official timestamp when FactSet ends the recording.


                  Note:- All the vendor and trimmed files would have default 1900-0101T00:00:00Z time stamp.'
              uploadTime:
                type: string
                nullable: true
                description: The official timestamp when FactSet publishes the audio file externally.
              fileSize:
                type: number
                description: Size of the Audio file, in bytes.
              reportId:
                type: integer
                description: 'The unique ID of the audio file for an event. The same ID is used for the transcript of the same event.

                  This report ID can also be used to map to the Event details in SDF tables.'
              ticker:
                type: string
                nullable: true
                description: 'Ticker-region identifier for the company hosting the event.


                  Note:- This field can have N/A value when the company is a private(non-equity company)'
              entityId:
                type: string
                description: Factset entity level identifier for the company hosting the event.
              trimmed:
                type: boolean
                description: 'The trimmed attribute helps identify if the audio is the trimmed version.

                  Note:- All the vendor generated files are trimmed regardless of the trimmed attribute value in the response.'
              sampleRate:
                type: number
                nullable: true
                description: 'The number of samples of audio carried per second in Kbps.


                  Note:- The field can have value as -1 for the audio files without sampleRate metadata'
              bitrate:
                type: number
                nullable: true
                description: 'The total number of bits of information stored per second of sound in Kbps.


                  Note:- The field can have value as -1 for the audio files without bitrate metadata'
              audioSourceId:
                type: integer
                nullable: true
                description: 'Unique ID for an Internal recording specific to reportID. For example, ReportID X would have multiple recordings from different source (Phone or Webcast or Vendor or Replay). One ReportID can have multiple AudioSourceIDs.


                  The audioSourceId identifier is available for audio calls since November 29, 2022.

                  Note:- Only un-trimmed audio files contain an audioSourceId value. All the vendor and trimmed audio files will have an audioSourceId value of null.'
          example: []
        meta:
          type: object
          properties:
            sort:
              type: array
              description: The value in _sort parameter if used in the request.
              items:
                type: string
            pagination:
              type: object
              description: "\t\nList of pagination objects"
              properties:
                total:
                  type: integer
                  description: Total number of files the API returns for a particular query.
                isEstimatedTotal:
                  type: boolean
                  description: Boolean value that represents whether the total count of files returned is exact or an estimate. This is defaulted to False as the API should always return the exact count.
                limit:
                  type: integer
                  description: Number of results returned per page
                offset:
                  type: integer
                  description: The flag indicating the position in the results array if additional results are available beyond the default value or the value in paginationLimit parameter (if used). This value is passed in the _paginationOffset parameter to retrieve subsequent results.
            partial:
              type: object
              description: ''
              properties:
                isPartial:
                  type: boolean
                  description: If the value is True, it indicates additional results are available. False represents that this is the last set of results for this request.
          example: example_value
    Events-Audio-400-Response:
      description: ''
      type: object
      properties:
        code:
          type: string
          example: example_value
        title:
          type: string
          example: Example Title
        id:
          type: string
          example: abc123
        details:
          type: object
          properties:
            validParameters:
              type: object
              properties:
                _sort:
                  type: array
                  items:
                    type: string
                _paginationLimit:
                  type: array
                  items:
                    type: string
                _paginationOffset:
                  type: array
                  items:
                    type: string
                reportId:
                  type: array
                  items:
                    type: string
                startDate:
                  type: array
                  items:
                    type: string
                endDate:
                  type: array
                  items:
                    type: string
                ids:
                  type: array
                  items:
                    type: string
                sourceCode:
                  type: array
                  items:
                    type: string
                fileName:
                  type: array
                  items:
                    type: string
                trimmed:
                  type: array
                  items:
                    type: string
                uploadTime:
                  type: array
                  items:
                    type: string
                audioSourceId:
                  type: array
                  items:
                    type: string
          example: example_value
    Events-Audio-History-400-Response:
      description: ''
      type: object
      properties:
        id:
          type: string
          example: abc123
        code:
          type: string
          example: example_value
        title:
          type: string
          example: Example Title
        details:
          type: object
          properties:
            validParameters:
              type: object
              properties:
                _paginationLimit:
                  type: array
                  items:
                    type: string
                _paginationOffset:
                  type: array
                  items:
                    type: string
                year:
                  type: array
                  items:
                    type: string
                trimmed:
                  type: array
                  items:
                    type: string
          example: example_value
    Error:
      type: object
      properties:
        id:
          type: string
          example: abc123
        code:
          type: string
          example: example_value
        title:
          type: string
          example: Example Title
  parameters:
    eventspaginationLimit:
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 500
        default: 25
      in: query
      name: _paginationLimit
      description: Specifies the number of results to return per page. [ Min=0 ; Max=500 ]
    year:
      schema:
        type: integer
        format: int32
      in: query
      name: year
      example: 2021
      description: Specifies the year for which the historical audio recordings and related metadata are to be retrieved.
    paginationOffset:
      schema:
        type: integer
        format: int32
        default: 0
      in: query
      name: _paginationOffset
      description: Specifies the starting point for pagination. This parameter is used to identify the beginning of next set of results.
    trimmed:
      schema:
        type: boolean
        default: false
      in: query
      name: trimmed
      example: true
      description: Specifies if trimmed/untrimmed historical audio recordings should be returned.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation