Freshdesk

1. Overview

Freshdesk is a cloud-based customer support platform that helps teams manage customer interactions through a unified ticketing system. It streamlines support operations by organizing customer queries, tracking issues, and enabling efficient communication across multiple channels.

Through the GoInsight Freshdesk node, you can seamlessly integrate customer support operations into your automated workflows. This integration enables comprehensive management of your support ecosystem, including:

• Contact Management: Create, retrieve, update, and delete customer contact records.
• Ticket Operations: Create, retrieve, update, and delete support tickets to track customer issues.
• Batch Retrieval: Fetch multiple contacts or tickets with pagination and filtering capabilities.

2. Prerequisites

Before using this node, you need to have the following:

• A valid Freshdesk account with an active subscription.
• API access enabled on your Freshdesk account.
• Appropriate permissions to create and manage API keys (typically requires agent or administrator access).

3. Credentials

For detailed guidance on how to obtain and configure your Freshdesk API credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the following core resources: Contact and Ticket.

Operation Details

Create a Contact

Creates a new contact in Freshdesk. Idempotency: If you provide UniqueExternalId, Freshdesk will reject duplicates. For safer retry handling, use a two-step workflow: search first, then create or update.

Input Parameters:

• Name: The contact's full name (required). This will be displayed in Freshdesk tickets and contact lists. Example: 'John Doe'

Options:

• Email: The contact's primary email address (optional but recommended). Used for ticket notifications and duplicate detection. Format: user@example.com
• Phone: The contact's phone number (optional). Supports international formats. Example: '+1-555-0100' or '1234567890'
• Address: The contact's physical address (optional). Free-text field. Example: '123 Main St, San Francisco, CA 94102'
• TwitterId: The contact's Twitter username (optional). Enter without '@' symbol. Example: 'john_doe' (not '@john_doe')
• UniqueExternalId: A unique identifier from your external system (optional but recommended for integration). Used for deduplication and syncing with CRM/ERP systems. Freshdesk will reject duplicate contacts with the same ID. Example: 'CRM-12345' or 'SAP-USER-789'

Output:

• Contact (object): The Freshdesk contact object returned on success. Contains fields: id (number), name (string), email (string), phone (string), address (string), twitter_id (string), unique_external_id (string), created_at (ISO 8601 datetime), updated_at (ISO 8601 datetime), active (boolean), deleted (boolean), company_id (number), view_all_tickets (boolean), other_emails (array), and other Freshdesk metadata fields.
• OriginalStatusCode (number): The original HTTP status code returned by Freshdesk API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. Common values: 201=Created, 400=Bad Request, 401=Unauthorized, 409=Conflict (duplicate), 422=Validation Error.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout or connection failure, may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business-level error from Freshdesk API (e.g., duplicate contact, invalid email format).

Delete a Contact

WARNING: Permanently deletes a Freshdesk contact specified by its contact ID. This operation cannot be undone and the contact data cannot be recovered. Use with caution.

Input Parameters:

• ContactId: The ID of the contact to be deleted. You can obtain this ID by calling Search Contacts or Get Many Contacts action. Example: "123456789"

Output:

• Deleted (bool): Indicates whether the specified contact was successfully deleted.
• OriginalStatusCode (number): The original HTTP status code returned by Freshdesk API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Error message if deletion failed or exception occurred; empty on success.

Get a Contact

Gets details of a Freshdesk contact specified by its contact ID.

Input Parameters:

• ContactId: The ID of the contact to retrieve. You can obtain this ID from the Search Contacts or List All Contacts actions, or from the Freshdesk admin console.

Output:

• Contact (object): The Freshdesk contact object. Core fields: id (number): Contact unique identifier, name (string): Full name, email (string): Primary email address, phone (string): Phone number, mobile (string): Mobile number, address (string): Physical address, twitter_id (string): Twitter handle, unique_external_id (string): External system ID, created_at (string): Creation timestamp (ISO 8601), updated_at (string): Last update timestamp (ISO 8601), active (boolean): Whether the contact is active, deleted (boolean): Whether the contact is deleted. Full schema: https://developers.freshdesk.com/api/#view_contact
• OriginalStatusCode (number): The original HTTP status code returned by the Freshdesk API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Contacts

Gets a list of Freshdesk contacts with optional pagination parameters.

Options:

• Page: Page number to retrieve (must be > 0). Defaults to 1 if not provided. Use this to paginate through large contact lists.
• PerPage: Number of contacts per page (must be > 0, max 100). Defaults to 30 if not provided. Freshdesk recommends 30-50 for optimal performance.

Output:

• Results (object-array): List of Freshdesk contact objects. Each object contains: id (number): Contact unique identifier, name (string): Full name, email (string): Email address, company_id (number): Associated company ID (0 if no company), phone (string): Primary phone number, created_at (string): Creation timestamp (ISO 8601 format), updated_at (string): Last update timestamp, active (boolean): Whether the contact is active, custom_fields (object): Custom field values.
• Pagination (object): Pagination metadata: current_page (number): Current page number, per_page (number): Number of items per page, total_count (number): Number of contacts returned in current page, has_more (boolean): Whether there might be more pages (true if current page is full).
• OriginalStatusCode (number): The original HTTP status code returned by Freshdesk API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging: 0: Did not reach upstream, 200: Success, 401: Invalid API Key, 404: Resource not found, 429: Rate limited, 5xx: Freshdesk server error.
• StatusCode (number): Operation status code: 200: Success (check ErrorMessage for business errors), -1: Parameter validation error, 500: Network/system error (timeout, connection failure, etc.).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Update a Contact

Updates an existing Freshdesk contact specified by its contact ID with provided details. Update Strategy: Only the fields you provide will be updated; fields not included in the request will remain unchanged (incremental update, similar to PATCH behavior). Note: At least one field (Name, Email, Phone, Address, TwitterId, or UniqueExternalId) must be provided for the update to proceed.

Input Parameters:

• ContactId: The ID of the contact to be updated. Get this ID from Search Contacts or List All Contacts API. Example: "123456"

Options:

• Name: The contact's name. Note: At least one field (Name, Email, Phone, Address, TwitterId, or UniqueExternalId) must be provided to update the contact.
• Email: The contact's email address. Format: user@example.com
• Phone: The contact's phone number. Supports international format: +1-555-0100
• Address: The contact's physical address.
• TwitterId: The contact's Twitter handle (username without @). Example: "elonmusk" (not "@elonmusk" or numeric ID).
• UniqueExternalId: A unique external identifier for the contact (e.g., CRM ID from another system).

Output:

• Updated (bool): Indicates whether the contact was successfully updated.
• Contact (object): The updated Freshdesk contact object. Core fields: id (number): Contact unique identifier, name (string): Contact name, email (string): Email address, phone (string): Phone number, address (string): Physical address, twitter_id (string): Twitter handle, unique_external_id (string): External system ID, job_title (string): Job title/position, company_id (number): Associated company ID, description (string): Contact description, tags (array): Associated tags, created_at (string): Creation timestamp (ISO 8601), updated_at (string): Last update timestamp (ISO 8601). Full schema: https://developers.freshdesk.com/api/#view_contact
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=Network/system error (may retry). Use OriginalStatusCode for upstream API's actual HTTP status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Create a Ticket

Creates a ticket in Freshdesk with the specified details. Note: This operation may trigger Freshdesk automation rules (e.g., auto-assignment, email notifications, webhooks). To disable notifications, configure your Freshdesk automation settings.

Input Parameters:

• Subject: Subject of the ticket.
• Description: Detailed description for the ticket.
• Email: The email will be used to identify the requester in Freshdesk. If the email already exists, the ticket will be associated with the existing contact.

Options:

• Priority: Ticket priority level. Determines the urgency of handling. Priority Levels: 1 (Low): General inquiries, feature requests, non-urgent issues. 2 (Medium): Standard support requests, minor bugs. [Default if not specified]. 3 (High): Significant issues affecting multiple users, urgent bugs. 4 (Urgent): Critical issues causing service downtime or data loss. Example: 3
• Status: Initial status of the ticket. Controls the workflow state. Status Values: 2 (Open): New ticket awaiting assignment. [Recommended for most cases]. 3 (Pending): Waiting for customer response or external dependency. 4 (Resolved): Issue fixed, awaiting customer confirmation. 5 (Closed): Ticket completed and archived. Note: For new tickets, use Status=2 (Open). Other statuses are typically set during ticket lifecycle management. Example: 2

Output:

• TicketId (number): ID of the newly created ticket. Use this ID to update, retrieve, or delete the ticket in subsequent operations. Example: 12345
• OriginalStatusCode (number): The original HTTP status code returned by the Freshdesk API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Delete a Ticket

WARNING: Permanently deletes a ticket from Freshdesk. This operation is IRREVERSIBLE and cannot be undone. The ticket and all its associated data (comments, attachments, time entries) will be permanently removed.

Input Parameters:

• TicketId: The unique ID of the ticket to delete. Can be obtained via Search Tickets or Get Many Tickets action. Example: "6" (numeric ID, not the display number like #123).

Output:

• Deleted (bool): Indicates whether the ticket was successfully deleted. true = Ticket deleted successfully (OriginalStatusCode 204). false = Deletion failed (check ErrorMessage for reason, e.g., ticket not found, permission denied).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. 204: Ticket deleted successfully, 404: Ticket not found, 401/403: Authentication/permission error.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage and OriginalStatusCode for business errors), -1=Parameter validation error, 500=System error (may retry). Use OriginalStatusCode to get the actual HTTP status from Freshdesk API.
• ErrorMessage (string): Detailed error message if the deletion failed. Empty string on success. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business-level error from the upstream API.

Get a Ticket

Retrieves the details of a Freshdesk ticket specified by its ticket ID.

Input Parameters:

• TicketId: The unique identifier of the Freshdesk ticket to retrieve. You can obtain ticket IDs by calling Search Tickets or List Tickets actions. Example: "6" or "158003421681".

Output:

• Ticket (object): The Freshdesk ticket object. Core fields: id (number): Ticket unique identifier, subject (string): Ticket subject/title, description (string): Full HTML description, description_text (string): Plain text description, status (number): Ticket status (2=Open, 3=Pending, 4=Resolved, 5=Closed), priority (number): Priority level (1=Low, 2=Medium, 3=High, 4=Urgent), source (number): Ticket source (1=Email, 2=Portal, 3=Phone, 7=Chat), requester_id (number): ID of the ticket requester, created_at (string): Creation timestamp (ISO 8601), updated_at (string): Last update timestamp, due_by (string): Due date for ticket resolution, tags (array): List of tags, custom_fields (object): Custom field values. For complete field list, refer to Freshdesk API documentation.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging and troubleshooting. 200: Upstream API returned success, 4xx: Client error (400 Bad Request, 401 Unauthorized, 404 Not Found), 5xx: Server error from upstream.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry). Use OriginalStatusCode for upstream API's actual HTTP status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business-level error from the upstream API (e.g., ticket not found, permission denied).

Get Many Tickets

Retrieves a list of Freshdesk tickets with optional filters for status, priority, pagination, and updated_since.

Options:

• Status: Filter tickets by status. Common use cases: 2 (Open): Newly created tickets awaiting assignment, 3 (Pending): Tickets waiting for customer response, 4 (Resolved): Tickets marked as solved by agents, 5 (Closed): Tickets confirmed resolved by customers. Leave empty to retrieve tickets of all statuses.
• Priority: Filter tickets by priority. Common use cases: 1 (Low): General inquiries, feature requests, non-urgent issues, 2 (Medium): Standard support requests, minor bugs, 3 (High): Significant issues affecting multiple users, urgent bugs, 4 (Urgent): Critical issues causing service downtime or data loss. Leave empty to retrieve tickets of all priorities.
• Page: Page number to retrieve, starting from 1.
• PerPage: Number of tickets per page, maximum 100.
• UpdatedSince: RFC 3339 timestamp to filter tickets updated after this time. Only tickets modified after this timestamp will be returned. Supported formats: UTC: 2025-01-01T00:00:00Z, With timezone: 2025-01-01T08:00:00+08:00. Example: "2025-01-15T10:30:00Z"

Output:

• Tickets (object-array): A list of Freshdesk ticket objects. Each ticket contains: id (number): Unique ticket identifier, subject (string): Ticket subject/title, status (number): Ticket status (2=Open, 3=Pending, 4=Resolved, 5=Closed), priority (number): Priority level (1=Low, 2=Medium, 3=High, 4=Urgent), requester_id (number): ID of the requester, created_at (string): Creation timestamp (ISO 8601), updated_at (string): Last update timestamp (ISO 8601), due_by (string): Due date timestamp (ISO 8601), description (string): Ticket description (HTML), tags (array): List of tags. For complete field list, see Freshdesk API documentation: https://developers.freshdesk.com/api/#view_a_ticket
• Pagination (object): Pagination metadata: current_page (number): Current page number, per_page (number): Items per page, returned_count (number): Number of tickets in current response, has_next_page (boolean): Whether there are more pages, total_pages (number): Total number of pages (null if unknown).
• OriginalStatusCode (number): The original HTTP status code returned by the Freshdesk API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Update a Ticket

This action performs an incremental update (PATCH-like behavior via PUT). Only the fields you provide will be updated; fields not included in the request will remain unchanged.Example: If you only update the Status field, the Subject, Description, Priority, and other fields will keep their original values.

Input Parameters:

• TicketId: The ID of the ticket to update. You can obtain this ID from: Search Tickets action (filter by requester email, status, etc.), Get Many Tickets action (list all tickets), Create a Ticket action (returns the newly created ticket ID). Example: "12345"

Options:

• Subject: New subject for the ticket. Leave empty to keep current subject.
• Description: New description for the ticket (supports HTML format). Leave empty to keep current description.
• Status: New ticket status. Leave empty to keep current status. Status values: 2 = Open: Ticket is being worked on, 3 = Pending: Waiting for customer response, 4 = Resolved: Issue has been resolved, 5 = Closed: Ticket is closed.
• Priority: New ticket priority. Leave empty to keep current priority. Priority values: 1 = Low: No immediate attention needed, 2 = Medium: Standard priority, 3 = High: Needs prompt attention, 4 = Urgent: Requires immediate action.
• AdditionalFields: Additional fields to update (key-value pairs). Use this for fields not exposed as explicit parameters. Common additional fields: tags (array): Array of tag strings, e.g. ["billing", "urgent"], type (string): Ticket type, e.g. "Question", "Incident", "Problem", "Feature Request", group_id (number): ID of the agent group to assign the ticket to, responder_id (number): ID of the agent to assign the ticket to, custom_fields (object): Custom field key-value pairs, e.g. {"cf_customer_tier": "Enterprise"}. For a complete list of fields, refer to the Freshdesk API documentation. Example: {"tags": ["billing"], "type": "Incident", "group_id": 22222}

Output:

• Ticket (object): The updated Freshdesk ticket object, containing the following core fields: id (number): Unique ticket identifier, subject (string): Ticket subject, description (string): Ticket description (HTML format), status (number): Ticket status (2=Open, 3=Pending, 4=Resolved, 5=Closed), priority (number): Ticket priority (1=Low, 2=Medium, 3=High, 4=Urgent), requester_id (number): ID of the ticket requester, responder_id (number): ID of the assigned agent, created_at (string): Creation timestamp (ISO 8601), updated_at (string): Last update timestamp (ISO 8601), due_by (string): Due date timestamp (ISO 8601), tags (array): Array of tag strings, type (string): Ticket type (e.g., "Question", "Incident", "Problem"), group_id (number): ID of the assigned agent group, custom_fields (object): Custom field key-value pairs.
• OriginalStatusCode (number): The original HTTP status code returned by Freshdesk API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging: 0: Did not reach upstream, 200: Success, 400: Bad request (invalid field values), 401: Invalid API Key, 404: Ticket not found, 429: Rate limited, 5xx: Freshdesk server error.
• StatusCode (number): Operation status code: 200: Success (check ErrorMessage for business errors), -1: Parameter validation error, 500: Network/system error (timeout, connection failure, etc.).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a simple workflow that creates a new support ticket in Freshdesk. This is one of the most common use cases when integrating support operations into your automation.

Scenario: You want to automatically create a support ticket when a customer submits a request through your system.

Workflow Overview: The workflow consists of three nodes: Start → Freshdesk → Answer. The Start node initiates the workflow, the Freshdesk node creates the ticket, and the Answer node returns the result.

Step-by-Step Guide:

1. Add the Freshdesk Node:
   • In the workflow canvas, click the "+" button to add a new node.
   • In the popup panel, select the "Tools" tab.
   • Find and select Freshdesk from the tools list.
   • In the list of supported operations for Freshdesk, click to select Create a Ticket. This will add the corresponding node to your canvas.
2. Configure the Node:
   • Click on the newly added Create a Ticket node. The configuration panel will expand on the right side.
   • Credentials Configuration: At the top of the panel, locate the credentials field. Click the dropdown menu and select your pre-configured Freshdesk credentials (API Key and Domain).
   • Parameter Configuration: Fill in the required input parameters:
   • Subject: Enter a subject for the ticket, such as "Customer inquiry about product features".
   • Description: Provide a detailed description of the issue, for example "Customer is asking about advanced features in the Pro plan".
   • Email: Enter the requester's email address, such as "customer@example.com".
   • Priority: Set the priority level. For this example, select 2 (Medium priority).
   • Status: Set the initial status. Select 2 (Open status).
3. Run and Verify:
   • Once all required parameters are correctly filled in, any error indicators in the top-right corner of the canvas will disappear.
   • Click the "Test Run" button in the top-right corner to execute the workflow.
   • After successful execution, click the log icon in the top-right corner to view the detailed input and output of the node, and verify that the ticket was successfully created. You should see a TicketId in the output, along with a StatusCode of 201.

Final Workflow Summary: After completing the above steps, your workflow is fully configured. When you click "Test Run", a new support ticket will be successfully created in your Freshdesk account, and you can verify it by logging into your Freshdesk dashboard.

6. FAQs

Q: What should I do if I receive a 401 Unauthorized error?

A: This error typically indicates an authentication issue. Please check the following:

• Verify that your API Key is correct and hasn't expired.
• Ensure your Domain is correctly formatted (e.g., "yourcompany" without the ".freshdesk.com" suffix).
• Confirm that your API access is enabled in your Freshdesk account settings.

Q: How do I find my Freshdesk subdomain?

A: Your Freshdesk subdomain is the first part of your Freshdesk URL. For example, if your Freshdesk URL is https://yourcompany.freshdesk.com, then your subdomain is yourcompany. When configuring the node, only provide the subdomain part without "https://" and ".freshdesk.com".

Q: What do the different ticket status codes mean?

A: Freshdesk uses numeric codes for ticket statuses:

• 2 = Open
• 3 = Pending
• 4 = Resolved
• 5 = Closed

Q: What do the different ticket priority codes mean?

A: Freshdesk uses numeric codes for ticket priorities:

• 1 = Low
• 2 = Medium
• 3 = High
• 4 = Urgent

Q: Can I permanently recover a deleted contact or ticket?

A: No. The delete operations for both contacts and tickets are permanent and cannot be undone. Please exercise caution when using these operations. Consider implementing a confirmation step in your workflow before executing delete operations.

Q: What is the maximum number of results I can retrieve in a single request?

A: For the "Get many Tickets" operation, the maximum is 100 tickets per page. For contacts, while there's no strict limit mentioned, it's recommended to use reasonable page sizes (e.g., 30-100) for optimal performance. Use pagination to retrieve larger datasets.

7. Official Documentation

For more detailed information about Freshdesk's API capabilities, please refer to the official documentation:

Freshdesk Official API Documentation