Freshservice

LAST UPDATED: MAY 30, 2025

Overview

Freshservice provides an intelligent, right-sized service management solution for modern businesses of all sizes. Freshservice does this by taking a fresh approach to building and delivering modern employee experiences and unified service management —empowering businesses to achieve efficiency, fast time-to-value, and improved employee satisfaction and productivity.

D3 SOAR is providing REST operations to function with Freshservice.

Freshservice is available for use in:

D3 SOAR	V14.0.576+
Category	ITSM
Deployment Options	Option II, Option IV

Known Limitations

Certain rate limits are imposed when using Freshservice's API. Refer to The Freshservice API for more information.

Connection

To connect to Freshservice from D3 SOAR, follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The server URL of the Freshservice API.	https://domain.freshservice.com
API Key	The API key for authentication.	*****
API Version	The version of the API to use for the connection.	v2

Permission Requirements

Each endpoint in the Freshservice API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required Permission
Close Tickets	Agent Role > Tickets > View Tickets + Edit ticket properties Account Admin role
Create Ticket	Agent Role > Tickets > View Tickets
Create Ticket Notes	Agent Role > Tickets > View Tickets
Delete Ticket Attachments	Agent Role > Tickets > View Tickets + Edit ticket properties
Delete Tickets	Agent Role > Tickets > View Tickets + Delete a ticket
Fetch Event	Agent Role > Tickets > View Tickets
Filter Departments	Admin Role > Perform Operational Admin actions > View Department
Get Departments	Admin Role > Perform Operational Admin actions > View Department
Get Groups	Admin Role > Play God with Super Admin controls (refer to the first bullet point in the Reader Note)
Get Tickets	Agent Role > Tickets > View Tickets
List Groups	Admin Role > Play God with Super Admin controls (refer to the first bullet point Reader Note)
List Tickets	Agent Role > Tickets > View Tickets
List Workspaces	Admin Role > Perform Operational Admin actions > Manage Workspace Details and Status (refer to the second bullet point in the Reader Note)
Resolve Tickets	Agent Role > Tickets > View Tickets + Edit ticket properties Account Admin role
Restore Tickets	Agent Role > Tickets > View Tickets + Delete a ticket
Search Tickets	Agent Role > Tickets > View Tickets
Update Tickets	Agent Role > Tickets > View Tickets + Edit ticket properties Account Admin role
Test Connection	Agent Role > Tickets > View Tickets

As Freshservice is using role-based access control (RBAC), the API Key is generated based on a specific agent account. Therefore, the command permissions are inherited from the agent account’s role. Users need to configure their agent profile from the Freshservice console for each command in this integration.

READER NOTE

The Freshservice API documentation lists Play God with Super Admin controls as required, but D3 testing confirms that Admin Role > Perform Operational Admin actions > View Agents and Agent groups is sufficient. This may change with future API updates.
The Manage Workspace Details and Status permission appears only after creating an additional workspace beyond the default IT Workspace on the Freshservice UI.
Refer to Understanding Roles for Agents: Freshservice for more information.

Configuring Freshservice to Work with D3 SOAR

Configuring Freshservice for use with D3 SOAR requires completing the following three steps:

Creating a Role

Log into Freshservice.
Navigate to Admin > Roles.
Click the New Role button, then select either the Agent role or Admin role option, depending on the requirements of the command for which permissions are being configured.
Configure the permissions for the new role.
1. Enter a name for the role.
2. Select the desired permission scopes.
3. Click the Save button to apply the configuration.
For the list of required permissions for each command, refer to the Permission Requirements sections.

Creating an Agent and Assigning Roles

Navigate to Admin > Agents.
Click the New Agent button.
Configure the new agent.
1. Enter the email address.
2. Enter the first name.
3. Enter the last name.
4. Click Create to add the agent.
Click the newly created agent.
Select the Permissions tab, then click the Edit icon.
Click the Add Role button.
Assign a role to the agent.
1. Select the desired role.
2. Choose the Across all groups in the service desk scope.
3. Click the Save button to assign.

READER NOTE

To use the Close Tickets, Resolve Tickets, and Update Tickets commands, users must ensure their assigned agent role includes the necessary permissions (i.e., View tickets and Edit ticket properties) and that they are also assigned the Account Admin role with the across all groups in the service desk scope.

Obtaining the API Key

Click the profile icon, then click the Profile settings link.
Complete the CAPTCHA verification, if prompted.
Copy the API key. Refer to Step 3i: Sub-step 2 in Configuring D3 SOAR to Work with Freshservice.

Configuring D3 SOAR to Work with Freshservice

Log in to D3 SOAR.
Find the Freshservice integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Freshservice in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Freshservice.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users have the option to choose the specific tenant sites to share the connection with. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the checkbox to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Server URL. This URL is unique to each organization’s Freshservice instance; the default value provided is a placeholder and will not function unless replaced.
  2. Input the API Key from the Freshservice platform. Refer to Step 3 in Obtaining the API Key for more information.
  3. Input the API Version. The default value is v2.
10. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
11. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
Test the connection.
1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Freshservice includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Freshservice API, refer to the Freshservice API reference.

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Freshservice to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose the desired date and time format, then click on the Save button.

The selected time format will now be visible when configuring Date/Time command input parameters.

Close Tickets

Changes the status of the specified tickets to "Closed".

READER NOTE

Ticket IDs is a required parameter to run this command.

Run the List Tickets or Search Tickets command to obtain the Ticket IDs. Ticket IDs can be found in the returned raw data of both commands at the path $.tickets[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to close. Ticked IDs can be obtained using the List Tickets or Search Tickets commands.	JSON `[ ***** ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Close Tickets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Ticket ID: *****. Reason:Not Found.

Error Sample Data

Close Tickets failed.

Status Code: 404.

Message: Ticket ID: *****. Reason:Not Found.

Create Ticket

Creates a new ticket in the service desk. To add custom fields, non-standard values, or additional fields beyond the provided parameters, use the Additional Fields parameter.

File IDs and File Source

It is not recommended to use the Test Command feature with the Create Ticket command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

READER NOTE

To use the Additional Fields parameter, follow the steps below:

Define Custom Fields in the Freshservice
1. Navigate to Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form.
2. Use the available options to name and define the custom fields. Ensure to save the changes.
Check the Custom Field's System Name
In D3 SOAR, run the List Tickets command and view the raw data for any ticket. The newly created custom field (for example, "Test123") will appear, but its value will be null for existing tickets that do not have the field assigned.
This is a method to identify the system name of the custom field, as the system name might differ from the display name. For example, a display name of "Test123" might have a system name of "test123". Always verify the system name prior to its usage.
Integrate Custom Field into the Additional Fields Parameter
- Use the following format to define custom fields in the Additional Fields parameter.
  JSON
```
{
     "custom_fields": {
          "your_custom_field_system_name": "value"
     }
}
```
- There are additional predefined fields that can be used. For fields that exist in D3 system parameters, inputting these in Additional Fields will override the D3 parameter value. For fields not present in D3 system parameters (e.g. "group_id"), the system name might differ from the display name (e.g. "Group").
  To confirm available fields, inspect the raw data of the List Tickets command. These fields should not fall under 'custom fields'. Refer to this example:
  JSON
```
{
    "cc_emails": [
        "support@example.com"
    ],
}
```

Always validate field system names against the raw data to prevent inconsistencies.

Input

Input Parameter	Required/Optional	Description	Example
Requester Email	Required	The email address of the requester. If there is no existing contact with this email in Freshservice, a new contact will be created.	service@example.com
Ticket Subject	Required	The subject of the ticket.	Suspicious phishing email
Description	Required	The HTML content of the ticket.	Details about the incident.2023***a
Priority	Optional	The priority level of the ticket. Available options are: Urgent High Medium Low By default, this value is set to Low. Urgency and Impact levels can override this priority. Without set Urgency and Impact levels, the ticket will always default to Low regardless of the chosen priority.	Urgent
Status	Optional	The status of the ticket. Available options are: Open Pending Resolved Closed By default, the status is set to Open.	Open
Source	Optional	The source of the ticket. Available options are: Email Portal Phone Chat Feedback Widget Yammer AWS Cloudwatch Pagerduty Walkup Slack Workplace Employee Onboarding MS Teams Employee Offboarding By default, the value is set to Phone.	Email
Urgency	Optional	The urgency level of the ticket. Available options are: High Medium Low By default, the value is set to Low.	High
Impact	Optional	The impact level of the ticket. High Medium Low By default, the value is set to Low.	High
Additional Fields	Optional	The key-value pairs for custom or other desired fields during ticket creation. Ensure custom fields are first set up under Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form. If field entries overlap with other parameters, the other parameters will be omitted. Refer to Customize Ticket Fields from Freshservice's documentation for more information.	JSON `{ "cc_emails": [ "support@example.com" ], "custom_fields": { "custom_note": "testNote123" } }`
File IDs	Optional	The IDs of the files stored in D3 SOAR's database to upload as ticket attachments. The total attachment size cannot exceed 40 MB.	JSON `[ "*****" ]`
File Source	Optional	The file source of the files to upload as ticket attachments. The options for file sources are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event	Playbook File

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Ticket failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unexpected/invalid field in request.

Error Sample Data

Create Ticket failed.

Status Code: 400.

Message: Unexpected/invalid field in request.

Create Ticket Notes

Creates a conversation note for the specified tickets.

File IDs and File Source

It is not recommended to use the Test Command feature with the Create Ticket Notes command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

READER NOTE

Ticket IDs is a required parameter to run this command.

Run the List Tickets or Search Tickets command to obtain the Ticket IDs. Ticket IDs can be found in the returned raw data of both commands at the path $.tickets[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets for which to create a note. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	JSON `[ ***** ]`
Note Content	Required	The HTML content of the note.	Say Hi
Private	Optional	Whether the note will be private. By default, the value is set to True.	False
Notify Emails	Optional	The email addresses of agents or users to notify about the note.	JSON `[ "support@example.com" ]`
File IDs	Optional	The IDs of the files stored in D3 SOAR's database to upload as note attachments.	JSON `[ "*****" ]`
File Source	Optional	The file source of the files to upload as ticket attachments. The options for file sources are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event	Playbook File

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Ticket Notes failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Ticket ID: 666. Reason:Not Found.

Error Sample Data

Create Ticket Notes failed.

Status Code: 404.

Message: Ticket ID: 666. Reason:Not Found.

Delete Ticket Attachments

Deletes the specified attachments from a ticket. A ticket's total attachment size must not exceed 40 MB. Use this command to manage a ticket's attachment size.

READER NOTE

Ticket ID and Attachment IDs are required parameters to run this command.

Run the List Tickets or Search Tickets command to obtain the Ticket IDs. Ticket IDs can be found in the returned raw data of both commands at the path $.tickets[*].id.
Run the Get Tickets command to obtain the Attachment IDs. Attachment IDs can be found in the returned raw data at the path $.results[*].attachments[*].id.
Not all tickets contain attachments. Ensure the Ticket ID is correctly paired with its corresponding Attachment IDs. It is recommended to first run the List Tickets or Search Tickets command to obtain the Ticket ID. Then, use this ID with the Get Tickets command to retrieve attachment details. Finally, use both the Ticket ID and Attachment IDs to execute this command.

Input

Input Parameter	Required/Optional	Description	Example
Ticket ID	Required	The ID of the ticket from which to remove attachments. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	*****
Attachment IDs	Required	The IDs of the attachment files to remove. Attachment IDs can be obtained using the Get Tickets command.	JSON `["*****"]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Ticket Attachments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Ticket ID: 7. AttachmentID: *****. Reason:Not Found.

Error Sample Data

Delete Ticket Attachments failed.

Status Code: 404.

Message: Ticket ID: 7. AttachmentID: *****. Reason:Not Found.

Delete Tickets

Deletes the specified tickets. Deleted tickets are not permanently removed. Use the Restore Tickets command to recover them.

READER NOTE

Ticket IDs is a required parameter to run this command.

Run the List Tickets or Search Tickets command to obtain the Ticket IDs. Ticket IDs can be found in the returned raw data of both commands at the path $.tickets[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to delete. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	JSON `[ ***** ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Tickets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Ticket ID: *****. Reason:Not Found.

Error Sample Data

Delete Tickets failed.

Status Code: 404.

Message: Ticket ID: *****. Reason:Not Found.

Fetch Event

Returns tickets as events from all accessible workspaces on the Freshservice platform based on specified criteria.

READER NOTE

Workspace ID is an optional parameter to run this command.

Run the List Workspaces command to obtain the Workspace ID. Workspace IDs can be found in the returned raw data at the path $.workspaces[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the range for fetching tickets by their updated time (in UTC). By default, only tickets created within the past 30 days will be returned.	2024-10-01 00:00
Number of Event(s) Fetched	Optional	The maximum number of the most recent tickets to fetch. The value must be an integer between 1 and 100. By default, all tickets matching the criteria will be returned.	10
Workspace ID	Optional	This parameter is applicable only to accounts with the Workspaces feature enabled and on Employee Support Mode. The ID of the workspace for which to retrieve tickets. Workspace ID can be obtained using the List Workspaces command. Use 0 to retrieve tickets across all workspaces (limited to global fields), but this value is not supported for the Major Incident ticket type. By default, tickets from the primary workspace will be returned.	*****
Ticket State	Optional	The state used to filter retrieved tickets. Available options are: New and My Open Watching Spam Deleted By default, tickets that are not deleted or flagged as spam will be returned. To include deleted tickets, select the Deleted option.	New and My Open
Ticket Type	Optional	The ticket type used to filter retrieved tickets. Available options are: Incident Service Request Case Query Issue Request Major Incident Alert By default, all tickets regardless of their type will be returned.	Incident
Requester Email	Optional	The email address of the requester used to filter retrieved tickets.	john@freshservice.com

Output

To view the sample output data for all commands, refer to this article.

Fetch Event Field Mapping

Fetch Event commands require event field mapping. Field mapping plays a key role for data normalization within the event pipeline. Field mapping converts the original data fields from the different providers to standardized D3 fields as defined by the D3 Model. Refer to Event and Incident Intake Field Mapping for details.

To add a custom field, click on the + Add Field button. Users can also remove built-in field mappings by clicking x. Note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

As a system integration, the Freshservice integration has some pre-configured field mappings for default field mapping.

Default Event Source
The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, users will find a set of field mappings provided by the system. Default event source provides field mappings for common fields from the fetched data. The default event source has a "Main Event JSON Path" (i.e. $.tickets) that is used to extract a batch of events from the response raw data. View the "Main Event JSON Path" by clicking on the Edit Event Source button.
- Main Event JSON Path: $.tickets
  The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.
  For example, the root node of a JSON Path is tickets. The child node denoting the Event name field would be subject. Putting it together, the JSON Path expression to extract the Unique Event Key is $.tickets.subject.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Document ID	.id
Start Time	.created_at
Description	.description
Event name	.subject
Event Type	.type
Priority	.priority
Event category	.category
Sub Category	.sub_category
Item Category	.item_category
Status	.status
Source	.source
Urgency	.urgency
Workspace ID	.workspace_id
Updated Time	.updated_at
Due Time	.due_by
Group ID	.group_id
Department ID	.department_id
Requester ID	.requester_id
Assignee ID	.responder_id
Is Escalated	.is_escalated
Username	.requested_for.name
User Email	.requested_for.email
Tag	.tags

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You are not authorized to perform this action.

Error Sample Data

Fetch Event failed.

Status Code: 403.

Message: You are not authorized to perform this action.

Filter Departments

Retrieves departments based on query criteria. By default, results are sorted by created_at in descending order.

Input

Input Parameter	Required/Optional	Description	Example
Department Name	Optional	The department name used to filter results. By default, all departments will be returned.	Sale

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Filter Departments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You are not authorized to perform this action.

Error Sample Data

Filter Departments failed.

Status Code: 403.

Message: You are not authorized to perform this action.

Get Departments

Retrieves departments or companies (in MSP mode) by ID.

READER NOTE

Department IDs is a required parameter to run this command.

Run the Filter Departments command to obtain the Department IDs. Department IDs can be found in the returned raw data at the path $.departments[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Department IDs	Required	The IDs of the departments to retrieve. Department IDs can be obtained using the Filter Departments command.	JSON `[ ***** ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Departments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Request failed for Department ID: 123456, Status code: 404, Reason: Not Found

Error Sample Data

Get Departments failed.

Status Code: 404.

Message: Request failed for Department ID: 123456, Status code: 404, Reason: Not Found

Get Tickets

Retrieves details of the specified tickets.

READER NOTE

Ticket IDs is a required parameter to run this command.

Run the List Tickets or Search Tickets command to obtain the Ticket IDs. Ticket IDs can be found in the returned raw data of both commands at the path $.tickets[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets for which to retrieve details. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	JSON `[ ***** ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Tickets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Resolve Ticket failed. Ticket ID: *****. Reason:Not Found.

Error Sample Data

Get Tickets failed.

Status Code: 404.

Message: Resolve Ticket failed. Ticket ID: *****. Reason:Not Found.

List Groups

Retrieves all agent groups.

READER NOTE

Workspace ID is an optional parameter to run this command.

Run the List Workspaces command to obtain the Workspace ID. Workspace IDs can be found in the returned raw data at the path $.workspaces[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Workspace ID	Optional	Filters agent groups present in the specified workspace. By default, agent groups from the primary workspace are returned. Workspace ID can be obtained using the List Workspaces command.	*****

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Groups failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You are not authorized to perform this action.

Error Sample Data

List Groups failed.

Status Code: 403.

Message: You are not authorized to perform this action.

List Tickets

Retrieves tickets based on the specified search criteria. Only tickets that have not been deleted or marked as spam will be retrieved, unless the Deleted option is selected for the Predefined Filter.

READER NOTE

Workspace ID is an optional parameter to run this command.

Run the List Workspaces command to obtain the Workspace ID. Workspace IDs can be found in the returned raw data at the path $.workspaces[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Workspace ID	Optional	This parameter applies only to accounts with the Workspaces feature enabled. The ID of the workspace from which to retrieve tickets. Workspace ID can be obtained using the List Workspaces command. A value of 0 retrieves tickets from all workspaces (limited to only global-level fields). By default, only tickets from the primary workspace are retrieved.	*****
Predefined Filter	Optional	The state used to filter tickets. Available options are: New and My Open Watching Spam Deleted By default, only tickets that have not been deleted or flagged as spam will be returned. To retrieve deleted tickets, use the Deleted filter.	New and My Open
Ticket Type	Optional	The ticket type used to filter results. Available options are: Incident Service Request Case Query Issue Request Major Incident Alert By default, all tickets regardless of their type will be returned.	Incident
Requester Email	Optional	The email address of the requester used to filter tickets.	test@freshservice.com
Updated Since	Optional	The datetime used to filter tickets. Tickets updated after the specified datetime will be retrieved. By default, only tickets created within the past 30 days are included. Use this parameter to retrieve older tickets.	2023-01-01 00:00

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Tickets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: invalid literal for int() with base 10.

Error Sample Data

List Tickets failed.

Status Code: 401.

Message: invalid literal for int() with base 10.

List Workspaces

Lists all workspaces created in the account.

Input

Input Parameter	Required/Optional	Description	Example
Workspace Name	Optional	The name of the workspace used to filter results. By default, all workspaces are returned.	IT

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Workspaces failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You are not authorized to perform this action.

Error Sample Data

List Workspaces failed.

Status Code: 403.

Message: You are not authorized to perform this action.

Resolve Tickets

Changes the status of the specified tickets to Resolved.

READER NOTE

Ticket IDs is a required parameter to run this command.

Run the List Tickets or Search Tickets command to obtain the Ticket IDs. Ticket IDs can be found in the returned raw data of both commands at the path $.tickets[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to resolve. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	JSON `[ ***** ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Resolve Tickets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Ticket ID: 666. Reason:Not Found.

Error Sample Data

Resolve Tickets failed.

Status Code: 404.

Message: Ticket ID: 666. Reason:Not Found.

Restore Tickets

Restores the specified deleted tickets.

READER NOTE

Ticket IDs is a required parameter to run this command.

Only deleted tickets can be restored.
Run the List Tickets command with the Predefined Filter input parameter set to deleted to obtain the Ticket IDs. Ticket IDs can be found in the returned raw data at the path $.tickets[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the deleted tickets to restore. The IDs of deleted tickets can be obtained using the List Tickets command and setting the Predefined Filter parameter to Deleted.	JSON `[ ***** ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Restore Tickets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Ticket ID: *****. Reason:Not Found.

Error Sample Data

Restore Tickets failed.

Status Code: 404.

Message: Ticket ID: *****. Reason:Not Found.

Search Tickets

Searches for tickets based on the defined query conditions. Custom ticket fields configured on Freshservice can be used to filter and return tickets matching the specified criteria. At least one parameter must be defined.

READER NOTE

The Assignee ID can be located in the Freshservice URL. Navigate to Admin > User Management > Agents, then select the desired user. The ID appears in the URL. For example, in the URL d3securityhelpdesk.freshservice.com/agents/23***7, the Assignee ID is 23***7.

Input

Input Parameter	Required/Optional	Description	Example
Priority	Optional	The priority level used to filter tickets. Available options are: Urgent High and Urgent Medium, High and Urgent All By default, all tickets regardless of priority level will be returned.	High and Urgent
Status	Optional	The status used to filter tickets. Available options are: Open Pending Resolved Closed By default, all tickets regardless of status will be returned.	Open
Requester Email	Optional	The email address used to filter tickets. By default, all tickets regardless of requester email will be returned.	test@freshservice.com
Created After	Optional	The datetime used to return tickets created after the specified value.	2023-08-29 00:00
Assignee ID	Optional	The ID of the ticket assignee used to filter tickets.	*****
Additional Query	Optional	Additional query conditions used to filter tickets. Refer to The Freshservice API for sample query conditions.	updated_at:<'2023-08-29' AND priority:<3

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Tickets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: blank query.

Error Sample Data

Search Tickets failed.

Status Code: 400.

Message: blank query.

Update Tickets

Updates the parameters of the specified tickets. To update custom fields, input non-preset values, or include additional fields beyond the provided parameters, use the Additional Fields parameter.

File IDs and File Source

It is not recommended to use the Test Command feature with the Update Tickets command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

READER NOTE

Ticket IDs is a required parameter to run this command.

Run the List Tickets command with the Predefined Filter input parameter set to deleted to obtain the Ticket IDs. Ticket IDs can be found in the returned raw data at the path $.tickets[*].id.

To use the Additional Fields parameter, follow the steps below:

Define Custom Fields in the Freshservice
1. Navigate to Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form.
2. Use the available options to name and define the custom fields. Ensure to save the changes.
Check the Custom Field's System Name
In D3 SOAR, run the List Tickets command and view the raw data for any ticket. The newly created custom field (for example, "Test123") will appear, but its value will be null for existing tickets that do not have the field assigned.
This is a method to identify the system name of the custom field, as the system name might differ from the display name. For example, a display name of "Test123" might have a system name of "test123". Always verify the system name prior to its usage.
Integrate Custom Field into the Additional Fields Parameter
- Use the following format to define custom fields in the Additional Fields parameter.
  JSON
```
{
     "custom_fields": {
          "your_custom_field_system_name": "value"
     }
}
```
- There are additional predefined fields that can be used. For fields that exist in D3 system parameters, inputting these in Additional Fields will override the D3 parameter value. For fields not present in D3 system parameters (e.g. "group_id"), the system name might differ from the display name (e.g. "Group").
  To confirm available fields, inspect the raw data of the List Tickets command. These fields should not fall under 'custom fields'. Refer to this example:
  JSON
```
{
    "cc_emails": [
        "support@example.com"
    ],
}
```

Always validate field system names against the raw data to prevent inconsistencies.

Input

Input Parameter	Required/Optional	Description	Example
Ticket IDs	Required	The IDs of the tickets to update. Ticket IDs can be obtained using the List Tickets or Search Tickets commands.	JSON `[ ***** ]`
Requester Email	Optional	The email address of the requester. If there is no existing contact with this email in Freshservice, a new contact will be created.	test@example.com
Ticket Subject	Optional	The subject of the ticket.	Suspicious phishing email-New Subject
Description	Optional	The HTML content of the ticket.	Update ticket test 0830a
Priority	Optional	The priority level of the ticket. Available options are: Urgent High Medium Low If Urgency and Impact are defined, they can override this value.	Urgent
Status	Optional	The status of the ticket. Available options are: Open Pending Resolved Closed	Pending
Source	Optional	The source of the ticket. Available options are: Email Portal Phone Chat Feedback Widget Yammer AWS Cloudwatch Pagerduty Walkup Slack Workplace Employee Onboarding MS Teams Employee Offboarding	Portal
Urgency	Optional	The urgency level of the ticket. Available options are: High Medium Low	High
Impact	Optional	The impact level of the ticket. Available options are: High Medium Low	Medium
Ticket Type	Optional	The ticket type. Available options are: Incident Service Request	Service Request
Tags	Optional	The tags for the ticket. All associated tags must be specified. Tags can consist of any text. New tags will be created if they do not already exist in the system.	JSON `[ "IMPORTANT", "tag_1" ]`
Additional Fields	Optional	The key-value pairs for custom or other desired fields during ticket creation. Ensure custom fields are first set up under Admin > Service Management > Service Desk Settings > Field Manager > Ticket Fields > Ticket Form. If field entries overlap with other parameters, the other parameters will be omitted. Refer to Customize Ticket Fields from Freshservice's documentation for more information.	JSON `{ "cc_emails": [ "test@example.com" ], "custom_fields": { "custom_note": "testNote830c" } }`
File IDs	Optional	The IDs of the files stored in D3 SOAR's database to upload as ticket attachments. The total attachment size cannot exceed 40 MB.	JSON `[ "*****" ]`
File Source	Optional	The file source of the files to upload as ticket attachments. The options for file sources are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event	Playbook File

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Tickets failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: It should be in the 'valid email address' format.

Error Sample Data

Update Tickets failed.

Status Code: 400.

Message: It should be in the 'valid email address' format.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Output Type

Description

Return Data Type

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

More details about an error can be viewed in the Error tab.

String

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help users locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Freshservice portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Test Connection failed caused of an unexpected error. Please use test command and check Raw Data for the details.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Test Connection failed caused of an unexpected error. Please use test command and check Raw Data for the details.

FAQ

How can I add and define values for custom ticket fields?

First, add the desired custom fields from Freshservice's UI. Next, use the Create Ticket or Update Ticket commands to add values to existing custom ticket fields via the Additional Fields parameter in either commands. For further clarification, refer to the READER NOTEs under the Create Ticket and Update Ticket commands.