openapi: 3.1.0
info:
  title: Freshworks Freshdesk API
  description: >-
    The Freshdesk API v2 is a RESTful API that provides programmatic access to
    Freshdesk helpdesk functionality. It allows developers to manage tickets,
    contacts, companies, agents, groups, and other helpdesk resources through
    standard CRUD operations. The API uses JSON for data exchange, supports
    API key authentication, and enables integration of Freshdesk customer
    support workflows into third-party applications and automation pipelines.
  version: '2.0'
  contact:
    name: Freshworks Support
    url: https://support.freshdesk.com/
  termsOfService: https://www.freshworks.com/terms/
externalDocs:
  description: Freshdesk API Documentation
  url: https://developers.freshdesk.com/api/
servers:
  - url: https://{domain}.freshdesk.com/api/v2
    description: Freshdesk Production Server
    variables:
      domain:
        default: yourdomain
        description: Your Freshdesk subdomain
tags:
  - name: Agents
    description: >-
      Manage helpdesk agents and their properties.
  - name: Business Hours
    description: >-
      Manage business hours configurations.
  - name: Companies
    description: >-
      Manage company records associated with contacts.
  - name: Contacts
    description: >-
      Manage customer contacts including creation, updates, merging,
      and deactivation.
  - name: Conversations
    description: >-
      Manage ticket conversations including replies, notes, and forwards.
  - name: Email Configs
    description: >-
      Manage email configuration settings for the helpdesk.
  - name: Groups
    description: >-
      Manage agent groups for ticket assignment and routing.
  - name: Products
    description: >-
      Manage products associated with the helpdesk.
  - name: Roles
    description: >-
      Manage agent roles and permissions.
  - name: SLA Policies
    description: >-
      Manage SLA policies for ticket response and resolution targets.
  - name: Surveys
    description: >-
      Manage customer satisfaction surveys.
  - name: Tickets
    description: >-
      Manage helpdesk tickets including creation, updates, assignment,
      and resolution workflows.
  - name: Time Entries
    description: >-
      Track time spent on tickets.
security:
  - basicAuth: []
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'
  /tickets/{ticket_id}/conversations:
    get:
      operationId: listTicketConversations
      summary: List all conversations of a ticket
      description: >-
        Retrieves all conversations (replies and notes) associated with
        a specific ticket.
      tags:
        - Conversations
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tickets/{ticket_id}/reply:
    post:
      operationId: replyToTicket
      summary: Reply to a ticket
      description: >-
        Adds a public reply to a ticket. The reply is sent to all
        recipients associated with the ticket.
      tags:
        - Conversations
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplyCreate'
      responses:
        '201':
          description: Reply created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tickets/{ticket_id}/notes:
    post:
      operationId: createNote
      summary: Create a note on a ticket
      description: >-
        Adds a private or public note to a ticket. Notes are used for
        internal communication or additional context.
      tags:
        - Conversations
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteCreate'
      responses:
        '201':
          description: Note created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts:
    get:
      operationId: listContacts
      summary: List all contacts
      description: >-
        Retrieves a paginated list of all contacts in the helpdesk.
        Supports filtering by email, phone, mobile, and company.
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: email
          in: query
          description: Filter contacts by email address.
          schema:
            type: string
            format: email
        - name: phone
          in: query
          description: Filter contacts by phone number.
          schema:
            type: string
        - name: company_id
          in: query
          description: Filter contacts by company ID.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createContact
      summary: Create a contact
      description: >-
        Creates a new contact in the helpdesk. At least one of name, email,
        phone, or mobile is required.
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '201':
          description: Contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contacts/{contact_id}:
    get:
      operationId: getContact
      summary: View a contact
      description: >-
        Retrieves the details of a specific contact by their ID.
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/ContactIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateContact
      summary: Update a contact
      description: >-
        Updates the properties of an existing contact.
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/ContactIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '200':
          description: Contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteContact
      summary: Delete a contact
      description: >-
        Soft-deletes a contact from the helpdesk.
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/ContactIdParam'
      responses:
        '204':
          description: Contact deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/{contact_id}/merge:
    put:
      operationId: mergeContacts
      summary: Merge contacts
      description: >-
        Merges secondary contacts into the primary contact specified by
        the contact_id path parameter.
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/ContactIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - secondary_contact_ids
              properties:
                secondary_contact_ids:
                  type: array
                  description: >-
                    Array of contact IDs to merge into the primary contact.
                  items:
                    type: integer
      responses:
        '200':
          description: Contacts merged successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /companies:
    get:
      operationId: listCompanies
      summary: List all companies
      description: >-
        Retrieves a paginated list of all companies in the helpdesk.
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCompany
      summary: Create a company
      description: >-
        Creates a new company record in the helpdesk.
      tags:
        - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyCreate'
      responses:
        '201':
          description: Company created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /companies/{company_id}:
    get:
      operationId: getCompany
      summary: View a company
      description: >-
        Retrieves the details of a specific company by its ID.
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/CompanyIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCompany
      summary: Update a company
      description: >-
        Updates the properties of an existing company record.
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/CompanyIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyCreate'
      responses:
        '200':
          description: Company updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCompany
      summary: Delete a company
      description: >-
        Deletes a company record from the helpdesk.
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/CompanyIdParam'
      responses:
        '204':
          description: Company deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /agents:
    get:
      operationId: listAgents
      summary: List all agents
      description: >-
        Retrieves a paginated list of all agents in the helpdesk.
        Supports filtering by email and state.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: email
          in: query
          description: Filter agents by email address.
          schema:
            type: string
            format: email
        - name: state
          in: query
          description: Filter agents by state.
          schema:
            type: string
            enum:
              - fulltime
              - occasional
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /agents/{agent_id}:
    get:
      operationId: getAgent
      summary: View an agent
      description: >-
        Retrieves the details of a specific agent by their ID.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AgentIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAgent
      summary: Update an agent
      description: >-
        Updates the properties of an existing agent.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AgentIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdate'
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /groups:
    get:
      operationId: listGroups
      summary: List all groups
      description: >-
        Retrieves a list of all agent groups in the helpdesk.
      tags:
        - Groups
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createGroup
      summary: Create a group
      description: >-
        Creates a new agent group in the helpdesk.
      tags:
        - Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
      responses:
        '201':
          description: Group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /groups/{group_id}:
    get:
      operationId: getGroup
      summary: View a group
      description: >-
        Retrieves the details of a specific agent group by its ID.
      tags:
        - Groups
      parameters:
        - $ref: '#/components/parameters/GroupIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateGroup
      summary: Update a group
      description: >-
        Updates the properties of an existing agent group.
      tags:
        - Groups
      parameters:
        - $ref: '#/components/parameters/GroupIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
      responses:
        '200':
          description: Group updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteGroup
      summary: Delete a group
      description: >-
        Deletes an agent group from the helpdesk.
      tags:
        - Groups
      parameters:
        - $ref: '#/components/parameters/GroupIdParam'
      responses:
        '204':
          description: Group deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /roles:
    get:
      operationId: listRoles
      summary: List all roles
      description: >-
        Retrieves a list of all agent roles configured in the helpdesk.
      tags:
        - Roles
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /roles/{role_id}:
    get:
      operationId: getRole
      summary: View a role
      description: >-
        Retrieves the details of a specific agent role by its ID.
      tags:
        - Roles
      parameters:
        - name: role_id
          in: path
          required: true
          description: The ID of the role to retrieve.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /products:
    get:
      operationId: listProducts
      summary: List all products
      description: >-
        Retrieves a list of all products configured in the helpdesk.
      tags:
        - Products
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/{product_id}:
    get:
      operationId: getProduct
      summary: View a product
      description: >-
        Retrieves the details of a specific product by its ID.
      tags:
        - Products
      parameters:
        - name: product_id
          in: path
          required: true
          description: The ID of the product to retrieve.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /email_configs:
    get:
      operationId: listEmailConfigs
      summary: List all email configurations
      description: >-
        Retrieves a list of all email configurations for the helpdesk.
      tags:
        - Email Configs
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmailConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sla_policies:
    get:
      operationId: listSLAPolicies
      summary: List all SLA policies
      description: >-
        Retrieves a list of all SLA policies configured in the helpdesk.
      tags:
        - SLA Policies
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SLAPolicy'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /business_hours:
    get:
      operationId: listBusinessHours
      summary: List all business hours
      description: >-
        Retrieves a list of all business hours configurations in the
        helpdesk.
      tags:
        - Business Hours
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BusinessHours'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /surveys/satisfaction_ratings:
    get:
      operationId: listSatisfactionRatings
      summary: List all satisfaction ratings
      description: >-
        Retrieves a list of all customer satisfaction ratings received
        for helpdesk tickets.
      tags:
        - Surveys
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: created_since
          in: query
          description: Filter ratings created since this timestamp.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SatisfactionRating'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tickets/{ticket_id}/time_entries:
    get:
      operationId: listTicketTimeEntries
      summary: List all time entries for a ticket
      description: >-
        Retrieves all time entries logged against a specific ticket.
      tags:
        - Time Entries
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TimeEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createTicketTimeEntry
      summary: Create a time entry for a ticket
      description: >-
        Logs a new time entry against a specific ticket for tracking
        time spent on support activities.
      tags:
        - Time Entries
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeEntryCreate'
      responses:
        '201':
          description: Time entry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Use your API key as the username and X as the password. The API
        key can be found in your Freshdesk profile 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 (max 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    TicketIdParam:
      name: ticket_id
      in: path
      required: true
      description: The ID of the ticket.
      schema:
        type: integer
    ContactIdParam:
      name: contact_id
      in: path
      required: true
      description: The ID of the contact.
      schema:
        type: integer
    CompanyIdParam:
      name: company_id
      in: path
      required: true
      description: The ID of the company.
      schema:
        type: integer
    AgentIdParam:
      name: agent_id
      in: path
      required: true
      description: The ID of the agent.
      schema:
        type: integer
    GroupIdParam:
      name: group_id
      in: path
      required: true
      description: The ID of the group.
      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:
    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.
    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.
    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.
    Conversation:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the conversation.
        body:
          type: string
          description: HTML content of the conversation.
        body_text:
          type: string
          description: Plain text content of the conversation.
        incoming:
          type: boolean
          description: Whether the conversation was incoming from the customer.
        private:
          type: boolean
          description: Whether the conversation is a private note.
        user_id:
          type: integer
          description: ID of the user who created the conversation.
        support_email:
          type: string
          description: Support email address used for the conversation.
        ticket_id:
          type: integer
          description: ID of the ticket this conversation belongs to.
        to_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses the conversation was sent to.
        cc_emails:
          type: array
          items:
            type: string
            format: email
          description: CC email addresses on the conversation.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the conversation was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the conversation was last updated.
    ReplyCreate:
      type: object
      required:
        - body
      properties:
        body:
          type: string
          description: HTML content of the reply.
        cc_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses to CC.
        bcc_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses to BCC.
    NoteCreate:
      type: object
      required:
        - body
      properties:
        body:
          type: string
          description: HTML content of the note.
        private:
          type: boolean
          description: Whether the note is private (internal only).
          default: true
        incoming:
          type: boolean
          description: Whether the note is incoming.
          default: false
    Contact:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the contact.
        name:
          type: string
          description: Full name of the contact.
        email:
          type: string
          format: email
          description: Primary email address of the contact.
        phone:
          type: string
          description: Phone number of the contact.
        mobile:
          type: string
          description: Mobile number of the contact.
        address:
          type: string
          description: Address of the contact.
        description:
          type: string
          description: Description or notes about the contact.
        job_title:
          type: string
          description: Job title of the contact.
        company_id:
          type: integer
          description: ID of the associated company.
        language:
          type: string
          description: Language preference of the contact.
        time_zone:
          type: string
          description: Time zone of the contact.
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the contact.
        active:
          type: boolean
          description: Whether the contact is active.
        custom_fields:
          type: object
          additionalProperties: true
          description: Key-value pairs for custom fields.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the contact was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the contact was last updated.
    ContactCreate:
      type: object
      properties:
        name:
          type: string
          description: Full name of the contact.
        email:
          type: string
          format: email
          description: Primary email address.
        phone:
          type: string
          description: Phone number.
        mobile:
          type: string
          description: Mobile number.
        address:
          type: string
          description: Address of the contact.
        description:
          type: string
          description: Description or notes about the contact.
        job_title:
          type: string
          description: Job title of the contact.
        company_id:
          type: integer
          description: ID of the associated company.
        language:
          type: string
          description: Language preference.
        time_zone:
          type: string
          description: Time zone.
        tags:
          type: array
          items:
            type: string
          description: Tags to associate.
        custom_fields:
          type: object
          additionalProperties: true
          description: Key-value pairs for custom fields.
    Company:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the company.
        name:
          type: string
          description: Name of the company.
        description:
          type: string
          description: Description of the company.
        note:
          type: string
          description: Notes about the company.
        domains:
          type: array
          items:
            type: string
          description: Email domains associated with the company.
        health_score:
          type: string
          description: Health score of the company account.
        account_tier:
          type: string
          description: Tier of the company account.
        renewal_date:
          type: string
          format: date
          description: Date of account renewal.
        industry:
          type: string
          description: Industry sector of the company.
        custom_fields:
          type: object
          additionalProperties: true
          description: Key-value pairs for custom fields.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the company was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the company was last updated.
    CompanyCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the company.
        description:
          type: string
          description: Description of the company.
        note:
          type: string
          description: Notes about the company.
        domains:
          type: array
          items:
            type: string
          description: Email domains associated with the company.
        health_score:
          type: string
          description: Health score of the company account.
        account_tier:
          type: string
          description: Tier of the company account.
        renewal_date:
          type: string
          format: date
          description: Date of account renewal.
        industry:
          type: string
          description: Industry sector.
        custom_fields:
          type: object
          additionalProperties: true
          description: Key-value pairs for custom fields.
    Agent:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the agent.
        contact:
          type: object
          description: Contact information for the agent.
          properties:
            name:
              type: string
              description: Name of the agent.
            email:
              type: string
              format: email
              description: Email address of the agent.
            phone:
              type: string
              description: Phone number of the agent.
            mobile:
              type: string
              description: Mobile number of the agent.
            job_title:
              type: string
              description: Job title of the agent.
        type:
          type: string
          description: Type of agent (support_agent, field_agent, collaborator).
        occasional:
          type: boolean
          description: Whether the agent is an occasional agent.
        available:
          type: boolean
          description: Whether the agent is currently available.
        group_ids:
          type: array
          items:
            type: integer
          description: IDs of groups the agent belongs to.
        role_ids:
          type: array
          items:
            type: integer
          description: IDs of roles assigned to the agent.
        ticket_scope:
          type: integer
          description: Scope of tickets the agent can access.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the agent was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the agent was last updated.
    AgentUpdate:
      type: object
      properties:
        occasional:
          type: boolean
          description: Whether the agent is occasional.
        group_ids:
          type: array
          items:
            type: integer
          description: IDs of groups to assign.
        role_ids:
          type: array
          items:
            type: integer
          description: IDs of roles to assign.
        ticket_scope:
          type: integer
          description: Scope of tickets the agent can access.
    Group:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the group.
        name:
          type: string
          description: Name of the group.
        description:
          type: string
          description: Description of the group.
        agent_ids:
          type: array
          items:
            type: integer
          description: IDs of agents in the group.
        auto_ticket_assign:
          type: boolean
          description: Whether auto ticket assignment is enabled.
        escalate_to:
          type: integer
          description: Agent ID to escalate unassigned tickets to.
        unassigned_for:
          type: string
          description: Time duration after which tickets are escalated.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the group was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the group was last updated.
    GroupCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the group.
        description:
          type: string
          description: Description of the group.
        agent_ids:
          type: array
          items:
            type: integer
          description: IDs of agents to include.
        auto_ticket_assign:
          type: boolean
          description: Whether to enable auto ticket assignment.
        escalate_to:
          type: integer
          description: Agent ID to escalate unassigned tickets to.
        unassigned_for:
          type: string
          description: Time duration after which tickets are escalated.
    Role:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the role.
        name:
          type: string
          description: Name of the role.
        description:
          type: string
          description: Description of the role.
        default:
          type: boolean
          description: Whether this is a default system role.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the role was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the role was last updated.
    Product:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the product.
        name:
          type: string
          description: Name of the product.
        description:
          type: string
          description: Description of the product.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the product was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the product was last updated.
    EmailConfig:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the email configuration.
        name:
          type: string
          description: Friendly name of the email configuration.
        reply_email:
          type: string
          format: email
          description: Reply-to email address.
        support_email:
          type: string
          format: email
          description: Support email address for receiving tickets.
        active:
          type: boolean
          description: Whether the email configuration is active.
        product_id:
          type: integer
          description: ID of the associated product.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the configuration was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the configuration was last updated.
    SLAPolicy:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the SLA policy.
        name:
          type: string
          description: Name of the SLA policy.
        description:
          type: string
          description: Description of the SLA policy.
        is_default:
          type: boolean
          description: Whether this is the default SLA policy.
        active:
          type: boolean
          description: Whether the SLA policy is active.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the SLA policy was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the SLA policy was last updated.
    BusinessHours:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the business hours configuration.
        name:
          type: string
          description: Name of the business hours configuration.
        description:
          type: string
          description: Description of the business hours.
        time_zone:
          type: string
          description: Time zone for the business hours.
        is_default:
          type: boolean
          description: Whether this is the default business hours.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the configuration was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the configuration was last updated.
    SatisfactionRating:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the satisfaction rating.
        survey_id:
          type: integer
          description: ID of the associated survey.
        user_id:
          type: integer
          description: ID of the user who provided the rating.
        agent_id:
          type: integer
          description: ID of the agent who handled the ticket.
        ticket_id:
          type: integer
          description: ID of the ticket that was rated.
        rating:
          type: integer
          description: Satisfaction rating value.
        feedback:
          type: string
          description: Feedback text from the customer.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the rating was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the rating was last updated.
    TimeEntry:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the time entry.
        agent_id:
          type: integer
          description: ID of the agent who logged the time.
        billable:
          type: boolean
          description: Whether the time entry is billable.
        executed_at:
          type: string
          format: date-time
          description: Timestamp when the work was executed.
        note:
          type: string
          description: Note describing the work performed.
        start_time:
          type: string
          format: date-time
          description: Start time of the time entry.
        time_spent:
          type: string
          description: Duration of time spent in HH:MM format.
        timer_running:
          type: boolean
          description: Whether the timer is currently running.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the time entry was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the time entry was last updated.
    TimeEntryCreate:
      type: object
      required:
        - time_spent
      properties:
        agent_id:
          type: integer
          description: ID of the agent logging the time.
        billable:
          type: boolean
          description: Whether the time entry is billable.
        executed_at:
          type: string
          format: date-time
          description: Timestamp when the work was executed.
        note:
          type: string
          description: Note describing the work performed.
        time_spent:
          type: string
          description: Duration of time spent in HH:MM format.
    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.