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.

  1. Higher rate limits as a result of significant performance enhancements
  2. Improved error handling - errors will return appropriate HTTP status codes and an error body
  3. Four new API categories - Business Hours, Products, Email Configs, and SLAs
  4. 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
  5. XML Support has been deprecated, only JSON is supported
  6. Only SSL calls (HTTPS) will be allowed
  7. Works only via Freshdesk domains and not via custom CNAMEs
  8. Support for page sizes up to 100 has been added
  9. New API deprecation and breaking change policies
  10. 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.

Plan Rate Limit/hr
Blossom 3000
Garden 3000
Estate 5000
Forest 5000

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

January 2021

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

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

June 2018

May 2018

December 2017

July 2017

January 2017

September 2016

July 2016

June 2016

May 2016

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?

  1. Log in to your Support Portal
  2. Click on your profile picture on the top right corner of your portal
  3. Go to Profile settings Page
  4. 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.

If the time zone information is not present, it will be assumed to be in UTC.
( 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" : [ ]
}
EXPAND ↓

Attachments

Attachments are supported for the following endpoints
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.

Error Response

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"
        }
    ]
}

Error Response Fields
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.

Error Codes

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.

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.

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
Email
— 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
* partially supported

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
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.
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
Email 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

post
/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
Email 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
Copied Copy 
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'
EXPAND ↓
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" : [ ]
}
EXPAND ↓

Create a Ticket With Custom Fields

Note:
Refer this solution article for more details regarding custom fields.

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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" : [ ]
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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" : [ ] 
  }
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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",
     }
  ]
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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" : [ ]
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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" : [ ]
}
EXPAND ↓

Create an Outbound Email

post
/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
Copied Copy 
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'
EXPAND ↓
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" : [ ]
}
EXPAND ↓

View a Ticket

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/20'
EXPAND ↓
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" : [ ]
}
EXPAND ↓

Additional Examples

1. Get the associated conversations along with the ticket response.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=conversations'
EXPAND ↓

2. Get the associated company and requester information along with the ticket response.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=company,requester'
EXPAND ↓

3. Get the associated stats information along with the ticket response.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=stats'
EXPAND ↓

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
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/23'
EXPAND ↓
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" : [ ]
}
EXPAND ↓

Additional Information

The 'associated_tickets_list' attribute returns an array of associated ticket IDs based on the association type value

  1. When association_type is 1 (Parent), it will return the list of child IDs associated with the respective parent.
  2. When association_type is 2 (Child), it will return the respective parent ticket ID.
  3. When association_type is 3 (Tracker), it will return the list of related ticket IDs associated with the respective tracker.
  4. 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

get
/api/v2/tickets/[id]/associated_tickets
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/associated_tickets'
EXPAND ↓
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"
}
]
}
EXPAND ↓

Get Prime Association of a Ticket

get
/api/v2/tickets/[id]/prime_association
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/44/prime_association'
EXPAND ↓
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"
}
EXPAND ↓

List All Tickets

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets'
EXPAND ↓
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
    }
  }
]
EXPAND ↓

Additional Examples

1. Get the first page of a list of tickets, with the ticket description included for each ticket.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?include=description'
EXPAND ↓

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.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?filter=watching'
EXPAND ↓

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.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?requester_id=1230&order_by=status&order_type=desc'
EXPAND ↓

4. Get the second page (tickets from 11-20) of a list of all tickets.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?per_page=10&page=2'
EXPAND ↓

5. Get the first page of a list of tickets that have shown any activity since the 17th of August, 2015.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?updated_since=2015-08-17'
EXPAND ↓

6. Get the associated stats information along with the ticket response.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?include=stats'
EXPAND ↓

7. Filter tickets based on the following requester email (super+man@gmail.com) which needs to be URL encoded.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?email=super%2Bman%40gmail.com'
EXPAND ↓

Filter Tickets

get
/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.

Format -    "(ticket_field:integer OR ticket_field:'string') AND ticket_field:boolean"

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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:3"'
EXPAND ↓
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
      }
    },
    ...
    ...
    ...
    ...
  ]
}
EXPAND ↓

Additional Examples

1. Get the list of Urgent and High priority tickets.
    "priority:4 OR priority:3"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:4%20OR%20priority:3"'
EXPAND ↓

2. Get the second page of Open and Pending tickets.
    "status:3 OR status:4"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="status:3%20OR%20status:4"&page=2'
EXPAND ↓

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"

Copied Copy 
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"'
EXPAND ↓

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"

Copied Copy 
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"'
EXPAND ↓

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.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string: finance"'
EXPAND ↓

5. Get the list of Urgent and High priority tickets created on a particular day.
    "priority:>3 AND created_at:'2017-01-01'"

Copied Copy 
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"'
EXPAND ↓

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')"

Copied Copy 
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)"'
EXPAND ↓

7. Get the list of tickets whose type is 'Problem' and tagged with 'marketing'.
    "type:'Problem' AND tag:'marketing'"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="type:%27Problem%27%20AND%20tag:%27marketing%27"'
EXPAND ↓

8. Get the list of tickets without any tag.
    "tag:null"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="tag:null"'
EXPAND ↓

9. Get the list of urgent tickets whose type is undefined.
    "type:null AND priority:4"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="type:null%20AND%20priority:4"'
EXPAND ↓

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"

Copied Copy 
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"'
EXPAND ↓

11. Get the list of unassigned tickets
    "agent_id:null"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="agent_id:null"'
EXPAND ↓

12. All unresolved tickets
    "status:2 OR status:3 OR status:6 OR status:7"

Copied Copy 
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"'
EXPAND ↓

13. Get the list of tickets using a value in the single line text field.
    "custom_string:theactualkeyword"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeyword"'
EXPAND ↓
Using AND operator
"custom_string:theactualkeywordone AND custom_string:theactualkeywordtwo"
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeywordone%20AND%20custom_string:theactualkeywordtwo"'
EXPAND ↓
Using OR operator
"custom_string:theactualkeywordone OR custom_string:theactualkeywordtwo"
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeywordone%OR%20custom_string:theactualkeywordtwo"'
EXPAND ↓

Update a Ticket

put
/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.
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
Email 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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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" : [ ]
}
EXPAND ↓

Update Multiple Tickets

post
/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
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
4
{ 
"job_id": "e4d18654f60b5204513155b26c6cb",
 "href":"https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb"
 }
EXPAND ↓

The bulk ticket update happens at the background and the progress can be checked using the job_id in the response.

Copied Copy 
1
2
3
4
{
    "id": "e4d18654f60b5204513155b26c6cb",
    "status": "IN PROGRESS",
}
EXPAND ↓

Forward a ticket

post
/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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

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
put
/api/v2/tickets/merge
Sample code | Curl
Copied Copy 
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
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

List all watchers

get
/api/v2/tickets/[id]/watchers
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/watchers'
EXPAND ↓
Response 
1
2
3
4
5
6
7
{
  "watcher_ids": [
    35010088657,
    35008297863,
    35014948467
  ]
}
EXPAND ↓

Add watcher

post
/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
Copied Copy 
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'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Remove watcher

put
/api/v2/tickets/[id]/unwatch
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X PUT 'https://domain.freshdesk.com/api/v2/tickets/569/unwatch'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Add watcher to multiple tickets

put
/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
Copied Copy 
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'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Remove watcher from multiple tickets

put
/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
Copied Copy 
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'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Delete a Ticket

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Delete Multiple Tickets

post
/api/v2/tickets/bulk_delete
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
4
{ 
"job_id": "e4d18654f60b5204513155b26c6cb630",
 "href":"https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb630"
 }
EXPAND ↓

The bulk ticket deletion happens at the background and the progress can be checked using the job_id in the response.

Copied Copy 
1
2
3
4
{
    "id": "e4d18654f60b5204513155b26c6cb630",
    "status": "IN PROGRESS",
}
EXPAND ↓

Delete an attachment

delete
/api/v2/attachments/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/attachments/1'
EXPAND ↓
Response
Copied Copy 
1
HTTP Status: 204 No Content
EXPAND ↓

Restore a Ticket

put
/api/v2/tickets/[id]/restore
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshdesk.com/api/v2/tickets/1/restore'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

List All Ticket Fields

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket_fields'
EXPAND ↓
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"
  }
]
EXPAND ↓

Additional Examples

1. List the ticket_field that is of type 'default_requester'

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket_fields?type=default_requester'
EXPAND ↓

List All Conversations of a Ticket

get
/api/v2/tickets/[id]/conversations
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/conversations'
EXPAND ↓
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
  }
]
EXPAND ↓

Additional Examples

1. This ticket's conversation has more than 30 entries. This request returns the second page (entries from 31 to 60).

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/1/conversations?page=2'
EXPAND ↓

List All Time Entries of a Ticket

get
/api/v2/tickets/[id]/time_entries
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries'
EXPAND ↓
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"
  }
]
EXPAND ↓

Additional Examples

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries?page=2'
EXPAND ↓

List All Satisfaction Ratings of a Ticket

get
/api/v2/tickets/[ticket_id]/satisfaction_ratings
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/[ticket_id]/satisfaction_ratings'
EXPAND ↓
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"
    }
]
EXPAND ↓

Ticket Summary

The Summary feature can be used to let agents from other groups/teams know:
  • 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

get
/api/v2/tickets/[id]/summary
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/summary'
EXPAND ↓
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": []
}
EXPAND ↓

Update Summary

put
/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
Copied Copy 
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'
EXPAND ↓
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": []
}
EXPAND ↓

Delete Summary

delete
/api/v2/tickets/[id]/summary
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/20/summary'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

get
/api/v2/tickets/archived/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X  -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/archived/40'
EXPAND ↓
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" : [ ]
 }
EXPAND ↓

Delete an Archive Ticket

delete
/api/v2/tickets/archived/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X  -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/archived/432'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

List All Conversations of an Archive Ticket

get
/api/v2/tickets/archived/[id]/conversations
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/archived/20/conversations'
EXPAND ↓
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" : [ ] 
}
 ]
EXPAND ↓

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

post
/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
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
{
  "user_ids": [ 1, 2]
}
EXPAND ↓

Update Ticket User Access

patch
/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
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
{
  "user_ids": [ 1, 3]
}
EXPAND ↓

Get Ticket User Access

get
/api/v2/tickets/[id]/accesses
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X  -X GET 'https://domain.freshdesk.com/api/v2/tickets/7/accesses'
EXPAND ↓
Response 
1
2
3
{
  "user_ids": [ 8, 9 ]
}
EXPAND ↓

Remove Ticket User Access

delete
/api/v2/tickets/[id]/accesses
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X  -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/1/accesses'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

get
/api/v2/admin/ticket_fields

To view all ticket field details, use this API.

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
   }
]
EXPAND ↓

Create a Ticket Field

post
/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
Copied Copy 
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'
EXPAND ↓
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"
         }
      ]
   }
}
EXPAND ↓

View a Ticket Field

get
/api/v2/admin/ticket_fields/[id]
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
      }
   ]
}
EXPAND ↓

Update a Ticket Field

put
/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
Copied Copy 
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'
EXPAND ↓
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":[ 

         ]
      }
   ]
}
EXPAND ↓

Delete a Ticket Field

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

get
/api/v2/admin/ticket_fields/[id]/sections

To view all section details related to a ticket field, use this API.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/20/sections'
EXPAND ↓
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
      }
   ]
}
EXPAND ↓

Create a Section

post
/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
Copied Copy 
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'
EXPAND ↓
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
      }
   ]
}
EXPAND ↓

List a specific Section details

get
/api/v2/admin/ticket_fields/[id]/sections/[section_id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3'
EXPAND ↓
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
   }
}
EXPAND ↓

Update a section

put
/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
Copied Copy 
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'
EXPAND ↓
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
   }
}
EXPAND ↓

Delete a section

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms?include=portals'
EXPAND ↓
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"
            }
        ]
    }
]
EXPAND ↓

Create a Ticket Form

post
/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
Copied Copy 
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'
EXPAND ↓
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"
      }
   ]
}
EXPAND ↓

View a Ticket Form

get
/api/v2/ticket-forms/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/2'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

Update a Ticket Form

put
/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
Copied Copy 
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'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

Delete a Ticket Form

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/ticket-forms/2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Clone a Ticket Form

clone
/api/v2/ticket-forms/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/2/clone'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

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

get
/api/v2/ticket-forms/[form-id]/fields/[field-id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/1/fields/1'
EXPAND ↓
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"
}
EXPAND ↓

Update A Ticket Form's Field

post
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Delete a Ticket Form's Field

delete
/api/v2/ticket-forms/[form-id]/fields/[field-id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/ticket-forms/2/fields/2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

post
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Create a Note

post
/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 parameter to false.

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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Create a Note With Attachment

Note:
This API request must have its content-type set to multipart/form-data.

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Update a conversation

put
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Delete a conversation

delete
/api/v2/conversations/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/conversations/5'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Reply to Forward

post
/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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

View Account

get
/api/v2/account
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/account'
EXPAND ↓
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"
  }
}
EXPAND ↓

Export Account

post
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
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
{
  "job" : {
    "id" : 432,
    "link": {
      "href" : "dailyplanet.freshdesk.com/api/v2/jobs/432",
      "method" : "GET"
    }
  }
}
EXPAND ↓

View a Job

get
/api/v2/jobs/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/jobs/432'
EXPAND ↓
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,
}
EXPAND ↓

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
email 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

post
/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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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"
  }
}
EXPAND ↓

View a Contact

get
/api/v2/contacts/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/434'
EXPAND ↓
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"
  }
}
EXPAND ↓

List All Contacts

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts'
EXPAND ↓
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
    }
  },
  ...
]
EXPAND ↓

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.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?email=superman@gmail.com'
EXPAND ↓

2. Get the first 20 verified contacts. By default, the contacts will be returned in alphabetical order.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?state=verified&per_page=20'
EXPAND ↓

3. Get a list of contacts updated after a particular timestamp.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?updated_since=2018-01-19T02:00:00Z'
EXPAND ↓

Search Contacts

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts/autocomplete?term=John'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
[
   {
      "id": 33,
      "name": "John Jonz"
   },
   {
      "id": 456,
      "name": "John Steven Jonz"
   }
 ]
EXPAND ↓

Filter ContactsBETA

get
/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.

Format -    "(contact_field:integer OR contact_field:'string') AND contact_field:boolean"

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
email 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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true"'
EXPAND ↓
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"
    },
    ...
    ...
    ...
    ...
  ]
}
EXPAND ↓

Additional Examples

1. Get the list of verified users associated to company 2331.
    "active:true AND company_id:2331"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true%20AND%20company_id:2331"'
EXPAND ↓

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')"

Copied Copy 
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)"'
EXPAND ↓

Update a Contact

put
/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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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"
  }
}
EXPAND ↓

Soft Delete a Contact

delete
/api/v2/contacts/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/contacts/432'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Permanently Delete a Contact

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/contacts/432/hard_delete'
EXPAND ↓
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
EXPAND ↓

Additional Examples

1. Force delete a contact that is not soft deleted already.

Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/contacts/432/hard_delete?force=true'
EXPAND ↓

Make Agent

put
/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
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshdesk.com/api/v2/contacts/432/make_agent'
EXPAND ↓
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
  }
}
EXPAND ↓

Additional Examples

1. Convert a contact to a collaborator (Collaborators Feature Required)

Copied Copy 
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'
EXPAND ↓

Restore a Contact

put
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
Copied Copy 
1
curl -v -u yourapikey:X -X PUT 'https://domain.freshdesk.com/api/v2/contacts/432/restore'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Send Invite to a Contact

put
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
Copied Copy 
1
curl -v -u yourapikey:X -X PUT 'https://domain.freshdesk.com/api/v2/contacts/432/send_invite'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Merge Contacts

post
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)
The following table lists the attributes of contact:
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
Copied Copy 
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'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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.

post
api/v2/contacts/export

Parameters

Attribute Type Description
fieldsMandatory object Fields of the contacts to be exported
The following table lists the fields:
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
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
{
  "id": "d809986de1ed8a1abaeb363ac455e917b356e347"
}
EXPAND ↓

Step 2: The contact export ID can be passed to another endpoint which will return a URL to the exported CSV file.

get
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
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST 'https://domain.freshdesk.com/api/v2/contacts/export/d809986de1ed8a1abaeb363ac455e917b356e347'
EXPAND ↓
Response 
1
2
3
4
5
{
  "id": "d809986de1ed8a1abaeb363ac455e917b356e347",
  "status": "completed",
  "download_url": "download_url"
}
EXPAND ↓

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.

get
api/v2/contacts/imports
Filter by Handle
Status api/v2/contacts/imports?status=[in_progress/completed/cancelled/failed]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/imports'
EXPAND ↓
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"
    }
  }
]
EXPAND ↓
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.

get
api/v2/contacts/imports/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/imports/423678'
EXPAND ↓
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"
}
EXPAND ↓
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.

post
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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓
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.

put
api/v2/contacts/imports/[id]/cancel
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT 'https://domain.freshdesk.com/api/v2/contacts/imports/423678/cancel'
EXPAND ↓
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"
  }
}
EXPAND ↓

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

get
/api/v2/contact_fields

To view all contact field details, use this API.

Sample code | Curl
Copied Copy 
1
2
# All Contact Fields
  curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contact_fields'
EXPAND ↓
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"
    }
]
EXPAND ↓

View a contact field

get
/api/v2/contact_fields/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contact_fields/18'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

Create a contact field

post
/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
Copied Copy 
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'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

Update a contact field

put
/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
Copied Copy 
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'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

Delete a contact field

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/contact_fields/24'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

get
/api/v2/agents/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents/432'
EXPAND ↓
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
}
EXPAND ↓

List All Agents

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents'
EXPAND ↓
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
   },
   ...
]
EXPAND ↓

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.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents?email=sample@freshdesk.com'
EXPAND ↓

2. Get the first 20 fulltime agents. By default, the agents will be returned in alphabetical order.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents?state=fulltime&per_page=20'
EXPAND ↓

Create an Agent

post
/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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

Agent creation with focus_mode disabled

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

Additional Examples

1. Create a Collaborator Agent (Collaborators Feature Required)

Copied Copy 
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'
EXPAND ↓

Update an Agent

put
/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)
email 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
Copied Copy 
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'
EXPAND ↓
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"
  }
}
EXPAND ↓

Delete an Agent

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/agents/2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Currently Authenticated Agent

get
/api/v2/agents/me
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents/me'
EXPAND ↓
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"
  }
}
EXPAND ↓

Create Multiple Agents

post
/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
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
4
{ 
"job_id": 100,
 "href": "https://domain.freshdesk.com/api/v2/jobs/100" 
}
EXPAND ↓

Search Agents

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/agents/autocomplete?term=John'
EXPAND ↓
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
   }
 ]
EXPAND ↓

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"
Field Name Type Description
priority array of number List of ticket priorities
ticket_type array of string List of ticket types
product_id array of number List of product ids
source array of numbers List of source ids
group_id array of numbers List of group ids
custom_fields dictionary Key value pairs containing the names and values of custom fields. Dependent fields are nested objects with key value pairs in them.
For resource: "contact"
Field Name Type Description
language array of string List of language_codes.
For resource: "company"
Field Name Type Description
domains array of string List of domains
name array of string List of company names

View a Skill

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET  'https://domain.freshdesk.com/api/v2/admin/skills/1'
EXPAND ↓
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"
        }
      }
    }
  ]
}
EXPAND ↓

List all Skills

get
/api/v2/admin/skills/

Note:
Incase if you are using old omni route, please use the end point: /api/v2/skills

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/skills'
EXPAND ↓
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
        ]
      }
    ]
  }
]
EXPAND ↓

Create a Skill

post
/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"
Field Name Type Description
priority array of number List of ticket priorities
ticket_type array of string List of ticket types
product_id array of number List of product ids
source array of numbers List of source ids
group_id array of numbers List of group ids
custom_fields dictionary Key value pairs containing the names and values of custom fields. Dependent fields are nested objects with key value pairs in them.
For resource: "contact"
Field Name Type Description
language array of string List of language_codes.
For resource: "company"
Field Name Type Description
domains array of string List of domains
name array of string List of company names
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

Delete a Skill

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE  'https://domain.freshdesk.com/api/v2/admin/skills/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Update a Skill

update
/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"
Field Name Type Description
priority array of number List of ticket priorities
ticket_type array of string List of ticket types
product_id array of number List of product ids
source array of numbers List of source ids
group_id array of numbers List of group ids
custom_fields dictionary Key value pairs containing the names and values of custom fields. Dependent fields are nested objects with key value pairs in them.
For resource: "contact"
Field Name Type Description
language array of string List of language_codes.
For resource: "company"
Field Name Type Description
domains array of string List of domains
name array of string List of company names
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

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

get
/api/v2/roles/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/roles/1'
EXPAND ↓
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"
}
EXPAND ↓

List All Roles

get
/api/v2/roles
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/roles'
EXPAND ↓
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"
  }
]
EXPAND ↓

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

post
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

View a Group

get
/api/v2/groups/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET  'https://domain.freshdesk.com/api/v2/groups/1'
EXPAND ↓
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"
  }
EXPAND ↓

List All Groups

get
/api/v2/groups
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/groups'
EXPAND ↓
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"
  }
]
EXPAND ↓

Update a Group

put
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Delete a Group

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE  'https://domain.freshdesk.com/api/v2/groups/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

post
/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
Copied Copy 
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'
EXPAND ↓
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
                }
            }
        ]
    }
}
EXPAND ↓

View a Group

get
/api/v2/admin/groups/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET  'https://domain.freshdesk.com/api/v2/admin/groups/1'
EXPAND ↓
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
            }
        }]
    }
}
EXPAND ↓

List All Groups

get
/api/v2/admin/groups
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/groups'
EXPAND ↓
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
                }
            }]
        }
    }
]
EXPAND ↓

Update a Group

put
/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
Copied Copy 
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'
EXPAND ↓
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"
            }
        ]
    }
}
EXPAND ↓

Delete a Group

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE  'https://domain.freshdesk.com/api/v2/admin/groups/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

List All Agents in a Group

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/groups/[:id]/agents'
EXPAND ↓
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
    }
]
EXPAND ↓

Add or Remove Agents in a Group

patch
/api/v2/admin/groups/[id]/agents
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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
                }
            }
        ]
    }
}
EXPAND ↓

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

post
/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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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"
    },
}
EXPAND ↓

View a Company

get
/api/v2/companies/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/companies/8'
EXPAND ↓
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
}
EXPAND ↓

List All Companies

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/companies'
EXPAND ↓
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"
   }
]
EXPAND ↓

Additional Examples

1. Get a list of companies updated after a particular timestamp.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/companies?updated_since=2024-02-28T00:00:00Z'
EXPAND ↓

Search Companies

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/companies/autocomplete?name=Acme'
EXPAND ↓
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."
    }
  ]
}
EXPAND ↓

Filter CompaniesBETA

get
/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.

Format -    "(company_field:integer OR company_field:'string') AND company_field:boolean"

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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/companies?query="domain:'lexcorp.org'"'
EXPAND ↓
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"
    },
    ...
    ...
    ...
    ...
  ]
}
EXPAND ↓

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'"

Copied Copy 
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"'
EXPAND ↓

2. Get the list of private companies associated with sector 8 (sector and private are custom fields).
    "sector:8 AND private:true"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/companies?query="sector:8%20AND%20private:true"'
EXPAND ↓

Update a Company

put
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

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
Copied Copy 
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'
EXPAND ↓
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"
  }
}
EXPAND ↓

Delete a Company

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/companies/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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.

post
api/v2/companies/export

Parameters

Attribute Type Description
fieldsMandatory object Fields of the companies to be exported
The following table lists the fields:
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
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
{
  "id": "d809986de1ed8a1abaeb363ac455e917b356e347"
}
EXPAND ↓

Step 2: The company export ID can be passed to another endpoint which will return a URL to the exported CSV file.

get
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
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST 'https://domain.freshdesk.com/api/v2/companies/export/d809986de1ed8a1abaeb363ac455e917b356e347'
EXPAND ↓
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"
}
EXPAND ↓

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.

get
api/v2/companies/imports
Filter by Handle
Status api/v2/companies/imports?status=[in_progress/completed/cancelled/failed]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/companies/imports'
EXPAND ↓
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"
    }
  }
]
EXPAND ↓
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.

get
api/v2/companies/imports/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/companies/imports/423678'
EXPAND ↓
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"
}
EXPAND ↓
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.

post
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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓
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.

put
api/v2/companies/imports/[id]/cancel
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT 'https://domain.freshdesk.com/api/v2/companies/imports/423678/cancel'
EXPAND ↓
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"
  }
}
EXPAND ↓

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

get
/api/v2/company_fields

To view all company field details, use this API.

Sample code | Curl
Copied Copy 
1
2
# All Company Fields
  curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/company_fields'
EXPAND ↓
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"
        ]
    }
]
EXPAND ↓

View a company field

get
/api/v2/company_fields/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/company_fields/8'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

Create a company field

post
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
Copied Copy 
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'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

Update a company field

put
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
Copied Copy 
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'
EXPAND ↓
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
        }
    ]
}
EXPAND ↓

Delete a company field

delete
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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/company_fields/9'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

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

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET "https://domain.freshdesk.com/api/v2/custom_objects/schemas"
EXPAND ↓
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": []
        }      
      ]
    }
  ]
}
EXPAND ↓

Retrieve A Specific Custom Object

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET "https://domain.freshdesk.com/api/v2/custom_objects/schemas/30"
EXPAND ↓
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": []
        }  
    ]
    }
EXPAND ↓

Create A Record

post
/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
Copied Copy 
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 } }'
EXPAND ↓
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
    }
  }
EXPAND ↓

Retrieve A Record

get
/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
Copied Copy 
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"
EXPAND ↓
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
        }
      }
EXPAND ↓

Update A Record

put
/api/v2/custom_objects/schemas/schema-id/records/{record-id}
Sample code | Curl
Copied Copy 
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 } }'
EXPAND ↓
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 
  }
}
EXPAND ↓

Delete A Record

delete
/api/v2/custom_objects/schemas/schema-id/records/{record-id}
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
Response 
1
204   No Content
EXPAND ↓

Retrieve All Records

get
/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
Copied Copy 
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"
EXPAND ↓
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="
        }
    }
}
EXPAND ↓

Retrieve The Count Of Records

get
/api/v2/custom_objects/schemas/schema_id/records/count
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
Response 
1
2
3
{
    "count": 12
}
EXPAND ↓

Filter Records Of A Custom Object

get
/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
Copied Copy 
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"
EXPAND ↓
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="
        }
    }
}
EXPAND ↓

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 '' in this custom object. Please use a different name." } ] }
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

post
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

View a Canned Response

get
/api/v2/canned_responses/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X  -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/canned_responses/82000005490’
EXPAND ↓
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"
 }
EXPAND ↓

Update a canned response

put
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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Bulk Create Canned Responses

post
/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
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
4
{
  "job_id": 100,
  "href": "https://domain.freshdesk.com/api/v2/jobs/100"
}
EXPAND ↓

Create Folder

post
/api/v2/canned_response_folder
Attribute Type Description
nameMandatory string Name of the folder
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
4
{
"Id":82000044383,
"name":"Folder"
}
EXPAND ↓

Update Folder

put
/api/v2/canned_response_folder/[id]
Attribute Type Description
nameMandatory string Name of the folder
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
Response 
1
2
3
4
{
"Id":82000044383,
"name":"Updated Folder"
}
EXPAND ↓

List All Folders

get
/canned_response_folders

To view all the canned response folders.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/canned_response_folders'
EXPAND ↓
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"
   }
]
EXPAND ↓

List All Canned Responses in a Folder

get
/canned_response_folders/[id]

To view all canned responses in a folder.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/canned_response_folders/1'
EXPAND ↓
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"
}
EXPAND ↓

Get details of Canned Responses in a Folder

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/canned_response_folders/1/responses'
EXPAND ↓
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"
   }
]
EXPAND ↓

Discussions

Enable your customers to help each other by enabling them to communicate with each other to ask questions, share ideas, and learn from each other. You can also gather critical feedback on what your customers like and dislike, what they'd like you to add and what they'd like you to change from discussion forums. Furthermore, if a critical issue or idea is raised in the community, you can convert it into a ticket and get your team to work on it right away.

Categories

In addition to helping you organize your community discussions better, Categories are useful when you are providing support across multiple products. You can choose to only show certain forum categories pertaining to a specific product in that product's portal.

Attribute Type Description
description string Description of the forum category
id number Unique ID of the forum category
name string Name of the forum category
created_at datetime Forum Category creation timestamp
updated_at datetime Forum Category updated timestamp

Create a Forum Category

post
/api/v2/discussions/categories

Parameters

Attribute Type Description
description string Description of the forum category
nameMandatoryUnique string Name of the forum category
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

View a Forum Category

get
/api/v2/discussions/categories/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories/2'
EXPAND ↓
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"
}
EXPAND ↓

List All Forum Categories

get
/api/v2/discussions/categories
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories'
EXPAND ↓
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"
  }
]
EXPAND ↓

List All Forums in a Category

get
/api/v2/discussions/categories/[id]/forums
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/categories/2/forums'
EXPAND ↓
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
  }
]
EXPAND ↓

Update a Forum Category

put
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Delete a Forum Category

delete
/api/v2/discussions/categories/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/categories/3'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Forums

Forums are collections of similar topics, so customers know exactly where to go to get a specific answer from the community. For example, you can have a specific forum to collect Feature Requests from your customers, another forum for the community to share tips and tricks and a third forum where customers can talk about the problems they are facing and their solutions.

Attribute Type Description
company_ids Array of numbers If the forum_visibility property is set to 4, the forum is only visible to users belonging to certain companies. This property is an array of those company IDs.
description string Description of the forum
forum_category_id number ID of the category to which this forum belongs
forum_type number Denotes the type of forum (Supported types can be seen in the Forum properties table below)
forum_visibility number Denotes the visibility level of the forum (See the Forum Visibility table below for supported levels)
id number Unique ID of the forum
name string Name of the forum
position number Controls the order in which the forums are displayed in the web page
posts_count number The total number of posts in the forum
topics_count number The total number of topics in the forum

Forum Properties

Forum Type Value
How To's 1
Ideas 2
Problems 3
Announcements 4
Forum Visibility Value
Everyone 1
Logged in users only 2
Agents only 3
Users in specific companies only 4

Create A Forum

post
/api/v2/discussions/categories/[category_id]/forums

Parameters

Attribute Type Description
company_ids Array of numbers If the forum_visibility property is set to 4, the forum is only visible to users belonging to certain companies. This property is an array of those company IDs.
description string Description of the forum
forum_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
Copied Copy 
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'
EXPAND ↓
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
  ]
}
EXPAND ↓

View A Forum

get
/api/v2/discussions/forums/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/2'
EXPAND ↓
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
}
EXPAND ↓

List All Topics in a Forum

get
/api/v2/discussions/forums/[id]/topics
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/5/topics'
EXPAND ↓
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"
  }
]
EXPAND ↓

Update a Forum

put
/api/v2/discussions/forums/[id]

Note:
1. The forum_type attribute cannot be updated if the forum already has topics.
2. The company_ids attribute cannot be updated unless the forum_visibility is set to 4.

Parameters

Attribute Type Description
company_ids Array of numbers If the forum_visibility property is set to 4, the forum is only visible to users belonging to certain companies. This property is an array of those company IDs.
description string Description of the forum
forum_category_id number ID of the category to which this forum belongs
forum_type number Denotes the type of forum (Supported types can be referred in the Forum type table below)
forum_visibility number Denotes the visibility level of the forum (Supported types can be referred in the Forum visibility table below)
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
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

Delete a Forum

delete
/api/v2/discussions/forums/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/forums/2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Monitor Forum

post
/api/v2/discussions/forums/[id]/follow

Parameters

Attribute Type Description
user_id Integer ID of the user who wished to follow the forum
If the user_id is not mentioned, the user whose API Key was used to make the API call will be considered the recipient.
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Unmonitor Forum

delete
/api/v2/discussions/forums/[forum_id]/follow?user_id=[user_id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/forums/1/follow?user_id=2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Monitoring Status For Forum

get
/api/v2/discussions/forums/[id]/follow?user_id=[id]

This API allows you to check if a forum is being monitored by a specific user. A HTTP status code of 204 indicates that it is being monitored while a status code of 404 indicates that it is not being monitored.

Note:
1. If the user_id is not mentioned, we will assume that the user is the one whose credentials (identified by the API key) are used to make the API call
2. Only administrators can check if a forum is being monitored by someone else

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/forums/14581/follow?user_id=2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Topics

Topics or individual posts in your forums are the actual discussion threads.

Attribute Type Description
forum_id number ID of the Forum in which this topic is present
hits number Number of views of that topic
id number Unique ID of the topic
locked boolean Set to true if the topic is locked which means that no more posts can be added to the topic
merged_topic_id number ID of the topic to which it is merged into
message string Message body of the topic
posts_count number Number of posts in that topic
replied_at datetime Timestamp of the latest comment made in the topic
replied_by datetime ID of the user who made the latest comment in that topic
stamp_type number Stamp type given to the topic
sticky boolean Set to true if the topic should stay on top of the forum for additional visibility
title string Title of the topic
user_id number ID of the user who created the topic
user_votes number Number of votes in the topic
created_at datetime Forum Topic creation timestamp
updated_at datetime Forum Topic updated timestamp

Topic Properties

Forum Type of Topic Valid Topic Stamp
Question 6 - Answered, 7 - Unanswered
Idea nil, 1 - Planned, 2 - Implemented, 3 - Not Taken, 4 - In Progress, 5 - Deferred
Problem 8 - Solved, 9 - Unsolved
Announcement nil

Create a Topic

post
/api/v2/discussions/forums/[forum_id]/topics

Note:
1. message given in the request will be added as the first comment/post to the topic.
2. sticky, locked can be part of request only if you have privilege to update a topic.

Parameters

Attribute Type Description
locked boolean Set to true if the topic is locked which means that no more posts can be added to the topic
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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

View a Topic

get
/api/v2/discussions/topics/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/3'
EXPAND ↓
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"
}
EXPAND ↓

List All Comments in a Topic

get
/api/v2/discussions/topics/[id]/comments

To view all conversations/comments/comments in a specific topic, use this API

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/1/comments'
EXPAND ↓
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"
  }
]
EXPAND ↓

Update a Topic

put
/api/v2/discussions/topics/[id]

Note:
1. If message is part of the request, then the first comment/post of the topic will be updated.
2. The forum_id can be only be updated if you have privilege to manage forums.

Parameters

Attribute Type Description
forum_id number ID of the Forum in which this topic is present
locked boolean Set to true if the topic is locked which means that no more posts can be added to the topic
message string Message body of the topic
stamp_type number stamp type given to the topic
sticky boolean Set to true if the topic should stay on top of the forum for additional visibility
title string Title of the topic

Topic Properties

Forum Type of Topic Valid Topic Stamp
Question 6 - Answered, 7 - Unanswered
Idea nil, 1 - Planned, 2 - Implemented, 3 - Not Taken, 4 - In Progress, 5 - Deferred
Problem 8 - Solved, 9 - Unsolved
Announcement nil
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Delete a Topic

delete
/api/v2/discussions/topics/[id]

Note:
Deleted topics cannot be brought back to life.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/discussions/topics/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Monitor Topic

post
/api/v2/discussions/topics/[id]/follow

Parameters

Attribute Type Description
user_id Integer ID of the user who wishes to follow the forum
If the user_id is not mentioned, the user whose API Key was used to make the API call will be consider the recipient.
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '' 'https://domain.freshdesk.com/api/v2/discussions/topics/1/follow'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Unmonitor Topic

delete
/api/v2/discussions/topics/[topic_id]/follow?user_id=[user_id]
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Monitoring Status For Topic

get
/api/v2/discussions/topics/[id]/follow?user_id=[id]

This API allows you to check if a topic is being monitored by a specific user. A HTTP status code of 204 indicates that it is being monitored while a status code of 404 indicates that it is not being monitored.

Note:
1. If the user_id is not mentioned, we will assume that the user is the one whose credentials (identified by the API key) were used to make the API call
2. Only administrators can check if a topic is being monitored by someone else

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/14581/follow?user_id=2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

List All Monitored Topics

get
/api/v2/discussions/topics/followed_by?user_id=[id]

This API allows you to view the list of topics that are being monitored by a specific user.

Note:
1. If the user_id is not mentioned, we will assume that the user is the one whose credentials (identified by the API key) were used to make the API call.
2. Only administrators can view the list of topics that are being monitored by someone else.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/followed_by?user_id=12'
EXPAND ↓
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"
  }
]
EXPAND ↓

List All Participated Topics

get
/api/v2/discussions/topics/participated_by?user_id=[id]

This API allows you to view the list of topics participated by a specific user, either creating or commenting in the topic.

Note:
1. If the user_id is not mentioned, we will assume that the user is the one whose credentials (identified by the API key) were used to make the API call.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/discussions/topics/participated_by?user_id=27'
EXPAND ↓
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"
  }
]
EXPAND ↓

Comments

Attribute Type Description
answer boolean Indicates if the comment is marked as the answer (for forum topics of type "Question")
body string Content of the comment in HTML
forum_id number ID of the forum in which the comment was posted
id number Unique ID of the comment or comment
published boolean Indicates if the comment is being published (allowed by moderators)
spam boolean Indicates if the comment is marked as spam
topic_id number ID of the topic in which the comment was posted
trash boolean Indicates if the Comment is marked as deleted
user_id number ID of the user who posted the comment
created_at datetime Comment creation timestamp
updated_at datetime Comment updated timestamp

Create A Comment

post
/api/v2/discussions/topics/[topic_id]/comments

Parameters

Attribute Type Description
bodyMandatory string Content of the comment in HTML
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Update A Comment

put
/api/v2/discussions/comments/[id]

Parameters

Attribute Type Description
answer boolean Indicates if the comment is marked as the answer (for forum topics of type "Question")
body string Content of the comment in HTML
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Delete A Comment

delete
/api/v2/discussions/comments/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE  'https://domain.freshdesk.com/api/v2/discussions/comments/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Solutions

An effective knowledge base solves two of the biggest help desk problems. First, since all agents have a common place to pool in and share solutions, you can be sure that customer responses are consistent throughout. Second, since customers can access and help themselves to solutions, they feel more confident about your business. And all the while, your support load reduces.

For better clarity, the Freshdesk knowledge base is categorized into a three level hierarchy - top level Categories that hold related Folders and Solution Articles inside each folder.

Categories

Categories broadly classify your solutions page into several sections. For example, you could place Shipping, Payments and Delivery related information under the Order Fulfilment category. Another interesting application of the top level category is when you are providing support across multiple brands or products.

Attribute Type Description
id number Unique ID of the solution category
name string Name of the solution category
description string Description of the solution category
visible_in_portals array of numbers List of portal IDs where this category is visible
created_at datetime Solution Category creation timestamp
updated_at datetime Solution Category updated timestamp

Create a Solution Category

post
/api/v2/solutions/categories

Parameters

Attribute Type Description
description string Description of the solution category
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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Create a translated solution category

post
/api/v2/solutions/categories/[id]/[language_code]

Note:
1. Multilingual Feature must be enabled for the account
2. Supported languages have to be configured from Admin > General Settings > Helpdesk
3. Configured languages can be retrieved from Helpdesk Settings

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Update a Solution Category

put
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Update a translated solution category

put
/api/v2/solutions/categories/[id]/[language_code]

Note:
1. Multilingual Feature must be enabled for the account
2. Supported languages have to be configured from Admin > General Settings > Helpdesk
3. Configured languages can be retrieved from Helpdesk Settings

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

View a Solution Category

get
/api/v2/solutions/categories/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3'
EXPAND ↓
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"
}
EXPAND ↓

View a translated solution category

get
/api/v2/solutions/categories/[id]/[language_code]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/es'
EXPAND ↓
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"
}
EXPAND ↓

List all Solution Categories

get
/api/v2/solutions/categories
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories'
EXPAND ↓
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"
  }
]
EXPAND ↓

View all translated solution categories

get
/api/v2/solutions/categories/[language_code]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/es'
EXPAND ↓
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"
  }
]
EXPAND ↓

Delete a Solution Category

delete
/api/v2/solutions/categories/[id]

Note:
When deleted, all translated versions will be deleted too.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/categories/3'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Folders

Related Solutions Articles and/or Folders are organized into Folders. Folders make it convenient for users to read similar articles or navigate to other possible solutions to their problem. For example, you can club solution articles related to tracking codes and postal services under the "Shipping" folder and “Shipping Folder” under “Orders Folder”.

Parameters

Attribute Type Description
id number Unique ID of the solution folder
name string Name of the solution folder
description string Description of the solution folder
parent_folder_id number ID of the parent folder
hierarchy array of objects Parent category and folders in which the folder is placed
articles_count number Number of articles present inside a folder
sub_folders_count number Number of folders present inside a folder
visibility number Accessibility of this folder. Please refer to Folder Properties table.
company_ids array of numbers IDs of the companies to whom this solution folder is visible
contact_segment_ids array of numbers IDs of the contact segments to whom this solution folder is visible
company_segment_ids array of numbers IDs of the company segments to whom this solution folder is visible
created_at datetime Solution Folder creation timestamp
updated_at datetime Solution Folder updated timestamp

Folder Visibility Properties

Visibility Value
All Users 1
Logged In Users 2
Agents 3
Selected Companies 4
Bots 5
Selected Contact Segments 6
Selected Company Segments 7

Note:
Attributes like parent_folder_id, sub_folders_count and hierarchy are specific to the 'Flexible Hierarchy' feature.

Create a Solution Folder

post
/api/v2/solutions/categories/[id]/folders

Parameters

Attribute Type Description
description string Description of the solution folder
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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Create a translated solution folder

post
/api/v2/solutions/folders/[id]/[language_code]

Note:
1. Multilingual Feature must be enabled for the account
2. Supported languages have to be configured from Admin > General Settings > Helpdesk
3. Configured languages can be retrieved from Helpdesk Settings

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Update a Solution Folder

put
/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
Copied Copy 
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'
EXPAND ↓
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]
}
EXPAND ↓

Update a translated solution folder

put
/api/v2/solutions/folders/[id]/[language_code]

Note:
1. Multilingual Feature must be enabled for the account
2. Supported languages have to be configured from Admin > General Settings > Helpdesk
3. Configured languages can be retrieved from Helpdesk Settings

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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]
}
EXPAND ↓

View a Solution Folder

get
/api/v2/solutions/folders/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4'
EXPAND ↓
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"
}
EXPAND ↓

View a translated solution folder

get
/api/v2/solutions/folders/[id]/[language_code]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/es'
EXPAND ↓
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"
}
EXPAND ↓

List all Solution Folders in a Category

get
/api/v2/solutions/categories/[category_id]/folders
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/folders'
EXPAND ↓
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]
  }
]
EXPAND ↓

View all translated solution folders in a category

get
/api/v2/solutions/categories/[category_id]/folders/[language_code]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/categories/3/folders/es'
EXPAND ↓
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]
  }
]
EXPAND ↓

List all Folders in a Folder

get
/api/v2/solutions/folders/[folder_id]/subfolders
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/2/subfolders'
EXPAND ↓
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]
  }
]
EXPAND ↓

List all translated folders in a folder

get
/api/v2/solutions/folders/[folder_id]/subfolders/[language_code]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/2/subfolders/es'
EXPAND ↓
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]
  }
]
EXPAND ↓

Delete a Solution Folder

delete
/api/v2/solutions/folders/[id]

Note:
When deleted, all translated versions will be deleted too.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/folders/3'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Articles

Solution Articles or knowledge base posts promote self-help in your support portal. These should ideally cover all aspects of your product or service like "how-to" instructions and FAQs. For example, in an e-commerce store, your knowledge base articles would include payment instructions, shipping information, and product return policies.

Attribute Type Description
id number Unique ID of the solution article
agent_id number ID of the agent who created the solution article
category_id number ID of the category to which the solution article belongs
description string Description of the solution article
description_text string Description of the solution article in plain text
folder_id number ID of the folder to which the solution article belongs
hierarchy array of objects Parent category and folders in which the article is placed
hits number Number of views for the solution article
status number Status of the solution article
seo_data dictionary Meta data for search engine optimization. Allows meta_title, meta_description and meta_keywords
tags array of strings Tags that have been associated with the solution article
thumbs_down number Number of down votes for the solution article
thumbs_up number Number of upvotes for the solution article
title string Title of the solution article
created_at datetime Solution Article creation timestamp
updated_at datetime Solution Article updated timestamp

Create a Solution Article

post
/api/v2/solutions/folders/[id]/articles

Parameters

Attribute Type Description
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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Create a translated solution article

post
/api/v2/solutions/articles/[id]/[language_code]

Note:
1. Multilingual Feature must be enabled for the account
2. Supported languages have to be configured from Admin > General Settings > Helpdesk
3. Configured languages can be retrieved from Helpdesk Settings

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Update a Solution Article

put
/api/v2/solutions/articles/[id]

Parameters

Attribute Type Description
agent_id number ID of the agent who created the solution article
description string Description of the solution article
status number Status of the solution article. (1 - draft, 2 - published)
When status=1 is passed without any other parameters, the article will be unpublished
seo_data dictionary Meta data for search engine optimization. Allows meta_title, meta_description and meta_keywords
tags array of strings Tags that have been associated with the solution article
title string Title of the solution article
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Update a translated solution article

put
/api/v2/solutions/articles/[id]/[language_code]

Note:
1. Multilingual Feature must be enabled for the account
2. Supported languages have to be configured from Admin > General Settings > Helpdesk
3. Configured languages can be retrieved from Helpdesk Settings

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

View a Solution Article

get
/api/v2/solutions/articles/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/articles/2'
EXPAND ↓
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"
}
EXPAND ↓

View a translated solution article

get
/api/v2/solutions/articles/[id]/[language_code]

Note:
When language_code is passed, metrics such as "thumbs_up", "thumbs_down" and "hits" will be specific to the language. Otherwise, the response will contain the consolidated metrics data.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/articles/2/es'
EXPAND ↓
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"
}
EXPAND ↓

List all Solution Articles in a Folder

get
/api/v2/solutions/folders/[id]/articles
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/articles'
EXPAND ↓
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"
  }
]
EXPAND ↓

View all translated solution articles in a folder

get
/api/v2/solutions/folders/[id]/articles/[language_code]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/articles/es'
EXPAND ↓
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"
  }
]
EXPAND ↓

Delete a Solution Article

delete
/api/v2/solutions/articles/[id]

Note:
When deleted, all translated versions will be deleted too.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/articles/2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Search solution articles

get
/api/v2/search/solutions?term=[keyword]

Search the articles in your Freshdesk account using a keyword.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/solutions?term=sample'
EXPAND ↓
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"
  }
]
EXPAND ↓

Surveys

The Customer Satisfaction Survey is a built-in feature in Freshdesk that can be used to directly measure helpdesk efficiency and customer satisfaction with every support ticket. Every time you resolve a ticket on your helpdesk, you could choose to send out the survey to your customers asking them how their experience was during the issue.

Attribute Type Description
id number ID of the survey
title string Title of the Survey
questions string Questions associated with the Survey
created_at datetime Survey creation timestamp
updated_at datetime Survey updated timestamp

Survey Question Attributes

Attribute Type Description
id string ID of the survey question. The default question for any survey will always have the ID as "default_question".
label string Title of the survey question
accepted_ratings array of string Accepted rating values for each specific question

List all Surveys

get
/api/v2/surveys

Use filters to view only specific surveys (those which match the criteria that you choose).

Note:
When using filters, the query string must be URL encoded

Filter by Handle
state /api/v2/surveys?state=active
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys'
EXPAND ↓
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"
      }
   },
   ...
]
EXPAND ↓

Additional Examples

1. Get a list of surveys filtered by the state.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys?state=active'
EXPAND ↓

Satisfaction Ratings

Every response to a customer satisfaction survey is recorded as a satisfaction rating. These ratings are used to generate a customer satisfaction report that you can use to see which of your agents have received the most number of happy ratings, and who hasn't been very helpful to your customers. This can help you in defining metrics in your support process more clearly and in training future support people based on results from the past.

Attribute Type Description
id number ID of the Satisfaction Rating
survey_id number Survey ID of the satisfaction rating
user_id number Requester ID of the ticket for which the satisfaction rating has been created or the ID of the user who has created the satisfaction rating.
agent_id number Responder ID of the ticket for which the satisfaction rating has been created.
group_id number Group ID associated with the ticket for which the satisfaction rating has been created.
ticket_id number ID of the ticket for which the satisfaction rating has been created.
feedback string Feedback given while creating the satisfaction rating.
questions string Survey Questions associated with the Survey
ratings key/value pair Key/Value pair of the question ID and the rating for that question. "default_question" will contain the default rating for the survey for both custom and classic surveys. Additional question_id and ratings for the questions will be present only for the new surveys.
created_at datetime Satisfaction Rating creation timestamp
updated_at datetime Satisfaction Rating updated timestamp

Create a Satisfaction Rating

post
/api/v2/tickets/[ticket_id]/satisfaction_ratings
Attribute Type Description
feedback string Feedback for the satisfaction rating
ratings key/value pair Key/Value pair of the question ID and the rating for that question. "default_question" will contain the default rating for the survey in case of both custom and classic survey.

New Survey Ratings

Rating Value Description
103 Extremely Happy
102 Very Happy
101 Happy
100 Neutral
-101 Unhappy
-102 Very Unhappy
-103 Extremely Unhappy

Classic Survey Ratings

Rating Value Description
1 Happy
2 Neutral
3 Unhappy
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

View all Satisfaction Ratings

get
/api/v2/surveys/satisfaction_ratings

Use filters to view only specific satisfaction ratings (those which match the criteria that you choose). The filters listed in the table below can also be combined.

Note:
When using filters, the query string must be URL encoded

Filter by Handle
created_since Example:
/api/v2/surveys/satisfaction_ratings?created_since=2015-01-19T02:00:00Z
user_id Example:
/api/v2/surveys/satisfaction_ratings?user_id=2
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys/satisfaction_ratings'
EXPAND ↓
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"
    }
]
EXPAND ↓

Additional Examples

1. Get a list of satisfaction ratings filtered by the user_id.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/surveys/satisfaction_ratings?user_id=2'
EXPAND ↓

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:

  1. Login to your account as an Administrator.
  2. Go to Admin > Field Service Management under General Settings.
  3. Click on Enable to enable Field Service Management for your account.
  4. You will be redirected to the landing page for FSM; from here, you can add field technicians, create service groups and access reports. For more information, view these articles.

Service Task

A service task is a ticket assigned to a field technician. It outlines an upcoming job and describes the work to be done along with information that the field technician would need like location, site contact details, and appointment date and time.

Create a Service Task

post
/api/v2/tickets

To create a service task, use the Create A Ticket API.

Note:
  1. It is mandatory that the value of ‘Type’ parameter is ‘Service Task’.
  2. A maximum of 10 service tasks can be created for a parent ticket.
  3. 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
Copied Copy 
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'
EXPAND ↓
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
  ]
}
EXPAND ↓

View a Service Task

get
/api/v2/tickets/[id]

To view a service task, use the View a Ticket API.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/125'
EXPAND ↓
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
}
EXPAND ↓

Update a Service Task

put
/api/v2/tickets/[id]

To update a service task, use the Update a Ticket API.

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
}
EXPAND ↓

Delete a Service Task

delete
/api/v2/tickets/[id]

To delete a service task, use the Delete A Ticket API.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/125'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Service Group

Create a Service Group

post
/api/v2/groups

To create a service group, use the Create A Group API.

Note:
1. It is mandatory that the value of 'group_type' parameter is ‘field_agent_group’.
2. The 'auto_ticket_assign' parameter is not applicable to service group creation

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

View a Service Group

get
/api/v2/groups/[id]

To view a service group, use the View A Group API.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET  'https://domain.freshdesk.com/api/v2/groups/7861'
EXPAND ↓
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
  ]
}
EXPAND ↓

Update a Service Group

put
/api/v2/groups/[id]

To update a service group, use the Update A Group API.

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Delete a Service Group

delete
/api/v2/groups/[id]

To delete a service group, use the Delete A Group API.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE  'https://domain.freshdesk.com/api/v2/groups/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Field Technicians

An existing contact can be converted to a field technician. To convert an agent to a field technician, first delete the agent; this converts them into a contact. Then, use the Make Field Technician API to convert the contact to a field technician

Make Field Technician

put
/api/v2/contacts/[id]/make_agent

To make a contact a field technician, use the Make Agent API.

Note:
1. Role associated to a field technician can only be of 'field technician role'.
2. A field technician cannot be an occasional agent.
3. Type needs to be field_agent.
4. A field technician can only be assigned ‘Group access (2)’ or ‘Restricted access (3)’ for the ticket_scope parameter. Default is 'Restricted access (3)'
5. There should be enough 'field technician licenses' in order to convert a contact into field technician. See how licenses can be purchased here.

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
    }
}
EXPAND ↓

Time Entries

The time tracking feature in Freshdesk lets you track the time spent by each agent on resolving tickets and thereby enables you to gain visibility on the helpdesk's overall performance. Freshdesk lets agents track the time they spend on a ticket with automatic start and stop timers. Agents can also manually log the time they have spent, and detail their activities during this period by adding comments to the time entries.

Attribute Type Description
agent_id number The ID of the agent to whom this time-entry is associated
billable boolean Set to true if the time entry is billable
id number Unique ID of the time entry
executed_at datetime Time at which this time-entry was added/created
note string Description of the time entry
start_time datetime The time at which the time-entry is added or the time of the last invoked "start-timer" action using a toggle
ticket_id number The ID of the ticket to which this time entry is associated
time_spent string The duration in hh:mm format
timer_running boolean Set to 'true' if the timer is currently running
created_at datetime Time Entry creation timestamp
updated_at datetime Time Entry updated timestamp

Create a Time Entry

post
/api/v2/tickets/[ticket_id]/time_entries

Note:
1. If the time_spent is not specified and the timer-running attribute is not specified, then the timer-running attribute will automatically be set to 'true'
2. If the start_time is specified and the timer-running attribute is not specified, then the timer-running attribute will automatically be set to 'true'
3. The start_time cannot be greater than the current time
4. The start_time cannot be given in the API request if the timer_running attribute is set to 'false'

Parameters

Attribute Type Description
agent_id number The agent to whom this time-entry is associated. One agent can have only one timer running. Everything else will be stopped if new timer is on for an agent
billable boolean Set as true if the entry is billable. Default value is true
executed_at datetime Time at which this time-entry id added/created
note string Description on this time-entry
start_time datetime The time at which the time-entry is added or the time of the last invoked "start-timer" action using a toggle
time_spent string The number of hours (in hh:mm format). Used to set the total time_spent
timer_running boolean Indicates if the timer is running
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

List All Time Entries

get
/api/v2/time_entries

Use filters to view only specific time entries (those which match the criteria that you choose). The filters listed in the table below can also be combined.

Filter by Handle
Company ID /api/v2/time_entries?company_id=[value]
Agent ID /api/v2/time_entries?agent_id=[value]
executed_after /api/v2/time_entries?executed_after=[value]
executed_before /api/v2/time_entries?executed_before=[value]
billable /api/v2/time_entries?billable=[true/false]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/time_entries'
EXPAND ↓
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"
  }
]
EXPAND ↓

Additional Examples

1. Get the list of billable time_entries

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/time_entries?billable=true'
EXPAND ↓

2. Get the list of time_entries executed before 2016-05-12 13:00:00

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/time_entries?executed_before=2016-05-12T13:00:00Z'
EXPAND ↓

Update a Time Entry

put
/api/v2/time_entries/[id]

Note:
1. The start_time cannot be updated if the timer is already running
2. The start_time cannot be be updated unless the timer_running attribute is updated from 'true' to 'false'
3. The start_time cannot be greater than the current time
4. The timer_running attribute cannot be set to the same value as before
5. The agent_id cannot be updated if the timer is already running

Parameters

Attribute Type Description
agent_id number The agent to whom this time-entry is associated. One agent can have only one timer running. Everything else will be stopped if new timer is on for an agent
billable boolean Set as true if the entry is billable. Default value is true
executed_at datetime Time at which this time-entry id added/created
note string Description on this time-entry
start_time datetime The time at which the time-entry is added or the time of the last invoked "start-timer" action using a toggle
time_spent string The number of hours (in hh:mm format). Used to set the total time_spent
timer_running boolean Indicates if the timer is running
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Start/Stop Timer

put
/api/v2/time_entries/[time_entry_id]/toggle_timer
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Delete a Time Entry

delete
/api/v2/time_entries/[id]

Note:
Deleted time entries cannot be restored.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/time_entries/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Email Configs

Note:
This section is for the old email configuration APIs which are no longer supported. You can find the new mailbox APIs which have additional capabilities here.
Only users with admin privileges can access the following APIs.

Attribute Type Description
active boolean Set to true if the email config is verified and activated
group_id number Denotes the group ID to which the email is associated
id number Unique ID of the email config
name string Name of the email config
primary_role boolean Set to true if the email associated to a product, is the primary email
product_id number Denotes the product ID to which the email is associated
reply_email string Denotes your support email address
to_email string Denotes the email address to which your support emails gets forwarded
created_at datetime Email Config creation timestamp
updated_at datetime Email Config updated timestamp

View an Email Config

get
/api/v2/email_configs/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email_configs/1'
EXPAND ↓
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"
}
EXPAND ↓

List All Email Configs

get
/api/v2/email_configs
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email_configs'
EXPAND ↓
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"
   }
]
EXPAND ↓

Email MailboxesNEW

Note:
Only users with admin privileges can access the following APIs.

Attribute Type Description
access_type string Denotes if the custom mailbox is to be used for incoming, outgoing or both.Takes the values "incoming", "outgoing" or "both". Should be set to "outgoing" or "both" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
active boolean Set to true if the email mailbox is verified and activated.
authentication string Denotes the type of authentication that should be used authenticate the custom mailbox. It can be plain/login/CRAM-MD5
custom_mailbox hash Mandatory if the mailbox is of the type custom mailbox. This field contains the incoming and/or outgoing configurations of the mailbox based on what access type is set.
default_reply_email boolean Set to true if the email associated to a product, is the primary email.
delete_from_server boolean If set to true, Freshdesk is given the permission to delete the email from the mailbox after the ticket is created.
failure_code string Denotes the failure message if any in the custom incoming mailbox.
forward_email string Denotes the email address to which your support emails gets forwarded.
freshdesk_mailbox hash If the mailbox is of the type Freshdesk mailbox this field contains the forward email to which your support emails gets forwarded.
group_id number Denotes the group ID to which the email is associated.
id number Unique ID of the email mailbox.
incoming hash Contains the incoming configuration of the custom mailbox.
mail_server string Denotes the server used by incoming and/or outgoing configurations of the mailbox.
mailbox_type string Denotes if the mailbox uses a Freshdesk mailbox or a custom mailbox setup by the customer. It takes the values "freshdesk_mailbox" or "custom_mailbox". Should be set to "custom_mailbox" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
name string Name of the email mailbox.
outgoing hash Contains the outgoing configuration of the custom mailbox.
password string Denotes the password that will be used to authenticate the custom mailbox.
port number Denotes the port used by incoming and/or outgoing configurations of the mailbox.
product_id number Denotes the product ID to which the email is associated.
support_email string Denotes your support email address.
use_ssl boolean Denotes if the incoming and/or outgoing configuration should use ssl while authenticating the mailbox.
username string Denotes the username used to authenticate the custom mailbox.
created_at datetime Email Mailbox creation timestamp
updated_at datetime Email Mailbox updated timestamp

Create an Email Mailbox

post
/api/v2/email/mailboxes

Parameters

Attribute Type Description
name string Name of the email mailbox.
support_email Mandatory Unique string Denotes your support email address.
group_id number Denotes the group ID to which the email is associated.
product_id number Denotes the product ID to which the email is associated.
default_reply_email string Set to true if the email associated to a product, is the primary email.
mailbox_type Mandatory string Denotes if the mailbox uses a Freshdesk mailbox or a custom mailbox setup by the customer. It takes the values "freshdesk_mailbox" or "custom_mailbox". Should be set to "custom_mailbox" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
custom_mailbox hash Mandatory if the mailbox is of the type custom mailbox. This field contains the incoming and/or outgoing configurations of the mailbox based on what access type is set.
access_type string Denotes if the custom mailbox is to be used for incoming, outgoing or both.Takes the values "incoming", "outgoing" or "both". Should be set to "outgoing" or "both" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
incoming hash Contains the incoming configuration of the custom mailbox.
mail_server * string Denotes the server used by incoming and/or outgoing configurations of the mailbox.
port * number Denotes the port used by incoming and/or outgoing configurations of the mailbox.
use_ssl * boolean Denotes if the incoming and/or outgoing configuration should use ssl while authenticating the mailbox.
delete_from_server ✝ boolean Denotes if the incoming configuration has to delete it from the server after authentication.
authentication * string Denotes the type of authentication that should be used authenticate the custom mailbox. It can be plain/login/CRAM-MD5
username * string Denotes the username used to authenticate the custom mailbox.
password * string Denotes the password that will be used to authenticate the custom mailbox.
* These attributes are mandatory in the incoming and/or outgoing hash if mailbox_type is 'custom_mailbox' and based on the access type set ("incoming", "outgoing" or "both").
✝ These attributes are mandatory in the incoming hash if mailbox_type is 'custom_mailbox' based on the access type set("incoming", "outgoing" or "both").
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
Request 
1
2
3
4
5
{
  "name": "Test emailbox via create api",
  "support_email": "testemail@gmail.com",
  "mailbox_type": "freshdesk_mailbox"
}
EXPAND ↓
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"
  }
}
EXPAND ↓

Create a custom mailbox

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
    }
  }
}
EXPAND ↓
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"
    }
  }
}
EXPAND ↓

View an Email Mailbox

get
/api/v2/email/mailboxes/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes/1'
EXPAND ↓
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"
    }
  }
}
EXPAND ↓

List All Email Mailboxes

get
/api/v2/email/mailboxes

Use filters to view only specific mailboxes (those which match the criteria that you choose). The filters listed in the table below can also be combined

Note:
1. When using filters, the query string must be URL encoded
2. By default the all the primary mailboxes will come first followed by the mailboxes ordered by product id in ascending.

Filter by Handle
support_email, forward_email /api/v2/contacts?<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
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes'
EXPAND ↓
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"
    }
  },
  ...
]
EXPAND ↓

Additional Examples

1. Get a list of mailboxes filtered by the support_email address. Since the support_email address is unique, you will get only one mailbox in the list.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes?support_email=superman@gmail.com'
EXPAND ↓

2. Get the mailboxes associated with a specific product and a group that are active.

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes?product_id=1&group_id=1&active=true'
EXPAND ↓

3. Mailboxes ordered by group in descending.( order_by is required if order_type is present)

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/email/mailboxes?order_by=group_id&order_type=desc'
EXPAND ↓

Update an Email Mailbox

put
/api/v2/email/mailboxes/[id]

Parameters

Attribute Type Description
name string Name of the email mailbox.
support_email string Denotes your support email address.
group_id number Denotes the group ID to which the email is associated.
product_id number Denotes the product ID to which the email is associated.
default_reply_email string Set to true if the email associated to a product, is the primary email.
mailbox_type string Denotes if the mailbox uses a Freshdesk mailbox or a custom mailbox setup by the customer. It takes the values "freshdesk_mailbox" or "custom_mailbox". Should be set to "custom_mailbox" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
custom_mailbox hash Mandatory if the mailbox is of the type custom mailbox. This field contains the incoming and/or outgoing configurations of the mailbox based on what access type is set.
access_type string Denotes if the custom mailbox is to be used for incoming, outgoing or both.Takes the values "incoming", "outgoing" or "both". Should be set to "outgoing" or "both" for a public domain mailbox like "gmail", "hotmail", "outlook", "yahoo", "aol".
incoming hash Contains the incoming configuration of the custom mailbox.
mail_server * string Denotes the server used by incoming and/or outgoing configurations of the mailbox.
port * number Denotes the port used by incoming and/or outgoing configurations of the mailbox.
use_ssl * boolean Denotes if the incoming and/or outgoing configuration should use ssl while authenticating the mailbox.
delete_from_server ✝ boolean Denotes if the incoming configuration has to delete it from the server after authentication.
authentication * string Denotes the type of authentication that should be used authenticate the custom mailbox. It can be plain/login/CRAM-MD5
username * string Denotes the username used to authenticate the custom mailbox.
password * string Denotes the password that will be used to authenticate the custom mailbox.
* These attributes are mandatory in the incoming and/or outgoing hash if mailbox_type is 'custom_mailbox' and based on the access type set ("incoming", "outgoing" or "both").
✝ These attributes are mandatory in the incoming hash if mailbox_type is 'custom_mailbox' based on the access type set("incoming", "outgoing" or "both").
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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",
}
EXPAND ↓
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"
  }
}
EXPAND ↓

Update a custom mailbox

Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
    }
  }
}
EXPAND ↓
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"
    }
  }
}
EXPAND ↓

Delete an Email Mailbox

delete
/api/v2/email/mailboxes/[id]

Note:
1. This action is irreversible. Emails sent to this inbox will no longer be created as tickets.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/email/mailboxes/1'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Update Mailbox Settings

put
/api/v2/email/settings

Parameters

Attribute Type Description
personalized_email_replies boolean If true, then agents will be allowed to choose their own name as the sender name in ticket replies and outbound emails. Sender email will still remain the support email address (like 'Rachel Doe ').
create_requester_using_reply_to boolean Note: If false, requester will be created using 'From' address in email.
allow_agent_to_initiate_conversation boolean If true, agents will be able to send outbound emails to new or existing customers that will be converted into outbound tickets.
original_sender_as_requester_for_forward boolean When an agent forwards an email from their mailbox to the helpdesk, create the ticket under the original sender. If false, the requester is the agent.
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
  }
EXPAND ↓
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
  }
EXPAND ↓

View Mailbox Settings

get
/api/v2/email/settings
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT GET 'https://domain.freshdesk.com/api/v2/email/settings'
EXPAND ↓
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
  }
EXPAND ↓

Update Automatic Bcc emails

put
/api/v2/notifications/email/bcc

Note:
1. The array has a limit of 255 characters.

Parameters

Attribute Type Description
emails array This email address will be included automatically in the Bcc field for all ticket communications.
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
Request 
1
2
3
{
    "emails": ["testemail1@gmail.com", "testemail2@gmail.com"]
  }
EXPAND ↓
Response 
1
2
3
{
    "emails": ["testemail1@gmail.com", "testemail2@gmail.com"]
  }
EXPAND ↓

View Automatic Bcc emails

get
/api/v2/notifications/email/bcc
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/notifications/email/bcc'
EXPAND ↓
Response 
1
2
3
{
    "emails": ["testemail1@gmail.com", "testemail2@gmail.com"]
  }
EXPAND ↓

Products

If you offer multiple products, you can have a separate support portal for each product. You can give these portals different URLs and hide irrelevant forums and solution articles by restricting access to specific categories but have agents support all these products from a single helpdesk.

Note:
Only users with admin privileges can access the following APIs.

Attribute Type Description
description string Description of the product
id number Unique ID of the product
name string Name of the product
created_at datetime Product creation timestamp
updated_at datetime Product updated timestamp

View a Product

get
/api/v2/products/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/products/1'
EXPAND ↓
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"
}
EXPAND ↓

List All Products

get
/api/v2/products
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/products'
EXPAND ↓
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"
   }
]
EXPAND ↓

Business Hours

Business Hours refer to the working hours of your company. When configured, anything outside your working hours will not be timed by Freshdesk. You can specify working hours for weekdays and weekends, as well as include a list of holidays on which your company will be closed.

Note:
Only users with admin privileges can access the following APIs.

Attribute Type Description
description string Description of the business hour
id number Unique ID of the business hour
is_default boolean Set to true if this is the default business hour
name string Name of the business hour
time_zone string Denotes the time zone of the business hour
business_hours dictionary Collection of start time and end time of days of a week - 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'

ATTRIBUTE TYPE DESCRIPTION
monday
tuesday
wednesday
thursday
friday
saturday
sunday 		dictionary Object of 'start_time' and 'end_time'
start_time string Time in "hh:mm:ss a" format ex: "08:00:00 am"
end_time string Time in "hh:mm:ss a" format ex: "11:59:59 am"
created_at datetime Business Hour creation timestamp
updated_at datetime Business Hour updated timestamp

View a Business Hour

get
/api/v2/business_hours/[id]

To view a particular business hour amongst all in the roster, use this API

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/business_hours/35000006727'
EXPAND ↓
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"
}
EXPAND ↓

List All Business Hours

get
/api/v2/business_hours

To view all the business hours in your list, use this API.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/business_hours'
EXPAND ↓
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"
	}

]
EXPAND ↓

Scenario Automations

Scenario Automations let you carry out a bunch of updates to the ticket with a single click. They help you quickly handle recurring scenarios.

Attribute Type Description
id number ID of the Scenario
name string Name of the Scenario
description string A short description about the Scenario
actions array of actions Actions to be performed by the Scenario
private boolean Boolean value stating whether the Scenario is accessible to self or all
created_at datetime Scenario Automations creation timestamp
updated_at datetime Scenario Automations updated timestamp

List All Scenario Automations

get
/scenario_automations.json

To view all the scenario automations in your list, use this API.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/scenario_automations'
EXPAND ↓
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"
   }
]
EXPAND ↓

SLA Policies

A service level agreement (SLA) policy lets you set standards of performance for your support team. Your SLA policies will be used in Freshdesk to determine the 'Due By' time for each ticket. You can have a default SLA policy for all customers, or have multiple SLA policies for different customer tiers, like those who have subscribed to your Premium Support package.

Note:
Only users with admin privileges can access the following APIs.

Attribute Type Description
active boolean Set to true if the SLA policy is active
description string Description of the SLA policy
id number Unique ID of the SLA policy
is_default boolean Set to true if it is the default SLA policy
name string Name of the SLA policy
position number Denotes the order of the SLA policy. If you have configured multiple SLA policies, the first one with matching conditions will be applied to a ticket.
sla_target dictionary Key value pair containing the object and the array of object IDs denoting the priorities and the applicable conditions.
'priority_4' - urgent, 'priority_3' - high, 'priority_2' - medium, 'priority_1' - low is mandatory and needs to be passed in the same order.

ATTRIBUTE TYPE DESCRIPTION
priority_4, priority_3, priority_2, priority_1 dictionary Nested collection of key value pairs containing the 'respond_within', 'resolve_within', 'business_hours', 'escalation_enabled'.
All are mandatory
respond_within number Mutliples of sixty and must be greater 900
resolve_within number Mutliples of sixty and must be greater 900
business_hours boolean Set to true if business hours needs to be used
escalation_enabled boolean Set to true if escalation is required
applicable_to dictionary Key value pair containing the 'company_ids', 'group_ids', 'sources', 'ticket_types', 'product_ids' denoting the conditions based on which the SLA policy is to be applied
One of them is mandatory.

ATTRIBUTE TYPE DESCRIPTION
company_ids array of number List of company ids
group_ids array of number List of group ids
sources array of number List of sources
ticket_types array of string List of ticket types
product_ids array of number List of products
escalation dictionary Nested collection of key value pairs containing the 'response' and 'resolution' denoting who to escalate to and when.
One of them is mandatory.

ATTRIBUTE TYPE DESCRIPTION
response dictionary Key value pairs of 'escalation_time' and 'agent_ids' denoting escalation response due time and agent ids
resolution dictionary Nested collection of key value pairs containing the 'level1', 'level2', 'level3', 'level4' levels of resolution escalation
level must be in the increasing order. And one of them mandatory.
i.e. level2 requires level1
level3 requires level2 and level1
level4 requires level3, level2 and level1
level1, level2, level3, level4 dictionary Key value pairs of 'escalation_time' and 'agent_ids' denoting escalation resolution due time and agent ids
escalation_time number Mutliples of sixty and must be greater 900
agent_ids array of number List of agent ids

Create SLA Policies

post
/api/v2/sla_policies

Parameters

Attribute Type Description
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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

List All SLA Policies

get
/api/v2/sla_policies
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/sla_policies'
EXPAND ↓
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"
   }
]
EXPAND ↓

Update an SLA Policy

put
/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
Copied Copy 
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'
EXPAND ↓
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"
}
EXPAND ↓

Omnichannel Activities

The activity API allows you and your agents to record activities from an external application or system in Freshdesk's contact timeline. Pushing information from your applications about a user can provide rich contextual information to your support agents using Freshdesk. Activities published using this API would show up on the contact timeline giving your agents a complete view of the customer’s journey.

Publish Activities

post
/api/v2/contact-activities

Parameters

Attribute Type Description
activityMandatory object Key value pair of the object which describes information about action that has occurred in an external application.

ATTRIBUTE TYPE DESCRIPTION
name Mandatory string The name of the activity performed (this is the text which is visible in the contact timeline).
timestamp string The time at which the activity was performed. If not given, this would be populated with the time at which we received activity.
description string User friendly description of the activity
link string Link to the activity
actorMandatory object Key value pair of the object which describes the person or entity performed the activity.
sourceMandatory object Key value pair of the object which describes the application, where the activity was performed.
object object Key value pair of the object which describes the object on which activity was performed.
context object Key value pair of the object which can be used to send additional context about the activity. It should adhere to the JSON schema https://json-schema.org
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
email * string Email address of the contact
twitter_id * string Twitter handle of the contact
unique_external_id * string External ID of the contact
facebook_id * string Facebook ID of the contact
id * number ID of the contact
name string Name of the contact
is_actor boolean Used to define whether the actor who performed the activity is the contact or not. Default value is true, i.e we assume that the contact has performed the activity.
*One of these five attributes is mandatory
The following table lists the attributes of actor:
Attribute Type Description
id string ID of the actor.
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.
The following table lists the attributes of source:
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.
The following table lists the attributes of object:
Attribute Type Description
type string Type of the object. As an example, the type could be "call", "transaction", "cart", "website".
id string ID of the object. It can be used to send transaction id, cart id etc.
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
Response 
1
HTTP Status: 200 Success
EXPAND ↓

List All Automation Rules

get
/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
Copied Copy 
1
curl -v -u yourapikey:X  -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/automations/1/rules'
EXPAND ↓
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
  }
}
EXPAND ↓

View an Automation Rule

get
/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
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/automations/1/rules/109866'
EXPAND ↓
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"
}
EXPAND ↓

Delete an Automation Rule

delete
/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
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/automations/1/rules/109866'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Create an Automation Rule

post
/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

events:
Field Name Type Description
field_name string Name of the field
from string Value of the field before the event
to string Value of the field after the event

performer:
Field Name Type Description
type integer Event performer. Possible values are:
1- Agent
2- Requester
3- Agent or Requester
4- System
Members

**Applicable only if type is 1**

 Array of strings IDs of the agents

conditions:
Field Name Type Description
name string Title of the condition
match_type string To check whether all conditions have to be met or atleast one. Possible values are: “all”,”any”
properties Array of objects Properties of the condition. Objects include:
1. resource_type(string) - Type of the resource. Possible values are contacts, tickets, companies, custom_object.
2. field_name(string) - Name of the field
3. Operator(Boolean)- AND/OR operator to combine multiple conditions in a rule
4. value(string) - Value set on the selected field
5. object_reference(string) - Ticket’s look up field value

actions:
Field Name Type Description
field_name string 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
Copied Copy 
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'
EXPAND ↓
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
    }
}
EXPAND ↓

Update an Automation Rule

put
/api/v2/automations/[automation_type_id]/rules/[id]
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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
    }
}
EXPAND ↓

Settings

Settings are configured through the Admin page of the Freshdesk web app.

View Helpdesk Settings

get
/api/v2/settings/helpdesk
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/settings/helpdesk'
EXPAND ↓
Response 
1
2
3
4
5
{
  "primary_language": "en",
  "supported_languages": ["ru-RU", "es"],
  "portal_languages": ["ru-RU"]
}
EXPAND ↓

Threads

Note: Access to the following APIs is restricted to users with admin privileges..

To create a new thread type, we utilize the following APIs. Our system distinguishes between two entities: threads and thread messages. When dealing with existing threads, we can create thread messages. Therefore, some APIs are designed to manage threads, while others are specifically tailored to handle thread messages.

JSON Parameters
Parameters Description
id It refers to the thread ID
type what type of thread it is whether a forward, discussion or private thread
title title given to the specific thread ex:abc thread
created_by it referes to who has created that thread
parent It refers to the parent ticket in which the thread is created under which we have parent_id and type as ticket
anchor we can create a thread from a note of a ticket
participants the one who is involved in sending the messages.
additional_info It can be anything like email_config_id i.e from there the actual email has come from , if the quoted text is present or not etc.

Create a thread

post
api/v2/collaboration/threads
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
        }
}
    ]
EXPAND ↓

Get a thread

get
api/v2/collaboration/threads/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/collaboration/threads/2'
EXPAND ↓
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"
          }
          
        ]
    }
EXPAND ↓

Update a thread

put
api/v2/collaboration/threads/[id]
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
            }
          }
        }
      }
EXPAND ↓

Delete a thread

delete
api/v2/collaboration/threads/[id]

Note: Deleting a thread is an irreversible action! Once deleted, it cannot be restored. Please use caution when proceeding with this action.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/collaboration/threads/2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Thread messages

Note: Access to the following APIs is restricted to users with admin privileges.

For creating replies or adding a new message for already created thread.

JSON Parameters
Parameters Description
body Content of the note in HTML format
body_text Content of the note in plan text format
attachment_ids IDs of attachments to be added to the reply
inline_attachment_ids IDs of inline attachments to be added to the reply
full_message HTML content with original and quoted text included
full_message_text Plain text that contains just the quoted text

Create message for thread

post
api/v2/collaboration/messages
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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&ltsupport@freshworks8249.freshdesk.com&gt 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&lt;support@freshworks8249.freshdesk.com&gt; 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&lt;support@freshworks8249.freshdesk.com&gt; 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 &lt;test@gmail.com&gt; 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&ltsupport@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:"
EXPAND ↓

Get message for thread

get
api/v2/collaboration/messages/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/collaboration/messages/2'
EXPAND ↓
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 &amp; 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: "
    }
EXPAND ↓

Update message for thread

put
api/v2/collaboration/messages/[id]
Sample code | Curl
Copied Copy 
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'
EXPAND ↓
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"
            }
          ]
        }
EXPAND ↓

Delete message for thread

delete
api/v2/collaboration/messages/[id]

Note: Deleting messages from a thread is an irreversible action! Once deleted, it cannot be restored. Please use caution when proceeding with this action.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/collaboration/messages/2'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Get quoted text for message

get
api/v2/collaboration/messages/[id]/generate-quote
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/collaboration/messages/{id}/generate-quote'
EXPAND ↓
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 &lt;test.test@test.com&gt;  wrote:<div dir=\"ltr\">test ticket<br>\\n</div>\\n\\n\\n</blockquote>\\n</div>"
    }
EXPAND ↓

Enter your Freshdesk domain and API key and the CURL commands will become executable.