openapi: 3.1.0
info:
  title: Freshworks Freshcaller Accounts Calls API
  description: The Freshcaller API provides access to cloud-based phone system functionality for contact center operations. It allows developers to export call data, call recordings, user information, and agent team details stored in the Freshcaller system. The API supports integration of voice and telephony workflows into broader business applications, enabling organizations to automate call center reporting, synchronize agent data, and build custom dashboards around their phone operations.
  version: '1.0'
  contact:
    name: Freshworks Support
    url: https://support.freshcaller.com/
  termsOfService: https://www.freshworks.com/terms/
servers:
- url: https://{domain}.freshcaller.com/api/v1
  description: Freshcaller Production Server
  variables:
    domain:
      default: yourdomain
      description: Your Freshcaller subdomain
security:
- apiKeyAuth: []
tags:
- name: Calls
  description: Access call records, call details, and call metrics from the Freshcaller system.
paths:
  /calls:
    get:
      operationId: listCalls
      summary: List all calls
      description: Retrieves a paginated list of all call records from the Freshcaller system including inbound, outbound, and missed calls.
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - name: by_time[from]
        in: query
        description: Filter calls from this timestamp (ISO 8601).
        schema:
          type: string
          format: date-time
      - name: by_time[to]
        in: query
        description: Filter calls up to this timestamp (ISO 8601).
        schema:
          type: string
          format: date-time
      - name: has_ancestry
        in: query
        description: Filter calls that have parent-child relationships.
        schema:
          type: boolean
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  calls:
                    type: array
                    items:
                      $ref: '#/components/schemas/Call'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /calls/{call_id}:
    get:
      operationId: getCall
      summary: View a call
      description: Retrieves the details of a specific call record by its ID, including call duration, participants, recording URL, and status.
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/CallIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  call:
                    $ref: '#/components/schemas/Call'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /calls/{call_id}/recording:
    get:
      operationId: getCallRecording
      summary: Get call recording
      description: Retrieves the recording URL for a specific call. The recording must be available and the account must have recording enabled.
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/CallIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  recording:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
                        description: URL of the call recording audio file.
                      duration:
                        type: integer
                        description: Duration of the recording in seconds.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    CallIdParam:
      name: call_id
      in: path
      required: true
      description: The ID of the call.
      schema:
        type: integer
    PageParam:
      name: page
      in: query
      description: Page number for pagination.
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPageParam:
      name: per_page
      in: query
      description: Number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    Call:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the call.
        direction:
          type: string
          description: Direction of the call.
          enum:
          - incoming
          - outgoing
        status:
          type: string
          description: Status of the call (completed, missed, voicemail, abandoned).
        phone_number:
          type: string
          description: Phone number involved in the call.
        caller_number:
          type: string
          description: Phone number of the caller.
        agent_id:
          type: integer
          description: ID of the agent who handled the call.
        queue_id:
          type: integer
          description: ID of the call queue.
        team_id:
          type: integer
          description: ID of the team.
        duration:
          type: integer
          description: Total duration of the call in seconds.
        bill_duration:
          type: integer
          description: Billable duration in seconds.
        talk_duration:
          type: integer
          description: Talk time duration in seconds.
        hold_duration:
          type: integer
          description: Hold time duration in seconds.
        wait_duration:
          type: integer
          description: Wait time duration in seconds.
        has_recording:
          type: boolean
          description: Whether the call has a recording.
        recording_url:
          type: string
          format: uri
          description: URL to the call recording.
        notes:
          type: string
          description: Notes about the call.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the call started.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the record was last updated.
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Human-readable error message.
    Meta:
      type: object
      properties:
        total_pages:
          type: integer
          description: Total number of pages.
        total:
          type: integer
          description: Total number of records.
        current_page:
          type: integer
          description: Current page number.
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Auth
      description: API key authentication. The API key can be found in your Freshcaller admin settings.
externalDocs:
  description: Freshcaller API Documentation
  url: https://developers.freshcaller.com/api/