Overview

Freshdesk is a cloud-based customer support platform that was founded with the mission of enabling companies of all sizes to provide great customer service. Our goal is simple: make it easy for brands to talk to their customers and make it easy for users to get in touch with businesses.

Freshdesk's APIs belong to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding or deleting data from your helpdesk. The APIs also support Cross-Origin Resource Sharing (CORS).

Note:
This documentation is for the v2.0 of the APIs. Documentation for the v1.0 APIs can be found here.

What API commands are used by Freshdesk?

Freshdesk APIs are plain JSON over HTTP and use the following HTTP verbs:

Command Purpose
POST Create an object
GET Fetch one or more objects
PUT Update an object
DELETE Remove an object

Note:
All API requests should hit the secured endpoint, that is, only HTTPS

What's New

Version 2 of the API brings several new features as well as changes to the previous APIs. This section highlights some of the new features introduced in v2.

  1. Higher rate limits as a result of significant performance enhancements
  2. Improved error handling - errors will return appropriate HTTP status codes and an error body
  3. Four new API categories - Business Hours, Products, Email Configs, and SLAs
  4. New APIs that enable you to Reply to a ticket and enhancements to existing APIs that enable you to Update a ticket's description, Update a ticket's notes, and Retrieve a list of tickets that have been recently modified
  5. XML Support has been deprecated, only JSON is supported
  6. Only SSL calls (HTTPS) will be allowed
  7. Works only via Freshdesk domains and not via custom CNAMEs
  8. Support for page sizes up to 100 has been added
  9. New API deprecation and breaking change policies
  10. Some categories have been renamed for consistency with the web application. For example, Forums are now Discussions and Users are now Contacts

Rate Limit

The number of API calls per minute is based on your plan. This limit is applied on an account wide basis irrespective of factors such as the number of agents or IP addresses used to make the calls. For all trial users, there is a default API limit of 50 calls/minute.

If your account hasn't been switched to the new minute level APIs, please contact support@freshdesk.com to get the new rate limits enabled for your account. To view the old API rate limits, click here

Note: An account can purchase additional API calls, to increase the rate limit. Contact us to know more about our pricing policy and purchase additional API calls.

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

To view the limits in the older plans, click here.

Plan Rate Limit/minute Maximum rate limit/minute per endpoint
Growth 200 Ticket Create - 80
Ticket Update - 80
Tickets List - 20
Contacts List - 20
Pro 400 Ticket Create - 160
Ticket Update - 160
Tickets List - 100
Contacts List - 100
Enterprise 700 Ticket Create - 280
Ticket Update - 280
Tickets List - 200
Contacts List - 200
If you have purchased additional rate limits, the sub-limits are as follows:
- 1000 Ticket Create - 400
Ticket Update - 400
Tickets List - 300
Contacts List - 300
- 2000 Ticket Create - 800
Ticket Update - 800
Tickets List - 400
Contacts List - 400

Notes:
1. Ensure to follow the rate limit - best practices to stay within the rate limit.
2. Even invalid requests count towards the rate limit.
3. Some custom apps consume API calls and these calls also count towards the rate limit.

You can check your current rate limit status by looking at the following HTTP headers which are returned in response to every API request.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Ratelimit-Total: 700
X-Ratelimit-Remaining: 426
X-Ratelimit-Used-CurrentRequest: 1
X-Freshdesk-Api-Version: latest=v2; requested=v2

Header Name Description
X-RateLimit-Total Total number of API calls allowed per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Used-CurrentRequest The number of API calls consumed by the current request. Most API requests consume one call, however, including additional information in the response will consume more calls.
Retry-After The number in seconds that you will have to wait to fire your next API request. This header will be returned only when the rate limit has been reached.

If your API request is received after the rate limit has been reached, Freshdesk will return an error in the response. The Retry-After value in the response header will tell you how long you need to wait before you can send another API request.

HTTP/1.1 429
Content-Type: application/json; charset=utf-8
Retry-After: 34

Policies

Freshdesk APIs are classified into either production or beta APIs. A production API is one that has been made generally available for public use and is stable. A beta API is one that is still in development or is for internal or limited use and whose stability cannot be guaranteed. Beta APIs may be removed or modified at any time without advance notice. The following policies apply to production APIs only.

Deprecation Policy

The current version of production level APIs is v2. When a new version of APIs is made generally available (not beta), the older version will be deprecated and will cease to function after six months. Once an API is removed, any request to it will result in a 404 error.

Note:
We will not remove any v1 API until similar functionality is present in the v2 APIs

Breaking Change Policy

Changes that do not break an API, such as adding a new attribute can be made at any time. Changes that break a production level API such as removing attributes or making major changes to the API’s behavior will only be done with an advance notice of 60 days. However, there may be rare occasions where due to legal, performance, or security reasons, we are forced to make breaking changes without advance notice.

Changelog

June 2022

  • We’ve added parent_folder_id, sub_folders_count, articles_count, hierarchy as solutions folder attributes and can be used in different Folder and Article APIs as part of Flexible Hierarchy feature. Read more about it here

November 2021

  • We've updated the Create an Email Mailbox API to allow only "custom_mailbox" in mailbox_type and access_type as "outgoing" or "both" for public domain mailboxes like "gmail", "hotmail", "outlook", "yahoo", "aol".

July 2021

January 2021

October 2020

  • We have updated the responses of /tickets, /tickets/id, /tickets/id/conversations to remove the content of the Tweets and Twitter direct messages inline with Twitter platform's content redistribution policy. Instead of the full Tweet content, you will be receiving the subject and description as 'View the message on Twitter'. For /contacts, /contacts/id APIs, you will be receiving the id of the user in the twitter_id field instead of the Twitter handle name.

April 2020

November 2019

September 2019

  • Unpublish an article by passing only the status as 1 without any other parameters in the Update a Solution Article API.
  • We've added a way to get article metrics for a specific language or consolidated across languages in the View a Solution Article API.

December 2018

  • We’ve added APIs to create and update SLA policies in your Freshdesk account.
  • The response to the GET Business hours API now includes the start time and end time of the business hours along with the time zone.

November 2018

  • We've added a way to get description in the List All tickets API by using the include: parameter. We will not be sending description in the standard response after 2019-01-31 and you will have to use include to get description if you need it in the response. For accounts created after 2018-11-30, using include is compulsory to get description.

July 2018

June 2018

May 2018

December 2017

July 2017

January 2017

September 2016

July 2016

June 2016

May 2016

Authentication

How does it work? Who can access my helpdesk? Can everybody see my data?

Before you can set the priority of a ticket or change a customer's name or use any of the APIs listed above, you need to "authenticate your ID" or "log in" in the same way as you log in to your helpdesk's web portal.

You can use your personal API key to authenticate the request. If you use the API key, there is no need for a password. You can use any set of characters as a dummy password.

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

For example, if your API key is abcdefghij1234567890, the curl command to use is:

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

Where can I find my API key?

  1. Log in to your Support Portal
  2. Click on your profile picture on the top right corner of your portal
  3. Go to Profile settings Page
  4. Your API key will be available below the change password section to your right

For more information, please refer to this solution article

Note:
If you are sure that your credentials are correct, but are still unable to access your helpdesk, make sure that the "APIkey:X" is Base64-encoded before passing it as an "Authorization" header.

What are the resources available via the API?

Every single piece of information - be it a customer's ID or the priority of a specific ticket - can be identified by its own unique identifier or "URI". If you want your data from the helpdesk, whether via your smartphone app or via a third party service, you need this identifier. All URIs follow a specific format and that format is:

https://your_helpdesk_domain_name/api/v2/resource_name

For example, if you are Davy Jones and you are managing problems of drowned souls via your Freshdesk portal "thelocker.freshdesk.com", then to access the contacts in your helpdesk, the syntax would be

https://thelocker.freshdesk.com/api/v2/contacts

For tickets, it would be

https://thelocker.freshdesk.com/api/v2/tickets

Note:
We have shortened API resource URLs throughout this document by omitting the domain name. For example, /api/v2/tickets is actually https://domain.freshdesk.com/api/v2/tickets

Will everyone have the same access rights?

No, your ability to access data depends on the permissions available to your Freshdesk user profile. For example, if your Freshdesk Agent Role is "Newbie Agent" who is only allowed to view tickets but not reply to them, then you will not be able to use the APIs to reply to a ticket.

Schema

Blank Fields:
Blank fields are included as null instead of being omitted.

Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. ( Example : 2016-02-13T23:27:49Z )

Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm

Note:
If a custom field is a date field, ensure to specify the value in the YYYY-MM-DD format.

If the time zone information is not present, it will be assumed to be in UTC.
( some valid datefields : 2016-02-15T21:16:25Z,    2012-12-24T12:56:15+05:30,    2010-03-23T12:00 )

Location Header:
POST requests will contain the Location Header in the response that points to the URL of the created resource.

Response
HTTP STATUS: HTTP 201 Created
Headers:
"Location": https://domain.freshdesk.com/api/v2/tickets/1

Embedding

Our previous version of APIs returned a large number of fields by default. In order to increase performance and reduce data usage, we have removed several of these fields in our v2.0 APIs. For example, when you view a ticket, we no longer return the requester's name or the company name. However, there may be situations where these fields are required and hence, we have included a mechanism to embed additional resources into an API call in order to minimise the number of required API calls.

Note:
Embedding resources into an API will consume an additional API call credit per embedded resource.

You can request for additional resources using the "include" keyword. For example you can embed the requester's details within the ticket view API by using the following command

Sample Request

curl -v -u 'abcdefgh12345678:X' -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=requester'

Sample Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

{
  "cc_emails" : ["user@cc.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["user@cc.com"],
  "email_config_id" : null,
  "fr_escalated" : false,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 1,
  "responder_id" : null,
  "source" : 2,
  "spam" : false,
  "status" : 2,
  "subject" : "",
  "company_id" : 1,
  "id" : 20,
  "type" : null,
  "to_emails" : null,
  "product_id" : null,
  "created_at" : "2015-08-24T11:56:51Z",
  "updated_at" : "2015-08-24T11:59:05Z",
  "due_by" : "2015-08-27T11:30:00Z",
  "fr_due_by" : "2015-08-25T11:30:00Z",
  "is_escalated" : false,
  "description_text" : "Not given.",
  "description" : "<div>Not given.</div>",
  "custom_fields" : {
    "category" : "Primary"
  },
  "tags" : [ ],
  "requester": {
    "email": "test@test.com",
    "id": 1,
    "mobile": null,
    "name": "Rachel",
    "phone": null
  },
  "attachments" : [ ]
}
EXPAND ↓

Attachments

Attachments are supported for the following endpoints
Please follow the guidelines listed below
  • Only files on your local machine can be attached using API.
  • The Content-Type should always be multipart/form-data for create/update requests with attachments.
  • The name of the file is preserved after it is attached i.e the filename sent in the response will be the same as the one in the request.
  • Sample code for dealing with attachments can be found here.

Errors

I have encountered an error. How do I debug it?

API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error. You can use the table below to understand what each code means.

HTTP Status Code Text Description
400 Client or Validation Error The request body/query string is not in the correct format. For example, the Create a ticket API requires the requester_id field to be sent as part of the request and if it is missing, this status code is returned.
401 Authentication Failure Indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here.
403 Access Denied This indicates that the agent whose credentials were used in making this request was not authorized to perform this API call. It could be that this API call requires admin level credentials or perhaps the Freshdesk portal doesn't have the corresponding feature enabled. It could also indicate that the user has reached the maximum number of failed login attempts or that the account has reached the maximum number of agents
404 Requested Resource not Found This status code is returned when the request contains invalid ID/Freshdesk domain in the URL or an invalid URL itself. For example, an API call to retrieve a ticket with an invalid ID will return a HTTP 404 status code to let you know that no such ticket exists.
405 Method not allowed This API request used the wrong HTTP verb/method. For example an API PUT request on /api/v2/tickets endpoint will return a HTTP 405 as /api/v2/tickets allows only GET and POST requests.
406 Unsupported Accept Header Only application/json and */* are supported.
When uploading files multipart/form-data is supported.
409 Inconsistent/Conflicting State The resource that is being created/updated is in an inconsistent or conflicting state. For example, if you attempt to Create a Contact with an email that is already associated with an existing user, this code will be returned.
415 Unsupported Content-type Content type application/xml is not supported. Only application/json is supported.
429 Rate Limit Exceeded The API rate limit allotted for your Freshdesk domain has been exhausted.
500 Unexpected Server Error Phew!! You can't do anything more here. This indicates an error at Freshdesk's side. Please email us your API script along with the response headers. We will reach you out to you and fix this ASAP.

Error Response

In addition to the HTTP status code, most errors will also return a response body that contains more information to help you debug the error. A sample error response is shown below. The format of the error response body is explained after the example.

Sample Error 
1
2
3
4
5
6
7
8
9
10
11
{
    "description":"Validation failed",
    "errors":[
        {
            "field":"name",
            "message":"Mandatory attribute missing",
            "code":"missing_field"
        }
    ]
}

Error Response Fields
Field Description
field The request field that triggerred this error. Applicable to HTTP 400 errors only.
message Detailed error message.
code Custom error code that is machine-parseable.

Error Codes

In addition to the the error message, the error response will also contain a error code that is machine-parseable. The following table lists the error codes and their descriptions.

Code Description
missing_field A mandatory attribute is missing. For example, calling Create a Contact without the mandatory email field in the request will result in this error.
invalid_value This code indicates that a request contained an incorrect or blank value, or was in an invalid format.
duplicate_value Indicates that this value already exists. This error is applicable to fields that require unique values such as the email address in a contact or the name in a company.
datatype_mismatch Indicates that the field value doesn't match the expected data type. Entering text in a numerical field would trigger this error.
invalid_field An unexpected field was part of the request. If any additional field is included in the request payload (other than what is specified in the API documentation), this error will occur.
invalid_json Request parameter is not a valid JSON. We recommend that you validate the JSON payload with a JSON validator before firing the API request.
invalid_credentials Incorrect or missing API credentials. As the name suggests, it indicates that the API request was made with invalid credentials. Forgetting to apply Base64 encoding on the API key is a common cause of this error.
access_denied Insufficient privileges to perform this action. An agent attempting to access admin APIs will result in this error.
require_feature Not allowed as a specific feature has to be enabled in your Freshdesk portal for you to perform this action.
account_suspended Account has been suspended.
ssl_required HTTPS is required in the API URL.
readonly_field Read only field cannot be altered.
inconsistent_state An email should be associated with the contact before converting the contact to an agent.
max_agents_reached The account has reached the maximum number of agents.
password_lockout The agent has reached the maximum number of failed login attempts.
password_expired The agent's password has expired.
no_content_required No JSON data required.
inaccessible_field The agent is not authorized to update this field.
incompatible_field The field cannot be updated due to the current state of the record.

Best Practices

Rate Limit
  • Whenever possible, please queue API calls at your end. This ensures that you can buffer calls on your end to avoid hitting the rate limit and retry API calls when you hit the rate limit after the retry-after time.
  • Cache non-volatile data on your end whenever it is feasible. For e.g. the mapping between agent name and ID is extremely unlikely to change. Hence, by caching it on the client side, you will be able to avoid API calls.
  • As soon as you recognise that a rate limit increase will be required in the future, contact us. This will make it possible for us to ensure that we are prepared to increase the limit as and when as it is needed.
Other
  • Avoid making API calls directly from a mobile app, rather send the request to your servers and make the API calls from there. This ensures that in the event of an API endpoint being modified, you will be able to make and deploy the change to your server rather than updating your app and forcing your users to the latest version.
  • Always use HTTP connection/multiplexing when making the API request. This will save some time while opening TCP connection to Freshdesk.
  • When retrieving a list of objects, avoid making calls referencing page numbers over 500 (deep pagination). These are performance intensive calls and you may suffer from extremely long response times.

API Index

CATEGORY CREATE VIEW VIEW LIST UPDATE DELETE OTHERS
Tickets Yes Yes Yes Yes Yes 7 more
Conversations Yes No Yes Yes* Yes
Contacts Yes Yes Yes Yes Yes 3 more
Agents Yes Yes Yes Yes Yes 1 more
Skills Yes Yes Yes Yes Yes
Roles No Yes Yes No No
Groups Yes Yes Yes Yes Yes
Companies Yes Yes Yes Yes Yes 2 more
Discussions
— Categories Yes Yes Yes Yes Yes
— Forums Yes Yes Yes Yes Yes 3 more
— Topics Yes Yes Yes Yes Yes 4 more
— Comments Yes No Yes Yes Yes
Solutions
— Categories Yes Yes Yes Yes Yes
— Folders Yes Yes Yes Yes Yes
— Solution Articles Yes Yes Yes Yes Yes
Surveys No No Yes No No
Satisfaction Ratings Yes No Yes No No
Time Entries Yes No Yes Yes Yes 1 more
Email
— Mailboxes Yes Yes Yes Yes Yes
— Settings No Yes No Yes No
— Bcc Emails No Yes No Yes No
— Email configs (old) No Yes Yes No No
Products No Yes Yes No No
Business Hours No Yes Yes No No
Settings
— Helpdesk No Yes No No No
Account No Yes Yes No No
Jobs No Yes No No
* partially supported

Tickets

A ticket is an issue raised by a requester that need to be solved. It could be an urgent, high-priority problem exposing a security vulnerability. It could also be low priority question about a free T-shirt. Tickets are assigned to agents based on the agent's expertise and on the subject of the ticket.

Attribute Type Description
attachments array of objects Ticket attachments. The total size of these attachments cannot exceed 20MB.
cc_emails array of strings Email address added in the 'cc' field of the incoming ticket email
company_id number ID of the company to which this ticket belongs
custom_fields dictionary Key value pairs containing the names and values of custom fields. Read more here
deleted boolean Set to true if the ticket has been deleted/trashed. Deleted tickets will not be displayed in any views except the "deleted" filter
description string HTML content of the ticket
description_text string Content of the ticket in plain text
due_by datetime Timestamp that denotes when the ticket is due to be resolved
email string Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact.
email_config_id number ID of email config which is used for this ticket.
(i.e., support@yourcompany.com/sales@yourcompany.com)
facebook_id string Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk.
fr_due_by datetime Timestamp that denotes when the first response is due
fr_escalated boolean Set to true if the ticket has been escalated as the result of first response time being breached
fwd_emails array of strings Email address(e)s added while forwarding a ticket
group_id number ID of the group to which the ticket has been assigned
id number Unique ID of the ticket
is_escalated boolean Set to true if the ticket has been escalated for any reason
name string Name of the requester
phone string Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory.
priority number Priority of the ticket
product_id number ID of the product to which the ticket is associated
reply_cc_emails array of strings Email address added while replying to a ticket
requester_id number User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email.
responder_id number ID of the agent to whom the ticket has been assigned
source number The channel through which the ticket was created
spam boolean Set to true if the ticket has been marked as spam
status number Status of the ticket
subject string Subject of the ticket
tags array of strings Tags that have been associated with the ticket
to_emails Array of strings Email addresses to which the ticket was originally sent
twitter_id string Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact.
type string Helps categorize the ticket according to the different kinds of issues your support team deals with.
created_at datetime Ticket creation timestamp
updated_at datetime Ticket updated timestamp

Ticket Properties

Every ticket uses certain fixed numerical values to denote its Status, and Priorities. These numerical values along with their meanings are given below.

Source Value
Email 1
Portal 2
Phone 3
Chat 7
Feedback Widget 9
Outbound Email 10
Status Value
Open 2
Pending 3
Resolved 4
Closed 5
Priority Value
Low 1
Medium 2
High 3
Urgent 4

Create a Ticket

post
/api/v2/tickets

Parameters

Attribute Type Description
name string Name of the requester
requester_id † number User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email.
email † string Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact.
facebook_id † string Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk.
phone † string Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory.
twitter_id † string Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact.
unique_external_id † string External ID of the requester. If no contact exists with this external ID in Freshdesk, they will be added as a new contact.
subject string Subject of the ticket. The default Value is null.
type string Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null.
status * number Status of the ticket. The default Value is 2.
priority * number Priority of the ticket. The default value is 1.
description string HTML content of the ticket.
responder_id number ID of the agent to whom the ticket has been assigned
attachments array of objects Ticket attachments. The total size of these attachments cannot exceed 20MB.
cc_emails array of strings Email address added in the 'cc' field of the incoming ticket email
custom_fields dictionary Key value pairs containing the names and values of custom fields. Read more here
due_by datetime Timestamp that denotes when the ticket is due to be resolved
email_config_id number ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com)
If product_id is given and email_config_id is not given, product's primary email_config_id will be set
fr_due_by datetime Timestamp that denotes when the first response is due
group_id number ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id
parent_id number ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket.
product_id number ID of the product to which the ticket is associated.
It will be ignored if the email_config_id attribute is set in the request.
source * number The channel through which the ticket was created. The default value is 2.
tags array of strings Tags that have been associated with the ticket
company_id number Company ID of the requester. This attribute can only be set if the Multiple Companies feature is enabled (Estate plan and above)
internal_agent_id Integer ID of the internal agent which the ticket should be assigned with
internal_group_id Integer ID of the internal group to which the ticket should be assigned with
lookup_parameter string This attribute for tickets can only be set if Custom Objects is enabled and a lookup field has been added under ticket fields.The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id.
* Refer Ticket properties table for supported values
† Any of the five attributes is mandatory

Ticket Properties

Every ticket uses certain fixed numerical values to denote its Source, Status, and Priorities. These numerical values along with their meanings are given below.

Source Value
Email 1
Portal 2
Phone 3
Chat 7
Feedback Widget 9
Outbound Email 10
Status Value
Open 2
Pending 3
Resolved 4
Closed 5
Priority Value
Low 1
Medium 2
High 3
Urgent 4
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{  "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : null,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 2,
  "status" : 2,
  "subject" : "Support needed..",
  "company_id" : 1,
  "id" : 1,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "Some details on the issue ...",
  "description" : "<div>Some details on the issue ..</div>",
  "tags" : [ ],
  "attachments" : [ ]
}
EXPAND ↓

Create a Ticket With Custom Fields

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

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{  "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"], "custom_fields" : { "category" : "Primary" } }' -X POST 'https://domain.freshdesk.com/api/v2/tickets'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : null,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 2,
  "status" : 2,
  "subject" : "Support needed..",
  "company_id" : 1,
  "id" : 1,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "Some details on the issue ...",
  "description" : "<div>Some details on the issue ..</div>",
  "custom_fields" : {
    "category" : "Primary"
  },
  "tags" : [ ],
  "attachments" : [ ]
}
EXPAND ↓

Create a Ticket With Custom Object record associated

Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #12345, here the primary_field_value will be “12345”

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"], "lookup_parameter" : "primary_field_value", "custom_fields" : { "cf_order_number_1" : "12345" } }' -X POST 'https://domain.freshdesk.com/api/v2/tickets'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : null,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 2,
  "status" : 2,
  "subject" : "Support needed..",
  "company_id" : 1,
  "id" : 1,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "Some details on the issue ...",
  "description" : "<div>Some details on the issue ..</div>",
  "custom_fields" : {
    "cf_order_number_1" : "12345"
  },
  "tags" : [ ],
  "attachments" : [ ] 
  }
EXPAND ↓

Create a Ticket With Attachment

Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.ext" -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -X POST 'https://domain.freshdesk.com/api/v2/tickets'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : null,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 2,
  "status" : 2,
  "subject" : "Ticket Title",
  "id" : 1,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "this is a sample ticket",
  "description" : "<div>this is a sample ticket</div>",
  "custom_fields" : {
   "category" : null
  },
  "tags" : [ ],
  "attachments":[
     {
        "id":4004881085,
        "content_type":"image/jpeg",
        "file_size":44115,
        "name":"attachment1.jpg",
        "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment.jpg"
        "created_at":"2014-07-28T16:20:03+05:30",
        "updated_at":"2014-07-28T16:20:03+05:30",
     },
     {
        "id":4004881086,
        "content_type":"image/jpeg",
        "file_size":44134,
        "name":"attachment2.jpg",
        "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment2.jpg"
        "created_at":"2014-07-28T16:20:03+05:30",
        "updated_at":"2014-07-28T16:20:03+05:30",
     }
  ]
}
EXPAND ↓

Create a Child Ticket

Note:
1. This API request must have parent_id.
2. For more information on Parent Child Ticketing refer to this section.

Additional Parameters

Attribute Type Description
parent_id integer ID of the parent ticket under which the child ticket needs to be created.
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{  "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "parent_id": 1, priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : null,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 2,
  "status" : 2,
  "subject" : "Support needed..",
  "company_id" : 1,
  "id" : 2,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "association_type" : 2,
  "associated_tickets_list" : [1]
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "Some details on the issue ...",
  "description" : "<div>Some details on the issue ..</div>",
  "tags" : [ ],
  "attachments" : [ ]
}
EXPAND ↓

Create a Tracker

Note:
1. This API request must have related_ticket_ids.
2. For more information on Linked Tickets refer to this section.

Additional Parameters

Attribute Type Description
related_ticket_ids array of integers List of Ticket IDs which needs to be linked to the Tracker being created.
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{  "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "related_ticket_ids": [1,2,3], priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : null,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 2,
  "status" : 2,
  "subject" : "Support needed..",
  "company_id" : 1,
  "id" : 5,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "association_type" : 3,
  "associated_tickets_list" : [1,2,3]
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "Some details on the issue ...",
  "description" : "<div>Some details on the issue ..</div>",
  "tags" : [ ],
  "attachments" : [ ]
}
EXPAND ↓

Create an Outbound Email

post
/api/v2/tickets/outbound_email

Note:
1. By default, the ticket will be assigned to the agent sending the email and it will be created with 'closed' status. This makes sure that SLA timers aren't running unnecessarily on an outbound ticket.
2. Unlike normal tickets, the subject and description of outbound tickets cannot be updated. More information on the difference between normal and outbound tickets can be found here

Parameters

Attribute Type Description
name string Name of the requester
email Mandatory string Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact.
subject Mandatory string Subject of the ticket. The default Value is null.
type string Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null.
status * number Status of the ticket. The default Value is 5.
priority * number Priority of the ticket. The default value is 1.
description string HTML content of the ticket.
attachments array of objects Ticket attachments. The total size of these attachments cannot exceed 20MB.
custom_fields dictionary Key value pairs containing the names and values of custom fields. Read more here
due_by datetime Timestamp that denotes when the ticket is due to be resolved
email_config_id Mandatory number ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com)
fr_due_by datetime Timestamp that denotes when the first response is due
group_id number ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id
tags array of strings Tags that have been associated with the ticket
* Refer Ticket properties table for supported values

Ticket Properties

Every ticket uses certain fixed numerical values to denote its Status, and Priorities. These numerical values along with their meanings are given below.

Status Value
Open 2
Pending 3
Resolved 4
Closed 5
Priority Value
Low 1
Medium 2
High 3
Urgent 4
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{  "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "email_config_id": 1, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets/outbound_email'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : 1,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 10,
  "status" : 2,
  "subject" : "Support needed..",
  "company_id" : 1,
  "id" : 1,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "Some details on the issue ...",
  "description" : "<div>Some details on the issue ..</div>",
  "tags" : [ ],
  "attachments" : [ ]
}
EXPAND ↓

View a Ticket

get
/api/v2/tickets/[id]

Use 'include' to embed additional details in the response. Each include will consume an additional credit. For example if you embed the requester and company information you will be charged a total of 3 API credits for the call.

Note:
By default, certain fields such as conversations, company name and requester email will not be included in the response. They can be retrieved via the embedding functionality.

Embed Handle
conversations /api/v2/tickets/[id]?include=conversations
Will return up to ten conversations sorted by "created_at" in ascending order. Including conversations will consume two API calls. In order to access more than ten conversations belonging to a ticket, use the List All Conversations of a Ticket API.
requester /api/v2/tickets/[id]?include=requester
Will return the requester's email, id, mobile, name, and phone.
company /api/v2/tickets/[id]?include=company
Will return the company's id and name.
stats /api/v2/tickets/[id]?include=stats
Will return the ticket’s closed_at, resolved_at and first_responded_at time
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/20'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "cc_emails" : ["user@cc.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["user@cc.com"],
  "email_config_id" : null,
  "fr_escalated" : false,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 1,
  "responder_id" : null,
  "source" : 2,
  "spam" : false,
  "status" : 2,
  "subject" : "",
  "company_id" : 1,
  "id" : 20,
  "type" : null,
  "to_emails" : null,
  "product_id" : null,
  "created_at" : "2015-08-24T11:56:51Z",
  "updated_at" : "2015-08-24T11:59:05Z",
  "due_by" : "2015-08-27T11:30:00Z",
  "fr_due_by" : "2015-08-25T11:30:00Z",
  "is_escalated" : false,
  "association_type" : null,
  "description_text" : "Not given.",
  "description" : "<div>Not given.</div>",
  "custom_fields" : {
    "category" : "Primary"
  },
  "tags" : [ ],
  "attachments" : [ ]
}
EXPAND ↓

Additional Examples

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

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

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

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

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

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

View a Ticket with Association

Use 'Association Type' to identify whether the ticket is a parent, child, tracker or related ticket.

Note:
1. For more information on Parent Child Ticketing refer to this section.
2. For more information on Linked Tickets refer to this section.

Ticket Properties

Every ticket uses certain fixed numerical values to denote its Association. These numerical values along with their meanings are given below.

Association Type Value
Parent 1
Child 2
Tracker 3
Related 4
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/23'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : null,
  "group_id" : null,
  "priority" : 1,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 2,
  "status" : 2,
  "subject" : "Support needed..",
  "company_id" : 1,
  "id" : 23,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "association_type" : 1,
  "associated_tickets_list" : [10,11,12]
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "Some details on the issue ...",
  "description" : "<div>Some details on the issue ..</div>",
  "tags" : [ ],
  "attachments" : [ ]
}
EXPAND ↓

Additional Information

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

  1. When association_type is 1 (Parent), it will return the list of child IDs associated with the respective parent.
  2. When association_type is 2 (Child), it will return the respective parent ticket ID.
  3. When association_type is 3 (Tracker), it will return the list of related ticket IDs associated with the respective tracker.
  4. When association_type is 4 (Related), it will return the respective tracker ticket ID.

Ticket Association API

Ticket association allows you to define the relationship between two or more tickets. You can refer to this section to know more about the APIs to create parent-child or linked tickets relationship between tickets.

Get Associated Tickets

get
/api/v2/tickets/[id]/associated_tickets
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/associated_tickets'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"tickets": [
{
"id": 44,
"group_id": 244782,
"priority": 1,
"requester_id": 50000067379,
"responder_id": 21797696,
"source": 2,
"company_id": 50000029563,
"status": 3,
"subject": "Website unresponsive",
"product_id": 18880,
"type": "L2 - Analysis",
"due_by": "2020-12-17T11:57:57Z",
"fr_due_by": "2020-12-14T01:24:43Z",
"is_escalated": false,
"created_at": "2020-12-11T22:24:43Z",
"updated_at": "2020-12-16T02:42:00Z"
}
]
}
EXPAND ↓

Get Prime Association of a Ticket

get
/api/v2/tickets/[id]/prime_association
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/44/prime_association'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"id": 20,
"group_id": 244782,
"priority": 1,
"requester_id": 50000067379,
"responder_id": 21797696,
"source": 2,
"company_id": 50000029563,
"status": 1,
"subject": "Website issue - tracker",
"product_id": 18880,
"type": "L4 - Bug",
"due_by": "2020-12-19T11:57:57Z",
"fr_due_by": "2020-12-15T01:24:43Z",
"is_escalated": false,
"created_at": "2020-12-10T20:20:43Z",
"updated_at": "2020-12-16T02:42:00Z"
}
EXPAND ↓

List All Tickets

get
/api/v2/tickets

Use filters to view only specific tickets (those which match the criteria that you choose). By default, only tickets that have not been deleted or marked as spam will be returned, unless you use the 'deleted' filter.

Note:
1. By default, only tickets that have been created within the past 30 days will be returned. For older tickets, use the updated_since filter
2. A maximum of 300 pages (30000 tickets) will be returned.
3. When using filters, the query string must be URL encoded - see example
4. Use 'include' to embed additional details in the response. Each include will consume an additional 2 credits. For example if you embed the stats information you will be charged a total of 3 API credits for the call.
5. For accounts created after 2018-11-30, you will have to use include to get description.

Filter by Handle
Predefined filters /api/v2/tickets?filter=[filter_name]
The various filters available are new_and_my_open, watching, spam, deleted.
Requester /api/v2/tickets?requester_id=[id]
/api/v2/tickets?email=[requester_email]
/api/v2/tickets?unique_external_id=[requester_unique_external_id]
Example:
/api/v2/tickets?email=superman@freshdesk.com
/api/v2/tickets?email=bat%2Bman%40gmail.com   (URL encoded bat+man@gmail.com)
Company ID /api/v2/tickets?company_id=[id]
Updated since /api/v2/tickets?updated_since=2015-01-19T02:00:00Z
Custom ticket views Check out the Filter Tickets API
Sort by Handle
created_at, due_by, updated_at, status /api/v2/tickets?order_by=created_at
Default sort order is created_at
asc, desc /api/v2/tickets?order_type=asc
Default sort order type is desc
Embed Handle
stats /api/v2/tickets?include=stats
Will return the ticket’s closed_at, resolved_at and first_responded_at time
requester /api/v2/tickets?include=requester
Will return the requester's email, id, mobile, name, and phone.
description /api/v2/tickets?include=description
Will return the ticket description and description_text.
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
[
  {
    "cc_emails" : ["user@cc.com", "user2@cc.com"],
    "fwd_emails" : [ ],
    "reply_cc_emails" : ["user@cc.com", "user2@cc.com"],
    "fr_escalated" : false,
    "spam" : false,
    "email_config_id" : null,
    "group_id" : 2,
    "priority" : 1,
    "requester_id" : 5,
    "responder_id" : 1,
    "source" : 2,
    "status" : 2,
    "subject" : "Please help",
    "to_emails" : null,
    "product_id" : null,
    "id" : 18,
    "type" : Lead,
    "created_at" : "2015-08-17T12:02:50Z",
    "updated_at" : "2015-08-17T12:02:51Z",
    "due_by" : "2015-08-20T11:30:00Z",
    "fr_due_by" : "2015-08-18T11:30:00Z",
    "is_escalated" : false,
    "custom_fields" : {
      "category" : "Default"
    }
  },
  {
    "cc_emails" : [ ],
    "fwd_emails" : [ ],
    "reply_cc_emails" : [ ],
    "fr_escalated" : false,
    "spam" : false,
    "email_config_id" : null,
    "group_id" : null,
    "priority" : 1,
    "requester_id" : 1,
    "responder_id" : null,
    "source" : 2,
    "status" : 2,
    "subject" : "",
    "to_emails" : null,
    "product_id" : null,
    "id" : 17,
    "type" : null,
    "created_at" : "2015-08-17T12:02:06Z",
    "updated_at" : "2015-08-17T12:02:07Z",
    "due_by" : "2015-08-20T11:30:00Z",
    "fr_due_by" : "2015-08-18T11:30:00Z",
    "is_escalated" : false,
    "custom_fields" : {
      "category" : null
    }
  }
]
EXPAND ↓

Additional Examples

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

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

2. Get the first page of a list of tickets that are being watched by the agent whose credentials were used to make this API call.

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

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

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

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

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

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

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

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

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

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

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

Filter Tickets

get
/api/v2/search/tickets?query=[query]

Use custom ticket fields that you have created in your account to filter through the tickets and get a list of tickets matching the specified ticket fields.

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

Note:
1. Archived tickets will not be included in the results
2. The query must be URL encoded
3. Query can be framed using the name of the ticket fields, which can be obtained from Ticket Fields endpoint. Ticket Fields are case sensitive
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
5. Logical operators AND, OR along with parentheses () can be used to group conditions
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
7. Input for date fields should be in UTC Format
8. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
9. To scroll through the pages add page parameter to the url. The page number starts with 1 and should not exceed 10
10. To filter for fields with no values assigned, use the null keyword
11. Please note that the updates will take a few minutes to get indexed, after which it will be available through API

Supported Ticket Fields

Field Type Description
agent_id integer ID of the agent to whom the ticket has been assigned
group_id integer ID of the group to which the ticket has been assigned
priority integer Priority of the ticket
status integer Status of the ticket
tag string Tag that has been associated to the tickets
type string Type of issue that has been associated to the tickets
due_by date Date (YYYY-MM-DD) when the ticket is due to be resolved
fr_due_by date Date (YYYY-MM-DD) when the first response is due
created_at date Ticket creation date (YYYY-MM-DD)
updated_at date Date (YYYY-MM-DD) when the ticket was last updated
Custom Fields
Single line text string
Number integer
Checkbox boolean
Dropdown string
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:3"'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
{
  "total":49,
  "results":[
    {
      "cc_emails":["clark.kent@kryptonspace.com"],
      "fwd_emails":[ ],
      "reply_cc_emails":[ ],
      "fr_escalated":false,
      "spam":false,
      "email_config_id":17,
      "group_id":156,
      "priority":3,
      "requester_id":6007738334,
      "responder_id":6001263404,
      "source":2,
      "company_id":2,
      "status":2,
      "subject":"Sample Title",
      "to_emails":null,
      "product_id":null,
      "id":47,
      "type":null,
      "due_by":"2016-02-23T16:00:00Z",
      "fr_due_by":"2016-02-22T17:00:00Z",
      "is_escalated":true,
      "description":"<div>Sample description</div>",
      "description_text":"Sample description",
      "created_at":"2016-02-20T09:16:58Z",
      "updated_at":"2016-02-23T16:14:57Z",
      "custom_fields":{
        "sector_no":7,
        "locked":true
      }
    },
    {
      "cc_emails":["bruce.wayne@gothamdomain.com"],
      "fwd_emails":[ ],
      "reply_cc_emails":[ ],
      "fr_escalated":true,
      "spam":false,
      "email_config_id":44,
      "group_id":65,
      "priority":3,
      "requester_id":6007738334,
      "responder_id":6001263404,
      "source":2,
      "company_id":33,
      "status":2,
      "subject":"New Title",
      "to_emails":null,
      "product_id":null,
      "id":57,
      "type":null,
      "due_by":"2016-02-23T16:00:00Z",
      "fr_due_by":"2016-02-22T17:00:00Z",
      "is_escalated":true,
      "description":"<div>New description</div>",
      "description_text":"New description",
      "created_at":"2016-02-20T16:15:10Z",
      "updated_at":"2016-03-14T15:58:13Z",
      "custom_fields":{
        "sector_no":8,
        "locked":true
      }
    },
    ...
    ...
    ...
    ...
  ]
}
EXPAND ↓

Additional Examples

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

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

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

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

3. Get the list of Urgent and High priority tickets in Open Status belong to the group_id 11.
    "priority:>3 AND group_id:11 AND status:2"

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

4. Get the list of locked tickets belong to Finance or Marketing sector (Custom Fields: locked, sector).
    "(cf_sector:'finance' OR cf_sector:'marketing') AND cf_locked:true"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="(cf_sector:%27finance%27%20OR%20cf_sector:%27marketing%27)%20AND%20cf_locked:true"'
EXPAND ↓

If you’re not getting a result for the above query, there’s a chance that the field might have been created recently or it has been moved to a new infrastructure. To query on these custom fields, use ‘custom_string’ instead of the actual field label.

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

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

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

6. Get the list of tickets whose type is 'Question' or 'Problem' and response due on first week of October 2017.
    "(type:'Question' OR type:'Problem') AND (due_by:>'2017-10-01' AND due_by:<'2017-10-07')"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="(type:%27Question%27%20OR%20type:%27Problem%27)%20AND%20(due_by:>%272017-10-01%27%20AND%20due_by:<%272017-10-07%27)"'
EXPAND ↓

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

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

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

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

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

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

10. Get the list of urgent tickets assigned to agents whose ids are 2 and 3.
    "(agent_id:2 OR agent_id:3) AND priority:4"

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

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

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

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

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

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

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

Update a Ticket

put
/api/v2/tickets/[id]

Note:
Unlike normal tickets, the subject and description of outbound tickets cannot be updated. More information on the difference between normal and outbound tickets can be found here

Parameters

Attribute Type Description
name string Name of the requester
requester_id number User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email.
email string Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact.
facebook_id string Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk.
phone string Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory.
twitter_id string Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact.
unique_external_id string External ID of the requester. If no contact exists with this external ID in Freshdesk, they will be added as a new contact.
subject string Subject of the ticket. The default Value is null.
type string Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null.
status * number Status of the ticket. The default Value is 2.
priority * number Priority of the ticket. The default value is 1.
description string HTML content of the ticket.
responder_id number ID of the agent to whom the ticket has been assigned
attachments array of objects Ticket attachments. The total size of these attachments cannot exceed 20MB.
custom_fields dictionary Key value pairs containing the names and values of custom fields. Read more here
due_by datetime Timestamp that denotes when the ticket is due to be resolved
email_config_id number ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com)
If the product_id is changed and the current email_config_id doesn't belong to that product, then this value will be automatically updated to the selected product's primary email_config_id
fr_due_by datetime Timestamp that denotes when the first response is due
group_id number ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id
parent_id number ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket.
product_id number ID of the product to which the ticket is associated.
source * number The channel through which the ticket was created. The default value is 2.
tags array of strings Tags that have been associated with the ticket
company_id number Company ID of the requester. This attribute can only be updated if the Multiple Companies feature is enabled (Estate plan and above)
internal_agent_id Integer ID of the internal agent which the ticket should be assigned with
internal_group_id Integer ID of the internal group to which the ticket should be assigned with
lookup_parameter string This attribute for tickets can only be set if Custom Objects is enabled and a lookup field has been added under ticket fields.The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id.
* Refer Ticket properties table for supported values

Ticket Properties

Every ticket uses certain fixed numerical values to denote its Source, Status, and Priorities. These numerical values along with their meanings are given below.

Source Value
Email 1
Portal 2
Phone 3
Chat 7
Feedback Widget 9
Outbound Email 10
Status Value
Open 2
Pending 3
Resolved 4
Closed 5
Priority Value
Low 1
Medium 2
High 3
Urgent 4
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "priority":2, "status":3 }' 'https://domain.freshdesk.com/api/v2/tickets/1'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "cc_emails" : [ ],
  "fwd_emails" : [ ],
  "reply_cc_emails" : [ ],
  "description_text" : "Not given.",
  "description" : "<div>Not given.</div>",
  "spam" : false,
  "email_config_id" : null,
  "fr_escalated" : false,
  "group_id" : null,
  "priority" : 2,
  "requester_id" : 1,
  "responder_id" : null,
  "source" : 3,
  "status" : 3,
  "subject" : "",
  "id" : 20,
  "type" : null,
  "to_emails" : null,
  "product_id" : null,
  "attachments" : [ ],
  "is_escalated" : false,
  "tags" : [ ],
  "created_at" : "2015-08-24T11:56:51Z",
  "updated_at" : "2015-08-24T11:59:05Z",
  "due_by" : "2015-08-27T11:30:00Z",
  "fr_due_by" : "2015-08-25T11:30:00Z"
}
EXPAND ↓

Update the lookup field within a ticket

Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #98765, here the primary_field_value will be “98765”

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "priority":2, "status":3, "lookup_parameter" : "primary_field_value", "custom_fields" : { "cf_order_number_1" : "98765" } }' 'https://domain.freshdesk.com/api/v2/tickets/1'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "fwd_emails" : [ ],
  "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"],
  "email_config_id" : null,
  "group_id" : null,
  "priority" : 2,
  "requester_id" : 129,
  "responder_id" : null,
  "source" : 2,
  "status" : 3,
  "subject" : "Support needed..",
  "company_id" : 1,
  "id" : 1,
  "type" : "Question",
  "to_emails" : null,
  "product_id" : null,
  "fr_escalated" : false,
  "spam" : false,
  "urgent" : false,
  "is_escalated" : false,
  "created_at" : "2015-07-09T13:08:06Z",
  "updated_at" : "2015-07-23T04:41:12Z",
  "due_by" : "2015-07-14T13:08:06Z",
  "fr_due_by" : "2015-07-10T13:08:06Z",
  "description_text" : "Some details on the issue ...",
  "description" : "<div>Some details on the issue ..</div>",
  "custom_fields" : {
    "cf_order_number_1" : "98765"
  },
  "tags" : [ ],
  "attachments" : [ ]
}
EXPAND ↓

Update Multiple Tickets

post
/api/v2/tickets/bulk_update

Note:
To update the internal group or internal agent of a ticket, the API request must also include status value

Attribute Type Description
ids Mandatory Array of numbers IDs of tickets to be updated

For bulk replies:
Attribute Type Description
body string Content of the reply to be added to the tickets
attachment_ids Array of numbers IDs of attachments to be added to the reply
inline_attachment_ids Array of numbers IDs of inline attachments to be added to the reply
cloud_files Array of objects Cloud attachments to be added to the reply

For bulk update of properties:
Attribute Type Description
from_email string Support email from which the reply should be sent
skip_close_notification boolean Used to skip email notifications sent to requesters on closing a ticket
email_config_id Integer Support email config on the ticket. Will be used for corresponding responses on the ticket
group_id Integer ID of the group to be assigned on the ticket
priority Integer Used to set the priority of the ticket. Possible values are 1,2,3,4
parent_id Integer ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket.
requester_id Integer ID of the requester on the ticket
responder_id Integer ID of the agent to be assigned on the ticket
source Integer Used to set the source of the ticket. Possible values are 1, 2,3,7,8,9,10
status Integer Used to set the status of the ticket. Possible values are 2,3,4,5,6,7
type String Type of the ticket.
product_id Integer ID of the product to be associated with the ticket
due_by date-time Timestamp that denotes when the ticket is due to be resolved
fr_due_by date-time Timestamp that denotes when the first response is due
custom_fields dictionary Key value pairs containing the names and values of custom fields. Read more here
tags Array of strings Tags that have been associated with the ticket
internal_agent_id Integer ID of the internal agent which the ticket should be assigned with
internal_group_id Integer ID of the internal group to which the ticket should be assigned with
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"bulk_action": {"ids": [20,21,22],"properties":{"from_email":"support@freshdesk.com","status":2,"group_id":1234,"type":"Question","priority":4},"reply":{"body":"Please check this ticket"}}}' 'https://domain.freshdesk.com/api/v2/tickets/bulk_update'
EXPAND ↓
Response 
1
2
3
4
{ 
"job_id": "e4d18654f60b5204513155b26c6cb",
 "href":"https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb"
 }
EXPAND ↓

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

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

Forward a ticket

post
/api/v2/tickets/[id]/forward

Forward your tickets to an external email address. You can also reply to the forwarded emails using the Reply to Forward API.

Attribute Type Description
body Mandatory string Content of the note in HTML format
body_text string Content of the note in plain text
id integer ID of the forwarded note
incoming boolean Set to true if a particular conversation should appear as being created from outside (i.e., not through web portal)
private boolean Set to true if the note is private
agent_id number ID of the agent/user who is forwarding the ticket
support_email string Email address from which the ticket is forwarded. For notes, this value will be null.
source number Denotes the type of the conversation.
ticket_id number ID of the ticket which gets forwarded
include_quoted_text boolean Include the quoted text conversations in the forwarded email. The default value is True.
include_original_attachments boolean Include the ticket attachments in the forwarded email. The default value is True.
from_email string The email address from which the forward is sent. By default the global support email will be used.
to_emails Mandatory array of strings Emails to which the ticket gets forwarded
cc_emails array of strings Email address added in the 'cc' field of the outgoing forward email.
bcc_emails array of strings Email address added in the 'bcc' field of the outgoing forward email.
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X  -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "to_emails": ["user@company.com"]}' 'https://domain.freshdesk.com/api/v2/tickets/3/forward'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "body":"<div>Hi tom, Still Angry</div>",
  "body_text":"Hi tom, Still Angry",
  "id":35131396111,
  "incoming":false,
  "private":true,
  "user_id":35008297863,
  "support_email":"support@domain.freshdesk.com",
  "source":8,
  "category":2,
  "ticket_id":3,
  "to_emails":["user@company..com"],
  "from_email":"\"Agent Bob\" <support@domain.freshdesk.com>",
  "cc_emails":[],
  "bcc_emails":[],
  "email_failure_count":null,
  "outgoing_failures":null,
  "created_at":"2020-08-24T05:53:09Z",
  "updated_at":"2020-08-24T05:53:09Z",
  "attachments":[],
  "deleted":false,
  "last_edited_at":null,
  "last_edited_user_id":null,
  "cloud_files":[],
  "has_quoted_text":true
}
EXPAND ↓

Ticket Merge API

Sometimes, a customer might try to get your attention regarding a particular issue by contacting you through separate channels. Sometimes, the same issue might be reported by different people in the team or someone might accidentally open a new ticket instead of following up on an existing one. To avoid conflicts, you can merge all related tickets together and keep the communication streamlined.

Attribute Type Description
primary_id integer Ticket to which conversations from secondary tickets will be merged
ticket_ids Array of numbers IDs of tickets to be merged
note_in_primary hash This contains the note added to the primary ticket along with the type of the note (public/private). A default note gets added if this is not specified in the request
note_in_secondary hash This contains the note added to the secondary tickets along with the type of the note (public/private). A default note gets added if this is not specified in the request
convert_recepients_to_cc boolean This will add recipients from secondary tickets in CC of the primary ticket
put
/api/v2/tickets/merge
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{"primary_id":20,"ticket_ids":[20,21,22],"convert_recepients_to_cc":true,"note_in_primary":{"body":"Sample note","private":true}}' 'https://domain.freshdesk.com/api/v2/tickets/merge
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Watcher

Using Watcher, you can follow the progress of a ticket even when it is not assigned to you. You can become a watcher of that ticket so that whenever there’s some update (like ticket reply or status change), you’ll receive an email notification.

Attribute Type Description
ids Mandatory array of numbers IDs of tickets for which the watcher should be updated
user_id Mandatory integer ID of the agent to be added/removed as a watcher on the ticket
watcher_ids array of numbers IDs of agents who’ve been added as watchers on the ticket

List all watchers

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

Add watcher

post
/api/v2/tickets/[id]/watch

Parameters

Attribute Type Description
user_idMandatory integer ID of the agent to be added as a watcher on the ticket
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{"user_id":35010088657}' -X POST 'https://domain.freshdesk.com/api/v2/tickets/569/watch'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Remove watcher

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

Add watcher to multiple tickets

put
/api/v2/tickets/bulk_watch

Parameters

Attribute Type Description
idsMandatory array of numbers IDs of tickets for which the watcher should be updated
user_id integer ID of the agent to be added as a watcher on the ticket
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{"ids":[560,561],"user_id":35014948467}' -X PUT 'https://domain.freshdesk.com/api/v2/tickets/bulk_watch'
EXPAND ↓
Response 
1
HTTP Status: 204 No Content
EXPAND ↓

Remove watcher from multiple tickets

put
/api/v2/tickets/bulk_unwatch

Parameters

Attribute Type Description
idsMandatory array of numbers ID's of tickets for which the watcher should be removed

Note:
So for this API we will not be passing any user_id by default it takes the user_id of the current user who is logged in and it uses only id's to remove the watcher of existing user and currently we haven't implemented it for other agents to pass their user_id and do bulk remove action.

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

Delete a Ticket

delete
/api/v2/tickets/[id]

Note:
Rest assured. When deleted, tickets are not cast into the fiery volcanoes of Mount Doom. You can retrieve them using the Restore Ticket API.

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

Delete Multiple Tickets

post
/api/v2/tickets/bulk_delete
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"bulk_action": {"ids": [20,21,22]}}' 'https://domain.freshdesk.com/api/v2/tickets/bulk_delete'
EXPAND ↓
Response 
1
2
3
4
{ 
"job_id": "e4d18654f60b5204513155b26c6cb630",
 "href":"https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb630"
 }
EXPAND ↓

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

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

Delete an attachment

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

Restore a Ticket

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

List All Ticket Fields

get
/api/v2/ticket_fields

Note:
The agent whose credentials (identified by the API key) are used to make the API call should be authorised to either view the ticket fields or create a new ticket

Ticket Fields
Ticket Field Description
id ID of the ticket field
default Set to true if the field is not a custom field
description Description of the ticket field
label Display name for the field (as seen by agents)
name Name of the ticket field
position Position in which the ticket field is displayed in the form
required_for_closure Set to true if the field is mandatory for closing the ticket
type For custom ticket fields, type of value associated with the field will be given (Examples custom_date, custom_text...)
required_for_agents Set to true if the field is mandatory for Agents
required_for_customers Set to true if the field is mandatory in the customer portal
label_for_customers Display name for the field (as seen in the customer portal)
customers_can_edit Set to true if the field can be updated by customers
displayed_to_customers Set to true if the field is displayed in the customer portal
portal_cc Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket
portal_cc_to Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list
choices List of values supported by the field
nested_ticket_fields Applicable only for dependent fields, this contain details of nested fields (see the sample response given below)

To view only specific ticket fields (that is, those which match only the criteria you choose) use the filters given below.

Filter by Handle
type /api/v2/ticket_fields?type=[type]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket_fields'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
[
  {
    "id" : 1,
    "description" : "Ticket requester",
    "label" : "Search a requester",
    "name" : "requester",
    "position" : 1,
    "portal_cc" : false,
    "portal_cc_to" : "company",
    "type" : "default_requester",
    "label_for_customers" : "Requester",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : true,
    "required_for_customers" : true,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2014-11-30T09:10:02Z",
    "updated_at" : "2014-12-17T11:58:08Z"
  },
  {
    "id" : 19,
    "description" : "",
    "label" : "Rating",
    "name" : "rating",
    "position" : 2,
    "type" : "custom_decimal",
    "label_for_customers" : "Rating",
    "default" : false,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2015-06-16T14:06:48Z",
    "updated_at" : "2015-06-16T14:06:51Z"
  },
  {
    "id" : 20,
    "description" : "",
    "label" : "regional_id",
    "name" : "regional_id",
    "position" : 3,
    "type" : "custom_number",
    "label_for_customers" : "regional_id",
    "default" : false,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2015-06-16T14:06:52Z",
    "updated_at" : "2015-06-16T14:06:53Z"
  },
  {
    "id" : 18,
    "description" : "",
    "label" : "customer_priority",
    "name" : "customer_priority",
    "position" : 4,
    "type" : "custom_dropdown",
    "label_for_customers" : "customer_priority",
    "default" : false,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2015-06-15T11:45:55Z",
    "updated_at" : "2015-06-16T14:06:54Z",
    "choices" : [
      "1st",
      "2nd"
    ]
  },
  {
    "id" : 21,
    "description" : "",
    "label" : "country",
    "name" : "country",
    "position" : 5,
    "type" : "nested_field",
    "label_for_customers" : "country",
    "default" : false,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2015-06-17T05:44:15Z",
    "updated_at" : "2015-06-17T05:44:16Z",
    "choices" : [
      {
        "usa" : [
          {
            "texas" : [
              "citytexas1"
            ]
          },
          {
            "washington" : [
              "dc",
              "seatle"
            ]
          },
          {
            "newyork" : [
              "manhattan",
              "boston"
            ]
          }
        ]
      },
      {
        "india" : [
          {
            "tamilnadu" : [
              "chennai",
              "trichy",
              "kovai",
              "madhurai"
            ]
          },
          {
            "kerala" : [
              "ernakulam",
              "kochin",
              "trivandrum"
            ]
          },
          {
            "gujarat" : [
              "allahabad",
              "gandhinagar"
            ]
          }
        ]
      }
    ],
    "nested_ticket_fields" : [
      {
        "description" : "",
        "id" : 3,
        "label" : "state",
        "label_in_portal" : "state",
        "level" : 2,
        "name" : "state",
        "ticket_field_id" : 21,
        "created_at" : "2015-06-17T05:44:16Z",
        "updated_at" : "2015-06-17T05:44:16Z"
      },
      {
        "description" : "",
        "id" : 4,
        "label" : "city",
        "label_in_portal" : "city",
        "level" : 3,
        "name" : "city",
        "ticket_field_id" : 21,
        "created_at" : "2015-06-17T05:44:16Z",
        "updated_at" : "2015-06-17T05:44:16Z"
      }
    ]
  },
  {
    "id" : 14,
    "description" : "",
    "label" : "internal_issue",
    "name" : "internal_issue",
    "position" : 6,
    "type" : "custom_checkbox",
    "label_for_customers" : "internal_issue",
    "default" : false,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2015-06-15T11:40:12Z",
    "updated_at" : "2015-06-17T05:44:16Z"
  },
  {
    "id" : 13,
    "description" : "",
    "label" : "department",
    "name" : "department",
    "position" : 8,
    "type" : "custom_text",
    "label_for_customers" : "department",
    "default" : false,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2015-05-11T11:03:28Z",
    "updated_at" : "2015-06-17T05:44:17Z"
  },
  {
    "id" : 2,
    "description" : "Ticket subject",
    "label" : "Subject",
    "name" : "subject",
    "position" : 10,
    "type" : "default_subject",
    "label_for_customers" : "Subject",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : true,
    "required_for_customers" : true,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2014-11-30T09:10:02Z",
    "updated_at" : "2015-06-17T05:44:18Z"
  },
  {
    "id" : 3,
    "description" : "Ticket type",
    "label" : "Type",
    "name" : "ticket_type",
    "position" : 11,
    "type" : "default_ticket_type",
    "label_for_customers" : "Type",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : false,
    "displayed_to_customers" : false,
    "created_at" : "2014-11-30T09:10:02Z",
    "updated_at" : "2015-06-17T05:44:18Z",
    "choices" : [
      "Question",
      "Incident",
      "Problem",
      "Feature Request",
      "Lead"
    ]
  },
  {
    "id" : 4,
    "description" : "Ticket source",
    "label" : "Source",
    "name" : "source",
    "position" : 12,
    "type" : "default_source",
    "label_for_customers" : "Source",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : false,
    "displayed_to_customers" : false,
    "created_at" : "2014-11-30T09:10:02Z",
    "updated_at" : "2015-06-17T05:44:19Z",
    "choices" : {
      "Email" : 1,
      "Portal" : 2,
      "Phone" : 3,
      "Forum" : 4,
      "Twitter" : 5,
      "Facebook" : 6,
      "Chat" : 7,
      "Feedback Widget" : 9
    }
  },
  {
    "id" : 5,
    "description" : "Ticket status",
    "label" : "Status",
    "name" : "status",
    "position" : 13,
    "type" : "default_status",
    "label_for_customers" : "Status",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : true,
    "required_for_customers" : false,
    "customers_can_edit" : false,
    "displayed_to_customers" : true,
    "created_at" : "2014-11-30T09:10:02Z",
    "updated_at" : "2015-06-17T05:44:19Z",
    "choices" : {
      "2" : [
        "Open",
        "Being Processed"
      ],
      "3" : [
        "Pending",
        "Awaiting your Reply"
      ],
      "4" : [
        "Resolved",
        "This ticket has been Resolved"
      ],
      "5" : [
        "Closed",
        "This ticket has been Closed"
      ],
      "6" : [
        "Waiting on Customer",
        "Awaiting your Reply"
      ],
      "7" : [
        "Waiting on Third Party",
        "Being Processed"
      ]
    }
  },
  {
    "id" : 6,
    "description" : "Ticket priority",
    "label" : "Priority",
    "name" : "priority",
    "position" : 14,
    "type" : "default_priority",
    "label_for_customers" : "Priority",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : true,
    "required_for_customers" : false,
    "customers_can_edit" : false,
    "displayed_to_customers" : false,
    "created_at" : "2014-11-30T09:10:02Z",
    "updated_at" : "2015-06-17T05:44:19Z",
    "choices" : {
      "Low" : 1,
      "Medium" : 2,
      "High" : 3,
      "Urgent" : 4
    }
  },
  {
    "id" : 7,
    "description" : "Ticket group",
    "label" : "Group",
    "name" : "group",
    "position" : 15,
    "type" : "default_group",
    "label_for_customers" : "Group",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : false,
    "displayed_to_customers" : false,
    "created_at" : "2014-11-30T09:10:02Z",
    "updated_at" : "2015-06-17T05:44:20Z",
    "choices" : {
      "Entertainment" : 4,
      "Product Management" : 1,
      "QA" : 2,
      "Sales" : 3,
      "vcxvxcvc" : 5
    }
  },
  {
    "id" : 8,
    "description" : "Agent",
    "label" : "Agent",
    "name" : "agent",
    "position" : 16,
    "type" : "default_agent",
    "label_for_customers" : "Assigned to",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : false,
    "displayed_to_customers" : true,
    "created_at" : "2014-11-30T09:10:03Z",
    "updated_at" : "2015-06-17T05:44:20Z",
    "choices" : {
      "fggfg" : 30,
      "Rt" : 31,
      "Super Man" : 32,
      "SuperThreefour" : 7,
      "superyu" : 5,
      "Support" : 1
    }
  },
  {
    "id" : 9,
    "description" : "Select the product, the ticket belongs to.",
    "label" : "Product",
    "name" : "product",
    "position" : 16,
    "type" : "default_product",
    "label_for_customers" : "Product",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : false,
    "required_for_customers" : false,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2014-11-30T09:10:03Z",
    "updated_at" : "2014-11-30T09:10:03Z",
    "choices" : {
      "ddd" : 1
    }
  },
  {
    "id" : 10,
    "description" : "Ticket description",
    "label" : "Description",
    "name" : "description",
    "position" : 17,
    "type" : "default_description",
    "label_for_customers" : "Description",
    "default" : true,
    "required_for_closure" : false,
    "required_for_agents" : true,
    "required_for_customers" : true,
    "customers_can_edit" : true,
    "displayed_to_customers" : true,
    "created_at" : "2014-11-30T09:10:03Z",
    "updated_at" : "2015-06-17T05:44:20Z"
  }
]
EXPAND ↓

Additional Examples

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

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

List All Conversations of a Ticket

get
/api/v2/tickets/[id]/conversations
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/conversations'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
  {
    "body_text" : "Please reply as soon as possible.",
    "body" : "<div>Please reply as soon as possible.</div>",
    "id" : 3,
    "incoming" : false,
    "private" : true,
    "user_id" : 1,
    "support_email" : null,
    "source" : 2,
    "ticket_id" : 20,
    "created_at" : "2015-08-24T11:59:05Z",
    "updated_at" : "2015-08-24T11:59:05Z",
    "from_email" : "agent2@yourcompany.com",
    "to_emails" : ["agent1@yourcompany.com"],
    "cc_emails": ["example@ccemail.com"],
    "bcc_emails": ["example@bccemail.com"],
    "attachments" : [ ],
    "last_edited_at" : "2015-08-24T11:59:59Z",
    "last_edited_user_id" : 2
  }
]
EXPAND ↓

Additional Examples

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

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

List All Time Entries of a Ticket

get
/api/v2/tickets/[id]/time_entries
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json"  -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
  {
    "billable" : true,
    "note" : null,
    "timer_running" : true,
    "id" : 1,
    "agent_id" : 1,
    "ticket_id" : 20,
    "time_spent" : "00:00",
    "created_at" : "2015-08-24T13:21:50Z",
    "updated_at" : "2015-08-24T13:21:50Z",
    "executed_at" : "2015-08-24T13:21:49Z",
    "start_time" : "2015-08-24T13:21:49Z"
  }
]
EXPAND ↓

Additional Examples

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

List All Satisfaction Ratings of a Ticket

get
/api/v2/tickets/[ticket_id]/satisfaction_ratings
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/[ticket_id]/satisfaction_ratings'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
[
    {
        "id": 102,
        "survey_id": 1,
        "user_id": 2,
        "agent_id": 1,
        "feedback": "Thank you for the quick action",
        "group_id": null,
        "ticket_id": 432,
        "ratings":{
            "default_question":103,
            "question_2":-102
        },
        "created_at": "2015-08-28T09:08:16Z",
        "updated_at": "2015-08-28T09:08:16Z"
    },
    {
        "id": 112,
        "survey_id": 1,
        "user_id": 2,
        "agent_id": 1,
        "feedback": "Thank you for the support",
        "group_id": null,
        "ticket_id": 432,
        "ratings":{
            "default_question":101
        },
        "created_at": "2015-08-28T010:08:16Z",
        "updated_at": "2015-08-28T011:08:16Z"
    }
]
EXPAND ↓

Ticket Summary

The Summary feature can be used to let agents from other groups/teams know:
  • Progress on the ticket so far and
  • Important information that has been repeatedly referenced

This adds a section below the ticket description, the section can be used to summarize everything the support team or support agent knows about a ticket before they assign the ticket they worked on to another team. This is available from the Blossom plan. You can read more details about ticket summary here.

View Summary

get
/api/v2/tickets/[id]/summary
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/summary'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"body": "<div dir=\"ltr\">Test summary</div>",
"body_text": "Test summary",
"id": 82007772826,
"user_id": 82002117631,
"ticket_id": 20,
"created_at": "2020-12-16T07:15:03Z",
"updated_at": "2020-12-16T07:15:03Z",
"attachments": [],
"last_edited_at": null,
"last_edited_user_id": null,
"cloud_files": []
}
EXPAND ↓

Update Summary

put
/api/v2/tickets/[id]/summary
Attribute Type Description
bodyMandatory integer Content of the summary note in HTML
attachments Array of files Attachments to be added to the summary note
user_id integer Id of the user who creates the summary note
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{"body":"Updated summary"}' 'https://domain.freshdesk.com/api/v2/tickets/20/summary'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"body": "<div dir=\"ltr\">Updated summary</div>",
"body_text": "Updated summary",
"id": 82007772826,
"user_id": 82002117631,
"ticket_id": 20,
"created_at": "2020-12-16T07:15:03Z",
"updated_at": "2020-12-16T07:25:00Z",
"attachments": [],
"last_edited_at":"2020-12-16T07:25:00Z",
"last_edited_user_id": 82002117631,
"cloud_files": []
}
EXPAND ↓

Delete Summary

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

Archive Tickets

In order to enhance the performance of your helpdesk, Freshdesk will archive closed, inactive tickets. This way, every time the helpdesk pulls up ticket count and other ticket properties, old and irrelevant tickets will be excluded making the process quicker and more efficient.

Depending on the company's ticket traffic, any 'closed' ticket that has been inactive for 120 days will be archived. Read more about ticket archiving here: https://support.freshdesk.com/en/support/solutions/articles/212901-ticket-archiving

View an Archive Ticket

get
/api/v2/tickets/archived/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X  -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/archived/40'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{ 
"cc_emails" : ["user@cc.com"],
 "fwd_emails" : [ ],
 "reply_cc_emails" : ["user@cc.com"], 
"email_config_id" : null, 
"fr_escalated" : false,
 "group_id" : null, 
"priority" : 1, 
"requester_id" : 1, 
"responder_id" : null, 
"source" : 2, 
"spam" : false, 
"status" : 5, 
"subject" : "", 
"company_id" : 1, 
"id" : 40,
 "type" : null, 
"to_emails" : null, 
"product_id" : null,
 "created_at" : "2015-08-24T11:56:51Z", 
"updated_at" : "2015-08-24T11:59:05Z", 
"due_by" : "2015-08-27T11:30:00Z", 
"fr_due_by" : "2015-08-25T11:30:00Z", 
"is_escalated" : false, 
"association_type" : null, 
"description_text" : "Not given.", 
"description" : "<div>Not given.</div>", 
"custom_fields" : { "category" : "Primary" },
 "tags" : [ ],
 "archived" : true,
 "attachments" : [ ]
 }
EXPAND ↓

Delete an Archive Ticket

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

List All Conversations of an Archive Ticket

get
/api/v2/tickets/archived/[id]/conversations
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/archived/20/conversations'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[ 
{
 "body_text" : "Please reply as soon as possible.", 
"body" : "<div>Please reply as soon as possible.</div>", 
"id" : 3, 
"incoming" : false, 
"private" : true, 
"user_id" : 1, 
"support_email" : null, 
"source" : 2, 
"ticket_id" : 20,
 "created_at" : "2015-08-24T11:59:05Z", 
"updated_at" : "2015-08-24T11:59:05Z", 
"from_email" : "agent2@yourcompany.com",
 "to_emails" : ["agent1@yourcompany.com"], 
"cc_emails": ["example@ccemail.com"],
 "bcc_emails": ["example@bccemail.com"], 
"attachments" : [ ] 
}
 ]
EXPAND ↓

Ticket User Access

Helps provide agents/collaborators access to a ticket based on a condition. For example: You can use the API to provide ticket access to the person who is raising a ticket or given the access to a ticket to anyone who has added a note on the ticket

Attribute Type Description
user_ids array of numbers IDs of users who have access to a particular ticket

Add Ticket User Access

post
/api/v2/tickets/[id]/accesses

Parameters

Attribute Type Description
user_ids Mandatory array of numbers List of User IDs for whom ticket access should be provided
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -d '{ "user_ids": [ 1, 2 ] }' -H "Content-Type: application/json" -X POST 'https://domain.freshdesk.com/api/v2/tickets/1/accesses'
EXPAND ↓
Response 
1
2
3
{
  "user_ids": [ 1, 2]
}
EXPAND ↓

Update Ticket User Access

patch
/api/v2/tickets/[id]/accesses

Parameters

Attribute Type Description
user_ids Mandatory array of objects Array of object type : { id: integer, deleted: boolean }, where id is the user id of the user and deleted indicates whether to remove access for this user or not
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
curl -v -u yourapikey:X -d '{
  "user_ids": [
    {
      "id": 2,
      "deleted": true
    },
    {
      "id": 3
    }
  ]
}
' -H "Content-Type: application/json" -X PATCH 'https://domain.freshdesk.com/api/v2/tickets/1/accesses'
EXPAND ↓
Response 
1
2
3
{
  "user_ids": [ 1, 3]
}
EXPAND ↓

Get Ticket User Access

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

Remove Ticket User Access

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

Ticket Fields

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

The custom and default ticket fields in Freshdesk have the following properties.

JSON Parameters
Ticket Field Description
id ID of the ticket field
default Set to true if the field is not a custom field
description Description of the ticket field
label Display name for the field (as seen by agents)
name Name of the ticket field
position Position in which the ticket field is displayed in the form
required_for_closure Set to true if the field is mandatory for closing the ticket
type For custom ticket fields, The type of value associated with the field will be given (Examples custom_date, custom_text...)
required_for_agents Set to true if the field is mandatory for Agents
required_for_customers Set to true if the field is mandatory in the customer portal
label_for_customers Display name for the field (as seen in the customer portal)
customers_can_edit Set to true if the field can be updated by customers
displayed_to_customers Set to true if the field is displayed in the customer portal
portal_cc Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket
portal_cc_to Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list
choices List of values supported by the field
is_fsm True if the Ticket field is inside FSM section (Applicable only if FSM is enabled)
field_update_in_progress True if the choice update is in progress (Applicable for the fields which has 100+ choices)
dependent_fields Applicable only for dependent fields, this contains details of nested fields (see the sample response given below)
section_mappings Applicable only if the field is part of a section. This contains section ID and position of the ticket field in the section

List All Ticket Fields

get
/api/v2/admin/ticket_fields

To view all ticket field details, use this API.

Sample code | Curl
Copied Copy 
1
2
3
4
5
# All Ticket Fields
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields'

# All Ticket Fields with section mapping
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields?include=section'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
# All Ticket Fields
[ 
   { 
      "id":21,
      "name":"cf_issue_type",
      "label":"Issue Type",
      "label_for_customers":"Issue Type",
      "position":1,
      "type":"custom_dropdown",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2019-12-16T09:35:26Z",
      "updated_at":"2019-12-16T09:35:27Z"
   },
   { 
      "id":20,
      "name":"cf_product_category",
      "label":"Product Category",
      "label_for_customers":"Product Category",
      "position":3,
      "type":"custom_dropdown",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2019-12-16T07:12:07Z",
      "updated_at":"2019-12-16T09:35:26Z",
      "has_section":true
   },
   { 
      "id":19,
      "name":"cf_subject",
      "label":"Subject",
      "label_for_customers":"Subject",
      "position":4,
      "type":"custom_text",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2019-12-11T12:10:46Z",
      "updated_at":"2019-12-16T09:35:26Z",
      "section_mappings":[ 
         { 
            "section_id":3,
            "position":1
         }
      ]
   },
   { 
      "id":12,
      "name":"cf_duplicate",
      "label":"Duplicate",
      "label_for_customers":"Duplicate",
      "position":5,
      "type":"custom_checkbox",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2019-12-03T12:23:58Z",
      "updated_at":"2019-12-16T09:35:26Z"
   }
]

# Ticket Fields with section mapping
[ 
   { 
      "id":21,
      "name":"cf_issue_type",
      "label":"Issue Type",
      "label_for_customers":"Issue Type",
      "position":1,
      "type":"custom_dropdown",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2019-12-16T09:35:26Z",
      "updated_at":"2019-12-16T09:35:27Z",
      "section_mappings": [
         {
            "section_id": 1,
            "position": 1
         }
      ]
   },
   { 
      "id":20,
      "name":"cf_product_category",
      "label":"Product Category",
      "label_for_customers":"Product Category",
      "position":3,
      "type":"custom_dropdown",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2019-12-16T07:12:07Z",
      "updated_at":"2019-12-16T09:35:26Z",
      "has_section":true,
      "sections": [
         {
            "id": 1,
            "label": "Ecosystem Type",
            "parent_ticket_field_id": 12,
            "choice_ids": [
               6
            ],
            "ticket_field_ids": [
               17,
               18,
               27
            ]
         }
      ]
   },
   { 
      "id":19,
      "name":"cf_subject",
      "label":"Subject",
      "label_for_customers":"Subject",
      "position":4,
      "type":"custom_text",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2019-12-11T12:10:46Z",
      "updated_at":"2019-12-16T09:35:26Z",
      "section_mappings":[ 
         { 
            "section_id":3,
            "position":1
         }
      ]
   },
   { 
      "id":12,
      "name":"cf_duplicate",
      "label":"Duplicate",
      "label_for_customers":"Duplicate",
      "position":5,
      "type":"custom_checkbox",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2019-12-03T12:23:58Z",
      "updated_at":"2019-12-16T09:35:26Z"
   }
]
EXPAND ↓

Create a Ticket Field

post
/api/v2/admin/ticket_fields

To create a new ticket field, use the following APIs.

JSON Parameters

Attribute Type Description
customers_can_edit boolean To specify whether the customer can edit the ticket field
label_for_customers string Ticket Field name to be displayed to customers
displayed_to_customers boolean Display Ticket Field to customers
label string Display the name of the Ticket Field
type string Ticket Field type. Can be custom_dropdown, custom_checkbox, custom_text, etc...
position number Position in which the ticket field is displayed in the form. If not given, it will be displayed on top
required_for_closure boolean Set to true if the field is mandatory for closing the ticket
required_for_agents boolean Set to true if the field is mandatory for Agents
required_for_customers boolean Set to true if the field is mandatory in the customer portal
choices (Applicable for dropdown) Array of dictionary Array of key, value pairs containing the value and position of dropdown choices
dependent_fields Array of dictionary Applicable only for dependent fields, this contains details of nested fields
section_mappings Array of dictionary Applicable only if the field is part of a section. This contains the details of a section (ID, position) for which it is been a part of
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
# Custom Dropdown
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Issue Type","displayed_to_customers":true,"label":"Issue Type","position":1,"type":"custom_dropdown","choices":[{"value":"Refund","position":1},{"value":"Faulty Product","position":2},{"value":"Item Not Delivered","position":3}]}' https://domain.freshdesk.com/api/v2/admin/ticket_fields'

# Custom Text with section mapping
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Feedback","displayed_to_customers":true,"section_mappings":[{"position":3,"section_id":1}],"label":"Feedback","type":"custom_text"}' https://domain.freshdesk.com/api/v2/admin/ticket_fields'

# Dependent Field
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Bank","displayed_to_customers":true,"label":"Bank","position":13,"type":"nested_field","choices":[{"value":"HDFC","position":1,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Porur","position":1},{"value":"OMR","position":2}]},{"value":"Madurai","position":2,"choices":[{"value":"Thirumangalam","position":1},{"value":"SB Colony","position":2}]}]},{"value":"SBI","position":2,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Tambaram","position":1},{"value":"Guindy","position":2}]},{"value":"Trichy","position":2,"choices":[{"value":"AGS Colony","position":1}]}]},{"value":"ICICI","position":3,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Avadi","position":1}]}]}],"dependent_fields":[{"label":"District","label_for_customers":"District","level":2},{"label":"Branch","label_for_customers":"Branch","level":3}]}' https://domain.freshdesk.com/api/v2/admin/ticket_fields'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
# Custom Dropdown
{ 
   "id":22,
   "name":"cf_issue_type_297457",
   "label":"Issue Type",
   "label_for_customers":"Issue Type",
   "position":1,
   "type":"custom_dropdown",
   "default":false,
   "customers_can_edit":true,
   "required_for_closure":false,
   "required_for_agents":false,
   "required_for_customers":false,
   "displayed_to_customers":true,
   "created_at":"2019-12-19T05:28:31Z",
   "updated_at":"2019-12-19T05:28:31Z",
   "choices":[ 
      { 
         "id":125,
         "position":1,
         "value":"Refund",
         "parent_choice_id":22,
         "choices":[ 

         ]
      },
      { 
         "id":126,
         "position":2,
         "value":"Faulty Product",
         "parent_choice_id":22,
         "choices":[ 

         ]
      },
      { 
         "id":127,
         "position":3,
         "value":"Item Not Delivered",
         "parent_choice_id":22,
         "choices":[ 

         ]
      }
   ]
}

# Custom Text with section mapping
{ 
   "id":27,
   "name":"cf_feedback",
   "label":"Feedback",
   "label_for_customers":"Feedback",
   "position":17,
   "type":"custom_text",
   "default":false,
   "customers_can_edit":true,
   "required_for_closure":false,
   "required_for_agents":false,
   "required_for_customers":false,
   "displayed_to_customers":true,
   "created_at":"2020-01-27T07:12:48Z",
   "updated_at":"2020-01-27T07:12:48Z",
   "archived":false,
   "section_mappings":[ 
      { 
         "section_id":1,
         "position":3
      }
   ]
}

# Dependent Field
{ 
   "ticket_field":{ 
      "id":28,
      "name":"cf_bank964807",
      "label":"Bank",
      "label_for_customers":"Bank",
      "position":13,
      "type":"nested_field",
      "default":false,
      "customers_can_edit":true,
      "required_for_closure":false,
      "required_for_agents":false,
      "required_for_customers":false,
      "displayed_to_customers":true,
      "created_at":"2020-01-27T07:19:59Z",
      "updated_at":"2020-01-27T07:19:59Z",
      "archived":false,
      "choices":[ 
         { 
            "id":6,
            "position":1,
            "value":"HDFC",
            "parent_choice_id":28,
            "choices":[ 
               { 
                  "id":7,
                  "position":1,
                  "value":"Chennai",
                  "parent_choice_id":6,
                  "choices":[ 
                     { 
                        "id":8,
                        "position":1,
                        "value":"Porur",
                        "parent_choice_id":7,
                        "choices":[ 

                        ]
                     },
                     { 
                        "id":9,
                        "position":2,
                        "value":"OMR",
                        "parent_choice_id":7,
                        "choices":[ 

                        ]
                     }
                  ]
               },
               { 
                  "id":10,
                  "position":2,
                  "value":"Madurai",
                  "parent_choice_id":6,
                  "choices":[ 
                     { 
                        "id":11,
                        "position":1,
                        "value":"Thirumangalam",
                        "parent_choice_id":10,
                        "choices":[ 

                        ]
                     },
                     { 
                        "id":12,
                        "position":2,
                        "value":"SB Colony",
                        "parent_choice_id":10,
                        "choices":[ 

                        ]
                     }
                  ]
               }
            ]
         },
         { 
            "id":13,
            "position":2,
            "value":"SBI",
            "parent_choice_id":28,
            "choices":[ 
               { 
                  "id":14,
                  "position":1,
                  "value":"Chennai",
                  "parent_choice_id":13,
                  "choices":[ 
                     { 
                        "id":15,
                        "position":1,
                        "value":"Tambaram",
                        "parent_choice_id":14,
                        "choices":[ 

                        ]
                     },
                     { 
                        "id":16,
                        "position":2,
                        "value":"Guindy",
                        "parent_choice_id":14,
                        "choices":[ 

                        ]
                     }
                  ]
               },
               { 
                  "id":17,
                  "position":2,
                  "value":"Trichy",
                  "parent_choice_id":13,
                  "choices":[ 
                     { 
                        "id":18,
                        "position":1,
                        "value":"AGS Colony",
                        "parent_choice_id":17,
                        "choices":[ 

                        ]
                     }
                  ]
               }
            ]
         },
         { 
            "id":19,
            "position":3,
            "value":"ICICI",
            "parent_choice_id":28,
            "choices":[ 
               { 
                  "id":20,
                  "position":1,
                  "value":"Chennai",
                  "parent_choice_id":19,
                  "choices":[ 
                     { 
                        "id":21,
                        "position":1,
                        "value":"Avadi",
                        "parent_choice_id":20,
                        "choices":[ 

                        ]
                     }
                  ]
               }
            ]
         }
      ],
      "dependent_fields":[ 
         { 
            "id":29,
            "name":"cf_district",
            "label":"District",
            "label_for_customers":"District",
            "level":2,
            "ticket_field_id":28,
            "created_at":"2020-01-27T07:19:59Z",
            "updated_at":"2020-01-27T07:19:59Z"
         },
         { 
            "id":30,
            "name":"cf_branch53114",
            "label":"Branch",
            "label_for_customers":"Branch",
            "level":3,
            "ticket_field_id":28,
            "created_at":"2020-01-27T07:19:59Z",
            "updated_at":"2020-01-27T07:19:59Z"
         }
      ]
   }
}
EXPAND ↓

View a Ticket Field

get
/api/v2/admin/ticket_fields/[id]
Sample code | Curl
Copied Copy 
1
2
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22?include=section'
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/16?include=section'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
   "id":22,
   "name":"cf_issue_type_297457",
   "label":"Issue Type",
   "label_for_customers":"Issue Type",
   "position":1,
   "type":"custom_dropdown",
   "default":false,
   "customers_can_edit":true,
   "required_for_closure":false,
   "required_for_agents":false,
   "required_for_customers":false,
   "displayed_to_customers":true,
   "created_at":"2019-12-19T05:28:31Z",
   "updated_at":"2019-12-19T05:28:31Z",
   "has_section":true,
   "sections":[
      {
         "id":1,
         "label":"Ecosystem Type",
         "parent_ticket_field_id":22,
         "choice_ids":[
            6
         ],
         "ticket_field_ids":[
            16
         ]
      }
   ],
   "choices":[
      {
         "id":125,
         "position":1,
         "value":"Refund",
         "parent_choice_id":22,
         "choices":[

         ]
      },
      {
         "id":126,
         "position":2,
         "value":"Faulty Product",
         "parent_choice_id":22,
         "choices":[

         ]
      },
      {
         "id":127,
         "position":3,
         "value":"Item Not Delivered",
         "parent_choice_id":22,
         "choices":[

         ]
      }
   ]
}
{
   "id":16,
   "name":"cf_mobile_os_type",
   "label":"Mobile OS Type",
   "label_for_customers":"Mobile OS Type",
   "position":5,
   "type":"custom_text",
   "default":false,
   "customers_can_edit":true,
   "required_for_closure":false,
   "required_for_agents":false,
   "required_for_customers":false,
   "displayed_to_customers":true,
   "created_at":"2020-01-03T09:45:03Z",
   "updated_at":"2020-01-03T09:45:15Z",
   "section_mappings":[
      {
         "section_id":1,
         "position":1
      }
   ]
}
EXPAND ↓

Update a Ticket Field

put
/api/v2/admin/ticket_fields/[id]

To Edit the contents of a ticket field, use this API

JSON Parameters

Attribute Type Description
customers_can_edit boolean To specify whether the customer can edit the ticket field
label_for_customers string Ticket Field name to be displayed to customers
displayed_to_customers boolean Display Ticket Field to customers
label string Display the name of the Ticket Field
type string Ticket Field type. Can be custom_dropdown, custom_checkbox, custom_text, etc...
position number Position in which the ticket field is displayed in the form. If not given, it will be displayed on top
required_for_closure boolean Set to true if the field is mandatory for closing the ticket
required_for_agents boolean Set to true if the field is mandatory for Agents
required_for_customers boolean Set to true if the field is mandatory in the customer portal
choices (Applicable for dropdown) Array of dictionary Array of key, value pairs containing the value and position of dropdown choices
dependent_fields Array of dictionary Applicable only for dependent fields, this contains details of nested fields
section_mappings Array of dictionary Applicable only if the field is part of a section. This contains the details of a section (ID, position) for which it is been a part of
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label_for_customers":"Issue Type", "label":"Issue Type", "position": 2, choices":[{ "deleted":true,"id":131 },{ "value":"Returns/Refund","id":129 },{ "value":"Faulty Product","id":130 },{ "value":"payments", "position":4 }] }' 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{ 
   "id":23,
   "name":"cf_issue_type_dropdown",
   "label":"Issue Type",
   "label_for_customers":"Issue Type",
   "position":2,
   "type":"custom_dropdown",
   "default":false,
   "customers_can_edit":true,
   "required_for_closure":false,
   "required_for_agents":false,
   "required_for_customers":false,
   "displayed_to_customers":true,
   "created_at":"2019-12-19T06:14:40Z",
   "updated_at":"2019-12-19T06:56:07Z",
   "choices":[ 
      { 
         "id":129,
         "position":1,
         "value":"Returns/Refund",
         "parent_choice_id":23,
         "choices":[ 

         ]
      },
      { 
         "id":130,
         "position":2,
         "value":"Faulty Product",
         "parent_choice_id":23,
         "choices":[ 

         ]
      },
      { 
         "id":133,
         "position":3,
         "value":"Payments",
         "parent_choice_id":23,
         "choices":[ 

         ]
      }
   ]
}
EXPAND ↓

Delete a Ticket Field

delete
/api/v2/admin/ticket_fields/[id]

Note: Be cautious about deleting a Ticket Field since this action is irreversible. You will not be able to restore a ticket field if you delete it.

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

Sections

This feature helps you to configure custom sections/section-fields for your Ticket field.

JSON Parameters
Section Attributes Description
id ID of the section
label Display name of the section
parent_ticket_field_id Ticket Field ID to which the section is mapped
ticket_field_ids Ticket Field IDs associated with the section (Ticket fields that are displayed as part of the section)
is_fsm Set to true if the ticket field is a FSM field (Field Service Management)
choice_ids Set of Choice IDs mapped to the section. The section will be displayed on choosing any one of the choices

List All Sections for a Ticket Field

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

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

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/20/sections'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{ 
   "sections":[ 
      { 
         "id":3,
         "label":"Environment Type (Mobile)",
         "parent_ticket_field_id":20,
         "choice_ids":[ 
            121
         ],
         "ticket_field_ids":[ 
            19
         ],
         "is_fsm":false
      },
      { 
         "id":4,
         "label":"Environment Type (Web)",
         "parent_ticket_field_id":20,
         "choice_ids":[ 
            120
         ],
         "ticket_field_ids":[ 

         ],
         "is_fsm":false
      }
   ]
}
EXPAND ↓

Create a Section

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

To create a new section, use the following APIs.

Parameters

Attribute Type Description
label string Display the name of the section
choice_ids Array of numbers Choice IDs for which the section to be displayed
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "label":"Environment Type (Web)", "choice_ids":[120] }' https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{ 
   "sections":[ 
      { 
         "id":3,
         "label":"Environment Type (Mobile)",
         "parent_ticket_field_id":20,
         "choice_ids":[ 
            121
         ],
         "ticket_field_ids":[ 
            19
         ],
         "is_fsm":false
      },
      { 
         "id":4,
         "label":"Environment Type (Web)",
         "parent_ticket_field_id":20,
         "choice_ids":[ 
            120
         ],
         "ticket_field_ids":[ 

         ],
         "is_fsm":false
      }
   ]
}
EXPAND ↓

List a specific Section details

get
/api/v2/admin/ticket_fields/[id]/sections/[section_id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ 
   "section":{ 
      "id":3,
      "label":"Environment Type (Web)",
      "parent_ticket_field_id":20,
      "choice_ids":[ 
         121
      ],
      "ticket_field_ids":[ 
         19
      ],
      "is_fsm":false
   }
}
EXPAND ↓

Update a section

put
/api/v2/admin/ticket_fields/[id]/sections/[section_id]

To Edit the section, use this API

Parameters

Attribute Type Description
label string Display the name of the section
choice_ids Array of numbers Choice IDs for which the section to be displayed
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label":"Environment Type (Mac OS)", "choice_ids":[134] }' 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{ 
   "section":{ 
      "id":3,
      "label":"Environment Type (Mac OS)",
      "parent_ticket_field_id":20,
      "choice_ids":[ 
         134
      ],
      "ticket_field_ids":[ 
         19
      ],
      "is_fsm":false
   }
}
EXPAND ↓

Delete a section

delete
/api/v2/admin/ticket_fields/[id]/sections/[section_id]

Note:
Be cautious about deleting a Section since this action is irreversible. You will not be able to restore a Section if you delete it.

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

Ticket Forms

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

Ticket forms allow you to show the right form to your customers depending on what they want to contact you about. You can create forms for different customer issues (eg: Returns, refunds, etc.), different product portals, or both.

JSON Parameters
Form Attributes Description
id ID of the ticket form
title Mandatory Name of the ticket form
default Set to true if the ticket form is the default form
description Description of the ticket form
portals Lists all the portals that are associated with the ticket form
fields Mandatory List of ticket fields which are added to the ticket form. Click here to see mandatory field attributes.
last_updated_by ID of the agent that last updated the form

List All Ticket Forms

get
/api/v2/ticket-forms

Note:
The agent whose credentials (identified by the API key) are used to make the API call should be authorised to either view the ticket forms or create a new ticket form

Form Attributes
Form Attribute Description
id ID of the ticket form
title Name of the ticket form
default Set to true if the form is the default form
description Description of the ticket form
portals Lists all the portals that are associated with the ticket form
widgets Lists all the widgets that are associated with the ticket form
last_updated_by ID of the agent that last updated the form
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms?include=portals'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
[
    {
        "id": 1,
        "name": "report_an_issue",
        "title": "Report an issue",
        "default": true,
        "description": "This form has all fields that customers can view or edit.",
        "created_at": "2022-05-25T10:43:01Z",
        "updated_at": "2022-06-01T10:21:34Z",
        "last_updated_by": 51020877290,
        "portals": []
    },
    {
        "id": 2,
        "name": "return_items",
        "title": "Return items",
        "default": false,
        "description": "Form to raise return requests on Acme portal",
        "created_at": "2022-05-27T10:33:34Z",
        "updated_at": "2022-05-31T10:06:26Z",
        "last_updated_by": 51020877290,
        "portals": [
            {
                "id": 1,
                "name": "portal 1"
            }
        ]
    }
]
EXPAND ↓

Create a Ticket Form

post
/api/v2/ticket-forms

To create a new ticket form, use the following APIs.

Note: A form can not be created without the requester and company field

JSON Parameters

Attribute Type Description
title Mandatory string Name of the ticket form
description string Description of the ticket form
fields Mandatory Array of dictionary The fields the form should contain. Click here to see mandatory field attributes.
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Custom ticket form
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{
  "title": "Custom ticket form",
  "description": "This is a custom ticket form",
  "fields": [{
    "id": 1,
    "label_for_customers": "requester",
    "customers_can_edit": true,
    "required_for_customers": true,
    "placeholder_for_customers": "requester",
    "hint_for_customers": "requester"
  },
  {
    "id": 2,
    "label_for_customers": "company",
    "customers_can_edit": true,
    "required_for_customers": true,
    "placeholder_for_customers": "company",
    "hint_for_customers": "company"
  }]
}' https://domain.freshdesk.com/api/v2/ticket-forms'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
# custom ticket form
{
   "id": 2,
   "name": "custom_ticket_form",
   "title": "Custom ticket form",
   "default": false,
   "description": "This is a custom ticket form",
   "created_at": "2022-06-01T14:10:59Z",
   "updated_at": "2022-06-01T14:10:59Z",
   "last_updated_by": 51020877290,
   "portals": [],
   "fields": [
      {
            "id": 1,
            "name": "requester",
            "label": "Search a requester",
            "label_for_customers": "requester",
            "position": 1,
            "type": "default_requester",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-06-01 14:10:59",
            "updated_at": "2022-06-01 14:10:59",
            "archived": false,
            "portal_cc": "false",
            "portal_cc_to": "company",
            "hint_for_customers": "requester",
            "placeholder_for_customers": "requester"
      },
      {
            "id": 2,
            "name": "company",
            "label": "Company",
            "label_for_customers": "company",
            "position": 2,
            "type": "default_company",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-06-01 14:10:59",
            "updated_at": "2022-06-01 14:10:59",
            "archived": false,
            "hint_for_customers": "company",
            "placeholder_for_customers": "company"
      }
   ]
}
EXPAND ↓

View a Ticket Form

get
/api/v2/ticket-forms/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/2'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
{
    "id": 2,
    "name": "return_items",
    "title": "Return items",
    "default": true,
    "description": "Form to raise return requests on Acme portal",
    "created_at": "2022-05-25T10:43:01Z",
    "updated_at": "2022-06-01T10:21:34Z",
    "last_updated_by": 51020877290,
    "portals": [],
    "fields": [
        {
            "id": 1,
            "name": "requester",
            "label": "Search a requester",
            "label_for_customers": "Requester",
            "position": 1,
            "type": "default_requester",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-05-25 10:43:01",
            "updated_at": "2022-05-25 10:43:01",
            "archived": false,
            "portal_cc": "false",
            "portal_cc_to": "company"
        },
        {
            "id": 2,
            "name": "subject",
            "label": "Subject",
            "label_for_customers": "Subject",
            "position": 2,
            "type": "default_subject",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-05-25 10:43:01",
            "updated_at": "2022-05-25 10:43:01",
            "archived": false
        },
        {
            "id": 3,
            "name": "status",
            "label": "Status",
            "label_for_customers": "Status",
            "position": 5,
            "type": "default_status",
            "default": true,
            "customers_can_edit": false,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": false,
            "displayed_to_customers": true,
            "created_at": "2022-05-25 10:43:01",
            "updated_at": "2022-05-25 10:43:01",
            "archived": false
        },
        {
            "id": 4,
            "name": "agent",
            "label": "Agent",
            "label_for_customers": "Assigned to",
            "position": 8,
            "type": "default_agent",
            "default": true,
            "customers_can_edit": false,
            "required_for_closure": false,
            "required_for_agents": false,
            "required_for_customers": false,
            "displayed_to_customers": true,
            "created_at": "2022-05-25 10:43:01",
            "updated_at": "2022-05-25 10:43:01",
            "archived": false
        },
        {
            "id": 5,
            "name": "description",
            "label": "Description",
            "label_for_customers": "Description",
            "position": 10,
            "type": "default_description",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-05-25 10:43:01",
            "updated_at": "2022-05-25 10:43:01",
            "archived": false
        },
        {
            "id": 6,
            "name": "company",
            "label": "Company",
            "label_for_customers": "Company",
            "position": 11,
            "type": "default_company",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-05-25 10:43:01",
            "updated_at": "2022-05-27 11:17:47",
            "archived": false
        }
    ]
}
EXPAND ↓

Update a Ticket Form

put
/api/v2/ticket-forms/[id]

To edit the contents of a ticket form, use the following API

JSON Parameters

Attribute Type Description
title Mandatory string Name of the ticket form
description string Description of the ticket form
fields Mandatory Array of dictionary The fields the form should contain. Click here to see mandatory field attributes.
Sample code | Curl
Copied Copy 
1
2
3
4
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{
  "title": "Updated returns form",
  "description": "New returns form for summer sale"
  }' 'https://domain.freshdesk.com/api/v2/ticket-forms/2'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
    "id": 1,
    "name": "updated_returns_form",
    "title": "Updated returns form",
    "default": false,
    "description": "New returns form for summer sale",
    "created_at": "2022-05-31T06:53:48Z",
    "updated_at": "2022-06-01T14:31:25Z",
    "last_updated_by": 51020877290,
    "portals": [],
    "fields": [
        {
            "id": 1,
            "name": "requester",
            "label": "Search a requester",
            "label_for_customers": "Requester details",
            "position": 1,
            "type": "default_requester",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-05-31 06:53:48",
            "updated_at": "2022-05-31 09:02:28",
            "archived": false,
            "portal_cc": "false",
            "portal_cc_to": null
        },
        {
            "id": 2,
            "name": "company",
            "label": "Company",
            "label_for_customers": "Company",
            "position": 2,
            "type": "default_company",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-05-31 06:53:48",
            "updated_at": "2022-05-31 06:53:48",
            "archived": false
        }
    ]
}
EXPAND ↓

Delete a Ticket Form

delete
/api/v2/ticket-forms/[id]

Note: Be cautious about deleting a ticket form since this action is irreversible. You will not be able to restore a ticket form if you delete it.

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

Clone a Ticket Form

clone
/api/v2/ticket-forms/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/2/clone'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
    "id": 3,
    "name": "copy_of_custom_ticket_form",
    "title": "Copy of custom ticket form",
    "default": false,
    "description": "",
    "created_at": "2022-05-25T10:43:01Z",
    "updated_at": "2022-06-01T10:21:34Z",
    "last_updated_by": 51020877290,
    "portals": [],
    "fields": [
        {
            "id": 1,
            "name": "requester",
            "label": "Search a requester",
            "label_for_customers": "Requester",
            "position": 1,
            "type": "default_requester",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-05-25 10:43:01",
            "updated_at": "2022-05-25 10:43:01",
            "archived": false,
            "portal_cc": "false",
            "portal_cc_to": "company"
        },
        {
            "id": 2,
            "name": "subject",
            "label": "Subject",
            "label_for_customers": "Subject",
            "position": 2,
            "type": "default_subject",
            "default": true,
            "customers_can_edit": true,
            "required_for_closure": false,
            "required_for_agents": true,
            "required_for_customers": true,
            "displayed_to_customers": true,
            "created_at": "2022-05-25 10:43:01",
            "updated_at": "2022-05-25 10:43:01",
            "archived": false
        }
    ]
}
EXPAND ↓

Ticket Form Fields

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

The ticket form fields in Freshdesk have the following properties.

JSON Parameters
Form Fields Description
id ID of the form field
name Name of the form field
label Display name for the form field (as seen by agents)
label_for_customers Mandatory Display name for the form field (as seen in the customer portal)
position Position in which the form field is displayed in the form
type Details on whether the form field is a custom or a default field. If it is a custom field, details on the field type (dropdown, decimal, date, etc.)
default True if the form field is a default form field
customers_can_edit Mandatory Set to true if the form field can be updated by customers
required_for_closure Set to true if the form field is mandatory for closing the ticket
required_for_agents Set to true if the form field is mandatory for Agents
required_for_customers Mandatory Set to true if the form field is displayed in the portal
displayed_to_customers Set to true if the form field is displayed in the portal
portal_cc Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket
portal_cc_to Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list
hint_for_customes Mandatory Can see the tooltip for the form field in the form
placeholder_for_customers Mandatory Can see the placeholder for the form field in the form

View A Ticket Form's Field

get
/api/v2/ticket-forms/[form-id]/fields/[field-id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/1/fields/1'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "id": 1,
    "name": "requester",
    "label": "Search a requester",
    "label_for_customers": "Requester email",
    "position": 1,
    "type": "default_requester",
    "default": true,
    "customers_can_edit": true,
    "required_for_closure": false,
    "required_for_agents": true,
    "required_for_customers": true,
    "displayed_to_customers": true,
    "created_at": "2022-05-27 10:33:34",
    "updated_at": "2022-05-31 09:25:06",
    "archived": false,
    "portal_cc": null,
    "portal_cc_to": null,
    "hint_for_customers": "Requester email",
    "placeholder_for_customers": "Requester Email"
}
EXPAND ↓

Update A Ticket Form's Field

post
/api/v2/ticket-forms/[form-id]/fields/[field-id]

To edit the contents of a ticket form field, use the following API

JSON Parameters

Attribute Type Description
id Mandatory * Integer ID of the ticket field (* mandatory only when creating a form)
label_for_customers Mandatory string Name of the form field
customers_can_edit Mandatory boolean Set to true if the field can be updated by customers
required_for_customers Mandatory boolean Set to true if the field is displayed in the portal
hint_for_customers Mandatory string Can see the tooltip for the form field in the form
placeholder_for_customers Mandatory string Can see the placeholder for the form field in the form
position Integer Position in which the form field is displayed in the form
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{
  "label_for_customers": "Requester email",
  "customers_can_edit": true,
  "required_for_customers": true,
  "hint_for_customers": "Requester email",
  "placeholder_for_customers": "Requester Email"
}' 'https://domain.freshdesk.com/api/v2/ticket-forms/2'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
    "id": 1,
    "name": "requester",
    "label": "Search a requester",
    "label_for_customers": "Requester email",
    "position": 1,
    "type": "default_requester",
    "default": true,
    "customers_can_edit": true,
    "required_for_closure": false,
    "required_for_agents": true,
    "required_for_customers": true,
    "displayed_to_customers": true,
    "created_at": "2022-05-27 10:33:34",
    "updated_at": "2022-05-31 09:25:06",
    "archived": false,
    "portal_cc": null,
    "portal_cc_to": null,
    "hint_for_customers": "Requester email",
    "placeholder_for_customers": "Requester Email"
}
EXPAND ↓

Delete a Ticket Form's Field

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

Conversations

Conversations consist of replies as well as public and private notes added to a ticket. Notes are non-invasive ways of sharing updates about a ticket amongst agents and customers. Private notes are for collaboration between agents and are not visible to the customer. Public notes are visible to, and can be created by, both customers and agents.

Attribute Type Description
attachments array of attachment objects Attachments associated with the conversation. The total size of all of a ticket's attachments cannot exceed 20MB.
body string Content of the conversation in HTML
body_text string Content of the conversation in plain text
id number ID of the conversation
incoming boolean Set to true if a particular conversation should appear as being created from outside (i.e., not through web portal)
to_emails array of strings Email addresses of agents/users who need to be notified about this conversation
private boolean Set to true if the note is private
source number Denotes the type of the conversation.
support_email string Email address from which the reply is sent. For notes, this value will be null.
ticket_id number ID of the ticket to which this conversation is being added
user_id number ID of the agent/user who is adding the conversation
last_edited_at datetime Timestamp when the conversation last edited
last_edited_user_id number ID of the agent who has last edited the conversation
created_at datetime Conversation creation timestamp
updated_at datetime Conversation updated timestamp

Conversation Properties

Conversation use certain fixed numerical values to denote their Source. These numerical values along with their meanings are given below.

Note:
This source attribute will be returned in the response body of the List All Conversations of a Ticket and View a ticket (only when 'include=conversation' is passed in url) endpoints.

Source Value
Reply 0
Note 2
Created from tweets 5
Created from survey feedback 6
Created from Facebook post 7
Source Type Value
Created from Forwarded Email 8
Created from Phone 9
E-Commerce 11

Create a Reply

post
/api/v2/tickets/[id]/reply

Parameters

Attribute Type Description
body † string Content of the note in HTML format
attachments array of attachment objects Attachments. The total size of all the ticket's attachments (not just this note) cannot exceed 20MB.
from_email string The email address from which the reply is sent. By default the global support email will be used.
user_id number ID of the agent who is adding the note
cc_emails array of strings Email address added in the 'cc' field of the outgoing ticket email.
bcc_emails array of strings Email address added in the 'bcc' field of the outgoing ticket email.
† Mandatory attribute
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"We are working on this issue. Will keep you posted." }' 'https://domain.freshdesk.com/api/v2/tickets/141/reply'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "body_text" : "We are working on this issue. Will keep you posted.",
  "body" : "<div>We are working on this issue. Will keep you posted.</div>",
  "id" : 4,
  "user_id" : 1,
  "from_email" : "support@yourcompany.com",
  "cc_emails" : [ ],
  "bcc_emails" : [ ],
  "ticket_id" : 141,
  "replied_to" : [
    "sample@yourcustomer.com"
  ],
  "attachments" : [ ],
  "created_at" : "2015-08-24T13:36:42Z",
  "updated_at" : "2015-08-24T13:36:42Z"
}
EXPAND ↓

Reply to a Ticket With Attachment

Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.txt" -F "body=this is a sample reply" -X POST 'https://domain.freshdesk.com/api/v2/tickets/27/reply'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "body_text" : "this is a sample reply",
    "body" : "<div>this is a sample reply</div>",
    "id" : 125,
    "user_id" : 1,
    "from_email" : "support@yourcompany.com",
    "cc_emails" : [ ],
    "bcc_emails" : [ ],
    "ticket_id" : 27,
    "replied_to" : [
        "sample@yourcustomer.com"
    ],
    "attachments" : [
        {
            "id" : 6013284906,
            "content_type" : "text/plain",
            "size" : 98,
            "name" : "data.txt",
            "attachment_url" : "https://cdn.freshdesk.com/data/helpdesk/attachments/production/6013284906/original/attachment1.txt",
            "created_at" : "2016-01-13T07:07:41Z",
            "updated_at" : "2016-01-13T07:07:41Z"
        }
    ],
    "created_at" : "2016-01-13T07:07:41Z",
    "updated_at" : "2016-01-13T07:07:41Z"
}
EXPAND ↓

Create a Note

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

Note:
By default, any note that you add will be private. If you wish to add a public note, set the parameter to false.

Parameters

Attribute Type Description
attachments array of attachment objects Attachments associated with the note. The total size of all of a ticket's attachments cannot exceed 20MB.
body † string Content of the note in HTML
incoming boolean Set to true if a particular note should appear as being created from outside (i.e., not through web portal). The default value is false
notify_emails array of strings Email addresses of agents/users who need to be notified about this note
private boolean Set to true if the note is private. The default value is true.
user_id number ID of the agent/user who is adding the note
† Mandatory attribute
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "private":false, "notify_emails":["tom@yourcompany.com"] }' 'https://domain.freshdesk.com/api/v2/tickets/3/notes'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "body_text" : "Hi tom, Still Angry",
  "body" : "<div>Hi tom, Still Angry</div>",
  "id" : 5,
  "incoming" : false,
  "private" : false,
  "user_id" : 1,
  "support_email" : null,
  "ticket_id" : 3,
  "notified_to" : ["tom@yourcompany.com"],
  "attachments" : [ ],
  "created_at" : "2015-08-24T13:49:37Z",
  "updated_at" : "2015-08-24T13:49:37Z"
}
EXPAND ↓

Create a Note With Attachment

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

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.ext" -F "body=Hi tom, Still Angry"  -F "notify_emails[]=tom@yourcompany.com" -X POST 'https://domain.freshdesk.com/api/v2/tickets/20/notes'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "body_text" : "Hi tom, Still Angry",
  "body" : "<div>Hi tom, Still Angry</div>",
  "id" : 5,
  "incoming" : false,
  "private" : false,
  "user_id" : 1,
  "support_email" : null,
  "ticket_id" : 20,
  "notified_to" : ["tom@yourcompany.com"],
  "attachments" : [  
          { 
            "id":4004881085,
            "content_type":"image/jpeg",
            "file_size":44115,
            "name":"attachment1.jpg",
            "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment1.jpg"
            "created_at":"2014-07-28T16:20:03+05:30",
            "updated_at":"2014-07-28T16:20:03+05:30",
          }
      ],
  "created_at" : "2015-08-24T13:49:37Z",
  "updated_at" : "2015-08-24T13:49:37Z"
}
EXPAND ↓

Update a conversation

put
/api/v2/conversations/[id]

Note:
Only public & private notes can be edited.

Parameters

Attribute Type Description
attachments array of attachment objects Attachments associated with the note. The total size of all of a ticket's attachments cannot exceed 20MB.
body string Content of the note in HTML
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "body":"Can you provide some screenshots?" }' 'https://domain.freshdesk.com/api/v2/conversations/5'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "body_text" : "Can you provide some screenshots?",
  "body" : "<div>Can you provide some screenshots?</div>",
  "id" : 5,
  "incoming" : false,
  "private" : false,
  "user_id" : 1,
  "support_email" : null,
  "ticket_id" : 20,
  "notified_to" : ["tom@yourcompany.com"],
  "attachments" : [ ],
  "created_at" : "2015-08-24T13:49:37Z",
  "updated_at" : "2015-08-24T13:49:37Z"
}
EXPAND ↓

Update a conversation With Attachment

Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.txt" -F "body=updated conversation" -X PUT 'https://domain.freshdesk.com/api/v2/conversations/6'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "body_text" : "updated conversation",
  "body" : "updated conversation",
  "id" : 6,
  "incoming" : false,
  "private" : false,
  "user_id" : 1,
  "support_email" : null,
  "ticket_id" : 20,
  "attachments" : [  
          { 
            "id":4004881085,
            "content_type":"image/jpeg",
            "file_size":44115,
            "name":"attachment1.jpg",
            "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment1.txt"
            "created_at":"2014-07-28T16:20:03+05:30",
            "updated_at":"2014-07-28T16:20:03+05:30",
          }
      ],
  "created_at" : "2015-08-24T13:49:37+05:30",
  "updated_at" : "2014-07-28T16:20:03+05:30"
}
EXPAND ↓

Delete a conversation

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

Reply to Forward

post
/api/v2/tickets/[id]/reply_to_forward
Attribute Type Description
body Mandatory string Content of the note in HTML format
body_text string Content of the note in plain text
user_id number ID of the agent/user who is replying to the forwarded email
ticket_id number ID of the ticket to which the reply is added
to_emails Mandatory array of strings Emails to which the reply is addressed
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X  -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "to_emails": ["user@company.com"]}' 'https://domain.freshdesk.com/api/v2/tickets/3/reply_to_forward'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "body":"<div>Hi tom, Still Angry</div>",
  "body_text":"Hi tom, Still Angry",
  "id":35131397084,
  "incoming":false,
  "private":true,
  "user_id":35008297863,
  "support_email":"support@supporttasks.freshdesk.com",
  "Source":2,
  "category":6,
  "ticket_id":3,
  "to_emails":["user@company.com"],
  "from_email":"\"Agent Bob\" <support@domain.freshdesk.com>",
  "cc_emails":[],
  "bcc_emails":[],
  "email_failure_count":null,
  "outgoing_failures":null,
  "created_at":"2020-08-24T06:05:34Z",
  "updated_at":"2020-08-24T06:05:34Z",
  "attachments":[],
  "deleted":false,
  "last_edited_at":null,
  "last_edited_user_id":null,
  "cloud_files":[],
  "has_quoted_text":true
}
EXPAND ↓

View Account

get
/api/v2/account
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/account'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  organisation_id: 284960733419037820,
  organisation_name: "dailyplanet.myfreshworks.com",
  account_id: 1840509,
  account_name: "Daily Planet",
  account_domain: "dailyplanet.freshdesk.com",
  bundle_id: null,
  hipaa_compliant: false,
  total_agents: {
    full_time: 1,
    occasional: 1,
    field_service: 0,
    collaborators: 0
  },
  timezone: "Eastern Time (US & Canada)",
  data_center: "US",
  tier_type: "Forest",
  address: {
    country: USA,
    state: California,
    city: San Mateo CA ,
    street: S. Delaware Street,
    postalcode: 94403
  },
  contact_person: {
    firstname: "Clark",
    lastname: "Kent",
    email: "clarkkent1@gmail.com"
  }
}
EXPAND ↓

Export Account

post
api/v2/account/export

You can export your account data depending on the data which you specifically need. You can configure it based on created date range, resources and export format.

Note:
Only Account admin can access the following APIs.

Attribute Type Description
date_range dictionary Provide date range within which the data was created
resources Array of dictionary Provide information about the resources that can be added to the export
output_format string Format of export data. eg: "json"
Date Range Attribute Description
start_date Start date of export data. eg: 2020-04-21T13:03:00Z
end_date End date of export data. eg: 2020-04-21T13:03:00Z
Resources Attribute Type Description
name string Resources to be included in export data eg. tickets, contacts
include Array of String Additional resources to be included within resource
Resource Name Allowed include parameters
tickets "notes", "attachments", "ticket_states", "schema_less_ticket", "requester"
archive_tickets "notes", "attachments"
contacts
companies "company_domains"
groups "agent_groups"
forums "posts"
canned_responses "all_canned_responses"
surveys "survey_handles", "survey_results", "survey_questions"
solutions
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{
  "date_range": {
    "start_date": "2020-04-21T13:03:00Z",
    "end_date": "2021-04-21T13:03:00Z"
  },
  "resources": [
    {
      "name": "tickets",
      "include": ["notes", "attachments", "ticket_states"]
    },
    {
      "name": "archive_tickets",
      "include": ["notes", "attachments"]
    },
    {
      "name": "contacts"
    },
    {
      "name": "companies",
      "include": ["company_domains"]
    },
    {
      "name": "groups",
      "include": ["agent_groups"]
    },
    {
      "name": "forums",
      "include": ["posts"]
    },
    {
      "name": "canned_responses",
      "include": ["all_canned_responses"]
    },
    {
      "name": "surveys",
      "include": ["survey_handles", "survey_results", "survey_questions"]
    },
    {
      "name": "solutions"
    }
  ],
  "output_format": "json"
}'
'https://domain.freshdesk.com/api/v2/account/export'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
{
  "job" : {
    "id" : 432,
    "link": {
      "href" : "dailyplanet.freshdesk.com/api/v2/jobs/432",
      "method" : "GET"
    }
  }
}
EXPAND ↓

View a Job

get
/api/v2/jobs/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/jobs/432'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
{
  "id" : "432",
  "name" : "ACCOUNT::EXPORT",
  "status" : "IN PROGRESS",
  "created_at" : "2015-08-28T11:47:58Z",
  "updated_at" : "2015-08-28T11:47:58Z",
  "status_updated_at" : "2015-08-28T11:47:58Z",
  "progress" : 80,
}
EXPAND ↓

Contacts

A contact is a customer or a potential customer who has raised a support ticket through any channel.

Attribute Type Description
active boolean Set to true if the contact has been verified
address string Address of the contact
avatar object Avatar of the contact
company_id number ID of the primary company to which this contact belongs
view_all_tickets boolean Set to true if the contact can see all tickets that are associated with the company to which he belong
custom_fields dictionary Key value pair containing the name and value of the custom fields. Read more here
deleted boolean Set to true if the contact has been deleted. Note that this attribute will only be present for deleted contacts
description string A short description of the contact
email string Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute
id number ID of the contact
job_title string Job title of the contact
language string Language of the contact
mobile string Mobile number of the contact
name string Name of the contact
other_emails array of strings Additional emails associated with the contact
phone string Telephone number of the contact
tags array of strings Tags associated with this contact
time_zone string Time zone in which the contact resides
twitter_id string Twitter handle of the contact
unique_external_id string External ID of the contact
other_companies array of hashes Additional companies associated with the contact
created_at datetime Contact creation timestamp
updated_at datetime Contact updated timestamp

Create a Contact

post
/api/v2/contacts

Parameters

Attribute Type Description
nameMandatory string Name of the contact
email *Unique string Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute.
phone * string Telephone number of the contact
mobile * string Mobile number of the contact
twitter_id *Unique string Twitter handle of the contact
unique_external_id *Unique string External ID of the contact
other_emails array of strings Additional emails associated with the contact
company_id number ID of the primary company to which this contact belongs
view_all_tickets boolean Set to true if the contact can see all the tickets that are associated with the company to which he belong
other_companies array of hashes Additional companies associated with the contact. This attribute can only be set if the Multiple Companies feature is enabled (Estate plan and above)
address string Address of the contact.
avatar object Avatar image of the contact The maximum file size is 5MB and the supported file types are .jpg, .jpeg, .jpe, and .png
custom_fields dictionary Key value pairs containing the name and value of the custom field. Only dates in the format YYYY-MM-DD are accepted as input for custom date fields. Read more here
description string A small description of the contact
job_title string Job title of the contact
language string Language of the contact. Default language is "en". This attribute can only be set if the Multiple Language feature is enabled (Garden plan and above)
tags array of strings Tags associated with this contact
time_zone string Time zone of the contact. Default value is the time zone of the domain. This attribute can only be set if the Multiple Time Zone feature is enabled (Garden plan and above)
lookup_parameter string This attribute for contacts can only be set if the Custom Objects feature is enabled. The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id.
*One of these four attributes is mandatory
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json'  -X POST -d '{ "name":"Super Man", "email":"superman@freshdesk.com", "other_emails": ["lex@freshdesk.com", "louis@freshdesk.com"] }' 'https://domain.freshdesk.com/api/v2/contacts'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "active": false,
  "address": null,
  "company_id":23,
  "view_all_tickets":false,
  "deleted": false,
  "description": null,
  "email": "superman@freshdesk.com",
  "id": 432,
  "job_title": null,
  "language": "en",
  "mobile": null,
  "name": "Super Man",
  "phone": null,
  "time_zone": "Chennai",
  "twitter_id": null,
  "other_emails":["lex@freshdesk.com","louis@freshdesk.com"],
  "other_companies":[
    { "company_id":25, "view_all_tickets":true },
    { "company_id":26, "view_all_tickets":false }
  ],
  "created_at": "2015-08-28T09:08:16Z",
  "updated_at": "2015-08-28T09:08:16Z",
  "tags": [ ],
  "avatar": null
}
EXPAND ↓

Create a contact with a custom object record associated

Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #12345, here the primary_field_value will be “12345”

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "name":"Super Man", "email":"superman@freshdesk.com", "other_emails": ["lex@freshdesk.com", "louis@freshdesk.com"], "lookup_parameter" : "primary_field_value", "custom_fields" : { "order_number" : "12345" } }' 'https://domain.freshdesk.com/api/v2/contacts'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "active": false,
  "address": null,
  "company_id":23,
  "view_all_tickets":false,
  "deleted": false,
  "description": null,
  "email": "superman@freshdesk.com",
  "id": 432,
  "job_title": null,
  "language": "en",
  "mobile": null,
  "name": "Super Man",
  "phone": null,
  "time_zone": "Chennai",
  "twitter_id": null,
  "other_emails":["lex@freshdesk.com","louis@freshdesk.com"],
  "other_companies":[
    { "company_id":25, "view_all_tickets":true },
    { "company_id":26, "view_all_tickets":false }
  ],
  "custom_fields":{
    "order_number": "12345"
  },
  "created_at": "2015-08-28T09:08:16Z",
  "updated_at": "2015-08-28T09:08:16Z",
  "tags": [ ],
  "avatar": null
}
EXPAND ↓

Create a Contact With Avatar

Note:
1. This API request must have its content-type set to multipart/form-data.
2. For more information on attachment refer to this section.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -F 'avatar=@/path/to/image.ext' -F 'name=Green Lantern' -F 'email=greenlantern@freshdesk.com' -X POST  'https://domain.freshdesk.com/api/v2/contacts'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "active":false,
  "address":null,
  "company_id":23,
  "view_all_tickets":false,
  "deleted":false,
  "description":null,
  "email":"greenlantern@freshdesk.com",
  "id":434,
  "job_title":null,
  "language":"en",
  "mobile":null,
  "name":"Green Lantern",
  "phone":null,
  "time_zone":"Chennai",
  "twitter_id":null,
  "other_emails":[ ],
  "other_companies":[
    { "company_id":25, "view_all_tickets":true },
    { "company_id":26, "view_all_tickets":false }
  ],
  "created_at":"2015-08-28T10:27:58Z",
  "updated_at":"2015-08-28T10:27:58Z",
  "tags":[ ],
  "avatar":{
    "avatar_url":"<AVATAR_URL>",
    "content_type":"application/octet-stream",
    "id":4,
    "name":"lantern.png",
    "size":13036,
    "created_at":"2015-08-28T10:27:58Z",
    "updated_at":"2015-08-28T10:27:58Z"
  }
}
EXPAND ↓

View a Contact

get
/api/v2/contacts/[id]
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/434'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "active": false,
  "address": null,
  "company_id":23,
  "view_all_tickets":false,
  "description": null,
  "email": "greenlantern@freshdesk.com",
  "id": 434,
  "job_title": null,
  "language": "en",
  "mobile": null,
  "name": "Green Lantern",
  "phone": null,
  "time_zone": "Chennai",
  "twitter_id": null,
  "other_emails": [],
  "other_companies":[
    { "company_id":25, "view_all_tickets":true },
    { "company_id":26, "view_all_tickets":false }
  ],
  "created_at": "2015-08-28T10:27:58Z",
  "updated_at": "2015-08-28T10:27:58Z",
  "custom_fields": {
    "department": "Operations"
    "fb_profile": null,
    "permanent": false
  },
  "tags": [],
  "avatar": {
    "avatar_url": "<AVATAR_URL>",
    "content_type": "application/octet-stream",
    "id": 4,
    "name": "rails.png",
    "size": 13036,
    "created_at": "2015-08-28T10:27:58Z",
    "updated_at": "2015-08-28T10:27:58Z"
  }
}
EXPAND ↓

List All Contacts

get
/api/v2/contacts

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

Note:
1. When using filters, the query string must be URL encoded
2. All unblocked and undeleted contacts will be returned by default

Filter by Handle
email, mobile, phone /api/v2/contacts?<filter>=<value>
Example:
/api/v2/contacts?email=superman@freshdesk.com
/api/v2/contacts?email=bat%2Bman%40gmail.com   (URL encoded bat+man@gmail.com)
/api/v2/contacts?mobile=7654367287
/api/v2/contacts?phone=4352789885
company_id /api/v2/contacts?company_id=45653
state /api/v2/contacts?state=[blocked/deleted/unverified/verified]
updated since /api/v2/contacts?updated_since=2018-01-19T02:00:00Z
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
[
  {
    "active":false,
    "address":null,
    "company_id":null,
    "description":null,
    "email":"rachel@freshdesk.com",
    "id":2,
    "job_title":null,
    "language":"en",
    "mobile":null,
    "name":"Rachel",
    "phone":null,
    "time_zone":"Chennai",
    "twitter_id":null,
    "created_at":"2015-08-18T16:18:14Z",
    "updated_at":"2015-08-24T09:25:19Z",
    "other_companies": [
        4,
        9,
        10
    ],
    "custom_fields":{
      "department": "Admin"
      "fb_profile": null,
      "permanent": true
    }
  },
  {
    "active":false,
    "address":null,
    "company_id":null,
    "deleted":false,
    "description":null,
    "email":"superman@freshdesk.com",
    "id":432,
    "job_title":null,
    "language":"en",
    "mobile":null,
    "name":"Super Man",
    "phone":null,
    "time_zone":"Chennai",
    "twitter_id":null,
    "created_at":"2015-08-28T09:08:16Z",
    "updated_at":"2015-08-28T09:08:16Z",
    "other_companies": [
        29,
        30
    ],
    "custom_fields":{
      "department": "Production",
      "fb_profile": "https://www.facebook.com/superman.567384",
      "permanent": true
    },
  },
  {
    "active":false,
    "address":null,
    "company_id":null,
    "description":null,
    "email":"greenlantern@freshdesk.com",
    "id":434,
    "job_title":null,
    "language":"en",
    "mobile":null,
    "name":"Green Lantern",
    "phone":null,
    "time_zone":"Chennai",
    "twitter_id":null,
    "created_at":"2015-08-28T10:27:58Z",
    "updated_at":"2015-08-28T10:27:58Z",
    "custom_fields":{
      "department": "Operations"
      "fb_profile": null,
      "permanent": false
    }
  },
  ...
]
EXPAND ↓

Additional Examples

1. Get a list of contacts filtered by the email address. Since the email address is unique, you will get only one contact in the list.

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

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

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

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

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

Search Contacts

get
/api/v2/contacts/autocomplete?term=[keyword]

Search for a contact using their name.

Note:
1. The search is case insensitive.
2. You cannot search with a substring. For example, a contact "John Jonz" can be looked up using "john", "Joh", "Jonz" and "jon". But it will not be returned when you search for "hn" or "nz".

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

Filter ContactsBETA

get
/api/v2/search/contacts?query=[query]

Use custom contact fields that you have created in your account to filter through the contacts and get a list of contacts matching the specified contact fields.

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

Note:
1. Deleted contacts will not be included in the results
2. The query must be URL encoded
3. Query can be framed using the name of the contact fields, which can be obtained from Contact Fields endpoint. Contact Fields are case sensitive
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
5. Logical operators AND, OR along with parentheses () can be used to group conditions
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
7. Input for date fields should be in UTC Format
8. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
9. To scroll through the pages add page parameter to the url. The page number starts with 1 and should not exceed 10
10. To filter for fields with no values assigned, use the null keyword
11. Please note that the updates will take a few minutes to get indexed, after which it will be available through API

Supported Contact Fields

Field Type Description
active boolean Set to true if the contact has been verified
company_id number ID of the primary company to which this contact belongs
twitter_id string Twitter handle of the contact
email string Primary email address associated to the contact
phone string Telephone number of the contact
mobile string Mobile number of the contact
tag string Tag that has been associated to the contacts
language string Language of the contact
time_zone string Time zone in which the contact resides
created_at date Contact creation date (YYYY-MM-DD)
updated_at date Date (YYYY-MM-DD) when the contact was last updated
Custom Fields
Single line text string
Number integer
Checkbox boolean
Dropdown string
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true"'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "total":22,
  "results":[
    {
      "active": true,
      "address": "11 Park Avenue,",
      "company_id": 331,
      "description": "alien hero",
      "email": "john@marsspace.com",
      "id": 112,
      "job_title": "Superhero",
      "language": "en",
      "mobile": "992339928",
      "name": "John Jonz",
      "phone": "+1992842882",
      "time_zone": "Eastern Time (US & Canada)",
      "twitter_id": "martian",
      "custom_fields": {
        "location": "Watch tower",
        "sector": "outer space"
      },
      "created_at": "2017-07-19T12:29:36Z",
      "updated_at": "2017-07-19T12:38:26Z"
    },
    ...
    ...
    ...
    ...
  ]
}
EXPAND ↓

Additional Examples

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

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

2. Get the list of users created in the first week of October 2017 in Chennai time zone.
    "time_zone:'Chennai' AND (created_at:>'2017-10-01' AND created_at:<'2017-10-07')"

Copied Copy 
1
curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="time_zone:%27Chennai%27%20AND%20(created_at:>%272017-10-01%27%20AND%20created_at:<%272017-10-07%27)"'
EXPAND ↓

Update a Contact

put
/api/v2/contacts/[id]

Parameters

Attribute Type Description
name string Name of the contact
email Unique string Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute.
phone string Telephone number of the contact
mobile string Mobile number of the contact
twitter_id Unique string Twitter handle of the contact
unique_external_id Unique string External ID of the contact
other_emails array of strings Additional emails associated with the contact
company_id number ID of the primary company to which this contact belongs
view_all_tickets boolean Set to true if the contact can see all the tickets that are associated with the company to which he belong
other_companies array of hashes Additional companies associated with the contact. This attribute can only be updated if the Multiple Companies feature is enabled (Estate plan and above)
address string Address of the contact.
avatar object Avatar image of the contact The maximum file size is 5MB and the supported file types are .jpg, .jpeg, .jpe, and .png
custom_fields dictionary Key value pairs containing the name and value of the custom field. Only dates in the format YYYY-MM-DD are accepted as input for custom date fields. Read more here
description string A small description of the contact
job_title string Job title of the contact
language string Language of the contact. Default language is "en". This attribute can only be updated if the Multiple Language feature is enabled (Garden plan and above)
tags array of strings Tags associated with this contact
time_zone string Time zone of the contact. Default value is the time zone of the domain. This attribute can only be updated if the Multiple Time Zone feature is enabled (Garden plan and above)
lookup_parameter string This attribute for contacts can only be set if the Custom Objects feature is enabled. The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id.
Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT -d '{ "name":"Clark Kent", "job_title":"Journalist", "other_emails": ["louis@freshdesk.com", "jonathan.kent@freshdesk.com"] }' 'https://domain.freshdesk.com/api/v2/contacts/432'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "active":false,
  "address":null,
  "company_id":23,
  "view_all_tickets":false,
  "deleted":false,
  "description":null,
  "email":"superman@freshdesk.com",
  "id":432,
  "job_title":"Journalist",
  "language":"en",
  "mobile":null,
  "name":"Clark Kent",
  "phone":null,
  "time_zone":"Chennai",
  "twitter_id":null,
  "other_emails":["louis@freshdesk.com","jonathan.kent@freshdesk.com"],
  "other_companies":[
    { "company_id":25, "view_all_tickets":true },
    { "company_id":26, "view_all_tickets":false }
  ],
  "created_at":"2015-08-28T09:08:16Z",
  "updated_at":"2015-08-28T11:37:05Z",
  "tags":[],
  "avatar":null
}
EXPAND ↓

Update the lookup field within a contact

Note:
1. The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #98765, here the primary_field_value will be “98765”

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT -d '{ "job_title":"Journalist", "lookup_parameter" : "primary_field_value", "custom_fields" : { "order_number" : "98765" } }' 'https://domain.freshdesk.com/api/v2/contacts/432'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "active": false,
  "address": null,
  "company_id":23,
  "view_all_tickets":false,
  "deleted": false,
  "description": null,
  "email": "superman@freshdesk.com",
  "id": 432,
  "job_title": "Journalist",
  "language": "en",
  "mobile": null,
  "name": "Super Man",
  "phone": null,
  "time_zone": "Chennai",
  "twitter_id": null,
  "other_emails":["lex@freshdesk.com","louis@freshdesk.com"],
  "other_companies":[
  { "company_id":25, "view_all_tickets":true },
  { "company_id":26, "view_all_tickets":false }
  ],
  "custom_fields":{
    "order_number": "98765",
  },
  "created_at": "2015-08-28T09:08:16Z",
  "updated_at": "2015-08-28T09:08:16Z",
  "tags": [ ],
  "avatar": null
}
EXPAND ↓

Update a Contact With Avatar

Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.

Sample code | Curl
Copied Copy 
1
curl -v -u yourapikey:X -F 'avatar=@/path/to/image.ext' -F 'job_title=Superhero' -X PUT  'https://domain.freshdesk.com/api/v2/contacts/434'
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "active":false,
  "address":null,
  "company_id":23,
  "view_all_tickets":false,
  "deleted":false,
  "description":null,
  "email":"greenlantern@freshdesk.com",
  "id":434,
  "job_title":'Superhero',
  "language":"en",
  "mobile":null,
  "name":"Green Lantern",
  "phone":null,
  "time_zone":"Chennai",
  "twitter_id":null,
  "created_at":"2015-08-28T10:27:58Z",
  "updated_at":"2015-08-28T10:27:58Z",
  "tags":[],
  "other_companies":[
    { "company_id":25, "view_all_tickets":true },
    { "company_id":26, "view_all_tickets":false }
  ],
  "avatar":{
    "avatar_url":"<AVATAR_URL>",
    "content_type":"application/octet-stream",
    "id":4,
    "name":"lantern.png",
    "size":13036,
    "created_at":"2015-08-28T10:27:58Z",
    "updated_at":"2015-08-28T10:27:58Z"
  }
}
EXPAND ↓

Soft Delete a Contact

delete
/api/v2/contacts/[id]
Sample code | Curl
Copied Copy 
1