"
+ "attachments": [
+ {
+ "id":1,
+ "name":"attachment_cr_1",
+ "content_type":"image/jpeg",
+ "size": 19127,
+ "created_at":"2018-07-19T09:08:53+05:30",
+ "updated_at":"2018-08-19T09:08:53+05:30",
+ "attachment_url":"attachment_url",
+ "thumb_url":"attachment_thumb_url"
+ }
+ ],
+ "created_at":"2018-08-16T09:08:53+05:30",
+ "updated_at":"2018-08-16T09:08:53+05:30"
+ }
+]
+EXPAND ↓
+Discussions
+Enable your customers to help each other by enabling them to communicate with each other to ask questions, share ideas, and learn from each other. You can also gather critical feedback on what your customers like and dislike, what they'd like you to add and what they'd like you to change from discussion forums. Furthermore, if a critical issue or idea is raised in the community, you can convert it into a ticket and get your team to work on it right away.
+
+Categories
+In addition to helping you organize your community discussions better, Categories are useful when you are providing support across multiple products. You can choose to only show certain forum categories pertaining to a specific product in that product's portal.
+
+Attribute Type Description
+description string Description of the forum category
+id number Unique ID of the forum category
+name string Name of the forum category
+created_at datetime Forum Category creation timestamp
+updated_at datetime Forum Category updated timestamp
+Create a Forum Category
+post /api/v2/discussions/categories
+Parameters
+Attribute Type Description
+description string Description of the forum category
+name
+Mandatory
+Unique
+string Name of the forum category
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"How to", "description":"Getting Started" }' 'https://domain.freshdesk.com/api/v2/discussions/categories'
+Response
+{
+ "id" : 2,
+ "name" : "How to",
+ "description" : "Queries on How to ?",
+ "created_at" : "2015-08-25T07:47:49Z",
+ "updated_at" : "2015-08-25T07:47:49Z"
+}
+View a Forum Category
+get /api/v2/discussions/categories/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories/2'
+Response
+{
+ "id" : 2,
+ "name" : "Report Problems",
+ "description" : "Tell us your problems",
+ "created_at" : "2015-08-25T07:47:49Z",
+ "updated_at" : "2015-08-25T07:53:00Z"
+}
+List All Forum Categories
+get /api/v2/discussions/categories
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories'
+Response
+[
+ {
+ "id" : 1,
+ "name" : "Test Account Forums",
+ "description" : "Default forum category, feel free to edit or delete it.",
+ "created_at" : "2015-08-10T07:54:33Z",
+ "updated_at" : "2015-08-10T07:54:33Z"
+ },
+ {
+ "id" : 2,
+ "name" : "Report Problems",
+ "description" : "Tell us your problems",
+ "created_at" : "2015-08-25T07:47:49Z",
+ "updated_at" : "2015-08-25T07:53:00Z"
+ }
+]
+EXPAND ↓
+List All Forums in a Category
+get /api/v2/discussions/categories/[id]/forums
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories/2/forums'
+Response
+[
+ {
+ "id" : 1,
+ "name" : "Announcements",
+ "description" : "General helpdesk announcements to the customers.",
+ "position" : 1,
+ "forum_category_id" : 1,
+ "forum_type" : 4,
+ "forum_visibility" : 1,
+ "topics_count" : 0,
+ "posts_count" : 0
+ },
+ {
+ "id" : 2,
+ "name" : "Feature Requests",
+ "description" : "Customers can voice their ideas here.",
+ "position" : 2,
+ "forum_category_id" : 1,
+ "forum_type" : 2,
+ "forum_visibility" : 1,
+ "topics_count" : 0,
+ "posts_count" : 0
+ },
+ {
+ "id" : 3,
+ "name" : "Tips and Tricks",
+ "description" : "Helpful Tips and Tricks.",
+ "position" : 3,
+ "forum_category_id" : 1,
+ "forum_type" : 1,
+ "forum_visibility" : 1,
+ "topics_count" : 0,
+ "posts_count" : 0
+ },
+ {
+ "id" : 4,
+ "name" : "Report a problem",
+ "description" : "",
+ "position" : 4,
+ "forum_category_id" : 1,
+ "forum_type" : 3,
+ "forum_visibility" : 1,
+ "topics_count" : 0,
+ "posts_count" : 0
+ }
+]
+EXPAND ↓
+Update a Forum Category
+put /api/v2/discussions/categories/[id]
+Parameters
+Attribute Type Description
+description string Description of the forum category
+name
+Unique
+string Name of the forum category
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name":"Report Problems", "description":"Tell us your problems" }' 'https://domain.freshdesk.com/api/v2/discussions/categories/3'
+Response
+{
+ "id" : 2,
+ "name" : "Report Problems",
+ "description" : "Tell us your problems",
+ "created_at" : "2015-08-25T07:47:49Z",
+ "updated_at" : "2015-08-25T07:53:00Z"
+}
+Delete a Forum Category
+delete /api/v2/discussions/categories/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/categories/3'
+Response
+HTTP Status: 204 No Content
+Forums
+Forums are collections of similar topics, so customers know exactly where to go to get a specific answer from the community. For example, you can have a specific forum to collect Feature Requests from your customers, another forum for the community to share tips and tricks and a third forum where customers can talk about the problems they are facing and their solutions.
+
+Attribute Type Description
+company_ids Array of numbers If the forum_visibility property is set to 4, the forum is only visible to users belonging to certain companies. This property is an array of those company IDs.
+description string Description of the forum
+forum_category_id number ID of the category to which this forum belongs
+forum_type number Denotes the type of forum (Supported types can be seen in the Forum properties table below)
+forum_visibility number Denotes the visibility level of the forum (See the Forum Visibility table below for supported levels)
+id number Unique ID of the forum
+name string Name of the forum
+position number Controls the order in which the forums are displayed in the web page
+posts_count number The total number of posts in the forum
+topics_count number The total number of topics in the forum
+Forum Properties
+Forum Type Value
+How To's 1
+Ideas 2
+Problems 3
+Announcements 4
+Forum Visibility Value
+Everyone 1
+Logged in users only 2
+Agents only 3
+Users in specific companies only 4
+Create A Forum
+post /api/v2/discussions/categories/[category_id]/forums
+Parameters
+Attribute Type Description
+company_ids Array of numbers If the forum_visibility property is set to 4, the forum is only visible to users belonging to certain companies. This property is an array of those company IDs.
+description string Description of the forum
+forum_type
+Mandatory
+number Denotes the type of forum (Supported types can be referred in the Forum type table below)
+forum_visibility
+Mandatory
+number Denotes the visibility level of the forum (Supported types can be referred in the Forum visibility table below)
+name
+Mandatory
+Unique
+string Name of the forum
+Forum Properties
+Forum Type Value
+How To's 1
+Ideas 2
+Problems 3
+Announcements 4
+Forum Visibility Value
+Everyone 1
+Logged in users only 2
+Agents only 3
+Users in specific companies only 4
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "description":"Ticket related functions", "forum_type":2, "forum_visibility":4, "name":"Ticket Operations", "company_ids":[1,2] }' 'https://domain.freshdesk.com/api/v2/discussions/categories/1/forums'
+Response
+{
+ "id" : 5,
+ "name" : "Ticket Operations",
+ "description" : "Ticket related functions",
+ "position" : 5,
+ "forum_category_id" : 1,
+ "forum_type" : 2,
+ "forum_visibility" : 4,
+ "topics_count" : 0,
+ "posts_count" : 0,
+ "company_ids" : [
+ 1,
+ 2
+ ]
+}
+EXPAND ↓
+View A Forum
+get /api/v2/discussions/forums/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/2'
+Response
+{
+ "id" : 5,
+ "name" : "Ticket Operations",
+ "description" : "Tickets and Ticket fields related queries",
+ "position" : 5,
+ "forum_category_id" : 1,
+ "forum_type" : 2,
+ "forum_visibility" : 1,
+ "topics_count" : 0,
+ "posts_count" : 0
+}
+EXPAND ↓
+List All Topics in a Forum
+get /api/v2/discussions/forums/[id]/topics
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/5/topics'
+Response
+[
+ {
+ "id" : 1,
+ "title" : "how to create a custom field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : false,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : true,
+ "created_at" : "2015-08-25T08:54:23Z",
+ "updated_at" : "2015-08-25T08:54:23Z",
+ "replied_at" : "2015-08-25T08:54:23Z"
+ },
+ {
+ "id" : 2,
+ "title" : "how to create a custom field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : false,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : false,
+ "created_at" : "2015-08-25T08:55:21Z",
+ "updated_at" : "2015-08-25T08:55:21Z",
+ "replied_at" : "2015-08-25T08:55:21Z"
+ },
+ {
+ "id" : 3,
+ "title" : "How to create a new ticket field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : true,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : false,
+ "created_at" : "2015-08-25T08:55:41Z",
+ "updated_at" : "2015-08-25T09:27:49Z",
+ "replied_at" : "2015-08-25T08:55:41Z"
+ }
+]
+EXPAND ↓
+Update a Forum
+put /api/v2/discussions/forums/[id]
+Note:
+1. The forum_type attribute cannot be updated if the forum already has topics.
+2. The company_ids attribute cannot be updated unless the forum_visibility is set to 4.
+
+Parameters
+Attribute Type Description
+company_ids Array of numbers If the forum_visibility property is set to 4, the forum is only visible to users belonging to certain companies. This property is an array of those company IDs.
+description string Description of the forum
+forum_category_id number ID of the category to which this forum belongs
+forum_type number Denotes the type of forum (Supported types can be referred in the Forum type table below)
+forum_visibility number Denotes the visibility level of the forum (Supported types can be referred in the Forum visibility table below)
+name
+Unique
+string Name of the forum
+Forum Properties
+Forum Type Value
+How To's 1
+Ideas 2
+Problems 3
+Announcements 4
+Forum Visibility Value
+Everyone 1
+Logged in users only 2
+Agents only 3
+Users in specific companies only 4
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "description":"Tickets and Ticket fields related queries", "forum_type":2, "forum_visibility":1 }' 'https://domain.freshdesk.com/api/v2/discussions/forums/2'
+Response
+{
+ "id" : 5,
+ "name" : "Ticket Operations",
+ "description" : "Tickets and Ticket fields related queries",
+ "position" : 5,
+ "forum_category_id" : 1,
+ "forum_type" : 2,
+ "forum_visibility" : 1,
+ "topics_count" : 0,
+ "posts_count" : 0
+}
+EXPAND ↓
+Delete a Forum
+delete /api/v2/discussions/forums/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/forums/2'
+Response
+HTTP Status: 204 No Content
+Monitor Forum
+post /api/v2/discussions/forums/[id]/follow
+Parameters
+Attribute Type Description
+user_id Integer ID of the user who wished to follow the forum
+If the user_id is not mentioned, the user whose API Key was used to make the API call will be considered the recipient.
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "user_id" : 2 }' 'https://domain.freshdesk.com/api/v2/discussions/forums/1/follow'
+Response
+HTTP Status: 204 No Content
+Unmonitor Forum
+delete /api/v2/discussions/forums/[forum_id]/follow?user_id=[user_id]
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/forums/1/follow?user_id=2'
+Response
+HTTP Status: 204 No Content
+Monitoring Status For Forum
+get /api/v2/discussions/forums/[id]/follow?user_id=[id]
+This API allows you to check if a forum is being monitored by a specific user. A HTTP status code of 204 indicates that it is being monitored while a status code of 404 indicates that it is not being monitored.
+
+Note:
+1. If the user_id is not mentioned, we will assume that the user is the one whose credentials (identified by the API key) are used to make the API call
+2. Only administrators can check if a forum is being monitored by someone else
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/14581/follow?user_id=2'
+Response
+HTTP Status: 204 No Content
+Topics
+Topics or individual posts in your forums are the actual discussion threads.
+
+Attribute Type Description
+forum_id number ID of the Forum in which this topic is present
+hits number Number of views of that topic
+id number Unique ID of the topic
+locked boolean Set to true if the topic is locked which means that no more posts can be added to the topic
+merged_topic_id number ID of the topic to which it is merged into
+message string Message body of the topic
+posts_count number Number of posts in that topic
+replied_at datetime Timestamp of the latest comment made in the topic
+replied_by datetime ID of the user who made the latest comment in that topic
+stamp_type number Stamp type given to the topic
+sticky boolean Set to true if the topic should stay on top of the forum for additional visibility
+title string Title of the topic
+user_id number ID of the user who created the topic
+user_votes number Number of votes in the topic
+created_at datetime Forum Topic creation timestamp
+updated_at datetime Forum Topic updated timestamp
+Topic Properties
+Forum Type of Topic Valid Topic Stamp
+Question 6 - Answered, 7 - Unanswered
+Idea nil, 1 - Planned, 2 - Implemented, 3 - Not Taken, 4 - In Progress, 5 - Deferred
+Problem 8 - Solved, 9 - Unsolved
+Announcement nil
+Create a Topic
+post /api/v2/discussions/forums/[forum_id]/topics
+Note:
+1. message given in the request will be added as the first comment/post to the topic.
+2. sticky, locked can be part of request only if you have privilege to update a topic.
+
+Parameters
+Attribute Type Description
+locked boolean Set to true if the topic is locked which means that no more posts can be added to the topic
+message
+Mandatory
+string Message body of the topic
+stamp_type number stamp type given to the topic
+sticky boolean Set to true if the topic should stay on top of the forum for additional visibility
+title
+Mandatory
+string Title of the topic
+Topic Properties
+Forum Type of Topic Valid Topic Stamp
+Question 6 - Answered, 7 - Unanswered
+Idea nil, 1 - Planned, 2 - Implemented, 3 - Not Taken, 4 - In Progress, 5 - Deferred
+Problem 8 - Solved, 9 - Unsolved
+Announcement nil
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "sticky":true, "locked":false, "title":"how to create a custom field", "message":"Can someone give me the steps..." }' 'https://domain.freshdesk.com/api/v2/discussions/forums/5/topics'
+Response
+{
+ "id" : 1,
+ "title" : "how to create a custom field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : false,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : true,
+ "created_at" : "2015-08-25T08:54:23Z",
+ "updated_at" : "2015-08-25T08:54:23Z",
+ "replied_at" : "2015-08-25T08:54:23Z"
+}
+EXPAND ↓
+View a Topic
+get /api/v2/discussions/topics/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/3'
+Response
+{
+ "id" : 3,
+ "title" : "How to create a new ticket field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : true,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : false,
+ "created_at" : "2015-08-25T08:55:41Z",
+ "updated_at" : "2015-08-25T09:27:49Z",
+ "replied_at" : "2015-08-25T08:55:41Z"
+}
+EXPAND ↓
+List All Comments in a Topic
+get /api/v2/discussions/topics/[id]/comments
+To view all conversations/comments/comments in a specific topic, use this API
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/1/comments'
+Response
+[
+ {
+ "id" : 1,
+ "body_text" : "Can someone give me the steps...",
+ "body" : "Can someone give me the steps...",
+ "topic_id" : 1,
+ "forum_id" : 5,
+ "user_id" : 1,
+ "answer" : false,
+ "published" : true,
+ "spam" : null,
+ "trash" : false,
+ "created_at" : "2015-08-25T08:54:23Z",
+ "updated_at" : "2015-08-25T08:54:23Z"
+ },
+ {
+ "id" : 4,
+ "body_text" : "What type of ticket field you are creating",
+ "body" : "What type of ticket field you are creating",
+ "topic_id" : 1,
+ "forum_id" : 5,
+ "user_id" : 1,
+ "answer" : false,
+ "published" : true,
+ "spam" : null,
+ "trash" : false,
+ "created_at" : "2015-08-25T09:36:54Z",
+ "updated_at" : "2015-08-25T09:36:54Z"
+ },
+ {
+ "id" : 5,
+ "body_text" : "What type of ticket field you are creating",
+ "body" : "What type of ticket field you are creating",
+ "topic_id" : 1,
+ "forum_id" : 5,
+ "user_id" : 1,
+ "answer" : false,
+ "published" : true,
+ "spam" : null,
+ "trash" : false,
+ "created_at" : "2015-08-25T09:41:16Z",
+ "updated_at" : "2015-08-25T09:41:16Z"
+ }
+]
+EXPAND ↓
+Update a Topic
+put /api/v2/discussions/topics/[id]
+Note:
+1. If message is part of the request, then the first comment/post of the topic will be updated.
+2. The forum_id can be only be updated if you have privilege to manage forums.
+
+Parameters
+Attribute Type Description
+forum_id number ID of the Forum in which this topic is present
+locked boolean Set to true if the topic is locked which means that no more posts can be added to the topic
+message string Message body of the topic
+stamp_type number stamp type given to the topic
+sticky boolean Set to true if the topic should stay on top of the forum for additional visibility
+title string Title of the topic
+Topic Properties
+Forum Type of Topic Valid Topic Stamp
+Question 6 - Answered, 7 - Unanswered
+Idea nil, 1 - Planned, 2 - Implemented, 3 - Not Taken, 4 - In Progress, 5 - Deferred
+Problem 8 - Solved, 9 - Unsolved
+Announcement nil
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "sticky":false, "locked":true, "title":"How to create a new ticket field", "message": "Steps: Go to Admin tab ..." }' 'https://domain.freshdesk.com/api/v2/discussions/topics/3'
+Response
+{
+ "id" : 3,
+ "title" : "How to create a new ticket field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : true,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : false,
+ "created_at" : "2015-08-25T08:55:41Z",
+ "updated_at" : "2015-08-25T09:27:49Z",
+ "replied_at" : "2015-08-25T08:55:41Z"
+}
+EXPAND ↓
+Delete a Topic
+delete /api/v2/discussions/topics/[id]
+Note:
+Deleted topics cannot be brought back to life.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/topics/1'
+Response
+HTTP Status: 204 No Content
+Monitor Topic
+post /api/v2/discussions/topics/[id]/follow
+Parameters
+Attribute Type Description
+user_id Integer ID of the user who wishes to follow the forum
+If the user_id is not mentioned, the user whose API Key was used to make the API call will be consider the recipient.
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '' 'https://domain.freshdesk.com/api/v2/discussions/topics/1/follow'
+Response
+HTTP Status: 204 No Content
+Unmonitor Topic
+delete /api/v2/discussions/topics/[topic_id]/follow?user_id=[user_id]
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE -d '{ "user_id" : 21 }' 'https://domain.freshdesk.com/api/v2/discussions/topics/1/follow?user_id=2'
+Response
+HTTP Status: 204 No Content
+Monitoring Status For Topic
+get /api/v2/discussions/topics/[id]/follow?user_id=[id]
+This API allows you to check if a topic is being monitored by a specific user. A HTTP status code of 204 indicates that it is being monitored while a status code of 404 indicates that it is not being monitored.
+
+Note:
+1. If the user_id is not mentioned, we will assume that the user is the one whose credentials (identified by the API key) were used to make the API call
+2. Only administrators can check if a topic is being monitored by someone else
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/14581/follow?user_id=2'
+Response
+HTTP Status: 204 No Content
+List All Monitored Topics
+get /api/v2/discussions/topics/followed_by?user_id=[id]
+This API allows you to view the list of topics that are being monitored by a specific user.
+
+Note:
+1. If the user_id is not mentioned, we will assume that the user is the one whose credentials (identified by the API key) were used to make the API call.
+2. Only administrators can view the list of topics that are being monitored by someone else.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/followed_by?user_id=12'
+Response
+[
+ {
+ "id" : 1,
+ "title" : "how to create a custom field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : false,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : true,
+ "created_at" : "2015-08-25T08:54:23Z",
+ "updated_at" : "2015-08-25T08:54:23Z",
+ "replied_at" : "2015-08-25T08:54:23Z"
+ },
+ {
+ "id" : 2,
+ "title" : "how to create a custom field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : false,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : false,
+ "created_at" : "2015-08-25T08:55:21Z",
+ "updated_at" : "2015-08-25T08:55:21Z",
+ "replied_at" : "2015-08-25T08:55:21Z"
+ },
+ {
+ "id" : 3,
+ "title" : "How to create a new ticket field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : true,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : false,
+ "created_at" : "2015-08-25T08:55:41Z",
+ "updated_at" : "2015-08-25T09:27:49Z",
+ "replied_at" : "2015-08-25T08:55:41Z"
+ }
+]
+EXPAND ↓
+List All Participated Topics
+get /api/v2/discussions/topics/participated_by?user_id=[id]
+This API allows you to view the list of topics participated by a specific user, either creating or commenting in the topic.
+
+Note:
+1. If the user_id is not mentioned, we will assume that the user is the one whose credentials (identified by the API key) were used to make the API call.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/participated_by?user_id=27'
+Response
+[
+ {
+ "id" : 1,
+ "title" : "how to create a custom field",
+ "forum_id" : 5,
+ "user_id" : 27,
+ "locked" : false,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : true,
+ "created_at" : "2015-08-25T08:54:23Z",
+ "updated_at" : "2015-08-25T08:54:23Z",
+ "replied_at" : "2015-08-25T08:54:23Z"
+ },
+ {
+ "id" : 2,
+ "title" : "how to create a custom field",
+ "forum_id" : 5,
+ "user_id" : 12,
+ "locked" : false,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : false,
+ "created_at" : "2015-08-25T08:55:21Z",
+ "updated_at" : "2015-08-25T08:55:21Z",
+ "replied_at" : "2015-08-25T08:55:21Z"
+ },
+ {
+ "id" : 3,
+ "title" : "How to create a new ticket field",
+ "forum_id" : 5,
+ "user_id" : 1,
+ "locked" : true,
+ "published" : true,
+ "stamp_type" : null,
+ "replied_by" : 1,
+ "posts_count" : 1,
+ "hits" : 0,
+ "user_votes" : 0,
+ "merged_topic_id" : null,
+ "sticky" : false,
+ "created_at" : "2015-08-25T08:55:41Z",
+ "updated_at" : "2015-08-25T09:27:49Z",
+ "replied_at" : "2015-08-25T08:55:41Z"
+ }
+]
+EXPAND ↓
+Comments
+Attribute Type Description
+answer boolean Indicates if the comment is marked as the answer (for forum topics of type "Question")
+body string Content of the comment in HTML
+forum_id number ID of the forum in which the comment was posted
+id number Unique ID of the comment or comment
+published boolean Indicates if the comment is being published (allowed by moderators)
+spam boolean Indicates if the comment is marked as spam
+topic_id number ID of the topic in which the comment was posted
+trash boolean Indicates if the Comment is marked as deleted
+user_id number ID of the user who posted the comment
+created_at datetime Comment creation timestamp
+updated_at datetime Comment updated timestamp
+Create A Comment
+post /api/v2/discussions/topics/[topic_id]/comments
+Parameters
+Attribute Type Description
+body
+Mandatory
+string Content of the comment in HTML
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"What type of ticket field you are creating" }' 'https://domain.freshdesk.com/api/v2/discussions/topics/1/comments'
+Response
+{
+ "id" : 4,
+ "body_text" : "What type of ticket field you are creating",
+ "body" : "What type of ticket field you are creating",
+ "topic_id" : 1,
+ "forum_id" : 5,
+ "user_id" : 1,
+ "answer" : false,
+ "published" : true,
+ "spam" : null,
+ "trash" : false,
+ "created_at" : "2015-08-25T09:36:54Z",
+ "updated_at" : "2015-08-25T09:36:54Z"
+}
+EXPAND ↓
+Update A Comment
+put /api/v2/discussions/comments/[id]
+Parameters
+Attribute Type Description
+answer boolean Indicates if the comment is marked as the answer (for forum topics of type "Question")
+body string Content of the comment in HTML
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "body": "Ticket field have different types ..." }' 'https://domain.freshdesk.com/api/v2/discussions/comments/6'
+Response
+{
+ "id" : 6,
+ "body_text" : "Ticket field have different types ...",
+ "body" : "Ticket field have different types ...",
+ "topic_id" : 1,
+ "forum_id" : 5,
+ "user_id" : 1,
+ "answer" : false,
+ "published" : true,
+ "spam" : null,
+ "trash" : false,
+ "created_at" : "2015-08-25T09:41:19Z",
+ "updated_at" : "2015-08-25T09:41:19Z"
+}
+EXPAND ↓
+Delete A Comment
+delete /api/v2/discussions/comments/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/comments/1'
+Response
+HTTP Status: 204 No Content
+Solutions
+An effective knowledge base solves two of the biggest help desk problems. First, since all agents have a common place to pool in and share solutions, you can be sure that customer responses are consistent throughout. Second, since customers can access and help themselves to solutions, they feel more confident about your business. And all the while, your support load reduces.
+
+For better clarity, the Freshdesk knowledge base is categorized into a three level hierarchy - top level Categories that hold related Folders and Solution Articles inside each folder.
+
+Categories
+Categories broadly classify your solutions page into several sections. For example, you could place Shipping, Payments and Delivery related information under the Order Fulfilment category. Another interesting application of the top level category is when you are providing support across multiple brands or products.
+
+Attribute Type Description
+id number Unique ID of the solution category
+name string Name of the solution category
+description string Description of the solution category
+visible_in_portals array of numbers List of portal IDs where this category is visible
+created_at datetime Solution Category creation timestamp
+updated_at datetime Solution Category updated timestamp
+Create a Solution Category
+post /api/v2/solutions/categories
+Parameters
+Attribute Type Description
+description string Description of the solution category
+name
+Mandatory
+Unique
+string Name of the solution category
+visible_in_portals array of numbers List of portal IDs where this category is visible. Allowed only if the account is configured with multiple portals.
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"sample category", "description":"This is a sample category." }' 'https://domain.freshdesk.com/api/v2/solutions/categories'
+Response
+{
+ "id": 3,
+ "name": "sample category",
+ "description": "This is a sample category.",
+ "created_at": "2016-09-06T10:00:13Z",
+ "updated_at": "2016-09-06T10:00:13Z"
+}
+Create a translated solution category
+post/api/v2/solutions/categories/[id]/[language_code]
+Note:
+1. Multilingual Feature must be enabled for the account
+2. Supported languages have to be configured from Admin > General Settings > Helpdesk
+3. Configured languages can be retrieved from Helpdesk Settings
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"la categoría de la muestra", "description":"este es creado para fines de demostración" }' 'https://domain.freshdesk.com/api/v2/solutions/categories/3/es'
+Response
+{
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "description": "este es creado para fines de demostración",
+ "created_at": "2016-09-08T07:04:07Z",
+ "updated_at": "2016-09-08T07:04:07Z"
+}
+Update a Solution Category
+put /api/v2/solutions/categories/[id]
+Parameters
+Attribute Type Description
+description string Description of the solution category
+name
+Unique
+string Name of the solution category
+visible_in_portals array of numbers List of portal IDs where this category is visible. Allowed only if the account is configured with multiple portals.
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "description":"updated description" }' 'https://domain.freshdesk.com/api/v2/solutions/categories/3'
+Response
+{
+ "id": 3,
+ "name": "sample category",
+ "description": "updated description",
+ "created_at": "2016-09-06T10:00:13Z",
+ "updated_at": "2016-09-06T10:00:13Z"
+}
+Update a translated solution category
+put/api/v2/solutions/categories/[id]/[language_code]
+Note:
+1. Multilingual Feature must be enabled for the account
+2. Supported languages have to be configured from Admin > General Settings > Helpdesk
+3. Configured languages can be retrieved from Helpdesk Settings
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "description":"actualizada descripción" }' 'https://domain.freshdesk.com/api/v2/solutions/categories/3/es'
+Response
+{
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "description": "actualizada descripción",
+ "created_at": "2016-09-08T07:04:07Z",
+ "updated_at": "2016-09-08T07:04:07Z"
+}
+View a Solution Category
+get /api/v2/solutions/categories/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3'
+Response
+{
+ "id": 3,
+ "name": "sample category",
+ "description": "This is a sample category.",
+ "created_at": "2016-09-06T10:00:13Z",
+ "updated_at": "2016-09-06T10:00:13Z"
+}
+View a translated solution category
+get/api/v2/solutions/categories/[id]/[language_code]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/es'
+Response
+{
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "description": "este es creado para fines de demostración",
+ "created_at": "2016-09-08T07:04:07Z",
+ "updated_at": "2016-09-08T07:04:07Z"
+}
+List all Solution Categories
+get /api/v2/solutions/categories
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories'
+Response
+[
+ {
+ "id": 1,
+ "name": "Default Category",
+ "description": null,
+ "created_at": "2016-09-08T05:50:39Z",
+ "updated_at": "2016-09-08T05:50:39Z"
+ },
+ {
+ "id": 2,
+ "name": "General",
+ "description": "Default solution category, feel free to edit or delete it.",
+ "created_at": "2016-09-08T05:50:39Z",
+ "updated_at": "2016-09-08T05:50:39Z"
+ },
+ {
+ "id": 3,
+ "name": "sample category",
+ "description": "This is a sample category created for demo purpose.",
+ "created_at": "2016-09-08T07:01:25Z",
+ "updated_at": "2016-09-08T07:01:25Z"
+ }
+]
+EXPAND ↓
+View all translated solution categories
+get/api/v2/solutions/categories/[language_code]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/es'
+Response
+[
+ {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "description": "este es creado para fines de demostración",
+ "created_at": "2016-09-08T07:04:07Z",
+ "updated_at": "2016-09-08T07:04:07Z"
+ }
+]
+Delete a Solution Category
+delete /api/v2/solutions/categories/[id]
+Note:
+When deleted, all translated versions will be deleted too.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/categories/3'
+Response
+HTTP Status: 204 No Content
+Folders
+Related Solutions Articles and/or Folders are organized into Folders. Folders make it convenient for users to read similar articles or navigate to other possible solutions to their problem. For example, you can club solution articles related to tracking codes and postal services under the "Shipping" folder and “Shipping Folder” under “Orders Folder”.
+
+Parameters
+Attribute Type Description
+id number Unique ID of the solution folder
+name string Name of the solution folder
+description string Description of the solution folder
+parent_folder_id number ID of the parent folder
+hierarchy array of objects Parent category and folders in which the folder is placed
+articles_count number Number of articles present inside a folder
+sub_folders_count number Number of folders present inside a folder
+visibility number Accessibility of this folder. Please refer to Folder Properties table.
+company_ids array of numbers IDs of the companies to whom this solution folder is visible
+contact_segment_ids array of numbers IDs of the contact segments to whom this solution folder is visible
+company_segment_ids array of numbers IDs of the company segments to whom this solution folder is visible
+created_at datetime Solution Folder creation timestamp
+updated_at datetime Solution Folder updated timestamp
+
+Folder Visibility Properties
+Visibility Value
+All Users 1
+Logged In Users 2
+Agents 3
+Selected Companies 4
+Bots 5
+Selected Contact Segments 6
+Selected Company Segments 7
+Note:
+Attributes like parent_folder_id, sub_folders_count and hierarchy are specific to the 'Flexible Hierarchy' feature.
+
+Create a Solution Folder
+post /api/v2/solutions/categories/[id]/folders
+Parameters
+Attribute Type Description
+description string Description of the solution folder
+name
+Mandatory
+Unique
+string Name of the solution folder
+parent_folder_id number ID of the parent folder
+visibility number Accessibility of this folder. The default value is 1
+company_ids array of numbers IDs of the companies to whom this solution folder is visible
+contact_segment_ids array of numbers IDs of the contact segments to whom this solution folder is visible
+company_segment_ids array of numbers IDs of the company segments to whom this solution folder is visible
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"sample folder", "description":"This is a sample folder.", "parent_folder_id":2, "visibility":1 }' 'https://domain.freshdesk.com/api/v2/solutions/categories/3/folders'
+Response
+{
+ "id": 4,
+ "name": "sample folder",
+ "description": "This is a sample folder",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 1,
+ "category_id": 3,
+ "created_at": "2016-09-08T12:04:49Z",
+ "updated_at": "2016-09-08T12:04:49Z"
+}
+EXPAND ↓
+Create a translated solution folder
+post/api/v2/solutions/folders/[id]/[language_code]
+Note:
+1. Multilingual Feature must be enabled for the account
+2. Supported languages have to be configured from Admin > General Settings > Helpdesk
+3. Configured languages can be retrieved from Helpdesk Settings
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name" : "carpeta de la muestra", "description" : "este es creado para fines de demostración" }' 'https://domain.freshdesk.com/api/v2/solutions/folders/4/es'
+Response
+{
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "description": "este es creado para fines de demostración",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 1,
+ "category_id": 3,
+ "created_at": "2016-09-08T13:01:01Z",
+ "updated_at": "2016-09-08T13:01:01Z"
+}
+EXPAND ↓
+Update a Solution Folder
+put /api/v2/solutions/folders/[id]
+Parameters
+Attribute Type Description
+description string Description of the solution folder
+name
+Unique
+string Name of the solution folder
+parent_folder_id number ID of the parent folder
+visibility number Accessibility of this folder. The default value is 1
+company_ids array of numbers IDs of the companies to whom this solution folder is visible
+contact_segment_ids array of numbers IDs of the contact segments to whom this solution folder is visible
+company_segment_ids array of numbers IDs of the company segments to whom this solution folder is visible
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "description":"updated description", "visibility":4, "company_ids": [1] }' 'https://domain.freshdesk.com/api/v2/solutions/folders/3'
+Response
+{
+ "id": 4,
+ "name": "sample folder",
+ "description": "updated description",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 4,
+ "category_id": 3,
+ "created_at": "2016-09-08T12:04:49Z",
+ "updated_at": "2016-09-08T13:17:47Z",
+ "company_ids": [1]
+}
+EXPAND ↓
+Update a translated solution folder
+put/api/v2/solutions/folders/[id]/[language_code]
+Note:
+1. Multilingual Feature must be enabled for the account
+2. Supported languages have to be configured from Admin > General Settings > Helpdesk
+3. Configured languages can be retrieved from Helpdesk Settings
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "description":"actualizada descripción" }' 'https://domain.freshdesk.com/api/v2/solutions/folders/3/es'
+Response
+{
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "description": "actualizada Descripción",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 4,
+ "category_id": 3,
+ "created_at": "2016-09-08T13:01:01Z",
+ "updated_at": "2016-09-08T13:27:08Z",
+ "company_ids": [1]
+}
+EXPAND ↓
+View a Solution Folder
+get /api/v2/solutions/folders/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4'
+Response
+{
+ "id": 4,
+ "name": "sample folder",
+ "description": "This is a sample folder",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 1,
+ "category_id": 3,
+ "created_at": "2016-09-08T12:04:49Z",
+ "updated_at": "2016-09-08T12:04:49Z"
+}
+EXPAND ↓
+View a translated solution folder
+get/api/v2/solutions/folders/[id]/[language_code]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/es'
+Response
+{
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "description": "este es creado para fines de demostración",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 1,
+ "category_id": 3,
+ "created_at": "2016-09-08T13:01:01Z",
+ "updated_at": "2016-09-08T13:01:01Z"
+}
+EXPAND ↓
+List all Solution Folders in a Category
+get /api/v2/solutions/categories/[category_id]/folders
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/folders'
+Response
+[
+ {
+ "id": 4,
+ "name": "sample folder",
+ "description": "This is created for demo purpose",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 4,
+ "created_at": "2016-09-08T12:04:49Z",
+ "updated_at": "2016-09-08T13:17:47Z",
+ "company_ids": [1]
+ }
+]
+EXPAND ↓
+View all translated solution folders in a category
+get/api/v2/solutions/categories/[category_id]/folders/[language_code]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/folders/es'
+Response
+[
+ {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "description": "actualizada Descripción",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 4,
+ "created_at": "2016-09-08T13:01:01Z",
+ "updated_at": "2016-09-08T13:27:08Z",
+ "company_ids": [1]
+ }
+]
+EXPAND ↓
+List all Folders in a Folder
+get /api/v2/solutions/folders/[folder_id]/subfolders
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/2/subfolders'
+Response
+[
+ {
+ "id": 4,
+ "name": "sample folder",
+ "description": "This is created for demo purpose",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 4,
+ "created_at": "2016-09-08T12:04:49Z",
+ "updated_at": "2016-09-08T13:17:47Z",
+ "company_ids": [1]
+ }
+]
+EXPAND ↓
+List all translated folders in a folder
+get/api/v2/solutions/folders/[folder_id]/subfolders/[language_code]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/2/subfolders/es'
+Response
+[
+ {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "description": "actualizada Descripción",
+ "parent_folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "articles_count": 5,
+ "sub_folders_count": 3,
+ "visibility": 4,
+ "created_at": "2016-09-08T13:01:01Z",
+ "updated_at": "2016-09-08T13:27:08Z",
+ "company_ids": [1]
+ }
+]
+EXPAND ↓
+Delete a Solution Folder
+delete /api/v2/solutions/folders/[id]
+Note:
+When deleted, all translated versions will be deleted too.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/folders/3'
+Response
+HTTP Status: 204 No Content
+Articles
+Solution Articles or knowledge base posts promote self-help in your support portal. These should ideally cover all aspects of your product or service like "how-to" instructions and FAQs. For example, in an e-commerce store, your knowledge base articles would include payment instructions, shipping information, and product return policies.
+
+
+Attribute Type Description
+id number Unique ID of the solution article
+agent_id number ID of the agent who created the solution article
+category_id number ID of the category to which the solution article belongs
+description string Description of the solution article
+description_text string Description of the solution article in plain text
+folder_id number ID of the folder to which the solution article belongs
+hierarchy array of objects Parent category and folders in which the article is placed
+hits number Number of views for the solution article
+status number Status of the solution article
+seo_data dictionary Meta data for search engine optimization. Allows meta_title, meta_description and meta_keywords
+tags array of strings Tags that have been associated with the solution article
+thumbs_down number Number of down votes for the solution article
+thumbs_up number Number of upvotes for the solution article
+title string Title of the solution article
+created_at datetime Solution Article creation timestamp
+updated_at datetime Solution Article updated timestamp
+Create a Solution Article
+post /api/v2/solutions/folders/[id]/articles
+Parameters
+Attribute Type Description
+description
+Mandatory
+string Description of the solution article
+status
+Mandatory
+number Status of the solution article. (1 - draft, 2 - published)
+seo_data dictionary Meta data for search engine optimization. Allows meta_title, meta_description and meta_keywords
+tags array of strings Tags that have been associated with the solution article
+title
+Mandatory
+string Title of the solution article
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "title": "sample article", "description" : "this is a sample article with some
HTML Content ", "status": 1, "seo_data" : { "meta_keywords" : ["sample", "demo", "article"] } }' 'https://domain.freshdesk.com/api/v2/solutions/folders/4/articles'
+Response
+{
+ "id": 2,
+ "title": "sample article",
+ "description": "this is a sample article with some
HTML Content ",
+ "description_text": "this is a sample article with some HTML Content ",
+ "status": 1,
+ "agent_id": 1,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "tags": [],
+ "seo_data": {
+ "meta_keywords": "sample,demo,article"
+ },
+ "created_at": "2016-09-09T06:34:27Z",
+ "updated_at": "2016-09-09T06:34:27Z"
+}
+EXPAND ↓
+Create a translated solution article
+post/api/v2/solutions/articles/[id]/[language_code]
+Note:
+1. Multilingual Feature must be enabled for the account
+2. Supported languages have to be configured from Admin > General Settings > Helpdesk
+3. Configured languages can be retrieved from Helpdesk Settings
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "title": "artículo de la muestra", "description" : "este es un artículo de la muestra con un poco de
Contenido HTML ", "status": 1 }' 'https://domain.freshdesk.com/api/v2/solutions/articles/2/es'
+Response
+{
+ "id": 2,
+ "title": "artículo de la muestra",
+ "description": "este es un artículo de la muestra con un poco de
Contenido HTML ",
+ "description_text": "este es un artículo de la muestra con un poco de Contenido HTML ",
+ "status": 1,
+ "agent_id": 1,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "tags": [],
+ "seo_data": {},
+ "created_at": "2016-09-09T07:02:27Z",
+ "updated_at": "2016-09-09T07:02:27Z"
+}
+EXPAND ↓
+Update a Solution Article
+put /api/v2/solutions/articles/[id]
+Parameters
+Attribute Type Description
+agent_id number ID of the agent who created the solution article
+description string Description of the solution article
+status number Status of the solution article. (1 - draft, 2 - published)
+When status=1 is passed without any other parameters, the article will be unpublished
+seo_data dictionary Meta data for search engine optimization. Allows meta_title, meta_description and meta_keywords
+tags array of strings Tags that have been associated with the solution article
+title string Title of the solution article
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "description":"updated description", "agent_id" : 2, "status": 2 }' 'https://domain.freshdesk.com/api/v2/solutions/articles/2'
+Response
+{
+ "id": 2,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "tags": [],
+ "seo_data": {},
+ "agent_id": 2,
+ "title": "sample article",
+ "description": "updated description",
+ "description_text": "updated description",
+ "status": 2,
+ "created_at": "2016-09-09T06:34:27Z",
+ "updated_at": "2016-09-09T07:07:56Z"
+}
+EXPAND ↓
+Update a translated solution article
+put/api/v2/solutions/articles/[id]/[language_code]
+Note:
+1. Multilingual Feature must be enabled for the account
+2. Supported languages have to be configured from Admin > General Settings > Helpdesk
+3. Configured languages can be retrieved from Helpdesk Settings
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "description":"actualizada descripción", "status" : 2 }' 'https://domain.freshdesk.com/api/v2/solutions/articles/2/es'
+Response
+{
+ "id": 2,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "tags": [],
+ "seo_data": {},
+ "agent_id": 2,
+ "title": "artículo de la muestra",
+ "description": "actualizada descripción",
+ "description_text": "actualizada descripción",
+ "status": 2,
+ "created_at": "2016-09-09T07:02:27Z",
+ "updated_at": "2016-09-09T07:14:28Z"
+}
+EXPAND ↓
+View a Solution Article
+get /api/v2/solutions/articles/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/articles/2'
+Response
+{
+ "id": 2,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "tags": [],
+ "seo_data": {},
+ "agent_id": 2,
+ "title": "sample article",
+ "description": "updated description",
+ "description_text": "updated description",
+ "status": 2,
+ "created_at": "2016-09-09T06:34:27Z",
+ "updated_at": "2016-09-09T07:07:56Z"
+}
+EXPAND ↓
+View a translated solution article
+get/api/v2/solutions/articles/[id]/[language_code]
+Note:
+When language_code is passed, metrics such as "thumbs_up", "thumbs_down" and "hits" will be specific to the language. Otherwise, the response will contain the consolidated metrics data.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/articles/2/es'
+Response
+{
+ "id": 2,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "tags": [],
+ "seo_data": {},
+ "agent_id": 2,
+ "title": "artículo de la muestra",
+ "description": "actualizada descripción",
+ "description_text": "actualizada descripción",
+ "status": 2,
+ "created_at": "2016-09-09T07:02:27Z",
+ "updated_at": "2016-09-09T07:14:28Z"
+}
+EXPAND ↓
+List all Solution Articles in a Folder
+get /api/v2/solutions/folders/[id]/articles
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/articles'
+Response
+[
+ {
+ "id": 1,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "seo_data": {
+ "meta_keywords": "sample, demo, article"
+ },
+ "agent_id": 1,
+ "title": "article",
+ "description": "this is a sample article with some
HTML Content ",
+ "description_text": "this is a sample article with some HTML Content ",
+ "status": 1,
+ "created_at": "2016-09-09T06:07:26Z",
+ "updated_at": "2016-09-09T06:07:26Z"
+ },
+ {
+ "id": 2,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "seo_data": {},
+ "agent_id": 1,
+ "title": "sample article",
+ "description": "updated description",
+ "description_text": "updated description",
+ "status": 2,
+ "created_at": "2016-09-09T06:34:27Z",
+ "updated_at": "2016-09-09T07:07:56Z"
+ }
+]
+EXPAND ↓
+View all translated solution articles in a folder
+get/api/v2/solutions/folders/[id]/articles/[language_code]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/articles/es'
+Response
+[
+ {
+ "id": 2,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "la categoría de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "carpeta de la muestra",
+ "language": "es"
+ }
+ }
+ ],
+ "thumbs_up": 0,
+ "thumbs_down": 0,
+ "hits": 0,
+ "tags": [],
+ "seo_data": {},
+ "agent_id": 2,
+ "title": "artículo de la muestra",
+ "description": "actualizada descripción",
+ "description_text": "actualizada descripción",
+ "status": 2,
+ "created_at": "2016-09-09T07:02:27Z",
+ "updated_at": "2016-09-09T07:14:28Z"
+ }
+]
+EXPAND ↓
+Delete a Solution Article
+delete /api/v2/solutions/articles/[id]
+Note:
+When deleted, all translated versions will be deleted too.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/articles/2'
+Response
+HTTP Status: 204 No Content
+Search solution articles
+get /api/v2/search/solutions?term=[keyword]
+Search the articles in your Freshdesk account using a keyword.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/solutions?term=sample'
+Response
+[
+ {
+ "id": 2,
+ "type": 1,
+ "category_id": 3,
+ "folder_id": 4,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ },
+ {
+ "level": 2,
+ "type": "folder",
+ "data": {
+ "id": 4,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "folder_visibility": 1,
+ "agent_id": 1,
+ "path": "3-sample-article-",
+ "modified_at": "2016-09-09T07:07:56Z",
+ "modified_by": 300000001,
+ "language_id": 6,
+ "title": "sample article",
+ "status": 2,
+ "created_at": "2016-09-09T02:07:56Z",
+ "updated_at": "2016-09-09T07:07:56Z",
+ "description": "
sample description
",
+ "description_text": "sample description",
+ "category_name": "sample category",
+ "folder_name": "sample folder"
+ },
+ {
+ "id": 3,
+ "type": 1,
+ "category_id": 5,
+ "folder_id": 2,
+ "hierarchy": [
+ {
+ "level": 0,
+ "type": "category",
+ "data": {
+ "id": 3,
+ "name": "sample category2",
+ "language": "en"
+ }
+ },
+ {
+ "level": 1,
+ "type": "folder",
+ "data": {
+ "id": 2,
+ "name": "sample folder",
+ "language": "en"
+ }
+ }
+ ],
+ "folder_visibility": 1,
+ "agent_id": 3,
+ "path": "5-sample-article-2",
+ “modified_at": "2018-05-13T14:50:15Z",
+ "modified_by": 35005371819,
+ "language_id": 6,
+ "title": "sample article 2",
+ "status": 2,
+ "created_at": "2018-05-13T14:50:15Z",
+ "updated_at": "2018-05-13T14:50:15Z",
+ "description": "sample description 2",
+ "category_name": "sample category2",
+ "folder_name": "sample folder"
+ }
+]
+EXPAND ↓
+Surveys
+The Customer Satisfaction Survey is a built-in feature in Freshdesk that can be used to directly measure helpdesk efficiency and customer satisfaction with every support ticket. Every time you resolve a ticket on your helpdesk, you could choose to send out the survey to your customers asking them how their experience was during the issue.
+
+Attribute Type Description
+id number ID of the survey
+title string Title of the Survey
+questions string Questions associated with the Survey
+created_at datetime Survey creation timestamp
+updated_at datetime Survey updated timestamp
+Survey Question Attributes
+Attribute Type Description
+id string ID of the survey question. The default question for any survey will always have the ID as "default_question".
+label string Title of the survey question
+accepted_ratings array of string Accepted rating values for each specific question
+List all Surveys
+get /api/v2/surveys
+Use filters to view only specific surveys (those which match the criteria that you choose).
+
+Note:
+When using filters, the query string must be URL encoded
+
+Filter by Handle
+state /api/v2/surveys?state=active
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys'
+Response
+[
+ {
+ "id":123,
+ "title": "Default Survey",
+ "questions":[
+ {
+ "id": "default_question",
+ "label": "How would you rate your overall satisfaction for the resolution provided by the agent?",
+ "accepted_ratings":[
+ -103,
+ 100,
+ 103
+ ]
+ },
+ {
+ "id": "question_1",
+ "label": "Are you satisfied with our customer support experience?",
+ "accepted_ratings": [
+ -103,
+ 100,
+ 103
+ ]
+ }
+ ]
+ "created_at":"2015-08-18T16:18:05Z",
+ "updated_at":"2015-08-25T08:50:20Z"
+ }
+ },
+ {
+ "id":334,
+ "title": "Customer Survey",
+ "questions":[
+ {
+ "id": "question_3",
+ "label": "How would you rate your overall satisfaction for the resolution provided by the agent?",
+ "accepted_ratings":[
+ -103,
+ 100,
+ 103
+ ]
+ },
+ {
+ "id": "question_4",
+ "label": "Are you satisfied with our customer support experience?",
+ "accepted_ratings": [
+ -103,
+ -102
+ 100,
+ 103
+ ]
+ }
+ ]
+ "created_at":"2015-08-18T17:18:05Z",
+ "updated_at":"2015-08-25T09:50:20Z"
+ }
+ },
+ ...
+]
+EXPAND ↓
+Additional Examples
+1. Get a list of surveys filtered by the state.
+
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys?state=active'
+Satisfaction Ratings
+Every response to a customer satisfaction survey is recorded as a satisfaction rating. These ratings are used to generate a customer satisfaction report that you can use to see which of your agents have received the most number of happy ratings, and who hasn't been very helpful to your customers. This can help you in defining metrics in your support process more clearly and in training future support people based on results from the past.
+
+Attribute Type Description
+id number ID of the Satisfaction Rating
+survey_id number Survey ID of the satisfaction rating
+user_id number Requester ID of the ticket for which the satisfaction rating has been created or the ID of the user who has created the satisfaction rating.
+agent_id number Responder ID of the ticket for which the satisfaction rating has been created.
+group_id number Group ID associated with the ticket for which the satisfaction rating has been created.
+ticket_id number ID of the ticket for which the satisfaction rating has been created.
+feedback string Feedback given while creating the satisfaction rating.
+questions string Survey Questions associated with the Survey
+ratings key/value pair Key/Value pair of the question ID and the rating for that question. "default_question" will contain the default rating for the survey for both custom and classic surveys. Additional question_id and ratings for the questions will be present only for the new surveys.
+created_at datetime Satisfaction Rating creation timestamp
+updated_at datetime Satisfaction Rating updated timestamp
+Create a Satisfaction Rating
+post /api/v2/tickets/[ticket_id]/satisfaction_ratings
+Attribute Type Description
+feedback string Feedback for the satisfaction rating
+ratings key/value pair Key/Value pair of the question ID and the rating for that question. "default_question" will contain the default rating for the survey in case of both custom and classic survey.
+New Survey Ratings
+Rating Value Description
+103 Extremely Happy
+102 Very Happy
+101 Happy
+100 Neutral
+-101 Unhappy
+-102 Very Unhappy
+-103 Extremely Unhappy
+Classic Survey Ratings
+Rating Value Description
+1 Happy
+2 Neutral
+3 Unhappy
+Sample code | Curl
+curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "feedback":"Thank you for the quick action", "ratings":{ "default_question": 103, "question_2":-102 } }' 'https://domain.freshdesk.com/api/v2/tickets/[ticket_id]/satisfaction_ratings'
+Response
+{
+ "id": false,
+ "survey_id": 1,
+ "user_id": 2,
+ "agent_id": 1,
+ "feedback": "Thank you for the quick action",
+ "group_id": null,
+ "ticket_id": 432,
+ "ratings":{
+ "default_question":103,
+ "question_2":-102
+ },
+ "created_at": "2015-08-28T09:08:16Z",
+ "updated_at": "2015-08-28T09:08:16Z"
+}
+EXPAND ↓
+View all Satisfaction Ratings
+get /api/v2/surveys/satisfaction_ratings
+Use filters to view only specific satisfaction ratings (those which match the criteria that you choose). The filters listed in the table below can also be combined.
+
+Note:
+When using filters, the query string must be URL encoded
+
+Filter by Handle
+created_since Example:
+/api/v2/surveys/satisfaction_ratings?created_since=2015-01-19T02:00:00Z
+user_id Example:
+/api/v2/surveys/satisfaction_ratings?user_id=2
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys/satisfaction_ratings'
+Response
+[
+ {
+ "id": 102,
+ "survey_id": 1,
+ "user_id": 2,
+ "agent_id": 1,
+ "feedback": "Thank you for the quick action",
+ "group_id": null,
+ "ticket_id": 432,
+ "ratings":{
+ "default_question":103,
+ "question_2":-102
+ },
+ "created_at": "2015-08-28T09:08:16Z",
+ "updated_at": "2015-08-28T09:08:16Z"
+ },
+ {
+ "id": 112,
+ "survey_id": 1,
+ "user_id": 2,
+ "agent_id": 1,
+ "feedback": "Thank you for the support",
+ "group_id": null,
+ "ticket_id": 432,
+ "ratings":{
+ "default_question":101
+ },
+ "created_at": "2015-08-28T010:08:16Z",
+ "updated_at": "2015-08-28T011:08:16Z"
+ }
+]
+EXPAND ↓
+Additional Examples
+1. Get a list of satisfaction ratings filtered by the user_id.
+
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys/satisfaction_ratings?user_id=2'
+Overview
+Freshdesk’s Field Service Management (FSM) allows your support agents and field technicians to work together to deliver stellar support to your customers. With the FSM module enabled in your account, you can onboard and dispatch field technicians, plan their schedules, pass on information of the customer to them for context, and live-track progress as they solve problems on-site.
+
+With the help of these REST APIs listed here, you can perform read, modify, add and delete operations on Service Tasks, Service Groups and Field Technicians.
+
+To view the list of apps available for Field Service Management, visit our app marketplace.
+
+Before You Dive In
+
+To enable Field Service Management in Freshdesk:
+Login to your account as an Administrator.
+Go to Admin > Field Service Management under General Settings.
+Click on Enable to enable Field Service Management for your account.
+You will be redirected to the landing page for FSM; from here, you can add field technicians, create service groups and access reports. For more information, view these articles.
+Service Task
+A service task is a ticket assigned to a field technician. It outlines an upcoming job and describes the work to be done along with information that the field technician would need like location, site contact details, and appointment date and time.
+
+Create a Service Task
+post /api/v2/tickets
+To create a service task, use the Create A Ticket API.
+
+
+Note:
+It is mandatory that the value of ‘Type’ parameter is ‘Service Task’.
+A maximum of 10 service tasks can be created for a parent ticket.
+This API request could have the parent_id parameter. Parent_id is the ID of the parent ticket to which the service task is attached. For more information on Parent Child Ticketing refer to this section.
+In addition to the parameters available for Create A Ticket API, the following parameters are available:
+
+Additional Parameters
+Name Type Description
+parent_id number ID of the parent ticket. If this attribute is not passed, the service task will be created without any association to a parent ticket
+type * string Type of a ticket. Should be 'Service Task'
+cf_fsm_contact_name * string Contact name of the requestor
+cf_fsm_phone_number * number Phone number of the requestor
+cf_fsm_service_location * string Service location of the requestor
+cf_fsm_appointment_start_time datetime The start date and time of the appointment in the
+format: YYYY-MM-DDThh:mm:ssZ (in UTC)
+cf_fsm_appointment_end_time datetime The end date and time of the appointment in the
+format: YYYY-MM-DDThh:mm:ssZ (in UTC)
+* Mandatory custom fields
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "parent_id" : 120, "type": "Service Task", "subject": "Forklift maintenance", "description": "Regular annual maintenance for Forklift A", "status": 2, "priority": 1, "requester_id": 32733, "custom_fields" : { "cf_fsm_contact_name": "Bob Tree", "cf_fsm_phone_number": "23123 67344", "cf_fsm_service_location": "7, Clinton Street, Brooklyn", "cf_fsm_appointment_start_time": "2019-08-10T10:00:00Z", "cf_fsm_appointment_end_time": "2019-08-10T11:00:00Z" } }' -X POST 'https://domain.freshdesk.com/api/v2/tickets'
+Response
+{
+ "cc_emails": [],
+ "fwd_emails": [],
+ "reply_cc_emails": [],
+ "ticket_cc_emails": [],
+ "fr_escalated": false,
+ "spam": false,
+ "email_config_id": null,
+ "group_id": null,
+ "priority": 1,
+ "requester_id": 32733,
+ "responder_id": null,
+ "source": 2,
+ "company_id": null,
+ "status": 2,
+ "subject": "Forklift maintenance",
+ "to_emails": null,
+ "product_id": null,
+ "id": 125,
+ "type": "Service Task",
+ "due_by": null,
+ "fr_due_by": null,
+ "is_escalated": false,
+ "description": "
Regular annual maintenance for Forklift A
",
+ "description_text": "Regular annual maintenance for Forklift A",
+ "custom_fields": {
+ "cf_fsm_contact_name": "Bob Tree",
+ "cf_fsm_phone_number": "23123 67344",
+ "cf_fsm_service_location": "7, Clinton Street, Brooklyn",
+ "cf_fsm_appointment_start_time": "2019-08-10T10:00:00Z",
+ "cf_fsm_appointment_end_time": "2019-08-10T11:00:00Z"
+ },
+ "created_at": "2019-11-18T09:48:21Z",
+ "updated_at": "2019-11-18T09:48:21Z",
+ "tags": [],
+ "attachments": [],
+ "internal_agent_id": null,
+ "internal_group_id": null,
+ "association_type": 2,
+ "associated_tickets_list": [
+ 120
+ ]
+}
+EXPAND ↓
+View a Service Task
+get /api/v2/tickets/[id]
+To view a service task, use the View a Ticket API.
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/125'
+Response
+{
+ "cc_emails": [],
+ "fwd_emails": [],
+ "reply_cc_emails": [],
+ "ticket_cc_emails": [],
+ "fr_escalated": false,
+ "spam": false,
+ "email_config_id": null,
+ "group_id": null,
+ "priority": 1,
+ "requester_id": 32733,
+ "responder_id": null,
+ "source": 2,
+ "company_id": null,
+ "status": 2,
+ "subject": "Forklift maintenance",
+ "association_type": 2,
+ "to_emails": null,
+ "product_id": null,
+ "id": 125,
+ "type": "Service Task",
+ "due_by": null,
+ "fr_due_by": null,
+ "is_escalated": false,
+ "description": "
Regular annual maintenance for Forklift A
",
+ "description_text": "Regular annual maintenance for Forklift A",
+ "custom_fields": {
+ "cf_fsm_contact_name": "Bob Tree",
+ "cf_fsm_phone_number": "23123 67344",
+ "cf_fsm_service_location": "7, Clinton Street, Brooklyn",
+ "cf_fsm_appointment_start_time": "2019-08-10T10:00:00Z",
+ "cf_fsm_appointment_end_time": "2019-08-10T11:00:00Z"
+ },
+ "created_at": "2019-11-18T09:48:21Z",
+ "updated_at": "2019-11-18T09:48:21Z",
+ "tags": [],
+ "attachments": [],
+ "source_additional_info": null,
+ "associated_tickets_list": [
+ 120
+ ],
+ "internal_agent_id": null,
+ "internal_group_id": null
+}
+EXPAND ↓
+Update a Service Task
+put /api/v2/tickets/[id]
+To update a service task, use the Update a Ticket API.
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "priority" : 2, "status" : 3 }' 'https://domain.freshdesk.com/api/v2/tickets/125'
+Response
+{
+ "cc_emails": [],
+ "fwd_emails": [],
+ "reply_cc_emails": [],
+ "ticket_cc_emails": [],
+ "spam": false,
+ "email_config_id": null,
+ "fr_escalated": false,
+ "group_id": null,
+ "priority": 2,
+ "requester_id": 32733,
+ "responder_id": null,
+ "source": 2,
+ "status": 3,
+ "subject": "test subject",
+ "company_id": null,
+ "custom_fields": {
+ "cf_fsm_contact_name": "test contact name",
+ "cf_fsm_phone_number": "9876543210",
+ "cf_fsm_service_location": "test location",
+ "cf_fsm_appointment_start_time": "2019-08-10T10:00:00Z",
+ "cf_fsm_appointment_end_time": "2019-08-10T11:00:00Z"
+ },
+ "description": "
test description
",
+ "description_text": "test description",
+ "id": 123,
+ "type": "Service Task",
+ "to_emails": null,
+ "product_id": null,
+ "internal_group_id": null,
+ "internal_agent_id": null,
+ "association_type": 2,
+ "associated_tickets_list": [
+ 120
+ ],
+ "attachments": [],
+ "is_escalated": false,
+ "tags": [],
+ "created_at": "2019-11-14T05:25:01Z",
+ "updated_at": "2019-11-14T05:30:19Z",
+ "due_by": null,
+ "fr_due_by": null
+}
+EXPAND ↓
+Delete a Service Task
+delete /api/v2/tickets/[id]
+To delete a service task, use the Delete A Ticket API.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/125'
+Response
+HTTP Status: 204 No Content
+Service Group
+Create a Service Group
+post /api/v2/groups
+To create a service group, use the Create A Group API.
+
+Note:
+1. It is mandatory that the value of 'group_type' parameter is ‘field_agent_group’.
+2. The 'auto_ticket_assign' parameter is not applicable to service group creation
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name": "Entertainment", "description": "Singers and dancers", "agent_ids": [27542,32733], "group_type": "field_agent_group" }' 'https://domain.freshdesk.com/api/v2/groups'
+Response
+{
+ "id": 7834,
+ "name": "Entertainment",
+ "description": "Singers and dancers",
+ "escalate_to": null,
+ "unassigned_for": "30m",
+ "business_hour_id": null,
+ "agent_ids": [
+ 27542,
+ 32733
+ ],
+ "auto_ticket_assign": false,
+ "group_type": "field_agent_group",
+ "created_at": "2019-11-13T05:09:46Z",
+ "updated_at": "2019-11-13T05:09:46Z"
+}
+EXPAND ↓
+View a Service Group
+get /api/v2/groups/[id]
+To view a service group, use the View A Group API.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/groups/7861'
+Response
+{
+ "id": 7861,
+ "name": "Entertainment",
+ "description": "Singers and dancers",
+ "escalate_to": 33889,
+ "unassigned_for": "2h",
+ "business_hour_id": null,
+ "auto_ticket_assign": false,
+ "group_type": "field_agent_group",
+ "created_at": "2019-11-13T09:25:55Z",
+ "updated_at": "2019-11-13T09:25:55Z",
+ "agent_ids": [
+ 27542,
+ 32733,
+ 33829,
+ 33887
+ ]
+}
+EXPAND ↓
+Update a Service Group
+put /api/v2/groups/[id]
+To update a service group, use the Update A Group API.
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name": "Electronics", "description": "Electronic appliances" }' 'https://domain.freshdesk.com/api/v2/groups/1'
+Response
+{
+ "id": 7861,
+ "name": "Electronics",
+ "description": "Electronic appliances",
+ "escalate_to": 33889,
+ "unassigned_for": "30m",
+ "business_hour_id": null,
+ "agent_ids": [
+ 27542,
+ 32733,
+ 33829,
+ 33887
+ ],
+ "group_type": "field_agent_group",
+ "auto_ticket_assign": false,
+ "created_at": "2019-11-13T09:25:55Z",
+ "updated_at": "2019-11-18T12:25:35Z"
+}
+EXPAND ↓
+Delete a Service Group
+delete /api/v2/groups/[id]
+To delete a service group, use the Delete A Group API.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/groups/1'
+Response
+HTTP Status: 204 No Content
+Field Technicians
+An existing contact can be converted to a field technician. To convert an agent to a field technician, first delete the agent; this converts them into a contact. Then, use the Make Field Technician API to convert the contact to a field technician
+Make Field Technician
+put /api/v2/contacts/[id]/make_agent
+To make a contact a field technician, use the Make Agent API.
+
+Note:
+1. Role associated to a field technician can only be of 'field technician role'.
+2. A field technician cannot be an occasional agent.
+3. Type needs to be field_agent.
+4. A field technician can only be assigned ‘Group access (2)’ or ‘Restricted access (3)’ for the ticket_scope parameter. Default is 'Restricted access (3)'
+5. There should be enough 'field technician licenses' in order to convert a contact into field technician. See how licenses can be purchased here.
+
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "type": "field_agent", "occasional": false, "group_ids": [7861], "role_ids": [2492] }' 'https://domain.freshdesk.com/api/v2/contacts/432/make_agent'
+Response
+{
+ "active": false,
+ "email": "anc@anc.com",
+ "job_title": null,
+ "language": "en",
+ "last_login_at": null,
+ "mobile": null,
+ "name": "Anc",
+ "phone": null,
+ "time_zone": "Chennai",
+ "created_at": "2019-11-12T09:09:49Z",
+ "updated_at": "2019-11-12T09:09:49Z",
+ "agent": {
+ "available_since": null,
+ "available": false,
+ "occasional": false,
+ "signature": null,
+ "id": 33887,
+ "ticket_scope": 3,
+ "group_ids": [
+ 7861
+ ],
+ "type": "field_agent",
+ "role_ids": [
+ 2492
+ ],
+ "created_at": "2019-11-13T11:35:29Z",
+ "updated_at": "2019-11-13T11:35:29Z",
+ "focus_mode": true
+ }
+}
+EXPAND ↓
+Time Entries
+The time tracking feature in Freshdesk lets you track the time spent by each agent on resolving tickets and thereby enables you to gain visibility on the helpdesk's overall performance. Freshdesk lets agents track the time they spend on a ticket with automatic start and stop timers. Agents can also manually log the time they have spent, and detail their activities during this period by adding comments to the time entries.
+
+Attribute Type Description
+agent_id number The ID of the agent to whom this time-entry is associated
+billable boolean Set to true if the time entry is billable
+id number Unique ID of the time entry
+executed_at datetime Time at which this time-entry was added/created
+note string Description of the time entry
+start_time datetime The time at which the time-entry is added or the time of the last invoked "start-timer" action using a toggle
+ticket_id number The ID of the ticket to which this time entry is associated
+time_spent string The duration in hh:mm format
+timer_running boolean Set to 'true' if the timer is currently running
+created_at datetime Time Entry creation timestamp
+updated_at datetime Time Entry updated timestamp
+Create a Time Entry
+post /api/v2/tickets/[ticket_id]/time_entries
+Note:
+1. If the time_spent is not specified and the timer-running attribute is not specified, then the timer-running attribute will automatically be set to 'true'
+2. If the start_time is specified and the timer-running attribute is not specified, then the timer-running attribute will automatically be set to 'true'
+3. The start_time cannot be greater than the current time
+4. The start_time cannot be given in the API request if the timer_running attribute is set to 'false'
+
+Parameters
+Attribute Type Description
+agent_id number The agent to whom this time-entry is associated. One agent can have only one timer running. Everything else will be stopped if new timer is on for an agent
+billable boolean Set as true if the entry is billable. Default value is true
+executed_at datetime Time at which this time-entry id added/created
+note string Description on this time-entry
+start_time datetime The time at which the time-entry is added or the time of the last invoked "start-timer" action using a toggle
+time_spent string The number of hours (in hh:mm format). Used to set the total time_spent
+timer_running boolean Indicates if the timer is running
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"note":"Invoice Prepartion", "time_spent":"10:40", "agent_id":1 }' 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries'
+Response
+{
+ "id" : 2,
+ "billable" : true,
+ "note" : "Invoice Prepartion",
+ "timer_running" : false,
+ "agent_id" : 1,
+ "ticket_id" : 20,
+ "time_spent" : "10:40",
+ "created_at" : "2015-08-25T07:31:55Z",
+ "updated_at" : "2015-08-25T07:31:55Z",
+ "start_time" : "2015-08-25T07:31:55Z",
+ "executed_at" : "2015-08-25T07:31:55Z"
+}
+EXPAND ↓
+List All Time Entries
+get /api/v2/time_entries
+Use filters to view only specific time entries (those which match the criteria that you choose). The filters listed in the table below can also be combined.
+
+Filter by Handle
+Company ID /api/v2/time_entries?company_id=[value]
+Agent ID /api/v2/time_entries?agent_id=[value]
+executed_after /api/v2/time_entries?executed_after=[value]
+executed_before /api/v2/time_entries?executed_before=[value]
+billable /api/v2/time_entries?billable=[true/false]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/time_entries'
+Response
+[
+ {
+ "billable" : true,
+ "note" : null,
+ "timer_running" : true,
+ "id" : 1,
+ "agent_id" : 1,
+ "ticket_id" : 20,
+ "time_spent" : "00:00",
+ "created_at" : "2015-08-24T13:21:50Z",
+ "updated_at" : "2015-08-24T13:21:50Z",
+ "executed_at" : "2015-08-24T13:21:49Z",
+ "start_time" : "2015-08-24T13:21:49Z"
+ }
+]
+EXPAND ↓
+Additional Examples
+1. Get the list of billable time_entries
+
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/time_entries?billable=true'
+2. Get the list of time_entries executed before 2016-05-12 13:00:00
+
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/time_entries?executed_before=2016-05-12T13:00:00Z'
+Update a Time Entry
+put /api/v2/time_entries/[id]
+Note:
+1. The start_time cannot be updated if the timer is already running
+2. The start_time cannot be be updated unless the timer_running attribute is updated from 'true' to 'false'
+3. The start_time cannot be greater than the current time
+4. The timer_running attribute cannot be set to the same value as before
+5. The agent_id cannot be updated if the timer is already running
+
+Parameters
+Attribute Type Description
+agent_id number The agent to whom this time-entry is associated. One agent can have only one timer running. Everything else will be stopped if new timer is on for an agent
+billable boolean Set as true if the entry is billable. Default value is true
+executed_at datetime Time at which this time-entry id added/created
+note string Description on this time-entry
+start_time datetime The time at which the time-entry is added or the time of the last invoked "start-timer" action using a toggle
+time_spent string The number of hours (in hh:mm format). Used to set the total time_spent
+timer_running boolean Indicates if the timer is running
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{"billable":true, "note":"Monthly Invoice Preparation", "time_spent":"11:40", "agent_id":1 }' 'https://domain.freshdesk.com/api/v2/time_entries/41'
+Response
+{
+ "id" : 1,
+ "billable" : true,
+ "note" : "Monthly Invoice Prepartion",
+ "timer_running" : true,
+ "agent_id" : 1,
+ "ticket_id" : 20,
+ "time_spent" : "11:40",
+ "created_at" : "2015-08-24T13:21:50Z",
+ "updated_at" : "2015-08-25T07:11:22Z",
+ "start_time" : "2015-08-25T07:11:22Z",
+ "executed_at" : "2015-08-24T13:21:49Z"
+}
+EXPAND ↓
+Start/Stop Timer
+put /api/v2/time_entries/[time_entry_id]/toggle_timer
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshdesk.com/api/v2/time_entries/3/toggle_timer'
+Response
+{
+ "id" : 1,
+ "billable" : true,
+ "note" : "Monthly Invoice Prepartion",
+ "timer_running" : false,
+ "agent_id" : 1,
+ "ticket_id" : 20,
+ "time_spent" : "11:41",
+ "created_at" : "2015-08-24T13:21:50Z",
+ "updated_at" : "2015-08-25T07:12:39Z",
+ "start_time" : "2015-08-25T07:11:22Z",
+ "executed_at" : "2015-08-24T13:21:49Z"
+}
+EXPAND ↓
+Delete a Time Entry
+delete /api/v2/time_entries/[id]
+Note:
+Deleted time entries cannot be restored.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/time_entries/1'
+Response
+HTTP Status: 204 No Content
+Email Configs
+Note:
+This section is for the old email configuration APIs which are no longer supported. You can find the new mailbox APIs which have additional capabilities here.
+Only users with admin privileges can access the following APIs.
+
+Attribute Type Description
+active boolean Set to true if the email config is verified and activated
+group_id number Denotes the group ID to which the email is associated
+id number Unique ID of the email config
+name string Name of the email config
+primary_role boolean Set to true if the email associated to a product, is the primary email
+product_id number Denotes the product ID to which the email is associated
+reply_email string Denotes your support email address
+to_email string Denotes the email address to which your support emails gets forwarded
+created_at datetime Email Config creation timestamp
+updated_at datetime Email Config updated timestamp
+View an Email Config
+get /api/v2/email_configs/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email_configs/1'
+Response
+{
+ "id":1,
+ "name":"Primary Email",
+ "product_id":null,
+ "to_email":"support@domain.freshdesk.com",
+ "reply_email":"support@domain.freshdesk.com",
+ "group_id":null,
+ "primary_role":false,
+ "active":true,
+ "created_at":"2014-01-08T09:08:53+05:30",
+ "updated_at":"2014-01-08T09:08:53+05:30"
+}
+EXPAND ↓
+List All Email Configs
+get /api/v2/email_configs
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email_configs'
+Response
+[
+ {
+ "id":1,
+ "name":"Primary Email",
+ "product_id":null,
+ "to_email":"support@domain.freshdesk.com",
+ "reply_email":"support@domain.freshdesk.com",
+ "group_id":null,
+ "primary_role":true,
+ "active":true,
+ "created_at":"2015-05-03T09:08:53+05:30",
+ "updated_at":"2015-05-03T09:08:53+05:30"
+ }
+ {
+ "id":2,
+ "name":"Support emails",
+ "product_id":null,
+ "to_email":"domaincomexample@domain.freshdesk.com",
+ "reply_email":"example@domain.freshdesk.com",
+ "group_id":2,
+ "primary_role":false,
+ "active":false,
+ "created_at":"2015-07-03T09:08:53+05:30",
+ "updated_at":"2015-07-03T09:08:53+05:30"
+ }
+]
+EXPAND ↓
+Email MailboxesNEW
+Note:
+Only users with admin privileges can access the following APIs.
+
+Attribute Type Description
+access_type string Denotes if the custom mailbox is to be used for incoming, outgoing or both.Takes the values "incoming", "outgoing" or "both". Should be set to "outgoing" or "both" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
+active boolean Set to true if the email mailbox is verified and activated.
+authentication string Denotes the type of authentication that should be used authenticate the custom mailbox. It can be plain/login/CRAM-MD5
+custom_mailbox hash Mandatory if the mailbox is of the type custom mailbox. This field contains the incoming and/or outgoing configurations of the mailbox based on what access type is set.
+default_reply_email boolean Set to true if the email associated to a product, is the primary email.
+delete_from_server boolean If set to true, Freshdesk is given the permission to delete the email from the mailbox after the ticket is created.
+failure_code string Denotes the failure message if any in the custom incoming mailbox.
+forward_email string Denotes the email address to which your support emails gets forwarded.
+freshdesk_mailbox hash If the mailbox is of the type Freshdesk mailbox this field contains the forward email to which your support emails gets forwarded.
+group_id number Denotes the group ID to which the email is associated.
+id number Unique ID of the email mailbox.
+incoming hash Contains the incoming configuration of the custom mailbox.
+mail_server string Denotes the server used by incoming and/or outgoing configurations of the mailbox.
+mailbox_type string Denotes if the mailbox uses a Freshdesk mailbox or a custom mailbox setup by the customer. It takes the values "freshdesk_mailbox" or "custom_mailbox". Should be set to "custom_mailbox" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
+name string Name of the email mailbox.
+outgoing hash Contains the outgoing configuration of the custom mailbox.
+password string Denotes the password that will be used to authenticate the custom mailbox.
+port number Denotes the port used by incoming and/or outgoing configurations of the mailbox.
+product_id number Denotes the product ID to which the email is associated.
+support_email string Denotes your support email address.
+use_ssl boolean Denotes if the incoming and/or outgoing configuration should use ssl while authenticating the mailbox.
+username string Denotes the username used to authenticate the custom mailbox.
+created_at datetime Email Mailbox creation timestamp
+updated_at datetime Email Mailbox updated timestamp
+Create an Email Mailbox
+post /api/v2/email/mailboxes
+Parameters
+Attribute Type Description
+name string Name of the email mailbox.
+support_email
+Mandatory
+Unique
+string Denotes your support email address.
+group_id number Denotes the group ID to which the email is associated.
+product_id number Denotes the product ID to which the email is associated.
+default_reply_email string Set to true if the email associated to a product, is the primary email.
+mailbox_type
+Mandatory
+string Denotes if the mailbox uses a Freshdesk mailbox or a custom mailbox setup by the customer. It takes the values "freshdesk_mailbox" or "custom_mailbox". Should be set to "custom_mailbox" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
+custom_mailbox hash Mandatory if the mailbox is of the type custom mailbox. This field contains the incoming and/or outgoing configurations of the mailbox based on what access type is set.
+access_type string Denotes if the custom mailbox is to be used for incoming, outgoing or both.Takes the values "incoming", "outgoing" or "both". Should be set to "outgoing" or "both" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
+incoming hash Contains the incoming configuration of the custom mailbox.
+mail_server * string Denotes the server used by incoming and/or outgoing configurations of the mailbox.
+port * number Denotes the port used by incoming and/or outgoing configurations of the mailbox.
+use_ssl * boolean Denotes if the incoming and/or outgoing configuration should use ssl while authenticating the mailbox.
+delete_from_server ✝ boolean Denotes if the incoming configuration has to delete it from the server after authentication.
+authentication * string Denotes the type of authentication that should be used authenticate the custom mailbox. It can be plain/login/CRAM-MD5
+username * string Denotes the username used to authenticate the custom mailbox.
+password * string Denotes the password that will be used to authenticate the custom mailbox.
+* These attributes are mandatory in the incoming and/or outgoing hash if mailbox_type is 'custom_mailbox' and based on the access type set ("incoming", "outgoing" or "both").
+✝ These attributes are mandatory in the incoming hash if mailbox_type is 'custom_mailbox' based on the access type set("incoming", "outgoing" or "both").
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name": "Test emailbox via create api", "support_email": "testemail@gmail.com", "mailbox_type": "freshdesk_mailbox" }' 'https://domain.freshdesk.com/api/v2/email/mailboxes'
+Request
+{
+ "name": "Test emailbox via create api",
+ "support_email": "testemail@gmail.com",
+ "mailbox_type": "freshdesk_mailbox"
+}
+Response
+{
+
+ "id": 25,
+ "name": "Test emailbox via create api",
+ "support_email": "testemail@gmail.com",
+ "group_id": null,
+ "default_reply_email": false,
+ "active": false,
+ "mailbox_type": "freshdesk_mailbox",
+ "created_at": "2019-11-04T07:26:53Z",
+ "updated_at": "2019-11-04T07:26:53Z",
+ "product_id": null,
+ "freshdesk_mailbox": {
+ "forward_email": "gmailcomtestemail@freshdesk.com"
+ }
+}
+EXPAND ↓
+
+Create a custom mailbox
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name": "Test emailbox via create api", "support_email": "testemail@gmail.com", "default_reply_email": true, "group_id": 1, "product_id": 1, "mailbox_type": "custom_mailbox", "custom_mailbox": { "access_type": "both", "incoming": { "mail_server": "imap.gmail.com", "port": 993, "use_ssl": true, "delete_from_server": false, "authentication": "Plain", "user_name": "testemail@gmail.com", "password": "test" }, "outgoing": { "mail_server": "imap.gmail.com", "port": 465, "use_ssl": true, "authentication": "Plain", "user_name": "testemail@gmail.com", "password": "test" } } }' 'https://domain.freshdesk.com/api/v2/email/mailboxes'
+Request
+{
+ "name": "Test emailbox via create api",
+ "support_email": "testemail@gmail.com",
+ "default_reply_email": true,
+ "group_id": 1,
+ "product_id": 1,
+ "mailbox_type": "custom_mailbox",
+ "custom_mailbox": {
+ "access_type": "both",
+ "incoming": {
+ "mail_server": "imap.gmail.com",
+ "port": 993,
+ "use_ssl": true,
+ "delete_from_server": false,
+ "authentication": "Plain",
+ "user_name": "testemail@gmail.com",
+ "password": "test"
+ },
+ "outgoing": {
+ "mail_server": "imap.gmail.com",
+ "port": 465,
+ "use_ssl": true,
+ "authentication": "Plain",
+ "user_name": "testemail@gmail.com",
+ "password": "test"
+ }
+ }
+}
+EXPAND ↓
+Response
+{
+ "id": 1,
+ "name": "Test emailbox via create api",
+ "support_email": "testemail@gmail.com",
+ "group_id": 1,
+ "default_reply_email": true,
+ "active": false,
+ "mailbox_type": "custom_mailbox",
+ "created_at": "2019-11-04T06:08:07Z",
+ "updated_at": "2019-11-04T06:08:07Z",
+ "product_id": 1,
+ "custom_mailbox": {
+ "access_type": "both",
+ "incoming": {
+ "mail_server": "imap.gmail.com",
+ "port": 993,
+ "use_ssl": true,
+ "delete_from_server": false,
+ "authentication": "plain",
+ "user_name": "testemail@gmail.com",
+ "failure_code": null
+ },
+ "outgoing": {
+ "mail_server": "imap.gmail.com",
+ "port": 465,
+ "use_ssl": true,
+ "authentication": "plain",
+ "user_name": "testemail@gmail.com"
+ }
+ }
+}
+EXPAND ↓
+View an Email Mailbox
+get /api/v2/email/mailboxes/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes/1'
+Response
+{
+ "id": 1,
+ "name": "mailbox",
+ "support_email": "testemail@gmail.com",
+ "group_id": 6,
+ "default_reply_email": true,
+ "active": false,
+ "mailbox_type": "custom_mailbox",
+ "created_at": "2019-09-04T08:17:26Z",
+ "updated_at": "2019-09-18T11:42:32Z",
+ "product_id": 1,
+ "custom_mailbox": {
+ "access_type": "both",
+ "incoming": {
+ "mail_server": "imap.gmail.com",
+ "port": 993,
+ "use_ssl": true,
+ "delete_from_server": false,
+ "authentication": "plain",
+ "user_name": "testemail@gmail.com",
+ "failure_code": null
+ },
+ "outgoing": {
+ "mail_server": "smtp.gmail.com",
+ "port": 587,
+ "use_ssl": true,
+ "authentication": "plain",
+ "user_name": "testemail@gmail.com"
+ }
+ }
+}
+EXPAND ↓
+List All Email Mailboxes
+get /api/v2/email/mailboxes
+Use filters to view only specific mailboxes (those which match the criteria that you choose). The filters listed in the table below can also be combined
+
+Note:
+1. When using filters, the query string must be URL encoded
+2. By default the all the primary mailboxes will come first followed by the mailboxes ordered by product id in ascending.
+
+Filter by Handle
+support_email, forward_email /api/v2/contacts?
=
+Example:
+/api/v2/email/mailboxes?support_email=superman@freshdesk.com
+/api/v2/email/mailboxes?support_email=bat%2Bman%40gmail.com (URL encoded bat+man@gmail.com)
+product_id, group_id /api/v2/email/mailboxes?product_id=1
+/api/v2/email/mailboxes?group_id=1
+active /api/v2/email/mailboxes?active=[true/false]
+Order by Handle
+order_by * /api/v2/email/mailboxes?=
+Example:
+/api/v2/email/mailboxes?order_by=product_id
+/api/v2/email/mailboxes?order_by=group_id
+order_type /api/v2/contacts?product_id=1&order_type=desc
+/api/v2/contacts?group_id=1&order_type=asc
+*Required if order_type is set.
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes'
+Response
+[
+ {
+ "id": 1,
+ "name": "Test Account",
+ "support_email": "testemail@gmail.com",
+ "group_id": 1,
+ "default_reply_email": true,
+ "active": true,
+ "mailbox_type": "freshdesk_mailbox",
+ "created_at": "2019-08-20T05:55:38Z",
+ "updated_at": "2019-08-20T05:55:38Z",
+ "product_id": 2,
+ "freshdesk_mailbox": {
+ "forward_email": "gmailcomtestemail@freshdesk.com"
+ }
+ },
+ {
+ "id": 4,
+ "name": "mailbox",
+ "support_email": "superman@gmail.com",
+ "group_id": 6,
+ "default_reply_email": true,
+ "active": false,
+ "mailbox_type": "custom_mailbox",
+ "created_at": "2019-09-04T08:17:26Z",
+ "updated_at": "2019-09-18T11:42:32Z",
+ "product_id": 1,
+ "custom_mailbox": {
+ "access_type": "both",
+ "incoming": {
+ "mail_server": "imap.gmail.com",
+ "port": 993,
+ "use_ssl": true,
+ "delete_from_server": false,
+ "authentication": "plain",
+ "user_name": "superman@gmail.com",
+ "failure_code": "null"
+ },
+ "outgoing": {
+ "mail_server": "smtp.gmail.com",
+ "port": 587,
+ "use_ssl": true,
+ "authentication": "plain",
+ "user_name": "superman@gmail.com"
+ }
+ }
+ },
+ {
+ "id": 5,
+ "name": "Test 2",
+ "support_email": "batman@gmail.com",
+ "group_id": null,
+ "default_reply_email": true,
+ "active": true,
+ "mailbox_type": "freshdesk_mailbox",
+ "created_at": "2019-08-21T05:14:48Z",
+ "updated_at": "2019-09-05T07:19:30Z",
+ "product_id": 2,
+ "freshdesk_mailbox": {
+ "forward_email": "gmailcombatman@gmail.com"
+ }
+ },
+ ...
+]
+EXPAND ↓
+Additional Examples
+1. Get a list of mailboxes filtered by the support_email address. Since the support_email address is unique, you will get only one mailbox in the list.
+
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes?support_email=superman@gmail.com'
+2. Get the mailboxes associated with a specific product and a group that are active.
+
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes?product_id=1&group_id=1&active=true'
+3. Mailboxes ordered by group in descending.( order_by is required if order_type is present)
+
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes?order_by=group_id&order_type=desc'
+Update an Email Mailbox
+put /api/v2/email/mailboxes/[id]
+Parameters
+Attribute Type Description
+name string Name of the email mailbox.
+support_email string Denotes your support email address.
+group_id number Denotes the group ID to which the email is associated.
+product_id number Denotes the product ID to which the email is associated.
+default_reply_email string Set to true if the email associated to a product, is the primary email.
+mailbox_type string Denotes if the mailbox uses a Freshdesk mailbox or a custom mailbox setup by the customer. It takes the values "freshdesk_mailbox" or "custom_mailbox". Should be set to "custom_mailbox" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
+custom_mailbox hash Mandatory if the mailbox is of the type custom mailbox. This field contains the incoming and/or outgoing configurations of the mailbox based on what access type is set.
+access_type string Denotes if the custom mailbox is to be used for incoming, outgoing or both.Takes the values "incoming", "outgoing" or "both". Should be set to "outgoing" or "both" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
+incoming hash Contains the incoming configuration of the custom mailbox.
+mail_server * string Denotes the server used by incoming and/or outgoing configurations of the mailbox.
+port * number Denotes the port used by incoming and/or outgoing configurations of the mailbox.
+use_ssl * boolean Denotes if the incoming and/or outgoing configuration should use ssl while authenticating the mailbox.
+delete_from_server ✝ boolean Denotes if the incoming configuration has to delete it from the server after authentication.
+authentication * string Denotes the type of authentication that should be used authenticate the custom mailbox. It can be plain/login/CRAM-MD5
+username * string Denotes the username used to authenticate the custom mailbox.
+password * string Denotes the password that will be used to authenticate the custom mailbox.
+* These attributes are mandatory in the incoming and/or outgoing hash if mailbox_type is 'custom_mailbox' and based on the access type set ("incoming", "outgoing" or "both").
+✝ These attributes are mandatory in the incoming hash if mailbox_type is 'custom_mailbox' based on the access type set("incoming", "outgoing" or "both").
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name": "Test emailbox via update api", "support_email": "testemail@gmail.com", "mailbox_type": "freshdesk_mailbox" }' 'https://domain.freshdesk.com/api/v2/email/mailboxes'
+Request
+{
+ "name": "Test emailbox via update api",
+ "support_email": "testemail@gmail.com",
+ "group_id": 1,
+ "mailbox_type": "freshdesk_mailbox",
+}
+Response
+{
+
+ "id": 25,
+ "name": "Test emailbox via update api",
+ "support_email": "testemail@gmail.com",
+ "group_id": 1,
+ "default_reply_email": false,
+ "active": false,
+ "mailbox_type": "freshdesk_mailbox",
+ "created_at": "2019-11-04T07:26:53Z",
+ "updated_at": "2019-11-04T07:26:53Z",
+ "product_id": null,
+ "freshdesk_mailbox": {
+ "forward_email": "gmailcomtestemail@freshdesk.com"
+ }
+}
+EXPAND ↓
+
+Update a custom mailbox
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name": "Test emailbox via update api", "support_email": "testemail@gmail.com", "default_reply_email": true, "group_id": 1, "product_id": 1, "mailbox_type": "custom_mailbox", "custom_mailbox": { "access_type": "both", "incoming": { "mail_server": "imap.gmail.com", "port": 993, "use_ssl": true, "delete_from_server": false, "authentication": "Plain", "user_name": "testemail@gmail.com", "password": "test" }, "outgoing": { "mail_server": "imap.gmail.com", "port": 465, "use_ssl": true, "authentication": "Plain", "user_name": "testemail@gmail.com", "password": "test" } } }' 'https://domain.freshdesk.com/api/v2/email/mailboxes'
+Request
+{
+ "name": "Test emailbox via update api",
+ "support_email": "testemail@gmail.com",
+ "default_reply_email": true,
+ "group_id": 1,
+ "product_id": 1,
+ "mailbox_type": "custom_mailbox",
+ "custom_mailbox": {
+ "access_type": "both",
+ "incoming": {
+ "mail_server": "imap.gmail.com",
+ "port": 993,
+ "use_ssl": true,
+ "delete_from_server": false,
+ "authentication": "Plain",
+ "user_name": "testemail@gmail.com",
+ "password": "test"
+ },
+ "outgoing": {
+ "mail_server": "imap.gmail.com",
+ "port": 465,
+ "use_ssl": true,
+ "authentication": "Plain",
+ "user_name": "testemail@gmail.com",
+ "password": "test"
+ }
+ }
+}
+EXPAND ↓
+Response
+{
+ "id": 1,
+ "name": "Test emailbox via update api",
+ "support_email": "testemail@gmail.com",
+ "group_id": 1,
+ "default_reply_email": true,
+ "active": false,
+ "mailbox_type": "custom_mailbox",
+ "created_at": "2019-11-04T06:08:07Z",
+ "updated_at": "2019-11-04T06:08:07Z",
+ "product_id": 1,
+ "custom_mailbox": {
+ "access_type": "both",
+ "incoming": {
+ "mail_server": "imap.gmail.com",
+ "port": 993,
+ "use_ssl": true,
+ "delete_from_server": false,
+ "authentication": "plain",
+ "user_name": "testemail@gmail.com",
+ "failure_code": null
+ },
+ "outgoing": {
+ "mail_server": "imap.gmail.com",
+ "port": 465,
+ "use_ssl": true,
+ "authentication": "plain",
+ "user_name": "testemail@gmail.com"
+ }
+ }
+}
+EXPAND ↓
+Delete an Email Mailbox
+delete /api/v2/email/mailboxes/[id]
+Note:
+1. This action is irreversible. Emails sent to this inbox will no longer be created as tickets.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/email/mailboxes/1'
+Response
+HTTP Status: 204 No Content
+Update Mailbox Settings
+put /api/v2/email/settings
+Parameters
+Attribute Type Description
+personalized_email_replies boolean If true, then agents will be allowed to choose their own name as the sender name in ticket replies and outbound emails. Sender email will still remain the support email address (like 'Rachel Doe ').
+create_requester_using_reply_to boolean Note: If false, requester will be created using 'From' address in email.
+allow_agent_to_initiate_conversation boolean If true, agents will be able to send outbound emails to new or existing customers that will be converted into outbound tickets.
+original_sender_as_requester_for_forward boolean When an agent forwards an email from their mailbox to the helpdesk, create the ticket under the original sender. If false, the requester is the agent.
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "personalized_email_replies": true, "create_requester_using_reply_to": true, "allow_agent_to_initiate_conversation": true, "original_sender_as_requester_for_forward": true }' 'https://domain.freshdesk.com/api/v2/email/settings'
+Request
+{
+ "personalized_email_replies": true,
+ "create_requester_using_reply_to": true,
+ "allow_agent_to_initiate_conversation": true,
+ "original_sender_as_requester_for_forward": true
+ }
+Response
+{
+ "personalized_email_replies": true,
+ "create_requester_using_reply_to": true,
+ "allow_agent_to_initiate_conversation": true,
+ "original_sender_as_requester_for_forward": true
+ }
+View Mailbox Settings
+get /api/v2/email/settings
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT GET 'https://domain.freshdesk.com/api/v2/email/settings'
+Response
+{
+ "personalized_email_replies": true,
+ "create_requester_using_reply_to": true,
+ "allow_agent_to_initiate_conversation": true,
+ "original_sender_as_requester_for_forward": true
+ }
+Update Automatic Bcc emails
+put /api/v2/notifications/email/bcc
+Note:
+1. The array has a limit of 255 characters.
+
+Parameters
+Attribute Type Description
+emails array This email address will be included automatically in the Bcc field for all ticket communications.
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "emails": ["testemail1@gmail.com", "testemail2@gmail.com"] }' 'https://domain.freshdesk.com/api/v2/notifications/email/bcc'
+Request
+{
+ "emails": ["testemail1@gmail.com", "testemail2@gmail.com"]
+ }
+Response
+{
+ "emails": ["testemail1@gmail.com", "testemail2@gmail.com"]
+ }
+View Automatic Bcc emails
+get /api/v2/notifications/email/bcc
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/notifications/email/bcc'
+Response
+{
+ "emails": ["testemail1@gmail.com", "testemail2@gmail.com"]
+ }
+Products
+If you offer multiple products, you can have a separate support portal for each product. You can give these portals different URLs and hide irrelevant forums and solution articles by restricting access to specific categories but have agents support all these products from a single helpdesk.
+
+Note:
+Only users with admin privileges can access the following APIs.
+
+Attribute Type Description
+description string Description of the product
+id number Unique ID of the product
+name string Name of the product
+created_at datetime Product creation timestamp
+updated_at datetime Product updated timestamp
+View a Product
+get /api/v2/products/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/products/1'
+Response
+{
+ "id":1,
+ "name":"Freshservice",
+ "description":"Support for IT",
+ "created_at":"2015-07-03T09:08:53+05:30",
+ "updated_at":"2015-07-03T09:08:53+05:30"
+}
+List All Products
+get /api/v2/products
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/products'
+Response
+[
+ {
+ "id":1,
+ "name":"Freshservice",
+ "description":"Support for IT",
+ "created_at":"2015-07-03T09:08:53+05:30",
+ "updated_at":"2015-07-03T09:08:53+05:30"
+ }
+]
+Business Hours
+Business Hours refer to the working hours of your company. When configured, anything outside your working hours will not be timed by Freshdesk. You can specify working hours for weekdays and weekends, as well as include a list of holidays on which your company will be closed.
+
+Note:
+Only users with admin privileges can access the following APIs.
+
+Attribute Type Description
+description string Description of the business hour
+id number Unique ID of the business hour
+is_default boolean Set to true if this is the default business hour
+name string Name of the business hour
+time_zone string Denotes the time zone of the business hour
+business_hours dictionary Collection of start time and end time of days of a week - 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'
+
+ATTRIBUTE TYPE DESCRIPTION
+monday
+tuesday
+wednesday
+thursday
+friday
+saturday
+sunday dictionary Object of 'start_time' and 'end_time'
+start_time string Time in "hh:mm:ss a" format ex: "08:00:00 am"
+end_time string Time in "hh:mm:ss a" format ex: "11:59:59 am"
+created_at datetime Business Hour creation timestamp
+updated_at datetime Business Hour updated timestamp
+View a Business Hour
+get /api/v2/business_hours/[id]
+To view a particular business hour amongst all in the roster, use this API
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/business_hours/35000006727'
+Response
+{
+ "id": 35000006727,
+ "name": "Default",
+ "description": "Default Business Calendar",
+ "time_zone": "Eastern Time (US & Canada)",
+ "is_default": true,
+ "business_hours": {
+ "monday": {
+ "start_time": "08:00:00 am",
+ "end_time": "11:59:59 pm"
+ },
+ "tuesday": {
+ "start_time": "08:00:00 am",
+ "end_time": "11:59:59 pm"
+ },
+ "wednesday": {
+ "start_time": "08:00:00 am",
+ "end_time": "05:00:00 pm"
+ },
+ "thursday": {
+ "start_time": "08:00:00 am",
+ "end_time": "05:00:00 pm"
+ },
+ "friday": {
+ "start_time": "08:00:00 am",
+ "end_time": "08:00:00 pm"
+ }
+ },
+ "created_at": "2017-09-21T14:00:50Z",
+ "updated_at": "2018-11-30T14:13:11Z"
+}
+EXPAND ↓
+List All Business Hours
+get /api/v2/business_hours
+To view all the business hours in your list, use this API.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/business_hours'
+Response
+[
+ {
+ "id": 35000006727,
+ "name": "Default",
+ "description": "Default Business Calendar",
+ "time_zone": "Eastern Time (US & Canada)",
+ "is_default": true,
+ "business_hours": {
+ "monday": {
+ "start_time": "08:00:00 am",
+ "end_time": "11:59:59 pm"
+ },
+ "tuesday": {
+ "start_time": "08:00:00 am",
+ "end_time": "11:59:59 pm"
+ },
+ "wednesday": {
+ "start_time": "08:00:00 am",
+ "end_time": "05:00:00 pm"
+ },
+ "thursday": {
+ "start_time": "08:00:00 am",
+ "end_time": "05:00:00 pm"
+ },
+ "friday": {
+ "start_time": "08:00:00 am",
+ "end_time": "08:00:00 pm"
+ }
+ },
+ "created_at": "2017-09-21T14:00:50Z",
+ "updated_at": "2018-11-30T14:13:11Z"
+ },
+ {
+ "id": 35000009127,
+ "name": "Default",
+ "description": "Americas Business Calendar",
+ "time_zone": "Eastern Time (US & Canada)",
+ "is_default": false,
+ "business_hours": {
+ "monday": {
+ "start_time": "08:00:00 am",
+ "end_time": "08:00:00 pm"
+ },
+ "tuesday": {
+ "start_time": "08:00:00 am",
+ "end_time": "08:00:00 pm"
+ },
+ "wednesday": {
+ "start_time": "08:00:00 am",
+ "end_time": "05:00:00 pm"
+ },
+ "thursday": {
+ "start_time": "08:00:00 am",
+ "end_time": "05:00:00 pm"
+ },
+ "friday": {
+ "start_time": "08:00:00 am",
+ "end_time": "08:00:00 pm"
+ }
+ },
+ "created_at": "2017-09-21T14:00:50Z",
+ "updated_at": "2018-11-30T14:13:11Z"
+ }
+
+]
+EXPAND ↓
+Scenario Automations
+Scenario Automations let you carry out a bunch of updates to the ticket with a single click. They help you quickly handle recurring scenarios.
+
+Attribute Type Description
+id number ID of the Scenario
+name string Name of the Scenario
+description string A short description about the Scenario
+actions array of actions Actions to be performed by the Scenario
+private boolean Boolean value stating whether the Scenario is accessible to self or all
+created_at datetime Scenario Automations creation timestamp
+updated_at datetime Scenario Automations updated timestamp
+List All Scenario Automations
+get /scenario_automations.json
+To view all the scenario automations in your list, use this API.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/scenario_automations'
+Response
+[
+ {
+ "id":1,
+ "name":"default",
+ "description":"Default Business Hour",
+ "actions":[
+ {
+ "name":"ticket_type",
+ "value":"Problem"
+ }
+ ],
+ "private":false
+ "created_at":"2018-08-16T09:08:53+05:30",
+ "updated_at":"2018-08-16T09:08:53+05:30"
+ }
+]
+EXPAND ↓
+SLA Policies
+A service level agreement (SLA) policy lets you set standards of performance for your support team. Your SLA policies will be used in Freshdesk to determine the 'Due By' time for each ticket. You can have a default SLA policy for all customers, or have multiple SLA policies for different customer tiers, like those who have subscribed to your Premium Support package.
+
+Note:
+Only users with admin privileges can access the following APIs.
+
+Attribute Type Description
+active boolean Set to true if the SLA policy is active
+description string Description of the SLA policy
+id number Unique ID of the SLA policy
+is_default boolean Set to true if it is the default SLA policy
+name string Name of the SLA policy
+position number Denotes the order of the SLA policy. If you have configured multiple SLA policies, the first one with matching conditions will be applied to a ticket.
+sla_target dictionary Key value pair containing the object and the array of object IDs denoting the priorities and the applicable conditions.
+'priority_4' - urgent, 'priority_3' - high, 'priority_2' - medium, 'priority_1' - low is mandatory and needs to be passed in the same order.
+
+ATTRIBUTE TYPE DESCRIPTION
+priority_4, priority_3, priority_2, priority_1 dictionary Nested collection of key value pairs containing the 'respond_within', 'resolve_within', 'business_hours', 'escalation_enabled'.
+All are mandatory
+respond_within number Mutliples of sixty and must be greater 900
+resolve_within number Mutliples of sixty and must be greater 900
+business_hours boolean Set to true if business hours needs to be used
+escalation_enabled boolean Set to true if escalation is required
+applicable_to dictionary Key value pair containing the 'company_ids', 'group_ids', 'sources', 'ticket_types', 'product_ids' denoting the conditions based on which the SLA policy is to be applied
+One of them is mandatory.
+
+ATTRIBUTE TYPE DESCRIPTION
+company_ids array of number List of company ids
+group_ids array of number List of group ids
+sources array of number List of sources
+ticket_types array of string List of ticket types
+product_ids array of number List of products
+escalation dictionary Nested collection of key value pairs containing the 'response' and 'resolution' denoting who to escalate to and when.
+One of them is mandatory.
+
+ATTRIBUTE TYPE DESCRIPTION
+response dictionary Key value pairs of 'escalation_time' and 'agent_ids' denoting escalation response due time and agent ids
+resolution dictionary Nested collection of key value pairs containing the 'level1', 'level2', 'level3', 'level4' levels of resolution escalation
+level must be in the increasing order. And one of them mandatory.
+i.e. level2 requires level1
+level3 requires level2 and level1
+level4 requires level3, level2 and level1
+level1, level2, level3, level4 dictionary Key value pairs of 'escalation_time' and 'agent_ids' denoting escalation resolution due time and agent ids
+escalation_time number Mutliples of sixty and must be greater 900
+agent_ids array of number List of agent ids
+Create SLA Policies
+post /api/v2/sla_policies
+Parameters
+Attribute Type Description
+name
+Mandatory
+string Name of the SLA policy
+sla_target
+Mandatory
+dictionary Key value pair containing the object and the array of object IDs denoting the priorities and the applicable conditions.
+applicable_to
+Mandatory
+dictionary Key Value pair of the object and the array of object IDs denoting the conditions based on which the SLA policy is to be applied
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name": "Service Agent SLA Policy", "description": "Service Agent SLA Policy", "active": true, "is_default": false, "position": 2, "sla_target": { "priority_4": {"respond_within": 300,"resolve_within": 600,"business_hours": true,"escalation_enabled": false }, "priority_3": {"respond_within": 600,"resolve_within": 900,"business_hours": true,"escalation_enabled": false }, "priority_2": {"respond_within": 900,"resolve_within": 1200,"business_hours": true,"escalation_enabled": false }, "priority_1": {"respond_within": 1200,"resolve_within": 1500,"business_hours": true,"escalation_enabled": false } }, "applicable_to": { "company_ids": [43000596607 ], "group_ids": [43000190415,43000190413 ], "sources": [2,5 ], "ticket_types": ["Incident","Feature Request" ], "product_ids": [43000003741 ] }, "escalation": { "response": {"escalation_time": 14400,"agent_ids": [43007075231,43025266048] }, "resolution": {"level_1": {"escalation_time": 3600,"agent_ids": [ 43007075231, 43025266165]},"level_2": {"escalation_time": 14400,"agent_ids": [ 43025266048]},"level_3": {"escalation_time": 259200,"agent_ids": [ 43025266165]},"level_4": {"escalation_time": 604800,"agent_ids": [ 43007075231, 43025236599]} } } }' 'https://domain.freshdesk.com/api/v2/sla_policies'
+EXPAND ↓
+Response
+{
+ "id": 43000088326,
+ "name": "Service Agent SLA Policy",
+ "description": "Service Agent SLA Policy",
+ "active": true,
+ "is_default": false,
+ "position": 2,
+ "sla_target": {
+ "priority_4": {
+ "respond_within": 300,
+ "resolve_within": 600,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_3": {
+ "respond_within": 600,
+ "resolve_within": 900,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_2": {
+ "respond_within": 900,
+ "resolve_within": 1200,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_1": {
+ "respond_within": 1200,
+ "resolve_within": 1500,
+ "business_hours": true,
+ "escalation_enabled": false
+ }
+ },
+ "applicable_to": {
+ "company_ids": [
+ 43000596607
+ ],
+ "group_ids": [
+ 43000190415,
+ 43000190413
+ ],
+ "sources": [
+ 2,
+ 5
+ ],
+ "ticket_types": [
+ "Incident",
+ "Feature Request"
+ ],
+ "product_ids": [
+ 43000003741
+ ]
+ },
+ "escalation": {
+ "response": {
+ "escalation_time": 14400,
+ "agent_ids": [
+ 43007075231,
+ 43025266048
+ ]
+ },
+ "resolution": {
+ "level_1": {
+ "escalation_time": 3600,
+ "agent_ids": [
+ 43007075231,
+ 43025266165
+ ]
+ },
+ "level_2": {
+ "escalation_time": 14400,
+ "agent_ids": [
+ 43025266048
+ ]
+ },
+ "level_3": {
+ "escalation_time": 259200,
+ "agent_ids": [
+ 43025266165
+ ]
+ },
+ "level_4": {
+ "escalation_time": 604800,
+ "agent_ids": [
+ 43007075231,
+ 43025236599
+ ]
+ }
+ }
+ },
+ "created_at": "2018-10-04T13:18:54Z",
+ "updated_at": "2019-02-13T12:22:51Z"
+}
+EXPAND ↓
+List All SLA Policies
+get /api/v2/sla_policies
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/sla_policies'
+Response
+[
+
+ {
+ "id": 43000088326,
+ "name": "Service Agent SLA Policy",
+ "description": "Service Agent SLA Policy",
+ "active": true,
+ "is_default": false,
+ "position": 2,
+ "sla_target": {
+ "priority_4": {
+ "respond_within": 1200,
+ "resolve_within": 900,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_3": {
+ "respond_within": 900,
+ "resolve_within": 900,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_2": {
+ "respond_within": 900,
+ "resolve_within": 900,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_1": {
+ "respond_within": 900,
+ "resolve_within": 900,
+ "business_hours": true,
+ "escalation_enabled": false
+ }
+ },
+ "applicable_to": {
+ "company_ids": [
+ 43000596607
+ ],
+ "group_ids": [
+ 43000190415,
+ 43000190413
+ ],
+ "sources": [
+ 2,
+ 5
+ ],
+ "ticket_types": [
+ "Incident",
+ "Feature Request"
+ ],
+ "product_ids": [
+ 43000003741
+ ]
+ },
+ "escalation": {
+ "response": {
+ "escalation_time": 14400,
+ "agent_ids": [
+ 43007075231,
+ 43025266048
+ ]
+ },
+ "resolution": {
+ "level_1": {
+ "escalation_time": 3600,
+ "agent_ids": [
+ 43007075231,
+ 43025266165
+ ]
+ },
+ "level_2": {
+ "escalation_time": 14400,
+ "agent_ids": [
+ 43025266048
+ ]
+ },
+ "level_3": {
+ "escalation_time": 259200,
+ "agent_ids": [
+ 43025266165
+ ]
+ },
+ "level_4": {
+ "escalation_time": 604800,
+ "agent_ids": [
+ 43007075231,
+ 43025236599
+ ]
+ }
+ }
+ },
+ "created_at": "2018-10-04T13:18:54Z",
+ "updated_at": "2019-02-13T12:22:51Z"
+ },
+ {
+ "id":1,
+ "name":"Default SLA Policy",
+ "description":"default policy",
+ "active": true,
+ "applicable_to":{},
+ "is_default":true,
+ "position" : 1,
+ "created_at":"2015-07-03T09:08:53+05:30",
+ "updated_at":"2015-07-03T09:08:53+05:30"
+ },
+ {
+ "id":2,
+ "name":"Company SLA Policy",
+ "description":"companies policy",
+ "active": true,
+ "applicable_to":{"group_ids":[3],"company_ids":[1,2]},
+ "is_default":false,
+ "position" : 2,
+ "created_at":"2015-07-03T09:08:53+05:30",
+ "updated_at":"2015-07-03T09:08:53+05:30"
+ }
+]
+EXPAND ↓
+Update an SLA Policy
+put /api/v2/sla_policies/[id]
+Parameters
+Attribute Type Description
+applicable_to
+Mandatory
+dictionary Key Value pair of the object and the array of object IDs denoting the conditions based on which the SLA policy is to be applied
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name": "Service Agent SLA Policy", "description": "Service Agent level SLA Policy", "active": true, "is_default": false, "position": 2, "sla_target": { "priority_4": {"respond_within": 300,"resolve_within": 300,"business_hours": true,"escalation_enabled": false }, "priority_3": {"respond_within": 600,"resolve_within": 600,"business_hours": true,"escalation_enabled": false }, "priority_2": {"respond_within": 900,"resolve_within": 1200,"business_hours": true,"escalation_enabled": false }, "priority_1": {"respond_within": 1200,"resolve_within": 1200,"business_hours": true,"escalation_enabled": false } }, "applicable_to": { "company_ids": [43000596607 ], "group_ids": [43000190415,43000190413 ], "sources": [2,5 ], "ticket_types": ["Incident","Feature Request" ], "product_ids": [43000003741 ] }, "escalation": { "response": {"escalation_time": 14400,"agent_ids": [43007075231,43025266048] }, "resolution": {"level_1": {"escalation_time": 3600,"agent_ids": [ 43007075231, 43025266165]},"level_2": {"escalation_time": 14400,"agent_ids": [ 43025266048]},"level_3": {"escalation_time": 259200,"agent_ids": [ 43025266165]},"level_4": {"escalation_time": 604800,"agent_ids": [ 43007075231, 43025236599]} } }' 'https://domain.freshdesk.com/api/v2/sla_policies/43000088326'
+EXPAND ↓
+Response
+{
+ "id": 43000088326,
+ "name": "Service Agent SLA Policy",
+ "description": "Service Agent level SLA Policy",
+ "active": true,
+ "is_default": false,
+ "position": 2,
+ "sla_target": {
+ "priority_4": {
+ "respond_within": 300,
+ "resolve_within": 300,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_3": {
+ "respond_within": 600,
+ "resolve_within": 600,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_2": {
+ "respond_within": 900,
+ "resolve_within": 1200,
+ "business_hours": true,
+ "escalation_enabled": false
+ },
+ "priority_1": {
+ "respond_within": 1200,
+ "resolve_within": 1200,
+ "business_hours": true,
+ "escalation_enabled": false
+ }
+ },
+ "applicable_to": {
+ "company_ids": [
+ 43000596607
+ ],
+ "group_ids": [
+ 43000190415,
+ 43000190413
+ ],
+ "sources": [
+ 2,
+ 5
+ ],
+ "ticket_types": [
+ "Incident",
+ "Feature Request"
+ ],
+ "product_ids": [
+ 43000003741
+ ]
+ },
+ "escalation": {
+ "response": {
+ "escalation_time": 14400,
+ "agent_ids": [
+ 43007075231,
+ 43025266048
+ ]
+ },
+ "resolution": {
+ "level_1": {
+ "escalation_time": 3600,
+ "agent_ids": [
+ 43007075231,
+ 43025266165
+ ]
+ },
+ "level_2": {
+ "escalation_time": 14400,
+ "agent_ids": [
+ 43025266048
+ ]
+ },
+ "level_3": {
+ "escalation_time": 259200,
+ "agent_ids": [
+ 43025266165
+ ]
+ },
+ "level_4": {
+ "escalation_time": 604800,
+ "agent_ids": [
+ 43007075231,
+ 43025236599
+ ]
+ }
+ }
+ },
+ "created_at": "2018-10-04T13:18:54Z",
+ "updated_at": "2019-02-16T12:22:51Z"
+}
+EXPAND ↓
+Omnichannel Activities
+The activity API allows you and your agents to record activities from an external application or system in Freshdesk's contact timeline. Pushing information from your applications about a user can provide rich contextual information to your support agents using Freshdesk. Activities published using this API would show up on the contact timeline giving your agents a complete view of the customer’s journey.
+
+Publish Activities
+post /api/v2/contact-activities
+Parameters
+Attribute Type Description
+activity
+Mandatory
+object Key value pair of the object which describes information about action that has occurred in an external application.
+
+ATTRIBUTE TYPE DESCRIPTION
+name
+Mandatory
+string The name of the activity performed (this is the text which is visible in the contact timeline).
+timestamp string The time at which the activity was performed. If not given, this would be populated with the time at which we received activity.
+description string User friendly description of the activity
+link string Link to the activity
+actor
+Mandatory
+object Key value pair of the object which describes the person or entity performed the activity.
+source
+Mandatory
+object Key value pair of the object which describes the application, where the activity was performed.
+object object Key value pair of the object which describes the object on which activity was performed.
+context object Key value pair of the object which can be used to send additional context about the activity. It should adhere to the JSON schema https://json-schema.org
+contact
+Mandatory
+object Key value pair of the object which represent Freshdesk contact information for identifying which contact to send the activity against. If the contact doesn’t exist with the given property, it will create a new contact.
+
+ATTRIBUTE TYPE DESCRIPTION
+email * string Email address of the contact
+twitter_id * string Twitter handle of the contact
+unique_external_id * string External ID of the contact
+facebook_id * string Facebook ID of the contact
+id * number ID of the contact
+name string Name of the contact
+is_actor boolean Used to define whether the actor who performed the activity is the contact or not. Default value is true, i.e we assume that the contact has performed the activity.
+*One of these five attributes is mandatory
+The following table lists the attributes of actor:
+Attribute Type Description
+id string ID of the actor.
+type
+Mandatory
+string The type of the actor. As an example, the type could be "agent", "shopper", "user", "customer", "system".
+name string Name of the actor.
+The following table lists the attributes of source:
+Attribute Type Description
+id string ID of the application, where the activity was performed.
+name
+Mandatory
+string Name of the application where the activity was performed.
+The following table lists the attributes of object:
+Attribute Type Description
+type string Type of the object. As an example, the type could be "call", "transaction", "cart", "website".
+id string ID of the object. It can be used to send transaction id, cart id etc.
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "activity": {"name": "Transaction failed", "timestamp": "2020-10-01T14:00:00Z", "description": "Transaction for Order ID on 1 Oct, 2019", "actor": {"id": "918mI2k1", "name": "Rachel", "type": "contact"}, "source": {"name": "shopify", "id": "7819e8k1119"}, "object": {"type": "transaction", "id": "1234", "link": "https://myorderstatus.orders.com/84637930"}, "context": {"name": "Rachel", "Items":2,"Item description": {"item1": {"Item name": "Gucci White Ace Sneakers", "Size": "10 UK", "Color": "White", "Instock": "Yes"}, "item2": {"Item name": "Gucci Round Sleeve T-Shirt", "Size": "40 UK", "Color": "Blue", "Instock": "Yes"} }, "Amount": "50", "Currency": "Dollars", "Postal code": "12401", "Order id": "84637930", "Transaction link": "myorderstatus.orders.com/84637930"} }, "contact": {"email": "rachel@freshdesk.com"} }' 'https://domain.freshdesk.com/api/v2/contact-activities'
+EXPAND ↓
+Response
+HTTP Status: 200 Success
+List All Automation Rules
+get /api/v2/automations/[automation_type_id]/rules
+Attribute Type Description
+automation_type_id
+Mandatory
+Type of the automation Type of the automation namely rules that run on: Ticket creation, Ticket updates and Hourly triggers
+
+Name Value
+automation_type_id
+1- Ticket creation
+3- Hourly triggers
+4- Ticket updates
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/automations/1/rules'
+Response
+{
+ "rules": [
+ {
+ "name": "string",
+ "position": 0,
+ "active": true,
+ "automation_type_id": 1,
+ "performer": {
+ "type": "string",
+ "members": [
+ "string"
+ ]
+ },
+ "events": [
+ {
+ "field_name": "string",
+ "from": "string",
+ "to": "string",
+ "value": "string",
+ "from_nested_field": {
+ "level": {
+ "field_name": "string",
+ "value": "string"
+ }
+ },
+ "to_nested_field": {
+ "level": {
+ "field_name": "string",
+ "value": "string"
+ }
+ }
+ }
+ ],
+ "conditions": [
+ {
+ "name": "string",
+ "match_type": "string",
+ "properties": [
+ {
+ "resource_type": "string",
+ "field_name": "string",
+ "operator": "string",
+ "value": "string",
+ "business_hours_id": 0,
+ "case_senstive": true,
+ "nested_fields": {
+ "level": {
+ "field_name": "string",
+ "value": "string"
+ }
+ },
+ "associated_fields": {
+ "field_name": "string",
+ "operator": "string",
+ "value": 0
+ },
+ "related_conditions": [
+ {
+ "field_name": "agent_availability",
+ "operator": "is",
+ "value": "unavailable",
+ "related_conditions": [
+ {
+ "field_name": "out_of_office",
+ "operator": "is",
+ "value": 0
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "operator": "string",
+ "actions": [
+ {
+ "field_name": "string",
+ "value": "string",
+ "email_to": 0,
+ "email_body": "string",
+ "api_key": "string",
+ "auth_header": {
+ "username": "string",
+ "password": "string"
+ },
+ "custom_headers": {
+ "value": "string"
+ },
+ "content": {
+ "content_layout": "string",
+ "content_type": "string"
+ },
+ "request_type": "string",
+ "url": "string",
+ "note_body": "string",
+ "notify_agents": [
+ 0
+ ],
+ "nested_fields": {
+ "level": {
+ "value": "string",
+ "field_name": "string"
+ }
+ },
+ "fwd_to": [
+ "string"
+ ],
+ "fwd_cc": "string",
+ "fwd_bcc": "string",
+ "fwd_note_body": "string",
+ "push_to": "string",
+ "slack_text": "string",
+ "office365_text": "string",
+ "resource_type": "same_ticket"
+ }
+ ],
+ "outdated": true,
+ "last_updated_by": 0,
+ "affected_tickets_count": 0,
+ "Summary": {
+ "performer": "string",
+ "events": [
+ "string"
+ ],
+ "conditions": {
+ "condition_set_1": [
+ "string"
+ ],
+ "condition_set_2": [
+ "string"
+ ]
+ },
+ "actions": [
+ "string"
+ ]
+ },
+ "id": 0,
+ "created_at": "2020-12-14T05:21:27.201Z",
+ "updated_at": "2020-12-14T05:21:27.201Z"
+ }
+ ],
+ "meta": {
+ "count": 0,
+ "cascading_rules": true
+ }
+}
+EXPAND ↓
+View an Automation Rule
+get /api/v2/automations/[automation_type_id]/rules/[id]
+Attribute Type Description
+id
+Mandatory
+integer ID of the automation rule
+automation_type_id
+Mandatory
+Integer Type id of the automation
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/automations/1/rules/109866'
+Response
+{
+ "name": "string",
+ "position": 0,
+ "active": true,
+ "automation_type_id": 0,
+ "performer": {
+ "type": "string",
+ "members": [
+ "string"
+ ]
+ },
+ "events": [
+ {
+ "field_name": "string",
+ "from": "string",
+ "to": "string",
+ "value": "string",
+ "from_nested_field": {
+ "level": {
+ "field_name": "string",
+ "value": "string"
+ }
+ },
+ "to_nested_field": {
+ "level": {
+ "field_name": "string",
+ "value": "string"
+ }
+ }
+ }
+ ],
+ "conditions": [
+ {
+ "name": "string",
+ "match_type": "string",
+ "properties": [
+ {
+ "resource_type": "string",
+ "field_name": "string",
+ "operator": "string",
+ "value": "string",
+ "business_hours_id": 0,
+ "case_senstive": true,
+ "nested_fields": {
+ "level": {
+ "field_name": "string",
+ "value": "string"
+ }
+ },
+ "associated_fields": {
+ "field_name": "string",
+ "operator": "string",
+ "value": 0
+ },
+ "related_conditions": [
+ {
+ "field_name": "agent_availability",
+ "operator": "is",
+ "value": "unavailable",
+ "related_conditions": [
+ {
+ "field_name": "out_of_office",
+ "operator": "is",
+ "value": 0
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ],
+ "operator": "string",
+ "actions": [
+ {
+ "field_name": "string",
+ "value": "string",
+ "email_to": 0,
+ "email_body": "string",
+ "api_key": "string",
+ "auth_header": {
+ "username": "string",
+ "password": "string"
+ },
+ "custom_headers": {
+ "value": "string"
+ },
+ "content": {
+ "content_layout": "string",
+ "content_type": "string"
+ },
+ "request_type": "string",
+ "url": "string",
+ "note_body": "string",
+ "notify_agents": [
+ 0
+ ],
+ "nested_fields": {
+ "level": {
+ "value": "string",
+ "field_name": "string"
+ }
+ },
+ "fwd_to": [
+ "string"
+ ],
+ "fwd_cc": "string",
+ "fwd_bcc": "string",
+ "fwd_note_body": "string",
+ "push_to": "string",
+ "slack_text": "string",
+ "office365_text": "string",
+ "resource_type": "same_ticket"
+ }
+ ],
+ "outdated": true,
+ "last_updated_by": 0,
+ "affected_tickets_count": 0,
+ "Summary": {
+ "performer": "string",
+ "events": [
+ "string"
+ ],
+ "conditions": {
+ "condition_set_1": [
+ "string"
+ ],
+ "condition_set_2": [
+ "string"
+ ]
+ },
+ "actions": [
+ "string"
+ ]
+ },
+ "id": 109866,
+ "created_at": "2020-12-14T05:21:27.239Z",
+ "updated_at": "2020-12-14T05:21:27.239Z"
+}
+EXPAND ↓
+Delete an Automation Rule
+delete /api/v2/automations/[automation_type_id]/rules/[id]
+Attribute Type Description
+id
+Mandatory
+integer ID of the automation rule
+automation_type_id
+Mandatory
+Integer Type id of the automation
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/automations/1/rules/109866'
+Response
+HTTP Status: 204 No Content
+Create an Automation Rule
+post /api/v2/automations/[automation_type_id]/rules
+Attribute Type Description
+automation_type_id
+Mandatory
+Integer Type id of the automation
+name
+Mandatory
+string Name of the automation rule
+description string Description of the automation rule
+position integer Position of the automation rule
+active boolean Set to true if the rule is active
+performer
+**Applicable only if automation_type_id is 4**
+
+Array of objects Any event performer (agent, customer or system) whose action triggers the rule
+events
+**Applicable only if automation_type_id is 4**
+
+Array of objects Events that are responsible for triggering the rule
+conditions
+Mandatory
+Array of objects Conditions to check whether the rule can run on a ticket or not
+operator string AND/OR operator to combine multiple conditions in a rule
+actions
+Mandatory
+Array of objects Actions to be performed by the rule on matching tickets
+
+events:
+Field Name Type Description
+field_name string Name of the field
+from string Value of the field before the event
+to string Value of the field after the event
+
+performer:
+Field Name Type Description
+type integer Event performer. Possible values are:
+1- Agent
+2- Requester
+3- Agent or Requester
+4- System
+Members
+**Applicable only if type is 1**
+
+Array of strings IDs of the agents
+
+conditions:
+Field Name Type Description
+name string Title of the condition
+match_type string To check whether all conditions have to be met or atleast one. Possible values are: “all”,”any”
+properties Array of objects Properties of the condition. Objects include:
+1. resource_type(string) - Type of the resource. Possible values are contacts, tickets, companies, custom_object.
+2. field_name(string) - Name of the field
+3. Operator(Boolean)- AND/OR operator to combine multiple conditions in a rule
+4. value(string) - Value set on the selected field
+5. object_reference(string) - Ticket’s look up field value
+
+actions:
+Field Name Type Description
+field_name string The action in an automation rule.Example-send_email_to_requester or add_tag
+value string Value to be set on the field
+email_to integer Send email to specific contact/agent/groups.
+email_body string Content of the email
+api_key string API key to authenticate any HTTP requests
+auth_header auth_header Combination of user name and password to be used for HTTP requests
+custom_headers custom_headers Custom header information for any HTTP request
+request_type string Type of the HTTP request
+url string URL for the HTTP request
+note_body string Content of the note added by the rule
+notify_agents Array of integers IDs of agents to be notified
+Fwd_to
+Fwd_cc
+Fwd_bcc
+fwd_note_body
+string Forward the ticket to an email address
+push_to string Channel through which the message will be sent. Possible options are:
+“Slack”
+“Office365”
+slack_text string Content of the message sent to slack
+office365_text string Content of the message sent to office365
+resource_type string Type of the ticket. Possible values are: “Same_ticket”, ”parent_ticket”, ”tracker_ticket”, ”custom_object”
+object_reference string Ticket’s look up field value
+The following table lists the attributes for each action field:
+Action Field Name Description
+send_email_to_requester Automation action that can send an email to the requester. The attributes action_type, include_to_and_cc, email_subject, email_body are required for this field.
+ATTRIBUTE TYPE DESCRIPTION
+action_type
+Mandatory
+string An email can be sent either as a new email (add_as_new_mail_thread )or as a response (append_in_same_mail_thread)
+include_to_and_cc
+Mandatory
+Boolean Set to true if all users in to and cc receive the email sent by the automation rule
+add_as_private_note
+Mandatory
+Boolean Set to true if the email is added as a private note on the ticket
+email_subject
+Mandatory
+string Subject of the email
+email_body
+Mandatory
+string Description of the email
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name": "Send email to group", "position": 1, "active": true, "performer": { "type": 1, "members": [ 82002117631 ] }, "events": [ { "field_name": "responder_id", "from": "--", "to": 82002117631 } ], "conditions": [ { "name": "condition_set_1", "match_type": "all", "properties": [ { "field_name": "responder_id", "resource_type": "ticket", "operator": "in", "value": [ "" ] } ] } ], "actions": [ { "field_name": "send_email_to_group", "email_to": 82000039290, "email_subject": "Ticket assigned", "email_body": "Ticket has been assigned to agent
" } ] }' 'https://domain.freshdesk.com/api/v2/automations/4/rules'
+Response
+{
+ "name": "Send email to group",
+ "position": 1,
+ "active": true,
+ "outdated": false,
+ "last_updated_by": 82002117631,
+ "id": 82000163682,
+ "summary": {
+ "performer": "When an action performed by Agent
Agent A
",
+ "events": [
+ "When Agent
is changed from ANY
to Agent A
"
+ ],
+ "conditions": {
+ "condition_set_1": [
+ "If Agent
is
NONE
"
+ ]
+ },
+ "actions": [
+ " Send Email to Group
Account managers
"
+ ]
+ },
+ "created_at": "2020-12-14T11:18:11Z",
+ "updated_at": "2020-12-14T11:18:11Z",
+ "affected_tickets_count": null,
+ "performer": {
+ "type": 1,
+ "members": [
+ 82002117631
+ ]
+ },
+ "events": [
+ {
+ "field_name": "responder_id",
+ "from": "--",
+ "to": 82002117631
+ }
+ ],
+ "conditions": [
+ {
+ "name": "condition_set_1",
+ "match_type": "all",
+ "properties": [
+ {
+ "field_name": "responder_id",
+ "resource_type": "ticket",
+ "operator": "in",
+ "value": [
+ ""
+ ]
+ }
+ ]
+ }
+ ],
+ "actions": [
+ {
+ "field_name": "send_email_to_group",
+ "email_to": 82000039290,
+ "email_subject": "Ticket assigned to agent",
+ "email_body": "Ticket has been assigned to agent
"
+ }
+ ],
+ "meta": {
+ "total_active_count": 3,
+ "total_count": 3
+ }
+}
+EXPAND ↓
+Update an Automation Rule
+put /api/v2/automations/[automation_type_id]/rules/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name": "Send email to agent", "position": 1, "active": true, "performer": { "type": 1, "members": [ 82002117631 ] }, "events": [ { "field_name": "responder_id", "from": "--", "to": 82002117631 } ], "conditions": [ { "name": "condition_set_1", "match_type": "all", "properties": [ { "field_name": "responder_id", "resource_type": "ticket", "operator": "in", "value": [ "" ] } ] } ], "actions": [ { "field_name": "send_email_to_agent", "email_to": 82000039290, "email_subject": "Ticket assigned to you", "email_body": "Ticket has been assigned to you. Please respond within the SLA
" } ] }' 'https://domain.freshdesk.com/api/v2/automations/4/rules/82000163682'
+EXPAND ↓
+Response
+{
+ "name": "Send email to agent",
+ "position": 1,
+ "active": true,
+ "outdated": false,
+ "last_updated_by": 82002117631,
+ "id": 82000163682,
+ "summary": {
+ "performer": "When an action performed by Agent
Agent A
",
+ "events": [
+ "When Agent
is changed from ANY
to Agent A
"
+ ],
+ "conditions": {
+ "condition_set_1": [
+ "If Agent
is
NONE
"
+ ]
+ },
+ "actions": [
+ " Send Email to Agent
Agent A
"
+ ]
+ },
+ "created_at": "2020-12-14T11:18:11Z",
+ "updated_at": "2020-12-14T11:18:11Z",
+ "affected_tickets_count": null,
+ "performer": {
+ "type": 1,
+ "members": [
+ 82002117631
+ ]
+ },
+ "events": [
+ {
+ "field_name": "responder_id",
+ "from": "--",
+ "to": 82002117631
+ }
+ ],
+ "conditions": [
+ {
+ "name": "condition_set_1",
+ "match_type": "all",
+ "properties": [
+ {
+ "field_name": "responder_id",
+ "resource_type": "ticket",
+ "operator": "in",
+ "value": [
+ ""
+ ]
+ }
+ ]
+ }
+ ],
+ "actions": [
+ {
+ "field_name": "send_email_to_agent",
+ "email_to": 82000039290,
+ "email_subject": "Ticket assigned to you",
+ "email_body": "Ticket has been assigned to you. Please respond within SLA
"
+ }
+ ],
+ "meta": {
+ "total_active_count": 3,
+ "total_count": 3
+ }
+}
+EXPAND ↓
+Settings
+Settings are configured through the Admin page of the Freshdesk web app.
+
+View Helpdesk Settings
+get /api/v2/settings/helpdesk
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/settings/helpdesk'
+Response
+{
+ "primary_language": "en",
+ "supported_languages": ["ru-RU", "es"],
+ "portal_languages": ["ru-RU"]
+}
+Threads
+Note: Access to the following APIs is restricted to users with admin privileges..
+
+To create a new thread type, we utilize the following APIs. Our system distinguishes between two entities: threads and thread messages. When dealing with existing threads, we can create thread messages. Therefore, some APIs are designed to manage threads, while others are specifically tailored to handle thread messages.
+
+JSON Parameters
+Parameters Description
+id It refers to the thread ID
+type what type of thread it is whether a forward, discussion or private thread
+title title given to the specific thread ex:abc thread
+created_by it referes to who has created that thread
+parent It refers to the parent ticket in which the thread is created under which we have parent_id and type as ticket
+anchor we can create a thread from a note of a ticket
+participants the one who is involved in sending the messages.
+additional_info It can be anything like email_config_id i.e from there the actual email has come from , if the quoted text is present or not etc.
+Create a thread
+post api/v2/collaboration/threads
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "type":"forward","parent":{"id":"156","type":"ticket"},"additional_info":{"email_config_id":1060000012850} }' 'https://domain.freshdesk.com/api/v2/collaboration/threads'
+Response
+[
+ {
+ "id": "28",
+ "type": "forward",
+ "title": null,
+ "created_by": "1060000",
+ "parent": {
+ "id": "156",
+ "type": "ticket"
+ },
+ "anchor": null,
+ "participants": {
+ "emails": null,
+ "agents": [
+ "1060000697424"
+ ]
+ },
+ "linked_object": {
+ "id": "28",
+ "type": "thread-messages",
+ "attributes": {
+ "last_activity_at": null,
+ "message_count": "0"
+ },
+ "links": {
+ "self": {
+ "href": "www.example.com",
+ "method": "GET",
+ "rel": "self"
+ }
+ }
+ },
+ "created_at": "2023-09-25T17:23:25Z",
+ "updated_at": "2023-09-25T17:23:25Z",
+ "additional_info": {
+ "email_config_id": "10600000"
+ },
+ "is_read": true,
+ "updated_by": "1060000697424"
+ }
+}
+ ]
+EXPAND ↓
+Get a thread
+get api/v2/collaboration/threads/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/collaboration/threads/2'
+Response
+{
+ {
+ "id": "147",
+ "type": "private",
+ "title": "Private thread created by XYZ",
+ "created_by": "925928",
+ "parent": {
+ "id": "227",
+ "type": "ticket"
+ },
+ "anchor": {
+ "id": "22709",
+ "type": "conversation"
+ },
+ "participants": {
+ "emails": [
+ "example@email.com",
+ "example2@email.com"
+ ],
+ "agents": [
+ "8809",
+ "8786"
+ ]
+ },
+ "linked_object": {
+ "id": "147",
+ "type": "thread-messages",
+ "attributes": {
+ "message_count": 17,
+ "last_activity_at": "2020-12-02T20:20:20Z",
+ "additionalProp1": "low",
+ "additionalProp2": "low",
+ "additionalProp3": "low"
+ },
+ "links": {
+ "self": {
+ "href": "www.example.com",
+ "method": "GET",
+ "rel": "agent"
+ }
+ }
+ },
+ "created_at": "2020-11-20T20:20:20Z",
+ "updated_at": "2020-12-02T20:20:20Z",
+ "additional_info": {
+ "email_config_id": "1"
+ },
+ "is_read": true,
+ "updated_by": "925928"
+ }
+
+ ]
+ }
+EXPAND ↓
+Update a thread
+put api/v2/collaboration/threads/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "title": "Updated returns form", "description": "New returns form for summer sale" }' 'https://domain.freshdesk.com/api/v2/collaboration/threads/2'
+Response
+{
+ "title": "Private thread created by XYZ",
+ "linked_object": {
+ "id": "147",
+ "attributes": {
+ "additionalProp1": "low",
+ "additionalProp2": "low",
+ "additionalProp3": "low"
+ },
+ "links": {
+ "self": {
+ "href": "www.example.com",
+ "method": "GET",
+ "rel": "agent"
+ }
+ }
+ }
+ }
+EXPAND ↓
+Delete a thread
+delete api/v2/collaboration/threads/[id]
+Note: Deleting a thread is an irreversible action! Once deleted, it cannot be restored. Please use caution when proceeding with this action.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/collaboration/threads/2'
+Response
+HTTP Status: 204 No Content
+Thread messages
+Note: Access to the following APIs is restricted to users with admin privileges.
+
+For creating replies or adding a new message for already created thread.
+
+JSON Parameters
+Parameters Description
+body Content of the note in HTML format
+body_text Content of the note in plan text format
+attachment_ids IDs of attachments to be added to the reply
+inline_attachment_ids IDs of inline attachments to be added to the reply
+full_message HTML content with original and quoted text included
+full_message_text Plain text that contains just the quoted text
+Create message for thread
+post api/v2/collaboration/messages
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body": "", "participants": { "email": { "to": [ "test@gmail.com" ] } }, "additional_info": { "has_quoted_text": true, "email_subject": "Fwd: " }, "thread_id": "24", "attachment_ids": [] }' 'https://domain.freshdesk.com/api/v2/collaboration/messages'
+Response
+{
+ "id": "40",
+ "body": "",
+ "body_text": "test",
+ "thread_id": "24",
+ "created_by": "1060000697424",
+ "created_at": "2023-09-25T12:39:39Z",
+ "updated_at": "2023-09-25T12:39:39Z",
+ "attachment_ids": [],
+ "inline_attachment_ids": null,
+ "participants": {
+ "email": {
+ "from": null,
+ "to": [
+ "test@gmail.com"
+ ],
+ "cc": null,
+ "bcc": null
+ },
+ "tagged_users": null
+ },
+ "edited": false,
+ "source": 1,
+ "additional_info": {
+ "skip_notification": false,
+ "auto_response": false,
+ "number_of_failed_emails": null,
+ "has_quoted_text": true,
+ "failed_emails_info": null,
+ "email_subject": "Fwd: "
+ },
+ "full_message": " On Mon, 25 Sep at 12:21 PM , freshworks<support@freshworks8249.freshdesk.com> wrote: \n\nOn Mon, 25 Sep at 12:00 PM , freshworks<support@freshworks8249.freshdesk.com> wrote: \nOn Mon, 25 Sep at 8:58 AM , freshworks<support@freshworks8249.freshdesk.com> wrote: Please take a look at ticket
#156 raised by Test (test@gmail.com).
On Mon, 25 Sep at 4:18 AM , Test <test@gmail.com> wrote:\n
Test
\n
\nThanks & regards,
Account administrator,
FW company,
phone-no:1234567890
",
+ "body_text": "Test Thanks & regards, Account administrator, FW company, phone-no:1234567890",
+ "thread_id": "18",
+ "created_by": "1060000697424",
+ "created_at": "2023-08-29T05:06:14Z",
+ "updated_at": "2023-08-29T05:06:19Z",
+ "attachment_ids": [],
+ "inline_attachment_ids": null,
+ "participants": {
+ "email": {
+ "from": null,
+ "to": [
+ "test@gmail.com"
+ ],
+ "cc": null,
+ "bcc": null
+ },
+ "tagged_users": null
+ },
+ "edited": true,
+ "source": 1,
+ "additional_info": {
+ "skip_notification": false,
+ "auto_response": false,
+ "number_of_failed_emails": 1,
+ "has_quoted_text": true,
+ "failed_emails_info": [
+ {
+ "email": "test@gmail.com",
+ "type": "invalid_email_dropped",
+ "field": "To"
+ }
+ ],
+ "email_subject": "Fwd: "
+ }
+EXPAND ↓
+Update message for thread
+put api/v2/collaboration/messages/[id]
+Sample code | Curl
+curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "title": "Updated returns form", "description": "New returns form for summer sale" }' 'https://domain.freshdesk.com/api/v2/collaboration/messages/2'
+Response
+{
+ "body": 'abc',
+ "attachment_ids": [
+ "9875",
+ "9876"
+ ],
+ "inline_attachment_ids": [
+ "98753",
+ "98763"
+ ],
+ "additional_info": {
+ "skip_notification": false,
+ "auto_response": false,
+ "number_of_failed_emails": 3,
+ "failed_emails_info": [
+ {
+ "email": "example@mail.com",
+ "type": "bounce_permanent",
+ "field": "to, cc, bcc"
+ }
+ ]
+ }
+EXPAND ↓
+Delete message for thread
+delete api/v2/collaboration/messages/[id]
+Note: Deleting messages from a thread is an irreversible action! Once deleted, it cannot be restored. Please use caution when proceeding with this action.
+
+Sample code | Curl
+curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/collaboration/messages/2'
+Response
+HTTP Status: 204 No Content
+Get quoted text for message
+get api/v2/collaboration/messages/[id]/generate-quote
+Sample code | Curl
+curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/collaboration/messages/{id}/generate-quote'
+Response
+{
+ "quoted_text": " On Tue, 29 Jun at 8:31 AM , test test <test.test@test.com> wrote:test ticket
\\n
\\n\\n\\n
\\n
"
+}
diff --git a/FRESHDESK_API_REFERENCE.md b/FRESHDESK_API_REFERENCE.md
new file mode 100644
index 0000000..7a0d735
--- /dev/null
+++ b/FRESHDESK_API_REFERENCE.md
@@ -0,0 +1,177 @@
+# Freshdesk API v2 Reference
+
+## General Pagination Rules
+
+- Default: 30 objects per page
+- Max per_page: 100
+- Use `page` parameter to paginate (starts at 1)
+- Link header contains next page URL
+- **Deep pagination warning**: Avoid page numbers over 500 - extremely slow response times
+
+## Autocomplete API Limitations
+
+All autocomplete endpoints (`/autocomplete`) have these limitations:
+- Returns LIMITED results (not paginated, typically ~10-20 matches)
+- Searches by PREFIX only (case insensitive)
+- Cannot search with substrings: "John" works, "ohn" does NOT
+- Returns minimal fields (usually just id and name)
+
+## Tickets API
+
+### GET /api/v2/tickets (List Tickets)
+
+**CRITICAL: 30-day default limit** - Only tickets created in past 30 days returned by default.
+Use `updated_since` for older tickets.
+
+Parameters:
+- `filter`: 'new_and_my_open', 'watching', 'spam', 'deleted'
+- `requester_id`: Filter by requester
+- `email`: Filter by requester email
+- `company_id`: Filter by company
+- `updated_since`: ISO 8601 timestamp (e.g., '2024-01-01T00:00:00Z')
+- `order_by`: 'created_at', 'due_by', 'updated_at', 'status'
+- `order_type`: 'asc' or 'desc' (default: desc)
+- `include`: 'stats', 'requester', 'description', 'company' (costs +1 API credit each)
+- `page`: Page number (default: 1)
+- `per_page`: Results per page (1-100, default: 30)
+
+Limits:
+- Max 300 pages (30,000 tickets)
+- Description requires `include=description` for accounts created after 2018-11-30
+
+### GET /api/v2/search/tickets (Filter/Search Tickets)
+
+**Query string max: 512 characters**
+**Max results: 300 (30 per page × 10 pages)**
+
+Supported query fields:
+- status, priority, group_id, requester_id, type, tag
+- created_at, updated_at, due_by (with :> and :< operators)
+- Custom fields with cf_ prefix
+
+NOT supported: company_id, description, subject, responder_id
+
+### GET /api/v2/tickets/{id}
+
+Parameters:
+- `include`: 'stats', 'conversations', 'requester', 'company'
+
+**CRITICAL LIMITATION for include=conversations:**
+- Returns only the **OLDEST 10 conversations**, sorted by created_at ascending
+- This is NOT the full history - use GET /api/v2/tickets/{id}/conversations for complete data
+
+## Conversations API
+
+### GET /api/v2/tickets/{id}/conversations
+
+Lists ALL conversations (notes, replies) for a ticket with pagination.
+
+Parameters:
+- `page`: Page number (default: 1)
+- `per_page`: Results per page (1-100, default: 30)
+
+Returns: Array of conversation objects containing:
+- `id`: Conversation ID
+- `body`: HTML body
+- `body_text`: Plain text body
+- `incoming`: Boolean, true if from customer
+- `private`: Boolean, true if private note
+- `user_id`: ID of user who created it
+- `support_email`: Support email used
+- `source`: Source type (0=Reply, 2=Note, etc.)
+- `to_emails`, `from_email`, `cc_emails`, `bcc_emails`: Email addresses
+- `created_at`, `updated_at`: Timestamps
+- `attachments`: Array of attachment objects
+- `ticket_id`: Parent ticket ID
+
+Pagination: Standard Link header pagination. Use page parameter to iterate.
+
+## Contacts API
+
+### GET /api/v2/contacts
+
+Filter parameters:
+- `email`: Filter by email
+- `mobile`: Filter by mobile
+- `phone`: Filter by phone
+- `state`: 'blocked', 'deleted', 'unverified', 'verified'
+- `company_id`: Filter by company
+- `_updated_since`: ISO 8601 timestamp
+
+Pagination: page, per_page (max 100)
+
+### GET /api/v2/search/contacts
+
+Query max: 512 characters
+Max results: 300 (30 per page × 10 pages)
+
+### GET /api/v2/contacts/autocomplete
+
+Parameter: `term` - search term for autocomplete
+
+## Companies API
+
+### GET /api/v2/companies
+
+Pagination: page, per_page (max 100)
+
+### GET /api/v2/search/companies
+
+Query max: 512 characters
+Max results: 300 (30 per page × 10 pages)
+
+### GET /api/v2/companies/autocomplete
+
+Parameter: `name` - company name to search
+
+## Agents API
+
+### GET /api/v2/agents
+
+Filter parameters:
+- `email`: Filter by email
+- `mobile`: Filter by mobile
+- `phone`: Filter by phone
+- `state`: Filter by state
+
+Pagination: page, per_page (max 100)
+
+### GET /api/v2/agents/autocomplete
+
+Parameter: `term` - search term
+
+## Groups API
+
+### GET /api/v2/groups
+
+Pagination: page, per_page (max 100)
+
+## Solutions API
+
+### Categories: GET /api/v2/solutions/categories
+No pagination - returns all
+
+### Folders: GET /api/v2/solutions/categories/{id}/folders
+No pagination - returns all in category
+
+### Articles: GET /api/v2/solutions/folders/{id}/articles
+No pagination - returns all in folder
+
+### Search: GET /api/v2/search/solutions?term={keyword}
+
+## Canned Responses API
+
+### GET /api/v2/canned_response_folders
+Returns all folders
+
+### GET /api/v2/canned_response_folders/{id}/responses
+Returns all responses in folder
+
+## Error Codes
+
+- 400: Bad Request (validation error)
+- 401: Unauthorized (invalid API key)
+- 403: Access Denied (insufficient permissions)
+- 404: Not Found
+- 429: Rate Limited (check Retry-After header)
+- 5xx: Server Error
diff --git a/src/freshdesk_mcp/server.py b/src/freshdesk_mcp/server.py
index 3749091..a136197 100755
--- a/src/freshdesk_mcp/server.py
+++ b/src/freshdesk_mcp/server.py
@@ -163,7 +163,14 @@ class CannedResponseCreate(BaseModel):
@mcp.tool()
async def get_ticket_fields() -> Dict[str, Any]:
- """Get ticket fields from Freshdesk."""
+ """Get all ticket fields from Freshdesk.
+
+ Returns the list of ticket fields including custom fields.
+ Use this to discover field names, types, and valid values for filtering and creating tickets.
+
+ Returns:
+ List of field definitions with name, label, type, and choices (for dropdowns)
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/ticket_fields"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
@@ -174,8 +181,46 @@ async def get_ticket_fields() -> Dict[str, Any]:
@mcp.tool()
-async def get_tickets(page: Optional[int] = 1, per_page: Optional[int] = 30) -> Dict[str, Any]:
- """Get tickets from Freshdesk with pagination support."""
+async def get_tickets(
+ company_id: Optional[int] = None,
+ requester_id: Optional[int] = None,
+ email: Optional[str] = None,
+ updated_since: Optional[str] = None,
+ filter: Optional[str] = None,
+ include: Optional[str] = None,
+ order_by: Optional[str] = None,
+ order_type: Optional[str] = None,
+ page: Optional[int] = 1,
+ per_page: Optional[int] = 30
+) -> Dict[str, Any]:
+ """Get tickets from Freshdesk with filtering and pagination support.
+
+ CRITICAL: By default, only tickets created in the past 30 DAYS are returned!
+ To get older tickets, you MUST use the updated_since parameter.
+
+ This endpoint supports filtering by company_id, requester_id, email, etc.
+ For query-based filtering (status, priority, tags, etc.), use search_tickets instead.
+
+ Args:
+ company_id: Filter tickets by company ID (use this instead of search_tickets for company filtering)
+ requester_id: Filter tickets by requester ID
+ email: Filter tickets by requester email (must be URL encoded if contains special chars)
+ updated_since: ISO 8601 timestamp (e.g. '2024-01-01T00:00:00Z'). REQUIRED for tickets older than 30 days!
+ filter: Predefined filter ('new_and_my_open', 'watching', 'spam', 'deleted')
+ include: Embed additional data: 'stats', 'requester', 'company', 'description' (comma-separated, each costs +1 API credit). Note: 'description' is REQUIRED for accounts created after 2018-11-30.
+ order_by: Sort field ('created_at', 'due_by', 'updated_at', 'status')
+ order_type: Sort order ('asc' or 'desc', default: 'desc')
+ page: Page number (default: 1)
+ per_page: Results per page (1-100, default: 30)
+
+ Returns:
+ Dict with tickets array and pagination info
+
+ Limitations:
+ - Max 300 pages (30,000 tickets total)
+ - Default returns only last 30 days of tickets
+ - Deleted/spam tickets excluded unless using those filters
+ """
# Validate input parameters
if page < 1:
return {"error": "Page number must be greater than 0"}
@@ -185,11 +230,29 @@ async def get_tickets(page: Optional[int] = 1, per_page: Optional[int] = 30) ->
url = f"https://{FRESHDESK_DOMAIN}/api/v2/tickets"
+ # Build params dynamically, only including non-None values
params = {
"page": page,
"per_page": per_page
}
+ if company_id is not None:
+ params["company_id"] = company_id
+ if requester_id is not None:
+ params["requester_id"] = requester_id
+ if email is not None:
+ params["email"] = email
+ if updated_since is not None:
+ params["updated_since"] = updated_since
+ if filter is not None:
+ params["filter"] = filter
+ if include is not None:
+ params["include"] = include
+ if order_by is not None:
+ params["order_by"] = order_by
+ if order_type is not None:
+ params["order_type"] = order_type
+
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}",
"Content-Type": "application/json"
@@ -359,7 +422,16 @@ async def update_ticket(ticket_id: int, ticket_fields: Dict[str, Any]) -> Dict[s
@mcp.tool()
async def delete_ticket(ticket_id: int) -> str:
- """Delete a ticket in Freshdesk."""
+ """Delete a ticket in Freshdesk.
+
+ WARNING: This permanently deletes the ticket. Use with caution.
+
+ Args:
+ ticket_id: The ID of the ticket to delete
+
+ Returns:
+ Empty response on success, error details on failure
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/tickets/{ticket_id}"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
@@ -369,39 +441,135 @@ async def delete_ticket(ticket_id: int) -> str:
return response.json()
@mcp.tool()
-async def get_ticket(ticket_id: int):
- """Get a ticket in Freshdesk."""
+async def get_ticket(ticket_id: int, include: Optional[str] = None):
+ """Get a single ticket by ID from Freshdesk.
+
+ Args:
+ ticket_id: The ID of the ticket to retrieve
+ include: Embed additional data (comma-separated): 'stats', 'conversations', 'requester', 'company'.
+ Each inclusion costs +1 API credit.
+
+ CRITICAL LIMITATION for 'conversations':
+ When include='conversations', only the OLDEST 10 conversations are returned,
+ sorted by created_at ascending. This is NOT the full conversation history!
+ To get ALL conversations, use get_ticket_conversation(ticket_id) instead,
+ which auto-paginates and returns the complete history.
+
+ Returns:
+ Ticket object with all fields. Use include parameter for embedded related data.
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/tickets/{ticket_id}"
+ params = {}
+ if include is not None:
+ params["include"] = include
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
}
async with httpx.AsyncClient() as client:
- response = await client.get(url, headers=headers)
+ response = await client.get(url, headers=headers, params=params if params else None)
return response.json()
@mcp.tool()
async def search_tickets(query: str) -> Dict[str, Any]:
- """Search for tickets in Freshdesk."""
+ """Search for tickets in Freshdesk using the Filter Tickets API.
+
+ IMPORTANT: This API has strict limitations on searchable fields.
+
+ Supported fields in query:
+ - agent_id: e.g. "agent_id:123"
+ - group_id: e.g. "group_id:11"
+ - priority: e.g. "priority:3" or "priority:>3" (1=Low, 2=Medium, 3=High, 4=Urgent)
+ - status: e.g. "status:2" (2=Open, 3=Pending, 4=Resolved, 5=Closed)
+ - tag: e.g. "tag:'billing'"
+ - type: e.g. "type:'Incident'"
+ - due_by: e.g. "due_by:>'2024-01-01'" (date format: 'YYYY-MM-DD')
+ - fr_due_by: e.g. "fr_due_by:<'2024-06-01'" (first response due by)
+ - created_at: e.g. "created_at:>'2024-01-01'" (date format: 'YYYY-MM-DD')
+ - updated_at: e.g. "updated_at:<'2024-06-01'" (date format: 'YYYY-MM-DD')
+ - Custom fields: e.g. "cf_fieldname:'value'" (use cf_ prefix)
+
+ NOT supported (will return 400 "Validation failed" error):
+ - requester_id: Use get_tickets(requester_id=...) instead
+ - company_id: Use get_tickets(company_id=...) instead
+ - description, subject: Not searchable
+ - responder_id: Not filterable
+
+ Query syntax:
+ - Do NOT wrap in double quotes - it will be done automatically
+ - Max 512 characters
+ - Operators: AND, OR, (), :> (>=), :< (<=)
+ - Dates MUST be in 'YYYY-MM-DD' format with single quotes
+
+ Args:
+ query: Search query string (e.g. "priority:>3 AND status:2")
+ Do NOT wrap in double quotes - handled automatically.
+
+ Returns:
+ Dict with matching tickets (max 300 results across 10 pages)
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/search/tickets"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
}
- params = {"query": query}
+ # Freshdesk API requires query to be wrapped in double quotes
+ # Strip any existing quotes and re-wrap to ensure correct format
+ clean_query = query.strip('"')
+ params = {"query": f'"{clean_query}"'}
async with httpx.AsyncClient() as client:
response = await client.get(url, headers=headers, params=params)
return response.json()
@mcp.tool()
-async def get_ticket_conversation(ticket_id: int)-> list[Dict[str, Any]]:
- """Get a ticket conversation in Freshdesk."""
+async def get_ticket_conversation(ticket_id: int) -> list[Dict[str, Any]]:
+ """Get ALL conversations for a ticket in Freshdesk.
+
+ This function automatically paginates through all pages to return the complete
+ conversation history. Conversations are returned sorted by created_at ascending
+ (oldest first).
+
+ Freshdesk API Behavior:
+ - Default page size: 30 conversations per page
+ - Max per_page: 100 (used here to minimize API calls)
+ - This function fetches ALL pages automatically
+
+ Args:
+ ticket_id: The ID of the ticket to get conversations for.
+
+ Returns:
+ list[Dict[str, Any]]: Complete list of all conversations for the ticket.
+ Each conversation includes: id, body, body_text, incoming, private,
+ user_id, support_email, to_emails, from_email, cc_emails, bcc_emails,
+ created_at, updated_at, attachments, source, ticket_id, etc.
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/tickets/{ticket_id}/conversations"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
}
+
+ all_conversations: list[Dict[str, Any]] = []
+ page = 1
+ per_page = 100 # Use max to minimize API calls
+
async with httpx.AsyncClient() as client:
- response = await client.get(url, headers=headers)
- return response.json()
+ while True:
+ params = {"page": page, "per_page": per_page}
+ response = await client.get(url, headers=headers, params=params)
+ conversations = response.json()
+
+ # Handle error responses or empty results
+ if not conversations or not isinstance(conversations, list):
+ break
+
+ all_conversations.extend(conversations)
+
+ # If we got fewer than requested, we've reached the end
+ if len(conversations) < per_page:
+ break
+
+ page += 1
+
+ return all_conversations
@mcp.tool()
async def create_ticket_reply(ticket_id: int,body: str)-> Dict[str, Any]:
@@ -450,8 +618,36 @@ async def update_ticket_conversation(conversation_id: int,body: str)-> Dict[str,
return f"Cannot update conversation ${response.json()}"
@mcp.tool()
-async def get_agents(page: Optional[int] = 1, per_page: Optional[int] = 30)-> list[Dict[str, Any]]:
- """Get all agents in Freshdesk with pagination support."""
+async def get_agents(
+ email: Optional[str] = None,
+ mobile: Optional[str] = None,
+ phone: Optional[str] = None,
+ state: Optional[str] = None,
+ page: Optional[int] = 1,
+ per_page: Optional[int] = 30
+) -> list[Dict[str, Any]]:
+ """List agents in Freshdesk with optional filtering and pagination.
+
+ Pagination:
+ - Default: 30 agents per page
+ - Max per_page: 100
+ - Use page parameter to iterate through results
+ - Check if returned count < per_page to detect last page
+
+ Args:
+ email: Filter by exact agent email (unique, returns one agent)
+ mobile: Filter by mobile number
+ phone: Filter by phone number
+ state: Filter by state ('fulltime', 'occasional')
+ page: Page number (default: 1)
+ per_page: Results per page (1-100, default: 30)
+
+ Returns:
+ List of agent objects. Each agent includes:
+ - id, available, occasional, signature, ticket_scope
+ - contact: nested object with email, name, phone, mobile, language, time_zone
+ - group_ids, role_ids, skill_ids, focus_mode
+ """
# Validate input parameters
if page < 1:
return {"error": "Page number must be greater than 0"}
@@ -466,13 +662,56 @@ async def get_agents(page: Optional[int] = 1, per_page: Optional[int] = 30)-> li
"page": page,
"per_page": per_page
}
+ if email is not None:
+ params["email"] = email
+ if mobile is not None:
+ params["mobile"] = mobile
+ if phone is not None:
+ params["phone"] = phone
+ if state is not None:
+ params["state"] = state
async with httpx.AsyncClient() as client:
response = await client.get(url, headers=headers, params=params)
return response.json()
@mcp.tool()
-async def list_contacts(page: Optional[int] = 1, per_page: Optional[int] = 30)-> list[Dict[str, Any]]:
- """List all contacts in Freshdesk with pagination support."""
+async def list_contacts(
+ email: Optional[str] = None,
+ mobile: Optional[str] = None,
+ phone: Optional[str] = None,
+ company_id: Optional[int] = None,
+ state: Optional[str] = None,
+ updated_since: Optional[str] = None,
+ page: Optional[int] = 1,
+ per_page: Optional[int] = 30
+) -> list[Dict[str, Any]]:
+ """List contacts in Freshdesk with optional filtering and pagination.
+
+ Pagination:
+ - Default: 30 contacts per page
+ - Max per_page: 100
+ - Use page parameter to iterate through results
+ - Check if returned count < per_page to detect last page
+
+ By default, only unblocked and undeleted contacts are returned.
+
+ Args:
+ email: Filter by exact email address (unique, returns one contact)
+ mobile: Filter by mobile number
+ phone: Filter by phone number
+ company_id: Filter by company ID (get all contacts in a company)
+ state: Filter by state ('blocked', 'deleted', 'unverified', 'verified')
+ updated_since: ISO 8601 timestamp (e.g. '2024-01-01T00:00:00Z')
+ page: Page number (default: 1)
+ per_page: Results per page (1-100, default: 30)
+
+ Returns:
+ List of contact objects. Each contact includes:
+ - id, name, email, phone, mobile, address, description
+ - company_id, active, job_title, language, time_zone
+ - twitter_id, other_companies, custom_fields
+ - created_at, updated_at
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/contacts"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
@@ -481,13 +720,32 @@ async def list_contacts(page: Optional[int] = 1, per_page: Optional[int] = 30)->
"page": page,
"per_page": per_page
}
+ if email is not None:
+ params["email"] = email
+ if mobile is not None:
+ params["mobile"] = mobile
+ if phone is not None:
+ params["phone"] = phone
+ if company_id is not None:
+ params["company_id"] = company_id
+ if state is not None:
+ params["state"] = state
+ if updated_since is not None:
+ params["_updated_since"] = updated_since
async with httpx.AsyncClient() as client:
response = await client.get(url, headers=headers, params=params)
return response.json()
@mcp.tool()
-async def get_contact(contact_id: int)-> Dict[str, Any]:
- """Get a contact in Freshdesk."""
+async def get_contact(contact_id: int) -> Dict[str, Any]:
+ """Get a single contact by ID from Freshdesk.
+
+ Args:
+ contact_id: The ID of the contact to retrieve
+
+ Returns:
+ Contact object with all fields including custom fields
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/contacts/{contact_id}"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
@@ -497,8 +755,25 @@ async def get_contact(contact_id: int)-> Dict[str, Any]:
return response.json()
@mcp.tool()
-async def search_contacts(query: str)-> list[Dict[str, Any]]:
- """Search for contacts in Freshdesk."""
+async def search_contacts(query: str) -> list[Dict[str, Any]]:
+ """Search for contacts using autocomplete in Freshdesk.
+
+ LIMITATIONS:
+ - This uses the autocomplete API which returns LIMITED results (not paginated)
+ - Searches by name prefix only (case insensitive)
+ - Cannot search with substrings: "John" works, "ohn" does NOT
+ - Returns only id and name fields
+
+ For comprehensive contact retrieval:
+ - Use list_contacts() with email parameter for exact email lookup
+ - Use list_contacts(company_id=X) to get all contacts in a company
+
+ Args:
+ query: Search term (name prefix, e.g. "John" matches "John Smith")
+
+ Returns:
+ List of matching contacts with id and name only (limited results)
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/contacts/autocomplete"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
@@ -509,8 +784,16 @@ async def search_contacts(query: str)-> list[Dict[str, Any]]:
return response.json()
@mcp.tool()
-async def update_contact(contact_id: int, contact_fields: Dict[str, Any])-> Dict[str, Any]:
- """Update a contact in Freshdesk."""
+async def update_contact(contact_id: int, contact_fields: Dict[str, Any]) -> Dict[str, Any]:
+ """Update a contact in Freshdesk.
+
+ Args:
+ contact_id: The ID of the contact to update
+ contact_fields: Dict of fields to update (e.g., {'name': 'New Name', 'email': 'new@email.com'})
+
+ Returns:
+ Updated contact object
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/contacts/{contact_id}"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
@@ -815,7 +1098,24 @@ async def update_agent(agent_id: int, agent_fields: Dict[str, Any]) -> Dict[str,
@mcp.tool()
async def search_agents(query: str) -> list[Dict[str, Any]]:
- """Search for agents in Freshdesk."""
+ """Search for agents using autocomplete in Freshdesk.
+
+ LIMITATIONS:
+ - This uses the autocomplete API which returns LIMITED results (not paginated)
+ - Searches by name or email prefix (case insensitive)
+ - Cannot search with substrings: "John" works, "ohn" does NOT
+ - Returns only basic agent info
+
+ For comprehensive agent retrieval:
+ - Use get_agents() with email parameter for exact email lookup
+ - Use get_agents() with pagination to list all agents
+
+ Args:
+ query: Search term (name/email prefix)
+
+ Returns:
+ List of matching agents (limited results)
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/agents/autocomplete?term={query}"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
@@ -825,7 +1125,24 @@ async def search_agents(query: str) -> list[Dict[str, Any]]:
return response.json()
@mcp.tool()
async def list_groups(page: Optional[int] = 1, per_page: Optional[int] = 30)-> list[Dict[str, Any]]:
- """List all groups in Freshdesk."""
+ """List all groups in Freshdesk with pagination.
+
+ Pagination:
+ - Default: 30 groups per page
+ - Max per_page: 100
+ - Use page parameter to iterate through results
+ - Check if returned count < per_page to detect last page
+
+ Args:
+ page: Page number (default: 1)
+ per_page: Results per page (1-100, default: 30)
+
+ Returns:
+ List of group objects. Each group includes:
+ - id, name, description, business_hour_id
+ - escalate_to, unassigned_for, agent_ids
+ - created_at, updated_at
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/groups"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}"
@@ -1055,7 +1372,29 @@ def create_reply(
@mcp.tool()
async def list_companies(page: Optional[int] = 1, per_page: Optional[int] = 30) -> Dict[str, Any]:
- """List all companies in Freshdesk with pagination support."""
+ """List all companies in Freshdesk with pagination support.
+
+ Pagination:
+ - Default: 30 companies per page
+ - Max per_page: 100
+ - Use page parameter to iterate through results
+ - Response includes pagination info with next_page/prev_page
+
+ Args:
+ page: Page number (default: 1)
+ per_page: Results per page (1-100, default: 30)
+
+ Returns:
+ Dict with:
+ - companies: Array of company objects
+ - pagination: {current_page, next_page, prev_page, per_page}
+
+ Each company includes:
+ - id, name, description, domains, note
+ - health_score, account_tier, renewal_date, industry
+ - custom_fields (including premium_support, plan, etc.)
+ - created_at, updated_at
+ """
# Validate input parameters
if page < 1:
return {"error": "Page number must be greater than 0"}
@@ -1103,7 +1442,14 @@ async def list_companies(page: Optional[int] = 1, per_page: Optional[int] = 30)
@mcp.tool()
async def view_company(company_id: int) -> Dict[str, Any]:
- """Get a company in Freshdesk."""
+ """Get a single company by ID from Freshdesk.
+
+ Args:
+ company_id: The ID of the company to retrieve
+
+ Returns:
+ Company object with all fields including custom fields
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/companies/{company_id}"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}",
@@ -1122,7 +1468,24 @@ async def view_company(company_id: int) -> Dict[str, Any]:
@mcp.tool()
async def search_companies(query: str) -> Dict[str, Any]:
- """Search for companies in Freshdesk."""
+ """Search for companies by name using autocomplete in Freshdesk.
+
+ LIMITATIONS:
+ - This uses the autocomplete API which returns LIMITED results (not paginated)
+ - Searches by company name prefix only (case insensitive)
+ - Cannot search with substrings: "Acme" works, "cme" does NOT
+ - Returns only id and name fields
+
+ For comprehensive company retrieval:
+ - Use list_companies() with pagination to list all companies
+ - Use view_company(company_id) for full company details
+
+ Args:
+ query: Company name prefix to search for (e.g. "Acme" matches "Acme Inc.")
+
+ Returns:
+ Dict with 'companies' array containing {id, name} for matches (limited results)
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/companies/autocomplete"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}",
@@ -1143,7 +1506,22 @@ async def search_companies(query: str) -> Dict[str, Any]:
@mcp.tool()
async def find_company_by_name(name: str) -> Dict[str, Any]:
- """Find a company by name in Freshdesk."""
+ """Find a company by name using autocomplete in Freshdesk.
+
+ NOTE: This is an alias for search_companies() with the same limitations.
+
+ LIMITATIONS:
+ - Uses autocomplete API - returns LIMITED results (not paginated)
+ - Searches by name prefix only (case insensitive)
+ - Cannot search with substrings: "Acme" works, "cme" does NOT
+ - Returns only id and name fields
+
+ Args:
+ name: Company name prefix to search for
+
+ Returns:
+ Dict with 'companies' array containing {id, name} for matches
+ """
url = f"https://{FRESHDESK_DOMAIN}/api/v2/companies/autocomplete"
headers = {
"Authorization": f"Basic {base64.b64encode(f'{FRESHDESK_API_KEY}:X'.encode()).decode()}",