Freshworks Freshsales API

openapi: 3.1.0
info:
  title: Freshworks Freshsales API
  description: >-
    The Freshsales API is a RESTful API that enables developers to access and
    manage CRM data within Freshsales. It supports operations for contacts,
    accounts, deals, leads, tasks, appointments, notes, and sales activities.
    The API uses token-based authentication and allows developers to read,
    modify, add, or delete CRM data, making it possible to build custom
    integrations, automate sales workflows, and synchronize Freshsales data
    with other business applications.
  version: '1.0'
  contact:
    name: Freshworks Support
    url: https://support.freshsales.io/
  termsOfService: https://www.freshworks.com/terms/
externalDocs:
  description: Freshsales API Documentation
  url: https://developers.freshworks.com/crm/api/
servers:
  - url: https://{domain}.myfreshworks.com/crm/sales/api
    description: Freshsales Production Server
    variables:
      domain:
        default: yourdomain
        description: Your Freshworks bundle alias
tags:
  - name: Accounts
    description: >-
      Manage company accounts with which you have business relationships.
  - name: Appointments
    description: >-
      Manage scheduled appointments and meetings.
  - name: Contacts
    description: >-
      Manage customer contacts and their associated information in the CRM.
  - name: Deals
    description: >-
      Manage sales deals and their pipeline progression.
  - name: Leads
    description: >-
      Manage sales leads before they are converted to contacts or accounts.
  - name: Notes
    description: >-
      Manage notes attached to CRM records.
  - name: Sales Activities
    description: >-
      Track and manage sales activity records.
  - name: Tasks
    description: >-
      Manage tasks associated with sales activities.
security:
  - apiKeyAuth: []
paths:
  /contacts:
    get:
      operationId: listContacts
      summary: List all contacts
      description: >-
        Retrieves a paginated list of all contacts in the CRM. Supports
        filtering and sorting by various contact fields.
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/SortTypeParam'
        - name: filter
          in: query
          description: Pre-defined view filter to apply.
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createContact
      summary: Create a contact
      description: >-
        Creates a new contact in the CRM with the specified properties.
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreate'
      responses:
        '200':
          description: Contact created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact:
                    $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:
                type: object
                properties:
                  contact:
                    $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:
                type: object
                properties:
                  contact:
                    $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: >-
        Deletes a contact from the CRM.
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/ContactIdParam'
      responses:
        '204':
          description: Contact deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sales_accounts:
    get:
      operationId: listAccounts
      summary: List all accounts
      description: >-
        Retrieves a paginated list of all company accounts in the CRM.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/SortTypeParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  sales_accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAccount
      summary: Create an account
      description: >-
        Creates a new company account in the CRM.
      tags:
        - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
      responses:
        '200':
          description: Account created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sales_account:
                    $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sales_accounts/{account_id}:
    get:
      operationId: getAccount
      summary: View an account
      description: >-
        Retrieves the details of a specific company account by its ID.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  sales_account:
                    $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAccount
      summary: Update an account
      description: >-
        Updates the properties of an existing company account.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreate'
      responses:
        '200':
          description: Account updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sales_account:
                    $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAccount
      summary: Delete an account
      description: >-
        Deletes a company account from the CRM.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/AccountIdParam'
      responses:
        '204':
          description: Account deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /deals:
    get:
      operationId: listDeals
      summary: List all deals
      description: >-
        Retrieves a paginated list of all deals in the CRM pipeline.
      tags:
        - Deals
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/SortTypeParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  deals:
                    type: array
                    items:
                      $ref: '#/components/schemas/Deal'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDeal
      summary: Create a deal
      description: >-
        Creates a new deal in the sales pipeline.
      tags:
        - Deals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealCreate'
      responses:
        '200':
          description: Deal created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  deal:
                    $ref: '#/components/schemas/Deal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /deals/{deal_id}:
    get:
      operationId: getDeal
      summary: View a deal
      description: >-
        Retrieves the details of a specific deal by its ID.
      tags:
        - Deals
      parameters:
        - $ref: '#/components/parameters/DealIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  deal:
                    $ref: '#/components/schemas/Deal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateDeal
      summary: Update a deal
      description: >-
        Updates the properties of an existing deal.
      tags:
        - Deals
      parameters:
        - $ref: '#/components/parameters/DealIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DealCreate'
      responses:
        '200':
          description: Deal updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  deal:
                    $ref: '#/components/schemas/Deal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDeal
      summary: Delete a deal
      description: >-
        Deletes a deal from the CRM.
      tags:
        - Deals
      parameters:
        - $ref: '#/components/parameters/DealIdParam'
      responses:
        '204':
          description: Deal deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /leads:
    get:
      operationId: listLeads
      summary: List all leads
      description: >-
        Retrieves a paginated list of all leads in the CRM.
      tags:
        - Leads
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/SortTypeParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  leads:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLead
      summary: Create a lead
      description: >-
        Creates a new lead in the CRM.
      tags:
        - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadCreate'
      responses:
        '200':
          description: Lead created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  lead:
                    $ref: '#/components/schemas/Lead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /leads/{lead_id}:
    get:
      operationId: getLead
      summary: View a lead
      description: >-
        Retrieves the details of a specific lead by their ID.
      tags:
        - Leads
      parameters:
        - $ref: '#/components/parameters/LeadIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  lead:
                    $ref: '#/components/schemas/Lead'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateLead
      summary: Update a lead
      description: >-
        Updates the properties of an existing lead.
      tags:
        - Leads
      parameters:
        - $ref: '#/components/parameters/LeadIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadCreate'
      responses:
        '200':
          description: Lead updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  lead:
                    $ref: '#/components/schemas/Lead'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteLead
      summary: Delete a lead
      description: >-
        Deletes a lead from the CRM.
      tags:
        - Leads
      parameters:
        - $ref: '#/components/parameters/LeadIdParam'
      responses:
        '204':
          description: Lead deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tasks:
    get:
      operationId: listTasks
      summary: List all tasks
      description: >-
        Retrieves a paginated list of all tasks in the CRM.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - name: filter
          in: query
          description: >-
            Filter tasks by status (open, due_today, due_tomorrow, overdue, completed).
          schema:
            type: string
            enum:
              - open
              - due_today
              - due_tomorrow
              - overdue
              - completed
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTask
      summary: Create a task
      description: >-
        Creates a new task in the CRM.
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreate'
      responses:
        '200':
          description: Task created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  task:
                    $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tasks/{task_id}:
    get:
      operationId: getTask
      summary: View a task
      description: >-
        Retrieves the details of a specific task by its ID.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  task:
                    $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateTask
      summary: Update a task
      description: >-
        Updates the properties of an existing task.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreate'
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  task:
                    $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteTask
      summary: Delete a task
      description: >-
        Deletes a task from the CRM.
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/TaskIdParam'
      responses:
        '204':
          description: Task deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /appointments:
    get:
      operationId: listAppointments
      summary: List all appointments
      description: >-
        Retrieves a paginated list of all appointments in the CRM.
      tags:
        - Appointments
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - name: filter
          in: query
          description: Filter appointments by time range.
          schema:
            type: string
            enum:
              - upcoming
              - past
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  appointments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAppointment
      summary: Create an appointment
      description: >-
        Creates a new appointment or meeting in the CRM.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentCreate'
      responses:
        '200':
          description: Appointment created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  appointment:
                    $ref: '#/components/schemas/Appointment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /appointments/{appointment_id}:
    get:
      operationId: getAppointment
      summary: View an appointment
      description: >-
        Retrieves the details of a specific appointment by its ID.
      tags:
        - Appointments
      parameters:
        - name: appointment_id
          in: path
          required: true
          description: The ID of the appointment.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  appointment:
                    $ref: '#/components/schemas/Appointment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAppointment
      summary: Delete an appointment
      description: >-
        Deletes an appointment from the CRM.
      tags:
        - Appointments
      parameters:
        - name: appointment_id
          in: path
          required: true
          description: The ID of the appointment.
          schema:
            type: integer
      responses:
        '204':
          description: Appointment deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /notes:
    post:
      operationId: createNote
      summary: Create a note
      description: >-
        Creates a new note attached to a CRM record (contact, account,
        deal, or lead).
      tags:
        - Notes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteCreate'
      responses:
        '200':
          description: Note created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  note:
                    $ref: '#/components/schemas/Note'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /notes/{note_id}:
    delete:
      operationId: deleteNote
      summary: Delete a note
      description: >-
        Deletes a note from the CRM.
      tags:
        - Notes
      parameters:
        - name: note_id
          in: path
          required: true
          description: The ID of the note.
          schema:
            type: integer
      responses:
        '204':
          description: Note deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sales_activities:
    get:
      operationId: listSalesActivities
      summary: List all sales activities
      description: >-
        Retrieves a paginated list of all sales activities in the CRM.
      tags:
        - Sales Activities
      parameters:
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  sales_activities:
                    type: array
                    items:
                      $ref: '#/components/schemas/SalesActivity'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSalesActivity
      summary: Create a sales activity
      description: >-
        Creates a new sales activity record in the CRM.
      tags:
        - Sales Activities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalesActivityCreate'
      responses:
        '200':
          description: Sales activity created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sales_activity:
                    $ref: '#/components/schemas/SalesActivity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Token-based authentication. Use the format "Token token=your_api_key".
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number for pagination.
      schema:
        type: integer
        minimum: 1
        default: 1
    SortParam:
      name: sort
      in: query
      description: Field to sort by.
      schema:
        type: string
    SortTypeParam:
      name: sort_type
      in: query
      description: Sort order direction.
      schema:
        type: string
        enum:
          - asc
          - desc
    ContactIdParam:
      name: contact_id
      in: path
      required: true
      description: The ID of the contact.
      schema:
        type: integer
    AccountIdParam:
      name: account_id
      in: path
      required: true
      description: The ID of the account.
      schema:
        type: integer
    DealIdParam:
      name: deal_id
      in: path
      required: true
      description: The ID of the deal.
      schema:
        type: integer
    LeadIdParam:
      name: lead_id
      in: path
      required: true
      description: The ID of the lead.
      schema:
        type: integer
    TaskIdParam:
      name: task_id
      in: path
      required: true
      description: The ID of the task.
      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:
    Contact:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the contact.
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        display_name:
          type: string
          description: Display name.
        email:
          type: string
          format: email
          description: Primary email address.
        work_number:
          type: string
          description: Work phone number.
        mobile_number:
          type: string
          description: Mobile phone number.
        address:
          type: string
          description: Mailing address.
        city:
          type: string
          description: City.
        state:
          type: string
          description: State or province.
        zipcode:
          type: string
          description: ZIP or postal code.
        country:
          type: string
          description: Country.
        job_title:
          type: string
          description: Job title.
        department:
          type: string
          description: Department name.
        lead_score:
          type: integer
          description: Lead score value.
        sales_account_id:
          type: integer
          description: ID of the associated account.
        owner_id:
          type: integer
          description: ID of the owning sales agent.
        lifecycle_stage_id:
          type: integer
          description: ID of the lifecycle stage.
        custom_field:
          type: object
          additionalProperties: true
          description: Custom field values.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    ContactCreate:
      type: object
      properties:
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        email:
          type: string
          format: email
          description: Primary email address.
        work_number:
          type: string
          description: Work phone number.
        mobile_number:
          type: string
          description: Mobile phone number.
        address:
          type: string
          description: Mailing address.
        city:
          type: string
          description: City.
        state:
          type: string
          description: State or province.
        zipcode:
          type: string
          description: ZIP or postal code.
        country:
          type: string
          description: Country.
        job_title:
          type: string
          description: Job title.
        department:
          type: string
          description: Department name.
        sales_account_id:
          type: integer
          description: ID of the associated account.
        owner_id:
          type: integer
          description: ID of the owning sales agent.
        custom_field:
          type: object
          additionalProperties: true
          description: Custom field values.
    Account:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the account.
        name:
          type: string
          description: Name of the company.
        address:
          type: string
          description: Address.
        city:
          type: string
          description: City.
        state:
          type: string
          description: State or province.
        zipcode:
          type: string
          description: ZIP or postal code.
        country:
          type: string
          description: Country.
        phone:
          type: string
          description: Phone number.
        website:
          type: string
          format: uri
          description: Website URL.
        number_o

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/freshworks/refs/heads/main/openapi/freshworks-freshsales-api-openapi.yml