Overview
Freshdesk is a cloud-based customer support platform that was founded with the mission of enabling companies of all sizes to provide great customer service. Our goal is simple: make it easy for brands to talk to their customers and make it easy for users to get in touch with businesses.
Freshdesk's APIs belong to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding or deleting data from your helpdesk. The APIs also support Cross-Origin Resource Sharing (CORS).
Note:
This documentation is for the v2.0 of the APIs. Documentation for the v1.0 APIs can be found here.
What API commands are used by Freshdesk?
Freshdesk APIs are plain JSON over HTTP and use the following HTTP verbs:
Command | Purpose |
---|---|
POST | Create an object |
GET | Fetch one or more objects |
PUT | Update an object |
DELETE | Remove an object |
Note:
All API requests should hit the secured endpoint, that is, only HTTPS
What's New
Version 2 of the API brings several new features as well as changes to the previous APIs. This section highlights some of the new features introduced in v2.
- Higher rate limits as a result of significant performance enhancements
- Improved error handling - errors will return appropriate HTTP status codes and an error body
- Four new API categories - Business Hours, Products, Email Configs, and SLAs
- New APIs that enable you to Reply to a ticket and enhancements to existing APIs that enable you to Update a ticket's description, Update a ticket's notes, and Retrieve a list of tickets that have been recently modified
- XML Support has been deprecated, only JSON is supported
- Only SSL calls (HTTPS) will be allowed
- Works only via Freshdesk domains and not via custom CNAMEs
- Support for page sizes up to 100 has been added
- New API deprecation and breaking change policies
- Some categories have been renamed for consistency with the web application. For example, Forums are now Discussions and Users are now Contacts
Rate Limit
The number of API calls per minute is based on your plan. This limit is applied on an account wide basis irrespective of factors such as the number of agents or IP addresses used to make the calls. For all trial users, there is a default API limit of 50 calls/minute.
If your account hasn't been switched to the new minute level APIs, please contact support@freshdesk.com to get the new rate limits enabled for your account. To view the old API rate limits, click here
Note: An account can purchase additional API calls, to increase the rate limit. Contact us to know more about our pricing policy and purchase additional API calls.
To view the limits in the older plans, click here.
Plan | Rate Limit/minute | Maximum rate limit/minute per endpoint |
---|---|---|
Growth | 200 |
Ticket Create - 80 Ticket Update - 80 Tickets List - 20 Contacts List - 20 |
Pro | 400 |
Ticket Create - 160 Ticket Update - 160 Tickets List - 100 Contacts List - 100 |
Enterprise | 700 |
Ticket Create - 280 Ticket Update - 280 Tickets List - 200 Contacts List - 200 |
If you have purchased additional rate limits, the sub-limits are as follows: | ||
- | 1000 |
Ticket Create - 400 Ticket Update - 400 Tickets List - 300 Contacts List - 300 |
- | 2000 |
Ticket Create - 800 Ticket Update - 800 Tickets List - 400 Contacts List - 400 |
Notes:
1. Ensure to follow the rate limit - best practices to stay within the rate limit.
2. Even invalid requests count towards the rate limit.
3. Some custom apps consume API calls and these calls also count towards the rate limit.
You can check your current rate limit status by looking at the following HTTP headers which are returned in response to every API request.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Ratelimit-Total: 700
X-Ratelimit-Remaining: 426
X-Ratelimit-Used-CurrentRequest: 1
X-Freshdesk-Api-Version: latest=v2; requested=v2
Header Name | Description |
---|---|
X-RateLimit-Total | Total number of API calls allowed per minute. |
X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. |
X-RateLimit-Used-CurrentRequest | The number of API calls consumed by the current request. Most API requests consume one call, however, including additional information in the response will consume more calls. |
Retry-After | The number in seconds that you will have to wait to fire your next API request. This header will be returned only when the rate limit has been reached. |
If your API request is received after the rate limit has been reached, Freshdesk will return an error in the response. The Retry-After value in the response header will tell you how long you need to wait before you can send another API request.
HTTP/1.1 429
Content-Type: application/json; charset=utf-8
Retry-After: 34
Policies
Freshdesk APIs are classified into either production or beta APIs. A production API is one that has been made generally available for public use and is stable. A beta API is one that is still in development or is for internal or limited use and whose stability cannot be guaranteed. Beta APIs may be removed or modified at any time without advance notice. The following policies apply to production APIs only.
Deprecation Policy
The current version of production level APIs is v2. When a new version of APIs is made generally available (not beta), the older version will be deprecated and will cease to function after six months. Once an API is removed, any request to it will result in a 404 error.
Note:
We will not remove any v1 API until similar functionality is present in the v2 APIs
Breaking Change Policy
Changes that do not break an API, such as adding a new attribute can be made at any time. Changes that break a production level API such as removing attributes or making major changes to the API’s behavior will only be done with an advance notice of 60 days. However, there may be rare occasions where due to legal, performance, or security reasons, we are forced to make breaking changes without advance notice.
Changelog
June 2022
- We’ve added parent_folder_id, sub_folders_count, articles_count, hierarchy as solutions folder attributes and can be used in different Folder and Article APIs as part of Flexible Hierarchy feature. Read more about it here
November 2021
- We've updated the Create an Email Mailbox API to allow only "custom_mailbox" in mailbox_type and access_type as "outgoing" or "both" for public domain mailboxes like "gmail", "hotmail", "outlook", "yahoo", "aol".
July 2021
- New APIs for Ticket User Access
- Support added to create collaborators using agent_type parameter while Creating an Agent
- Support added to convert contacts to collaborators using type parameter utilizing Make Agent section
January 2021
- Canned Responses API now supports creating canned response folders and bulk creation of canned responses
- New APIs for Archive Tickets
- New APIs for Automations
- New APIs for Ticket Summary and Merge Tickets
- New APIs to Bulk Update and Bulk Delete tickets
- New APIs to Get Associated Tickets and Prime Association
October 2020
- We have updated the responses of /tickets, /tickets/id, /tickets/id/conversations to remove the content of the Tweets and Twitter direct messages inline with Twitter platform's content redistribution policy. Instead of the full Tweet content, you will be receiving the subject and description as 'View the message on Twitter'. For /contacts, /contacts/id APIs, you will be receiving the id of the user in the twitter_id field instead of the Twitter handle name.
April 2020
- We’ve added contact_segment_ids and company_segment_ids as solutions folder attributes and can be used in Create a Solution Folder and Update a Solution Folder API. Read more about customer segments here.
November 2019
September 2019
- Unpublish an article by passing only the status as 1 without any other parameters in the Update a Solution Article API.
- We've added a way to get article metrics for a specific language or consolidated across languages in the View a Solution Article API.
December 2018
- We’ve added APIs to create and update SLA policies in your Freshdesk account.
- The response to the GET Business hours API now includes the start time and end time of the business hours along with the time zone.
November 2018
- We've added a way to get description in the List All tickets API by using the include: parameter. We will not be sending description in the standard response after 2019-01-31 and you will have to use include to get description if you need it in the response. For accounts created after 2018-11-30, using include is compulsory to get description.
July 2018
- New API to restore, send invite and merge contacts
June 2018
- Create a ticket now accepts parent_id to create child tickets
- Create a ticket now accepts related_ticket_ids to create tracker tickets
- View a ticket now supports ticket association
May 2018
- New API to list all Topics participated by a user
- New APIs to list all watchers on a ticket, add or remove watcher, bulk add or bulk remove watchers.
- New APIs for forwarding a ticket and reply to a forward.
December 2017
- New API to Filter contacts
- New API to Filter companies
July 2017
- New API to Filter tickets
January 2017
- Create a Contact, Update a Contact and View a Contact now accepts other_companies attribute
- Create a Ticket and Update a Ticket now accepts company_id attribute
September 2016
- New APIs for Solutions
- New API to view helpdesk settings
July 2016
- New API to list all Satisfaction Ratings of a ticket
- New APIs for Surveys and Satisfaction Ratings
- New APIs to update an agent, delete an agent
- New APIs to list all roles, view a role
- Make Agent API now accepts list of agent related attributes in request
June 2016
- List all Tickets now supports the embedding of the requester info.
May 2016
- View a Ticket and List all Tickets now support the embedding of the ticket stats.
- List All Ticket Fields, List All Company Fields and List All Contact Fields are also allowed for agents who can Create a Ticket, Create a Company and Create a Contact respectively.
- Updating or deleting a ticket that has been marked as spam or deleted will now return a '405 Method Not Allowed'
- Updating or deleting a contact that has been blocked or deleted will now return a '405 Method Not Allowed'
- New API to create an outbound email
- Added support for editing tickets created through outbound email via Update a Ticket
- Create a Ticket and Update a Ticket now enforce dynamic form validation
- View a Ticket now supports embedding the details of the requester and the company
- Previously, for the ticket APIs, we accepted 'description' and 'description_html' as attributes in the request. Now we will only accept the description attribute which can now optionally contain HTML. In the response, we will return a 'description' and 'description_text' (which will strip any HTML out of description). We have made similar changes to Topics, Comments, and Agents. The full set of breaking changes are listed below
- The following request attributes have been removed
- 'description_html' has been removed from Create a Ticket and Update a Ticket
- 'body_html' has been removed from Create a Note, Create a Reply and Update a conversation
- The following request attributes have been renamed
- 'message_html' has been renamed to message in Create a Topic
- 'body_html' has been renamed to body in Creat a Comment
- The following response attributes have been removed
- 'description_html' has been removed from Forum responses
- The following response attributes have been renamed
- 'description' and 'description_html' have been renamed to description_text and description respectively in Ticket responses
- 'body' and body_html have been renamed to body_text and body in Conversation & Forum Comment responses
- 'signature_html' has been renamed to signature in Agent responses
- Notes have been renamed to Conversations. This has resulted in breaking changes in the following four APIs
- List All Notes of a Ticket has been renamed to List All Conversations of a Ticket
- View a ticket (include=notes is now include=conversations)
- Update A Note has been renamed to Update a Conversation
- Delete A Note is now Delete a Conversation
- Reply to Ticket has been renamed to Create Reply and moved to the Conversations section
- New API to retrieve the currently authenticated agent
- Added support for associating multiple emails to a contact
- We’ve added new APIs for Email Mailboxes.The API's support:
- Added new APIs for Viewing Mailbox Settings and Updating Mailbox Settings
- Also added new APIs for Viewing the bcc emails and Updating the bcc emails
April 2016
March 2016
November 2019
Authentication
How does it work? Who can access my helpdesk? Can everybody see my data?
Before you can set the priority of a ticket or change a customer's name or use any of the APIs listed above, you need to "authenticate your ID" or "log in" in the same way as you log in to your helpdesk's web portal.
You can use your personal API key to authenticate the request. If you use the API key, there is no need for a password. You can use any set of characters as a dummy password.
curl -v -u apikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets'
For example, if your API key is abcdefghij1234567890, the curl command to use is:
curl -v -u abcdefghij1234567890:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets'
Where can I find my API key?
- Log in to your Support Portal
- Click on your profile picture on the top right corner of your portal
- Go to Profile settings Page
- Your API key will be available below the change password section to your right
For more information, please refer to this solution article
Note:
If you are sure that your credentials are correct, but are still unable to access your helpdesk, make sure that the "APIkey:X" is Base64-encoded before passing it as an "Authorization" header.
What are the resources available via the API?
Every single piece of information - be it a customer's ID or the priority of a specific ticket - can be identified by its own unique identifier or "URI". If you want your data from the helpdesk, whether via your smartphone app or via a third party service, you need this identifier. All URIs follow a specific format and that format is:
https://your_helpdesk_domain_name/api/v2/resource_name
For example, if you are Davy Jones and you are managing problems of drowned souls via your Freshdesk portal "thelocker.freshdesk.com", then to access the contacts in your helpdesk, the syntax would be
https://thelocker.freshdesk.com/api/v2/contacts
For tickets, it would be
https://thelocker.freshdesk.com/api/v2/tickets
Note:
We have shortened API resource URLs throughout this document by omitting the domain name. For example, /api/v2/tickets is actually https://domain.freshdesk.com/api/v2/tickets
Will everyone have the same access rights?
No, your ability to access data depends on the permissions available to your Freshdesk user profile. For example, if your Freshdesk Agent Role is "Newbie Agent" who is only allowed to view tickets but not reply to them, then you will not be able to use the APIs to reply to a ticket.
Schema
Blank Fields:
Blank fields are included as null instead of being omitted.
Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. ( Example : 2016-02-13T23:27:49Z )
Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm
Note:
If a custom field is a date field, ensure to specify the value in the YYYY-MM-DD format.
( some valid datefields : 2016-02-15T21:16:25Z, 2012-12-24T12:56:15+05:30, 2010-03-23T12:00 )
Location Header:
POST requests will contain the Location Header in the response that points to the URL of the created resource.
Response
HTTP STATUS: HTTP 201 Created
Headers:
"Location": https://domain.freshdesk.com/api/v2/tickets/1
Embedding
Our previous version of APIs returned a large number of fields by default. In order to increase performance and reduce data usage, we have removed several of these fields in our v2.0 APIs. For example, when you view a ticket, we no longer return the requester's name or the company name. However, there may be situations where these fields are required and hence, we have included a mechanism to embed additional resources into an API call in order to minimise the number of required API calls.
Note:
Embedding resources into an API will consume an additional API call credit per embedded resource.
You can request for additional resources using the "include" keyword. For example you can embed the requester's details within the ticket view API by using the following command
Sample Request
curl -v -u 'abcdefgh12345678:X' -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=requester'
Sample Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | { "cc_emails" : ["user@cc.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["user@cc.com"], "email_config_id" : null, "fr_escalated" : false, "group_id" : null, "priority" : 1, "requester_id" : 1, "responder_id" : null, "source" : 2, "spam" : false, "status" : 2, "subject" : "", "company_id" : 1, "id" : 20, "type" : null, "to_emails" : null, "product_id" : null, "created_at" : "2015-08-24T11:56:51Z", "updated_at" : "2015-08-24T11:59:05Z", "due_by" : "2015-08-27T11:30:00Z", "fr_due_by" : "2015-08-25T11:30:00Z", "is_escalated" : false, "description_text" : "Not given.", "description" : "<div>Not given.</div>", "custom_fields" : { "category" : "Primary" }, "tags" : [ ], "requester": { "email": "test@test.com", "id": 1, "mobile": null, "name": "Rachel", "phone": null }, "attachments" : [ ] } |
Attachments
Attachments are supported for the following endpoints- Create a Ticket
- Update a Ticket
- Create a Contact
- Update a Contact
- Reply to a Ticket
- Update a conversation
Please follow the guidelines listed below
- Only files on your local machine can be attached using API.
- The Content-Type should always be multipart/form-data for create/update requests with attachments.
- The name of the file is preserved after it is attached i.e the filename sent in the response will be the same as the one in the request.
- Sample code for dealing with attachments can be found here.
Errors
I have encountered an error. How do I debug it?
API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error. You can use the table below to understand what each code means.
HTTP Status Code | Text | Description |
---|---|---|
400 | Client or Validation Error | The request body/query string is not in the correct format. For example, the Create a ticket API requires the requester_id field to be sent as part of the request and if it is missing, this status code is returned. |
401 | Authentication Failure | Indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here. |
403 | Access Denied | This indicates that the agent whose credentials were used in making this request was not authorized to perform this API call. It could be that this API call requires admin level credentials or perhaps the Freshdesk portal doesn't have the corresponding feature enabled. It could also indicate that the user has reached the maximum number of failed login attempts or that the account has reached the maximum number of agents |
404 | Requested Resource not Found | This status code is returned when the request contains invalid ID/Freshdesk domain in the URL or an invalid URL itself. For example, an API call to retrieve a ticket with an invalid ID will return a HTTP 404 status code to let you know that no such ticket exists. |
405 | Method not allowed | This API request used the wrong HTTP verb/method. For example an API PUT request on /api/v2/tickets endpoint will return a HTTP 405 as /api/v2/tickets allows only GET and POST requests. |
406 | Unsupported Accept Header | Only application/json and */* are supported. When uploading files multipart/form-data is supported. |
409 | Inconsistent/Conflicting State | The resource that is being created/updated is in an inconsistent or conflicting state. For example, if you attempt to Create a Contact with an email that is already associated with an existing user, this code will be returned. |
415 | Unsupported Content-type | Content type application/xml is not supported. Only application/json is supported. |
429 | Rate Limit Exceeded | The API rate limit allotted for your Freshdesk domain has been exhausted. |
500 | Unexpected Server Error | Phew!! You can't do anything more here. This indicates an error at Freshdesk's side. Please email us your API script along with the response headers. We will reach you out to you and fix this ASAP. |
In addition to the HTTP status code, most errors will also return a response body that contains more information to help you debug the error. A sample error response is shown below. The format of the error response body is explained after the example.
Sample Error
1 2 3 4 5 6 7 8 9 10 11 | { "description":"Validation failed", "errors":[ { "field":"name", "message":"Mandatory attribute missing", "code":"missing_field" } ] } |
Field | Description |
---|---|
field | The request field that triggerred this error. Applicable to HTTP 400 errors only. |
message | Detailed error message. |
code | Custom error code that is machine-parseable. |
In addition to the the error message, the error response will also contain a error code that is machine-parseable. The following table lists the error codes and their descriptions.
Code | Description |
---|---|
missing_field | A mandatory attribute is missing. For example, calling Create a Contact without the mandatory email field in the request will result in this error. |
invalid_value | This code indicates that a request contained an incorrect or blank value, or was in an invalid format. |
duplicate_value | Indicates that this value already exists. This error is applicable to fields that require unique values such as the email address in a contact or the name in a company. |
datatype_mismatch | Indicates that the field value doesn't match the expected data type. Entering text in a numerical field would trigger this error. |
invalid_field | An unexpected field was part of the request. If any additional field is included in the request payload (other than what is specified in the API documentation), this error will occur. |
invalid_json | Request parameter is not a valid JSON. We recommend that you validate the JSON payload with a JSON validator before firing the API request. |
invalid_credentials | Incorrect or missing API credentials. As the name suggests, it indicates that the API request was made with invalid credentials. Forgetting to apply Base64 encoding on the API key is a common cause of this error. |
access_denied | Insufficient privileges to perform this action. An agent attempting to access admin APIs will result in this error. |
require_feature | Not allowed as a specific feature has to be enabled in your Freshdesk portal for you to perform this action. |
account_suspended | Account has been suspended. |
ssl_required | HTTPS is required in the API URL. |
readonly_field | Read only field cannot be altered. |
inconsistent_state | An email should be associated with the contact before converting the contact to an agent. |
max_agents_reached | The account has reached the maximum number of agents. |
password_lockout | The agent has reached the maximum number of failed login attempts. |
password_expired | The agent's password has expired. |
no_content_required | No JSON data required. |
inaccessible_field | The agent is not authorized to update this field. |
incompatible_field | The field cannot be updated due to the current state of the record. |
Pagination
API responses that return a list of objects, such as View List of Tickets and View List of Contacts are paginated. To scroll through the pages, add the parameter page to the query string. The page number starts with 1.
https://domain.freshdesk.com/api/v2/contacts?page=2
By default, the number of objects returned per page is 30. This can be adjusted by adding the per_page parameter to the query string. The maximum number of objects that can be retrieved per page is 100. Invalid values and values greater than 100 will result in an error.
https://domain.freshdesk.com/api/v2/contacts?per_page=10
The per_page and page parameters can also be used together. The following example will retrieve the contacts from 11 to 20.
https://domain.freshdesk.com/api/v2/contacts?per_page=10&page=2
The 'link' header in the response will hold the next page url if exists. If you have reached the last page of objects, then the link header will not be set.
Headers: "link":< https://domain.freshdesk.com/api/v2/tickets?filter=all_tickets&page=2>;rel="next"
Best Practices
Rate Limit
- Whenever possible, please queue API calls at your end. This ensures that you can buffer calls on your end to avoid hitting the rate limit and retry API calls when you hit the rate limit after the retry-after time.
- Cache non-volatile data on your end whenever it is feasible. For e.g. the mapping between agent name and ID is extremely unlikely to change. Hence, by caching it on the client side, you will be able to avoid API calls.
- As soon as you recognise that a rate limit increase will be required in the future, contact us. This will make it possible for us to ensure that we are prepared to increase the limit as and when as it is needed.
Other
- Avoid making API calls directly from a mobile app, rather send the request to your servers and make the API calls from there. This ensures that in the event of an API endpoint being modified, you will be able to make and deploy the change to your server rather than updating your app and forcing your users to the latest version.
- Always use HTTP connection/multiplexing when making the API request. This will save some time while opening TCP connection to Freshdesk.
- When retrieving a list of objects, avoid making calls referencing page numbers over 500 (deep pagination). These are performance intensive calls and you may suffer from extremely long response times.
Code Samples
Code samples for accessing the Freshdesk API in various languages including Ruby, PHP, Java, Python, and Node JS are available in our Github repository.
API Index
CATEGORY | CREATE | VIEW | VIEW LIST | UPDATE | DELETE | OTHERS |
---|---|---|---|---|---|---|
Tickets | Yes | Yes | Yes | Yes | Yes | 7 more |
Conversations | Yes | No | Yes | Yes* | Yes | |
Contacts | Yes | Yes | Yes | Yes | Yes | 3 more |
Agents | Yes | Yes | Yes | Yes | Yes | 1 more |
Skills | Yes | Yes | Yes | Yes | Yes | |
Roles | No | Yes | Yes | No | No | |
Groups | Yes | Yes | Yes | Yes | Yes | |
Companies | Yes | Yes | Yes | Yes | Yes | 2 more |
Discussions | ||||||
— Categories | Yes | Yes | Yes | Yes | Yes | |
— Forums | Yes | Yes | Yes | Yes | Yes | 3 more |
— Topics | Yes | Yes | Yes | Yes | Yes | 4 more |
— Comments | Yes | No | Yes | Yes | Yes | |
Solutions | ||||||
— Categories | Yes | Yes | Yes | Yes | Yes | |
— Folders | Yes | Yes | Yes | Yes | Yes | |
— Solution Articles | Yes | Yes | Yes | Yes | Yes | |
Surveys | No | No | Yes | No | No | |
Satisfaction Ratings | Yes | No | Yes | No | No | |
Time Entries | Yes | No | Yes | Yes | Yes | 1 more |
— Mailboxes | Yes | Yes | Yes | Yes | Yes | |
— Settings | No | Yes | No | Yes | No | |
— Bcc Emails | No | Yes | No | Yes | No | |
— Email configs (old) | No | Yes | Yes | No | No | |
Products | No | Yes | Yes | No | No | |
Business Hours | No | Yes | Yes | No | No | |
Settings | ||||||
— Helpdesk | No | Yes | No | No | No | |
Account | No | Yes | Yes | No | No | |
Jobs | No | Yes | No | No |
Tickets
A ticket is an issue raised by a requester that need to be solved. It could be an urgent, high-priority problem exposing a security vulnerability. It could also be low priority question about a free T-shirt. Tickets are assigned to agents based on the agent's expertise and on the subject of the ticket.
Attribute | Type | Description |
---|---|---|
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 20MB. |
cc_emails | array of strings | Email address added in the 'cc' field of the incoming ticket email |
company_id | number | ID of the company to which this ticket belongs |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
deleted | boolean | Set to true if the ticket has been deleted/trashed. Deleted tickets will not be displayed in any views except the "deleted" filter |
description | string | HTML content of the ticket |
description_text | string | Content of the ticket in plain text |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
string | Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact. | |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
facebook_id | string | Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk. |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
fr_escalated | boolean | Set to true if the ticket has been escalated as the result of first response time being breached |
fwd_emails | array of strings | Email address(e)s added while forwarding a ticket |
group_id | number | ID of the group to which the ticket has been assigned |
id | number | Unique ID of the ticket |
is_escalated | boolean | Set to true if the ticket has been escalated for any reason |
name | string | Name of the requester |
phone | string | Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory. |
priority | number | Priority of the ticket |
product_id | number | ID of the product to which the ticket is associated |
reply_cc_emails | array of strings | Email address added while replying to a ticket |
requester_id | number | User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
source | number | The channel through which the ticket was created |
spam | boolean | Set to true if the ticket has been marked as spam |
status | number | Status of the ticket |
subject | string | Subject of the ticket |
tags | array of strings | Tags that have been associated with the ticket |
to_emails | Array of strings | Email addresses to which the ticket was originally sent |
twitter_id | string | Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. |
created_at | datetime | Ticket creation timestamp |
updated_at | datetime | Ticket updated timestamp |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Status, and Priorities. These numerical values along with their meanings are given below.
Source | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 7 |
Feedback Widget | 9 |
Outbound Email | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Create a Ticket
/api/v2/tickets
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the requester |
requester_id † | number | User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email. |
email † | string | Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact. |
facebook_id † | string | Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk. |
phone † | string | Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory. |
twitter_id † | string | Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact. |
unique_external_id † | string | External ID of the requester. If no contact exists with this external ID in Freshdesk, they will be added as a new contact. |
subject | string | Subject of the ticket. The default Value is null. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null. |
status * | number | Status of the ticket. The default Value is 2. |
priority * | number | Priority of the ticket. The default value is 1. |
description | string | HTML content of the ticket. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 20MB. |
cc_emails | array of strings | Email address added in the 'cc' field of the incoming ticket email |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) If product_id is given and email_config_id is not given, product's primary email_config_id will be set |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
group_id | number | ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id |
parent_id | number | ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket. |
product_id | number | ID of the product to which the ticket is associated. It will be ignored if the email_config_id attribute is set in the request. |
source * | number | The channel through which the ticket was created. The default value is 2. |
tags | array of strings | Tags that have been associated with the ticket |
company_id | number | Company ID of the requester. This attribute can only be set if the Multiple Companies feature is enabled (Estate plan and above) |
internal_agent_id | Integer | ID of the internal agent which the ticket should be assigned with |
internal_group_id | Integer | ID of the internal group to which the ticket should be assigned with |
lookup_parameter | string | This attribute for tickets can only be set if Custom Objects is enabled and a lookup field has been added under ticket fields.The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
* Refer Ticket properties table for supported values † Any of the five attributes is mandatory |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Source, Status, and Priorities. These numerical values along with their meanings are given below.
Source | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 7 |
Feedback Widget | 9 |
Outbound Email | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
Create a Ticket With Custom Fields
Note:
Refer this solution article for more details regarding custom fields.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"], "custom_fields" : { "category" : "Primary" } }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "custom_fields" : { "category" : "Primary" }, "tags" : [ ], "attachments" : [ ] } |
Create a Ticket With Custom Object record associated
Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #12345, here the primary_field_value will be “12345”
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"], "lookup_parameter" : "primary_field_value", "custom_fields" : { "cf_order_number_1" : "12345" } }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "custom_fields" : { "cf_order_number_1" : "12345" }, "tags" : [ ], "attachments" : [ ] } |
Create a Ticket With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.ext" -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Ticket Title", "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "this is a sample ticket", "description" : "<div>this is a sample ticket</div>", "custom_fields" : { "category" : null }, "tags" : [ ], "attachments":[ { "id":4004881085, "content_type":"image/jpeg", "file_size":44115, "name":"attachment1.jpg", "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment.jpg" "created_at":"2014-07-28T16:20:03+05:30", "updated_at":"2014-07-28T16:20:03+05:30", }, { "id":4004881086, "content_type":"image/jpeg", "file_size":44134, "name":"attachment2.jpg", "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment2.jpg" "created_at":"2014-07-28T16:20:03+05:30", "updated_at":"2014-07-28T16:20:03+05:30", } ] } |
Create a Child Ticket
Note:
1. This API request must have parent_id.
2. For more information on Parent Child Ticketing refer to this section.
Additional Parameters
Attribute | Type | Description |
---|---|---|
parent_id | integer | ID of the parent ticket under which the child ticket needs to be created. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "parent_id": 1, priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 2, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "association_type" : 2, "associated_tickets_list" : [1] "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
Create a Tracker
Note:
1. This API request must have related_ticket_ids.
2. For more information on Linked Tickets refer to this section.
Additional Parameters
Attribute | Type | Description |
---|---|---|
related_ticket_ids | array of integers | List of Ticket IDs which needs to be linked to the Tracker being created. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "related_ticket_ids": [1,2,3], priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 5, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "association_type" : 3, "associated_tickets_list" : [1,2,3] "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
Create an Outbound Email
/api/v2/tickets/outbound_email
Note:
1. By default, the ticket will be assigned to the agent sending the email and it will be created with 'closed' status. This makes sure that SLA timers aren't running unnecessarily on an outbound ticket.
2. Unlike normal tickets, the subject and description of outbound tickets cannot be updated. More information on the difference between normal and outbound tickets can be found here
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the requester |
email Mandatory | string | Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact. |
subject Mandatory | string | Subject of the ticket. The default Value is null. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null. |
status * | number | Status of the ticket. The default Value is 5. |
priority * | number | Priority of the ticket. The default value is 1. |
description | string | HTML content of the ticket. |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 20MB. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
email_config_id Mandatory | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
group_id | number | ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id |
tags | array of strings | Tags that have been associated with the ticket |
* Refer Ticket properties table for supported values |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Status, and Priorities. These numerical values along with their meanings are given below.
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "email_config_id": 1, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets/outbound_email' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : 1, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 10, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
View a Ticket
/api/v2/tickets/[id]
Use 'include' to embed additional details in the response. Each include will consume an additional credit. For example if you embed the requester and company information you will be charged a total of 3 API credits for the call.
Note:
By default, certain fields such as conversations, company name and requester email will not be included in the response. They can be retrieved via the embedding functionality.
Embed | Handle |
---|---|
conversations |
/api/v2/tickets/[id]?include=conversations Will return up to ten conversations sorted by "created_at" in ascending order. Including conversations will consume two API calls. In order to access more than ten conversations belonging to a ticket, use the List All Conversations of a Ticket API. |
requester |
/api/v2/tickets/[id]?include=requester Will return the requester's email, id, mobile, name, and phone. |
company |
/api/v2/tickets/[id]?include=company Will return the company's id and name. |
stats |
/api/v2/tickets/[id]?include=stats Will return the ticket’s closed_at, resolved_at and first_responded_at time |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "cc_emails" : ["user@cc.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["user@cc.com"], "email_config_id" : null, "fr_escalated" : false, "group_id" : null, "priority" : 1, "requester_id" : 1, "responder_id" : null, "source" : 2, "spam" : false, "status" : 2, "subject" : "", "company_id" : 1, "id" : 20, "type" : null, "to_emails" : null, "product_id" : null, "created_at" : "2015-08-24T11:56:51Z", "updated_at" : "2015-08-24T11:59:05Z", "due_by" : "2015-08-27T11:30:00Z", "fr_due_by" : "2015-08-25T11:30:00Z", "is_escalated" : false, "association_type" : null, "description_text" : "Not given.", "description" : "<div>Not given.</div>", "custom_fields" : { "category" : "Primary" }, "tags" : [ ], "attachments" : [ ] } |
Additional Examples
1. Get the associated conversations along with the ticket response.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=conversations' |
2. Get the associated company and requester information along with the ticket response.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=company,requester' |
3. Get the associated stats information along with the ticket response.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=stats' |
View a Ticket with Association
Use 'Association Type' to identify whether the ticket is a parent, child, tracker or related ticket.
Note:
1. For more information on Parent Child Ticketing refer to this section.
2. For more information on Linked Tickets refer to this section.
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Association. These numerical values along with their meanings are given below.
Association Type | Value |
---|---|
Parent | 1 |
Child | 2 |
Tracker | 3 |
Related | 4 |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/23' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 23, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "association_type" : 1, "associated_tickets_list" : [10,11,12] "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
Additional Information
The 'associated_tickets_list' attribute returns an array of associated ticket IDs based on the association type value
- When association_type is 1 (Parent), it will return the list of child IDs associated with the respective parent.
- When association_type is 2 (Child), it will return the respective parent ticket ID.
- When association_type is 3 (Tracker), it will return the list of related ticket IDs associated with the respective tracker.
- When association_type is 4 (Related), it will return the respective tracker ticket ID.
Ticket Association API
Ticket association allows you to define the relationship between two or more tickets. You can refer to this section to know more about the APIs to create parent-child or linked tickets relationship between tickets.
Get Associated Tickets
/api/v2/tickets/[id]/associated_tickets
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/associated_tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | { "tickets": [ { "id": 44, "group_id": 244782, "priority": 1, "requester_id": 50000067379, "responder_id": 21797696, "source": 2, "company_id": 50000029563, "status": 3, "subject": "Website unresponsive", "product_id": 18880, "type": "L2 - Analysis", "due_by": "2020-12-17T11:57:57Z", "fr_due_by": "2020-12-14T01:24:43Z", "is_escalated": false, "created_at": "2020-12-11T22:24:43Z", "updated_at": "2020-12-16T02:42:00Z" } ] } |
Get Prime Association of a Ticket
/api/v2/tickets/[id]/prime_association
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/44/prime_association' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "id": 20, "group_id": 244782, "priority": 1, "requester_id": 50000067379, "responder_id": 21797696, "source": 2, "company_id": 50000029563, "status": 1, "subject": "Website issue - tracker", "product_id": 18880, "type": "L4 - Bug", "due_by": "2020-12-19T11:57:57Z", "fr_due_by": "2020-12-15T01:24:43Z", "is_escalated": false, "created_at": "2020-12-10T20:20:43Z", "updated_at": "2020-12-16T02:42:00Z" } |
List All Tickets
/api/v2/tickets
Use filters to view only specific tickets (those which match the criteria that you choose). By default, only tickets that have not been deleted or marked as spam will be returned, unless you use the 'deleted' filter.
Note:
1. By default, only tickets that have been created within the past 30 days will be returned. For older tickets, use the updated_since filter
2. A maximum of 300 pages (30000 tickets) will be returned.
3. When using filters, the query string must be URL encoded - see example
4. Use 'include' to embed additional details in the response. Each include will consume an additional 2 credits. For example if you embed the stats information you will be charged a total of 3 API credits for the call.
5. For accounts created after 2018-11-30, you will have to use include to get description.
Filter by | Handle |
---|---|
Predefined filters |
/api/v2/tickets?filter=[filter_name] The various filters available are new_and_my_open, watching, spam, deleted. |
Requester | /api/v2/tickets?requester_id=[id] /api/v2/tickets?email=[requester_email] /api/v2/tickets?unique_external_id=[requester_unique_external_id] Example: /api/v2/tickets?email=superman@freshdesk.com /api/v2/tickets?email=bat%2Bman%40gmail.com (URL encoded bat+man@gmail.com) |
Company ID | /api/v2/tickets?company_id=[id] |
Updated since | /api/v2/tickets?updated_since=2015-01-19T02:00:00Z |
Custom ticket views | Check out the Filter Tickets API |
Sort by | Handle |
---|---|
created_at, due_by, updated_at, status |
/api/v2/tickets?order_by=created_at Default sort order is created_at |
asc, desc |
/api/v2/tickets?order_type=asc Default sort order type is desc |
Embed | Handle |
---|---|
stats |
/api/v2/tickets?include=stats Will return the ticket’s closed_at, resolved_at and first_responded_at time |
requester |
/api/v2/tickets?include=requester Will return the requester's email, id, mobile, name, and phone. |
description |
/api/v2/tickets?include=description Will return the ticket description and description_text. |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | [ { "cc_emails" : ["user@cc.com", "user2@cc.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["user@cc.com", "user2@cc.com"], "fr_escalated" : false, "spam" : false, "email_config_id" : null, "group_id" : 2, "priority" : 1, "requester_id" : 5, "responder_id" : 1, "source" : 2, "status" : 2, "subject" : "Please help", "to_emails" : null, "product_id" : null, "id" : 18, "type" : Lead, "created_at" : "2015-08-17T12:02:50Z", "updated_at" : "2015-08-17T12:02:51Z", "due_by" : "2015-08-20T11:30:00Z", "fr_due_by" : "2015-08-18T11:30:00Z", "is_escalated" : false, "custom_fields" : { "category" : "Default" } }, { "cc_emails" : [ ], "fwd_emails" : [ ], "reply_cc_emails" : [ ], "fr_escalated" : false, "spam" : false, "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 1, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "", "to_emails" : null, "product_id" : null, "id" : 17, "type" : null, "created_at" : "2015-08-17T12:02:06Z", "updated_at" : "2015-08-17T12:02:07Z", "due_by" : "2015-08-20T11:30:00Z", "fr_due_by" : "2015-08-18T11:30:00Z", "is_escalated" : false, "custom_fields" : { "category" : null } } ] |
Additional Examples
1. Get the first page of a list of tickets, with the ticket description included for each ticket.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?include=description' |
2. Get the first page of a list of tickets that are being watched by the agent whose credentials were used to make this API call.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?filter=watching' |
3. Get the first page of a list of tickets from the specified requester. The tickets will be returned in the descending order of their priority i.e highest priority first.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?requester_id=1230&order_by=status&order_type=desc' |
4. Get the second page (tickets from 11-20) of a list of all tickets.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?per_page=10&page=2' |
5. Get the first page of a list of tickets that have shown any activity since the 17th of August, 2015.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?updated_since=2015-08-17' |
6. Get the associated stats information along with the ticket response.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?include=stats' |
7. Filter tickets based on the following requester email (super+man@gmail.com) which needs to be URL encoded.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?email=super%2Bman%40gmail.com' |
Filter Tickets
/api/v2/search/tickets?query=[query]
Use custom ticket fields that you have created in your account to filter through the tickets and get a list of tickets matching the specified ticket fields.
Note:
1. Archived tickets will not be included in the results
2. The query must be URL encoded
3. Query can be framed using the name of the ticket fields, which can be obtained from Ticket Fields endpoint. Ticket Fields are case sensitive
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
5. Logical operators AND, OR along with parentheses () can be used to group conditions
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
7. Input for date fields should be in UTC Format
8. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
9. To scroll through the pages add page parameter to the url. The page number starts with 1 and should not exceed 10
10. To filter for fields with no values assigned, use the null keyword
11. Please note that the updates will take a few minutes to get indexed, after which it will be available through API
Supported Ticket Fields
Field | Type | Description |
---|---|---|
agent_id | integer | ID of the agent to whom the ticket has been assigned |
group_id | integer | ID of the group to which the ticket has been assigned |
priority | integer | Priority of the ticket |
status | integer | Status of the ticket |
tag | string | Tag that has been associated to the tickets |
type | string | Type of issue that has been associated to the tickets |
due_by | date | Date (YYYY-MM-DD) when the ticket is due to be resolved |
fr_due_by | date | Date (YYYY-MM-DD) when the first response is due |
created_at | date | Ticket creation date (YYYY-MM-DD) |
updated_at | date | Date (YYYY-MM-DD) when the ticket was last updated |
Custom Fields | ||
Single line text | string | |
Number | integer | |
Checkbox | boolean | |
Dropdown | string |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:3"' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 | { "total":49, "results":[ { "cc_emails":["clark.kent@kryptonspace.com"], "fwd_emails":[ ], "reply_cc_emails":[ ], "fr_escalated":false, "spam":false, "email_config_id":17, "group_id":156, "priority":3, "requester_id":6007738334, "responder_id":6001263404, "source":2, "company_id":2, "status":2, "subject":"Sample Title", "to_emails":null, "product_id":null, "id":47, "type":null, "due_by":"2016-02-23T16:00:00Z", "fr_due_by":"2016-02-22T17:00:00Z", "is_escalated":true, "description":"<div>Sample description</div>", "description_text":"Sample description", "created_at":"2016-02-20T09:16:58Z", "updated_at":"2016-02-23T16:14:57Z", "custom_fields":{ "sector_no":7, "locked":true } }, { "cc_emails":["bruce.wayne@gothamdomain.com"], "fwd_emails":[ ], "reply_cc_emails":[ ], "fr_escalated":true, "spam":false, "email_config_id":44, "group_id":65, "priority":3, "requester_id":6007738334, "responder_id":6001263404, "source":2, "company_id":33, "status":2, "subject":"New Title", "to_emails":null, "product_id":null, "id":57, "type":null, "due_by":"2016-02-23T16:00:00Z", "fr_due_by":"2016-02-22T17:00:00Z", "is_escalated":true, "description":"<div>New description</div>", "description_text":"New description", "created_at":"2016-02-20T16:15:10Z", "updated_at":"2016-03-14T15:58:13Z", "custom_fields":{ "sector_no":8, "locked":true } }, ... ... ... ... ] } |
Additional Examples
1. Get the list of Urgent and High priority tickets.
"priority:4 OR priority:3"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:4%20OR%20priority:3"' |
2. Get the second page of Open and Pending tickets.
"status:3 OR status:4"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="status:3%20OR%20status:4"&page=2' |
3. Get the list of Urgent and High priority tickets in Open Status belong to the group_id 11. "priority:>3 AND group_id:11 AND status:2"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:>3%20AND%20group_id:11%20AND%20status:2"' |
4. Get the list of locked tickets belong to Finance or Marketing sector (Custom Fields: locked, sector). "(cf_sector:'finance' OR cf_sector:'marketing') AND cf_locked:true"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="(cf_sector:%27finance%27%20OR%20cf_sector:%27marketing%27)%20AND%20cf_locked:true"' |
If you’re not getting a result for the above query, there’s a chance that the field might have been created recently or it has been moved to a new infrastructure. To query on these custom fields, use ‘custom_string’ instead of the actual field label.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string: finance"' |
5. Get the list of Urgent and High priority tickets created on a particular day. "priority:>3 AND created_at:'2017-01-01'"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:>3%20AND%20created_at:%272017-01-01%27"' |
6. Get the list of tickets whose type is 'Question' or 'Problem' and response due on first week of October 2017. "(type:'Question' OR type:'Problem') AND (due_by:>'2017-10-01' AND due_by:<'2017-10-07')"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="(type:%27Question%27%20OR%20type:%27Problem%27)%20AND%20(due_by:>%272017-10-01%27%20AND%20due_by:<%272017-10-07%27)"' |
7. Get the list of tickets whose type is 'Problem' and tagged with 'marketing'. "type:'Problem' AND tag:'marketing'"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="type:%27Problem%27%20AND%20tag:%27marketing%27"' |
8. Get the list of tickets without any tag. "tag:null"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="tag:null"' |
9. Get the list of urgent tickets whose type is undefined. "type:null AND priority:4"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="type:null%20AND%20priority:4"' |
10. Get the list of urgent tickets assigned to agents whose ids are 2 and 3. "(agent_id:2 OR agent_id:3) AND priority:4"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="(agent_id:2%20OR%20agent_id:3)%20AND%20priority:4"' |
11. Get the list of unassigned tickets "agent_id:null"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="agent_id:null"' |
12. All unresolved tickets "status:2 OR status:3 OR status:6 OR status:7"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="status:2%20OR%20status:3%20OR%20status:6%20OR%20status:7"' |
13. Get the list of tickets using a value in the single line text field. "custom_string:theactualkeyword"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeyword"' |
"custom_string:theactualkeywordone AND custom_string:theactualkeywordtwo"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeywordone%20AND%20custom_string:theactualkeywordtwo"' |
"custom_string:theactualkeywordone OR custom_string:theactualkeywordtwo"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeywordone%OR%20custom_string:theactualkeywordtwo"' |
Update a Ticket
/api/v2/tickets/[id]
Note:
Unlike normal tickets, the subject and description of outbound tickets cannot be updated. More information on the difference between normal and outbound tickets can be found here
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the requester |
requester_id | number | User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email. |
string | Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact. | |
facebook_id | string | Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk. |
phone | string | Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory. |
twitter_id | string | Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact. |
unique_external_id | string | External ID of the requester. If no contact exists with this external ID in Freshdesk, they will be added as a new contact. |
subject | string | Subject of the ticket. The default Value is null. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null. |
status * | number | Status of the ticket. The default Value is 2. |
priority * | number | Priority of the ticket. The default value is 1. |
description | string | HTML content of the ticket. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 20MB. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) If the product_id is changed and the current email_config_id doesn't belong to that product, then this value will be automatically updated to the selected product's primary email_config_id |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
group_id | number | ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id |
parent_id | number | ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket. |
product_id | number | ID of the product to which the ticket is associated. |
source * | number | The channel through which the ticket was created. The default value is 2. |
tags | array of strings | Tags that have been associated with the ticket |
company_id | number | Company ID of the requester. This attribute can only be updated if the Multiple Companies feature is enabled (Estate plan and above) |
internal_agent_id | Integer | ID of the internal agent which the ticket should be assigned with |
internal_group_id | Integer | ID of the internal group to which the ticket should be assigned with |
lookup_parameter | string | This attribute for tickets can only be set if Custom Objects is enabled and a lookup field has been added under ticket fields.The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
* Refer Ticket properties table for supported values |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Source, Status, and Priorities. These numerical values along with their meanings are given below.
Source | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 7 |
Feedback Widget | 9 |
Outbound Email | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "priority":2, "status":3 }' 'https://domain.freshdesk.com/api/v2/tickets/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "cc_emails" : [ ], "fwd_emails" : [ ], "reply_cc_emails" : [ ], "description_text" : "Not given.", "description" : "<div>Not given.</div>", "spam" : false, "email_config_id" : null, "fr_escalated" : false, "group_id" : null, "priority" : 2, "requester_id" : 1, "responder_id" : null, "source" : 3, "status" : 3, "subject" : "", "id" : 20, "type" : null, "to_emails" : null, "product_id" : null, "attachments" : [ ], "is_escalated" : false, "tags" : [ ], "created_at" : "2015-08-24T11:56:51Z", "updated_at" : "2015-08-24T11:59:05Z", "due_by" : "2015-08-27T11:30:00Z", "fr_due_by" : "2015-08-25T11:30:00Z" } |
Update the lookup field within a ticket
Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #98765, here the primary_field_value will be “98765”
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "priority":2, "status":3, "lookup_parameter" : "primary_field_value", "custom_fields" : { "cf_order_number_1" : "98765" } }' 'https://domain.freshdesk.com/api/v2/tickets/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 2, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 3, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "custom_fields" : { "cf_order_number_1" : "98765" }, "tags" : [ ], "attachments" : [ ] } |
Update Multiple Tickets
/api/v2/tickets/bulk_update
Note:
To update the internal group or internal agent of a ticket, the API request must also include status value
Attribute | Type | Description |
---|---|---|
ids Mandatory | Array of numbers | IDs of tickets to be updated |
For bulk replies:
Attribute | Type | Description |
---|---|---|
body | string | Content of the reply to be added to the tickets |
attachment_ids | Array of numbers | IDs of attachments to be added to the reply |
inline_attachment_ids | Array of numbers | IDs of inline attachments to be added to the reply |
cloud_files | Array of objects | Cloud attachments to be added to the reply |
For bulk update of properties:
Attribute | Type | Description |
---|---|---|
from_email | string | Support email from which the reply should be sent |
skip_close_notification | boolean | Used to skip email notifications sent to requesters on closing a ticket |
email_config_id | Integer | Support email config on the ticket. Will be used for corresponding responses on the ticket |
group_id | Integer | ID of the group to be assigned on the ticket |
priority | Integer | Used to set the priority of the ticket. Possible values are 1,2,3,4 |
parent_id | Integer | ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket. |
requester_id | Integer | ID of the requester on the ticket |
responder_id | Integer | ID of the agent to be assigned on the ticket |
source | Integer | Used to set the source of the ticket. Possible values are 1, 2,3,7,8,9,10 |
status | Integer | Used to set the status of the ticket. Possible values are 2,3,4,5,6,7 |
type | String | Type of the ticket. |
product_id | Integer | ID of the product to be associated with the ticket |
due_by | date-time | Timestamp that denotes when the ticket is due to be resolved |
fr_due_by | date-time | Timestamp that denotes when the first response is due |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
tags | Array of strings | Tags that have been associated with the ticket |
internal_agent_id | Integer | ID of the internal agent which the ticket should be assigned with |
internal_group_id | Integer | ID of the internal group to which the ticket should be assigned with |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"bulk_action": {"ids": [20,21,22],"properties":{"from_email":"support@freshdesk.com","status":2,"group_id":1234,"type":"Question","priority":4},"reply":{"body":"Please check this ticket"}}}' 'https://domain.freshdesk.com/api/v2/tickets/bulk_update' |
Response
1 2 3 4 | { "job_id": "e4d18654f60b5204513155b26c6cb", "href":"https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb" } |
The bulk ticket update happens at the background and the progress can be checked using the job_id in the response.
1 2 3 4 | { "id": "e4d18654f60b5204513155b26c6cb", "status": "IN PROGRESS", } |
Forward a ticket
/api/v2/tickets/[id]/forward
Forward your tickets to an external email address. You can also reply to the forwarded emails using the Reply to Forward API.
Attribute | Type | Description |
---|---|---|
body Mandatory | string | Content of the note in HTML format |
body_text | string | Content of the note in plain text |
id | integer | ID of the forwarded note |
incoming | boolean | Set to true if a particular conversation should appear as being created from outside (i.e., not through web portal) |
private | boolean | Set to true if the note is private |
agent_id | number | ID of the agent/user who is forwarding the ticket |
support_email | string | Email address from which the ticket is forwarded. For notes, this value will be null. |
source | number | Denotes the type of the conversation. |
ticket_id | number | ID of the ticket which gets forwarded |
include_quoted_text | boolean | Include the quoted text conversations in the forwarded email. The default value is True. |
include_original_attachments | boolean | Include the ticket attachments in the forwarded email. The default value is True. |
from_email | string | The email address from which the forward is sent. By default the global support email will be used. |
to_emails Mandatory | array of strings | Emails to which the ticket gets forwarded |
cc_emails | array of strings | Email address added in the 'cc' field of the outgoing forward email. |
bcc_emails | array of strings | Email address added in the 'bcc' field of the outgoing forward email. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "to_emails": ["user@company.com"]}' 'https://domain.freshdesk.com/api/v2/tickets/3/forward' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "body":"<div>Hi tom, Still Angry</div>", "body_text":"Hi tom, Still Angry", "id":35131396111, "incoming":false, "private":true, "user_id":35008297863, "support_email":"support@domain.freshdesk.com", "source":8, "category":2, "ticket_id":3, "to_emails":["user@company..com"], "from_email":"\"Agent Bob\" <support@domain.freshdesk.com>", "cc_emails":[], "bcc_emails":[], "email_failure_count":null, "outgoing_failures":null, "created_at":"2020-08-24T05:53:09Z", "updated_at":"2020-08-24T05:53:09Z", "attachments":[], "deleted":false, "last_edited_at":null, "last_edited_user_id":null, "cloud_files":[], "has_quoted_text":true } |
Ticket Merge API
Sometimes, a customer might try to get your attention regarding a particular issue by contacting you through separate channels. Sometimes, the same issue might be reported by different people in the team or someone might accidentally open a new ticket instead of following up on an existing one. To avoid conflicts, you can merge all related tickets together and keep the communication streamlined.
Attribute | Type | Description |
---|---|---|
primary_id | integer | Ticket to which conversations from secondary tickets will be merged |
ticket_ids | Array of numbers | IDs of tickets to be merged |
note_in_primary | hash | This contains the note added to the primary ticket along with the type of the note (public/private). A default note gets added if this is not specified in the request |
note_in_secondary | hash | This contains the note added to the secondary tickets along with the type of the note (public/private). A default note gets added if this is not specified in the request |
convert_recepients_to_cc | boolean | This will add recipients from secondary tickets in CC of the primary ticket |
/api/v2/tickets/merge
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{"primary_id":20,"ticket_ids":[20,21,22],"convert_recepients_to_cc":true,"note_in_primary":{"body":"Sample note","private":true}}' 'https://domain.freshdesk.com/api/v2/tickets/merge |
Response
1 | HTTP Status: 204 No Content |
Watcher
Using Watcher, you can follow the progress of a ticket even when it is not assigned to you. You can become a watcher of that ticket so that whenever there’s some update (like ticket reply or status change), you’ll receive an email notification.
Attribute | Type | Description |
---|---|---|
ids Mandatory | array of numbers | IDs of tickets for which the watcher should be updated |
user_id Mandatory | integer | ID of the agent to be added/removed as a watcher on the ticket |
watcher_ids | array of numbers | IDs of agents who’ve been added as watchers on the ticket |
Add watcher
/api/v2/tickets/[id]/watch
Parameters
Attribute | Type | Description |
---|---|---|
user_idMandatory | integer | ID of the agent to be added as a watcher on the ticket |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{"user_id":35010088657}' -X POST 'https://domain.freshdesk.com/api/v2/tickets/569/watch' |
Response
1 | HTTP Status: 204 No Content |
Add watcher to multiple tickets
/api/v2/tickets/bulk_watch
Parameters
Attribute | Type | Description |
---|---|---|
idsMandatory | array of numbers | IDs of tickets for which the watcher should be updated |
user_id | integer | ID of the agent to be added as a watcher on the ticket |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{"ids":[560,561],"user_id":35014948467}' -X PUT 'https://domain.freshdesk.com/api/v2/tickets/bulk_watch' |
Response
1 | HTTP Status: 204 No Content |
Remove watcher from multiple tickets
/api/v2/tickets/bulk_unwatch
Parameters
Attribute | Type | Description |
---|---|---|
idsMandatory | array of numbers | ID's of tickets for which the watcher should be removed |
Note:
So for this API we will not be passing any user_id by default it takes the user_id of the current user who is logged in and it uses only id's to remove the watcher of existing user and currently we haven't implemented it for other agents to pass their user_id and do bulk remove action.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{"ids":[560,561]}' -X PUT 'https://domain.freshdesk.com/api/v2/tickets/bulk_unwatch' |
Response
1 | HTTP Status: 204 No Content |
Delete a Ticket
/api/v2/tickets/[id]
Note:
Rest assured. When deleted, tickets are not cast into the fiery volcanoes of Mount Doom. You can retrieve them using the Restore Ticket API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/1' |
Response
1 | HTTP Status: 204 No Content |
Delete Multiple Tickets
/api/v2/tickets/bulk_delete
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"bulk_action": {"ids": [20,21,22]}}' 'https://domain.freshdesk.com/api/v2/tickets/bulk_delete' |
Response
1 2 3 4 | { "job_id": "e4d18654f60b5204513155b26c6cb630", "href":"https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb630" } |
The bulk ticket deletion happens at the background and the progress can be checked using the job_id in the response.
1 2 3 4 | { "id": "e4d18654f60b5204513155b26c6cb630", "status": "IN PROGRESS", } |
List All Ticket Fields
/api/v2/ticket_fields
Note:
The agent whose credentials (identified by the API key) are used to make the API call should be authorised to either view the ticket fields or create a new ticket
Ticket Fields
Ticket Field | Description |
---|---|
id | ID of the ticket field |
default | Set to true if the field is not a custom field |
description | Description of the ticket field |
label | Display name for the field (as seen by agents) |
name | Name of the ticket field |
position | Position in which the ticket field is displayed in the form |
required_for_closure | Set to true if the field is mandatory for closing the ticket |
type | For custom ticket fields, type of value associated with the field will be given (Examples custom_date, custom_text...) |
required_for_agents | Set to true if the field is mandatory for Agents |
required_for_customers | Set to true if the field is mandatory in the customer portal |
label_for_customers | Display name for the field (as seen in the customer portal) |
customers_can_edit | Set to true if the field can be updated by customers |
displayed_to_customers | Set to true if the field is displayed in the customer portal |
portal_cc | Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket |
portal_cc_to | Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list |
choices | List of values supported by the field |
nested_ticket_fields | Applicable only for dependent fields, this contain details of nested fields (see the sample response given below) |
To view only specific ticket fields (that is, those which match only the criteria you choose) use the filters given below.
Filter by | Handle |
---|---|
type | /api/v2/ticket_fields?type=[type] |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket_fields' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 | [ { "id" : 1, "description" : "Ticket requester", "label" : "Search a requester", "name" : "requester", "position" : 1, "portal_cc" : false, "portal_cc_to" : "company", "type" : "default_requester", "label_for_customers" : "Requester", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : true, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2014-12-17T11:58:08Z" }, { "id" : 19, "description" : "", "label" : "Rating", "name" : "rating", "position" : 2, "type" : "custom_decimal", "label_for_customers" : "Rating", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-16T14:06:48Z", "updated_at" : "2015-06-16T14:06:51Z" }, { "id" : 20, "description" : "", "label" : "regional_id", "name" : "regional_id", "position" : 3, "type" : "custom_number", "label_for_customers" : "regional_id", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-16T14:06:52Z", "updated_at" : "2015-06-16T14:06:53Z" }, { "id" : 18, "description" : "", "label" : "customer_priority", "name" : "customer_priority", "position" : 4, "type" : "custom_dropdown", "label_for_customers" : "customer_priority", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-15T11:45:55Z", "updated_at" : "2015-06-16T14:06:54Z", "choices" : [ "1st", "2nd" ] }, { "id" : 21, "description" : "", "label" : "country", "name" : "country", "position" : 5, "type" : "nested_field", "label_for_customers" : "country", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-17T05:44:15Z", "updated_at" : "2015-06-17T05:44:16Z", "choices" : [ { "usa" : [ { "texas" : [ "citytexas1" ] }, { "washington" : [ "dc", "seatle" ] }, { "newyork" : [ "manhattan", "boston" ] } ] }, { "india" : [ { "tamilnadu" : [ "chennai", "trichy", "kovai", "madhurai" ] }, { "kerala" : [ "ernakulam", "kochin", "trivandrum" ] }, { "gujarat" : [ "allahabad", "gandhinagar" ] } ] } ], "nested_ticket_fields" : [ { "description" : "", "id" : 3, "label" : "state", "label_in_portal" : "state", "level" : 2, "name" : "state", "ticket_field_id" : 21, "created_at" : "2015-06-17T05:44:16Z", "updated_at" : "2015-06-17T05:44:16Z" }, { "description" : "", "id" : 4, "label" : "city", "label_in_portal" : "city", "level" : 3, "name" : "city", "ticket_field_id" : 21, "created_at" : "2015-06-17T05:44:16Z", "updated_at" : "2015-06-17T05:44:16Z" } ] }, { "id" : 14, "description" : "", "label" : "internal_issue", "name" : "internal_issue", "position" : 6, "type" : "custom_checkbox", "label_for_customers" : "internal_issue", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-15T11:40:12Z", "updated_at" : "2015-06-17T05:44:16Z" }, { "id" : 13, "description" : "", "label" : "department", "name" : "department", "position" : 8, "type" : "custom_text", "label_for_customers" : "department", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-05-11T11:03:28Z", "updated_at" : "2015-06-17T05:44:17Z" }, { "id" : 2, "description" : "Ticket subject", "label" : "Subject", "name" : "subject", "position" : 10, "type" : "default_subject", "label_for_customers" : "Subject", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : true, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:18Z" }, { "id" : 3, "description" : "Ticket type", "label" : "Type", "name" : "ticket_type", "position" : 11, "type" : "default_ticket_type", "label_for_customers" : "Type", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : false, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:18Z", "choices" : [ "Question", "Incident", "Problem", "Feature Request", "Lead" ] }, { "id" : 4, "description" : "Ticket source", "label" : "Source", "name" : "source", "position" : 12, "type" : "default_source", "label_for_customers" : "Source", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : false, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:19Z", "choices" : { "Email" : 1, "Portal" : 2, "Phone" : 3, "Forum" : 4, "Twitter" : 5, "Facebook" : 6, "Chat" : 7, "Feedback Widget" : 9 } }, { "id" : 5, "description" : "Ticket status", "label" : "Status", "name" : "status", "position" : 13, "type" : "default_status", "label_for_customers" : "Status", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:19Z", "choices" : { "2" : [ "Open", "Being Processed" ], "3" : [ "Pending", "Awaiting your Reply" ], "4" : [ "Resolved", "This ticket has been Resolved" ], "5" : [ "Closed", "This ticket has been Closed" ], "6" : [ "Waiting on Customer", "Awaiting your Reply" ], "7" : [ "Waiting on Third Party", "Being Processed" ] } }, { "id" : 6, "description" : "Ticket priority", "label" : "Priority", "name" : "priority", "position" : 14, "type" : "default_priority", "label_for_customers" : "Priority", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : false, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:19Z", "choices" : { "Low" : 1, "Medium" : 2, "High" : 3, "Urgent" : 4 } }, { "id" : 7, "description" : "Ticket group", "label" : "Group", "name" : "group", "position" : 15, "type" : "default_group", "label_for_customers" : "Group", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : false, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:20Z", "choices" : { "Entertainment" : 4, "Product Management" : 1, "QA" : 2, "Sales" : 3, "vcxvxcvc" : 5 } }, { "id" : 8, "description" : "Agent", "label" : "Agent", "name" : "agent", "position" : 16, "type" : "default_agent", "label_for_customers" : "Assigned to", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:03Z", "updated_at" : "2015-06-17T05:44:20Z", "choices" : { "fggfg" : 30, "Rt" : 31, "Super Man" : 32, "SuperThreefour" : 7, "superyu" : 5, "Support" : 1 } }, { "id" : 9, "description" : "Select the product, the ticket belongs to.", "label" : "Product", "name" : "product", "position" : 16, "type" : "default_product", "label_for_customers" : "Product", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:03Z", "updated_at" : "2014-11-30T09:10:03Z", "choices" : { "ddd" : 1 } }, { "id" : 10, "description" : "Ticket description", "label" : "Description", "name" : "description", "position" : 17, "type" : "default_description", "label_for_customers" : "Description", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : true, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:03Z", "updated_at" : "2015-06-17T05:44:20Z" } ] |
Additional Examples
1. List the ticket_field that is of type 'default_requester'
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket_fields?type=default_requester' |
List All Conversations of a Ticket
/api/v2/tickets/[id]/conversations
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/conversations' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | [ { "body_text" : "Please reply as soon as possible.", "body" : "<div>Please reply as soon as possible.</div>", "id" : 3, "incoming" : false, "private" : true, "user_id" : 1, "support_email" : null, "source" : 2, "ticket_id" : 20, "created_at" : "2015-08-24T11:59:05Z", "updated_at" : "2015-08-24T11:59:05Z", "from_email" : "agent2@yourcompany.com", "to_emails" : ["agent1@yourcompany.com"], "cc_emails": ["example@ccemail.com"], "bcc_emails": ["example@bccemail.com"], "attachments" : [ ], "last_edited_at" : "2015-08-24T11:59:59Z", "last_edited_user_id" : 2 } ] |
Additional Examples
1. This ticket's conversation has more than 30 entries. This request returns the second page (entries from 31 to 60).
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/1/conversations?page=2' |
List All Time Entries of a Ticket
/api/v2/tickets/[id]/time_entries
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | [ { "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" } ] |
Additional Examples
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries?page=2' |
List All Satisfaction Ratings of a Ticket
/api/v2/tickets/[ticket_id]/satisfaction_ratings
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/[ticket_id]/satisfaction_ratings' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | [ { "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" } ] |
Ticket Summary
- Progress on the ticket so far and
- Important information that has been repeatedly referenced
This adds a section below the ticket description, the section can be used to summarize everything the support team or support agent knows about a ticket before they assign the ticket they worked on to another team. This is available from the Blossom plan. You can read more details about ticket summary here.
View Summary
/api/v2/tickets/[id]/summary
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/summary' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "body": "<div dir=\"ltr\">Test summary</div>", "body_text": "Test summary", "id": 82007772826, "user_id": 82002117631, "ticket_id": 20, "created_at": "2020-12-16T07:15:03Z", "updated_at": "2020-12-16T07:15:03Z", "attachments": [], "last_edited_at": null, "last_edited_user_id": null, "cloud_files": [] } |
Update Summary
/api/v2/tickets/[id]/summary
Attribute | Type | Description |
---|---|---|
bodyMandatory | integer | Content of the summary note in HTML |
attachments | Array of files | Attachments to be added to the summary note |
user_id | integer | Id of the user who creates the summary note |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{"body":"Updated summary"}' 'https://domain.freshdesk.com/api/v2/tickets/20/summary' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "body": "<div dir=\"ltr\">Updated summary</div>", "body_text": "Updated summary", "id": 82007772826, "user_id": 82002117631, "ticket_id": 20, "created_at": "2020-12-16T07:15:03Z", "updated_at": "2020-12-16T07:25:00Z", "attachments": [], "last_edited_at":"2020-12-16T07:25:00Z", "last_edited_user_id": 82002117631, "cloud_files": [] } |
Archive Tickets
In order to enhance the performance of your helpdesk, Freshdesk will archive closed, inactive tickets. This way, every time the helpdesk pulls up ticket count and other ticket properties, old and irrelevant tickets will be excluded making the process quicker and more efficient.Depending on the company's ticket traffic, any 'closed' ticket that has been inactive for 120 days will be archived. Read more about ticket archiving here: https://support.freshdesk.com/en/support/solutions/articles/212901-ticket-archiving
View an Archive Ticket
/api/v2/tickets/archived/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/archived/40' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | { "cc_emails" : ["user@cc.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["user@cc.com"], "email_config_id" : null, "fr_escalated" : false, "group_id" : null, "priority" : 1, "requester_id" : 1, "responder_id" : null, "source" : 2, "spam" : false, "status" : 5, "subject" : "", "company_id" : 1, "id" : 40, "type" : null, "to_emails" : null, "product_id" : null, "created_at" : "2015-08-24T11:56:51Z", "updated_at" : "2015-08-24T11:59:05Z", "due_by" : "2015-08-27T11:30:00Z", "fr_due_by" : "2015-08-25T11:30:00Z", "is_escalated" : false, "association_type" : null, "description_text" : "Not given.", "description" : "<div>Not given.</div>", "custom_fields" : { "category" : "Primary" }, "tags" : [ ], "archived" : true, "attachments" : [ ] } |
List All Conversations of an Archive Ticket
/api/v2/tickets/archived/[id]/conversations
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/archived/20/conversations' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | [ { "body_text" : "Please reply as soon as possible.", "body" : "<div>Please reply as soon as possible.</div>", "id" : 3, "incoming" : false, "private" : true, "user_id" : 1, "support_email" : null, "source" : 2, "ticket_id" : 20, "created_at" : "2015-08-24T11:59:05Z", "updated_at" : "2015-08-24T11:59:05Z", "from_email" : "agent2@yourcompany.com", "to_emails" : ["agent1@yourcompany.com"], "cc_emails": ["example@ccemail.com"], "bcc_emails": ["example@bccemail.com"], "attachments" : [ ] } ] |
Ticket User Access
Helps provide agents/collaborators access to a ticket based on a condition. For example: You can use the API to provide ticket access to the person who is raising a ticket or given the access to a ticket to anyone who has added a note on the ticket
Attribute | Type | Description |
---|---|---|
user_ids | array of numbers | IDs of users who have access to a particular ticket |
Add Ticket User Access
/api/v2/tickets/[id]/accesses
Parameters
Attribute | Type | Description |
---|---|---|
user_ids Mandatory | array of numbers | List of User IDs for whom ticket access should be provided |
Sample code | Curl
1 | curl -v -u yourapikey:X -d '{ "user_ids": [ 1, 2 ] }' -H "Content-Type: application/json" -X POST 'https://domain.freshdesk.com/api/v2/tickets/1/accesses' |
Response
1 2 3 | { "user_ids": [ 1, 2] } |
Update Ticket User Access
/api/v2/tickets/[id]/accesses
Parameters
Attribute | Type | Description |
---|---|---|
user_ids Mandatory | array of objects | Array of object type : { id: integer, deleted: boolean }, where id is the user id of the user and deleted indicates whether to remove access for this user or not |
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 12 | curl -v -u yourapikey:X -d '{ "user_ids": [ { "id": 2, "deleted": true }, { "id": 3 } ] } ' -H "Content-Type: application/json" -X PATCH 'https://domain.freshdesk.com/api/v2/tickets/1/accesses' |
Response
1 2 3 | { "user_ids": [ 1, 3] } |
Ticket Fields
Note: Only users with admin privileges can access the following APIs.
The custom and default ticket fields in Freshdesk have the following properties.
JSON Parameters
Ticket Field | Description |
---|---|
id | ID of the ticket field |
default | Set to true if the field is not a custom field |
description | Description of the ticket field |
label | Display name for the field (as seen by agents) |
name | Name of the ticket field |
position | Position in which the ticket field is displayed in the form |
required_for_closure | Set to true if the field is mandatory for closing the ticket |
type | For custom ticket fields, The type of value associated with the field will be given (Examples custom_date, custom_text...) |
required_for_agents | Set to true if the field is mandatory for Agents |
required_for_customers | Set to true if the field is mandatory in the customer portal |
label_for_customers | Display name for the field (as seen in the customer portal) |
customers_can_edit | Set to true if the field can be updated by customers |
displayed_to_customers | Set to true if the field is displayed in the customer portal |
portal_cc | Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket |
portal_cc_to | Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list |
choices | List of values supported by the field |
is_fsm | True if the Ticket field is inside FSM section (Applicable only if FSM is enabled) |
field_update_in_progress | True if the choice update is in progress (Applicable for the fields which has 100+ choices) |
dependent_fields | Applicable only for dependent fields, this contains details of nested fields (see the sample response given below) |
section_mappings | Applicable only if the field is part of a section. This contains section ID and position of the ticket field in the section |
List All Ticket Fields
/api/v2/admin/ticket_fields
To view all ticket field details, use this API.
Sample code | Curl
1 2 3 4 5 | # All Ticket Fields curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields' # All Ticket Fields with section mapping curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields?include=section' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 | # All Ticket Fields [ { "id":21, "name":"cf_issue_type", "label":"Issue Type", "label_for_customers":"Issue Type", "position":1, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-16T09:35:26Z", "updated_at":"2019-12-16T09:35:27Z" }, { "id":20, "name":"cf_product_category", "label":"Product Category", "label_for_customers":"Product Category", "position":3, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-16T07:12:07Z", "updated_at":"2019-12-16T09:35:26Z", "has_section":true }, { "id":19, "name":"cf_subject", "label":"Subject", "label_for_customers":"Subject", "position":4, "type":"custom_text", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-11T12:10:46Z", "updated_at":"2019-12-16T09:35:26Z", "section_mappings":[ { "section_id":3, "position":1 } ] }, { "id":12, "name":"cf_duplicate", "label":"Duplicate", "label_for_customers":"Duplicate", "position":5, "type":"custom_checkbox", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-03T12:23:58Z", "updated_at":"2019-12-16T09:35:26Z" } ] # Ticket Fields with section mapping [ { "id":21, "name":"cf_issue_type", "label":"Issue Type", "label_for_customers":"Issue Type", "position":1, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-16T09:35:26Z", "updated_at":"2019-12-16T09:35:27Z", "section_mappings": [ { "section_id": 1, "position": 1 } ] }, { "id":20, "name":"cf_product_category", "label":"Product Category", "label_for_customers":"Product Category", "position":3, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-16T07:12:07Z", "updated_at":"2019-12-16T09:35:26Z", "has_section":true, "sections": [ { "id": 1, "label": "Ecosystem Type", "parent_ticket_field_id": 12, "choice_ids": [ 6 ], "ticket_field_ids": [ 17, 18, 27 ] } ] }, { "id":19, "name":"cf_subject", "label":"Subject", "label_for_customers":"Subject", "position":4, "type":"custom_text", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-11T12:10:46Z", "updated_at":"2019-12-16T09:35:26Z", "section_mappings":[ { "section_id":3, "position":1 } ] }, { "id":12, "name":"cf_duplicate", "label":"Duplicate", "label_for_customers":"Duplicate", "position":5, "type":"custom_checkbox", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-03T12:23:58Z", "updated_at":"2019-12-16T09:35:26Z" } ] |
Create a Ticket Field
/api/v2/admin/ticket_fields
To create a new ticket field, use the following APIs.
JSON Parameters
Attribute | Type | Description |
---|---|---|
customers_can_edit | boolean | To specify whether the customer can edit the ticket field |
label_for_customers | string | Ticket Field name to be displayed to customers |
displayed_to_customers | boolean | Display Ticket Field to customers |
label | string | Display the name of the Ticket Field |
type | string | Ticket Field type. Can be custom_dropdown, custom_checkbox, custom_text, etc... |
position | number | Position in which the ticket field is displayed in the form. If not given, it will be displayed on top |
required_for_closure | boolean | Set to true if the field is mandatory for closing the ticket |
required_for_agents | boolean | Set to true if the field is mandatory for Agents |
required_for_customers | boolean | Set to true if the field is mandatory in the customer portal |
choices (Applicable for dropdown) | Array of dictionary | Array of key, value pairs containing the value and position of dropdown choices |
dependent_fields | Array of dictionary | Applicable only for dependent fields, this contains details of nested fields |
section_mappings | Array of dictionary | Applicable only if the field is part of a section. This contains the details of a section (ID, position) for which it is been a part of |
Sample code | Curl
1 2 3 4 5 6 7 8 | # Custom Dropdown curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Issue Type","displayed_to_customers":true,"label":"Issue Type","position":1,"type":"custom_dropdown","choices":[{"value":"Refund","position":1},{"value":"Faulty Product","position":2},{"value":"Item Not Delivered","position":3}]}' https://domain.freshdesk.com/api/v2/admin/ticket_fields' # Custom Text with section mapping curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Feedback","displayed_to_customers":true,"section_mappings":[{"position":3,"section_id":1}],"label":"Feedback","type":"custom_text"}' https://domain.freshdesk.com/api/v2/admin/ticket_fields' # Dependent Field curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Bank","displayed_to_customers":true,"label":"Bank","position":13,"type":"nested_field","choices":[{"value":"HDFC","position":1,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Porur","position":1},{"value":"OMR","position":2}]},{"value":"Madurai","position":2,"choices":[{"value":"Thirumangalam","position":1},{"value":"SB Colony","position":2}]}]},{"value":"SBI","position":2,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Tambaram","position":1},{"value":"Guindy","position":2}]},{"value":"Trichy","position":2,"choices":[{"value":"AGS Colony","position":1}]}]},{"value":"ICICI","position":3,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Avadi","position":1}]}]}],"dependent_fields":[{"label":"District","label_for_customers":"District","level":2},{"label":"Branch","label_for_customers":"Branch","level":3}]}' https://domain.freshdesk.com/api/v2/admin/ticket_fields' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 | # Custom Dropdown { "id":22, "name":"cf_issue_type_297457", "label":"Issue Type", "label_for_customers":"Issue Type", "position":1, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-19T05:28:31Z", "updated_at":"2019-12-19T05:28:31Z", "choices":[ { "id":125, "position":1, "value":"Refund", "parent_choice_id":22, "choices":[ ] }, { "id":126, "position":2, "value":"Faulty Product", "parent_choice_id":22, "choices":[ ] }, { "id":127, "position":3, "value":"Item Not Delivered", "parent_choice_id":22, "choices":[ ] } ] } # Custom Text with section mapping { "id":27, "name":"cf_feedback", "label":"Feedback", "label_for_customers":"Feedback", "position":17, "type":"custom_text", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2020-01-27T07:12:48Z", "updated_at":"2020-01-27T07:12:48Z", "archived":false, "section_mappings":[ { "section_id":1, "position":3 } ] } # Dependent Field { "ticket_field":{ "id":28, "name":"cf_bank964807", "label":"Bank", "label_for_customers":"Bank", "position":13, "type":"nested_field", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2020-01-27T07:19:59Z", "updated_at":"2020-01-27T07:19:59Z", "archived":false, "choices":[ { "id":6, "position":1, "value":"HDFC", "parent_choice_id":28, "choices":[ { "id":7, "position":1, "value":"Chennai", "parent_choice_id":6, "choices":[ { "id":8, "position":1, "value":"Porur", "parent_choice_id":7, "choices":[ ] }, { "id":9, "position":2, "value":"OMR", "parent_choice_id":7, "choices":[ ] } ] }, { "id":10, "position":2, "value":"Madurai", "parent_choice_id":6, "choices":[ { "id":11, "position":1, "value":"Thirumangalam", "parent_choice_id":10, "choices":[ ] }, { "id":12, "position":2, "value":"SB Colony", "parent_choice_id":10, "choices":[ ] } ] } ] }, { "id":13, "position":2, "value":"SBI", "parent_choice_id":28, "choices":[ { "id":14, "position":1, "value":"Chennai", "parent_choice_id":13, "choices":[ { "id":15, "position":1, "value":"Tambaram", "parent_choice_id":14, "choices":[ ] }, { "id":16, "position":2, "value":"Guindy", "parent_choice_id":14, "choices":[ ] } ] }, { "id":17, "position":2, "value":"Trichy", "parent_choice_id":13, "choices":[ { "id":18, "position":1, "value":"AGS Colony", "parent_choice_id":17, "choices":[ ] } ] } ] }, { "id":19, "position":3, "value":"ICICI", "parent_choice_id":28, "choices":[ { "id":20, "position":1, "value":"Chennai", "parent_choice_id":19, "choices":[ { "id":21, "position":1, "value":"Avadi", "parent_choice_id":20, "choices":[ ] } ] } ] } ], "dependent_fields":[ { "id":29, "name":"cf_district", "label":"District", "label_for_customers":"District", "level":2, "ticket_field_id":28, "created_at":"2020-01-27T07:19:59Z", "updated_at":"2020-01-27T07:19:59Z" }, { "id":30, "name":"cf_branch53114", "label":"Branch", "label_for_customers":"Branch", "level":3, "ticket_field_id":28, "created_at":"2020-01-27T07:19:59Z", "updated_at":"2020-01-27T07:19:59Z" } ] } } |
View a Ticket Field
/api/v2/admin/ticket_fields/[id]
Sample code | Curl
1 2 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22?include=section' curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/16?include=section' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 | { "id":22, "name":"cf_issue_type_297457", "label":"Issue Type", "label_for_customers":"Issue Type", "position":1, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-19T05:28:31Z", "updated_at":"2019-12-19T05:28:31Z", "has_section":true, "sections":[ { "id":1, "label":"Ecosystem Type", "parent_ticket_field_id":22, "choice_ids":[ 6 ], "ticket_field_ids":[ 16 ] } ], "choices":[ { "id":125, "position":1, "value":"Refund", "parent_choice_id":22, "choices":[ ] }, { "id":126, "position":2, "value":"Faulty Product", "parent_choice_id":22, "choices":[ ] }, { "id":127, "position":3, "value":"Item Not Delivered", "parent_choice_id":22, "choices":[ ] } ] } { "id":16, "name":"cf_mobile_os_type", "label":"Mobile OS Type", "label_for_customers":"Mobile OS Type", "position":5, "type":"custom_text", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2020-01-03T09:45:03Z", "updated_at":"2020-01-03T09:45:15Z", "section_mappings":[ { "section_id":1, "position":1 } ] } |
Update a Ticket Field
/api/v2/admin/ticket_fields/[id]
To Edit the contents of a ticket field, use this API
JSON Parameters
Attribute | Type | Description |
---|---|---|
customers_can_edit | boolean | To specify whether the customer can edit the ticket field |
label_for_customers | string | Ticket Field name to be displayed to customers |
displayed_to_customers | boolean | Display Ticket Field to customers |
label | string | Display the name of the Ticket Field |
type | string | Ticket Field type. Can be custom_dropdown, custom_checkbox, custom_text, etc... |
position | number | Position in which the ticket field is displayed in the form. If not given, it will be displayed on top |
required_for_closure | boolean | Set to true if the field is mandatory for closing the ticket |
required_for_agents | boolean | Set to true if the field is mandatory for Agents |
required_for_customers | boolean | Set to true if the field is mandatory in the customer portal |
choices (Applicable for dropdown) | Array of dictionary | Array of key, value pairs containing the value and position of dropdown choices |
dependent_fields | Array of dictionary | Applicable only for dependent fields, this contains details of nested fields |
section_mappings | Array of dictionary | Applicable only if the field is part of a section. This contains the details of a section (ID, position) for which it is been a part of |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label_for_customers":"Issue Type", "label":"Issue Type", "position": 2, choices":[{ "deleted":true,"id":131 },{ "value":"Returns/Refund","id":129 },{ "value":"Faulty Product","id":130 },{ "value":"payments", "position":4 }] }' 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | { "id":23, "name":"cf_issue_type_dropdown", "label":"Issue Type", "label_for_customers":"Issue Type", "position":2, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-19T06:14:40Z", "updated_at":"2019-12-19T06:56:07Z", "choices":[ { "id":129, "position":1, "value":"Returns/Refund", "parent_choice_id":23, "choices":[ ] }, { "id":130, "position":2, "value":"Faulty Product", "parent_choice_id":23, "choices":[ ] }, { "id":133, "position":3, "value":"Payments", "parent_choice_id":23, "choices":[ ] } ] } |
Delete a Ticket Field
/api/v2/admin/ticket_fields/[id]
Note: Be cautious about deleting a Ticket Field since this action is irreversible. You will not be able to restore a ticket field if you delete it.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22' |
Response
1 | HTTP Status: 204 No Content |
Sections
This feature helps you to configure custom sections/section-fields for your Ticket field.
JSON Parameters
Section Attributes | Description |
---|---|
id | ID of the section |
label | Display name of the section |
parent_ticket_field_id | Ticket Field ID to which the section is mapped |
ticket_field_ids | Ticket Field IDs associated with the section (Ticket fields that are displayed as part of the section) |
is_fsm | Set to true if the ticket field is a FSM field (Field Service Management) |
choice_ids | Set of Choice IDs mapped to the section. The section will be displayed on choosing any one of the choices |
List All Sections for a Ticket Field
/api/v2/admin/ticket_fields/[id]/sections
To view all section details related to a ticket field, use this API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/20/sections' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "sections":[ { "id":3, "label":"Environment Type (Mobile)", "parent_ticket_field_id":20, "choice_ids":[ 121 ], "ticket_field_ids":[ 19 ], "is_fsm":false }, { "id":4, "label":"Environment Type (Web)", "parent_ticket_field_id":20, "choice_ids":[ 120 ], "ticket_field_ids":[ ], "is_fsm":false } ] } |
Create a Section
/api/v2/admin/ticket_fields/[id]/sections
To create a new section, use the following APIs.
Parameters
Attribute | Type | Description |
---|---|---|
label | string | Display the name of the section |
choice_ids | Array of numbers | Choice IDs for which the section to be displayed |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "label":"Environment Type (Web)", "choice_ids":[120] }' https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "sections":[ { "id":3, "label":"Environment Type (Mobile)", "parent_ticket_field_id":20, "choice_ids":[ 121 ], "ticket_field_ids":[ 19 ], "is_fsm":false }, { "id":4, "label":"Environment Type (Web)", "parent_ticket_field_id":20, "choice_ids":[ 120 ], "ticket_field_ids":[ ], "is_fsm":false } ] } |
List a specific Section details
/api/v2/admin/ticket_fields/[id]/sections/[section_id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "section":{ "id":3, "label":"Environment Type (Web)", "parent_ticket_field_id":20, "choice_ids":[ 121 ], "ticket_field_ids":[ 19 ], "is_fsm":false } } |
Update a section
/api/v2/admin/ticket_fields/[id]/sections/[section_id]
To Edit the section, use this API
Parameters
Attribute | Type | Description |
---|---|---|
label | string | Display the name of the section |
choice_ids | Array of numbers | Choice IDs for which the section to be displayed |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label":"Environment Type (Mac OS)", "choice_ids":[134] }' 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "section":{ "id":3, "label":"Environment Type (Mac OS)", "parent_ticket_field_id":20, "choice_ids":[ 134 ], "ticket_field_ids":[ 19 ], "is_fsm":false } } |
Delete a section
/api/v2/admin/ticket_fields/[id]/sections/[section_id]
Note:
Be cautious about deleting a Section since this action is irreversible. You will not be able to restore a Section if you delete it.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3' |
Response
1 | HTTP Status: 204 No Content |
Ticket Forms
Note: Only users with admin privileges can access the following APIs.
Ticket forms allow you to show the right form to your customers depending on what they want to contact you about. You can create forms for different customer issues (eg: Returns, refunds, etc.), different product portals, or both.
JSON Parameters
Form Attributes | Description |
---|---|
id | ID of the ticket form |
title Mandatory | Name of the ticket form |
default | Set to true if the ticket form is the default form |
description | Description of the ticket form |
portals | Lists all the portals that are associated with the ticket form |
fields Mandatory | List of ticket fields which are added to the ticket form. Click here to see mandatory field attributes. |
last_updated_by | ID of the agent that last updated the form |
List All Ticket Forms
/api/v2/ticket-forms
Note:
The agent whose credentials (identified by the API key) are used to make the API call should be authorised to either view the ticket forms or create a new ticket form
Form Attributes
Form Attribute | Description |
---|---|
id | ID of the ticket form |
title | Name of the ticket form |
default | Set to true if the form is the default form |
description | Description of the ticket form |
portals | Lists all the portals that are associated with the ticket form |
widgets | Lists all the widgets that are associated with the ticket form |
last_updated_by | ID of the agent that last updated the form |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms?include=portals' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | [ { "id": 1, "name": "report_an_issue", "title": "Report an issue", "default": true, "description": "This form has all fields that customers can view or edit.", "created_at": "2022-05-25T10:43:01Z", "updated_at": "2022-06-01T10:21:34Z", "last_updated_by": 51020877290, "portals": [] }, { "id": 2, "name": "return_items", "title": "Return items", "default": false, "description": "Form to raise return requests on Acme portal", "created_at": "2022-05-27T10:33:34Z", "updated_at": "2022-05-31T10:06:26Z", "last_updated_by": 51020877290, "portals": [ { "id": 1, "name": "portal 1" } ] } ] |
Create a Ticket Form
/api/v2/ticket-forms
To create a new ticket form, use the following APIs.
Note: A form can not be created without the requester and company field
JSON Parameters
Attribute | Type | Description |
---|---|---|
title Mandatory | string | Name of the ticket form |
description | string | Description of the ticket form |
fields Mandatory | Array of dictionary | The fields the form should contain. Click here to see mandatory field attributes. |
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | # Custom ticket form curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "title": "Custom ticket form", "description": "This is a custom ticket form", "fields": [{ "id": 1, "label_for_customers": "requester", "customers_can_edit": true, "required_for_customers": true, "placeholder_for_customers": "requester", "hint_for_customers": "requester" }, { "id": 2, "label_for_customers": "company", "customers_can_edit": true, "required_for_customers": true, "placeholder_for_customers": "company", "hint_for_customers": "company" }] }' https://domain.freshdesk.com/api/v2/ticket-forms' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 | # custom ticket form { "id": 2, "name": "custom_ticket_form", "title": "Custom ticket form", "default": false, "description": "This is a custom ticket form", "created_at": "2022-06-01T14:10:59Z", "updated_at": "2022-06-01T14:10:59Z", "last_updated_by": 51020877290, "portals": [], "fields": [ { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "requester", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-06-01 14:10:59", "updated_at": "2022-06-01 14:10:59", "archived": false, "portal_cc": "false", "portal_cc_to": "company", "hint_for_customers": "requester", "placeholder_for_customers": "requester" }, { "id": 2, "name": "company", "label": "Company", "label_for_customers": "company", "position": 2, "type": "default_company", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-06-01 14:10:59", "updated_at": "2022-06-01 14:10:59", "archived": false, "hint_for_customers": "company", "placeholder_for_customers": "company" } ] } |
View a Ticket Form
/api/v2/ticket-forms/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | { "id": 2, "name": "return_items", "title": "Return items", "default": true, "description": "Form to raise return requests on Acme portal", "created_at": "2022-05-25T10:43:01Z", "updated_at": "2022-06-01T10:21:34Z", "last_updated_by": 51020877290, "portals": [], "fields": [ { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false, "portal_cc": "false", "portal_cc_to": "company" }, { "id": 2, "name": "subject", "label": "Subject", "label_for_customers": "Subject", "position": 2, "type": "default_subject", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false }, { "id": 3, "name": "status", "label": "Status", "label_for_customers": "Status", "position": 5, "type": "default_status", "default": true, "customers_can_edit": false, "required_for_closure": false, "required_for_agents": true, "required_for_customers": false, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false }, { "id": 4, "name": "agent", "label": "Agent", "label_for_customers": "Assigned to", "position": 8, "type": "default_agent", "default": true, "customers_can_edit": false, "required_for_closure": false, "required_for_agents": false, "required_for_customers": false, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false }, { "id": 5, "name": "description", "label": "Description", "label_for_customers": "Description", "position": 10, "type": "default_description", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false }, { "id": 6, "name": "company", "label": "Company", "label_for_customers": "Company", "position": 11, "type": "default_company", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-27 11:17:47", "archived": false } ] } |
Update a Ticket Form
/api/v2/ticket-forms/[id]
To edit the contents of a ticket form, use the following API
JSON Parameters
Attribute | Type | Description |
---|---|---|
title Mandatory | string | Name of the ticket form |
description | string | Description of the ticket form |
fields Mandatory | Array of dictionary | The fields the form should contain. Click here to see mandatory field attributes. |
Sample code | Curl
1 2 3 4 | 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/ticket-forms/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | { "id": 1, "name": "updated_returns_form", "title": "Updated returns form", "default": false, "description": "New returns form for summer sale", "created_at": "2022-05-31T06:53:48Z", "updated_at": "2022-06-01T14:31:25Z", "last_updated_by": 51020877290, "portals": [], "fields": [ { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester details", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-31 06:53:48", "updated_at": "2022-05-31 09:02:28", "archived": false, "portal_cc": "false", "portal_cc_to": null }, { "id": 2, "name": "company", "label": "Company", "label_for_customers": "Company", "position": 2, "type": "default_company", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-31 06:53:48", "updated_at": "2022-05-31 06:53:48", "archived": false } ] } |
Delete a Ticket Form
/api/v2/ticket-forms/[id]
Note: Be cautious about deleting a ticket form since this action is irreversible. You will not be able to restore a ticket form if you delete it.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/ticket-forms/2' |
Response
1 | HTTP Status: 204 No Content |
Clone a Ticket Form
/api/v2/ticket-forms/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/2/clone' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | { "id": 3, "name": "copy_of_custom_ticket_form", "title": "Copy of custom ticket form", "default": false, "description": "", "created_at": "2022-05-25T10:43:01Z", "updated_at": "2022-06-01T10:21:34Z", "last_updated_by": 51020877290, "portals": [], "fields": [ { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false, "portal_cc": "false", "portal_cc_to": "company" }, { "id": 2, "name": "subject", "label": "Subject", "label_for_customers": "Subject", "position": 2, "type": "default_subject", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false } ] } |
Ticket Form Fields
Note: Only users with admin privileges can access the following APIs.
The ticket form fields in Freshdesk have the following properties.
JSON Parameters
Form Fields | Description |
---|---|
id | ID of the form field |
name | Name of the form field |
label | Display name for the form field (as seen by agents) |
label_for_customers Mandatory | Display name for the form field (as seen in the customer portal) |
position | Position in which the form field is displayed in the form |
type | Details on whether the form field is a custom or a default field. If it is a custom field, details on the field type (dropdown, decimal, date, etc.) |
default | True if the form field is a default form field |
customers_can_edit Mandatory | Set to true if the form field can be updated by customers |
required_for_closure | Set to true if the form field is mandatory for closing the ticket |
required_for_agents | Set to true if the form field is mandatory for Agents |
required_for_customers Mandatory | Set to true if the form field is displayed in the portal |
displayed_to_customers | Set to true if the form field is displayed in the portal |
portal_cc | Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket |
portal_cc_to | Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list |
hint_for_customes Mandatory | Can see the tooltip for the form field in the form |
placeholder_for_customers Mandatory | Can see the placeholder for the form field in the form |
View A Ticket Form's Field
/api/v2/ticket-forms/[form-id]/fields/[field-id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/1/fields/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester email", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-27 10:33:34", "updated_at": "2022-05-31 09:25:06", "archived": false, "portal_cc": null, "portal_cc_to": null, "hint_for_customers": "Requester email", "placeholder_for_customers": "Requester Email" } |
Update A Ticket Form's Field
/api/v2/ticket-forms/[form-id]/fields/[field-id]
To edit the contents of a ticket form field, use the following API
JSON Parameters
Attribute | Type | Description |
---|---|---|
id Mandatory * | Integer | ID of the ticket field (* mandatory only when creating a form) |
label_for_customers Mandatory | string | Name of the form field |
customers_can_edit Mandatory | boolean | Set to true if the field can be updated by customers |
required_for_customers Mandatory | boolean | Set to true if the field is displayed in the portal |
hint_for_customers Mandatory | string | Can see the tooltip for the form field in the form |
placeholder_for_customers Mandatory | string | Can see the placeholder for the form field in the form |
position | Integer | Position in which the form field is displayed in the form |
Sample code | Curl
1 2 3 4 5 6 7 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label_for_customers": "Requester email", "customers_can_edit": true, "required_for_customers": true, "hint_for_customers": "Requester email", "placeholder_for_customers": "Requester Email" }' 'https://domain.freshdesk.com/api/v2/ticket-forms/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester email", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-27 10:33:34", "updated_at": "2022-05-31 09:25:06", "archived": false, "portal_cc": null, "portal_cc_to": null, "hint_for_customers": "Requester email", "placeholder_for_customers": "Requester Email" } |
Conversations
Conversations consist of replies as well as public and private notes added to a ticket. Notes are non-invasive ways of sharing updates about a ticket amongst agents and customers. Private notes are for collaboration between agents and are not visible to the customer. Public notes are visible to, and can be created by, both customers and agents.
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments associated with the conversation. The total size of all of a ticket's attachments cannot exceed 20MB. |
body | string | Content of the conversation in HTML |
body_text | string | Content of the conversation in plain text |
id | number | ID of the conversation |
incoming | boolean | Set to true if a particular conversation should appear as being created from outside (i.e., not through web portal) |
to_emails | array of strings | Email addresses of agents/users who need to be notified about this conversation |
private | boolean | Set to true if the note is private |
source | number | Denotes the type of the conversation. |
support_email | string | Email address from which the reply is sent. For notes, this value will be null. |
ticket_id | number | ID of the ticket to which this conversation is being added |
user_id | number | ID of the agent/user who is adding the conversation |
last_edited_at | datetime | Timestamp when the conversation last edited |
last_edited_user_id | number | ID of the agent who has last edited the conversation |
created_at | datetime | Conversation creation timestamp |
updated_at | datetime | Conversation updated timestamp |
Conversation Properties
Conversation use certain fixed numerical values to denote their Source. These numerical values along with their meanings are given below.
Note:
This source attribute will be returned in the response body of the List All Conversations of a Ticket and View a ticket (only when 'include=conversation' is passed in url) endpoints.
Source | Value | |
---|---|---|
Reply | 0 | |
Note | 2 | |
Created from tweets | 5 | |
Created from survey feedback | 6 | |
Created from Facebook post | 7 |
Source Type | Value | |
---|---|---|
Created from Forwarded Email | 8 | |
Created from Phone | 9 | |
E-Commerce | 11 |
Create a Reply
/api/v2/tickets/[id]/reply
Parameters
Attribute | Type | Description |
---|---|---|
body † | string | Content of the note in HTML format |
attachments | array of attachment objects | Attachments. The total size of all the ticket's attachments (not just this note) cannot exceed 20MB. |
from_email | string | The email address from which the reply is sent. By default the global support email will be used. |
user_id | number | ID of the agent who is adding the note |
cc_emails | array of strings | Email address added in the 'cc' field of the outgoing ticket email. |
bcc_emails | array of strings | Email address added in the 'bcc' field of the outgoing ticket email. |
† Mandatory attribute |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"We are working on this issue. Will keep you posted." }' 'https://domain.freshdesk.com/api/v2/tickets/141/reply' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "body_text" : "We are working on this issue. Will keep you posted.", "body" : "<div>We are working on this issue. Will keep you posted.</div>", "id" : 4, "user_id" : 1, "from_email" : "support@yourcompany.com", "cc_emails" : [ ], "bcc_emails" : [ ], "ticket_id" : 141, "replied_to" : [ "sample@yourcustomer.com" ], "attachments" : [ ], "created_at" : "2015-08-24T13:36:42Z", "updated_at" : "2015-08-24T13:36:42Z" } |
Reply to a Ticket With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.txt" -F "body=this is a sample reply" -X POST 'https://domain.freshdesk.com/api/v2/tickets/27/reply' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "body_text" : "this is a sample reply", "body" : "<div>this is a sample reply</div>", "id" : 125, "user_id" : 1, "from_email" : "support@yourcompany.com", "cc_emails" : [ ], "bcc_emails" : [ ], "ticket_id" : 27, "replied_to" : [ "sample@yourcustomer.com" ], "attachments" : [ { "id" : 6013284906, "content_type" : "text/plain", "size" : 98, "name" : "data.txt", "attachment_url" : "https://cdn.freshdesk.com/data/helpdesk/attachments/production/6013284906/original/attachment1.txt", "created_at" : "2016-01-13T07:07:41Z", "updated_at" : "2016-01-13T07:07:41Z" } ], "created_at" : "2016-01-13T07:07:41Z", "updated_at" : "2016-01-13T07:07:41Z" } |
Create a Note
/api/v2/tickets/[ticket_id]/notes
Note:
By default, any note that you add will be private. If you wish to add a public note, set the
Parameters
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments associated with the note. The total size of all of a ticket's attachments cannot exceed 20MB. |
body † | string | Content of the note in HTML |
incoming | boolean | Set to true if a particular note should appear as being created from outside (i.e., not through web portal). The default value is false |
notify_emails | array of strings | Email addresses of agents/users who need to be notified about this note |
private | boolean | Set to true if the note is private. The default value is true. |
user_id | number | ID of the agent/user who is adding the note |
† Mandatory attribute |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "private":false, "notify_emails":["tom@yourcompany.com"] }' 'https://domain.freshdesk.com/api/v2/tickets/3/notes' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "body_text" : "Hi tom, Still Angry", "body" : "<div>Hi tom, Still Angry</div>", "id" : 5, "incoming" : false, "private" : false, "user_id" : 1, "support_email" : null, "ticket_id" : 3, "notified_to" : ["tom@yourcompany.com"], "attachments" : [ ], "created_at" : "2015-08-24T13:49:37Z", "updated_at" : "2015-08-24T13:49:37Z" } |
Create a Note With Attachment
Note:
This API request must have its content-type set to multipart/form-data.
Sample code | Curl
1 | curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.ext" -F "body=Hi tom, Still Angry" -F "notify_emails[]=tom@yourcompany.com" -X POST 'https://domain.freshdesk.com/api/v2/tickets/20/notes' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "body_text" : "Hi tom, Still Angry", "body" : "<div>Hi tom, Still Angry</div>", "id" : 5, "incoming" : false, "private" : false, "user_id" : 1, "support_email" : null, "ticket_id" : 20, "notified_to" : ["tom@yourcompany.com"], "attachments" : [ { "id":4004881085, "content_type":"image/jpeg", "file_size":44115, "name":"attachment1.jpg", "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment1.jpg" "created_at":"2014-07-28T16:20:03+05:30", "updated_at":"2014-07-28T16:20:03+05:30", } ], "created_at" : "2015-08-24T13:49:37Z", "updated_at" : "2015-08-24T13:49:37Z" } |
Update a conversation
/api/v2/conversations/[id]
Note:
Only public & private notes can be edited.
Parameters
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments associated with the note. The total size of all of a ticket's attachments cannot exceed 20MB. |
body | string | Content of the note in HTML |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "body":"Can you provide some screenshots?" }' 'https://domain.freshdesk.com/api/v2/conversations/5' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "body_text" : "Can you provide some screenshots?", "body" : "<div>Can you provide some screenshots?</div>", "id" : 5, "incoming" : false, "private" : false, "user_id" : 1, "support_email" : null, "ticket_id" : 20, "notified_to" : ["tom@yourcompany.com"], "attachments" : [ ], "created_at" : "2015-08-24T13:49:37Z", "updated_at" : "2015-08-24T13:49:37Z" } |
Update a conversation With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.txt" -F "body=updated conversation" -X PUT 'https://domain.freshdesk.com/api/v2/conversations/6' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | { "body_text" : "updated conversation", "body" : "updated conversation", "id" : 6, "incoming" : false, "private" : false, "user_id" : 1, "support_email" : null, "ticket_id" : 20, "attachments" : [ { "id":4004881085, "content_type":"image/jpeg", "file_size":44115, "name":"attachment1.jpg", "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment1.txt" "created_at":"2014-07-28T16:20:03+05:30", "updated_at":"2014-07-28T16:20:03+05:30", } ], "created_at" : "2015-08-24T13:49:37+05:30", "updated_at" : "2014-07-28T16:20:03+05:30" } |
Reply to Forward
/api/v2/tickets/[id]/reply_to_forward
Attribute | Type | Description |
---|---|---|
body Mandatory | string | Content of the note in HTML format |
body_text | string | Content of the note in plain text |
user_id | number | ID of the agent/user who is replying to the forwarded email |
ticket_id | number | ID of the ticket to which the reply is added |
to_emails Mandatory | array of strings | Emails to which the reply is addressed |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "to_emails": ["user@company.com"]}' 'https://domain.freshdesk.com/api/v2/tickets/3/reply_to_forward' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "body":"<div>Hi tom, Still Angry</div>", "body_text":"Hi tom, Still Angry", "id":35131397084, "incoming":false, "private":true, "user_id":35008297863, "support_email":"support@supporttasks.freshdesk.com", "Source":2, "category":6, "ticket_id":3, "to_emails":["user@company.com"], "from_email":"\"Agent Bob\" <support@domain.freshdesk.com>", "cc_emails":[], "bcc_emails":[], "email_failure_count":null, "outgoing_failures":null, "created_at":"2020-08-24T06:05:34Z", "updated_at":"2020-08-24T06:05:34Z", "attachments":[], "deleted":false, "last_edited_at":null, "last_edited_user_id":null, "cloud_files":[], "has_quoted_text":true } |
View Account
/api/v2/account
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/account' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { organisation_id: 284960733419037820, organisation_name: "dailyplanet.myfreshworks.com", account_id: 1840509, account_name: "Daily Planet", account_domain: "dailyplanet.freshdesk.com", bundle_id: null, hipaa_compliant: false, total_agents: { full_time: 1, occasional: 1, field_service: 0, collaborators: 0 }, timezone: "Eastern Time (US & Canada)", data_center: "US", tier_type: "Forest", address: { country: USA, state: California, city: San Mateo CA , street: S. Delaware Street, postalcode: 94403 }, contact_person: { firstname: "Clark", lastname: "Kent", email: "clarkkent1@gmail.com" } } |
Export Account
api/v2/account/export
You can export your account data depending on the data which you specifically need. You can configure it based on created date range, resources and export format.
Note:
Only Account admin can access the following APIs.
Attribute | Type | Description |
---|---|---|
date_range | dictionary | Provide date range within which the data was created |
resources | Array of dictionary | Provide information about the resources that can be added to the export |
output_format | string | Format of export data. eg: "json" |
Date Range Attribute | Description | |
---|---|---|
start_date | Start date of export data. eg: 2020-04-21T13:03:00Z | |
end_date | End date of export data. eg: 2020-04-21T13:03:00Z |
Resources Attribute | Type | Description | |
---|---|---|---|
name | string | Resources to be included in export data eg. tickets, contacts | |
include | Array of String | Additional resources to be included within resource |
Resource Name | Allowed include parameters | |
---|---|---|
tickets | "notes", "attachments", "ticket_states", "schema_less_ticket", "requester" | |
archive_tickets | "notes", "attachments" | |
contacts | ||
companies | "company_domains" | |
groups | "agent_groups" | |
forums | "posts" | |
canned_responses | "all_canned_responses" | |
surveys | "survey_handles", "survey_results", "survey_questions" | |
solutions |
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "date_range": { "start_date": "2020-04-21T13:03:00Z", "end_date": "2021-04-21T13:03:00Z" }, "resources": [ { "name": "tickets", "include": ["notes", "attachments", "ticket_states"] }, { "name": "archive_tickets", "include": ["notes", "attachments"] }, { "name": "contacts" }, { "name": "companies", "include": ["company_domains"] }, { "name": "groups", "include": ["agent_groups"] }, { "name": "forums", "include": ["posts"] }, { "name": "canned_responses", "include": ["all_canned_responses"] }, { "name": "surveys", "include": ["survey_handles", "survey_results", "survey_questions"] }, { "name": "solutions" } ], "output_format": "json" }' 'https://domain.freshdesk.com/api/v2/account/export' |
Response
1 2 3 4 5 6 7 8 9 | { "job" : { "id" : 432, "link": { "href" : "dailyplanet.freshdesk.com/api/v2/jobs/432", "method" : "GET" } } } |
View a Job
/api/v2/jobs/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/jobs/432' |
Response
1 2 3 4 5 6 7 8 9 | { "id" : "432", "name" : "ACCOUNT::EXPORT", "status" : "IN PROGRESS", "created_at" : "2015-08-28T11:47:58Z", "updated_at" : "2015-08-28T11:47:58Z", "status_updated_at" : "2015-08-28T11:47:58Z", "progress" : 80, } |
Contacts
A contact is a customer or a potential customer who has raised a support ticket through any channel.
Attribute | Type | Description |
---|---|---|
active | boolean | Set to true if the contact has been verified |
address | string | Address of the contact |
avatar | object | Avatar of the contact |
company_id | number | ID of the primary company to which this contact belongs |
view_all_tickets | boolean | Set to true if the contact can see all tickets that are associated with the company to which he belong |
custom_fields | dictionary | Key value pair containing the name and value of the custom fields. Read more here |
deleted | boolean | Set to true if the contact has been deleted. Note that this attribute will only be present for deleted contacts |
description | string | A short description of the contact |
string | Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute | |
id | number | ID of the contact |
job_title | string | Job title of the contact |
language | string | Language of the contact |
mobile | string | Mobile number of the contact |
name | string | Name of the contact |
other_emails | array of strings | Additional emails associated with the contact |
phone | string | Telephone number of the contact |
tags | array of strings | Tags associated with this contact |
time_zone | string | Time zone in which the contact resides |
twitter_id | string | Twitter handle of the contact |
unique_external_id | string | External ID of the contact |
other_companies | array of hashes | Additional companies associated with the contact |
created_at | datetime | Contact creation timestamp |
updated_at | datetime | Contact updated timestamp |
Create a Contact
/api/v2/contacts
Parameters
Attribute | Type | Description |
---|---|---|
nameMandatory | string | Name of the contact |
email *Unique | string | Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute. |
phone * | string | Telephone number of the contact |
mobile * | string | Mobile number of the contact |
twitter_id *Unique | string | Twitter handle of the contact |
unique_external_id *Unique | string | External ID of the contact |
other_emails | array of strings | Additional emails associated with the contact |
company_id | number | ID of the primary company to which this contact belongs |
view_all_tickets | boolean | Set to true if the contact can see all the tickets that are associated with the company to which he belong |
other_companies | array of hashes | Additional companies associated with the contact. This attribute can only be set if the Multiple Companies feature is enabled (Estate plan and above) |
address | string | Address of the contact. |
avatar | object | Avatar image of the contact The maximum file size is 5MB and the supported file types are .jpg, .jpeg, .jpe, and .png |
custom_fields | dictionary | Key value pairs containing the name and value of the custom field. Only dates in the format YYYY-MM-DD are accepted as input for custom date fields. Read more here |
description | string | A small description of the contact |
job_title | string | Job title of the contact |
language | string | Language of the contact. Default language is "en". This attribute can only be set if the Multiple Language feature is enabled (Garden plan and above) |
tags | array of strings | Tags associated with this contact |
time_zone | string | Time zone of the contact. Default value is the time zone of the domain. This attribute can only be set if the Multiple Time Zone feature is enabled (Garden plan and above) |
lookup_parameter | string | This attribute for contacts can only be set if the Custom Objects feature is enabled. The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
*One of these four attributes is mandatory |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "name":"Super Man", "email":"superman@freshdesk.com", "other_emails": ["lex@freshdesk.com", "louis@freshdesk.com"] }' 'https://domain.freshdesk.com/api/v2/contacts' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "active": false, "address": null, "company_id":23, "view_all_tickets":false, "deleted": false, "description": null, "email": "superman@freshdesk.com", "id": 432, "job_title": null, "language": "en", "mobile": null, "name": "Super Man", "phone": null, "time_zone": "Chennai", "twitter_id": null, "other_emails":["lex@freshdesk.com","louis@freshdesk.com"], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "created_at": "2015-08-28T09:08:16Z", "updated_at": "2015-08-28T09:08:16Z", "tags": [ ], "avatar": null } |
Create a contact with a custom object record associated
Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #12345, here the primary_field_value will be “12345”
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "name":"Super Man", "email":"superman@freshdesk.com", "other_emails": ["lex@freshdesk.com", "louis@freshdesk.com"], "lookup_parameter" : "primary_field_value", "custom_fields" : { "order_number" : "12345" } }' 'https://domain.freshdesk.com/api/v2/contacts' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | { "active": false, "address": null, "company_id":23, "view_all_tickets":false, "deleted": false, "description": null, "email": "superman@freshdesk.com", "id": 432, "job_title": null, "language": "en", "mobile": null, "name": "Super Man", "phone": null, "time_zone": "Chennai", "twitter_id": null, "other_emails":["lex@freshdesk.com","louis@freshdesk.com"], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "custom_fields":{ "order_number": "12345" }, "created_at": "2015-08-28T09:08:16Z", "updated_at": "2015-08-28T09:08:16Z", "tags": [ ], "avatar": null } |
Create a Contact With Avatar
Note:
1. This API request must have its content-type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F 'avatar=@/path/to/image.ext' -F 'name=Green Lantern' -F 'email=greenlantern@freshdesk.com' -X POST 'https://domain.freshdesk.com/api/v2/contacts' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | { "active":false, "address":null, "company_id":23, "view_all_tickets":false, "deleted":false, "description":null, "email":"greenlantern@freshdesk.com", "id":434, "job_title":null, "language":"en", "mobile":null, "name":"Green Lantern", "phone":null, "time_zone":"Chennai", "twitter_id":null, "other_emails":[ ], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z", "tags":[ ], "avatar":{ "avatar_url":"<AVATAR_URL>", "content_type":"application/octet-stream", "id":4, "name":"lantern.png", "size":13036, "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z" } } |
View a Contact
/api/v2/contacts/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/434' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | { "active": false, "address": null, "company_id":23, "view_all_tickets":false, "description": null, "email": "greenlantern@freshdesk.com", "id": 434, "job_title": null, "language": "en", "mobile": null, "name": "Green Lantern", "phone": null, "time_zone": "Chennai", "twitter_id": null, "other_emails": [], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "created_at": "2015-08-28T10:27:58Z", "updated_at": "2015-08-28T10:27:58Z", "custom_fields": { "department": "Operations" "fb_profile": null, "permanent": false }, "tags": [], "avatar": { "avatar_url": "<AVATAR_URL>", "content_type": "application/octet-stream", "id": 4, "name": "rails.png", "size": 13036, "created_at": "2015-08-28T10:27:58Z", "updated_at": "2015-08-28T10:27:58Z" } } |
List All Contacts
/api/v2/contacts
Use filters to view only specific contacts (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. All unblocked and undeleted contacts will be returned by default
Filter by | Handle |
---|---|
email, mobile, phone |
/api/v2/contacts?<filter>=<value> Example: /api/v2/contacts?email=superman@freshdesk.com /api/v2/contacts?email=bat%2Bman%40gmail.com (URL encoded bat+man@gmail.com) /api/v2/contacts?mobile=7654367287 /api/v2/contacts?phone=4352789885 |
company_id | /api/v2/contacts?company_id=45653 |
state | /api/v2/contacts?state=[blocked/deleted/unverified/verified] |
updated since | /api/v2/contacts?updated_since=2018-01-19T02:00:00Z |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | [ { "active":false, "address":null, "company_id":null, "description":null, "email":"rachel@freshdesk.com", "id":2, "job_title":null, "language":"en", "mobile":null, "name":"Rachel", "phone":null, "time_zone":"Chennai", "twitter_id":null, "created_at":"2015-08-18T16:18:14Z", "updated_at":"2015-08-24T09:25:19Z", "other_companies": [ 4, 9, 10 ], "custom_fields":{ "department": "Admin" "fb_profile": null, "permanent": true } }, { "active":false, "address":null, "company_id":null, "deleted":false, "description":null, "email":"superman@freshdesk.com", "id":432, "job_title":null, "language":"en", "mobile":null, "name":"Super Man", "phone":null, "time_zone":"Chennai", "twitter_id":null, "created_at":"2015-08-28T09:08:16Z", "updated_at":"2015-08-28T09:08:16Z", "other_companies": [ 29, 30 ], "custom_fields":{ "department": "Production", "fb_profile": "https://www.facebook.com/superman.567384", "permanent": true }, }, { "active":false, "address":null, "company_id":null, "description":null, "email":"greenlantern@freshdesk.com", "id":434, "job_title":null, "language":"en", "mobile":null, "name":"Green Lantern", "phone":null, "time_zone":"Chennai", "twitter_id":null, "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z", "custom_fields":{ "department": "Operations" "fb_profile": null, "permanent": false } }, ... ] |
Additional Examples
1. Get a list of contacts filtered by the email address. Since the email address is unique, you will get only one contact in the list.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?email=superman@gmail.com' |
2. Get the first 20 verified contacts. By default, the contacts will be returned in alphabetical order.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?state=verified&per_page=20' |
3. Get a list of contacts updated after a particular timestamp.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?updated_since=2018-01-19T02:00:00Z' |
Search Contacts
/api/v2/contacts/autocomplete?term=[keyword]
Search for a contact using their name.
Note:
1. The search is case insensitive.
2. You cannot search with a substring. For example, a contact "John Jonz" can be looked up using "john", "Joh", "Jonz" and "jon". But it will not be returned when you search for "hn" or "nz".
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts/autocomplete?term=John' |
Response
1 2 3 4 5 6 7 8 9 10 | [ { "id": 33, "name": "John Jonz" }, { "id": 456, "name": "John Steven Jonz" } ] |
Filter ContactsBETA
/api/v2/search/contacts?query=[query]
Use custom contact fields that you have created in your account to filter through the contacts and get a list of contacts matching the specified contact fields.
Note:
1. Deleted contacts will not be included in the results
2. The query must be URL encoded
3. Query can be framed using the name of the contact fields, which can be obtained from Contact Fields endpoint. Contact Fields are case sensitive
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
5. Logical operators AND, OR along with parentheses () can be used to group conditions
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
7. Input for date fields should be in UTC Format
8. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
9. To scroll through the pages add page parameter to the url. The page number starts with 1 and should not exceed 10
10. To filter for fields with no values assigned, use the null keyword
11. Please note that the updates will take a few minutes to get indexed, after which it will be available through API
Supported Contact Fields
Field | Type | Description |
---|---|---|
active | boolean | Set to true if the contact has been verified |
company_id | number | ID of the primary company to which this contact belongs |
twitter_id | string | Twitter handle of the contact |
string | Primary email address associated to the contact | |
phone | string | Telephone number of the contact |
mobile | string | Mobile number of the contact |
tag | string | Tag that has been associated to the contacts |
language | string | Language of the contact |
time_zone | string | Time zone in which the contact resides |
created_at | date | Contact creation date (YYYY-MM-DD) |
updated_at | date | Date (YYYY-MM-DD) when the contact was last updated |
Custom Fields | ||
Single line text | string | |
Number | integer | |
Checkbox | boolean | |
Dropdown | string |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true"' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "total":22, "results":[ { "active": true, "address": "11 Park Avenue,", "company_id": 331, "description": "alien hero", "email": "john@marsspace.com", "id": 112, "job_title": "Superhero", "language": "en", "mobile": "992339928", "name": "John Jonz", "phone": "+1992842882", "time_zone": "Eastern Time (US & Canada)", "twitter_id": "martian", "custom_fields": { "location": "Watch tower", "sector": "outer space" }, "created_at": "2017-07-19T12:29:36Z", "updated_at": "2017-07-19T12:38:26Z" }, ... ... ... ... ] } |
Additional Examples
1. Get the list of verified users associated to company 2331.
"active:true AND company_id:2331"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true%20AND%20company_id:2331"' |
2. Get the list of users created in the first week of October 2017 in Chennai time zone.
"time_zone:'Chennai' AND (created_at:>'2017-10-01' AND created_at:<'2017-10-07')"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="time_zone:%27Chennai%27%20AND%20(created_at:>%272017-10-01%27%20AND%20created_at:<%272017-10-07%27)"' |
Update a Contact
/api/v2/contacts/[id]
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the contact |
email Unique | string | Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute. |
phone | string | Telephone number of the contact |
mobile | string | Mobile number of the contact |
twitter_id Unique | string | Twitter handle of the contact |
unique_external_id Unique | string | External ID of the contact |
other_emails | array of strings | Additional emails associated with the contact |
company_id | number | ID of the primary company to which this contact belongs |
view_all_tickets | boolean | Set to true if the contact can see all the tickets that are associated with the company to which he belong |
other_companies | array of hashes | Additional companies associated with the contact. This attribute can only be updated if the Multiple Companies feature is enabled (Estate plan and above) |
address | string | Address of the contact. |
avatar | object | Avatar image of the contact The maximum file size is 5MB and the supported file types are .jpg, .jpeg, .jpe, and .png |
custom_fields | dictionary | Key value pairs containing the name and value of the custom field. Only dates in the format YYYY-MM-DD are accepted as input for custom date fields. Read more here |
description | string | A small description of the contact |
job_title | string | Job title of the contact |
language | string | Language of the contact. Default language is "en". This attribute can only be updated if the Multiple Language feature is enabled (Garden plan and above) |
tags | array of strings | Tags associated with this contact |
time_zone | string | Time zone of the contact. Default value is the time zone of the domain. This attribute can only be updated if the Multiple Time Zone feature is enabled (Garden plan and above) |
lookup_parameter | string | This attribute for contacts can only be set if the Custom Objects feature is enabled. The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT -d '{ "name":"Clark Kent", "job_title":"Journalist", "other_emails": ["louis@freshdesk.com", "jonathan.kent@freshdesk.com"] }' 'https://domain.freshdesk.com/api/v2/contacts/432' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "active":false, "address":null, "company_id":23, "view_all_tickets":false, "deleted":false, "description":null, "email":"superman@freshdesk.com", "id":432, "job_title":"Journalist", "language":"en", "mobile":null, "name":"Clark Kent", "phone":null, "time_zone":"Chennai", "twitter_id":null, "other_emails":["louis@freshdesk.com","jonathan.kent@freshdesk.com"], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "created_at":"2015-08-28T09:08:16Z", "updated_at":"2015-08-28T11:37:05Z", "tags":[], "avatar":null } |
Update the lookup field within a contact
Note:
1. The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #98765, here the primary_field_value will be “98765”
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT -d '{ "job_title":"Journalist", "lookup_parameter" : "primary_field_value", "custom_fields" : { "order_number" : "98765" } }' 'https://domain.freshdesk.com/api/v2/contacts/432' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | { "active": false, "address": null, "company_id":23, "view_all_tickets":false, "deleted": false, "description": null, "email": "superman@freshdesk.com", "id": 432, "job_title": "Journalist", "language": "en", "mobile": null, "name": "Super Man", "phone": null, "time_zone": "Chennai", "twitter_id": null, "other_emails":["lex@freshdesk.com","louis@freshdesk.com"], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "custom_fields":{ "order_number": "98765", }, "created_at": "2015-08-28T09:08:16Z", "updated_at": "2015-08-28T09:08:16Z", "tags": [ ], "avatar": null } |
Update a Contact With Avatar
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F 'avatar=@/path/to/image.ext' -F 'job_title=Superhero' -X PUT 'https://domain.freshdesk.com/api/v2/contacts/434' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "active":false, "address":null, "company_id":23, "view_all_tickets":false, "deleted":false, "description":null, "email":"greenlantern@freshdesk.com", "id":434, "job_title":'Superhero', "language":"en", "mobile":null, "name":"Green Lantern", "phone":null, "time_zone":"Chennai", "twitter_id":null, "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z", "tags":[], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "avatar":{ "avatar_url":"<AVATAR_URL>", "content_type":"application/octet-stream", "id":4, "name":"lantern.png", "size":13036, "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z" } } |
Permanently Delete a Contact
/api/v2/contacts/[id]/hard_delete
Hard delete a contact to completely remove it from the portal. Can be used for GDPR compliance.
Note:
1. API requires that the contact is already soft deleted. Otherwise, send a force parameter to be true.
2. All tickets related to the contact will also be deleted and cannot be retrieved later.
Parameters
Attribute | Type | Description |
---|---|---|
idMandatory | integer | Contact ID |
force | boolean | Send as true to force hard delete of a contact that is not already soft deleted |
*This attribute is mandatory |
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/contacts/432/hard_delete' |
Response
1 2 3 | HTTP Status: 204 No Content - Success HTTP Status: 400 No Content - User invalid (not soft deleted) HTTP Status: 404 No Content - User not found |
Additional Examples
1. Force delete a contact that is not soft deleted already.
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/contacts/432/hard_delete?force=true' |
Make Agent
/api/v2/contacts/[id]/make_agent
Note:
1. The contact must have an email address in order to be converted into an agent
2. If the contact has 'other_emails' they will be deleted after the conversion
3. If your account has already reached the maximum number of agents, the API request will fail with HTTP error code 403
4. The agent whose credentials (identified by the API key) are used to make the API call should be authorised to convert a contact into an agent.
5. If no request payload is given, this API will try to convert this contact to Full time agent with global ticket scope and role as Support Agent.
Parameters
Attribute | Type | Description |
---|---|---|
occasional | boolean | Set to true if this is an occasional agent (true => occasional, false => full-time) |
signature | string | Signature of the agent in HTML format |
ticket_scope | number | Ticket permission of the agent (1 -> Global Access, 2 -> Group Access, 3 -> Restricted Access). Current logged in agent can't update his/her ticket_scope |
skill_ids | array of numbers | Skill ids associated with the agent |
group_ids | array of numbers | Group IDs associated with the agent |
role_ids | array of numbers | Role IDs associated with the agent. At least one role should be associated with the agent. Current logged in agent can't update his/her role_ids (Role IDs should be corresponding to the type of agents. For example: Ticket collaborator for collaborator agent, Agent or admin for support agent) |
type | string | Type of Agent (support_agent -> Support Agent, field_agent -> Field Agent, collaborator -> Collaborator) By default, agent will be converted to a Support Agent |
focus_mode | boolean | Focus mode of the agent. Default value is true |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshdesk.com/api/v2/contacts/432/make_agent' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "active": false, "email": "superman@freshdesk.com", "job_title": "Journalist", "language": "en", "last_login_at": null, "mobile": null, "name": "Clark Kent", "phone": null, "time_zone": "Chennai", "created_at": "2015-08-28T09:08:16Z", "updated_at": "2015-08-28T11:47:58Z", "agent": { "available_since": null, "available": true, "occasional": false, "signature": null, "group_ids" : [ 4 ], "type":"support_agent", "role_ids" : [ 1 ], "id": 432, "ticket_scope": 1, "created_at": "2015-08-28T11:47:58Z", "updated_at": "2015-08-28T11:47:58Z", "focus_mode": true } } |
Additional Examples
1. Convert a contact to a collaborator (Collaborators Feature Required)
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "type":"collaborator" }' 'https://domain.freshdesk.com/api/v2/contacts/432/make_agent' |
Restore a Contact
api/v2/contacts/[id]/restore
Note:
Agent's name, phone, mobile number and job title can't be updated using the API. They can be updated from the Neo Admin Center.
Used to restore contacts that have been soft-deleted from a Freshdesk account.
Sample code | Curl
1 | curl -v -u yourapikey:X -X PUT 'https://domain.freshdesk.com/api/v2/contacts/432/restore' |
Response
1 | HTTP Status: 204 No Content |
Send Invite to a Contact
api/v2/contacts/[id]/send_invite
Used to send an activation email to an existing contact for email verification. Once the activation is complete, these contacts can log in to the customer portal using their password and check the status of their tickets. They can also access knowledge base articles or forums that are available only to users who are logged in.
Sample code | Curl
1 | curl -v -u yourapikey:X -X PUT 'https://domain.freshdesk.com/api/v2/contacts/432/send_invite' |
Response
1 | HTTP Status: 204 No Content |
Merge Contacts
api/v2/contacts/merge
Used to merge two or more duplicate contacts together.
Note:
Phone / Mobile / Twitter id / Unique External values are mandatory if they are present in both primary and secondary contacts.
Parameters
Attribute | Type | Description |
---|---|---|
primary_contact_idMandatory | integer | ID of the primary contact |
secondary_contact_ids Mandatory | array of integers | IDs of the secondary contacts |
contact | object | Contains attributes that need to be updated in the primary contact during merge (optional) |
Attribute | Type | Description |
---|---|---|
email Unique | string | Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute. |
phone | string | Telephone number of the contact |
mobile | string | Mobile number of the contact |
twitter_id Unique | string | Twitter handle ID of the contact |
unique_external_id Unique | string | External ID of the contact |
other_emails | array of strings | Additional emails associated with the contact |
company_ids | array of numbers | IDs of the companies associated with the contact |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "primary_contact_id":132, "secondary_contact_ids":[133,134,135], "contact": { "email": "rachel@freshdesk.com", "other_emails": ["louis@freshdesk.com", "jonathan.kent@freshdesk.com"], "company_ids": [1] }' 'https://domain.freshdesk.com/api/v2/contacts/merge' |
Response
1 | HTTP Status: 204 No Content |
Contact Export
In order to export contacts using the Freshdesk API, you'll need to make two different API calls.
Step 1: You'll first need to hit the following endpoint with details about your export. This will start the background job and get you a contact export ID.
api/v2/contacts/export
Parameters
Attribute | Type | Description |
---|---|---|
fieldsMandatory | object | Fields of the contacts to be exported |
Attribute | Type | Description |
---|---|---|
default_fields Mandatory | object | List of default fields of the contacts to be exported. |
custom_fields Mandatory | object | List of custom fields of the contacts to be exported. |
Tip: If you are not sure about what to include in this request, you can use the List All Contact Fields to get a list of all contact fields in your Freshdesk account.
Sample code | Curl
1 2 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "fields": { "default_fields": ["name", "email"], "custom_fields": [] } }' 'https://domain.freshdesk.com/api/v2/contacts/export' |
Response
1 2 3 | { "id": "d809986de1ed8a1abaeb363ac455e917b356e347" } |
Step 2: The contact export ID can be passed to another endpoint which will return a URL to the exported CSV file.
api/v2/contacts/export/[id]
This endpoint will return a valid URL to the CSV only when the export is done completely. The background job can take anywhere between a few seconds to several minutes to complete depending on the no of contacts and the no of fields you're including in your export. We recommend that you come up with a pre-defined interval and make the API call more than once in order to get the URL in the response.
Note: Every Freshdesk account will be restricted to running only one contact export at a time. Once the export is complete, the exported file can be accessed using the URL for 15 days, post which it will get removed automatically.
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST 'https://domain.freshdesk.com/api/v2/contacts/export/d809986de1ed8a1abaeb363ac455e917b356e347' |
Response
1 2 3 4 5 | { "id": "d809986de1ed8a1abaeb363ac455e917b356e347", "status": "completed", "download_url": "download_url" } |
Contact Import
List contact imports
This API allows you to fetch a list of up to 5 most recent contact imports that are either in-progress or have completed already. You can also filter your imports by status and list up to 5 of them in either state.
api/v2/contacts/imports
Filter by | Handle |
---|---|
Status | api/v2/contacts/imports?status=[in_progress/completed/cancelled/failed] |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/imports' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | [ { "id": 423678, "created_at": "2018-08-28T10:27:58Z", "status": "completed", "total_records": 250, "completed_records": 245, "failures": { "count": 5, "report": "url" } } ] |
View a contact import
Used to look up information about an import. In addition to its status, this API also returns an estimate for completion when the import is in progress and returns a list of failures when the import is complete.
api/v2/contacts/imports/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/imports/423678' |
Response
1 2 3 4 5 6 7 8 | { "id": 423678, "created_at": "2018-08-28T10:27:58Z", "status": "in_progress", "total_records": 250, "completed_records": 245, "estimated_time_remaining": "03:49:59" } |
Trigger a contact import
You can import contacts in bulk to a Freshdesk account by creating an import file and passing it to this API. This endpoint only supports CSV files (in UTF-8 format) and for the import to work properly, every row will need to include a minimum of two values - name and either an email address or phone number of the contact.
Note: For more information creating rows in your import file, please check out our solution article on importing your customer data into Freshdesk.
api/v2/contacts/imports
Parameters
Attribute | Type | Description |
---|---|---|
fileMandatory | object | CSV file to be imported. |
fieldsMandatory | object | Fields to be imported along with the index of the field as present in the import file. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: multipart/form-data' -F "file=@sample.csv" -F "fields[name]=0" -F "fields[email]=2" POST 'https://domain.freshdesk.com/api/v2/contacts/imports' |
Response
1 2 3 4 5 6 7 8 | { "id": 423678, "created_at": "2018-08-28T10:27:58Z", "status": "in_progress", "total_records": 250, "completed_records": 245, "estimated_time_remaining": "03:49:59" } |
Cancel a contact import
Used to cancel an import job that is currently in progress. Upon cancellation, this API will list the no of completed records it has imported already and also failures.
api/v2/contacts/imports/[id]/cancel
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT 'https://domain.freshdesk.com/api/v2/contacts/imports/423678/cancel' |
Response
1 2 3 4 5 6 7 8 9 10 11 | { "id": 423678, "created_at": "2018-08-28T10:27:58Z", "status": "cancelled", "total_records": 250, "completed_records": 245, "failures": { "count": 5, "report": "url" } } |
Contact Fields
Note: Only users with admin privileges can access the following APIs.
The custom and default contact fields in Freshdesk have the following properties.
Parameters
Contact Field | Description |
---|---|
editable_in_signup | Set to true if the field can be updated by customers during signup. The default Value is false |
id | ID of the contact field |
label | Display name for the field (as seen by agents) |
name | Name of the contact field |
position | Position of the contact field |
default | Set to true if the field is not a custom field |
type | For custom contact fields, type of value associated with the field will be given (Examples custom_date, custom_text...) |
customers_can_edit | Set to true if the customer can edit the fields in the customer portal. The default Value is false |
label_for_customers | Display name for the field (as seen in the customer portal) |
required_for_customers | Set to true if the field is mandatory in the customer portal. The default Value is false |
displayed_for_customers | Set to true if the customers can see the field in the customer portal. The default Value is false |
required_for_agents | Set to true if the field is mandatory for agents. The default Value is false |
choices | Array of key, value pairs containing the value and position of dropdown choices |
Supported Types
Supported Types | Description |
---|---|
custom_text | Custom text field |
custom_paragraph | Custom paragragh field |
custom_checkbox | Custom checkbox field |
custom_number | Custom checkbox field |
custom_dropdown | Custom dropdown field |
custom_phone_number | Custom phone number field |
custom_url | Custom URL field |
custom_date | Custom date field |
List all contact fields
/api/v2/contact_fields
To view all contact field details, use this API.
Sample code | Curl
1 2 | # All Contact Fields curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contact_fields' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 | [ { "editable_in_signup": true, "id": 1, "name": "name", "label": "Full name", "position": 1, "required_for_agents": true, "type": "default_name", "default": true, "customers_can_edit": true, "label_for_customers": "Full name", "required_for_customers": true, "displayed_for_customers": true, "created_at": "2023-01-20T06:48:42Z", "updated_at": "2023-01-20T06:48:42Z" }, { "editable_in_signup": false, "id": 2, "name": "job_title", "label": "Title", "position": 2, "required_for_agents": false, "type": "default_job_title", "default": true, "customers_can_edit": true, "label_for_customers": "Title", "required_for_customers": false, "displayed_for_customers": true, "created_at": "2023-01-20T06:48:42Z", "updated_at": "2023-01-20T06:48:42Z" }, { "editable_in_signup": true, "id": 3, "name": "email", "label": "Email", "position": 3, "required_for_agents": false, "type": "default_email", "default": true, "customers_can_edit": false, "label_for_customers": "Email", "required_for_customers": false, "displayed_for_customers": true, "created_at": "2023-01-20T06:48:42Z", "updated_at": "2023-01-20T06:48:42Z" }, { "editable_in_signup": false, "id": 4, "name": "phone", "label": "Work phone", "position": 4, "required_for_agents": false, "type": "default_phone", "default": true, "customers_can_edit": true, "label_for_customers": "Work phone", "required_for_customers": false, "displayed_for_customers": true, "created_at": "2023-01-20T06:48:42Z", "updated_at": "2023-01-20T06:48:42Z" }, { "editable_in_signup": false, "id": 8, "name": "mobile", "label": "Mobile phone", "position": 5, "required_for_agents": false, "type": "default_mobile", "default": true, "customers_can_edit": true, "label_for_customers": "Mobile phone", "required_for_customers": false, "displayed_for_customers": true, "created_at": "2023-01-20T06:50:22Z", "updated_at": "2023-01-20T06:50:22Z" }, { "editable_in_signup": false, "id": 10, "name": "twitter_id", "label": "Twitter", "position": 7, "required_for_agents": false, "type": "default_twitter_id", "default": true, "customers_can_edit": true, "label_for_customers": "Twitter", "required_for_customers": false, "displayed_for_customers": true, "created_at": "2023-01-20T06:50:22Z", "updated_at": "2023-01-20T06:50:22Z" }, { "editable_in_signup": false, "id": 5, "name": "company_name", "label": "Company", "position": 8, "required_for_agents": false, "type": "default_company_name", "default": true, "customers_can_edit": false, "label_for_customers": "Company", "required_for_customers": false, "displayed_for_customers": true, "created_at": "2023-01-20T06:48:42Z", "updated_at": "2023-01-20T06:48:42Z" }, { "editable_in_signup": false, "id": 11, "name": "address", "label": "Address", "position": 9, "required_for_agents": false, "type": "default_address", "default": true, "customers_can_edit": false, "label_for_customers": "Address", "required_for_customers": false, "displayed_for_customers": false, "created_at": "2023-01-20T06:50:22Z", "updated_at": "2023-01-20T06:50:22Z" }, { "editable_in_signup": false, "id": 6, "name": "time_zone", "label": "Time zone", "position": 10, "required_for_agents": false, "type": "default_time_zone", "default": true, "customers_can_edit": true, "label_for_customers": "Time zone", "required_for_customers": false, "displayed_for_customers": true, "created_at": "2023-01-20T06:48:42Z", "updated_at": "2023-01-20T06:48:42Z", "choices": { "American Samoa": "(GMT-11:00) American Samoa", "International Date Line West": "(GMT-11:00) International Date Line West", "Midway Island": "(GMT-11:00) Midway Island", "Hawaii": "(GMT-10:00) Hawaii", "Alaska": "(GMT-09:00) Alaska", "Pacific Time (US & Canada)": "(GMT-08:00) Pacific Time (US & Canada)", "Tijuana": "(GMT-08:00) Tijuana", "Arizona": "(GMT-07:00) Arizona", "Mazatlan": "(GMT-07:00) Mazatlan", "Mountain Time (US & Canada)": "(GMT-07:00) Mountain Time (US & Canada)", "Central America": "(GMT-06:00) Central America", "Central Time (US & Canada)": "(GMT-06:00) Central Time (US & Canada)", "Chihuahua": "(GMT-06:00) Chihuahua", "Guadalajara": "(GMT-06:00) Guadalajara", "Mexico City": "(GMT-06:00) Mexico City", "Monterrey": "(GMT-06:00) Monterrey", "Saskatchewan": "(GMT-06:00) Saskatchewan", "Bogota": "(GMT-05:00) Bogota", "Eastern Time (US & Canada)": "(GMT-05:00) Eastern Time (US & Canada)", "Indiana (East)": "(GMT-05:00) Indiana (East)", "Lima": "(GMT-05:00) Lima", "Quito": "(GMT-05:00) Quito", "Atlantic Time (Canada)": "(GMT-04:00) Atlantic Time (Canada)", "Caracas": "(GMT-04:00) Caracas", "Georgetown": "(GMT-04:00) Georgetown", "La Paz": "(GMT-04:00) La Paz", "Santiago": "(GMT-04:00) Santiago", "Newfoundland": "(GMT-03:30) Newfoundland", "Brasilia": "(GMT-03:00) Brasilia", "Buenos Aires": "(GMT-03:00) Buenos Aires", "Greenland": "(GMT-03:00) Greenland", "Montevideo": "(GMT-03:00) Montevideo", "Mid-Atlantic": "(GMT-02:00) Mid-Atlantic", "Azores": "(GMT-01:00) Azores", "Cape Verde Is.": "(GMT-01:00) Cape Verde Is.", "Casablanca": "(GMT+00:00) Casablanca", "Dublin": "(GMT+00:00) Dublin", "Edinburgh": "(GMT+00:00) Edinburgh", "Lisbon": "(GMT+00:00) Lisbon", "London": "(GMT+00:00) London", "Monrovia": "(GMT+00:00) Monrovia", "UTC": "(GMT+00:00) UTC", "Amsterdam": "(GMT+01:00) Amsterdam", "Belgrade": "(GMT+01:00) Belgrade", "Berlin": "(GMT+01:00) Berlin", "Bern": "(GMT+01:00) Bern", "Bratislava": "(GMT+01:00) Bratislava", "Brussels": "(GMT+01:00) Brussels", "Budapest": "(GMT+01:00) Budapest", "Copenhagen": "(GMT+01:00) Copenhagen", "Ljubljana": "(GMT+01:00) Ljubljana", "Madrid": "(GMT+01:00) Madrid", "Paris": "(GMT+01:00) Paris", "Prague": "(GMT+01:00) Prague", "Rome": "(GMT+01:00) Rome", "Sarajevo": "(GMT+01:00) Sarajevo", "Skopje": "(GMT+01:00) Skopje", "Stockholm": "(GMT+01:00) Stockholm", "Vienna": "(GMT+01:00) Vienna", "Warsaw": "(GMT+01:00) Warsaw", "West Central Africa": "(GMT+01:00) West Central Africa", "Zagreb": "(GMT+01:00) Zagreb", "Athens": "(GMT+02:00) Athens", "Bucharest": "(GMT+02:00) Bucharest", "Cairo": "(GMT+02:00) Cairo", "Harare": "(GMT+02:00) Harare", "Helsinki": "(GMT+02:00) Helsinki", "Jerusalem": "(GMT+02:00) Jerusalem", "Kaliningrad": "(GMT+02:00) Kaliningrad", "Kyiv": "(GMT+02:00) Kyiv", "Pretoria": "(GMT+02:00) Pretoria", "Riga": "(GMT+02:00) Riga", "Sofia": "(GMT+02:00) Sofia", "Tallinn": "(GMT+02:00) Tallinn", "Vilnius": "(GMT+02:00) Vilnius", "Baghdad": "(GMT+03:00) Baghdad", "Istanbul": "(GMT+03:00) Istanbul", "Kuwait": "(GMT+03:00) Kuwait", "Minsk": "(GMT+03:00) Minsk", "Moscow": "(GMT+03:00) Moscow", "Nairobi": "(GMT+03:00) Nairobi", "Riyadh": "(GMT+03:00) Riyadh", "St. Petersburg": "(GMT+03:00) St. Petersburg", "Volgograd": "(GMT+03:00) Volgograd", "Tehran": "(GMT+03:30) Tehran", "Abu Dhabi": "(GMT+04:00) Abu Dhabi", "Baku": "(GMT+04:00) Baku", "Muscat": "(GMT+04:00) Muscat", "Samara": "(GMT+04:00) Samara", "Tbilisi": "(GMT+04:00) Tbilisi", "Yerevan": "(GMT+04:00) Yerevan", "Kabul": "(GMT+04:30) Kabul", "Ekaterinburg": "(GMT+05:00) Ekaterinburg", "Islamabad": "(GMT+05:00) Islamabad", "Karachi": "(GMT+05:00) Karachi", "Tashkent": "(GMT+05:00) Tashkent", "Chennai": "(GMT+05:30) Chennai", "Kolkata": "(GMT+05:30) Kolkata", "Mumbai": "(GMT+05:30) Mumbai", "New Delhi": "(GMT+05:30) New Delhi", "Sri Jayawardenepura": "(GMT+05:30) Sri Jayawardenepura", "Kathmandu": "(GMT+05:45) Kathmandu", "Almaty": "(GMT+06:00) Almaty", "Astana": "(GMT+06:00) Astana", "Dhaka": "(GMT+06:00) Dhaka", "Urumqi": "(GMT+06:00) Urumqi", "Rangoon": "(GMT+06:30) Rangoon", "Bangkok": "(GMT+07:00) Bangkok", "Hanoi": "(GMT+07:00) Hanoi", "Jakarta": "(GMT+07:00) Jakarta", "Krasnoyarsk": "(GMT+07:00) Krasnoyarsk", "Novosibirsk": "(GMT+07:00) Novosibirsk", "Beijing": "(GMT+08:00) Beijing", "Chongqing": "(GMT+08:00) Chongqing", "Hong Kong": "(GMT+08:00) Hong Kong", "Irkutsk": "(GMT+08:00) Irkutsk", "Kuala Lumpur": "(GMT+08:00) Kuala Lumpur", "Perth": "(GMT+08:00) Perth", "Singapore": "(GMT+08:00) Singapore", "Taipei": "(GMT+08:00) Taipei", "Ulaanbaatar": "(GMT+08:00) Ulaanbaatar", "Osaka": "(GMT+09:00) Osaka", "Sapporo": "(GMT+09:00) Sapporo", "Seoul": "(GMT+09:00) Seoul", "Tokyo": "(GMT+09:00) Tokyo", "Yakutsk": "(GMT+09:00) Yakutsk", "Adelaide": "(GMT+09:30) Adelaide", "Darwin": "(GMT+09:30) Darwin", "Brisbane": "(GMT+10:00) Brisbane", "Canberra": "(GMT+10:00) Canberra", "Guam": "(GMT+10:00) Guam", "Hobart": "(GMT+10:00) Hobart", "Melbourne": "(GMT+10:00) Melbourne", "Port Moresby": "(GMT+10:00) Port Moresby", "Sydney": "(GMT+10:00) Sydney", "Vladivostok": "(GMT+10:00) Vladivostok", "Magadan": "(GMT+11:00) Magadan", "New Caledonia": "(GMT+11:00) New Caledonia", "Solomon Is.": "(GMT+11:00) Solomon Is.", "Srednekolymsk": "(GMT+11:00) Srednekolymsk", "Auckland": "(GMT+12:00) Auckland", "Fiji": "(GMT+12:00) Fiji", "Kamchatka": "(GMT+12:00) Kamchatka", "Marshall Is.": "(GMT+12:00) Marshall Is.", "Wellington": "(GMT+12:00) Wellington", "Chatham Is.": "(GMT+12:45) Chatham Is.", "Nuku'alofa": "(GMT+13:00) Nuku'alofa", "Samoa": "(GMT+13:00) Samoa", "Tokelau Is.": "(GMT+13:00) Tokelau Is." } }, { "editable_in_signup": false, "id": 7, "name": "language", "label": "Language", "position": 11, "required_for_agents": false, "type": "default_language", "default": true, "customers_can_edit": true, "label_for_customers": "Language", "required_for_customers": false, "displayed_for_customers": true, "created_at": "2023-01-20T06:48:42Z", "updated_at": "2023-01-20T06:48:42Z", "choices": { "ar": "Arabic", "bs": "Bosnian", "bg": "Bulgarian", "ca": "Catalan", "zh-CN": "Chinese", "zh-TW": "Chinese (Traditional)", "zh-HK": "Chinese - Hongkong", "hr": "Croatian", "cs": "Czech", "da": "Danish", "nl": "Dutch", "en": "English", "et": "Estonian", "fil": "Filipino", "fi": "Finnish", "fr": "French", "de": "German", "el": "Greek", "he": "Hebrew", "hu": "Hungarian", "is": "Icelandic", "id": "Indonesian", "it": "Italian", "ja-JP": "Japanese", "ja": "Japanese - Test", "ko": "Korean", "lv-LV": "Latvian", "lt": "Lithuanian", "long-text": "Long-Text", "ms": "Malay", "nb-NO": "Norwegian", "no": "Norwegian - Test", "pl": "Polish", "pt-BR": "Portuguese (BR)", "pt-PT": "Portuguese/Portugal", "ro": "Romanian", "ru-RU": "Russian", "ru": "Russian - Test", "sr": "Serbian", "sk": "Slovak", "sl": "Slovenian", "es": "Spanish", "es-LA": "Spanish (Latin America)", "es-419": "Spanish (Latin America) - Test", "sv-SE": "Swedish", "test-ui": "Test-UI", "th": "Thai", "tr": "Turkish", "uk": "Ukrainian", "vi": "Vietnamese" } }, { "editable_in_signup": false, "id": 12, "name": "tag_names", "label": "Tags", "position": 12, "required_for_agents": false, "type": "default_tag_names", "default": true, "customers_can_edit": false, "label_for_customers": "Tags", "required_for_customers": false, "displayed_for_customers": false, "created_at": "2023-01-20T06:50:22Z", "updated_at": "2023-01-20T06:50:22Z" }, { "editable_in_signup": false, "id": 13, "name": "description", "label": "About", "position": 13, "required_for_agents": false, "type": "default_description", "default": true, "customers_can_edit": false, "label_for_customers": "About", "required_for_customers": false, "displayed_for_customers": false, "created_at": "2023-01-20T06:50:22Z", "updated_at": "2023-01-20T06:50:22Z" }, { "editable_in_signup": false, "id": 15, "name": "unique_external_id", "label": "Unique external ID", "position": 15, "required_for_agents": false, "type": "default_unique_external_id", "default": true, "customers_can_edit": false, "label_for_customers": "Unique external ID", "required_for_customers": false, "displayed_for_customers": false, "created_at": "2023-01-20T06:50:22Z", "updated_at": "2023-01-20T06:50:22Z" }, { "editable_in_signup": false, "id": 16, "name": "twitter_profile_status", "label": "Twitter Verified Profile", "position": 16, "required_for_agents": false, "type": "default_twitter_profile_status", "default": true, "customers_can_edit": false, "label_for_customers": "Twitter Verified Profile", "required_for_customers": false, "displayed_for_customers": false, "created_at": "2023-01-20T06:50:22Z", "updated_at": "2023-01-20T06:50:22Z" }, { "editable_in_signup": false, "id": 17, "name": "twitter_followers_count", "label": "Twitter Follower Count", "position": 17, "required_for_agents": false, "type": "default_twitter_followers_count", "default": true, "customers_can_edit": false, "label_for_customers": "Twitter Follower Count", "required_for_customers": false, "displayed_for_customers": false, "created_at": "2023-01-20T06:50:22Z", "updated_at": "2023-01-20T06:50:22Z" } ] |
View a contact field
/api/v2/contact_fields/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contact_fields/18' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "editable_in_signup": true, "id": 18, "name": "custom_company_name", "label": "Company Name", "position": 10, "required_for_agents": true, "type": "custom_dropdown", "default": false, "customers_can_edit": true, "label_for_customers": "Company Name", "required_for_customers": true, "displayed_for_customers": true, "created_at": "2023-01-20T07:01:01Z", "updated_at": "2023-01-20T07:01:01Z", "choices": [ { "id": 1, "label": "Company 1", "value": "Company 1", "position": 1 }, { "id": 2, "label": "Company 2", "value": "Company 2", "position": 2 } ] } |
Create a contact field
/api/v2/contact_fields
To create a new contact field, use the following APIs.
Parameters
Attributes | Type | Description |
---|---|---|
label * | string | Display name for the field (as seen by agents) |
label_for_customers * | string | Display name for the field (as seen in the customer portal) |
type * | string | For custom contact fields, type of value associated with the field will be given (Examples custom_date, custom_text...) |
editable_in_signup | boolean | Set to true if the field can be updated by customers during signup. The default Value is false |
position | integer | Position of the company field. If not given, the position value will be 1. The maximum position value that can be given is the number of fields available plus 1. |
required_for_agents | boolean | Set to true if the field is mandatory for agents. The default Value is false |
customers_can_edit | boolean | Set to true if the customer can edit the fields in the customer portal. The default Value is false |
required_for_customers | boolean | Set to true if the field is mandatory in the customer portal. The default Value is false |
displayed_for_customers | boolean | Set to true if the customers can see the field in the customer portal. The default Value is false |
choices (Applicable for dropdown) | Array of hash | Array of key, value pairs containing the value and position of dropdown choices |
Sample code | Curl
1 2 3 | # Custom Dropdown curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "editable_in_signup": true, "label": "Company Name", "position": 10, "required_for_agents": true, "type": "custom_dropdown", "customers_can_edit": true, "label_for_customers": "Company Name", "required_for_customers": true, "displayed_for_customers": true, "choices":[{ "value": "Company 1", "position":1 }, { "value": "Company 2", "position": 2 }]}' 'https://domain.freshdesk.com/api/v2/contact_fields' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | # Custom Dropdown { "editable_in_signup": true, "id": 24, "name": "custom_company_name", "label": "Company Name", "position": 10, "required_for_agents": true, "type": "custom_dropdown", "default": false, "customers_can_edit": true, "label_for_customers": "Company Name", "required_for_customers": true, "displayed_for_customers": true, "created_at": "2023-01-20T05:27:11Z", "updated_at": "2023-01-20T05:27:11Z", "choices": [ { "id": 27, "label": "Company 1", "value": "Company 1", "position": 1 }, { "id": 28, "label": "Company 2", "value": "Company 2", "position": 2 } ] } |
Update a contact field
/api/v2/contact_fields/[id]
To Edit the contents of a contact field, use this API
Parameters
Attributes | Type | Description |
---|---|---|
label | string | Display name for the field (as seen by agents) |
label_for_customers | string | Display name for the field (as seen in the customer portal) |
editable_in_signup | boolean | Set to true if the field can be updated by customers during signup. The default Value is false |
position | integer | Position of the company field. The maximum position value that can be given is the number of fields available plus 1. |
required_for_agents | boolean | Set to true if the field is mandatory for agents. The default Value is false |
customers_can_edit | boolean | Set to true if the customer can edit the fields in the customer portal. The default Value is false |
required_for_customers | boolean | Set to true if the field is mandatory in the customer portal. The default Value is false |
displayed_for_customers | boolean | Set to true if the customers can see the field in the customer portal. The default Value is false |
choices (Applicable for dropdown) | Array of hash | Array of key, value pairs containing the value and position of dropdown choices |
Sample code | Curl
1 2 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label": "Company Test", "position": 10, "required_for_agents": true, "label_for_customers": "Company Test", "choices":[{ "id": 27, "value": "Company Name 1", "position":1 }, { "id": 28, "deleted": true }, { "value": "Company Name 2", "position": 2 }] }' 'https://domain.freshdesk.com/api/v2/contact_fields/24' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "editable_in_signup": true, "id": 24, "name": "custom_company_name", "label": "Company Test", "position": 10, "required_for_agents": false, "type": "custom_dropdown", "default": false, "customers_can_edit": true, "label_for_customers": "Company Test", "required_for_customers": true, "displayed_for_customers": true, "created_at": "2023-01-20T05:27:11Z", "updated_at": "2023-01-20T06:27:59Z", "choices": [ { "id": 27, "label": "Company Name 1", "value": "Company Name 1", "position": 1 }, { "id": 29, "label": "Company Name 2", "value": "Company Name 2", "position": 2 } ] } |
Delete a contact field
/api/v2/contact_field/[id]
Note: This action is irreversible. You will not be able to restore a contact field once deleted. Data stored in the corresponding field across all contacts will be lost.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/contact_fields/24' |
Response
1 | HTTP Status: 204 No Content |
Agents
Agents in Freshdesk can be “full-time” or “occasional”. Full time agents are those in your core support team who will log in to your help desk every day. Occasional agents are those who would only need to log in a few times every month, such as the CEO or field staff.
Note:
All Agent APIs other than the Currently Authenticated Agent API require admin privileges.
Attribute | Type | Description |
---|---|---|
available | boolean | If the agent is in a group that has enabled "Automatic Ticket Assignment", this attribute will be set to true if the agent is accepting new tickets |
available_since | datetime | Timestamp that denotes when the agent became available/unavailable (depending on the value of the 'available' attribute) |
id | number | User ID of the agent |
occasional | boolean | Set to true if this is an occasional agent (true => occasional, false => full-time) |
signature | string | Signature of the agent in HTML format |
ticket_scope | number | Ticket permission of the agent (1 -> Global Access, 2 -> Group Access, 3 -> Restricted Access) |
type | string | Type of Agent (support_agent -> Support Agent, field_agent -> Field Agent, collaborator -> Collaborator) |
skill_ids | array of numbers | Skill ids associated with the agent |
group_ids | array of numbers | Group IDs associated with the agent |
role_ids | array of numbers | Role IDs associated with the agent |
created_at | datetime | Agent creation timestamp |
updated_at | datetime | Agent updated timestamp |
contact[active] | string | Set to true if the agent is verified |
contact[email] | string | Email address of the agent |
contact[job_title] | string | Job title of the agent |
contact[language] | string | Language of the agent. Default language is "en" |
contact[last_login_at] | timestamp | Timestamp of the agent's last successful login |
contact[mobile] | string | Mobile number of the agent |
contact[name] | string | Name of the agent |
contact[phone] | number | Telephone number of the agent |
contact[time_zone] | string | Time zone of the agent |
contact[created_at] | datetime | Creation timestamp |
contact[updated_at] | datetime | Timestamp of the last update |
focus_mode | boolean | Focus mode of the agent |
View an Agent
/api/v2/agents/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents/432' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | { "available":true, "occasional":false, "signature":null, "group_ids" : [ 4 ], "role_ids" : [ 1 ], "skill_ids" : [ 2 ], "id":432, "ticket_scope":1, "created_at":"2015-08-28T11:47:58Z", "updated_at":"2015-08-28T11:47:58Z", "available_since":null, "type": "support_agent", "contact":{ "active":false, "email":"superman@freshdesk.com", "job_title":"Journalist", "language":"en", "last_login_at":null, "mobile":null, "name":"Clark Kent", "phone":null, "time_zone":"Chennai", "created_at":"2015-08-28T09:08:16Z", "updated_at":"2015-08-28T11:47:58Z" }, "focus_mode": true } |
List All Agents
/api/v2/agents
Use filters to view only specific agents (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 |
---|---|
email, mobile, phone | /api/v2/agents?<filter>=<value> Example: /api/v2/agents?email=superman@freshdesk.com /api/v2/agents?mobile=7654367287 /api/v2/agents?phone=4352789885 |
state | /api/v2/agents?state=[fulltime/occasional] |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 | [ { "available":true, "occasional":false, "signature":null, "id":1, "ticket_scope":1, "created_at":"2015-08-18T16:18:05Z", "updated_at":"2015-08-18T16:18:05Z", "available_since":null, "type": "support_agent", "contact":{ "active":true, "email":"sample@freshdesk.com", "job_title":null, "language":"en", "last_login_at":"2015-08-21T14:54:46+05:30", "mobile":null, "name":"Support", "phone":null, "time_zone":"Chennai", "created_at":"2015-08-18T16:18:05Z", "updated_at":"2015-08-25T08:50:20Z" }, "focus_mode": true }, { "available":true, "occasional":false, "signature":null, "signature":null, "id":432, "ticket_scope":1, "created_at":"2015-08-28T11:47:58Z", "updated_at":"2015-08-28T11:47:58Z", "available_since":null, "type": "support_agent", "contact":{ "active":false, "email":"superman@freshdesk.com", "job_title":"Journalist", "language":"en", "last_login_at":null, "mobile":null, "name":"Clark Kent", "phone":null, "time_zone":"Chennai", "created_at":"2015-08-28T09:08:16Z", "updated_at":"2015-08-28T11:47:58Z" }, "focus_mode": true }, ... ] |
Additional Examples
1. Get a list of agents filtered by the email address. Since the email address is unique, you will get only one agent in the list.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents?email=sample@freshdesk.com' |
2. Get the first 20 fulltime agents. By default, the agents will be returned in alphabetical order.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents?state=fulltime&per_page=20' |
Create an Agent
/api/v2/agents/
Parameters
Attribute | Type | Description |
---|---|---|
occasional | boolean | Set to true if this is an occasional agent (true => occasional, false => full-time) |
signature | string | Signature of the agent in HTML format |
ticket_scopeMandatory | number | Ticket permission of the agent (1 -> Global Access, 2 -> Group Access, 3 -> Restricted Access). Current logged in agent can't update his/her ticket_scope |
skill_ids | array of numbers | Skill ids associated with the agent |
group_ids | array of numbers | Group IDs associated with the agent |
role_ids | array of numbers | Role IDs associated with the agent. At least one role should be associated with the agent. Current logged in agent can't update his/her role_ids (Role IDs should be corresponding to the type of agents. For example: Ticket collaborator for collaborator agent, Agent or admin for support agent) |
agent_type | number | Type of Agent (1 -> Support Agent, 2 -> Field Agent, 3 -> Collaborator). By default, support agent is created |
email Mandatory | string | Email address of the Agent. |
language | string | Language of the Agent. Default language is "en" |
time_zone | string | Time zone of the Agent. Default value is time zone of the domain |
focus_mode | boolean | Focus mode of the agent. Default value is true |
Sample code | Curl
1 2 3 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "email":"superman@freshdesk.com", "name": "Super man", "ticket_scope":1, "occasional": true, "language": "en", "group_ids": [1], "role_ids": [2], "skill_ids": [3] }'https://domain.freshdesk.com/api/v2/agents' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | { "available": false, "occasional": true, "id": 1, "ticket_scope": 1, "signature": "<div dir=\"ltr\"><p><br></p>\n</div>", "group_ids": [ 1 ], "role_ids": [ 2 ], "skill_ids": [ 3 ], "created_at": "2019-12-19T04:07:53Z", "updated_at": "2019-12-19T04:07:53Z", "available_since": null, "type": "support_agent", "contact": { "active": false, "email": "superman@freshdesk.com", "job_title": null, "language": "en", "last_login_at": null, "mobile": null, "name": "Super man", "phone": null, "time_zone": "Chennai", "created_at": "2019-12-19T04:07:53Z", "updated_at": "2019-12-19T04:07:53Z" }, "focus_mode": true } |
Agent creation with focus_mode disabled
Sample code | Curl
1 2 3 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "email":"superman@freshdesk.com", "name": "Super man", "ticket_scope":1, "occasional": true, "language": "en", "group_ids": [1], "role_ids": [2], "skill_ids": [3], "agent_type": 3, "focus_mode": false }'https://domain.freshdesk.com/api/v2/agents' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | { "available": false, "occasional": true, "id": 1, "ticket_scope": 1, "signature": "<div dir=\"ltr\"><p><br></p>\n</div>", "group_ids": [ 1 ], "role_ids": [ 2 ], "skill_ids": [ 3 ], "created_at": "2019-12-19T04:07:53Z", "updated_at": "2019-12-19T04:07:53Z", "available_since": null, "type": "support_agent", "contact": { "active": false, "email": "superman@freshdesk.com", "job_title": null, "language": "en", "last_login_at": null, "mobile": null, "name": "Super man", "phone": null, "time_zone": "Chennai", "created_at": "2019-12-19T04:07:53Z", "updated_at": "2019-12-19T04:07:53Z" }, "focus_mode": false } |
Additional Examples
1. Create a Collaborator Agent (Collaborators Feature Required)
1 2 3 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "email":"superman@freshdesk.com", "name": "Super man", "ticket_scope":1, "occasional": true, "language": "en", "group_ids": [1], "role_ids": [2], "skill_ids": [3], "agent_type": 3 }'https://domain.freshdesk.com/api/v2/agents' |
Update an Agent
/api/v2/agents/[id]
Note:
Agent's name, phone, mobile number and job title can't be updated using the API. They can be updated from the Neo Admin Center.
Parameters
Attribute | Type | Description |
---|---|---|
occasional | boolean | Set to true if this is an occasional agent (true => occasional, false => full-time) |
signature | string | Signature of the agent in HTML format |
ticket_scope | number | Ticket permission of the agent (1 -> Global Access, 2 -> Group Access, 3 -> Restricted Access). Current logged in agent can't update his/her ticket_scope |
skill_ids | array of numbers | Skill ids associated with the agent |
group_ids | array of numbers | Group IDs associated with the agent |
role_ids | array of numbers | Role IDs associated with the agent. At least one role should be associated with the agent. Current logged in agent can't update his/her role_ids (Role IDs should be corresponding to the type of agents. For example: Ticket collaborator for collaborator agent, Agent or admin for support agent) |
string | Email address of the Agent. | |
language | string | Language of the Agent. Default language is "en" |
time_zone | string | Time zone of the Agent. Default value is time zone of the domain |
focus_mode | boolean | Focus mode of the agent. Default value is true |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT -d '{ "ticket_scope":1, "name":"Super Agent" }' 'https://domain.freshdesk.com/api/v2/agents/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | { "available" : true, "occasional" : false, "id" : 1, "ticket_scope" : 1, "signature" : "Super Agent", "group_ids" : [ 4 ], "role_ids" : [ 1 ], "skill_ids" : [ 1 ], "created_at" : "2016-05-25T11:36:14Z", "updated_at" : "2016-07-06T12:25:57Z", "available_since" : null, "type": "support_agent", "contact" : { "active" : true, "email" : "sample@yourdomain.com", "language" : "en", "last_login_at" : "2016-06-14T11:07:52Z", "time_zone" : "Chennai", "created_at" : "2016-02-29T06:32:29Z", "updated_at" : "2016-06-24T14:30:20Z" } } |
Delete an Agent
/api/v2/agents/[id]
Note:
Agent's name, phone, mobile number and job title can't be updated using the API. They can be updated from the Neo Admin Center.
Note:
Deleting an agent will downgrade the agent into a contact.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/agents/2' |
Response
1 | HTTP Status: 204 No Content |
Currently Authenticated Agent
/api/v2/agents/me
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents/me' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "available":true, "occasional":false, "signature":null, "group_ids" : [ 4 ], "role_ids" : [ 1 ], "skill_ids": [ 1 ], "id":432, "ticket_scope":1, "created_at":"2015-08-28T11:47:58Z", "updated_at":"2015-08-28T11:47:58Z", "available_since":null, "type": "support_agent", "contact":{ "active":false, "email":"superman@freshdesk.com", "job_title":"Journalist", "language":"en", "last_login_at":null, "mobile":null, "name":"Clark Kent", "phone":null, "time_zone":"Chennai", "created_at":"2015-08-28T09:08:16Z", "updated_at":"2015-08-28T11:47:58Z" } } |
Create Multiple Agents
/api/v2/agents/bulk
Attribute | Type | Description |
---|---|---|
occasional | boolean | Set to true if this is an occasional agent (true => occasional, false => full-time) |
signature | string | Signature of the agent in HTML format |
ticket_scopeMandatory | number | Ticket permission of the agent (1 -> Global Access, 2 -> Group Access, 3 -> Restricted Access). Current logged in agent can't update his/her ticket_scope |
skill_ids | array of numbers | Skill ids associated with the agent |
group_ids | array of numbers | Group IDs associated with the agent |
role_ids | array of numbers | Role IDs associated with the agent. At least one role should be associated with the agent. Current logged in agent can't update his/her role_ids |
name | string | Name of the Agent |
emailMandatory | string | Email address of the Agent. |
phone | string | Telephone number of the Agent. |
mobile | string | Mobile number of the Agent. |
job_title | string | Job title of the Agent. |
language | string | Language of the Agent. Default language is "en". |
time_zone | string | Time zone of the Agent. Default value is time zone of the domain. |
focus_mode | boolean | Focus mode of the agent. Default value is true |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "agents": [{"email":"superman@freshdesk.com", "name": "Super man", "ticket_scope":1, "occasional": true, "language": "en", "group_ids": [1], "role_ids": [2], "skill_ids": [3] },{"email":"supportagent@freshdesk.com", "name": "Support agent", "ticket_scope":1, "occasional": false, "language": "de", "group_ids": [10], "role_ids": [12], "skill_ids": [3] }] }' https://domain.freshdesk.com/api/v2/agents/bulk' |
Response
1 2 3 4 | { "job_id": 100, "href": "https://domain.freshdesk.com/api/v2/jobs/100" } |
Search Agents
/api/v2/agents/autocomplete?term=[keyword]
Search for an agent using their name or email.
Note:
1. The search is case insensitive.
2. You cannot search with a substring. For example, an agent "John Jonz" can be looked up using "john", "Joh", "Jonz" and "jon". But it will not be returned when you search for "hn" or "th".
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents/autocomplete?term=John' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | [ { "id": 33, "name": "John Jonz", "email": "john.jonz@freshdesk.com", "avatar": null }, { "id": 456, "name": "John Steven Jonz", "email": "john.steven@freshdesk.com", "avatar": null } ] |
Skills
Skills allow you to easily match tickets to the right agents. You can associate distinct skills to each agent and create rules to make sure that only tickets matching those skills are assigned to them.
Note:
Only users with admin privileges can access the following APIs.
Attribute | Type | Description | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | number | ID of the skill | ||||||||||||||||||||||||||||||||||||
name | string | Name of the skill | ||||||||||||||||||||||||||||||||||||
rank | string | Position/rank of the skill | ||||||||||||||||||||||||||||||||||||
created_at | datetime | Timestamp of the when the skill was created. | ||||||||||||||||||||||||||||||||||||
updated_at | datetime | Timestamp of the when the skill was updated. | ||||||||||||||||||||||||||||||||||||
agents | array | Array of agent user IDs object separated by commas. | ||||||||||||||||||||||||||||||||||||
match_type | string | Match type for conditions("all", "any") | ||||||||||||||||||||||||||||||||||||
condtions | array | Array of objects and with:
"resources", "field_name", "operator", "value", "nested_fields" The operators we support for dependent fields are "is" and "is_not" and for all the other dropdown fields the supported operators are "in" and "not_in" For resource: "ticket"
|
View a Skill
/api/v2/admin/skills/[id]
Note:
Incase if you are using old omni route, please use the end point: /api/v2/skills
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/skills/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | { "id": 1, "name": "German travel experts", "rank": 1, "created_at": "2019-11-20T07:18:57Z", "updated_at": "2019-12-18T13:06:29Z", "agents": [ { "id": 1 }, { "id": 2 } ], "match_type": "all", "conditions": [ { "resource_type": "contact", "field_name": "language", "operator": "in", "value": [ "de" ] }, { "resource_type": "ticket", "field_name": "cf_issue_type", "operator": "is", "value": "Booking", "nested_fields": { "level2": { "field_name": "cf_preferred_issue_details", "value": "Itinerary change" } } } ] } |
List all Skills
/api/v2/admin/skills/
Note:
Incase if you are using old omni route, please use the end point: /api/v2/skills
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/skills' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 | [ { "id": 1, "name": "German Travel Experts", "rank": 1, "created_at": "2019-11-20T07:18:57Z", "updated_at": "2019-12-18T12:55:14Z", "agents": [ { "id": 1 }, { "id": 2 } ], "match_type": "all", "conditions": [ { "resource_type": "ticket", "field_name": "source", "operator": "in", "value": [ 2, 4 ] }, { "resource_type": "ticket", "field_name": "priority", "operator": "in", "value": [ 1, 3 ] } ] }, { "id": 2, "name": "US Travel Experts", "rank": 2, "created_at": "2019-12-18T13:03:11Z", "updated_at": "2019-12-18T13:03:11Z", "agents": [ { "id": 1 } ], "match_type": "all", "conditions": [ { "resource_type": "ticket", "field_name": "product_id", "operator": "in", "value": [ 3 ] } ] } ] |
Create a Skill
/api/v2/admin/skills
Note:
Incase if you are using old omni route, please use the end point: /api/v2/skills
Parameters
Attribute | Type | Description | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name Mandatory | string | Name of the skill | ||||||||||||||||||||||||||||||||||||
agents | array | Array of agent user IDs object separated by commas. | ||||||||||||||||||||||||||||||||||||
match_type | string | Match type for conditions("all", "any") | ||||||||||||||||||||||||||||||||||||
condtions | array | Array of objects and with:
"resources", "field_name", "operator", "value", "nested_fields" The operators we support for dependent fields are "is" and "is_not" and for all the other dropdown fields the supported operators are "in" and "not_in" For resource: "ticket"
|
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name": "Indian travel experts", "agents": [{ "id": 1 }], "match_type": "all", "conditions": [{ "resource_type": "ticket", "field_name": "cf_issue_type", "operator": "is", "value": "Booking", "nested_fields": { "level2": { "field_name": "cf_preferred_issue_details", "operator": "is", "value": "Itinerary change" } } }] }' 'https://domain.freshdesk.com/api/v2/admin/skills' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | { "id": 0, "created_at": "2019-12-18T11:45:25.017Z", "updated_at": "2019-12-18T11:45:25.017Z", "name": "Indian travel experts", "agents": [ { "id": 1 } ], "match_type": "all", "conditions": [ { "resource_type": "ticket", "field_name": "cf_issue_type", "operator": "is", "value": "Booking", "nested_fields": { "level2": { "field_name": "cf_preferred_issue_details", "value": "Itinerary change" } } } ], "rank": 1 } |
Delete a Skill
/api/v2/admin/skills/[id]
Note:
Incase if you are using old omni route, please use the end point: /api/v2/skills
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/admin/skills/1' |
Response
1 | HTTP Status: 204 No Content |
Update a Skill
/api/v2/admin/skills/[id]
Note:
Incase if you are using old omni route, please use the end point: /api/v2/skills
Parameters
Attribute | Type | Description | ||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name | string | Name of the skill | ||||||||||||||||||||||||||||||||||||
rank | string | Position/rank of the skill | ||||||||||||||||||||||||||||||||||||
agents | array | Array of agent user IDs object separated by commas. | ||||||||||||||||||||||||||||||||||||
match_type | string | Match type for conditions("all", "any") | ||||||||||||||||||||||||||||||||||||
condtions | array | Array of objects and with:
"resources", "field_name", "operator", "value", "nested_fields" The operators we support for dependent fields are "is" and "is_not" and for all the other dropdown fields the supported operators are "in" and "not_in" For resource: "ticket"
|
Sample code | Curl
1 2 3 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name": "German travel experts", "agents": [{ "id": 1 }], "match_type": "any", "conditions": [{ "resource_type": "ticket", "field_name": "source", "operator": "in", "value": [2, 4] }]] } 'https://domain.freshdesk.com/api/v2/admin/skills/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "id": 1, "created_at": "2019-12-18T11:45:25.017Z", "updated_at": "2019-12-18T11:45:25.017Z", "name": "German travel experts", "agents": [ { "id": 1 } ], "match_type": "any", "conditions": [ { "resource_type": "ticket", "field_name": "source", "operator": "in", "value": [ 2, 4 ] } ], "rank": 1 } |
Roles
Roles allow you to create special privileges and profiles specifying what an agent can see and do within your Freshdesk support portal. These roles help you classify your team into different sections and assign them capabilities so that they get to do what they need to on their helpdesk, without getting in each other's way. They are especially useful for larger teams where there are different groups of employees trying to handle different things.
Note:
Only users with admin privileges can access the following APIs.
Attribute | Type | Description |
---|---|---|
description | string | Description of the Role |
id | number | Unique ID of the Role |
name | string | Name of the Role |
default | boolean | Set to true if this is the default role |
created_at | datetime | Role creation timestamp |
updated_at | datetime | Role updated timestamp |
View a Role
/api/v2/roles/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/roles/1' |
Response
1 2 3 4 5 6 7 8 | { "id" : 1, "name" : "Account Administrator", "description" : "Has complete control over the help desk including access to Account or Billing related information, and receives Invoices.", "default" : true, "created_at" : "2016-02-29T06:32:28Z", "updated_at" : "2016-02-29T06:32:28Z" } |
List All Roles
/api/v2/roles
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/roles' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | [ { "id" : 1, "name" : "Account Administrator", "description" : "Has complete control over the help desk including access to Account or Billing related information, and receives Invoices.", "default" : true, "created_at" : "2016-02-29T06:32:28Z", "updated_at" : "2016-02-29T06:32:28Z" }, { "id" : 2, "name" : "Administrator", "description" : "Can configure all features through the Admin tab, but is restricted from viewing Account or Billing related information.", "default" : true, "created_at" : "2016-02-29T06:32:28Z", "updated_at" : "2016-02-29T06:32:28Z" }, { "id" : 3, "name" : "Supervisor", "description" : "Can perform all agent related activities and access reports, but cannot access or change configurations in the Admin tab.", "default" : true, "created_at" : "2016-02-29T06:32:28Z", "updated_at" : "2016-02-29T06:32:28Z" }, { "id" : 4, "name" : "Agent", "description" : "Can log, view, reply, update and resolve tickets and manage contacts.", "default" : true, "created_at" : "2016-02-29T06:32:28Z", "updated_at" : "2016-02-29T06:32:28Z" } ] |
Groups
You can organise your agents into different groups so they could focus on one kind of problem, and get to know the solutions and customers better.
Note:
This section is for the old Group APIs. You can find the new Group APIs which have additional capabilities here.
Only users with admin privileges can access the following APIs.
Attribute | Type | Description |
---|---|---|
agent_ids | array | Array of agent user IDs separated by commas. Instructions on finding an agent's user ID can be found here. |
auto_ticket_assign | number | Describes the type of automatic ticket assignment set for the group. Automatic ticket assignment is only available on certain plans. |
business_hour_id | number | Unique ID of the business hour associated with the group |
description | string | Description of the group |
escalate_to | number | The ID of the user to whom an escalation email is sent if a ticket is unassigned. To create/update a group with an escalate_to value of 'none', please set the value of this parameter to 'null' |
id | number | Unique ID of the group |
name | string | Name of the group |
unassigned_for | string | The time after which an escalation email is sent if a ticket remains unassigned. The accepted values are "30m" for 30 minutes, "1h" for 1 hour, "2h" for 2 hours, "4h" for 4 hours, "8h" for 8 hours, "12h" for 12 hours, "1d" for 1 day, "2d" for 2 days, and "3d" for 3 days |
created_at | datetime | Group creation timestamp |
updated_at | datetime | Group updated timestamp |
Automatic Ticket Assignment Properties
Every group uses certain fixed numerical values to denote the type of its automatic ticket assignment configuration. It is represented by the key auto_ticket_assign. These numerical values along with their meanings are given below.
Assignment Type | Value |
---|---|
Disabled | 0 |
Round Robin | 1 |
Skill Based Round Robin | 2 |
Load Based Round Robin* | 3 |
Omniroute | 12 |
*Load Based Round Robin is getting upgraded to Omniroute.
Create a Group
/api/v2/groups
Parameters
Attribute | Type | Description |
---|---|---|
agent_ids | array | Array of agent user ids separated by comma (' , '). Instructions on getting the agent's user ID |
auto_ticket_assign | number | Describes the automatic ticket assignment type. Will not be supported if your Freshdesk account is not on a plan that supports automatic ticket assignment. The accepted values are 0 and 1. To set other assignment types to a group, use Admin-Groups API. The default value is 0. |
description | string | Description of the group |
escalate_to | number | The user to whom the escalation email is sent of a ticket is unassigned. To create/update escalate_to with 'none' provide the value 'null' in the request |
nameMandatoryUnique | string | Name of the group |
unassigned_for | string | The time after which an escalation email will be sent if a ticket remains unassigned. The accepted values are "30m" for 30 minutes, "1h" for 1 hour, "2h" for 2 hour, "4h" for 4 hour, "8h" for 8 hour, "12h" for 12 hour, "1d" for 1 day, "2d" for 2days, "3d" for 3 days. The default value is "30m" |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"Entertainment", "description":"Singers and dancers", "unassigned_for":"30m", "agent_ids":[1,16] }' 'https://domain.freshdesk.com/api/v2/groups' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 | { "id":5, "name":"Entertainment", "description":"Singers and dancers", "business_hour_id":null "escalate_to":1, "unassigned_for":"30m", "agent_ids":[1,16], "auto_ticket_assign":0, "created_at":"2014-01-08T07:53:41+05:30", "updated_at":"2014-01-08T07:53:41+05:30" } |
View a Group
/api/v2/groups/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/groups/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 | { "id":1, "name":"Entertainers", "description":"Singers dancers and stand up comedians", "business_hour_id":null "escalate_to":1, "unassigned_for":"30m", "agent_ids":[2,15], "auto_ticket_assign":0, "created_at":"2014-01-08T07:53:41+05:30", "updated_at":"2014-01-08T07:53:41+05:30" } |
List All Groups
/api/v2/groups
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/groups' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | [ { "id":1, "name":"Entertainers", "description":"Singers dancers and stand up comedians", "business_hour_id":null "escalate_to":1, "unassigned_for":"30m", "auto_ticket_assign":0, "created_at":"2014-01-08T07:53:41+05:30", "updated_at":"2014-01-08T07:53:41+05:30" } ] |
Update a Group
/api/v2/groups/[id]
Note:
To delete all the agents associated with a group, update the group with "agent_ids"= [ ] (empty array)
Parameters
Attribute | Type | Description |
---|---|---|
agent_ids | array | Array of agent user ids separated by comma (' , '). Instructions on getting the agent's user ID |
auto_ticket_assign | number | Describes the automatic ticket assignment type. Will not be supported if your Freshdesk account is not on a plan that supports automatic ticket assignment. The accepted values are 0 and 1. To set other assignment types to a group, use Admin-Groups API. The default value is 0. |
description | string | Description of the group |
escalate_to | number | The user to whom the escalation email is sent of a ticket is unassigned. To create/update escalate_to with 'none' provide the value 'null' in the request |
nameUnique | string | Name of the group |
unassigned_for | string | The time after which an escalation email will be sent if a ticket remains unassigned. The accepted values are "30m" for 30 minutes, "1h" for 1 hour, "2h" for 2 hour, "4h" for 4 hour, "8h" for 8 hour, "12h" for 12 hour, "1d" for 1 day, "2d" for 2days, "3d" for 3 days. The default value is "30m" |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name":"Entertainers", "description":"Singers dancers and stand up comedians", "agent_ids":[2,15], "auto_ticket_assign":1 }' 'https://domain.freshdesk.com/api/v2/groups/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 | { "id":1, "name":"Entertainers", "description":"Singers dancers and stand up comedians", "business_hour_id":null "escalate_to":1, "unassigned_for":"30m", "agent_ids":[2,15], "auto_ticket_assign":1, "created_at":"2014-01-08T07:53:41+05:30", "updated_at":"2014-01-08T07:53:41+05:30" } |
Delete a Group
/api/v2/groups/[id]
Note:
1. Deleting a Group will only disband the group and not delete its members.
2. Deleted groups cannot be restored.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/groups/1' |
Response
1 | HTTP Status: 204 No Content |
Groups
You can organize your agents into groups depending on the type of issues they work on, the team they belong to, etc.
Note:
Use this API if your account has the revamped UI for groups (launched in March 2021). If your account is on the latest Freshdesk Omnichannel offering, operations performed through this API will be synced to your respective Freshchat and Freshcaller accounts (Check the Omnichannel Groups section for more details.)
Only users with admin privileges can access the following APIs.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the group |
name | string | Name of the group |
description | string | Description of the group |
type | string | Group type from the list : ["support_agent_group", "field_agent_group"] |
escalate_to | number | The ID of the user to whom an escalation email is sent if a ticket is unassigned. To create/update a group with an escalate_to value of 'none', please set the value of this parameter to 'null' |
unassigned_for | string | The time after which an escalation email is sent if a ticket remains unassigned. The accepted values are "30m" for 30 minutes, "1h" for 1 hour, "2h" for 2 hours, "4h" for 4 hours, "8h" for 8 hours, "12h" for 12 hours, "1d" for 1 day, "2d" for 2 days, and "3d" for 3 days |
agent_ids | array | Array of agent user IDs separated by commas. Instructions on finding an agent's user ID can be found here. |
business_calendar_id | number | Unique ID of the business calender associated with the group |
sync_status | hash | Contains the group sync_status [pass or fail] with the seeder products |
allow_agents_to_change_availability | boolean | Set to true if agents are allowed to change availability |
automatic_agent_assignment | hash | Contains settings related to automatic_agent_assignment. As an example, whether it is enabled and what type it is of. By choosing the type "channel_specific" you can get an array of settings related to your ticket or chat configuration. (see the reference below) "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings": { "capping_limit": 2 } }] } |
created_at | datetime | Group creation timestamp |
updated_at | datetime | Group updated timestamp |
Create a Group
/api/v2/admin/groups
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the group |
description | string | Description of the group |
type | string | Group type from the list : ["support_agent_group", "field_agent_group"] |
escalate_to | number | The ID of the user to whom an escalation email is sent if a ticket is unassigned. To create/update a group with an escalate_to value of 'none', please set the value of this parameter to 'null' |
unassigned_for | string | The time after which an escalation email is sent if a ticket remains unassigned. The accepted values are "30m" for 30 minutes, "1h" for 1 hour, "2h" for 2 hours, "4h" for 4 hours, "8h" for 8 hours, "12h" for 12 hours, "1d" for 1 day, "2d" for 2 days, and "3d" for 3 days |
agent_ids | array | Array of agent user IDs separated by commas. Instructions on finding an agent's user ID can be found here. |
business_calendar_id | number | Unique ID of the business calender associated with the group |
allow_agents_to_change_availability | boolean | Set to true if agents are allowed to change availability |
automatic_agent_assignment | hash | Contains settings related to automatic_agent_assignment. As an example, whether it is enabled and what type it is of. By choosing the type "channel_specific" you can get an array of settings related to your ticket or chat configuration. (see the reference below) "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings": { "capping_limit": 2 } }] } |
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 | # Group with basic settings curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"Entertainment", "description":"Singers and dancers", "type":"support_agent_group", "unassigned_for":"30m", "agent_ids":[14], "business_calendar_id":1 }' 'https://domain.freshdesk.com/api/v2/admin/groups' # Group with automatic_agent_assignment:enabled as false curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"Entertainment", "description":"Singers and dancers", "type":"support_agent_group", "unassigned_for":"30m", "agent_ids":[14], "business_calendar_id":1, "allow_agents_to_change_availability":true, automatic_agent_assignment":{"enabled":false} }' 'https://domain.freshdesk.com/api/v2/admin/groups' # Group with automatic_agent_assignment:enabled as true and ticket related settings. Here automatic_agent_assignment:type should have value as "channel_specific". automatic_agent_assignment:settings ticket assignment_type can be any one of ["round_robin", "load_based_round_robin", "skill_based_round_robin", "lbrr_by_omniroute"]. curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"Entertainment", "description":"Singers and dancers", "type":"support_agent_group", "unassigned_for":"30m", "agent_ids":[14], "business_calendar_id":1, "allow_agents_to_change_availability":true, automatic_agent_assignment":{"enabled":true, "type":"channel_specific", "settings":[{"channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings":{"capping_limit":2}}]} }' 'https://domain.freshdesk.com/api/v2/admin/groups' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 | # Group with basic settings { "id": 7651, "name": "Entertainment", "description": "Singers and dancers", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [ 14 ], "created_at": "2021-02-18T13:07:59Z", "updated_at": "2021-02-18T13:07:59Z", "allow_agents_to_change_availability": false, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": false } } # Group with automatic_agent_assignment:enabled as false { "id": 7652, "name": "Entertainment", "description": "Singers and dancers", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [ 14 ], "created_at": "2021-02-18T13:09:15Z", "updated_at": "2021-02-18T13:09:15Z", "allow_agents_to_change_availability": true, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": false } } # Group with automatic_agent_assignment:enabled as true and ticket related settings { "id": 7653, "name": "Entertainment", "description": "Singers and dancers", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [ 14 ], "created_at": "2021-02-18T13:11:04Z", "updated_at": "2021-02-18T13:11:04Z", "allow_agents_to_change_availability": true, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings": { "capping_limit": 2 } } ] } } |
View a Group
/api/v2/admin/groups/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/groups/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | # Example 1 { "id": 1, "name": "Account managers", "description": "Account managers", "escalate_to": null, "unassigned_for": null, "agent_ids": [], "created_at": "2021-02-10T07:20:31Z", "updated_at": "2021-02-10T07:20:31Z", "allow_agents_to_change_availability": false, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": false } } # Example 2 { "id": 2, "name": "Billing", "description": "Billing", "escalate_to": 2, "unassigned_for": "30m", "agent_ids": [4], "created_at": "2021-02-10T07:20:31Z", "updated_at": "2021-02-10T07:20:31Z", "allow_agents_to_change_availability": true, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings": { "capping_limit": 2 } }] } } |
List All Groups
/api/v2/admin/groups
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/groups' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | [ { "id": 6733, "name": "Account managers", "description": "Account managers", "escalate_to": null, "unassigned_for": null, "agent_ids": [], "created_at": "2021-02-10T07:20:31Z", "updated_at": "2021-02-10T07:20:31Z", "allow_agents_to_change_availability": false, "business_calendar_id": null, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": false } }, { "id": 6705, "name": "Billing", "description": "Members of the Billing team belong to this group", "escalate_to": null, "unassigned_for": null, "agent_ids": [], "created_at": "2021-02-10T06:32:10Z", "updated_at": "2021-02-10T06:32:10Z", "allow_agents_to_change_availability": false, "business_calendar_id": null, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": false } }, { "id": 6706, "name": "Payment", "description": "Members of the Payments team belong to this group", "escalate_to": [6], "unassigned_for": "30", "agent_ids": [2], "created_at": "2021-02-11T06:32:10Z", "updated_at": "2021-02-11T06:32:10Z", "allow_agents_to_change_availability": true, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings": { "capping_limit": 2 } }] } } ] |
Update a Group
/api/v2/admin/groups/[id]
Note:
Agents can be added or removed through api/v2/admin/groups/:id/agents
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the group |
description | string | Description of the group |
type | string | Group type from the list : ["support_agent_group", "field_agent_group"] |
escalate_to | number | The ID of the user to whom an escalation email is sent if a ticket is unassigned. To create/update a group with an escalate_to value of 'none', please set the value of this parameter to 'null' |
unassigned_for | string | The time after which an escalation email is sent if a ticket remains unassigned. The accepted values are "30m" for 30 minutes, "1h" for 1 hour, "2h" for 2 hours, "4h" for 4 hours, "8h" for 8 hours, "12h" for 12 hours, "1d" for 1 day, "2d" for 2 days, and "3d" for 3 days |
agent_ids | array | Array of agent user IDs separated by commas. Instructions on finding an agent's user ID can be found here. |
business_calendar_id | number | Unique ID of the business calender associated with the group |
allow_agents_to_change_availability | boolean | Set to true if agents are allowed to change availability |
automatic_agent_assignment | hash | Contains settings related to automatic_agent_assignment. As an example, whether it is enabled and what type it is of. By choosing the type "channel_specific" you can get an array of settings related to your ticket or chat configuration. (see the reference below) "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings": { "capping_limit": 2 } }] } |
Sample code | Curl
1 2 3 4 5 6 7 8 | # Group with general settings update curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name":"Entertainers", "description":"Singers dancers and stand up comedians" }' 'https://domain.freshdesk.com/api/v2/admin/groups/1' # Group with automatic_agent_assignment settings update - Example 1 curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "automatic_agent_assignment":{"enabled":true, "type":"channel_specific", "settings":[{"channel": "ticket", "assignment_type": "round_robin"}]} }' 'https://domain.freshdesk.com/api/v2/admin/groups/1' # Group with automatic_agent_assignment settings update - Example 2 curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "automatic_agent_assignment":{"enabled":true, "type":"channel_specific", "settings":[{"channel": "ticket", "assignment_type": "lbrr_by_omnroute"}]} }' 'https://domain.freshdesk.com/api/v2/admin/groups/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | # Group with general settings update { "id": 1, "name": "Entertainers", "description": "Singers dancers and stand up comedians", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [2,15], "created_at": "2021-02-18T13:07:59Z", "updated_at": "2021-02-18T13:53:23Z", "allow_agents_to_change_availability": false, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": false } } # Group with automatic_agent_assignment settings update - Example 1 { "id": 1, "name": "Entertainers", "description": "Singers dancers and stand up comedians", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [2,15], "created_at": "2021-02-18T13:07:59Z", "updated_at": "2021-02-18T14:03:34Z", "allow_agents_to_change_availability": false, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "round_robin" } ] } } # Group with automatic_agent_assignment settings update - Example 2 { "id": 1, "name": "Entertainers", "description": "Singers dancers and stand up comedians", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [2,15], "created_at": "2021-02-18T13:07:59Z", "updated_at": "2021-02-18T14:05:32Z", "allow_agents_to_change_availability": false, "business_calendar_id": 1, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "lbrr_by_omniroute" } ] } } |
Delete a Group
/api/v2/admin/groups/[id]
Note:
1. Deleting a group will delete all information related to the group. Agents associated with the group will be unmapped from it.
2. Deleted groups cannot be restored.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/admin/groups/1' |
Response
1 | HTTP Status: 204 No Content |
List All Agents in a Group
/api/v2/admin/groups/[id]/agents
Note:
In the api_response, params "freshcaller_agent" and "freshchat_agent" will only be visible if the Freshdesk account is an Omnichannel account.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/groups/[:id]/agents' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | [ { "id": 16830, "ticket_scope": 1, "write_access": true, "role_ids": [ 3376 ], "contact": { "name": "Agent1", "avatar": {}, "email": "agent1@gmail.com" }, "created_at": "2021-02-18T14:17:49Z", "updated_at": "2021-02-18T14:17:55Z", "freshcaller_agent": true, "freshchat_agent": true }, { "id": 14290, "ticket_scope": 1, "write_access": true, "role_ids": [ 3373 ], "contact": { "name": "Agent2", "avatar": {}, "email": "agent2@gmail.com" }, "created_at": "2021-02-10T06:32:10Z", "updated_at": "2021-02-18T12:15:36Z", "freshcaller_agent": true, "freshchat_agent": true } ] |
Add or Remove Agents in a Group
/api/v2/admin/groups/[id]/agents
Sample code | Curl
1 2 3 4 5 6 7 8 | # Add agents curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "agents":[{"id": 16830}, {"id": 14290}] }' 'https://domain.freshdesk.com/api/v2/admin/groups/[:id]/agents' # Remove agents curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "agents":[{"id": 16830, "deleted": true}, {"id": 14290, "deleted": true}] }' 'https://domain.freshdesk.com/api/v2/admin/groups/[:id]/agents' # Add and remove agents curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "agents":[{"id": 16830, "deleted": true}, {"id": 14290}] }' 'https://domain.freshdesk.com/api/v2/admin/groups/[:id]/agents' |
Response
1 2 3 4 5 6 7 8 | # Add agents HTTP Status: 204 No Content # Remove agents HTTP Status: 204 No Content # Add and remove agents HTTP Status: 204 No Content |
Omnichannel Group
If the Freshdesk account is an omnichannel account, then we can also assign chat related automatic agent assignment settings in a Group settings. This api provides a common group across desk, chat and caller side. Example all the group operations performed through this api at desk side will be synced to respective chat and caller accounts.
Note:
An omnichannel account can have automatic_agent_assignment:type as "channel_specific" only.
Supporting Chat "assignment_type" as "intelli_assign".
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 12 13 | # Create Group with only Chat settings - Example 1 curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"Entertainment", "description":"Singers and dancers", "type":"support_agent_group", "unassigned_for":"30m", "agent_ids":[14], "business_calendar_id":1, "automatic_agent_assignment": {"enabled": true, "type": "channel_specific", "settings": [{"channel": "chat", "assignment_type": "intelli_assign"}]} }' 'https://domain.freshdesk.com/api/v2/admin/groups' # Create Group with only Chat settings - Example 2 curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"Entertainment", "description":"Singers and dancers", "type":"support_agent_group", "unassigned_for":"30m", "agent_ids":[14], "business_calendar_id":1, "automatic_agent_assignment": {"enabled": true, "type": "channel_specific", "settings": [{"channel": "chat", "assignment_type": "intelli_assign", "assignment_type_settings":{"reassign_conversation_of_inactive_agent": true}}]} }' 'https://domain.freshdesk.com/api/v2/admin/groups' # Update Group with only Chat settings curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "automatic_agent_assignment":{"enabled":true, "type":"channel_specific", "settings":[{"channel": "chat", "assignment_type": "intelli_assign", "assignment_type_settings":{"reassign_conversation_of_inactive_agent": true}}]} }' 'https://domain.freshdesk.com/api/v2/admin/groups/1' # Create Group with Ticket and Chat settings curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"Entertainment", "description":"Singers and dancers", "type":"support_agent_group", "unassigned_for":"30m", "agent_ids":[14], "business_calendar_id":1, "automatic_agent_assignment": {"enabled": true, "type": "channel_specific", "settings": [{"channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings":{"capping_limit":2}}, {"channel": "chat", "assignment_type": "intelli_assign", "assignment_type_settings":{"reassign_conversation_of_inactive_agent": true}}]} }' 'https://domain.freshdesk.com/api/v2/admin/groups' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | # Create Group with only Chat settings - Example 1 { "id": 7655, "name": "Entertainment", "description": "Singers and dancers", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [14], "business_calendar_id":1, "created_at": "2021-02-19T03:22:12Z", "updated_at": "2021-02-19T03:22:12Z", "allow_agents_to_change_availability": false, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "chat", "assignment_type": "intelli_assign" } ] } } # Create Group with only Chat settings - Example 2 { "id": 7656, "name": "Entertainment", "description": "Singers and dancers", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [14], "business_calendar_id":1, "created_at": "2021-02-19T04:22:12Z", "updated_at": "2021-02-19T04:22:12Z", "allow_agents_to_change_availability": false, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "chat", "assignment_type": "intelli_assign", "assignment_type_settings": { "reassign_conversation_of_inactive_agent": true } } ] } } # Update Group with only Chat settings { "id": 7656, "name": "Entertainment", "description": "Singers and dancers", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [14], "business_calendar_id":1, "created_at": "2021-02-19T04:22:12Z", "updated_at": "2021-02-19T04:25:12Z", "allow_agents_to_change_availability": false, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "chat", "assignment_type": "intelli_assign", "assignment_type_settings": { "reassign_conversation_of_inactive_agent": true } } ] } } # Create Group with Ticket and Chat settings { "id": 7657, "name": "Entertainment", "description": "Singers and dancers", "escalate_to": null, "unassigned_for": "30m", "agent_ids": [], "created_at": "2021-02-19T03:38:02Z", "updated_at": "2021-02-19T03:38:02Z", "allow_agents_to_change_availability": false, "business_calendar_id": null, "type": "support_agent_group", "automatic_agent_assignment": { "enabled": true, "type": "channel_specific", "settings": [ { "channel": "ticket", "assignment_type": "skill_based_round_robin", "assignment_type_settings": { "capping_limit": 2 } }, { "channel": "chat", "assignment_type": "intelli_assign", "assignment_type_settings": { "reassign_conversation_of_inactive_agent": true } } ] } } |
Companies
When multiple contacts from the same company contact you, it is better to group them into a company. This way, the tickets of the contacts can be mapped to the company. This also enables you to find an alternative person to call/email when a contact is unavailable.
Attribute | Type | Description |
---|---|---|
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
description | string | Description of the company |
domains | array | Domains of the company. Email addresses of contacts that contain this domain will be associated with that company automatically. |
id | number | Unique ID of the company |
name | string | Name of the company |
note | string | Any specific note about the company |
health_score | string | The strength of your relationship with the company |
account_tier | string | Classification based on how much value the company brings to your business |
renewal_date | date | Date when your contract or relationship with the company is due for renewal |
industry | string | The industry the company serves in |
created_at | datetime | Company creation timestamp |
updated_at | datetime | Company updated timestamp |
Create a Company
/api/v2/companies
Parameters
Attribute | Type | Description |
---|---|---|
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Only dates in the format YYYY-MM-DD are accepted as input for custom date fields. Read more here |
description | string | Description of the company |
domains | array | Domains of the company. Email addresses of contacts that contain this domain will be associated with that company automatically. |
nameMandatoryUnique | string | Name of the company |
note | string | Any specific note about the company |
health_score | string | The strength of your relationship with the company |
account_tier | string | Classification based on how much value the company brings to your business |
renewal_date | date | Date when your contract or relationship with the company is due for renewal |
industry | string | The industry the company serves in |
lookup_parameter | string | This attribute for companies can only be set if Custom Objects feature is enabled. The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
Sample code | Curl
1 2 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"SuperNova", "domains":["supernova","nova"], "description":"Spaceship Manufacturing Company", "health_score":"Happy", "account_tier":"Premium", "renewal_date":"2020-12-31"}' 'https://domain.freshdesk.com/api/v2/companies' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "id":8, "name":"SuperNova", "description":"Spaceship Manufacturing Company", "domains":["supernova","nova"], "note":null, "created_at":"2014-01-08T09:08:53+05:30", "updated_at":"2014-01-08T09:08:53+05:30", "health_score": "Happy", "account_tier": "Premium", "renewal_date": "2020-12-31T00:00:00Z", "industry": null } |
Create a Company With Custom Object record associated
Note:
1. The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #12345, here the primary_field_value will be “12345”
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"SuperNova", "domains":["supernova","nova"], "description":"Spaceship Manufacturing Company", "health_score":"Happy", "account_tier":"Premium", "renewal_date":"2020-12-31", "lookup_parameter" : "primary_field_value", "custom_fields" : { "order_number" : "12345" } }' 'https://domain.freshdesk.com/api/v2/companies' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "id" : 8, "name" : "SuperNova", "description" : "Spaceship Manufacturing Company", "domains" : ["supernova","nova"], "note" : null, "created_at" : "2014-01-08T09:08:53+05:30", "updated_at" : "2014-01-08T09:08:53+05:30", "health_score" : "Happy", "account_tier" : "Premium", "renewal_date" : "2020-12-31T00:00:00Z", "industry" : null, "custom_fields" : { "order_number" : "12345" }, } |
View a Company
/api/v2/companies/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/companies/8' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | { "id":8, "name":"Super Nova", "description":"Space Shuttle Manufacturing", "domains":["supernova","nova","super"], "note":null, "custom_fields" : { "website": "https://www.supernova.org", "address": "123, Baker Street,\r\nNew York" }, "created_at":"2014-01-08T09:08:53+05:30", "updated_at":"2014-01-08T09:08:53+05:30", "health_score": "Happy", "account_tier": "Premium", "renewal_date": "2020-12-31T00:00:00Z", "industry": null } |
List All Companies
/api/v2/companies
Use filters to view only specific companies (those which match the criteria that you choose)
Note:
1. When using filters, the query string must be URL encoded
2. All companies will be returned by default
Filter by | Handle |
---|---|
updated since | /api/v2/companies?updated_since=2023-02-28T00:00:00Z |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/companies' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | [ { "id":8, "name":"Super Nova", "description":"Space Shuttle Manufacturing", "domains":["supernova","nova","super"], "note":null, "created_at":"2014-01-08T09:08:53+05:30", "updated_at":"2014-01-08T09:08:53+05:30", "custom_fields" : { "website": "https://www.supernova.org", "address": "123, Baker Street,\r\nNew York" }, "health_score": "Happy", "account_tier": "Premium", "renewal_date": "2020-12-31T00:00:00Z", "industry": null }, { "id":9, "name":"Poseidon", "description":"Ship Building Company", "domains":["poseidon"], "note":null, "created_at":"2014-01-08T09:08:53+05:30", "updated_at":"2014-01-08T09:08:53+05:30", "custom_fields" : { "website": "https://www.poseidoncorp.org", "address": null }, "health_score": null, "account_tier": "Premium", "renewal_date": null, "industry": "Marine" } ] |
Additional Examples
1. Get a list of companies updated after a particular timestamp.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/companies?updated_since=2024-02-28T00:00:00Z' |
Search Companies
/api/v2/companies/autocomplete?name=[keyword]
Search for a company using its name.
Note:
1. The search is case insensitive.
2. You cannot search with a substring. For example, a company "Acme Corporation" can be looked up using "acme", "Ac", "Corporation" and "Co". But it will not be returned when you search for "cme" or "orporation".
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/companies/autocomplete?name=Acme' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 | { "companies":[ { "id": 33, "name": "Acme Inc." }, { "id": 456, "name": "Big Acme Inc." } ] } |
Filter CompaniesBETA
/api/v2/search/companies?query=[query]
Use custom company fields that you have created in your account to filter through the companies and get a list of companies matching the specified company fields.
Note:
1. Deleted companies will not be included in the results
2. The query must be URL encoded
3. Query can be framed using the name of the company fields, which can be obtained from Company Fields endpoint. Company Fields are case sensitive
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
5. Logical operators AND, OR along with parentheses () can be used to group conditions
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
7. Input for date fields should be in UTC Format
8. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
9. To scroll through the pages add page parameter to the url. The page number starts with 1 and should not exceed 10
10. To filter for fields with no values assigned, use the null keyword
11. Please note that the updates will take a few minutes to get indexed, after which it will be available through API
Supported Company Fields
Field | Type | Description |
---|---|---|
domain | string | Domain of the company |
created_at | date | Company creation date (YYYY-MM-DD) |
updated_at | date | Date (YYYY-MM-DD) when the company was last updated |
Custom Fields | ||
Single line text | string | |
Number | integer | |
Checkbox | boolean | |
Dropdown | string |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/companies?query="domain:'lexcorp.org'"' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | { "total":56, "results":[ { "id": 33, "name": "Lex Corp", "description": "Sales and Marketing", "note": "Sales division of Alexander Luthor's companies", "domains": [ "lexcorp.org", "lexcorp.us" ], "custom_fields": { "sector": 5, "private": true }, "created_at": "2017-12-15T06:34:09Z", "updated_at": "2017-12-15T06:34:09Z" }, ... ... ... ... ] } |
Additional Examples
1. Get the list of companies created on first week of October 2017.
"created_at:>'2017-10-01' AND created_at:<'2017-10-07'"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/companies?query="created_at:>%272017-10-01%27%20AND%20created_at:<%272017-10-07%27"' |
2. Get the list of private companies associated with sector 8 (sector and private are custom fields).
"sector:8 AND private:true"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/companies?query="sector:8%20AND%20private:true"' |
Update a Company
/api/v2/companies/[id]
Note:
To delete all existing domains for a company, perform an update with the attribute "domains"=[ ] (empty array)
Parameters
Attribute | Type | Description |
---|---|---|
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Only dates in the format YYYY-MM-DD are accepted as input for custom date fields. Read more here |
description | string | Description of the company |
domains | array | Domains of the company. Email addresses of contacts that contain this domain will be associated with that company automatically. |
nameUnique | string | Name of the company |
note | string | Any specific note about the company |
health_score | string | The strength of your relationship with the company |
account_tier | string | Classification based on how much value the company brings to your business |
renewal_date | date | Date when your contract or relationship with the company is due for renewal |
industry | string | The industry the company serves in |
lookup_parameter | string | This attribute for companies can only be set if Custom Objects feature is enabled. The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name":"Super Nova", "domains":["supernova","nova","super"], "description":"Space Shuttle Manufacturing", "account_tier":"Enterprise", "industry":"Aerospace and Defense" }' 'https://domain.freshdesk.com/api/v2/companies/8' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "id":8, "name":"Super Nova", "description":"Space Shuttle Manufacturing", "domains":["supernova","nova","super"], "note":null, "created_at":"2014-01-08T09:08:53+05:30", "updated_at":"2014-01-08T09:08:53+05:30", "health_score": "Happy", "account_tier": "Enterprise", "renewal_date": "2020-12-31T00:00:00Z", "industry": "Aerospace and Defense" } |
Update the lookup field within a company
Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #98765, here the primary_field_value will be “98765”
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "domains":["supernova","nova"], "lookup_parameter" : "primary_field_value", "custom_fields" : { "order_number" : "98765" } }' 'https://domain.freshdesk.com/api/v2/companies/8' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "id":8, "name":"SuperNova", "description":"Space Shuttle Manufacturing", "domains":["supernova","nova"], "note":null, "created_at":"2014-01-08T09:08:53+05:30", "updated_at":"2014-01-08T09:08:53+05:30", "health_score": "Happy", "account_tier": "Enterprise", "renewal_date": "2020-12-31T00:00:00Z", "industry": "Aerospace and Defense", "custom_fields":{ "order_number": "98765" } } |
Delete a Company
/api/v2/companies/[id]
Note:
1. Deleting a company does not delete the contacts that are associated with it. However the association will be removed.
2. Once deleted, a company cannot be restored.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/companies/1' |
Response
1 | HTTP Status: 204 No Content |
Company Export
In order to export companies using the Freshdesk API, you'll need to make two different API calls.
Step 1: You'll first need to hit the following endpoint with details about your export. This will start the background job and get you a company export ID.
api/v2/companies/export
Parameters
Attribute | Type | Description |
---|---|---|
fieldsMandatory | object | Fields of the companies to be exported |
Attribute | Type | Description |
---|---|---|
default_fields Mandatory | object | List of default fields of the companies to be exported. |
custom_fields Mandatory | object | List of custom fields of the companies to be exported. |
Tip: If you are not sure about what to include in this request, you can use the List All Company Fields to get a list of all company fields in your Freshdesk account.
Sample code | Curl
1 2 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "fields": { "default_fields": ["name", "domain"], "custom_fields": [] } }' 'https://domain.freshdesk.com/api/v2/companies/export' |
Response
1 2 3 | { "id": "d809986de1ed8a1abaeb363ac455e917b356e347" } |
Step 2: The company export ID can be passed to another endpoint which will return a URL to the exported CSV file.
api/v2/companies/export/[id]
This endpoint will return a valid URL to the CSV only when the export is done completely. The background job can take anywhere between a few seconds to several minutes to complete depending on the no of companies and the no of fields you're including in your export. We recommend that you come up with a pre-defined interval and make the API call more than once in order to get the URL in the response.
Note: Every Freshdesk account will be restricted to running only one company export at a time. Once the export is complete, the exported file can be accessed using the URL for 15 days, post which it will get removed automatically.
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST 'https://domain.freshdesk.com/api/v2/companies/export/d809986de1ed8a1abaeb363ac455e917b356e347' |
Response
1 2 3 4 5 | { "id": "d809986de1ed8a1abaeb363ac455e917b356e347", "status": "completed", "download_url": "https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/3301/original/companies-October-24-2018-06_40.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2JSYZ7O3%2F20181024%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20181024T064029Z&X-Amz-Expires=300&X-Amz-Signature=8eefc037a4a289e6baed83fc2e568c3ec65cde512a3dd6fea5b4188a7933a66c&X-Amz-SignedHeaders=Host&response-content-disposition=attachment&response-content-type=application%2Foctet-stream" } |
Company Import
List company imports
This API allows you to fetch a list of up to 5 most recent company imports that are either in-progress or have completed already. You can also filter your imports by status and list up to 5 of them in either state.
api/v2/companies/imports
Filter by | Handle |
---|---|
Status | api/v2/companies/imports?status=[in_progress/completed/cancelled/failed] |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/companies/imports' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | [ { "id": 423678, "created_at": "2018-08-28T10:27:58Z", "status": "completed", "total_records": 250, "completed_records": 245, "failures": { "count": 5, "report": "url" } } ] |
View a company import
Used to look up information about an import. In addition to its status, this API also returns an estimate for completion when the import is in progress and returns a list of failures when the import is complete.
api/v2/companies/imports/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/companies/imports/423678' |
Response
1 2 3 4 5 6 7 8 | { "id": 423678, "created_at": "2018-08-28T10:27:58Z", "status": "in_progress", "total_records": 250, "completed_records": 245, "estimated_time_remaining": "03:49:59" } |
Trigger a company import
You can import companies in bulk to a Freshdesk account by creating an import file and passing it to this API. This endpoint only supports CSV files (in UTF-8 format) and for the import to work properly, every row will need to include a minimum of two values - name and either an email address or phone number of the company.
Note: For more information creating rows in your import file, please check out our solution article on importing your customer data into Freshdesk.
api/v2/companies/imports
Parameters
Attribute | Type | Description |
---|---|---|
fileMandatory | object | CSV file to be imported. |
fieldsMandatory | object | Fields to be imported along with the index of the field as present in the import file. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: multipart/form-data' -F "file=@sample.csv" -F "fields[name]=0" -F "fields[email]=2" POST 'https://domain.freshdesk.com/api/v2/companies/imports' |
Response
1 2 3 4 5 6 7 8 | { "id": 423678, "created_at": "2018-08-28T10:27:58Z", "status": "in_progress", "total_records": 250, "completed_records": 245, "estimated_time_remaining": "03:49:59" } |
Cancel a company import
Used to cancel an import job that is currently in progress. Upon cancellation, this API will list the no of completed records it has imported already and also failures.
api/v2/companies/imports/[id]/cancel
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT 'https://domain.freshdesk.com/api/v2/companies/imports/423678/cancel' |
Response
1 2 3 4 5 6 7 8 9 10 11 | { "id": 423678, "created_at": "2018-08-28T10:27:58Z", "status": "cancelled", "total_records": 250, "completed_records": 245, "failures": { "count": 5, "report": "url" } } |
Company Fields
Note: Only users with admin privileges can access the following APIs.
The custom and default company fields in Freshdesk have the following properties.
Parameters
Company Field | Description |
---|---|
id | ID of the company field |
name | Name of the company field |
label | Display name for the field (as seen by agents) |
position | Position of the company field |
required_for_agents | Set to true if the field is mandatory for agents. The default Value is false |
type | For custom company fields, type of value associated with the field will be given (Examples custom_date, custom_text...) |
default | Set to true if the field is not a custom field |
choices | Array of key, value pairs containing the value and position of dropdown choices |
Supported Types
Supported Types | Description |
---|---|
custom_text | Custom text field |
custom_paragraph | Custom paragragh field |
custom_checkbox | Custom checkbox field |
custom_number | Custom checkbox field |
custom_dropdown | Custom dropdown field |
custom_phone_number | Custom phone number field |
custom_url | Custom URL field |
custom_date | Custom date field |
List all company fields
/api/v2/company_fields
To view all company field details, use this API.
Sample code | Curl
1 2 | # All Company Fields curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/company_fields' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | [ { "id": 1, "name": "name", "label": "Company Name", "position": 1, "required_for_agents": true, "type": "default_name", "default": true, "created_at": "2023-01-20T15:03:22Z", "updated_at": "2023-01-20T15:03:22Z" }, { "id": 2, "name": "description", "label": "Description", "position": 2, "required_for_agents": false, "type": "default_description", "default": true, "created_at": "2023-01-20T15:05:02Z", "updated_at": "2023-01-20T15:05:02Z" }, { "id": 3, "name": "note", "label": "Notes", "position": 3, "required_for_agents": false, "type": "default_note", "default": true, "created_at": "2023-01-20T15:05:02Z", "updated_at": "2023-01-20T15:05:02Z" }, { "id": 4, "name": "domains", "label": "Domains for this company", "position": 4, "required_for_agents": false, "type": "default_domains", "default": true, "created_at": "2023-01-20T15:05:02Z", "updated_at": "2023-01-20T15:05:02Z" }, { "id": 5, "name": "health_score", "label": "Health score", "position": 5, "required_for_agents": false, "type": "default_health_score", "default": true, "created_at": "2023-01-20T15:05:02Z", "updated_at": "2023-01-20T15:05:02Z", "choices": [ "At risk", "Doing okay", "Happy" ] }, { "id": 6, "name": "account_tier", "label": "Account tier", "position": 6, "required_for_agents": false, "type": "default_account_tier", "default": true, "created_at": "2023-01-20T15:05:02Z", "updated_at": "2023-01-20T15:05:02Z", "choices": [ "Basic", "Premium", "Enterprise" ] }, { "id": 7, "name": "renewal_date", "label": "Renewal date", "position": 7, "required_for_agents": false, "type": "default_renewal_date", "default": true, "created_at": "2023-01-20T15:05:02Z", "updated_at": "2023-01-20T15:05:02Z" }, { "id": 8, "name": "industry", "label": "Industry", "position": 8, "required_for_agents": false, "type": "default_industry", "default": true, "created_at": "2023-01-20T15:05:02Z", "updated_at": "2023-01-20T15:05:02Z", "choices": [ "Automotive", "Consumer Durables and Apparel", "Diversified Consumer Services", "Hotels, Restaurants and Leisure", "Consumer Goods", "Household Durables", "Leisure Products", "Textiles, Apparel and Luxury Goods", "Education Services", "Family Services", "Specialized Consumer Services", "Media", "Distributors", "Specialty Retail", "Beverages", "Food Products", "Food and Staples Retailing", "Personal Products", "Tobacco", "Gas Utilities", "Banks", "Capital Markets", "Diversified Financial Services", "Insurance", "Real Estate", "Health Care Equipment and Supplies", "Health Care Providers and Services", "Biotechnology", "Pharmaceuticals", "Professional Services", "Aerospace and Defense", "Air Freight and Logistics", "Airlines", "Commercial Services and Supplies", "Construction and Engineering", "Electrical Equipment", "Industrial Conglomerates", "Machinery", "Marine", "Road and Rail", "Trading Companies and Distributors", "Transportation", "Internet Software and Services", "IT Services", "Software", "Communications Equipment", "Electronic Equipment, Instruments and Components", "Technology Hardware, Storage and Peripherals", "Building Materials", "Chemicals", "Containers and Packaging", "Metals and Mining", "Paper and Forest Products", "Diversified Telecommunication Services", "Wireless Telecommunication Services", "Renewable Electricity", "Electric Utilities", "Utilities", "Other" ] } ] |
View a company field
/api/v2/company_fields/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/company_fields/8' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 | { "id": 8, "name": "industry", "label": "Industry", "position": 8, "required_for_agents": false, "type": "default_industry", "default": true, "created_at": "2023-01-20T15:05:02Z", "updated_at": "2023-01-20T15:05:02Z", "choices": [ { "id": 7, "label": "Automotive", "value": "Automotive", "position": 1 }, { "id": 8, "label": "Consumer Durables and Apparel", "value": "Consumer Durables and Apparel", "position": 2 }, { "id": 9, "label": "Diversified Consumer Services", "value": "Diversified Consumer Services", "position": 3 }, { "id": 10, "label": "Hotels, Restaurants and Leisure", "value": "Hotels, Restaurants and Leisure", "position": 4 }, { "id": 11, "label": "Consumer Goods", "value": "Consumer Goods", "position": 5 }, { "id": 12, "label": "Household Durables", "value": "Household Durables", "position": 6 }, { "id": 13, "label": "Leisure Products", "value": "Leisure Products", "position": 7 }, { "id": 14, "label": "Textiles, Apparel and Luxury Goods", "value": "Textiles, Apparel and Luxury Goods", "position": 8 }, { "id": 15, "label": "Education Services", "value": "Education Services", "position": 9 }, { "id": 16, "label": "Family Services", "value": "Family Services", "position": 10 }, { "id": 17, "label": "Specialized Consumer Services", "value": "Specialized Consumer Services", "position": 11 }, { "id": 18, "label": "Media", "value": "Media", "position": 12 }, { "id": 19, "label": "Distributors", "value": "Distributors", "position": 13 }, { "id": 20, "label": "Specialty Retail", "value": "Specialty Retail", "position": 14 }, { "id": 21, "label": "Beverages", "value": "Beverages", "position": 15 }, { "id": 22, "label": "Food Products", "value": "Food Products", "position": 16 }, { "id": 23, "label": "Food and Staples Retailing", "value": "Food and Staples Retailing", "position": 17 }, { "id": 24, "label": "Personal Products", "value": "Personal Products", "position": 18 }, { "id": 25, "label": "Tobacco", "value": "Tobacco", "position": 19 }, { "id": 26, "label": "Gas Utilities", "value": "Gas Utilities", "position": 20 }, { "id": 27, "label": "Banks", "value": "Banks", "position": 21 }, { "id": 28, "label": "Capital Markets", "value": "Capital Markets", "position": 22 }, { "id": 29, "label": "Diversified Financial Services", "value": "Diversified Financial Services", "position": 23 }, { "id": 30, "label": "Insurance", "value": "Insurance", "position": 24 }, { "id": 31, "label": "Real Estate", "value": "Real Estate", "position": 25 }, { "id": 32, "label": "Health Care Equipment and Supplies", "value": "Health Care Equipment and Supplies", "position": 26 }, { "id": 33, "label": "Health Care Providers and Services", "value": "Health Care Providers and Services", "position": 27 }, { "id": 34, "label": "Biotechnology", "value": "Biotechnology", "position": 28 }, { "id": 35, "label": "Pharmaceuticals", "value": "Pharmaceuticals", "position": 29 }, { "id": 36, "label": "Professional Services", "value": "Professional Services", "position": 30 }, { "id": 37, "label": "Aerospace and Defense", "value": "Aerospace and Defense", "position": 31 }, { "id": 38, "label": "Air Freight and Logistics", "value": "Air Freight and Logistics", "position": 32 }, { "id": 39, "label": "Airlines", "value": "Airlines", "position": 33 }, { "id": 40, "label": "Commercial Services and Supplies", "value": "Commercial Services and Supplies", "position": 34 }, { "id": 41, "label": "Construction and Engineering", "value": "Construction and Engineering", "position": 35 }, { "id": 42, "label": "Electrical Equipment", "value": "Electrical Equipment", "position": 36 }, { "id": 43, "label": "Industrial Conglomerates", "value": "Industrial Conglomerates", "position": 37 }, { "id": 44, "label": "Machinery", "value": "Machinery", "position": 38 }, { "id": 45, "label": "Marine", "value": "Marine", "position": 39 }, { "id": 46, "label": "Road and Rail", "value": "Road and Rail", "position": 40 }, { "id": 47, "label": "Trading Companies and Distributors", "value": "Trading Companies and Distributors", "position": 41 }, { "id": 48, "label": "Transportation", "value": "Transportation", "position": 42 }, { "id": 49, "label": "Internet Software and Services", "value": "Internet Software and Services", "position": 43 }, { "id": 50, "label": "IT Services", "value": "IT Services", "position": 44 }, { "id": 51, "label": "Software", "value": "Software", "position": 45 }, { "id": 52, "label": "Communications Equipment", "value": "Communications Equipment", "position": 46 }, { "id": 53, "label": "Electronic Equipment, Instruments and Components", "value": "Electronic Equipment, Instruments and Components", "position": 47 }, { "id": 54, "label": "Technology Hardware, Storage and Peripherals", "value": "Technology Hardware, Storage and Peripherals", "position": 48 }, { "id": 55, "label": "Building Materials", "value": "Building Materials", "position": 49 }, { "id": 56, "label": "Chemicals", "value": "Chemicals", "position": 50 }, { "id": 57, "label": "Containers and Packaging", "value": "Containers and Packaging", "position": 51 }, { "id": 58, "label": "Metals and Mining", "value": "Metals and Mining", "position": 52 }, { "id": 59, "label": "Paper and Forest Products", "value": "Paper and Forest Products", "position": 53 }, { "id": 60, "label": "Diversified Telecommunication Services", "value": "Diversified Telecommunication Services", "position": 54 }, { "id": 61, "label": "Wireless Telecommunication Services", "value": "Wireless Telecommunication Services", "position": 55 }, { "id": 62, "label": "Renewable Electricity", "value": "Renewable Electricity", "position": 56 }, { "id": 63, "label": "Electric Utilities", "value": "Electric Utilities", "position": 57 }, { "id": 64, "label": "Utilities", "value": "Utilities", "position": 58 }, { "id": 65, "label": "Other", "value": "Other", "position": 59 } ] } |
Create a company field
api/v2/company_fields
To create a new company field, use the following APIs.
Parameters
Attributes | Type | Description |
---|---|---|
label * | string | Display name for the field (as seen by agents) |
type * | string | For custom company fields, type of value associated with the field will be given (Examples custom_date, custom_text...) |
position | integer | Position of the company field. If not given, the position value will be 1. The maximum position value that can be given is the number of fields available plus 1. |
required_for_agents | boolean | Set to true if the field is mandatory in the customer portal. The default Value is false |
choices (Applicable for dropdown) | Array of hash | Array of key, value pairs containing the value and position of dropdown choices |
Sample code | Curl
1 2 3 | # Custom Dropdown curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "label": "Test Field", "position": 5, "required_for_agents": true, "type": "custom_dropdown", "choices":[{ "value": "choice 1", "position": 1 }, { "value": "choice 2", "position": 2 }] }' 'https://domain.freshdesk.com/api/v2/company_fields' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | # Custom Dropdown { "id": 9, "name": "test_field", "label": "Test Field", "position": 5, "required_for_agents": true, "type": "custom_dropdown", "default": false, "created_at": "2023-01-23T05:50:20Z", "updated_at": "2023-01-23T05:50:20Z", "choices": [ { "id": 66, "label": "choice 1", "value": "choice 1", "position": 1 }, { "id": 67, "label": "choice 2", "value": "choice 2", "position": 2 } ] } |
Update a company field
api/v2/company_field/[id]
To Edit the contents of a company field, use this API
Parameters
Attributes | Type | Description |
---|---|---|
label | string | Display name for the field (as seen by agents) |
position | integer | Position of the company field. The maximum position value that can be given is the number of fields available plus 1. |
required_for_agents | boolean | Set to true if the field is mandatory in the customer portal. |
choices (Applicable for dropdown) | Array of hash | Array of key, value pairs containing the value and position of dropdown choices |
Sample code | Curl
1 2 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label": "Test Field updated", "position": 5, "required_for_agents": false, "choices":[{ "id": 66, "value": "choice updated 1" }, { "id": 67, "deleted": true }, { "value": "Choice updated 2", "position": 2 }] }' 'https://domain.freshdesk.com/api/v2/company_fields/9' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | { "id": 9, "name": "test_field", "label": "Test Field updated", "position": 5, "required_for_agents": false, "type": "custom_dropdown", "default": false, "created_at": "2023-01-23T05:50:20Z", "updated_at": "2023-01-23T06:38:32Z", "choices": [ { "id": 66, "label": "choice updated 1", "value": "choice updated 1", "position": 1 }, { "id": 68, "label": "Choice updated 2", "value": "Choice updated 2", "position": 2 } ] } |
Delete a company field
api/v2/company_field/[id]
Note: This action is irreversible. You will not be able to restore a company field once deleted. Data stored in the corresponding field across all companies will be lost.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/company_fields/9' |
Response
1 | HTTP Status: 204 No Content |
Custom Objects
Freshdesk offers objects that are native to a helpdesk system, like tickets, contacts, and companies. These objects form the core of any business and contain the basic information related to the issue (ticket) a particular customer (contact) mapped to an organization (company) is facing. This basic information might fall short in helping agents get the full context behind the ticket. And at scale, it becomes necessary to provide contextual support proactively.
With 'Custom Objects', powered by Freshworks Neo, you can create and bring in information specific to your business use-cases right within Freshdesk and enable your agents to offer a contextual and faster resolution. With 'Custom Objects' enabled in your account, you can create your custom data entities and thus extend the data model in Freshdesk to solve your business use-cases. More information about Custom Objects can be found here
Note: Custom Objects can be enabled on request for accounts on Enterprise plan.
Custom Object Attributes
Attributes are the properties of a Custom Object Schema. A Custom Object Schema has the following attributes.
Attributes | Type | Description | Required? |
---|---|---|---|
Name | String | Name of the Schema | Yes |
Id | Integer | Auto-generated unique identifier for the Schema | Auto-generated |
Fields | Array of Objects | Fields in the Schema | No |
Description | String | A short description of the Schema | No |
Field Attributes
Fields in a Custom Object Schema have the following attributes.
Attributes | Type | Description | Required? |
---|---|---|---|
Name | Integer | Auto-generated unique identifier for a particular field | Yes |
Id | String | Name of the field | Auto-generated |
Label | String | Fields in the Schema | No |
Deleted | String | The default value is false. Should be set ‘true’ if you no longer intend to use this field. Can be restored by setting the value as false again | No |
Filterable | Boolean | Whether the given field is marked as filterable. The default value is false | Yes |
Hint | String | Hint to identify a particular field (Eg. This is a text field) | No |
Position | Integer | Position of the field (in case of multiple fields in a schema) | No |
Required | Boolean | To make the field mandatory while defining a custom object. The default value is false | Yes |
Type | String | Type of the field. It can be any of the below supported field types | Yes |
Supported Field Types
The following are the field types supported in a Custom Object Schema.
Attributes | Description | Can it be marked filterable? |
---|---|---|
PRIMARY | A string field type that can be marked unique to the Custom Object. A Custom Object Schema can contain only one PRIMARY field and this cannot be changed at a later point. | Yes |
TEXT | A string field type, displayed in a single-line text input. It has a length limit of 100 characters | Yes |
DROPDOWN | A dropdown input that allows users to select one value from the Pre-defined list of values | Yes |
MULTI-SELECT | Allows the user to select multiple values from the set of values provided for the field | Yes |
NUMBER | A string of numbers or numeric values | Yes |
DATE | A date value that can be provided in YYYY-MM-DD format | Yes |
LOOKUP RELATIONSHIP | Association of an Object with other Objects(Custom or Native) | Marked filterable by default |
PARAGRAPH | A string field type, displayed in a multi-line text input | No |
DECIMAL | Allows numeric values for which the precision can be defined | No |
Note:
1. A maximum of 20 Custom Objects can be created per Freshdesk account
2. A maximum of 100 fields can be created per Custom Object
3. A maximum of 5 associations can be created for a Custom Object with another Object(both Custom and Native), per Freshdesk account
4. A maximum of 25 fields can be set as filterable within a Custom Object. A field can be set as filterable at the time of creation, and cannot be edited later to be made filterable
Create A Custom Object
You can create a Custom Object through the UI by providing its Name, Description and Icon. You can also add the fields and lookup relationships between the Objects (both Custom and Native) through the UI. More information can be found here
With the help of APIs listed below, you can retrieve the list of existing Custom Objects and read a specific Custom Object's Schema. You can also perform create, read, update, and delete operations on the Custom Object records.
Retrieve Existing Custom Objects
/api/v2/custom_objects/schemas
The response lists all the existing Custom Object schemas along with the field names and their attributes such as field type, marked required or optional etc.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET "https://domain.freshdesk.com/api/v2/custom_objects/schemas" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 | { "schemas": [ { "name": "Bookings", "prefix": "BKG", "title": null, "description": null, "version": 1, "deleted": false, "id": 30, "created_time": 1624081385288, "updated_time": 1624081385288, "fields": [ { "id": "09ec0f82-6908-460f-8428-786afa208789", "name": "customer_id", "label": "Customer ID", "type": "PRIMARY", "position": 1, "required": true, "editable": true, "visible": true, "deleted": false, "placeholder": null, "hint": null, "filterable": true, "searchable": true, "parent_id": null, "choices": [] }, { "id": "e573039c-d7c2-481d-8cbb-5ea3a261881d", "name": "customer_name", "label": "Customer Name", "type": "TEXT", "position": 2, "required": true, "editable": true, "visible": true, "deleted": false, "placeholder": null, "hint": null, "filterable": true, "searchable": true, "parent_id": null, "choices": [] }, { "id": "f967039c-d7c2-481d-8cbb-5yu3a261783d", "name": "age", "label": "Age", "type": "NUMBER", "position": 3, "required": true, "editable": true, "visible": true, "deleted": false, "placeholder": null, "hint": null, "filterable": true, "searchable": true, "parent_id": null, "choices": [] } ] } ] } |
Retrieve A Specific Custom Object
/api/v2/custom_objects/schemas/{schema-id}
The following are the default read-only meta fields present in every Custom Object.
Attributes | Description |
---|---|
display_id | Unique Identifier for the record |
created_time | The timestamp at which the record is created |
updated_time | The timestamp at which the record is last updated |
The response retrieves the specified Custom Object schema along with the field names and their attributes such as field type, marked required or optional etc.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | { "name": "Bookings", "prefix": "BKG", "title": null, "description": null, "version": 1, "deleted": false, "id": 30, "created_time": 1624081385288, "updated_time": 1624081385288, "fields": [ { "id": "09ec0f82-6908-460f-8428-786afa208789", "name": "customer_id", "label": "Customer ID", "type": "PRIMARY", "position": 1, "required": true, "editable": true, "visible": true, "deleted": false, "placeholder": null, "hint": null, "filterable": true, "searchable": true, "parent_id": null, "choices": [] }, { "id": "e573039c-d7c2-481d-8cbb-5ea3a261881d", "name": "customer_name", "label": "Customer Name", "type": "TEXT", "position": 2, "required": true, "editable": true, "visible": true, "deleted": false, "placeholder": null, "hint": null, "filterable": true, "searchable": true, "parent_id": null, "choices": [] }, { "id": "f967039c-d7c2-481d-8cbb-5yu3a261783d", "name": "age", "label": "Age", "type": "NUMBER", "position": 3, "required": true, "editable": true, "visible": true, "deleted": false, "placeholder": null, "hint": null, "filterable": true, "searchable": true, "parent_id": null, "choices": [] } ] } |
Create A Record
/api/v2/custom_objects/schemas/schema-id/records/
Note:
1. The field names and their attributes to construct the request body can be obtained using the Retrieve Custom Object API.
2. While creating a record with a Lookup field value, the ID of the Object should be specified as the Lookup field value.
- For Tickets, display_id should be used as the Lookup field value
- For Contacts, org_contact_id should be used as the Lookup field value.
- For Companies, org_company_id should be used as the Lookup field value
- For Custom Objects, id of the record should be used as the Lookup field value
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30/records" -d '{ "data": { "customer_id": "C1234", "customer_name": "Alan Turing", "age": 35 } }' |
Response
1 2 3 4 5 6 7 8 9 10 | { "display_id": "BKG-1", "created_time": 1615529200004, "updated_time": 1615529200004, "data": { "customer_id": C1234, "customer_name": "Alan Turing", "age": 35 } } |
Retrieve A Record
/api/v2/custom_objects/schemas/{schema-id}/records/{record-id}
The response retrieves the specified record from an existing Custom Object with all the field values (including null values).
Note:
1. The version property tracks the revisions made to a Custom Object Record and prevents data loss when multiple agents update the same record.
2. When a record is created, its version is set to 1. Future retrievals will include the current version number, which must be included in updates to ensure changes apply to the latest version. If an outdated version is used, the update will fail to persist the new changes, ensuring no recent updates are lost.
3. To avoid conflicts, always fetch the latest version using the Record Fetch API, retain the version information, and include it in your update request.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30/records/BKG-1" |
Response
1 2 3 4 5 6 7 8 9 10 11 | { "display_id": "BKG-1", "created_time": 1615529200004, "updated_time": 1615529200004, "data": { "license_no": null, "customer_id": C1234, "email": "john@freshworks.com", "status": null } } |
Update A Record
/api/v2/custom_objects/schemas/schema-id/records/{record-id}
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30/records/BKG-1" -d '{ "display_id": "BKG-1", "data": { "customer_id": "C1234", "customer_name": "Alan Turing", "age": 36 } }' |
Response
1 2 3 4 5 6 7 8 9 10 | { "display_id": "BKG-1", "created_time": 1615532081008, "updated_time": 1615532488376, "data": { "customer_id": C12345, "customer_name": "Alan Turing", "age": 36 } } |
Delete A Record
/api/v2/custom_objects/schemas/schema-id/records/{record-id}
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X DELETE "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30/records/BKG-1" |
Response
1 | 204 No Content |
Retrieve All Records
/api/v2/custom_objects/schemas/schema-id/records
Supported request parameters
Attributes | Type | Description |
---|---|---|
page_size | Integer | The number of records to be returned in a single query per page |
_links | Object | Contains links for actions such as navigation, count of records etc. |
_links.next | String | To fetch the records in the next page(acts as next page link) |
_links.prev | String | To fetch the records in the previous page (acts as previous page link) |
_links.count | String | To retrieve the total number of records for a specific Custom Object |
Note:
1. By default, 20 records will be returned in a single query per page
2. A maximum of 100 records can be returned in a single query per page and the pages can only be fetched sequentially
3. For navigating to the next page, use the 'next' page link present in the '_links' parameter.As the 'next' page link in the response is a relative end point, add prefix 'https://domain.freshdesk.com/api/v2/custom_objects' to form the absolute endpoint and invoke the request.
For example: If the relative next page link is "/schemas/30/records?page_size=2&next_token=Lbr2zerj3WHNDsZ1XkS5BLhIl0ATadaz1nfS5KXTvR7", then the absolute next page link should be 'https://domain.freshdesk.com/api/v2/custom_objects/schemas/30/records?page_size=2&next_token=Lbr2zerj3WHNDsZ1XkS5BLhIl0ATadaz1nfS5KXTvR7'
4. Similarly, for navigating to the previous page, use the 'prev' page link present in the '_links' parameter. As the 'prev' page link in the response is a relative end point, add prefix 'https://domain.freshdesk.com/api/v2/custom_objects' to form the absolute endpoint and invoke the request.
5. For retrieving the total number of records , use the 'count' link present in the '_links' parameter. As the 'count' link in the response is a relative end point, add prefix 'https://domain.freshdesk.com/api/v2/custom_objects' to form the absolute endpoint and invoke the request.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30/records?page_size=2" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | { "records": [ { "display_id": "BKG-2", "created_time": 1615532081010, "updated_time": 1615532081010, "data": { "customer_id": "C6789", "customer_name": "Dennis Ritchie", "age": 40 }, "metadata": { "primary_field_name": "customer_id" } }, { "display_id": "BKG-1", "created_time": 1615532081008, "updated_time": 1615532081008, "data": { "customer_id": "C1234", "customer_name": "Alan Turing", "age": 30 }, "metadata": { "primary_field_name": "customer_id" } } ], "_links": { "next": { "href": "/schemas/30/records?page_size=2&prev_token=&next_token=xyz" }, "count": { "href": "/schemas/30/records/count" }, "prev": { "href": "/schemas/30/records?page_size=2&prev_token=abc&next_token=" } } } |
Retrieve The Count Of Records
/api/v2/custom_objects/schemas/schema_id/records/count
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30/records/count" |
Response
1 2 3 | { "count": 12 } |
Filter Records Of A Custom Object
/api/v2/custom_objects/schemas/schema_id/records?{field-name}{operator}{value}
The query parameters can be specified to filter the records. The query parameters is a list of conditions connected by the AND operator. A condition consists of three components i.e Operand, Operator and Value. For Custom Object records, Operand is the Field name and Value is the Field Value. Example: {field_name}{operator}{field_value}
Supported Operators
Operator | URL Encoded Equivalent | Description |
---|---|---|
= | = | Equal to |
> | %5Bgt%5D= | Greater than |
< | %5Blt%5D= | Less than |
>= | %5Bgte%5D= | Greater than or equal to |
<= | %5Blte%5D= | Less than or equal to |
Note:
1. System fields 'created_time' and 'updated_time' can also be used as the Operands. These fields must be provided in YYYY-MM-DDTHH:mm:ss.SSSZ format.
2. The Operator and the Field value must be URL encoded (See sample code below)
3. The Operators != (Not equal to) and 'OR' are not supported
4. To filter records using a Lookup field, the ID of the Object should be specified as the field value.
- For Tickets, display_id should be used as the field value
- For Contacts, org_contact_id should be used as the field value.
- For Companies, org_company_id should be used as the field value
- For Custom Objects, id of the record should be used as the Lookup field value
Supported Request Parameters
Parameters | Type | Description |
---|---|---|
sort_by | string | Sort the records by the Field name |
sort_order | string | Order of sorting the records (ASC or DESC) |
Note:
1. Sorting can only be performed on the filterable fields. By default, the result is sorted on the Created Time
2. Although sorting can be performed on the dropdown fields, the order of data will be in an arbitrary fashion.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30/records?age%5Bgte%5D=35&updated_time%5Bgte%5D=2020-09-23T22:35:45.000Z&sort_by=customer_name;ASC&page_size=2" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | { "records": [ { "display_id": "BKG-2", "created_time": 1615532081010, "updated_time": 1615532081010, "data": { "customer_id": "C6789", "customer_name": "Dennis Ritchie", "age": 40 }, "metadata": { "primary_field_name": "customer_id" } }, { "display_id": "BKG-6", "created_time": 1615532088908, "updated_time": 1615532088908, "data": { "customer_id": "C4554", "customer_name": "James Gosling", "age": 36 }, "metadata": { "primary_field_name": "customer_id" } } ], "_links": { "next": { "href": "/schemas/30/records?age%5Bgte%5D=35&sort_by=customer_name;ASC&page_size=2&prev_token=&next_token=xyz" }, "count": { "href": "/schemas/30/records/count?age%5Bgte%5D=35" }, "prev": { "href": "/schemas/30/records?age%5Bgte%5D=35&sort_by=customer_name;ASC&page_size=2&prev_token=abc&next_token=" } } } |
Error Descriptions
The common errors returned are listed below.
Error type | Error Sample |
---|---|
When trying to get a Custom Object that does not exist | { "error_type": "RESOURCE_NOT_FOUND", "message": "Custom object with id '4239567577' does not exist.", "errors": [] } |
Reached the maximum limit of custom objects per Account | { "error_type": "CONSTRAINT_VIOLATION", "message": "Reached the maximum limit of 20 custom objects.", "errors": [] } |
Provided duplicate field name | {
"error_type": "INVALID_INPUT",
"message": "Invalid input",
"errors": [
{
"type": "schema",
"name": "fields",
"message": "There is another field with the same label ' |
Provided invalid choice value | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "country", "message": "Invalid choice 'India' for 'Country' field." } ] } |
Version mismatch in Record | { "error_type": "CONSTRAINT_VIOLATION", "message": "Constraint violation", "errors": [ { "type": "record", "name": "version", "message": "Unable to update the record. Please try again." } ] } |
Field does not exist | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "order_name", "message": "Field does not exist." } ] } |
Invalid permission in permission token | { "error_type": "PERMISSION_NOT_ALLOWED", "message": "Permission not allowed", "errors": [ { "type": "schema", "name": "permission", "message": "You do not have the required permissions to perform this action." } ] } |
Reached the maximum limit on the number of fields per Custom Object | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "type": "schema", "name": "fields", "message": "Reached the maximum limit of 100 fields." } ] } |
Reached the maximum limit on the number of filterable fields per Custom Object | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "type": "schema", "name": "fields", "message": "Reached the maximum limit of 30 filterable fields." } ] } |
Reached the maximum limit on the number of searchable fields per Custom Object | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "type": "schema", "name": "fields", "message": "Reached the maximum limit of 60 searchable fields." } ] } |
Reached the maximum limit on the number of unique fields per Custom Object | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "type": "schema", "name": "fields", "message": "Reached the maximum limit of 6 unique fields." } ] } |
Reached the maximum limit on the number of lookup fields per Custom Object | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "type": "schema", "name": "fields", "message": "Reached the maximum limit of 5 lookup fields." } ] } |
When value entered in a TEXT field is more than 256 characters long | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "customer_name", "message": "Value must not exceed 256 characters for 'Customer Name' field." } ] } |
When a decimal value is provided for a NUMBER field | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "pincode", "message": "Please enter a valid number for 'Pincode' field." } ] } |
When a number value is provided for a DECIMAL field | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "amount_paid", "message": "Please enter a valid decimal value for 'Amount Paid' field." } ] } |
Invalid or an already deleted choice is provided while creating or updating records | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "order_status", "message": "Invalid choice 'closed' for 'Order Status' field." } ] } |
Invalid value is provided for TEXT field | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "first_name", "message": "Please enter a valid text for 'First Name' field." } ] } |
Invalid value is provided for Checkbox field | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "is_indian_citizen", "message": "Please enter a boolean value for 'Is Indian Citizen' field." } ] } |
Invalid value is provided for Paragraph field | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "address", "message": "Please enter a valid text for 'Address' field." } ] } |
Invalid value is provided for Date field | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "date_of_birth", "message": "Please enter a valid date for 'Date of Birth' field." } ] } |
When trying to get a Record with an invalid prefix provided in its ID. | { "error_type": "RESOURCE_NOT_FOUND", "message": "Record with id 'CUS-123' does not exist.", "errors": [] } |
When trying to get a Record that does not exist | { "error_type": "RESOURCE_NOT_FOUND", "message": "Record with id 'CUS-123' does not exist.", "errors": [] } |
A custom object with records cannot be deleted. | { "error_type": "DELETION_NOT_ALLOWED", "message": "Deletion not allowed", "errors": [ { "type": "schema", "name": "", "message": "A custom object with records cannot be deleted. Delete the records first and try again." } ] } |
Invalid field specified in sort parameter. | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "sort_by", "message": "Invalid field specified in sort parameter." } ] } |
Invalid sort order specified in sort parameter. | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "sort_by", "message": "Invalid sort order specified in sort parameter." } ] } |
Invalid value is provided as sort parameter. | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "sort_by", "message": "Invalid value provided as sort parameter." } ] } |
When the specified field cannot be used to filter records. | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "customer_name", "message": "Field 'Customer Name' cannot be used to filter records." } ] } |
When more than 10 filter conditions are applied while querying the list of records. | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "filters", "message": "A maximum of 10 filter conditions can be applied while querying the list of records." } ] } |
When the Custom object with specified id does not exist. | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "order_id", "message": "Custom object with id '3451' does not exist." } ] } |
Invalid value specified for a field in filter condition. | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "order_id", "message": "Please enter a valid value for 'Order ID' field in filter condition." } ] } |
Invalid conditional operator provided for a field. | { "error_type": "INVALID_INPUT", "message": "Invalid input", "errors": [ { "name": "first_name", "message": "Please enter a valid conditional operator for 'First Name' field." } ] } |
Canned Responses
Canned Responses are predefined reply templates which can be used to quickly send out replies to tickets. Canned Responses reside inside canned response folders. These APIs allow access to the folders and responses under the folders.
Note:
Only users with admin privileges can access the following APIs.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the canned response folder |
name | string | Name of the canned response folder |
personal | boolean | Set true if the folder can be accessed only by you |
responses_count | number | Number of canned responses in the folder |
created_at | datetime | Canned Response Folders creation timestamp |
updated_at | datetime | Canned Response Folders updated timestamp |
Create a canned response
/api/v2/canned_responses
Attribute | Type | Description |
---|---|---|
title Mandatory | string | Title of the canned response |
content_html Mandatory | string | HTML version of the canned response content. |
folder_id Mandatory | number | Folder where the canned response gets added |
visibility Mandatory | number | Denotes the visibility of the canned response. Possible values are: 0- If it is visible to all agents, 1- If it is personal, 2- If it is visible to select groups |
group_ids * | array of numbers | Groups for which the canned response is visible. Use only if visibility is set to 2. |
attachments | array of objects | Attachments associated with the canned response. The total size cannot exceed 20MB |
* Use only if visibility is set to 2. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "title":"Sample canned response", "content_html":"This is a sample canned response","folder_id":4,"visibility":1]}' 'https://domain.freshdesk.com/api/v2/canned_responses' |
Response
1 2 3 4 5 6 7 8 9 10 | { "id":35000093982, "title":"Sample canned response", "folder_id":4, "content":"This is a sample canned response", "content_html":"<div>This is a sample canned response</div>", "attachments":[], "created_at":"2020-08-24T06:53:36Z", "updated_at":"2020-08-24T06:53:36Z" } |
View a Canned Response
/api/v2/canned_responses/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/canned_responses/82000005490’ |
Response
1 2 3 4 5 6 7 8 9 10 | { "id": 82000005490, "title": "We’ve received your request", "folder_id": 82000010465, "content": "Thank you for reaching out to us. Our team will look into your request and get back to you shortly. \n \n \n You can check the status of your request and add comments here:\n \n {{ticket.url}}\n \n \n Regards, \n {{ticket.agent.name}}", "content_html": "<div dir=\"ltr\">\n Thank you for reaching out to us. Our team will look into your request and get back to you shortly. \n <br>\n <br>\n You can check the status of your request and add comments here:\n <br>\n {{ticket.url}}\n <br>\n <br>\n Regards,<br>\n {{ticket.agent.name}}\n </div>\n ", "attachments": [], "created_at": "2020-09-08T11:08:10Z", "updated_at": "2020-09-08T11:08:10Z" } |
Update a canned response
api/v2/canned_responses/[id]
Attribute | Type | Description |
---|---|---|
title | string | Title of the canned response |
content_html | string | HTML version of the canned response content. |
folder_id | number | Folder where the canned response gets added |
visibility | number | Denotes the visibility of the canned response. Possible values are: 0- If it is visible to all agents, 1- If it is personal, 2- If it is visible to select groups |
group_ids * | array of numbers | Groups for which the canned response is visible. Use only if visibility is set to 2. |
attachments | array of objects | Attachments associated with the canned response. The total size cannot exceed 20MB |
* Use only if visibility is set to 2. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "title":"Sample canned response - updated", "content_html":"This is a sample canned response.","folder_id":4,"visibility":1]}' 'https://domain.freshdesk.com/api/v2/canned_responses/35000093982' |
Response
1 2 3 4 5 6 7 8 9 10 | { "id":35000093982, "title":"Sample canned response - updated", "folder_id":4, "content":"This is a sample canned response", "content_html":"<div>This is a sample canned response.</div>", "attachments":[], "created_at":"2020-08-24T06:53:36Z", "updated_at":"2020-08-24T06:58:36Z" } |
Bulk Create Canned Responses
/api/v2/canned_responses/bulk
Attribute | Type | Description |
---|---|---|
titleMandatory | string | Title of the canned response |
content_htmlMandatory | string | HTML version of the canned response content. |
folder_idMandatory | number | Folder where the canned response gets added. |
visibilityMandatory | number |
Denotes the visibility of the canned response. Possible values are:
0- If it is visible to all agents,
1- If it is personal,
2- If it is visible to select groups
|
group_ids | Array of numbers | Groups for which the canned response is visible. Use only if visibility is set to 2. |
attachments | Array of objects | Attachments associated with the canned response. The total size cannot exceed 20MB. |
Note:
1. group_ids is mandatory only if the visibility is set to 2.
2. Folder_id is not mandatory when the visibility is set to 1.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"canned_responses":[{"title":"Sample canned response", "content_html":"This is a sample canned response","folder_id":82000010465,"visibility":1},{"title":"Second response", "content_html":"This is the second canned response","folder_id":82000010455,"visibility":1}] }' 'https://domain.freshdesk.com/api/v2/api/v2/canned_responses/create_multiple' |
Response
1 2 3 4 | { "job_id": 100, "href": "https://domain.freshdesk.com/api/v2/jobs/100" } |
Create Folder
/api/v2/canned_response_folder
Attribute | Type | Description |
---|---|---|
nameMandatory | string | Name of the folder |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "name":"Folder"}' 'https://domain.freshdesk.com/api/v2/canned_response_folders' |
Response
1 2 3 4 | { "Id":82000044383, "name":"Folder" } |
Update Folder
/api/v2/canned_response_folder/[id]
Attribute | Type | Description |
---|---|---|
nameMandatory | string | Name of the folder |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "name":"Updated folder"}' 'https://domain.freshdesk.com/api/v2/canned_response_folders/82000044383' |
Response
1 2 3 4 | { "Id":82000044383, "name":"Updated Folder" } |
List All Folders
/canned_response_folders
To view all the canned response folders.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/canned_response_folders' |
Response
1 2 3 4 5 6 7 8 9 10 | [ { "id":1, "name":"My folder", "personal":false, "responses_count":3, "created_at":"2018-08-16T09:08:53+05:30", "updated_at":"2018-08-16T09:08:53+05:30" } ] |
List All Canned Responses in a Folder
/canned_response_folders/[id]
To view all canned responses in a folder.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/canned_response_folders/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 | { "id":1, "name":"My folder", "canned_responses" : [ { "id": 1, "title": "Canned response 1" } ], "created_at":"2018-08-16T09:08:53+05:30", "updated_at":"2018-08-16T09:08:53+05:30" } |
Get details of Canned Responses in a Folder
/canned_response_folders/[id]/responses
To view all the details of canned responses in a folder.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the canned response |
title | string | Title of the canned response |
folder_id | number | Set to true if the folder can be accessed only by you |
content | string | Plaintext version of the canned response content |
content_html | string | HTML version of the canned response content |
attachments | array | Attachments associated with the canned response |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/canned_response_folders/1/responses' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | [ { "id":1, "title":"Canned Response title 1", "folder_id":1, "content":"Canned response sample content", "content_html":"<div dir=\"ltr\">Canned response sample content<div>" "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" } ] |
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
/api/v2/discussions/categories
Parameters
Attribute | Type | Description |
---|---|---|
description | string | Description of the forum category |
nameMandatoryUnique | string | Name of the forum category |
Sample code | Curl
1 | 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
1 2 3 4 5 6 7 | { "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
/api/v2/discussions/categories/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories/2' |
Response
1 2 3 4 5 6 7 | { "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
/api/v2/discussions/categories
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | [ { "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" } ] |
List All Forums in a Category
/api/v2/discussions/categories/[id]/forums
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories/2/forums' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 | [ { "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 } ] |
Update a Forum Category
/api/v2/discussions/categories/[id]
Parameters
Attribute | Type | Description |
---|---|---|
description | string | Description of the forum category |
nameUnique | string | Name of the forum category |
Sample code | Curl
1 | 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
1 2 3 4 5 6 7 | { "id" : 2, "name" : "Report Problems", "description" : "Tell us your problems", "created_at" : "2015-08-25T07:47:49Z", "updated_at" : "2015-08-25T07:53:00Z" } |
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
/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_typeMandatory | number | Denotes the type of forum (Supported types can be referred in the Forum type table below) |
forum_visibilityMandatory | number | Denotes the visibility level of the forum (Supported types can be referred in the Forum visibility table below) |
nameMandatoryUnique | 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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | { "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 ] } |
View A Forum
/api/v2/discussions/forums/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 | { "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 } |
List All Topics in a Forum
/api/v2/discussions/forums/[id]/topics
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/5/topics' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | [ { "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" } ] |
Update a Forum
/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) |
nameUnique | 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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 | { "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 } |
Monitor Forum
/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
1 | 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
1 | HTTP Status: 204 No Content |
Monitoring Status For Forum
/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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/14581/follow?user_id=2' |
Response
1 | 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
/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 |
messageMandatory | 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 |
titleMandatory | 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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "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" } |
View a Topic
/api/v2/discussions/topics/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/3' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "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" } |
List All Comments in a Topic
/api/v2/discussions/topics/[id]/comments
To view all conversations/comments/comments in a specific topic, use this API
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/1/comments' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | [ { "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" } ] |
Update a Topic
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "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" } |
Monitor Topic
/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
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '' 'https://domain.freshdesk.com/api/v2/discussions/topics/1/follow' |
Response
1 | HTTP Status: 204 No Content |
Unmonitor Topic
/api/v2/discussions/topics/[topic_id]/follow?user_id=[user_id]
Sample code | Curl
1 | 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
1 | HTTP Status: 204 No Content |
Monitoring Status For Topic
/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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/14581/follow?user_id=2' |
Response
1 | HTTP Status: 204 No Content |
List All Monitored Topics
/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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/followed_by?user_id=12' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | [ { "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" } ] |
List All Participated Topics
/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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/participated_by?user_id=27' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | [ { "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" } ] |
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
/api/v2/discussions/topics/[topic_id]/comments
Parameters
Attribute | Type | Description |
---|---|---|
bodyMandatory | string | Content of the comment in HTML |
Sample code | Curl
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "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" } |
Update A Comment
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "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" } |
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
/api/v2/solutions/categories
Parameters
Attribute | Type | Description |
---|---|---|
description | string | Description of the solution category |
nameMandatoryUnique | 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
1 | 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
1 2 3 4 5 6 7 | { "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
/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
1 | 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
1 2 3 4 5 6 7 | { "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
/api/v2/solutions/categories/[id]
Parameters
Attribute | Type | Description |
---|---|---|
description | string | Description of the solution category |
nameUnique | 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
1 | 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
1 2 3 4 5 6 7 | { "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
/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
1 | 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
1 2 3 4 5 6 7 | { "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
/api/v2/solutions/categories/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3' |
Response
1 2 3 4 5 6 7 | { "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
/api/v2/solutions/categories/[id]/[language_code]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/es' |
Response
1 2 3 4 5 6 7 | { "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
/api/v2/solutions/categories
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | [ { "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" } ] |
View all translated solution categories
/api/v2/solutions/categories/[language_code]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/es' |
Response
1 2 3 4 5 6 7 8 9 | [ { "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
/api/v2/solutions/categories/[id]
Note:
When deleted, all translated versions will be deleted too.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/categories/3' |
Response
1 | 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
/api/v2/solutions/categories/[id]/folders
Parameters
Attribute | Type | Description |
---|---|---|
description | string | Description of the solution folder |
nameMandatoryUnique | 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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | { "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" } |
Create a translated solution folder
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | { "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" } |
Update a Solution Folder
/api/v2/solutions/folders/[id]
Parameters
Attribute | Type | Description |
---|---|---|
description | string | Description of the solution folder |
nameUnique | 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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | { "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] } |
Update a translated solution folder
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | { "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] } |
View a Solution Folder
/api/v2/solutions/folders/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | { "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" } |
View a translated solution folder
/api/v2/solutions/folders/[id]/[language_code]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/es' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | { "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" } |
List all Solution Folders in a Category
/api/v2/solutions/categories/[category_id]/folders
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/folders' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | [ { "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] } ] |
View all translated solution folders in a category
/api/v2/solutions/categories/[category_id]/folders/[language_code]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/folders/es' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | [ { "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] } ] |
List all Folders in a Folder
/api/v2/solutions/folders/[folder_id]/subfolders
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/2/subfolders' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | [ { "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] } ] |
List all translated folders in a folder
/api/v2/solutions/folders/[folder_id]/subfolders/[language_code]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/2/subfolders/es' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | [ { "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] } ] |
Delete a Solution Folder
/api/v2/solutions/folders/[id]
Note:
When deleted, all translated versions will be deleted too.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/folders/3' |
Response
1 | 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
/api/v2/solutions/folders/[id]/articles
Parameters
Attribute | Type | Description |
---|---|---|
descriptionMandatory | string | Description of the solution article |
statusMandatory | 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 |
titleMandatory | string | Title of the solution article |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "title": "sample article", "description" : "this is a sample article with some <b> HTML Content </b>", "status": 1, "seo_data" : { "meta_keywords" : ["sample", "demo", "article"] } }' 'https://domain.freshdesk.com/api/v2/solutions/folders/4/articles' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | { "id": 2, "title": "sample article", "description": "this is a sample article with some <b> HTML Content </b>", "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" } |
Create a translated solution article
/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
1 | 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 <b> Contenido HTML </b>", "status": 1 }' 'https://domain.freshdesk.com/api/v2/solutions/articles/2/es' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | { "id": 2, "title": "artículo de la muestra", "description": "este es un artículo de la muestra con un poco de <b> Contenido HTML </b>", "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" } |
Update a Solution Article
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | { "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" } |
Update a translated solution article
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | { "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" } |
View a Solution Article
/api/v2/solutions/articles/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/articles/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | { "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" } |
View a translated solution article
/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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/articles/2/es' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | { "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" } |
List all Solution Articles in a Folder
/api/v2/solutions/folders/[id]/articles
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/articles' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | [ { "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 <b> HTML Content </b>", "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" } ] |
View all translated solution articles in a folder
/api/v2/solutions/folders/[id]/articles/[language_code]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/articles/es' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | [ { "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" } ] |
Delete a Solution Article
/api/v2/solutions/articles/[id]
Note:
When deleted, all translated versions will be deleted too.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/articles/2' |
Response
1 | HTTP Status: 204 No Content |
Search solution articles
/api/v2/search/solutions?term=[keyword]
Search the articles in your Freshdesk account using a keyword.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/solutions?term=sample' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 | [ { "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": "<p>sample description</p>", "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" } ] |
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
/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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | [ { "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" } }, ... ] |
Additional Examples
1. Get a list of surveys filtered by the state.
1 | 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
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | { "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" } |
View all Satisfaction Ratings
/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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys/satisfaction_ratings' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | [ { "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" } ] |
Additional Examples
1. Get a list of satisfaction ratings filtered by the user_id.
1 | 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
/api/v2/tickets
To create a service task, use the Create A Ticket API.
- 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | { "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": "<div>Regular annual maintenance for Forklift A</div>", "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 ] } |
View a Service Task
/api/v2/tickets/[id]
To view a service task, use the View a Ticket API.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/125' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | { "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": "<div>Regular annual maintenance for Forklift A</div>", "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 } |
Update a Service Task
/api/v2/tickets/[id]
To update a service task, use the Update a Ticket API.
Sample code | Curl
1 2 3 4 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | { "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": "<div>test description</div>", "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 } |
Delete a Service Task
/api/v2/tickets/[id]
To delete a service task, use the Delete A Ticket API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/125' |
Response
1 | HTTP Status: 204 No Content |
Service Group
Create a Service Group
/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
1 2 3 4 5 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "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" } |
View a Service Group
/api/v2/groups/[id]
To view a service group, use the View A Group API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/groups/7861' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "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 ] } |
Update a Service Group
/api/v2/groups/[id]
To update a service group, use the Update A Group API.
Sample code | Curl
1 2 3 4 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "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" } |
Delete a Service Group
/api/v2/groups/[id]
To delete a service group, use the Delete A Group API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/groups/1' |
Response
1 | 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 technicianMake Field Technician
/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
1 2 3 4 5 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "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 } } |
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
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "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" } |
List All Time Entries
/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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/time_entries' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | [ { "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" } ] |
Additional Examples
1. Get the list of billable time_entries
1 | 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
1 | 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
/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
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "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" } |
Start/Stop Timer
/api/v2/time_entries/[time_entry_id]/toggle_timer
Sample code | Curl
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "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" } |
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
/api/v2/email_configs/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email_configs/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 | { "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" } |
List All Email Configs
/api/v2/email_configs
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email_configs' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | [ { "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" } ] |
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
/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
1 | 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
1 2 3 4 5 | { "name": "Test emailbox via create api", "support_email": "testemail@gmail.com", "mailbox_type": "freshdesk_mailbox" } |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "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" } } |
Create a custom mailbox
Sample code | Curl
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "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" } } } |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "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" } } } |
View an Email Mailbox
/api/v2/email/mailboxes/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "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" } } } |
List All Email Mailboxes
/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?<filter>=<value> 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?<filter>=<value> 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
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | [ { "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" } }, ... ] |
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.
1 | 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.
1 | 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)
1 | 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
/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
1 | 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
1 2 3 4 5 6 | { "name": "Test emailbox via update api", "support_email": "testemail@gmail.com", "group_id": 1, "mailbox_type": "freshdesk_mailbox", } |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "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" } } |
Update a custom mailbox
Sample code | Curl
1 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "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" } } } |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "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" } } } |
Delete an Email Mailbox
/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
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/email/mailboxes/1' |
Response
1 | HTTP Status: 204 No Content |
Update Mailbox Settings
/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
1 | 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
1 2 3 4 5 6 | { "personalized_email_replies": true, "create_requester_using_reply_to": true, "allow_agent_to_initiate_conversation": true, "original_sender_as_requester_for_forward": true } |
Response
1 2 3 4 5 6 | { "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
/api/v2/email/settings
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT GET 'https://domain.freshdesk.com/api/v2/email/settings' |
Response
1 2 3 4 5 6 | { "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
/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
1 | 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
1 2 3 | { "emails": ["testemail1@gmail.com", "testemail2@gmail.com"] } |
Response
1 2 3 | { "emails": ["testemail1@gmail.com", "testemail2@gmail.com"] } |
View Automatic Bcc emails
/api/v2/notifications/email/bcc
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/notifications/email/bcc' |
Response
1 2 3 | { "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
/api/v2/products/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/products/1' |
Response
1 2 3 4 5 6 7 | { "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
/api/v2/products
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/products' |
Response
1 2 3 4 5 6 7 8 9 | [ { "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'
|
||||||||||||
created_at | datetime | Business Hour creation timestamp | ||||||||||||
updated_at | datetime | Business Hour updated timestamp |
View a Business Hour
/api/v2/business_hours/[id]
To view a particular business hour amongst all in the roster, use this API
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/business_hours/35000006727' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "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" } |
List All Business Hours
/api/v2/business_hours
To view all the business hours in your list, use this API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/business_hours' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | [ { "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" } ] |
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
/scenario_automations.json
To view all the scenario automations in your list, use this API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/scenario_automations' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | [ { "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" } ] |
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.
|
||||||||||||||||||
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.
|
||||||||||||||||||
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.
|
Create SLA Policies
/api/v2/sla_policies
Parameters
Attribute | Type | Description |
---|---|---|
nameMandatory | string | Name of the SLA policy |
sla_targetMandatory | dictionary | Key value pair containing the object and the array of object IDs denoting the priorities and the applicable conditions. |
applicable_toMandatory | 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
1 | 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' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 | { "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" } |
List All SLA Policies
/api/v2/sla_policies
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/sla_policies' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | [ { "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" } ] |
Update an SLA Policy
/api/v2/sla_policies/[id]
Parameters
Attribute | Type | Description |
---|---|---|
applicable_toMandatory | 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
1 | 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' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 | { "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" } |
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
/api/v2/contact-activities
Parameters
Attribute | Type | Description | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
activityMandatory | object | Key value pair of the object which describes information about action that has occurred in an external application.
|
|||||||||||||||||||||||||||
contactMandatory | 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 |
---|---|---|
id | string | ID of the actor. |
typeMandatory | string | The type of the actor. As an example, the type could be "agent", "shopper", "user", "customer", "system". |
name | string | Name of the actor. |
Attribute | Type | Description |
---|---|---|
id | string | ID of the application, where the activity was performed. |
nameMandatory | string | Name of the application where the activity was performed. |
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
1 | 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' |
Response
1 | HTTP Status: 200 Success |
List All Automation Rules
/api/v2/automations/[automation_type_id]/rules
Attribute | Type | Description |
---|---|---|
automation_type_idMandatory | 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
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/automations/1/rules' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | { "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 } } |
View an Automation Rule
/api/v2/automations/[automation_type_id]/rules/[id]
Attribute | Type | Description |
---|---|---|
idMandatory | integer | ID of the automation rule |
automation_type_idMandatory | Integer | Type id of the automation |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/automations/1/rules/109866' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | { "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" } |
Delete an Automation Rule
/api/v2/automations/[automation_type_id]/rules/[id]
Attribute | Type | Description |
---|---|---|
idMandatory | integer | ID of the automation rule |
automation_type_idMandatory | Integer | Type id of the automation |
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/automations/1/rules/109866' |
Response
1 | HTTP Status: 204 No Content |
Create an Automation Rule
/api/v2/automations/[automation_type_id]/rules
Attribute | Type | Description |
---|---|---|
automation_type_idMandatory | Integer | Type id of the automation |
nameMandatory | 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 |
conditionsMandatory | 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 |
actionsMandatory | Array of objects | Actions to be performed by the rule on matching tickets |
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 |
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 |
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
|
Field Name | Type | Description |
---|---|---|
field_name | string | Name of the field |
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 |
Sample code | Curl
1 | 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": "<p dir=\"ltr\">Ticket has been assigned to agent</p>" } ] }' 'https://domain.freshdesk.com/api/v2/automations/4/rules' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 | { "name": "Send email to group", "position": 1, "active": true, "outdated": false, "last_updated_by": 82002117631, "id": 82000163682, "summary": { "performer": "When an action performed by <div class = SummaryKey>Agent</div> <div class = SummaryValue>Agent A</div> ", "events": [ "When <div class = SummaryKey>Agent</div> is changed from <div class = SummaryValue>ANY</div> to <div class = SummaryValue>Agent A</div>" ], "conditions": { "condition_set_1": [ "If <div class = SummaryKey>Agent</div> <div class = SummaryOperator>is</div> <div class = SummaryValue>NONE</div>" ] }, "actions": [ " <div class = SummaryKey>Send Email to Group</div> <div class = SummaryValue>Account managers</div>" ] }, "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": "<p dir=\"ltr\">Ticket has been assigned to agent</p>" } ], "meta": { "total_active_count": 3, "total_count": 3 } } |
Update an Automation Rule
/api/v2/automations/[automation_type_id]/rules/[id]
Sample code | Curl
1 | 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": "<p dir=\"ltr\">Ticket has been assigned to you. Please respond within the SLA</p>" } ] }' 'https://domain.freshdesk.com/api/v2/automations/4/rules/82000163682' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 | { "name": "Send email to agent", "position": 1, "active": true, "outdated": false, "last_updated_by": 82002117631, "id": 82000163682, "summary": { "performer": "When an action performed by <div class = SummaryKey>Agent</div> <div class = SummaryValue>Agent A</div> ", "events": [ "When <div class = SummaryKey>Agent</div> is changed from <div class = SummaryValue>ANY</div> to <div class = SummaryValue>Agent A</div>" ], "conditions": { "condition_set_1": [ "If <div class = SummaryKey>Agent</div> <div class = SummaryOperator>is</div> <div class = SummaryValue>NONE</div>" ] }, "actions": [ " <div class = SummaryKey>Send Email to Agent</div> <div class = SummaryValue>Agent A</div>" ] }, "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": "<p dir=\"ltr\">Ticket has been assigned to you. Please respond within SLA</p>" } ], "meta": { "total_active_count": 3, "total_count": 3 } } |
Settings
Settings are configured through the Admin page of the Freshdesk web app.
View Helpdesk Settings
/api/v2/settings/helpdesk
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/settings/helpdesk' |
Response
1 2 3 4 5 | { "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
api/v2/collaboration/threads
Sample code | Curl
1 2 3 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | [ { "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" } } ] |
Get a thread
api/v2/collaboration/threads/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/collaboration/threads/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | { { "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" } ] } |
Update a thread
api/v2/collaboration/threads/[id]
Sample code | Curl
1 2 3 4 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "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" } } } } |
Delete a thread
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
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/collaboration/threads/2' |
Response
1 | 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
api/v2/collaboration/messages
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body": "<div data-test-id=\"reply-editor-body-wrapper\" style=\"font-family:-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif; font-size:14px;\"><div dir=\"ltr\"><p>test</p></div></div>", "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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "id": "40", "body": "<div style=\"font-family:-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif; font-size:14px\"><div dir=\"ltr\"><div>test</div></div></div>", "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": "<div data-test-id=\"reply-editor-body-wrapper\" style=\"font-family:-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif; font-size:14px;\"><div dir=\"ltr\"><p>test</p></div></div><div class='freshdesk_quote'> <blockquote class='freshdesk_quote'>On Mon, 25 Sep at 12:21 PM , <span class='separator' />freshworks<support@freshworks8249.freshdesk.com> wrote: <div dir=\"ltr\"><div>test</div></div>\n<div rel=\"quoted-text\"></div>\n<div class=\"freshdesk_quote\"><blockquote class=\"freshdesk_quote\">On Mon, 25 Sep at 12:00 PM , <span class=\"separator\">freshworks<support@freshworks8249.freshdesk.com> wrote: <div style=\"font-family:-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif; font-size:14px\"><div dir=\"ltr\"><div>test</div></div></div>\n<div class=\"freshdesk_quote\"><blockquote class=\"freshdesk_quote\">On Mon, 25 Sep at 8:58 AM , <span class=\"separator\">freshworks<support@freshworks8249.freshdesk.com> wrote: <div>Please take a look at ticket <a href=\"https://freshworks8249.freshdesk.com/helpdesk/tickets/156\" rel=\"noreferrer\">#156</a> raised by Test (test@gmail.com).</div>\n<div dir=\"ltr\"><div>test</div></div>\n<div class=\"freshdesk_quote\"><blockquote class=\"freshdesk_quote\">On Mon, 25 Sep at 4:18 AM , Test <test@gmail.com> wrote:<div style=\"font-family:-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif; font-size:14px\"><div><br></div></div>\n</blockquote></div></span>\n</blockquote></div></span>\n</blockquote></div></blockquote</div>", "full_message_text": "test On Mon, 25 Sep at 12:21 PM , freshworks<support@freshworks8249.freshdesk.com> wrote: test On Mon, 25 Sep at 12:00 PM , freshworks<support@freshworks8249.freshdesk.com> wrote: test On 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). test On Mon, 25 Sep at 4:18 AM , Test <test@gmail.com> wrote:" |
Get message for thread
api/v2/collaboration/messages/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/collaboration/messages/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 | { "id": "21", "body": "<div style='box-sizing: border-box; color: rgb(24, 50, 71); font-family: -apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(247, 249, 250); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial'>Test</div>\n<div style='box-sizing: border-box; color: rgb(24, 50, 71); font-family: -apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(247, 249, 250); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial'><br style=\"box-sizing: border-box\"></div>\n<div style='box-sizing: border-box; color: rgb(24, 50, 71); font-family: -apple-system, \"system-ui\", \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(247, 249, 250); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial'>Thanks & regards,<br style=\"box-sizing: border-box\">Account administrator,<br style=\"box-sizing: border-box\">FW company,<br style=\"box-sizing: border-box\">phone-no:1234567890</div>", "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: " } |
Update message for thread
api/v2/collaboration/messages/[id]
Sample code | Curl
1 2 3 4 | 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | { "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" } ] } |
Delete message for thread
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
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/collaboration/messages/2' |
Response
1 | HTTP Status: 204 No Content |
Get quoted text for message
api/v2/collaboration/messages/[id]/generate-quote
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/collaboration/messages/{id}/generate-quote' |
Response
1 2 3 | { "quoted_text": "<div class=\"freshdesk_quote\"> <blockquote class=\"freshdesk_quote\"> On Tue, 29 Jun at 8:31 AM <span class=\"separator\" />, test test <test.test@test.com> wrote:<div dir=\"ltr\">test ticket<br>\\n</div>\\n\\n\\n</blockquote>\\n</div>" } |