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 i.e. 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 upto 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 hour 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.

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

Note:
1. Please follow the best practices to stay under the rate limit.
2. If you need more than the default limit, please contact us.
3. Even invalid requests will count towards the rate limit.
4. Some custom apps (freshplugs) consume API calls which 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: 3000
X-Ratelimit-Remaining: 998
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 hour.
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: 1521

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

September 2016

July 2016

June 2016

May 2016

  • View a Ticket and List all Tickets now support the embedding of the ticket stats.
  • List All Ticket Fields, List All Company Fields and List All Contact Fields are also allowed for agents who can Create a Ticket, Create a Company and Create a Contact respectively.
  • April 2016

    • Updating or deleting a ticket that has been marked as spam or deleted will now return a '405 Method Not Allowed'
    • Updating or deleting a contact that has been blocked or deleted will now return a '405 Method Not Allowed'
    • New API to create an outbound email
    • Added support for editing tickets created through outbound email via Update a Ticket
    • Create a Ticket and Update a Ticket now enforce dynamic form validation
    • View a Ticket now supports embedding the details of the requester and the company

    March 2016

    • Previously, for the ticket APIs, we accepted 'description' and 'description_html' as attributes in the request. Now we will only accept the description attribute which can now optionally contain HTML. In the response, we will return a 'description' and 'description_text' (which will strip any HTML out of description). We have made similar changes to Topics, Comments, and Agents. The full set of breaking changes are listed below
    • The following request attributes have been removed
    • 'description_html' has been removed from Create a Ticket and Update a Ticket
    • 'body_html' has been removed from Create a Note, Create a Reply and Update a conversation
    • The following request attributes have been renamed
    • 'message_html' has been renamed to message in Create a Topic
    • 'body_html' has been renamed to body in Creat a Comment
    • The following response attributes have been removed
    • 'description_html' has been removed from Forum responses
    • The following response attributes have been renamed
    • 'description' and 'description_html' have been renamed to description_text and description respectively in Ticket responses
    • 'body' and body_html have been renamed to body_text and body in Conversation & Forum Comment responses
    • 'signature_html' has been renamed to signature in Agent responses
    • Notes have been renamed to Conversations. This has resulted in breaking changes in the following four APIs
    • List All Notes of a Ticket has been renamed to List All Conversations of a Ticket
    • View a ticket (include=notes is now include=conversations)
    • Update A Note has been renamed to Update a Conversation
    • Delete A Note is now Delete a Conversation
    • Reply to Ticket has been renamed to Create Reply and moved to the Conversations section
    • New API to retrieve the currently authenticated agent
    • Added support for associating multiple emails to a contact

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

Freshdesk also uses Basic Access Authorization. This means that for authentication, you can use the same username and password that you use when you log in to your helpdesk.

curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X 'GET https://domain.freshdesk.com/api/v2/tickets'

Note:
If you are sure that your password and username are correct, but are still unable to access your helpdesk, make sure that your "username:password" (or "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
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 that returns a single object will consume an additional API call credit per embedded resource while embedding into APIs that return a collection of objects will consume two additional credits.

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 alloted 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 trigerred 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 6 more
Conversations Yes No Yes Yes* Yes
Contacts Yes Yes Yes Yes Yes 1 more
Agents Yes* Yes Yes Yes Yes 1 more
Roles No Yes Yes No No
Groups Yes Yes Yes Yes Yes
Companies Yes Yes Yes Yes Yes 1 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 configs 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
* 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 15MB.
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
Mobihelp 8
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. If no contact exists with this facebook_id, then a new contact will be created.
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.
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 15MB.
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
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
* 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
Mobihelp 8
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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 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 user@yourcompany.com:test -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 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 15MB.
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 user@yourcompany.com:test -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 upto 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 user@yourcompany.com:test -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
{ "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" : [ ], "attachments" : [ ] }
EXPAND ↓

Additional Examples

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

Copied Copy
1
curl -v -u user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=stats'
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. When using filters, the query string must be URL encoded - see example
3. 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.

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]
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 Currently not available
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.
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
57
58
59
60
[ { "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, "description_text" : "Computer is not working as expected", "description" : "<div>Computer is not working as expected</div>", "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, "description_text" : "Not given.", "description" : "<div>Not given.</div>", "custom_fields" : { "category" : null } } ]
EXPAND ↓

Additional Examples

1. 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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/tickets?filter=watching'
EXPAND ↓

2. Get the first page of a list of tickets from the specified requestor. The tickets will be returned in the descending order of their priority i.e highest priority first.

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

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

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

4. 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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/tickets?updated_since=2015-08-17'
EXPAND ↓

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

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

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

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

Update a Ticket

put
/api/v2/tickets/[id]

Note:
1. 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.
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 15MB.
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
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
* 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
Mobihelp 8
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 user@yourcompany.com:test -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 ↓

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 user@yourcompany.com:test -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/1'
EXPAND ↓
Response
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 user@yourcompany.com:test -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 (API key or username/password) are being used to make this 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 user@yourcompany.com:test -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
420
[ { "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, "MobiHelp" : 8, "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 user@yourcompany.com:test -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 user@yourcompany.com:test -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
[ { "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 ↓

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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries?page=2'
EXPAND ↓

List All Satisfaction Ratings of a TicketBETA

get
/api/v2/tickets/[ticket_id]/satisfaction_ratings
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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 ↓

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 15MB.
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
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
Created from Mobihelp 10
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 15MB.
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/user 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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 15MB.
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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 15MB.
body string Content of the note in HTML
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "body":"Can you provide some screeshots?" }' '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 screeshots?", "body" : "<div>Can you provide some screeshots?</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 user@yourcompany.com:test -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 user@yourcompany.com:test -X DELETE 'https://domain.freshdesk.com/api/v2/conversations/5'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
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 company to which this contact belongs
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 number 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
view_all_tickets boolean Set to true if the contact can see all tickets that are associated with the company to which he belong
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 * number Mobile number of the contact
twitter_id *Unique string Twitter handle of the contact
other_emails array of strings Additional emails associated with the contact
company_id number ID of the 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
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)
*One of these four attributes is mandatory
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "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, "other_emails":["lex@freshdesk.com","louis@freshdesk.com"], "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 user@yourcompany.com:test -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
{ "active":false, "address":null, "company_id":null, "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":[ ], "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 user@yourcompany.com:test -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
{ "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, "other_emails": [], "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]
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
[ { "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", "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", "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 user@yourcompany.com:test -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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/contacts?state=verified&per_page=20'
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 number Mobile number of the contact
twitter_id Unique string Twitter handle of the contact
other_emails array of strings Additional emails associated with the contact
company_id number ID of the 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
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)
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "active":false, "address":null, "company_id":null, "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"], "created_at":"2015-08-28T09:08:16Z", "updated_at":"2015-08-28T11:37:05Z", "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 user@yourcompany.com:test -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
{ "active":false, "address":null, "company_id":null, "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":[], "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 ↓

Delete a Contact

delete
/api/v2/contacts/[id]
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshdesk.com/api/v2/contacts/432'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
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 (API key, username and password) were used to make this 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 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
group_ids array of numbers Group IDs associated with the agent
role_ids array of numbers Role IDs associated with the agent. Atleast one role should be assoicated with the agent. Current logged in agent can't update his/her role_ids
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "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 ], "role_ids" : [ 1 ], "id": 432, "ticket_scope": 1, "created_at": "2015-08-28T11:47:58Z", "updated_at": "2015-08-28T11:47:58Z" } }
EXPAND ↓

List All Contact Fields

get
/api/v2/contact_fields

Note:
The agent whose credentials (API key or username/password) are being used to make this API call should be authorised to either view the contact fields or create contact

Contact Fields
Contact Field Description
editable_in_signup Set to true if the field can be updated by customers during signup
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 Customers can edit the field in the customer portal
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
displayed_for_customers Customers can see the field in the customer portal
required_for_agents Set to true if the field is mandatory for agents
choices List of values supported by the field
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
[ { "editable_in_signup":true, "id":1, "label":"Full Name", "name":"name", "position":1, "type":"default_name", "default":true, "customers_can_edit":true, "label_for_customers":"Full Name", "required_for_customers":true, "displayed_for_customers":true, "required_for_agents":true, "created_at":"2015-08-18T16:18:07Z", "updated_at":"2015-08-18T16:18:07Z" }, { "editable_in_signup":false, "id":2, "label":"Title", "name":"job_title", "position":2, "type":"default_job_title", "default":true, "customers_can_edit":true, "label_for_customers":"Title", "required_for_customers":false, "displayed_for_customers":true, "required_for_agents":false, "created_at":"2015-08-18T16:18:07Z", "updated_at":"2015-08-18T16:18:07Z" }, ... { "editable_in_signup":false, "id":11, "label":"Language", "name":"language", "position":12, "type":"default_language", "choices":{ "ar":"Arabic", "ca":"Catalan", "zh-CN":"Chinese", "cs":"Czech", "da":"Danish", "nl":"Dutch", "en":"English", "et":"Estonian", "fi":"Finnish", "fr":"French", "de":"German", "he":"Hebrew", "hu":"Hungarian", "id":"Indonesian", "it":"Italian", "ja-JP":"Japanese", "ko":"Korean", "nb-NO":"Norwegian", "pl":"Polish", "pt-BR":"Portuguese (BR)", "pt-PT":"Portuguese/Portugal", "ru-RU":"Russian", "sk":"Slovak", "sl":"Slovenian", "es":"Spanish", "es-LA":"Spanish (Latin America)", "sv-SE":"Swedish", "tr":"Turkish", "uk":"Ukrainian", "vi":"Vietnamese" }, "default":true, "customers_can_edit":true, "label_for_customers":"Language", "required_for_customers":false, "displayed_for_customers":true, "required_for_agents":false, "created_at":"2015-08-18T16:18:08Z", "updated_at":"2015-08-18T16:18:08Z" }, { "editable_in_signup":false, "id":12, "label":"Tags", "name":"tag_names", "position":13, "type":"default_tag_names", "default":true, "customers_can_edit":false, "label_for_customers":"Tags", "required_for_customers":false, "displayed_for_customers":false, "required_for_agents":false, "created_at":"2015-08-18T16:18:08Z", "updated_at":"2015-08-18T16:18:08Z" }, { "editable_in_signup": false, "id": 6000773035, "label": "Permanent", "name": "permanent", "position": 14, "type": "custom_checkbox", "default": false, "customers_can_edit": true, "label_for_customers": "Permanent", "required_for_customers": false, "displayed_for_customers": true, "required_for_agents": false, "created_at": "2016-01-09T06:31:16Z", "updated_at": "2016-01-09T06:31:16Z" } ]
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:
Only administrators can execute the following APIs

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)
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] number 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

View an Agent

get
/api/v2/agents/[id]
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "available":true, "occasional":false, "signature":null, "group_ids" : [ 4 ], "role_ids" : [ 1 ], "id":432, "ticket_scope":1, "created_at":"2015-08-28T11:47:58Z", "updated_at":"2015-08-28T11:47:58Z", "available_since":null, "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 ↓

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 user@yourcompany.com:test -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
[ { "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, "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" } }, { "available":true, "occasional":false, "s ignature":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, "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 ↓

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 user@yourcompany.com:test -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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/agents?state=fulltime&per_page=20'
EXPAND ↓

Update an Agent

put
/api/v2/agents/[id]

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
group_ids array of numbers Group IDs associated with the agent
role_ids array of numbers Role IDs associated with the agent. Atleast one role should be assoicated with the agent. Current logged in agent can't update his/her role_ids
name string Name of the Agent
email string Email address of the Agent.
phone string Telephone number of the Agent.
mobile number 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
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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 ], "created_at" : "2016-05-25T11:36:14Z", "updated_at" : "2016-07-06T12:25:57Z", "available_since" : null, "contact" : { "active" : true, "email" : "sample@yourdomain.com", "job_title" : null, "language" : "en", "last_login_at" : "2016-06-14T11:07:52Z", "mobile" : null, "name" : "Sample", "phone" : null, "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:
Deleting an agent will downgrade the agent into a contact.

Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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 user@yourcompany.com:test -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
{ "available":true, "occasional":false, "signature":null, "group_ids" : [ 4 ], "role_ids" : [ 1 ], "id":432, "ticket_scope":1, "created_at":"2015-08-28T11:47:58Z", "updated_at":"2015-08-28T11:47:58Z", "available_since":null, "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 ↓

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 user@yourcompany.com:test -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 user@yourcompany.com:test -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:
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 boolean Set to true if automatic ticket assignment has been enabled. 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

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 boolean Describes the automatic ticket assignment type. Will not be supported if the "Round Robin" feature is disabled for the account. The default value is false
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 user@yourcompany.com:test -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":true, "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 user@yourcompany.com:test -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":true, "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 user@yourcompany.com:test -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":true, "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 boolean Describes the automatic ticket assignment type. Will not be supported if the "Round Robin" feature is disabled for the account. The default value is false
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 user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "name":"Entertainers", "description":"Singers dancers and stand up comedians", "agent_ids":[2,15] }' '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":true, "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 user@yourcompany.com:test -X DELETE 'https://domain.freshdesk.com/api/v2/groups/1'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Companies

When multiple contacts from the same company contact you, its 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
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
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "name":"SuperNova", "domains":["supernova","nova"], "description":"Spaceship Manufacturing Company" }' 'https://domain.freshdesk.com/api/v2/companies'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
{ "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" }
EXPAND ↓

View a Company

get
/api/v2/companies/[id]
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "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" } }
EXPAND ↓

List All Companies

get
/api/v2/companies
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
[ { "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" } }, { "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 } } ]
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
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "name":"Super Nova", "domains":["supernova","nova","super"], "description":"Space Shuttle Manufacturing" }' 'https://domain.freshdesk.com/api/v2/companies/8'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
{ "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" }
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 user@yourcompany.com:test -X DELETE 'https://domain.freshdesk.com/api/v2/companies/1'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

List All Company Fields

get
/api/v2/company_fields

Note:
The agent whose credentials (API key or username/password) are being used to make this API call should be authorised to either view the company fields or create a company

Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
[ { "id":1, "name":"name", "label":"Company name", "field_type":"default_name", "required_for_agent":true, "position":1, "default":true, "created_at":"2014-12-12T12:29:46+05:30", "updated_at":"2014-12-12T12:29:46+05:30" }, { "id":2, "name":"description", "label":"Description", "field_type":"default_description", "required_for_agent":false, "position":2, "default":true, "created_at":"2014-12-12T12:29:46+05:30", "updated_at":"2014-12-12T12:29:46+05:30" }, { "id":3, "name":"note", "label":"Notes", "field_type":"default_note", "required_for_agent":false, "position":3, "default":true, "created_at":"2014-12-12T12:29:46+05:30", "updated_at":"2014-12-12T12:29:46+05:30" }, { "id":4, "name":"domains", "label":"Domain Names for this company", "field_type":"default_domains", "required_for_agent":false, "position":4, "default":true, "created_at":"2014-12-12T12:29:46+05:30", "updated_at":"2014-12-12T12:29:46+05:30" }, { "id": 5, "name": "website", "label": "Website", "position": 5, "required_for_agent": false, "type": "custom_url", "default": false, "created_at": "2016-01-09T06:52:41Z", "updated_at": "2016-01-09T06:52:41Z" }, { "id": 6, "name": "address", "label": "Address", "position": 6, "required_for_agent": false, "type": "custom_paragraph", "default": false, "created_at": "2016-01-09T06:52:41Z", "updated_at": "2016-01-09T06:52:41Z" } ]
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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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, then the user whose API Key or username/password was used to make the API call will be considered the recepient.
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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 user@yourcompany.com:test -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 (API key or userame/password) were 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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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, then the user whose API Key or username/password was used to make the API call will be consider the recepient.
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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 user@yourcompany.com:test -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 (API key or userame/password) 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 user@yourcompany.com:test -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 (API key or userame/password) 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 user@yourcompany.com:test -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 ↓

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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 BETA

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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 BETA

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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 BETA

get
/api/v2/solutions/categories/[id]
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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 user@yourcompany.com:test -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 BETA

get
/api/v2/solutions/categories
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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 user@yourcompany.com:test -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 BETA

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 user@yourcompany.com:test -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/categories/3'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Folders

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

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
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
created_at datetime Solution Folder creation timestamp
updated_at datetime Solution Folder updated timestamp

Folder Properties

Visibility Value
All Users 1
Logged In Users 2
Agents 3
Selected Companies 4

Create a Solution Folder BETA

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
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
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "name":"sample folder", "description":"This is a sample folder.", "visibility":1 }' 'https://domain.freshdesk.com/api/v2/solutions/categories/3/folders'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
{ "id": 4, "name": "sample folder", "description": "This is a sample folder", "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 user@yourcompany.com:test -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
{ "id": 4, "name": "carpeta de la muestra", "description": "este es creado para fines de demostración", "visibility": 1, "category_id": 3, "created_at": "2016-09-08T13:01:01Z", "updated_at": "2016-09-08T13:01:01Z" }
EXPAND ↓

Update a Solution Folder BETA

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

Parameters

Attribute Type Description
description string Description of the solution folder
nameUnique string Name of the solution 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
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "id": 4, "name": "sample folder", "description": "updated description", "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 user@yourcompany.com:test -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
{ "id": 4, "name": "carpeta de la muestra", "description": "actualizada Descripción", "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 BETA

get
/api/v2/solutions/folders/[id]
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
{ "id": 4, "name": "sample folder", "description": "This is a sample folder", "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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/solutions/folders/4/es'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
{ "id": 4, "name": "carpeta de la muestra", "description": "este es creado para fines de demostración", "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 BETA

get
/api/v2/solutions/categories/[category_id]/folders
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
[ { "id": 4, "name": "sample folder", "description": "This is created for demo purpose", "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 user@yourcompany.com:test -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
[ { "id": 4, "name": "carpeta de la muestra", "description": "actualizada Descripción", "visibility": 4, "created_at": "2016-09-08T13:01:01Z", "updated_at": "2016-09-08T13:27:08Z", "company_ids": [1] } ]
EXPAND ↓

Delete a Solution Folder BETA

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 user@yourcompany.com:test -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
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
type number The type of the solution article
created_at datetime Solution Article creation timestamp
updated_at datetime Solution Article updated timestamp

Create a Solution Article BETA

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
typeMandatory number The type of the solution article. (1 - permenant, 2 - workaround)
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "title": "sample article", "description" : "this is a sample article with some <b> HTML Content </b>", "type" : 1, "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
{ "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, "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 user@yourcompany.com:test -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
{ "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, "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 BETA

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)
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
type number The type of the solution article. (1 - permenant, 2 - workaround)
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "id": 2, "type": 1, "category_id": 3, "folder_id": 4, "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 user@yourcompany.com:test -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
{ "id": 2, "type": 1, "category_id": 3, "folder_id": 4, "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 BETA

get
/api/v2/solutions/articles/[id]
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "id": 2, "type": 1, "category_id": 3, "folder_id": 4, "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]
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
{ "id": 2, "type": 1, "category_id": 3, "folder_id": 4, "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 BETA

get
/api/v2/solutions/folders/[id]/articles
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
[ { "id": 1, "type": 1, "category_id": 3, "folder_id": 4, "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, "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 user@yourcompany.com:test -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
[ { "id": 2, "type": 1, "category_id": 3, "folder_id": 4, "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 BETA

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 user@yourcompany.com:test -X DELETE 'https://domain.freshdesk.com/api/v2/solutions/articles/2'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Surveys

The Customer Satisfaction Survey is a built-in functionality 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 arry of string Accepted rating values for each specific question

List all SurveysBETA

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 user@yourcompany.com:test -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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/surveys?state=active'
EXPAND ↓

Satisfaction Ratings

Every response to a customer satisfcation 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 recieved 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 RatingBETA

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 user@yourcompany.com:test -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 RatingsBETA

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 user@yourcompany.com:test -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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/surveys/satisfaction_ratings?user_id=2'
EXPAND ↓

Time Entries

The time tracking feature in Freshdesk lets you track the time spent by each agent on 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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 attriubute 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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 user@yourcompany.com:test -X DELETE 'https://domain.freshdesk.com/api/v2/time_entries/1'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Email Configs

Note:
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 user@yourcompany.com:test -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 user@yourcompany.com:test -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 ↓

Products

If you offer multiple produts, 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 user@yourcompany.com:test -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 user@yourcompany.com:test -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
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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/business_hours/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
{ "id":1, "name":"default", "description":"Default Business Hour", "time_zone": "Chennai", "is_default": true, "created_at":"2014-01-08T09:08:53+05:30", "updated_at":"2014-01-08T09:08:53+05:30" }
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 user@yourcompany.com:test -X GET 'https://domain.freshdesk.com/api/v2/business_hours'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
[ { "id":1, "name":"default", "description":"Default Business Hour", "created_at":"2014-01-08T09:08:53+05:30", "updated_at":"2014-01-08T09: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
applicable_to dictionary Key value pair containing the object and the array of object IDs denoting the conditions based on which the SLA policy is to be applied
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.

List All SLA Policies

get
/api/v2/sla_policies
Sample code | Curl
Copied Copy
1
curl -v -u user@yourcompany.com:test -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
[ { "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]

Note:
Although it is possible to associate SLA policies with both groups and companies through the Web UI, currently the API only allows you to update the list of companies that the SLA policy is applicable to.

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 user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "applicable_to": { "company_ids" : [1,2] } }' 'https://domain.freshdesk.com/api/v2/sla_policies/2'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
{ "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 ↓

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 user@yourcompany.com:test -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 ↓

Enter your Freshdesk domain and username/password and the CURL commands will become executable.

Help and Support
Send us a message
Chat with us

...or Browse Help Articles

Copyright © Freshdesk Inc. All Rights Reserved.