Freshdesk connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

What you can do

Connect this agent connector to let your agent:

• Create time entry, ticket note, solution article — Log a time entry against a ticket for billing or effort tracking
• List time entries, solution articles, satisfaction ratings — Retrieve time entries logged across tickets, with filtering by agent, company, and execution date range
• Filter tickets — Search tickets using Freshdesk’s structured query syntax (field:value expressions combined with AND/OR), for filtering beyond what List Tickets’ predefined filters support
• Forward ticket — Forward a ticket’s conversation to one or more external email addresses, optionally including the full ticket thread
• Delete ticket, contact, company — Move a ticket to the trash in Freshdesk
• Update contact, company, agent — Update an existing contact in Freshdesk

Common workflows

Proxy API call

Don’t worry about your Freshdesk domain in the path. Scalekit automatically resolves {{domain}} from the connected account’s configuration and constructs the full URL for you. For example, if your Freshdesk domain is mycompany.freshdesk.com, a request with path="/v2/agents/me" will be sent to https://mycompany.freshdesk.com/api/v2/agents/me automatically.

Node.js

const result = await actions.request({
  connectionName: 'freshdesk',
  identifier: 'user_123',
  path: '/v2/agents/me',
  method: 'GET',
});
console.log(result);

Python

result = actions.request(
    connection_name='freshdesk',
    identifier='user_123',
    path="/v2/agents/me",
    method="GET",
)
print(result)

Execute a tool

Node.js

const result = await actions.executeTool({
  connector: 'freshdesk',
  identifier: 'user_123',
  toolName: 'freshdesk_agent_create',
  toolInput: {},
});
console.log(result);

Python

result = actions.execute_tool(
    connection_name='freshdesk',
    identifier='user_123',
    tool_name='freshdesk_agent_create',
    tool_input={},
)
print(result)

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

freshdesk_agent_create#Create a new agent in Freshdesk. Email is required and must be unique. Agent will receive invitation email to set up account. At least one role must be assigned.12 params▾

Create a new agent in Freshdesk. Email is required and must be unique. Agent will receive invitation email to set up account. At least one role must be assigned.

NameTypeRequiredDescription

emailstringrequiredEmail address of the agent (must be unique)

role_idsarrayrequiredArray of role IDs to assign to the agent (at least one required)

ticket_scopenumberrequiredTicket permission level (1=Global Access, 2=Group Access, 3=Restricted Access)

agent_typenumberoptionalType of agent (1=Support Agent, 2=Field Agent, 3=Collaborator)

focus_modebooleanoptionalFocus mode setting for the agent

group_idsarrayoptionalArray of group IDs to assign the agent to

languagestringoptionalLanguage preference of the agent

namestringoptionalFull name of the agent

occasionalbooleanoptionalWhether the agent is occasional (true) or full-time (false)

signaturestringoptionalAgent email signature in HTML format

skill_idsarrayoptionalArray of skill IDs to assign to the agent

time_zonestringoptionalTime zone of the agent

freshdesk_agent_delete#Delete an agent from Freshdesk. This action is irreversible and will remove the agent from the system. The agent will no longer have access to the helpdesk and all associated data will be permanently deleted.1 param▾

Delete an agent from Freshdesk. This action is irreversible and will remove the agent from the system. The agent will no longer have access to the helpdesk and all associated data will be permanently deleted.

NameTypeRequiredDescription

agent_idnumberrequiredID of the agent to delete

freshdesk_agent_get#Retrieve details of a specific agent by ID, including their roles, groups, skills, ticket scope, and contact information.1 param▾

Retrieve details of a specific agent by ID, including their roles, groups, skills, ticket scope, and contact information.

NameTypeRequiredDescription

agent_idnumberrequiredID of the agent to retrieve

freshdesk_agent_update#Update an existing agent in Freshdesk. Only the fields provided are changed. Use this to change an agent's role, ticket scope, group/skill assignments, or contact details.15 params▾

Update an existing agent in Freshdesk. Only the fields provided are changed. Use this to change an agent's role, ticket scope, group/skill assignments, or contact details.

NameTypeRequiredDescription

agent_idnumberrequiredID of the agent to update

agent_typenumberoptionalType of agent (1=Support Agent, 2=Field Agent, 3=Collaborator)

emailstringoptionalEmail address of the agent

focus_modebooleanoptionalFocus mode setting for the agent

group_idsarrayoptionalArray of group IDs to assign the agent to

languagestringoptionalLanguage preference of the agent

mobilestringoptionalMobile phone number of the agent

namestringoptionalFull name of the agent

occasionalbooleanoptionalWhether the agent is occasional (true) or full-time (false)

phonestringoptionalTelephone number of the agent

role_idsarrayoptionalArray of role IDs to assign to the agent

signaturestringoptionalAgent email signature in HTML format

skill_idsarrayoptionalArray of skill IDs to assign to the agent

ticket_scopenumberoptionalTicket permission level (1=Global Access, 2=Group Access, 3=Restricted Access)

time_zonestringoptionalTime zone of the agent

freshdesk_agents_list#Retrieve a list of agents from Freshdesk with filtering options. Returns agent details including IDs, contact information, roles, and availability status. Supports pagination with up to 100 agents per page.6 params▾

Retrieve a list of agents from Freshdesk with filtering options. Returns agent details including IDs, contact information, roles, and availability status. Supports pagination with up to 100 agents per page.

NameTypeRequiredDescription

emailstringoptionalFilter agents by email address

mobilestringoptionalFilter agents by mobile number

pagenumberoptionalPage number for pagination (starts from 1)

per_pagenumberoptionalNumber of agents per page (max 100)

phonestringoptionalFilter agents by phone number

statestringoptionalFilter agents by state (fulltime or occasional)

freshdesk_canned_response_create#Create a new canned response template that agents can insert into ticket replies. Must belong to an existing canned response folder.5 params▾

Create a new canned response template that agents can insert into ticket replies. Must belong to an existing canned response folder.

NameTypeRequiredDescription

content_htmlstringrequiredHTML content of the canned response

folder_idnumberrequiredID of the canned response folder this response belongs to

titlestringrequiredTitle of the canned response

group_idsarrayoptionalArray of group IDs that can use this response, when visibility is 2

visibilitynumberoptionalWho can see this canned response. 0=personal, 1=all agents, 2=specific groups

freshdesk_canned_response_folders_list#Retrieve all canned response folders, each including the canned responses stored inside it. Use a folder ID with Create Canned Response.0 params▾

Retrieve all canned response folders, each including the canned responses stored inside it. Use a folder ID with Create Canned Response.

freshdesk_companies_list#Retrieve a paginated list of all companies in the Freshdesk account.2 params▾

Retrieve a paginated list of all companies in the Freshdesk account.

NameTypeRequiredDescription

pagenumberoptionalPage number for pagination (starts from 1)

per_pagenumberoptionalNumber of companies per page (max 100)

freshdesk_company_create#Create a new company in Freshdesk. Name is required. Use domains to auto-associate contacts and tickets whose email domain matches.7 params▾

Create a new company in Freshdesk. Name is required. Use domains to auto-associate contacts and tickets whose email domain matches.

NameTypeRequiredDescription

namestringrequiredName of the company

custom_fieldsobjectoptionalKey-value pairs containing custom field names and values

descriptionstringoptionalDescription of the company

domainsarrayoptionalArray of email domains associated with the company

health_scorestringoptionalHealth score label for the company

industrystringoptionalIndustry the company operates in

notestringoptionalInternal note about the company

freshdesk_company_delete#Delete a company from Freshdesk. This action is irreversible; contacts and tickets associated with the company are not deleted but lose their company association.1 param▾

Delete a company from Freshdesk. This action is irreversible; contacts and tickets associated with the company are not deleted but lose their company association.

NameTypeRequiredDescription

company_idnumberrequiredID of the company to delete

freshdesk_company_get#Retrieve details of a specific company by ID, including custom fields, domains, and health score.1 param▾

Retrieve details of a specific company by ID, including custom fields, domains, and health score.

NameTypeRequiredDescription

company_idnumberrequiredID of the company to retrieve

freshdesk_company_update#Update an existing company in Freshdesk. Only the fields provided are changed.8 params▾

Update an existing company in Freshdesk. Only the fields provided are changed.

NameTypeRequiredDescription

company_idnumberrequiredID of the company to update

custom_fieldsobjectoptionalKey-value pairs containing custom field names and values

descriptionstringoptionalDescription of the company

domainsarrayoptionalArray of email domains associated with the company

health_scorestringoptionalHealth score label for the company

industrystringoptionalIndustry the company operates in

namestringoptionalName of the company

notestringoptionalInternal note about the company

freshdesk_contact_create#Create a new contact in Freshdesk. Email and name are required. Supports custom fields, company assignment, and contact segmentation.12 params▾

Create a new contact in Freshdesk. Email and name are required. Supports custom fields, company assignment, and contact segmentation.

NameTypeRequiredDescription

emailstringrequiredEmail address of the contact

namestringrequiredFull name of the contact

addressstringoptionalAddress of the contact

company_idnumberoptionalCompany ID to associate with the contact

custom_fieldsobjectoptionalKey-value pairs for custom field values

descriptionstringoptionalDescription about the contact

job_titlestringoptionalJob title of the contact

languagestringoptionalLanguage preference of the contact

mobilestringoptionalMobile number of the contact

phonestringoptionalPhone number of the contact

tagsarrayoptionalArray of tags to associate with the contact

time_zonestringoptionalTime zone of the contact

freshdesk_contact_delete#Soft-delete a contact in Freshdesk, moving it to the trash. The contact can be restored from the trash within Freshdesk before it is permanently purged.1 param▾

Soft-delete a contact in Freshdesk, moving it to the trash. The contact can be restored from the trash within Freshdesk before it is permanently purged.

NameTypeRequiredDescription

contact_idnumberrequiredID of the contact to delete

freshdesk_contact_get#Retrieve details of a specific contact by ID, including custom fields and associated company.1 param▾

Retrieve details of a specific contact by ID, including custom fields and associated company.

NameTypeRequiredDescription

contact_idnumberrequiredID of the contact to retrieve

freshdesk_contact_update#Update an existing contact in Freshdesk. Only the fields provided are changed.10 params▾

Update an existing contact in Freshdesk. Only the fields provided are changed.

NameTypeRequiredDescription

contact_idnumberrequiredID of the contact to update

company_idnumberoptionalCompany ID to associate with the contact

custom_fieldsobjectoptionalKey-value pairs for custom field values

descriptionstringoptionalDescription about the contact

emailstringoptionalEmail address of the contact

job_titlestringoptionalJob title of the contact

mobilestringoptionalMobile number of the contact

namestringoptionalFull name of the contact

phonestringoptionalPhone number of the contact

tagsarrayoptionalArray of tags to associate with the contact

freshdesk_contacts_list#Retrieve a list of contacts with filtering and pagination. Supports filtering by email, phone, mobile, company, and state.8 params▾

Retrieve a list of contacts with filtering and pagination. Supports filtering by email, phone, mobile, company, and state.

NameTypeRequiredDescription

company_idnumberoptionalFilter by company ID

emailstringoptionalFilter by contact email

mobilestringoptionalFilter by mobile number

pagenumberoptionalPage number for pagination (starts from 1)

per_pagenumberoptionalNumber of contacts per page (max 100)

phonestringoptionalFilter by phone number

statestringoptionalFilter by contact state

updated_sincestringoptionalFilter contacts updated since this timestamp (ISO 8601)

freshdesk_group_create#Create a new agent group in Freshdesk for routing and organizing tickets. Name is required.5 params▾

Create a new agent group in Freshdesk for routing and organizing tickets. Name is required.

NameTypeRequiredDescription

namestringrequiredName of the group

agent_idsarrayoptionalArray of agent IDs to add to the group

descriptionstringoptionalDescription of the group

escalate_tonumberoptionalAgent ID to escalate unassigned tickets to after the unassigned_for period

unassigned_forstringoptionalTime after which an unassigned ticket in this group is escalated

freshdesk_groups_list#Retrieve a list of all agent groups in Freshdesk, including group membership and escalation settings.0 params▾

Retrieve a list of all agent groups in Freshdesk, including group membership and escalation settings.

freshdesk_roles_list#Retrieve a list of all roles from Freshdesk. Returns role details including IDs, names, descriptions, default status, and timestamps. This endpoint provides information about the different permission levels and access controls available in the Freshdesk system.0 params▾

Retrieve a list of all roles from Freshdesk. Returns role details including IDs, names, descriptions, default status, and timestamps. This endpoint provides information about the different permission levels and access controls available in the Freshdesk system.

freshdesk_satisfaction_ratings_list#Retrieve customer satisfaction survey ratings submitted across tickets, optionally filtered to ratings created since a given time.2 params▾

Retrieve customer satisfaction survey ratings submitted across tickets, optionally filtered to ratings created since a given time.

NameTypeRequiredDescription

created_sincestringoptionalOnly return ratings created since this timestamp (ISO 8601)

pagenumberoptionalPage number for pagination (starts from 1)

freshdesk_solution_article_create#Create a new knowledge base article inside a solution folder. Status controls whether it is a draft or published.5 params▾

Create a new knowledge base article inside a solution folder. Status controls whether it is a draft or published.

NameTypeRequiredDescription

descriptionstringrequiredHTML content of the article body

folder_idnumberrequiredID of the solution folder to create the article in

titlestringrequiredTitle of the article

statusnumberoptionalPublication status of the article. 1=Draft, 2=Published

tagsarrayoptionalArray of tags to associate with the article

freshdesk_solution_articles_list#Retrieve all knowledge base articles inside a specific solution folder.3 params▾

Retrieve all knowledge base articles inside a specific solution folder.

NameTypeRequiredDescription

folder_idnumberrequiredID of the solution folder to list articles from

pagenumberoptionalPage number for pagination (starts from 1)

per_pagenumberoptionalNumber of articles per page (max 100)

freshdesk_ticket_create#Create a new ticket in Freshdesk. Requires either requester_id, email, facebook_id, phone, twitter_id, or unique_external_id to identify the requester.14 params▾

Create a new ticket in Freshdesk. Requires either requester_id, email, facebook_id, phone, twitter_id, or unique_external_id to identify the requester.

NameTypeRequiredDescription

cc_emailsarrayoptionalArray of email addresses to be added in CC

custom_fieldsobjectoptionalKey-value pairs containing custom field names and values

descriptionstringoptionalHTML content of the ticket describing the issue

emailstringoptionalEmail address of the requester. If no contact exists, will be added as new contact.

group_idnumberoptionalID of the group to which the ticket has been assigned

namestringoptionalName of the requester

prioritynumberoptionalPriority of the ticket. 1=Low, 2=Medium, 3=High, 4=Urgent

requester_idnumberoptionalUser ID of the requester. For existing contacts, can be passed instead of email.

responder_idnumberoptionalID of the agent to whom the ticket has been assigned

sourcenumberoptionalChannel through which ticket was created. 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback Widget, 10=Outbound Email

statusnumberoptionalStatus of the ticket. 2=Open, 3=Pending, 4=Resolved, 5=Closed

subjectstringoptionalSubject of the ticket

tagsarrayoptionalArray of tags to be associated with the ticket

typestringoptionalHelps categorize the ticket according to different kinds of issues

freshdesk_ticket_delete#Move a ticket to the trash in Freshdesk. Trashed tickets can be restored within 30 days via the Freshdesk UI before being permanently purged.1 param▾

Move a ticket to the trash in Freshdesk. Trashed tickets can be restored within 30 days via the Freshdesk UI before being permanently purged.

NameTypeRequiredDescription

ticket_idnumberrequiredID of the ticket to delete

freshdesk_ticket_forward#Forward a ticket's conversation to one or more external email addresses, optionally including the full ticket thread.6 params▾

Forward a ticket's conversation to one or more external email addresses, optionally including the full ticket thread.

NameTypeRequiredDescription

bodystringrequiredHTML content of the forward message

ticket_idnumberrequiredID of the ticket to forward

to_emailsarrayrequiredArray of email addresses to forward the ticket to

bcc_emailsarrayoptionalArray of email addresses to BCC on the forward

cc_emailsarrayoptionalArray of email addresses to CC on the forward

quoted_conversationbooleanoptionalIf true, includes the full ticket thread in the forwarded email

freshdesk_ticket_get#Retrieve details of a specific ticket by ID. Includes ticket properties, conversations, and metadata.2 params▾

Retrieve details of a specific ticket by ID. Includes ticket properties, conversations, and metadata.

NameTypeRequiredDescription

ticket_idnumberrequiredID of the ticket to retrieve

includestringoptionalAdditional resources to include (stats, requester, company, conversations)

freshdesk_ticket_note_create#Add a note to a ticket conversation in Freshdesk. Notes are internal by default (visible only to agents); set private to false to create a public note visible to the customer.6 params▾

Add a note to a ticket conversation in Freshdesk. Notes are internal by default (visible only to agents); set private to false to create a public note visible to the customer.

NameTypeRequiredDescription

bodystringrequiredHTML content of the note

ticket_idnumberrequiredID of the ticket to add the note to

incomingbooleanoptionalIf true, marks the note as a third-party contribution added from outside Freshdesk

notify_emailsarrayoptionalArray of email addresses to notify about this note

privatebooleanoptionalIf true, the note is only visible to agents. Defaults to true.

user_idnumberoptionalID of the agent creating the note

freshdesk_ticket_update#Update an existing ticket in Freshdesk. Note: Subject and description of outbound tickets cannot be updated.10 params▾

Update an existing ticket in Freshdesk. Note: Subject and description of outbound tickets cannot be updated.

NameTypeRequiredDescription

ticket_idnumberrequiredID of the ticket to update

custom_fieldsobjectoptionalKey-value pairs containing custom field names and values

descriptionstringoptionalHTML content of the ticket (cannot be updated for outbound tickets)

group_idnumberoptionalID of the group to which the ticket has been assigned

namestringoptionalName of the requester

prioritynumberoptionalPriority of the ticket. 1=Low, 2=Medium, 3=High, 4=Urgent

responder_idnumberoptionalID of the agent to whom the ticket has been assigned

statusnumberoptionalStatus of the ticket. 2=Open, 3=Pending, 4=Resolved, 5=Closed

subjectstringoptionalSubject of the ticket (cannot be updated for outbound tickets)

tagsarrayoptionalArray of tags to be associated with the ticket

freshdesk_tickets_filter#Search tickets using Freshdesk's structured query syntax (field:value expressions combined with AND/OR), for filtering beyond what List Tickets' predefined filters support. Supports fields like agent_id, group_id, priority, status, tag, type, due_by, fr_due_by, created_at, updated_at, closed_at, and custom fields. Returns up to 30 results per page across a maximum of 10 pages.2 params▾

Search tickets using Freshdesk's structured query syntax (field:value expressions combined with AND/OR), for filtering beyond what List Tickets' predefined filters support. Supports fields like agent_id, group_id, priority, status, tag, type, due_by, fr_due_by, created_at, updated_at, closed_at, and custom fields. Returns up to 30 results per page across a maximum of 10 pages.

NameTypeRequiredDescription

querystringrequiredQuery expression to filter tickets, e.g. "priority:3 AND status:2". Must be enclosed in double quotes and be 512 characters or fewer.

pagenumberoptionalPage number for pagination (1-10)

freshdesk_tickets_list#Retrieve a list of tickets with filtering and pagination. Supports filtering by status, priority, requester, and more. Returns 30 tickets per page by default.8 params▾

Retrieve a list of tickets with filtering and pagination. Supports filtering by status, priority, requester, and more. Returns 30 tickets per page by default.

NameTypeRequiredDescription

company_idnumberoptionalFilter by company ID

emailstringoptionalFilter by requester email

filterstringoptionalFilter name (new_and_my_open, watching, spam, deleted)

includestringoptionalAdditional resources to include (description, requester, company, stats)

pagenumberoptionalPage number for pagination (starts from 1)

per_pagenumberoptionalNumber of tickets per page (max 100)

requester_idnumberoptionalFilter by requester ID

updated_sincestringoptionalFilter tickets updated since this timestamp (ISO 8601)

freshdesk_tickets_reply#Add a public reply to a ticket conversation. The reply will be visible to the customer and will update the ticket status if specified.6 params▾

Add a public reply to a ticket conversation. The reply will be visible to the customer and will update the ticket status if specified.

NameTypeRequiredDescription

bodystringrequiredHTML content of the reply

ticket_idnumberrequiredID of the ticket to reply to

bcc_emailsarrayoptionalArray of email addresses to BCC on the reply

cc_emailsarrayoptionalArray of email addresses to CC on the reply

from_emailstringoptionalEmail address to send the reply from

user_idnumberoptionalID of the agent sending the reply

freshdesk_time_entries_list#Retrieve time entries logged across tickets, with filtering by agent, company, and execution date range.6 params▾

Retrieve time entries logged across tickets, with filtering by agent, company, and execution date range.

NameTypeRequiredDescription

agent_idnumberoptionalFilter by the agent who logged the time

billablebooleanoptionalFilter by billable status

company_idnumberoptionalFilter by company

executed_afterstringoptionalFilter entries executed after this timestamp (ISO 8601)

executed_beforestringoptionalFilter entries executed before this timestamp (ISO 8601)

pagenumberoptionalPage number for pagination (starts from 1)

freshdesk_time_entry_create#Log a time entry against a ticket for billing or effort tracking.6 params▾

Log a time entry against a ticket for billing or effort tracking.

NameTypeRequiredDescription

ticket_idnumberrequiredID of the ticket to log time against

time_spentstringrequiredTime spent, formatted as hh:mm

agent_idnumberoptionalID of the agent who performed the work

billablebooleanoptionalWhether this time entry is billable

executed_atstringoptionalWhen the work was performed (ISO 8601). Defaults to now.

notestringoptionalNote describing the work done