openapi: 3.1.0
info:
  title: Freshworks Freshcaller Accounts Tickets 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: Tickets
  description: Manage helpdesk tickets including creation, updates, assignment, and resolution workflows.
paths:
  /tickets:
    get:
      operationId: listTickets
      summary: List all tickets
      description: Retrieves a list of all tickets in the helpdesk. Results can be filtered by various criteria including status, priority, and requester. Supports pagination with a default page size of 30.
      tags:
      - Tickets
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - name: filter
        in: query
        description: Pre-defined filter to apply. Options include new_and_my_open, watching, spam, deleted.
        schema:
          type: string
      - name: requester_id
        in: query
        description: Filter tickets by requester ID.
        schema:
          type: integer
      - name: email
        in: query
        description: Filter tickets by requester email.
        schema:
          type: string
          format: email
      - name: updated_since
        in: query
        description: Return tickets updated after this timestamp in UTC format.
        schema:
          type: string
          format: date-time
      - name: order_by
        in: query
        description: Field to sort by.
        schema:
          type: string
          enum:
          - created_at
          - due_by
          - updated_at
          - status
      - name: order_type
        in: query
        description: Sort order direction.
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Ticket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTicket
      summary: Create a ticket
      description: Creates a new ticket in the helpdesk. Requires at least a subject, description, and requester identification (email, phone, or requester_id). Supports attachments and custom fields.
      tags:
      - Tickets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketCreate'
      responses:
        '201':
          description: Ticket created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tickets/{ticket_id}:
    get:
      operationId: getTicket
      summary: View a ticket
      description: Retrieves the details of a specific ticket by its ID, including all ticket properties and custom fields.
      tags:
      - Tickets
      parameters:
      - $ref: '#/components/parameters/TicketIdParam'
      - name: include
        in: query
        description: Include additional information in the response. Comma-separated values from conversations, requester, company, stats.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateTicket
      summary: Update a ticket
      description: Updates the properties of an existing ticket. Only the fields included in the request body will be updated.
      tags:
      - Tickets
      parameters:
      - $ref: '#/components/parameters/TicketIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketUpdate'
      responses:
        '200':
          description: Ticket updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ticket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteTicket
      summary: Delete a ticket
      description: Soft-deletes a ticket by moving it to the trash. The ticket can be restored later using the restore endpoint.
      tags:
      - Tickets
      parameters:
      - $ref: '#/components/parameters/TicketIdParam'
      responses:
        '204':
          description: Ticket deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tickets/{ticket_id}/restore:
    put:
      operationId: restoreTicket
      summary: Restore a deleted ticket
      description: Restores a previously deleted ticket from the trash.
      tags:
      - Tickets
      parameters:
      - $ref: '#/components/parameters/TicketIdParam'
      responses:
        '204':
          description: Ticket restored successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    TicketIdParam:
      name: ticket_id
      in: path
      required: true
      description: The ID of the ticket.
      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 (max 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
  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'
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        description:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          description: List of specific validation errors.
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error.
              message:
                type: string
                description: Error message for the field.
              code:
                type: string
                description: Error code.
    Ticket:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the ticket.
        subject:
          type: string
          description: Subject of the ticket.
        description:
          type: string
          description: HTML content of the ticket description.
        description_text:
          type: string
          description: Plain text content of the ticket description.
        status:
          type: integer
          description: Status of the ticket. 2=Open, 3=Pending, 4=Resolved, 5=Closed.
          enum:
          - 2
          - 3
          - 4
          - 5
        priority:
          type: integer
          description: Priority of the ticket. 1=Low, 2=Medium, 3=High, 4=Urgent.
          enum:
          - 1
          - 2
          - 3
          - 4
        source:
          type: integer
          description: Channel through which the ticket was created. 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback Widget, 10=Outbound Email.
        type:
          type: string
          description: Type of the ticket.
        requester_id:
          type: integer
          description: ID of the requester who raised the ticket.
        responder_id:
          type: integer
          description: ID of the agent assigned to the ticket.
        group_id:
          type: integer
          description: ID of the group to which the ticket is assigned.
        company_id:
          type: integer
          description: ID of the company associated with the ticket.
        product_id:
          type: integer
          description: ID of the product associated with the ticket.
        email:
          type: string
          format: email
          description: Email address of the requester.
        phone:
          type: string
          description: Phone number of the requester.
        tags:
          type: array
          description: Tags associated with the ticket.
          items:
            type: string
        due_by:
          type: string
          format: date-time
          description: Timestamp indicating when the ticket is due.
        fr_due_by:
          type: string
          format: date-time
          description: Timestamp indicating when the first response is due.
        is_escalated:
          type: boolean
          description: Whether the ticket has been escalated.
        custom_fields:
          type: object
          description: Key-value pairs of custom field values.
          additionalProperties: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the ticket was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the ticket was last updated.
    TicketUpdate:
      type: object
      properties:
        subject:
          type: string
          description: Subject of the ticket.
        description:
          type: string
          description: HTML content of the ticket description.
        status:
          type: integer
          description: Status of the ticket.
          enum:
          - 2
          - 3
          - 4
          - 5
        priority:
          type: integer
          description: Priority of the ticket.
          enum:
          - 1
          - 2
          - 3
          - 4
        responder_id:
          type: integer
          description: ID of the agent to assign.
        group_id:
          type: integer
          description: ID of the group to assign.
        type:
          type: string
          description: Type of the ticket.
        tags:
          type: array
          items:
            type: string
          description: Tags to associate with the ticket.
        custom_fields:
          type: object
          additionalProperties: true
          description: Key-value pairs for custom fields.
    TicketCreate:
      type: object
      required:
      - subject
      - description
      properties:
        subject:
          type: string
          description: Subject of the ticket.
        description:
          type: string
          description: HTML content of the ticket description.
        email:
          type: string
          format: email
          description: Email of the requester.
        phone:
          type: string
          description: Phone number of the requester.
        requester_id:
          type: integer
          description: ID of the requester.
        status:
          type: integer
          description: Status of the ticket.
          enum:
          - 2
          - 3
          - 4
          - 5
          default: 2
        priority:
          type: integer
          description: Priority of the ticket.
          enum:
          - 1
          - 2
          - 3
          - 4
          default: 1
        source:
          type: integer
          description: Channel through which the ticket was created.
        type:
          type: string
          description: Type of the ticket.
        responder_id:
          type: integer
          description: ID of the agent to assign.
        group_id:
          type: integer
          description: ID of the group to assign.
        product_id:
          type: integer
          description: ID of the associated product.
        company_id:
          type: integer
          description: ID of the associated company.
        tags:
          type: array
          items:
            type: string
          description: Tags to associate with the ticket.
        cc_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses to CC on the ticket.
        custom_fields:
          type: object
          additionalProperties: true
          description: Key-value pairs for custom fields.
        parent_id:
          type: integer
          description: ID of the parent ticket to create a child ticket.
  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/