openapi: 3.1.0
info:
  title: Freshworks Freshcaller 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/
externalDocs:
  description: Freshcaller API Documentation
  url: https://developers.freshcaller.com/api/
servers:
  - url: https://{domain}.freshcaller.com/api/v1
    description: Freshcaller Production Server
    variables:
      domain:
        default: yourdomain
        description: Your Freshcaller subdomain
tags:
  - name: Call Metrics
    description: >-
      Access call center metrics and analytics data.
  - name: Calls
    description: >-
      Access call records, call details, and call metrics from the
      Freshcaller system.
  - name: Teams
    description: >-
      Manage agent teams for call routing and organization.
  - name: Users
    description: >-
      Manage agent users in the Freshcaller system including creation,
      updates, and status management.
security:
  - apiKeyAuth: []
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'
  /users:
    get:
      operationId: listUsers
      summary: List all users
      description: >-
        Retrieves a list of all agent users configured in the Freshcaller
        system, including their status and role information.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      summary: Create a user
      description: >-
        Creates a new agent user in the Freshcaller system.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{user_id}:
    get:
      operationId: getUser
      summary: View a user
      description: >-
        Retrieves the details of a specific user by their ID.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/UserIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateUser
      summary: Update a user
      description: >-
        Updates the properties of an existing agent user.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/UserIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /user_statuses:
    get:
      operationId: listUserStatuses
      summary: List all user statuses
      description: >-
        Retrieves the current availability status of all agent users
        in the Freshcaller system.
      tags:
        - Users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_statuses:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /teams:
    get:
      operationId: listTeams
      summary: List all teams
      description: >-
        Retrieves a list of all agent teams configured in the Freshcaller
        system for call routing purposes.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  teams:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTeam
      summary: Create a team
      description: >-
        Creates a new agent team in the Freshcaller system for call
        routing and organizational purposes.
      tags:
        - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamCreate'
      responses:
        '201':
          description: Team created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  team:
                    $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /teams/{team_id}:
    get:
      operationId: getTeam
      summary: View a team
      description: >-
        Retrieves the details of a specific team by its ID.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/TeamIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  team:
                    $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateTeam
      summary: Update a team
      description: >-
        Updates the properties of an existing team.
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/TeamIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamCreate'
      responses:
        '200':
          description: Team updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  team:
                    $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /call_metrics:
    get:
      operationId: listCallMetrics
      summary: List call metrics
      description: >-
        Retrieves aggregated call center metrics and analytics data
        for the specified time period.
      tags:
        - Call Metrics
      parameters:
        - name: by_time[from]
          in: query
          description: Start of the time range (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: by_time[to]
          in: query
          description: End of the time range (ISO 8601).
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  call_metrics:
                    type: array
                    items:
                      $ref: '#/components/schemas/CallMetric'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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.
  parameters:
    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
    CallIdParam:
      name: call_id
      in: path
      required: true
      description: The ID of the call.
      schema:
        type: integer
    UserIdParam:
      name: user_id
      in: path
      required: true
      description: The ID of the user.
      schema:
        type: integer
    TeamIdParam:
      name: team_id
      in: path
      required: true
      description: The ID of the team.
      schema:
        type: integer
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.
    User:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the user.
        name:
          type: string
          description: Full name of the user.
        email:
          type: string
          format: email
          description: Email address.
        phone:
          type: string
          description: Phone number.
        role:
          type: string
          description: Role of the user (admin, supervisor, agent).
        available:
          type: boolean
          description: Whether the user is currently available.
        team_ids:
          type: array
          items:
            type: integer
          description: IDs of teams the user belongs to.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    UserCreate:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          description: Full name of the user.
        email:
          type: string
          format: email
          description: Email address.
        phone:
          type: string
          description: Phone number.
        role:
          type: string
          description: Role to assign (admin, supervisor, agent).
        team_ids:
          type: array
          items:
            type: integer
          description: IDs of teams to assign.
    UserStatus:
      type: object
      properties:
        user_id:
          type: integer
          description: ID of the user.
        name:
          type: string
          description: Name of the user.
        available:
          type: boolean
          description: Whether the user is available.
        on_call:
          type: boolean
          description: Whether the user is currently on a call.
        status:
          type: string
          description: Current status label.
    Team:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the team.
        name:
          type: string
          description: Name of the team.
        description:
          type: string
          description: Description of the team.
        user_ids:
          type: array
          items:
            type: integer
          description: IDs of users in the team.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    TeamCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the team.
        description:
          type: string
          description: Description.
        user_ids:
          type: array
          items:
            type: integer
          description: IDs of users to include.
    CallMetric:
      type: object
      properties:
        total_calls:
          type: integer
          description: Total number of calls.
        answered_calls:
          type: integer
          description: Number of answered calls.
        missed_calls:
          type: integer
          description: Number of missed calls.
        abandoned_calls:
          type: integer
          description: Number of abandoned calls.
        voicemails:
          type: integer
          description: Number of voicemails.
        average_talk_time:
          type: integer
          description: Average talk time in seconds.
        average_wait_time:
          type: integer
          description: Average wait time in seconds.
        average_handle_time:
          type: integer
          description: Average handle time in seconds.
    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.
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Human-readable error message.