Overview
Freshdesk is a cloud-based customer support platform that was founded with the mission of enabling companies of all sizes to provide great customer service. Our goal is simple: make it easy for brands to talk to their customers and make it easy for users to get in touch with businesses.
Freshdesk's APIs belong to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding or deleting data from your helpdesk. The APIs also support Cross-Origin Resource Sharing (CORS).
Note:
This documentation is for the v2.0 of the APIs. Documentation for the v1.0 APIs can be found here.
What API commands are used by Freshdesk?
Freshdesk APIs are plain JSON over HTTP and use the following HTTP verbs:
Command | Purpose |
---|---|
POST | Create an object |
GET | Fetch one or more objects |
PUT | Update an object |
DELETE | Remove an object |
Note:
All API requests should hit the secured endpoint, that is, only HTTPS
What's New
Version 2 of the API brings several new features as well as changes to the previous APIs. This section highlights some of the new features introduced in v2.
- Higher rate limits as a result of significant performance enhancements
- Improved error handling - errors will return appropriate HTTP status codes and an error body
- Four new API categories - Business Hours, Products, Email Configs, and SLAs
- New APIs that enable you to Reply to a ticket and enhancements to existing APIs that enable you to Update a ticket's description, Update a ticket's notes, and Retrieve a list of tickets that have been recently modified
- XML Support has been deprecated, only JSON is supported
- Only SSL calls (HTTPS) will be allowed
- Works only via Freshdesk domains and not via custom CNAMEs
- Support for page sizes up to 100 has been added
- New API deprecation and breaking change policies
- Some categories have been renamed for consistency with the web application. For example, Forums are now Discussions and Users are now Contacts
Rate Limit
The number of API calls per minute is based on your plan. This limit is applied on an account wide basis irrespective of factors such as the number of agents or IP addresses used to make the calls. For all trial users, there is a default API limit of 50 calls/minute.
If your account hasn't been switched to the new minute level APIs, please contact support@freshdesk.com to get the new rate limits enabled for your account. To view the old API rate limits, click here
Note: An account can purchase additional API calls, to increase the rate limit. Contact us to know more about our pricing policy and purchase additional API calls.
To view the limits in the older plans, click here.
Plan | Rate Limit/minute | Maximum rate limit/minute per endpoint |
---|---|---|
Growth | 200 |
Ticket Create - 80 Ticket Update - 80 Tickets List - 20 Contacts List - 20 |
Pro | 400 |
Ticket Create - 160 Ticket Update - 160 Tickets List - 100 Contacts List - 100 |
Enterprise | 700 |
Ticket Create - 280 Ticket Update - 280 Tickets List - 200 Contacts List - 200 |
If you have purchased additional rate limits, the sub-limits are as follows: | ||
- | 1000 |
Ticket Create - 400 Ticket Update - 400 Tickets List - 300 Contacts List - 300 |
- | 2000 |
Ticket Create - 800 Ticket Update - 800 Tickets List - 400 Contacts List - 400 |
Notes:
1. Ensure to follow the rate limit - best practices to stay within the rate limit.
2. Even invalid requests count towards the rate limit.
3. Some custom apps consume API calls and these calls also count towards the rate limit.
You can check your current rate limit status by looking at the following HTTP headers which are returned in response to every API request.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Ratelimit-Total: 700
X-Ratelimit-Remaining: 426
X-Ratelimit-Used-CurrentRequest: 1
X-Freshdesk-Api-Version: latest=v2; requested=v2
Header Name | Description |
---|---|
X-RateLimit-Total | Total number of API calls allowed per minute. |
X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. |
X-RateLimit-Used-CurrentRequest | The number of API calls consumed by the current request. Most API requests consume one call, however, including additional information in the response will consume more calls. |
Retry-After | The number in seconds that you will have to wait to fire your next API request. This header will be returned only when the rate limit has been reached. |
If your API request is received after the rate limit has been reached, Freshdesk will return an error in the response. The Retry-After value in the response header will tell you how long you need to wait before you can send another API request.
HTTP/1.1 429
Content-Type: application/json; charset=utf-8
Retry-After: 34
Policies
Freshdesk APIs are classified into either production or beta APIs. A production API is one that has been made generally available for public use and is stable. A beta API is one that is still in development or is for internal or limited use and whose stability cannot be guaranteed. Beta APIs may be removed or modified at any time without advance notice. The following policies apply to production APIs only.
Deprecation Policy
The current version of production level APIs is v2. When a new version of APIs is made generally available (not beta), the older version will be deprecated and will cease to function after six months. Once an API is removed, any request to it will result in a 404 error.
Note:
We will not remove any v1 API until similar functionality is present in the v2 APIs
Breaking Change Policy
Changes that do not break an API, such as adding a new attribute can be made at any time. Changes that break a production level API such as removing attributes or making major changes to the API’s behavior will only be done with an advance notice of 60 days. However, there may be rare occasions where due to legal, performance, or security reasons, we are forced to make breaking changes without advance notice.
Changelog
June 2022
- We’ve added parent_folder_id, sub_folders_count, articles_count, hierarchy as solutions folder attributes and can be used in different Folder and Article APIs as part of Flexible Hierarchy feature. Read more about it here
November 2021
- We've updated the Create an Email Mailbox API to allow only "custom_mailbox" in mailbox_type and access_type as "outgoing" or "both" for public domain mailboxes like "gmail", "hotmail", "outlook", "yahoo", "aol".
July 2021
- New APIs for Ticket User Access
- Support added to create collaborators using agent_type parameter while Creating an Agent
- Support added to convert contacts to collaborators using type parameter utilizing Make Agent section
January 2021
- Canned Responses API now supports creating canned response folders and bulk creation of canned responses
- New APIs for Archive Tickets
- New APIs for Automations
- New APIs for Ticket Summary and Merge Tickets
- New APIs to Bulk Update and Bulk Delete tickets
- New APIs to Get Associated Tickets and Prime Association
October 2020
- We have updated the responses of /tickets, /tickets/id, /tickets/id/conversations to remove the content of the Tweets and Twitter direct messages inline with Twitter platform's content redistribution policy. Instead of the full Tweet content, you will be receiving the subject and description as 'View the message on Twitter'. For /contacts, /contacts/id APIs, you will be receiving the id of the user in the twitter_id field instead of the Twitter handle name.
April 2020
- We’ve added contact_segment_ids and company_segment_ids as solutions folder attributes and can be used in Create a Solution Folder and Update a Solution Folder API. Read more about customer segments here.
November 2019
September 2019
- Unpublish an article by passing only the status as 1 without any other parameters in the Update a Solution Article API.
- We've added a way to get article metrics for a specific language or consolidated across languages in the View a Solution Article API.
December 2018
- We’ve added APIs to create and update SLA policies in your Freshdesk account.
- The response to the GET Business hours API now includes the start time and end time of the business hours along with the time zone.
November 2018
- We've added a way to get description in the List All tickets API by using the include: parameter. We will not be sending description in the standard response after 2019-01-31 and you will have to use include to get description if you need it in the response. For accounts created after 2018-11-30, using include is compulsory to get description.
July 2018
- New API to restore, send invite and merge contacts
June 2018
- Create a ticket now accepts parent_id to create child tickets
- Create a ticket now accepts related_ticket_ids to create tracker tickets
- View a ticket now supports ticket association
May 2018
- New API to list all Topics participated by a user
- New APIs to list all watchers on a ticket, add or remove watcher, bulk add or bulk remove watchers.
- New APIs for forwarding a ticket and reply to a forward.
December 2017
- New API to Filter contacts
- New API to Filter companies
July 2017
- New API to Filter tickets
January 2017
- Create a Contact, Update a Contact and View a Contact now accepts other_companies attribute
- Create a Ticket and Update a Ticket now accepts company_id attribute
September 2016
- New APIs for Solutions
- New API to view helpdesk settings
July 2016
- New API to list all Satisfaction Ratings of a ticket
- New APIs for Surveys and Satisfaction Ratings
- New APIs to update an agent, delete an agent
- New APIs to list all roles, view a role
- Make Agent API now accepts list of agent related attributes in request
June 2016
- List all Tickets now supports the embedding of the requester info.
May 2016
- View a Ticket and List all Tickets now support the embedding of the ticket stats.
- List All Ticket Fields, List All Company Fields and List All Contact Fields are also allowed for agents who can Create a Ticket, Create a Company and Create a Contact respectively.
- Updating or deleting a ticket that has been marked as spam or deleted will now return a '405 Method Not Allowed'
- Updating or deleting a contact that has been blocked or deleted will now return a '405 Method Not Allowed'
- New API to create an outbound email
- Added support for editing tickets created through outbound email via Update a Ticket
- Create a Ticket and Update a Ticket now enforce dynamic form validation
- View a Ticket now supports embedding the details of the requester and the company
- Previously, for the ticket APIs, we accepted 'description' and 'description_html' as attributes in the request. Now we will only accept the description attribute which can now optionally contain HTML. In the response, we will return a 'description' and 'description_text' (which will strip any HTML out of description). We have made similar changes to Topics, Comments, and Agents. The full set of breaking changes are listed below
- The following request attributes have been removed
- 'description_html' has been removed from Create a Ticket and Update a Ticket
- 'body_html' has been removed from Create a Note, Create a Reply and Update a conversation
- The following request attributes have been renamed
- 'message_html' has been renamed to message in Create a Topic
- 'body_html' has been renamed to body in Creat a Comment
- The following response attributes have been removed
- 'description_html' has been removed from Forum responses
- The following response attributes have been renamed
- 'description' and 'description_html' have been renamed to description_text and description respectively in Ticket responses
- 'body' and body_html have been renamed to body_text and body in Conversation & Forum Comment responses
- 'signature_html' has been renamed to signature in Agent responses
- Notes have been renamed to Conversations. This has resulted in breaking changes in the following four APIs
- List All Notes of a Ticket has been renamed to List All Conversations of a Ticket
- View a ticket (include=notes is now include=conversations)
- Update A Note has been renamed to Update a Conversation
- Delete A Note is now Delete a Conversation
- Reply to Ticket has been renamed to Create Reply and moved to the Conversations section
- New API to retrieve the currently authenticated agent
- Added support for associating multiple emails to a contact
- We’ve added new APIs for Email Mailboxes.The API's support:
- Added new APIs for Viewing Mailbox Settings and Updating Mailbox Settings
- Also added new APIs for Viewing the bcc emails and Updating the bcc emails
April 2016
March 2016
November 2019
Authentication
How does it work? Who can access my helpdesk? Can everybody see my data?
Before you can set the priority of a ticket or change a customer's name or use any of the APIs listed above, you need to "authenticate your ID" or "log in" in the same way as you log in to your helpdesk's web portal.
You can use your personal API key to authenticate the request. If you use the API key, there is no need for a password. You can use any set of characters as a dummy password.
curl -v -u apikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets'
For example, if your API key is abcdefghij1234567890, the curl command to use is:
curl -v -u abcdefghij1234567890:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets'
Where can I find my API key?
- Log in to your Support Portal
- Click on your profile picture on the top right corner of your portal
- Go to Profile settings Page
- Your API key will be available below the change password section to your right
For more information, please refer to this solution article
Note:
If you are sure that your credentials are correct, but are still unable to access your helpdesk, make sure that the "APIkey:X" is Base64-encoded before passing it as an "Authorization" header.
What are the resources available via the API?
Every single piece of information - be it a customer's ID or the priority of a specific ticket - can be identified by its own unique identifier or "URI". If you want your data from the helpdesk, whether via your smartphone app or via a third party service, you need this identifier. All URIs follow a specific format and that format is:
https://your_helpdesk_domain_name/api/v2/resource_name
For example, if you are Davy Jones and you are managing problems of drowned souls via your Freshdesk portal "thelocker.freshdesk.com", then to access the contacts in your helpdesk, the syntax would be
https://thelocker.freshdesk.com/api/v2/contacts
For tickets, it would be
https://thelocker.freshdesk.com/api/v2/tickets
Note:
We have shortened API resource URLs throughout this document by omitting the domain name. For example, /api/v2/tickets is actually https://domain.freshdesk.com/api/v2/tickets
Will everyone have the same access rights?
No, your ability to access data depends on the permissions available to your Freshdesk user profile. For example, if your Freshdesk Agent Role is "Newbie Agent" who is only allowed to view tickets but not reply to them, then you will not be able to use the APIs to reply to a ticket.
Schema
Blank Fields:
Blank fields are included as null instead of being omitted.
Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. ( Example : 2016-02-13T23:27:49Z )
Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm
Note:
If a custom field is a date field, ensure to specify the value in the YYYY-MM-DD format.
( some valid datefields : 2016-02-15T21:16:25Z, 2012-12-24T12:56:15+05:30, 2010-03-23T12:00 )
Location Header:
POST requests will contain the Location Header in the response that points to the URL of the created resource.
Response
HTTP STATUS: HTTP 201 Created
Headers:
"Location": https://domain.freshdesk.com/api/v2/tickets/1
Embedding
Our previous version of APIs returned a large number of fields by default. In order to increase performance and reduce data usage, we have removed several of these fields in our v2.0 APIs. For example, when you view a ticket, we no longer return the requester's name or the company name. However, there may be situations where these fields are required and hence, we have included a mechanism to embed additional resources into an API call in order to minimise the number of required API calls.
Note:
Embedding resources into an API will consume an additional API call credit per embedded resource.
You can request for additional resources using the "include" keyword. For example you can embed the requester's details within the ticket view API by using the following command
Sample Request
curl -v -u 'abcdefgh12345678:X' -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=requester'
Sample Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | { "cc_emails" : ["user@cc.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["user@cc.com"], "email_config_id" : null, "fr_escalated" : false, "group_id" : null, "priority" : 1, "requester_id" : 1, "responder_id" : null, "source" : 2, "spam" : false, "status" : 2, "subject" : "", "company_id" : 1, "id" : 20, "type" : null, "to_emails" : null, "product_id" : null, "created_at" : "2015-08-24T11:56:51Z", "updated_at" : "2015-08-24T11:59:05Z", "due_by" : "2015-08-27T11:30:00Z", "fr_due_by" : "2015-08-25T11:30:00Z", "is_escalated" : false, "description_text" : "Not given.", "description" : "<div>Not given.</div>", "custom_fields" : { "category" : "Primary" }, "tags" : [ ], "requester": { "email": "test@test.com", "id": 1, "mobile": null, "name": "Rachel", "phone": null }, "attachments" : [ ] } |
Attachments
Attachments are supported for the following endpoints- Create a Ticket
- Update a Ticket
- Create a Contact
- Update a Contact
- Reply to a Ticket
- Update a conversation
Please follow the guidelines listed below
- Only files on your local machine can be attached using API.
- The Content-Type should always be multipart/form-data for create/update requests with attachments.
- The name of the file is preserved after it is attached i.e the filename sent in the response will be the same as the one in the request.
- Sample code for dealing with attachments can be found here.
Errors
I have encountered an error. How do I debug it?
API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error. You can use the table below to understand what each code means.
HTTP Status Code | Text | Description |
---|---|---|
400 | Client or Validation Error | The request body/query string is not in the correct format. For example, the Create a ticket API requires the requester_id field to be sent as part of the request and if it is missing, this status code is returned. |
401 | Authentication Failure | Indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here. |
403 | Access Denied | This indicates that the agent whose credentials were used in making this request was not authorized to perform this API call. It could be that this API call requires admin level credentials or perhaps the Freshdesk portal doesn't have the corresponding feature enabled. It could also indicate that the user has reached the maximum number of failed login attempts or that the account has reached the maximum number of agents |
404 | Requested Resource not Found | This status code is returned when the request contains invalid ID/Freshdesk domain in the URL or an invalid URL itself. For example, an API call to retrieve a ticket with an invalid ID will return a HTTP 404 status code to let you know that no such ticket exists. |
405 | Method not allowed | This API request used the wrong HTTP verb/method. For example an API PUT request on /api/v2/tickets endpoint will return a HTTP 405 as /api/v2/tickets allows only GET and POST requests. |
406 | Unsupported Accept Header | Only application/json and */* are supported. When uploading files multipart/form-data is supported. |
409 | Inconsistent/Conflicting State | The resource that is being created/updated is in an inconsistent or conflicting state. For example, if you attempt to Create a Contact with an email that is already associated with an existing user, this code will be returned. |
415 | Unsupported Content-type | Content type application/xml is not supported. Only application/json is supported. |
429 | Rate Limit Exceeded | The API rate limit allotted for your Freshdesk domain has been exhausted. |
500 | Unexpected Server Error | Phew!! You can't do anything more here. This indicates an error at Freshdesk's side. Please email us your API script along with the response headers. We will reach you out to you and fix this ASAP. |
In addition to the HTTP status code, most errors will also return a response body that contains more information to help you debug the error. A sample error response is shown below. The format of the error response body is explained after the example.
Sample Error
1 2 3 4 5 6 7 8 9 10 11 | { "description":"Validation failed", "errors":[ { "field":"name", "message":"Mandatory attribute missing", "code":"missing_field" } ] } |
Field | Description |
---|---|
field | The request field that triggerred this error. Applicable to HTTP 400 errors only. |
message | Detailed error message. |
code | Custom error code that is machine-parseable. |
In addition to the the error message, the error response will also contain a error code that is machine-parseable. The following table lists the error codes and their descriptions.
Code | Description |
---|---|
missing_field | A mandatory attribute is missing. For example, calling Create a Contact without the mandatory email field in the request will result in this error. |
invalid_value | This code indicates that a request contained an incorrect or blank value, or was in an invalid format. |
duplicate_value | Indicates that this value already exists. This error is applicable to fields that require unique values such as the email address in a contact or the name in a company. |
datatype_mismatch | Indicates that the field value doesn't match the expected data type. Entering text in a numerical field would trigger this error. |
invalid_field | An unexpected field was part of the request. If any additional field is included in the request payload (other than what is specified in the API documentation), this error will occur. |
invalid_json | Request parameter is not a valid JSON. We recommend that you validate the JSON payload with a JSON validator before firing the API request. |
invalid_credentials | Incorrect or missing API credentials. As the name suggests, it indicates that the API request was made with invalid credentials. Forgetting to apply Base64 encoding on the API key is a common cause of this error. |
access_denied | Insufficient privileges to perform this action. An agent attempting to access admin APIs will result in this error. |
require_feature | Not allowed as a specific feature has to be enabled in your Freshdesk portal for you to perform this action. |
account_suspended | Account has been suspended. |
ssl_required | HTTPS is required in the API URL. |
readonly_field | Read only field cannot be altered. |
inconsistent_state | An email should be associated with the contact before converting the contact to an agent. |
max_agents_reached | The account has reached the maximum number of agents. |
password_lockout | The agent has reached the maximum number of failed login attempts. |
password_expired | The agent's password has expired. |
no_content_required | No JSON data required. |
inaccessible_field | The agent is not authorized to update this field. |
incompatible_field | The field cannot be updated due to the current state of the record. |
Pagination
API responses that return a list of objects, such as View List of Tickets and View List of Contacts are paginated. To scroll through the pages, add the parameter page to the query string. The page number starts with 1.
https://domain.freshdesk.com/api/v2/contacts?page=2
By default, the number of objects returned per page is 30. This can be adjusted by adding the per_page parameter to the query string. The maximum number of objects that can be retrieved per page is 100. Invalid values and values greater than 100 will result in an error.
https://domain.freshdesk.com/api/v2/contacts?per_page=10
The per_page and page parameters can also be used together. The following example will retrieve the contacts from 11 to 20.
https://domain.freshdesk.com/api/v2/contacts?per_page=10&page=2
The 'link' header in the response will hold the next page url if exists. If you have reached the last page of objects, then the link header will not be set.
Headers: "link":< https://domain.freshdesk.com/api/v2/tickets?filter=all_tickets&page=2>;rel="next"
Best Practices
Rate Limit
- Whenever possible, please queue API calls at your end. This ensures that you can buffer calls on your end to avoid hitting the rate limit and retry API calls when you hit the rate limit after the retry-after time.
- Cache non-volatile data on your end whenever it is feasible. For e.g. the mapping between agent name and ID is extremely unlikely to change. Hence, by caching it on the client side, you will be able to avoid API calls.
- As soon as you recognise that a rate limit increase will be required in the future, contact us. This will make it possible for us to ensure that we are prepared to increase the limit as and when as it is needed.
Other
- Avoid making API calls directly from a mobile app, rather send the request to your servers and make the API calls from there. This ensures that in the event of an API endpoint being modified, you will be able to make and deploy the change to your server rather than updating your app and forcing your users to the latest version.
- Always use HTTP connection/multiplexing when making the API request. This will save some time while opening TCP connection to Freshdesk.
- When retrieving a list of objects, avoid making calls referencing page numbers over 500 (deep pagination). These are performance intensive calls and you may suffer from extremely long response times.
Code Samples
Code samples for accessing the Freshdesk API in various languages including Ruby, PHP, Java, Python, and Node JS are available in our Github repository.
API Index
CATEGORY | CREATE | VIEW | VIEW LIST | UPDATE | DELETE | OTHERS |
---|---|---|---|---|---|---|
Tickets | Yes | Yes | Yes | Yes | Yes | 7 more |
Conversations | Yes | No | Yes | Yes* | Yes | |
Contacts | Yes | Yes | Yes | Yes | Yes | 3 more |
Agents | Yes | Yes | Yes | Yes | Yes | 1 more |
Skills | Yes | Yes | Yes | Yes | Yes | |
Roles | No | Yes | Yes | No | No | |
Groups | Yes | Yes | Yes | Yes | Yes | |
Companies | Yes | Yes | Yes | Yes | Yes | 2 more |
Discussions | ||||||
— Categories | Yes | Yes | Yes | Yes | Yes | |
— Forums | Yes | Yes | Yes | Yes | Yes | 3 more |
— Topics | Yes | Yes | Yes | Yes | Yes | 4 more |
— Comments | Yes | No | Yes | Yes | Yes | |
Solutions | ||||||
— Categories | Yes | Yes | Yes | Yes | Yes | |
— Folders | Yes | Yes | Yes | Yes | Yes | |
— Solution Articles | Yes | Yes | Yes | Yes | Yes | |
Surveys | No | No | Yes | No | No | |
Satisfaction Ratings | Yes | No | Yes | No | No | |
Time Entries | Yes | No | Yes | Yes | Yes | 1 more |
— Mailboxes | Yes | Yes | Yes | Yes | Yes | |
— Settings | No | Yes | No | Yes | No | |
— Bcc Emails | No | Yes | No | Yes | No | |
— Email configs (old) | No | Yes | Yes | No | No | |
Products | No | Yes | Yes | No | No | |
Business Hours | No | Yes | Yes | No | No | |
Settings | ||||||
— Helpdesk | No | Yes | No | No | No | |
Account | No | Yes | Yes | No | No | |
Jobs | No | Yes | No | No |
Tickets
A ticket is an issue raised by a requester that need to be solved. It could be an urgent, high-priority problem exposing a security vulnerability. It could also be low priority question about a free T-shirt. Tickets are assigned to agents based on the agent's expertise and on the subject of the ticket.
Attribute | Type | Description |
---|---|---|
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 20MB. |
cc_emails | array of strings | Email address added in the 'cc' field of the incoming ticket email |
company_id | number | ID of the company to which this ticket belongs |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
deleted | boolean | Set to true if the ticket has been deleted/trashed. Deleted tickets will not be displayed in any views except the "deleted" filter |
description | string | HTML content of the ticket |
description_text | string | Content of the ticket in plain text |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
string | Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact. | |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
facebook_id | string | Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk. |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
fr_escalated | boolean | Set to true if the ticket has been escalated as the result of first response time being breached |
fwd_emails | array of strings | Email address(e)s added while forwarding a ticket |
group_id | number | ID of the group to which the ticket has been assigned |
id | number | Unique ID of the ticket |
is_escalated | boolean | Set to true if the ticket has been escalated for any reason |
name | string | Name of the requester |
phone | string | Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory. |
priority | number | Priority of the ticket |
product_id | number | ID of the product to which the ticket is associated |
reply_cc_emails | array of strings | Email address added while replying to a ticket |
requester_id | number | User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
source | number | The channel through which the ticket was created |
spam | boolean | Set to true if the ticket has been marked as spam |
status | number | Status of the ticket |
subject | string | Subject of the ticket |
tags | array of strings | Tags that have been associated with the ticket |
to_emails | Array of strings | Email addresses to which the ticket was originally sent |
twitter_id | string | Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. |
created_at | datetime | Ticket creation timestamp |
updated_at | datetime | Ticket updated timestamp |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Status, and Priorities. These numerical values along with their meanings are given below.
Source | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 7 |
Feedback Widget | 9 |
Outbound Email | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Create a Ticket
/api/v2/tickets
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the requester |
requester_id † | number | User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email. |
email † | string | Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact. |
facebook_id † | string | Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk. |
phone † | string | Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory. |
twitter_id † | string | Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact. |
unique_external_id † | string | External ID of the requester. If no contact exists with this external ID in Freshdesk, they will be added as a new contact. |
subject | string | Subject of the ticket. The default Value is null. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null. |
status * | number | Status of the ticket. The default Value is 2. |
priority * | number | Priority of the ticket. The default value is 1. |
description | string | HTML content of the ticket. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 20MB. |
cc_emails | array of strings | Email address added in the 'cc' field of the incoming ticket email |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) If product_id is given and email_config_id is not given, product's primary email_config_id will be set |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
group_id | number | ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id |
parent_id | number | ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket. |
product_id | number | ID of the product to which the ticket is associated. It will be ignored if the email_config_id attribute is set in the request. |
source * | number | The channel through which the ticket was created. The default value is 2. |
tags | array of strings | Tags that have been associated with the ticket |
company_id | number | Company ID of the requester. This attribute can only be set if the Multiple Companies feature is enabled (Estate plan and above) |
internal_agent_id | Integer | ID of the internal agent which the ticket should be assigned with |
internal_group_id | Integer | ID of the internal group to which the ticket should be assigned with |
lookup_parameter | string | This attribute for tickets can only be set if Custom Objects is enabled and a lookup field has been added under ticket fields.The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
* Refer Ticket properties table for supported values † Any of the five attributes is mandatory |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Source, Status, and Priorities. These numerical values along with their meanings are given below.
Source | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 7 |
Feedback Widget | 9 |
Outbound Email | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
Create a Ticket With Custom Fields
Note:
Refer this solution article for more details regarding custom fields.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"], "custom_fields" : { "category" : "Primary" } }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "custom_fields" : { "category" : "Primary" }, "tags" : [ ], "attachments" : [ ] } |
Create a Ticket With Custom Object record associated
Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #12345, here the primary_field_value will be “12345”
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"], "lookup_parameter" : "primary_field_value", "custom_fields" : { "cf_order_number_1" : "12345" } }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "custom_fields" : { "cf_order_number_1" : "12345" }, "tags" : [ ], "attachments" : [ ] } |
Create a Ticket With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.ext" -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Ticket Title", "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "this is a sample ticket", "description" : "<div>this is a sample ticket</div>", "custom_fields" : { "category" : null }, "tags" : [ ], "attachments":[ { "id":4004881085, "content_type":"image/jpeg", "file_size":44115, "name":"attachment1.jpg", "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment.jpg" "created_at":"2014-07-28T16:20:03+05:30", "updated_at":"2014-07-28T16:20:03+05:30", }, { "id":4004881086, "content_type":"image/jpeg", "file_size":44134, "name":"attachment2.jpg", "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment2.jpg" "created_at":"2014-07-28T16:20:03+05:30", "updated_at":"2014-07-28T16:20:03+05:30", } ] } |
Create a Child Ticket
Note:
1. This API request must have parent_id.
2. For more information on Parent Child Ticketing refer to this section.
Additional Parameters
Attribute | Type | Description |
---|---|---|
parent_id | integer | ID of the parent ticket under which the child ticket needs to be created. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "parent_id": 1, priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 2, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "association_type" : 2, "associated_tickets_list" : [1] "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
Create a Tracker
Note:
1. This API request must have related_ticket_ids.
2. For more information on Linked Tickets refer to this section.
Additional Parameters
Attribute | Type | Description |
---|---|---|
related_ticket_ids | array of integers | List of Ticket IDs which needs to be linked to the Tracker being created. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "related_ticket_ids": [1,2,3], priority": 1, "status": 2, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 5, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "association_type" : 3, "associated_tickets_list" : [1,2,3] "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
Create an Outbound Email
/api/v2/tickets/outbound_email
Note:
1. By default, the ticket will be assigned to the agent sending the email and it will be created with 'closed' status. This makes sure that SLA timers aren't running unnecessarily on an outbound ticket.
2. Unlike normal tickets, the subject and description of outbound tickets cannot be updated. More information on the difference between normal and outbound tickets can be found here
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the requester |
email Mandatory | string | Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact. |
subject Mandatory | string | Subject of the ticket. The default Value is null. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null. |
status * | number | Status of the ticket. The default Value is 5. |
priority * | number | Priority of the ticket. The default value is 1. |
description | string | HTML content of the ticket. |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 20MB. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
email_config_id Mandatory | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
group_id | number | ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id |
tags | array of strings | Tags that have been associated with the ticket |
* Refer Ticket properties table for supported values |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Status, and Priorities. These numerical values along with their meanings are given below.
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "email_config_id": 1, "cc_emails": ["ram@freshdesk.com","diana@freshdesk.com"] }' -X POST 'https://domain.freshdesk.com/api/v2/tickets/outbound_email' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : 1, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 10, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
View a Ticket
/api/v2/tickets/[id]
Use 'include' to embed additional details in the response. Each include will consume an additional credit. For example if you embed the requester and company information you will be charged a total of 3 API credits for the call.
Note:
By default, certain fields such as conversations, company name and requester email will not be included in the response. They can be retrieved via the embedding functionality.
Embed | Handle |
---|---|
conversations |
/api/v2/tickets/[id]?include=conversations Will return up to ten conversations sorted by "created_at" in ascending order. Including conversations will consume two API calls. In order to access more than ten conversations belonging to a ticket, use the List All Conversations of a Ticket API. |
requester |
/api/v2/tickets/[id]?include=requester Will return the requester's email, id, mobile, name, and phone. |
company |
/api/v2/tickets/[id]?include=company Will return the company's id and name. |
stats |
/api/v2/tickets/[id]?include=stats Will return the ticket’s closed_at, resolved_at and first_responded_at time |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "cc_emails" : ["user@cc.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["user@cc.com"], "email_config_id" : null, "fr_escalated" : false, "group_id" : null, "priority" : 1, "requester_id" : 1, "responder_id" : null, "source" : 2, "spam" : false, "status" : 2, "subject" : "", "company_id" : 1, "id" : 20, "type" : null, "to_emails" : null, "product_id" : null, "created_at" : "2015-08-24T11:56:51Z", "updated_at" : "2015-08-24T11:59:05Z", "due_by" : "2015-08-27T11:30:00Z", "fr_due_by" : "2015-08-25T11:30:00Z", "is_escalated" : false, "association_type" : null, "description_text" : "Not given.", "description" : "<div>Not given.</div>", "custom_fields" : { "category" : "Primary" }, "tags" : [ ], "attachments" : [ ] } |
Additional Examples
1. Get the associated conversations along with the ticket response.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=conversations' |
2. Get the associated company and requester information along with the ticket response.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=company,requester' |
3. Get the associated stats information along with the ticket response.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20?include=stats' |
View a Ticket with Association
Use 'Association Type' to identify whether the ticket is a parent, child, tracker or related ticket.
Note:
1. For more information on Parent Child Ticketing refer to this section.
2. For more information on Linked Tickets refer to this section.
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Association. These numerical values along with their meanings are given below.
Association Type | Value |
---|---|
Parent | 1 |
Child | 2 |
Tracker | 3 |
Related | 4 |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/23' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "Support needed..", "company_id" : 1, "id" : 23, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "association_type" : 1, "associated_tickets_list" : [10,11,12] "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "tags" : [ ], "attachments" : [ ] } |
Additional Information
The 'associated_tickets_list' attribute returns an array of associated ticket IDs based on the association type value
- When association_type is 1 (Parent), it will return the list of child IDs associated with the respective parent.
- When association_type is 2 (Child), it will return the respective parent ticket ID.
- When association_type is 3 (Tracker), it will return the list of related ticket IDs associated with the respective tracker.
- When association_type is 4 (Related), it will return the respective tracker ticket ID.
Ticket Association API
Ticket association allows you to define the relationship between two or more tickets. You can refer to this section to know more about the APIs to create parent-child or linked tickets relationship between tickets.
Get Associated Tickets
/api/v2/tickets/[id]/associated_tickets
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/associated_tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | { "tickets": [ { "id": 44, "group_id": 244782, "priority": 1, "requester_id": 50000067379, "responder_id": 21797696, "source": 2, "company_id": 50000029563, "status": 3, "subject": "Website unresponsive", "product_id": 18880, "type": "L2 - Analysis", "due_by": "2020-12-17T11:57:57Z", "fr_due_by": "2020-12-14T01:24:43Z", "is_escalated": false, "created_at": "2020-12-11T22:24:43Z", "updated_at": "2020-12-16T02:42:00Z" } ] } |
Get Prime Association of a Ticket
/api/v2/tickets/[id]/prime_association
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/44/prime_association' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | { "id": 20, "group_id": 244782, "priority": 1, "requester_id": 50000067379, "responder_id": 21797696, "source": 2, "company_id": 50000029563, "status": 1, "subject": "Website issue - tracker", "product_id": 18880, "type": "L4 - Bug", "due_by": "2020-12-19T11:57:57Z", "fr_due_by": "2020-12-15T01:24:43Z", "is_escalated": false, "created_at": "2020-12-10T20:20:43Z", "updated_at": "2020-12-16T02:42:00Z" } |
List All Tickets
/api/v2/tickets
Use filters to view only specific tickets (those which match the criteria that you choose). By default, only tickets that have not been deleted or marked as spam will be returned, unless you use the 'deleted' filter.
Note:
1. By default, only tickets that have been created within the past 30 days will be returned. For older tickets, use the updated_since filter
2. A maximum of 300 pages (30000 tickets) will be returned.
3. When using filters, the query string must be URL encoded - see example
4. Use 'include' to embed additional details in the response. Each include will consume an additional 2 credits. For example if you embed the stats information you will be charged a total of 3 API credits for the call.
5. For accounts created after 2018-11-30, you will have to use include to get description.
Filter by | Handle |
---|---|
Predefined filters |
/api/v2/tickets?filter=[filter_name] The various filters available are new_and_my_open, watching, spam, deleted. |
Requester | /api/v2/tickets?requester_id=[id] /api/v2/tickets?email=[requester_email] /api/v2/tickets?unique_external_id=[requester_unique_external_id] Example: /api/v2/tickets?email=superman@freshdesk.com /api/v2/tickets?email=bat%2Bman%40gmail.com (URL encoded bat+man@gmail.com) |
Company ID | /api/v2/tickets?company_id=[id] |
Updated since | /api/v2/tickets?updated_since=2015-01-19T02:00:00Z |
Custom ticket views | Check out the Filter Tickets API |
Sort by | Handle |
---|---|
created_at, due_by, updated_at, status |
/api/v2/tickets?order_by=created_at Default sort order is created_at |
asc, desc |
/api/v2/tickets?order_type=asc Default sort order type is desc |
Embed | Handle |
---|---|
stats |
/api/v2/tickets?include=stats Will return the ticket’s closed_at, resolved_at and first_responded_at time |
requester |
/api/v2/tickets?include=requester Will return the requester's email, id, mobile, name, and phone. |
description |
/api/v2/tickets?include=description Will return the ticket description and description_text. |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | [ { "cc_emails" : ["user@cc.com", "user2@cc.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["user@cc.com", "user2@cc.com"], "fr_escalated" : false, "spam" : false, "email_config_id" : null, "group_id" : 2, "priority" : 1, "requester_id" : 5, "responder_id" : 1, "source" : 2, "status" : 2, "subject" : "Please help", "to_emails" : null, "product_id" : null, "id" : 18, "type" : Lead, "created_at" : "2015-08-17T12:02:50Z", "updated_at" : "2015-08-17T12:02:51Z", "due_by" : "2015-08-20T11:30:00Z", "fr_due_by" : "2015-08-18T11:30:00Z", "is_escalated" : false, "custom_fields" : { "category" : "Default" } }, { "cc_emails" : [ ], "fwd_emails" : [ ], "reply_cc_emails" : [ ], "fr_escalated" : false, "spam" : false, "email_config_id" : null, "group_id" : null, "priority" : 1, "requester_id" : 1, "responder_id" : null, "source" : 2, "status" : 2, "subject" : "", "to_emails" : null, "product_id" : null, "id" : 17, "type" : null, "created_at" : "2015-08-17T12:02:06Z", "updated_at" : "2015-08-17T12:02:07Z", "due_by" : "2015-08-20T11:30:00Z", "fr_due_by" : "2015-08-18T11:30:00Z", "is_escalated" : false, "custom_fields" : { "category" : null } } ] |
Additional Examples
1. Get the first page of a list of tickets, with the ticket description included for each ticket.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?include=description' |
2. Get the first page of a list of tickets that are being watched by the agent whose credentials were used to make this API call.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?filter=watching' |
3. Get the first page of a list of tickets from the specified requester. The tickets will be returned in the descending order of their priority i.e highest priority first.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?requester_id=1230&order_by=status&order_type=desc' |
4. Get the second page (tickets from 11-20) of a list of all tickets.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?per_page=10&page=2' |
5. Get the first page of a list of tickets that have shown any activity since the 17th of August, 2015.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?updated_since=2015-08-17' |
6. Get the associated stats information along with the ticket response.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?include=stats' |
7. Filter tickets based on the following requester email (super+man@gmail.com) which needs to be URL encoded.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets?email=super%2Bman%40gmail.com' |
Filter Tickets
/api/v2/search/tickets?query=[query]
Use custom ticket fields that you have created in your account to filter through the tickets and get a list of tickets matching the specified ticket fields.
Note:
1. Archived tickets will not be included in the results
2. The query must be URL encoded
3. Query can be framed using the name of the ticket fields, which can be obtained from Ticket Fields endpoint. Ticket Fields are case sensitive
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
5. Logical operators AND, OR along with parentheses () can be used to group conditions
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
7. Input for date fields should be in UTC Format
8. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
9. To scroll through the pages add page parameter to the url. The page number starts with 1 and should not exceed 10
10. To filter for fields with no values assigned, use the null keyword
11. Please note that the updates will take a few minutes to get indexed, after which it will be available through API
Supported Ticket Fields
Field | Type | Description |
---|---|---|
agent_id | integer | ID of the agent to whom the ticket has been assigned |
group_id | integer | ID of the group to which the ticket has been assigned |
priority | integer | Priority of the ticket |
status | integer | Status of the ticket |
tag | string | Tag that has been associated to the tickets |
type | string | Type of issue that has been associated to the tickets |
due_by | date | Date (YYYY-MM-DD) when the ticket is due to be resolved |
fr_due_by | date | Date (YYYY-MM-DD) when the first response is due |
created_at | date | Ticket creation date (YYYY-MM-DD) |
updated_at | date | Date (YYYY-MM-DD) when the ticket was last updated |
Custom Fields | ||
Single line text | string | |
Number | integer | |
Checkbox | boolean | |
Dropdown | string |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:3"' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 | { "total":49, "results":[ { "cc_emails":["clark.kent@kryptonspace.com"], "fwd_emails":[ ], "reply_cc_emails":[ ], "fr_escalated":false, "spam":false, "email_config_id":17, "group_id":156, "priority":3, "requester_id":6007738334, "responder_id":6001263404, "source":2, "company_id":2, "status":2, "subject":"Sample Title", "to_emails":null, "product_id":null, "id":47, "type":null, "due_by":"2016-02-23T16:00:00Z", "fr_due_by":"2016-02-22T17:00:00Z", "is_escalated":true, "description":"<div>Sample description</div>", "description_text":"Sample description", "created_at":"2016-02-20T09:16:58Z", "updated_at":"2016-02-23T16:14:57Z", "custom_fields":{ "sector_no":7, "locked":true } }, { "cc_emails":["bruce.wayne@gothamdomain.com"], "fwd_emails":[ ], "reply_cc_emails":[ ], "fr_escalated":true, "spam":false, "email_config_id":44, "group_id":65, "priority":3, "requester_id":6007738334, "responder_id":6001263404, "source":2, "company_id":33, "status":2, "subject":"New Title", "to_emails":null, "product_id":null, "id":57, "type":null, "due_by":"2016-02-23T16:00:00Z", "fr_due_by":"2016-02-22T17:00:00Z", "is_escalated":true, "description":"<div>New description</div>", "description_text":"New description", "created_at":"2016-02-20T16:15:10Z", "updated_at":"2016-03-14T15:58:13Z", "custom_fields":{ "sector_no":8, "locked":true } }, ... ... ... ... ] } |
Additional Examples
1. Get the list of Urgent and High priority tickets.
"priority:4 OR priority:3"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:4%20OR%20priority:3"' |
2. Get the second page of Open and Pending tickets.
"status:3 OR status:4"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="status:3%20OR%20status:4"&page=2' |
3. Get the list of Urgent and High priority tickets in Open Status belong to the group_id 11. "priority:>3 AND group_id:11 AND status:2"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:>3%20AND%20group_id:11%20AND%20status:2"' |
4. Get the list of locked tickets belong to Finance or Marketing sector (Custom Fields: locked, sector). "(cf_sector:'finance' OR cf_sector:'marketing') AND cf_locked:true"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="(cf_sector:%27finance%27%20OR%20cf_sector:%27marketing%27)%20AND%20cf_locked:true"' |
If you’re not getting a result for the above query, there’s a chance that the field might have been created recently or it has been moved to a new infrastructure. To query on these custom fields, use ‘custom_string’ instead of the actual field label.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string: finance"' |
5. Get the list of Urgent and High priority tickets created on a particular day. "priority:>3 AND created_at:'2017-01-01'"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="priority:>3%20AND%20created_at:%272017-01-01%27"' |
6. Get the list of tickets whose type is 'Question' or 'Problem' and response due on first week of October 2017. "(type:'Question' OR type:'Problem') AND (due_by:>'2017-10-01' AND due_by:<'2017-10-07')"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="(type:%27Question%27%20OR%20type:%27Problem%27)%20AND%20(due_by:>%272017-10-01%27%20AND%20due_by:<%272017-10-07%27)"' |
7. Get the list of tickets whose type is 'Problem' and tagged with 'marketing'. "type:'Problem' AND tag:'marketing'"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="type:%27Problem%27%20AND%20tag:%27marketing%27"' |
8. Get the list of tickets without any tag. "tag:null"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="tag:null"' |
9. Get the list of urgent tickets whose type is undefined. "type:null AND priority:4"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="type:null%20AND%20priority:4"' |
10. Get the list of urgent tickets assigned to agents whose ids are 2 and 3. "(agent_id:2 OR agent_id:3) AND priority:4"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="(agent_id:2%20OR%20agent_id:3)%20AND%20priority:4"' |
11. Get the list of unassigned tickets "agent_id:null"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="agent_id:null"' |
12. All unresolved tickets "status:2 OR status:3 OR status:6 OR status:7"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="status:2%20OR%20status:3%20OR%20status:6%20OR%20status:7"' |
13. Get the list of tickets using a value in the single line text field. "custom_string:theactualkeyword"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeyword"' |
"custom_string:theactualkeywordone AND custom_string:theactualkeywordtwo"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeywordone%20AND%20custom_string:theactualkeywordtwo"' |
"custom_string:theactualkeywordone OR custom_string:theactualkeywordtwo"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/tickets?query="custom_string:theactualkeywordone%OR%20custom_string:theactualkeywordtwo"' |
Update a Ticket
/api/v2/tickets/[id]
Note:
Unlike normal tickets, the subject and description of outbound tickets cannot be updated. More information on the difference between normal and outbound tickets can be found here
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the requester |
requester_id | number | User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email. |
string | Email address of the requester. If no contact exists with this email address in Freshdesk, it will be added as a new contact. | |
facebook_id | string | Facebook ID of the requester. A contact should exist with this facebook_id in Freshdesk. |
phone | string | Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory. |
twitter_id | string | Twitter handle of the requester. If no contact exists with this handle in Freshdesk, it will be added as a new contact. |
unique_external_id | string | External ID of the requester. If no contact exists with this external ID in Freshdesk, they will be added as a new contact. |
subject | string | Subject of the ticket. The default Value is null. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null. |
status * | number | Status of the ticket. The default Value is 2. |
priority * | number | Priority of the ticket. The default value is 1. |
description | string | HTML content of the ticket. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 20MB. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) If the product_id is changed and the current email_config_id doesn't belong to that product, then this value will be automatically updated to the selected product's primary email_config_id |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
group_id | number | ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id |
parent_id | number | ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket. |
product_id | number | ID of the product to which the ticket is associated. |
source * | number | The channel through which the ticket was created. The default value is 2. |
tags | array of strings | Tags that have been associated with the ticket |
company_id | number | Company ID of the requester. This attribute can only be updated if the Multiple Companies feature is enabled (Estate plan and above) |
internal_agent_id | Integer | ID of the internal agent which the ticket should be assigned with |
internal_group_id | Integer | ID of the internal group to which the ticket should be assigned with |
lookup_parameter | string | This attribute for tickets can only be set if Custom Objects is enabled and a lookup field has been added under ticket fields.The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
* Refer Ticket properties table for supported values |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Source, Status, and Priorities. These numerical values along with their meanings are given below.
Source | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 7 |
Feedback Widget | 9 |
Outbound Email | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "priority":2, "status":3 }' 'https://domain.freshdesk.com/api/v2/tickets/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "cc_emails" : [ ], "fwd_emails" : [ ], "reply_cc_emails" : [ ], "description_text" : "Not given.", "description" : "<div>Not given.</div>", "spam" : false, "email_config_id" : null, "fr_escalated" : false, "group_id" : null, "priority" : 2, "requester_id" : 1, "responder_id" : null, "source" : 3, "status" : 3, "subject" : "", "id" : 20, "type" : null, "to_emails" : null, "product_id" : null, "attachments" : [ ], "is_escalated" : false, "tags" : [ ], "created_at" : "2015-08-24T11:56:51Z", "updated_at" : "2015-08-24T11:59:05Z", "due_by" : "2015-08-27T11:30:00Z", "fr_due_by" : "2015-08-25T11:30:00Z" } |
Update the lookup field within a ticket
Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #98765, here the primary_field_value will be “98765”
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "priority":2, "status":3, "lookup_parameter" : "primary_field_value", "custom_fields" : { "cf_order_number_1" : "98765" } }' 'https://domain.freshdesk.com/api/v2/tickets/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["ram@freshdesk.com", "diana@freshdesk.com"], "email_config_id" : null, "group_id" : null, "priority" : 2, "requester_id" : 129, "responder_id" : null, "source" : 2, "status" : 3, "subject" : "Support needed..", "company_id" : 1, "id" : 1, "type" : "Question", "to_emails" : null, "product_id" : null, "fr_escalated" : false, "spam" : false, "urgent" : false, "is_escalated" : false, "created_at" : "2015-07-09T13:08:06Z", "updated_at" : "2015-07-23T04:41:12Z", "due_by" : "2015-07-14T13:08:06Z", "fr_due_by" : "2015-07-10T13:08:06Z", "description_text" : "Some details on the issue ...", "description" : "<div>Some details on the issue ..</div>", "custom_fields" : { "cf_order_number_1" : "98765" }, "tags" : [ ], "attachments" : [ ] } |
Update Multiple Tickets
/api/v2/tickets/bulk_update
Note:
To update the internal group or internal agent of a ticket, the API request must also include status value
Attribute | Type | Description |
---|---|---|
ids Mandatory | Array of numbers | IDs of tickets to be updated |
For bulk replies:
Attribute | Type | Description |
---|---|---|
body | string | Content of the reply to be added to the tickets |
attachment_ids | Array of numbers | IDs of attachments to be added to the reply |
inline_attachment_ids | Array of numbers | IDs of inline attachments to be added to the reply |
cloud_files | Array of objects | Cloud attachments to be added to the reply |
For bulk update of properties:
Attribute | Type | Description |
---|---|---|
from_email | string | Support email from which the reply should be sent |
skip_close_notification | boolean | Used to skip email notifications sent to requesters on closing a ticket |
email_config_id | Integer | Support email config on the ticket. Will be used for corresponding responses on the ticket |
group_id | Integer | ID of the group to be assigned on the ticket |
priority | Integer | Used to set the priority of the ticket. Possible values are 1,2,3,4 |
parent_id | Integer | ID of the parent ticket that this ticket should be linked to. When passing this field, the current ticket actioned upon will be converted to a child ticket. |
requester_id | Integer | ID of the requester on the ticket |
responder_id | Integer | ID of the agent to be assigned on the ticket |
source | Integer | Used to set the source of the ticket. Possible values are 1, 2,3,7,8,9,10 |
status | Integer | Used to set the status of the ticket. Possible values are 2,3,4,5,6,7 |
type | String | Type of the ticket. |
product_id | Integer | ID of the product to be associated with the ticket |
due_by | date-time | Timestamp that denotes when the ticket is due to be resolved |
fr_due_by | date-time | Timestamp that denotes when the first response is due |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
tags | Array of strings | Tags that have been associated with the ticket |
internal_agent_id | Integer | ID of the internal agent which the ticket should be assigned with |
internal_group_id | Integer | ID of the internal group to which the ticket should be assigned with |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"bulk_action": {"ids": [20,21,22],"properties":{"from_email":"support@freshdesk.com","status":2,"group_id":1234,"type":"Question","priority":4},"reply":{"body":"Please check this ticket"}}}' 'https://domain.freshdesk.com/api/v2/tickets/bulk_update' |
Response
1 2 3 4 | { "job_id": "e4d18654f60b5204513155b26c6cb", "href":"https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb" } |
The bulk ticket update happens at the background and the progress can be checked using the job_id in the response.
1 2 3 4 | { "id": "e4d18654f60b5204513155b26c6cb", "status": "IN PROGRESS", } |
Forward a ticket
/api/v2/tickets/[id]/forward
Forward your tickets to an external email address. You can also reply to the forwarded emails using the Reply to Forward API.
Attribute | Type | Description |
---|---|---|
body Mandatory | string | Content of the note in HTML format |
body_text | string | Content of the note in plain text |
id | integer | ID of the forwarded note |
incoming | boolean | Set to true if a particular conversation should appear as being created from outside (i.e., not through web portal) |
private | boolean | Set to true if the note is private |
agent_id | number | ID of the agent/user who is forwarding the ticket |
support_email | string | Email address from which the ticket is forwarded. For notes, this value will be null. |
source | number | Denotes the type of the conversation. |
ticket_id | number | ID of the ticket which gets forwarded |
include_quoted_text | boolean | Include the quoted text conversations in the forwarded email. The default value is True. |
include_original_attachments | boolean | Include the ticket attachments in the forwarded email. The default value is True. |
from_email | string | The email address from which the forward is sent. By default the global support email will be used. |
to_emails Mandatory | array of strings | Emails to which the ticket gets forwarded |
cc_emails | array of strings | Email address added in the 'cc' field of the outgoing forward email. |
bcc_emails | array of strings | Email address added in the 'bcc' field of the outgoing forward email. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "to_emails": ["user@company.com"]}' 'https://domain.freshdesk.com/api/v2/tickets/3/forward' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "body":"<div>Hi tom, Still Angry</div>", "body_text":"Hi tom, Still Angry", "id":35131396111, "incoming":false, "private":true, "user_id":35008297863, "support_email":"support@domain.freshdesk.com", "source":8, "category":2, "ticket_id":3, "to_emails":["user@company..com"], "from_email":"\"Agent Bob\" <support@domain.freshdesk.com>", "cc_emails":[], "bcc_emails":[], "email_failure_count":null, "outgoing_failures":null, "created_at":"2020-08-24T05:53:09Z", "updated_at":"2020-08-24T05:53:09Z", "attachments":[], "deleted":false, "last_edited_at":null, "last_edited_user_id":null, "cloud_files":[], "has_quoted_text":true } |
Ticket Merge API
Sometimes, a customer might try to get your attention regarding a particular issue by contacting you through separate channels. Sometimes, the same issue might be reported by different people in the team or someone might accidentally open a new ticket instead of following up on an existing one. To avoid conflicts, you can merge all related tickets together and keep the communication streamlined.
Attribute | Type | Description |
---|---|---|
primary_id | integer | Ticket to which conversations from secondary tickets will be merged |
ticket_ids | Array of numbers | IDs of tickets to be merged |
note_in_primary | hash | This contains the note added to the primary ticket along with the type of the note (public/private). A default note gets added if this is not specified in the request |
note_in_secondary | hash | This contains the note added to the secondary tickets along with the type of the note (public/private). A default note gets added if this is not specified in the request |
convert_recepients_to_cc | boolean | This will add recipients from secondary tickets in CC of the primary ticket |
/api/v2/tickets/merge
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{"primary_id":20,"ticket_ids":[20,21,22],"convert_recepients_to_cc":true,"note_in_primary":{"body":"Sample note","private":true}}' 'https://domain.freshdesk.com/api/v2/tickets/merge |
Response
1 | HTTP Status: 204 No Content |
Watcher
Using Watcher, you can follow the progress of a ticket even when it is not assigned to you. You can become a watcher of that ticket so that whenever there’s some update (like ticket reply or status change), you’ll receive an email notification.
Attribute | Type | Description |
---|---|---|
ids Mandatory | array of numbers | IDs of tickets for which the watcher should be updated |
user_id Mandatory | integer | ID of the agent to be added/removed as a watcher on the ticket |
watcher_ids | array of numbers | IDs of agents who’ve been added as watchers on the ticket |
Add watcher
/api/v2/tickets/[id]/watch
Parameters
Attribute | Type | Description |
---|---|---|
user_idMandatory | integer | ID of the agent to be added as a watcher on the ticket |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{"user_id":35010088657}' -X POST 'https://domain.freshdesk.com/api/v2/tickets/569/watch' |
Response
1 | HTTP Status: 204 No Content |
Add watcher to multiple tickets
/api/v2/tickets/bulk_watch
Parameters
Attribute | Type | Description |
---|---|---|
idsMandatory | array of numbers | IDs of tickets for which the watcher should be updated |
user_id | integer | ID of the agent to be added as a watcher on the ticket |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{"ids":[560,561],"user_id":35014948467}' -X PUT 'https://domain.freshdesk.com/api/v2/tickets/bulk_watch' |
Response
1 | HTTP Status: 204 No Content |
Remove watcher from multiple tickets
/api/v2/tickets/bulk_unwatch
Parameters
Attribute | Type | Description |
---|---|---|
idsMandatory | array of numbers | ID's of tickets for which the watcher should be removed |
Note:
So for this API we will not be passing any user_id by default it takes the user_id of the current user who is logged in and it uses only id's to remove the watcher of existing user and currently we haven't implemented it for other agents to pass their user_id and do bulk remove action.
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -d '{"ids":[560,561]}' -X PUT 'https://domain.freshdesk.com/api/v2/tickets/bulk_unwatch' |
Response
1 | HTTP Status: 204 No Content |
Delete a Ticket
/api/v2/tickets/[id]
Note:
Rest assured. When deleted, tickets are not cast into the fiery volcanoes of Mount Doom. You can retrieve them using the Restore Ticket API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/tickets/1' |
Response
1 | HTTP Status: 204 No Content |
Delete Multiple Tickets
/api/v2/tickets/bulk_delete
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"bulk_action": {"ids": [20,21,22]}}' 'https://domain.freshdesk.com/api/v2/tickets/bulk_delete' |
Response
1 2 3 4 | { "job_id": "e4d18654f60b5204513155b26c6cb630", "href":"https://domain.freshdesk.com/api/v2/jobs/e4d18654f60b5204513155b26c6cb630" } |
The bulk ticket deletion happens at the background and the progress can be checked using the job_id in the response.
1 2 3 4 | { "id": "e4d18654f60b5204513155b26c6cb630", "status": "IN PROGRESS", } |
List All Ticket Fields
/api/v2/ticket_fields
Note:
The agent whose credentials (identified by the API key) are used to make the API call should be authorised to either view the ticket fields or create a new ticket
Ticket Fields
Ticket Field | Description |
---|---|
id | ID of the ticket field |
default | Set to true if the field is not a custom field |
description | Description of the ticket field |
label | Display name for the field (as seen by agents) |
name | Name of the ticket field |
position | Position in which the ticket field is displayed in the form |
required_for_closure | Set to true if the field is mandatory for closing the ticket |
type | For custom ticket fields, type of value associated with the field will be given (Examples custom_date, custom_text...) |
required_for_agents | Set to true if the field is mandatory for Agents |
required_for_customers | Set to true if the field is mandatory in the customer portal |
label_for_customers | Display name for the field (as seen in the customer portal) |
customers_can_edit | Set to true if the field can be updated by customers |
displayed_to_customers | Set to true if the field is displayed in the customer portal |
portal_cc | Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket |
portal_cc_to | Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list |
choices | List of values supported by the field |
nested_ticket_fields | Applicable only for dependent fields, this contain details of nested fields (see the sample response given below) |
To view only specific ticket fields (that is, those which match only the criteria you choose) use the filters given below.
Filter by | Handle |
---|---|
type | /api/v2/ticket_fields?type=[type] |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket_fields' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 | [ { "id" : 1, "description" : "Ticket requester", "label" : "Search a requester", "name" : "requester", "position" : 1, "portal_cc" : false, "portal_cc_to" : "company", "type" : "default_requester", "label_for_customers" : "Requester", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : true, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2014-12-17T11:58:08Z" }, { "id" : 19, "description" : "", "label" : "Rating", "name" : "rating", "position" : 2, "type" : "custom_decimal", "label_for_customers" : "Rating", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-16T14:06:48Z", "updated_at" : "2015-06-16T14:06:51Z" }, { "id" : 20, "description" : "", "label" : "regional_id", "name" : "regional_id", "position" : 3, "type" : "custom_number", "label_for_customers" : "regional_id", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-16T14:06:52Z", "updated_at" : "2015-06-16T14:06:53Z" }, { "id" : 18, "description" : "", "label" : "customer_priority", "name" : "customer_priority", "position" : 4, "type" : "custom_dropdown", "label_for_customers" : "customer_priority", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-15T11:45:55Z", "updated_at" : "2015-06-16T14:06:54Z", "choices" : [ "1st", "2nd" ] }, { "id" : 21, "description" : "", "label" : "country", "name" : "country", "position" : 5, "type" : "nested_field", "label_for_customers" : "country", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-17T05:44:15Z", "updated_at" : "2015-06-17T05:44:16Z", "choices" : [ { "usa" : [ { "texas" : [ "citytexas1" ] }, { "washington" : [ "dc", "seatle" ] }, { "newyork" : [ "manhattan", "boston" ] } ] }, { "india" : [ { "tamilnadu" : [ "chennai", "trichy", "kovai", "madhurai" ] }, { "kerala" : [ "ernakulam", "kochin", "trivandrum" ] }, { "gujarat" : [ "allahabad", "gandhinagar" ] } ] } ], "nested_ticket_fields" : [ { "description" : "", "id" : 3, "label" : "state", "label_in_portal" : "state", "level" : 2, "name" : "state", "ticket_field_id" : 21, "created_at" : "2015-06-17T05:44:16Z", "updated_at" : "2015-06-17T05:44:16Z" }, { "description" : "", "id" : 4, "label" : "city", "label_in_portal" : "city", "level" : 3, "name" : "city", "ticket_field_id" : 21, "created_at" : "2015-06-17T05:44:16Z", "updated_at" : "2015-06-17T05:44:16Z" } ] }, { "id" : 14, "description" : "", "label" : "internal_issue", "name" : "internal_issue", "position" : 6, "type" : "custom_checkbox", "label_for_customers" : "internal_issue", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-06-15T11:40:12Z", "updated_at" : "2015-06-17T05:44:16Z" }, { "id" : 13, "description" : "", "label" : "department", "name" : "department", "position" : 8, "type" : "custom_text", "label_for_customers" : "department", "default" : false, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2015-05-11T11:03:28Z", "updated_at" : "2015-06-17T05:44:17Z" }, { "id" : 2, "description" : "Ticket subject", "label" : "Subject", "name" : "subject", "position" : 10, "type" : "default_subject", "label_for_customers" : "Subject", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : true, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:18Z" }, { "id" : 3, "description" : "Ticket type", "label" : "Type", "name" : "ticket_type", "position" : 11, "type" : "default_ticket_type", "label_for_customers" : "Type", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : false, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:18Z", "choices" : [ "Question", "Incident", "Problem", "Feature Request", "Lead" ] }, { "id" : 4, "description" : "Ticket source", "label" : "Source", "name" : "source", "position" : 12, "type" : "default_source", "label_for_customers" : "Source", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : false, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:19Z", "choices" : { "Email" : 1, "Portal" : 2, "Phone" : 3, "Forum" : 4, "Twitter" : 5, "Facebook" : 6, "Chat" : 7, "Feedback Widget" : 9 } }, { "id" : 5, "description" : "Ticket status", "label" : "Status", "name" : "status", "position" : 13, "type" : "default_status", "label_for_customers" : "Status", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:19Z", "choices" : { "2" : [ "Open", "Being Processed" ], "3" : [ "Pending", "Awaiting your Reply" ], "4" : [ "Resolved", "This ticket has been Resolved" ], "5" : [ "Closed", "This ticket has been Closed" ], "6" : [ "Waiting on Customer", "Awaiting your Reply" ], "7" : [ "Waiting on Third Party", "Being Processed" ] } }, { "id" : 6, "description" : "Ticket priority", "label" : "Priority", "name" : "priority", "position" : 14, "type" : "default_priority", "label_for_customers" : "Priority", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : false, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:19Z", "choices" : { "Low" : 1, "Medium" : 2, "High" : 3, "Urgent" : 4 } }, { "id" : 7, "description" : "Ticket group", "label" : "Group", "name" : "group", "position" : 15, "type" : "default_group", "label_for_customers" : "Group", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : false, "created_at" : "2014-11-30T09:10:02Z", "updated_at" : "2015-06-17T05:44:20Z", "choices" : { "Entertainment" : 4, "Product Management" : 1, "QA" : 2, "Sales" : 3, "vcxvxcvc" : 5 } }, { "id" : 8, "description" : "Agent", "label" : "Agent", "name" : "agent", "position" : 16, "type" : "default_agent", "label_for_customers" : "Assigned to", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : false, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:03Z", "updated_at" : "2015-06-17T05:44:20Z", "choices" : { "fggfg" : 30, "Rt" : 31, "Super Man" : 32, "SuperThreefour" : 7, "superyu" : 5, "Support" : 1 } }, { "id" : 9, "description" : "Select the product, the ticket belongs to.", "label" : "Product", "name" : "product", "position" : 16, "type" : "default_product", "label_for_customers" : "Product", "default" : true, "required_for_closure" : false, "required_for_agents" : false, "required_for_customers" : false, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:03Z", "updated_at" : "2014-11-30T09:10:03Z", "choices" : { "ddd" : 1 } }, { "id" : 10, "description" : "Ticket description", "label" : "Description", "name" : "description", "position" : 17, "type" : "default_description", "label_for_customers" : "Description", "default" : true, "required_for_closure" : false, "required_for_agents" : true, "required_for_customers" : true, "customers_can_edit" : true, "displayed_to_customers" : true, "created_at" : "2014-11-30T09:10:03Z", "updated_at" : "2015-06-17T05:44:20Z" } ] |
Additional Examples
1. List the ticket_field that is of type 'default_requester'
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket_fields?type=default_requester' |
List All Conversations of a Ticket
/api/v2/tickets/[id]/conversations
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/conversations' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | [ { "body_text" : "Please reply as soon as possible.", "body" : "<div>Please reply as soon as possible.</div>", "id" : 3, "incoming" : false, "private" : true, "user_id" : 1, "support_email" : null, "source" : 2, "ticket_id" : 20, "created_at" : "2015-08-24T11:59:05Z", "updated_at" : "2015-08-24T11:59:05Z", "from_email" : "agent2@yourcompany.com", "to_emails" : ["agent1@yourcompany.com"], "cc_emails": ["example@ccemail.com"], "bcc_emails": ["example@bccemail.com"], "attachments" : [ ], "last_edited_at" : "2015-08-24T11:59:59Z", "last_edited_user_id" : 2 } ] |
Additional Examples
1. This ticket's conversation has more than 30 entries. This request returns the second page (entries from 31 to 60).
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/1/conversations?page=2' |
List All Time Entries of a Ticket
/api/v2/tickets/[id]/time_entries
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | [ { "billable" : true, "note" : null, "timer_running" : true, "id" : 1, "agent_id" : 1, "ticket_id" : 20, "time_spent" : "00:00", "created_at" : "2015-08-24T13:21:50Z", "updated_at" : "2015-08-24T13:21:50Z", "executed_at" : "2015-08-24T13:21:49Z", "start_time" : "2015-08-24T13:21:49Z" } ] |
Additional Examples
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/time_entries?page=2' |
List All Satisfaction Ratings of a Ticket
/api/v2/tickets/[ticket_id]/satisfaction_ratings
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/tickets/[ticket_id]/satisfaction_ratings' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | [ { "id": 102, "survey_id": 1, "user_id": 2, "agent_id": 1, "feedback": "Thank you for the quick action", "group_id": null, "ticket_id": 432, "ratings":{ "default_question":103, "question_2":-102 }, "created_at": "2015-08-28T09:08:16Z", "updated_at": "2015-08-28T09:08:16Z" }, { "id": 112, "survey_id": 1, "user_id": 2, "agent_id": 1, "feedback": "Thank you for the support", "group_id": null, "ticket_id": 432, "ratings":{ "default_question":101 }, "created_at": "2015-08-28T010:08:16Z", "updated_at": "2015-08-28T011:08:16Z" } ] |
Ticket Summary
- Progress on the ticket so far and
- Important information that has been repeatedly referenced
This adds a section below the ticket description, the section can be used to summarize everything the support team or support agent knows about a ticket before they assign the ticket they worked on to another team. This is available from the Blossom plan. You can read more details about ticket summary here.
View Summary
/api/v2/tickets/[id]/summary
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/20/summary' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "body": "<div dir=\"ltr\">Test summary</div>", "body_text": "Test summary", "id": 82007772826, "user_id": 82002117631, "ticket_id": 20, "created_at": "2020-12-16T07:15:03Z", "updated_at": "2020-12-16T07:15:03Z", "attachments": [], "last_edited_at": null, "last_edited_user_id": null, "cloud_files": [] } |
Update Summary
/api/v2/tickets/[id]/summary
Attribute | Type | Description |
---|---|---|
bodyMandatory | integer | Content of the summary note in HTML |
attachments | Array of files | Attachments to be added to the summary note |
user_id | integer | Id of the user who creates the summary note |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{"body":"Updated summary"}' 'https://domain.freshdesk.com/api/v2/tickets/20/summary' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "body": "<div dir=\"ltr\">Updated summary</div>", "body_text": "Updated summary", "id": 82007772826, "user_id": 82002117631, "ticket_id": 20, "created_at": "2020-12-16T07:15:03Z", "updated_at": "2020-12-16T07:25:00Z", "attachments": [], "last_edited_at":"2020-12-16T07:25:00Z", "last_edited_user_id": 82002117631, "cloud_files": [] } |
Archive Tickets
In order to enhance the performance of your helpdesk, Freshdesk will archive closed, inactive tickets. This way, every time the helpdesk pulls up ticket count and other ticket properties, old and irrelevant tickets will be excluded making the process quicker and more efficient.Depending on the company's ticket traffic, any 'closed' ticket that has been inactive for 120 days will be archived. Read more about ticket archiving here: https://support.freshdesk.com/en/support/solutions/articles/212901-ticket-archiving
View an Archive Ticket
/api/v2/tickets/archived/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/archived/40' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | { "cc_emails" : ["user@cc.com"], "fwd_emails" : [ ], "reply_cc_emails" : ["user@cc.com"], "email_config_id" : null, "fr_escalated" : false, "group_id" : null, "priority" : 1, "requester_id" : 1, "responder_id" : null, "source" : 2, "spam" : false, "status" : 5, "subject" : "", "company_id" : 1, "id" : 40, "type" : null, "to_emails" : null, "product_id" : null, "created_at" : "2015-08-24T11:56:51Z", "updated_at" : "2015-08-24T11:59:05Z", "due_by" : "2015-08-27T11:30:00Z", "fr_due_by" : "2015-08-25T11:30:00Z", "is_escalated" : false, "association_type" : null, "description_text" : "Not given.", "description" : "<div>Not given.</div>", "custom_fields" : { "category" : "Primary" }, "tags" : [ ], "archived" : true, "attachments" : [ ] } |
List All Conversations of an Archive Ticket
/api/v2/tickets/archived/[id]/conversations
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshdesk.com/api/v2/tickets/archived/20/conversations' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | [ { "body_text" : "Please reply as soon as possible.", "body" : "<div>Please reply as soon as possible.</div>", "id" : 3, "incoming" : false, "private" : true, "user_id" : 1, "support_email" : null, "source" : 2, "ticket_id" : 20, "created_at" : "2015-08-24T11:59:05Z", "updated_at" : "2015-08-24T11:59:05Z", "from_email" : "agent2@yourcompany.com", "to_emails" : ["agent1@yourcompany.com"], "cc_emails": ["example@ccemail.com"], "bcc_emails": ["example@bccemail.com"], "attachments" : [ ] } ] |
Ticket User Access
Helps provide agents/collaborators access to a ticket based on a condition. For example: You can use the API to provide ticket access to the person who is raising a ticket or given the access to a ticket to anyone who has added a note on the ticket
Attribute | Type | Description |
---|---|---|
user_ids | array of numbers | IDs of users who have access to a particular ticket |
Add Ticket User Access
/api/v2/tickets/[id]/accesses
Parameters
Attribute | Type | Description |
---|---|---|
user_ids Mandatory | array of numbers | List of User IDs for whom ticket access should be provided |
Sample code | Curl
1 | curl -v -u yourapikey:X -d '{ "user_ids": [ 1, 2 ] }' -H "Content-Type: application/json" -X POST 'https://domain.freshdesk.com/api/v2/tickets/1/accesses' |
Response
1 2 3 | { "user_ids": [ 1, 2] } |
Update Ticket User Access
/api/v2/tickets/[id]/accesses
Parameters
Attribute | Type | Description |
---|---|---|
user_ids Mandatory | array of objects | Array of object type : { id: integer, deleted: boolean }, where id is the user id of the user and deleted indicates whether to remove access for this user or not |
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 12 | curl -v -u yourapikey:X -d '{ "user_ids": [ { "id": 2, "deleted": true }, { "id": 3 } ] } ' -H "Content-Type: application/json" -X PATCH 'https://domain.freshdesk.com/api/v2/tickets/1/accesses' |
Response
1 2 3 | { "user_ids": [ 1, 3] } |
Ticket Fields
Note: Only users with admin privileges can access the following APIs.
The custom and default ticket fields in Freshdesk have the following properties.
JSON Parameters
Ticket Field | Description |
---|---|
id | ID of the ticket field |
default | Set to true if the field is not a custom field |
description | Description of the ticket field |
label | Display name for the field (as seen by agents) |
name | Name of the ticket field |
position | Position in which the ticket field is displayed in the form |
required_for_closure | Set to true if the field is mandatory for closing the ticket |
type | For custom ticket fields, The type of value associated with the field will be given (Examples custom_date, custom_text...) |
required_for_agents | Set to true if the field is mandatory for Agents |
required_for_customers | Set to true if the field is mandatory in the customer portal |
label_for_customers | Display name for the field (as seen in the customer portal) |
customers_can_edit | Set to true if the field can be updated by customers |
displayed_to_customers | Set to true if the field is displayed in the customer portal |
portal_cc | Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket |
portal_cc_to | Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list |
choices | List of values supported by the field |
is_fsm | True if the Ticket field is inside FSM section (Applicable only if FSM is enabled) |
field_update_in_progress | True if the choice update is in progress (Applicable for the fields which has 100+ choices) |
dependent_fields | Applicable only for dependent fields, this contains details of nested fields (see the sample response given below) |
section_mappings | Applicable only if the field is part of a section. This contains section ID and position of the ticket field in the section |
List All Ticket Fields
/api/v2/admin/ticket_fields
To view all ticket field details, use this API.
Sample code | Curl
1 2 3 4 5 | # All Ticket Fields curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields' # All Ticket Fields with section mapping curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields?include=section' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 | # All Ticket Fields [ { "id":21, "name":"cf_issue_type", "label":"Issue Type", "label_for_customers":"Issue Type", "position":1, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-16T09:35:26Z", "updated_at":"2019-12-16T09:35:27Z" }, { "id":20, "name":"cf_product_category", "label":"Product Category", "label_for_customers":"Product Category", "position":3, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-16T07:12:07Z", "updated_at":"2019-12-16T09:35:26Z", "has_section":true }, { "id":19, "name":"cf_subject", "label":"Subject", "label_for_customers":"Subject", "position":4, "type":"custom_text", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-11T12:10:46Z", "updated_at":"2019-12-16T09:35:26Z", "section_mappings":[ { "section_id":3, "position":1 } ] }, { "id":12, "name":"cf_duplicate", "label":"Duplicate", "label_for_customers":"Duplicate", "position":5, "type":"custom_checkbox", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-03T12:23:58Z", "updated_at":"2019-12-16T09:35:26Z" } ] # Ticket Fields with section mapping [ { "id":21, "name":"cf_issue_type", "label":"Issue Type", "label_for_customers":"Issue Type", "position":1, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-16T09:35:26Z", "updated_at":"2019-12-16T09:35:27Z", "section_mappings": [ { "section_id": 1, "position": 1 } ] }, { "id":20, "name":"cf_product_category", "label":"Product Category", "label_for_customers":"Product Category", "position":3, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-16T07:12:07Z", "updated_at":"2019-12-16T09:35:26Z", "has_section":true, "sections": [ { "id": 1, "label": "Ecosystem Type", "parent_ticket_field_id": 12, "choice_ids": [ 6 ], "ticket_field_ids": [ 17, 18, 27 ] } ] }, { "id":19, "name":"cf_subject", "label":"Subject", "label_for_customers":"Subject", "position":4, "type":"custom_text", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-11T12:10:46Z", "updated_at":"2019-12-16T09:35:26Z", "section_mappings":[ { "section_id":3, "position":1 } ] }, { "id":12, "name":"cf_duplicate", "label":"Duplicate", "label_for_customers":"Duplicate", "position":5, "type":"custom_checkbox", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-03T12:23:58Z", "updated_at":"2019-12-16T09:35:26Z" } ] |
Create a Ticket Field
/api/v2/admin/ticket_fields
To create a new ticket field, use the following APIs.
JSON Parameters
Attribute | Type | Description |
---|---|---|
customers_can_edit | boolean | To specify whether the customer can edit the ticket field |
label_for_customers | string | Ticket Field name to be displayed to customers |
displayed_to_customers | boolean | Display Ticket Field to customers |
label | string | Display the name of the Ticket Field |
type | string | Ticket Field type. Can be custom_dropdown, custom_checkbox, custom_text, etc... |
position | number | Position in which the ticket field is displayed in the form. If not given, it will be displayed on top |
required_for_closure | boolean | Set to true if the field is mandatory for closing the ticket |
required_for_agents | boolean | Set to true if the field is mandatory for Agents |
required_for_customers | boolean | Set to true if the field is mandatory in the customer portal |
choices (Applicable for dropdown) | Array of dictionary | Array of key, value pairs containing the value and position of dropdown choices |
dependent_fields | Array of dictionary | Applicable only for dependent fields, this contains details of nested fields |
section_mappings | Array of dictionary | Applicable only if the field is part of a section. This contains the details of a section (ID, position) for which it is been a part of |
Sample code | Curl
1 2 3 4 5 6 7 8 | # Custom Dropdown curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Issue Type","displayed_to_customers":true,"label":"Issue Type","position":1,"type":"custom_dropdown","choices":[{"value":"Refund","position":1},{"value":"Faulty Product","position":2},{"value":"Item Not Delivered","position":3}]}' https://domain.freshdesk.com/api/v2/admin/ticket_fields' # Custom Text with section mapping curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Feedback","displayed_to_customers":true,"section_mappings":[{"position":3,"section_id":1}],"label":"Feedback","type":"custom_text"}' https://domain.freshdesk.com/api/v2/admin/ticket_fields' # Dependent Field curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{"customers_can_edit":true,"label_for_customers":"Bank","displayed_to_customers":true,"label":"Bank","position":13,"type":"nested_field","choices":[{"value":"HDFC","position":1,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Porur","position":1},{"value":"OMR","position":2}]},{"value":"Madurai","position":2,"choices":[{"value":"Thirumangalam","position":1},{"value":"SB Colony","position":2}]}]},{"value":"SBI","position":2,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Tambaram","position":1},{"value":"Guindy","position":2}]},{"value":"Trichy","position":2,"choices":[{"value":"AGS Colony","position":1}]}]},{"value":"ICICI","position":3,"choices":[{"value":"Chennai","position":1,"choices":[{"value":"Avadi","position":1}]}]}],"dependent_fields":[{"label":"District","label_for_customers":"District","level":2},{"label":"Branch","label_for_customers":"Branch","level":3}]}' https://domain.freshdesk.com/api/v2/admin/ticket_fields' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 | # Custom Dropdown { "id":22, "name":"cf_issue_type_297457", "label":"Issue Type", "label_for_customers":"Issue Type", "position":1, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-19T05:28:31Z", "updated_at":"2019-12-19T05:28:31Z", "choices":[ { "id":125, "position":1, "value":"Refund", "parent_choice_id":22, "choices":[ ] }, { "id":126, "position":2, "value":"Faulty Product", "parent_choice_id":22, "choices":[ ] }, { "id":127, "position":3, "value":"Item Not Delivered", "parent_choice_id":22, "choices":[ ] } ] } # Custom Text with section mapping { "id":27, "name":"cf_feedback", "label":"Feedback", "label_for_customers":"Feedback", "position":17, "type":"custom_text", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2020-01-27T07:12:48Z", "updated_at":"2020-01-27T07:12:48Z", "archived":false, "section_mappings":[ { "section_id":1, "position":3 } ] } # Dependent Field { "ticket_field":{ "id":28, "name":"cf_bank964807", "label":"Bank", "label_for_customers":"Bank", "position":13, "type":"nested_field", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2020-01-27T07:19:59Z", "updated_at":"2020-01-27T07:19:59Z", "archived":false, "choices":[ { "id":6, "position":1, "value":"HDFC", "parent_choice_id":28, "choices":[ { "id":7, "position":1, "value":"Chennai", "parent_choice_id":6, "choices":[ { "id":8, "position":1, "value":"Porur", "parent_choice_id":7, "choices":[ ] }, { "id":9, "position":2, "value":"OMR", "parent_choice_id":7, "choices":[ ] } ] }, { "id":10, "position":2, "value":"Madurai", "parent_choice_id":6, "choices":[ { "id":11, "position":1, "value":"Thirumangalam", "parent_choice_id":10, "choices":[ ] }, { "id":12, "position":2, "value":"SB Colony", "parent_choice_id":10, "choices":[ ] } ] } ] }, { "id":13, "position":2, "value":"SBI", "parent_choice_id":28, "choices":[ { "id":14, "position":1, "value":"Chennai", "parent_choice_id":13, "choices":[ { "id":15, "position":1, "value":"Tambaram", "parent_choice_id":14, "choices":[ ] }, { "id":16, "position":2, "value":"Guindy", "parent_choice_id":14, "choices":[ ] } ] }, { "id":17, "position":2, "value":"Trichy", "parent_choice_id":13, "choices":[ { "id":18, "position":1, "value":"AGS Colony", "parent_choice_id":17, "choices":[ ] } ] } ] }, { "id":19, "position":3, "value":"ICICI", "parent_choice_id":28, "choices":[ { "id":20, "position":1, "value":"Chennai", "parent_choice_id":19, "choices":[ { "id":21, "position":1, "value":"Avadi", "parent_choice_id":20, "choices":[ ] } ] } ] } ], "dependent_fields":[ { "id":29, "name":"cf_district", "label":"District", "label_for_customers":"District", "level":2, "ticket_field_id":28, "created_at":"2020-01-27T07:19:59Z", "updated_at":"2020-01-27T07:19:59Z" }, { "id":30, "name":"cf_branch53114", "label":"Branch", "label_for_customers":"Branch", "level":3, "ticket_field_id":28, "created_at":"2020-01-27T07:19:59Z", "updated_at":"2020-01-27T07:19:59Z" } ] } } |
View a Ticket Field
/api/v2/admin/ticket_fields/[id]
Sample code | Curl
1 2 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22?include=section' curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/16?include=section' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 | { "id":22, "name":"cf_issue_type_297457", "label":"Issue Type", "label_for_customers":"Issue Type", "position":1, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-19T05:28:31Z", "updated_at":"2019-12-19T05:28:31Z", "has_section":true, "sections":[ { "id":1, "label":"Ecosystem Type", "parent_ticket_field_id":22, "choice_ids":[ 6 ], "ticket_field_ids":[ 16 ] } ], "choices":[ { "id":125, "position":1, "value":"Refund", "parent_choice_id":22, "choices":[ ] }, { "id":126, "position":2, "value":"Faulty Product", "parent_choice_id":22, "choices":[ ] }, { "id":127, "position":3, "value":"Item Not Delivered", "parent_choice_id":22, "choices":[ ] } ] } { "id":16, "name":"cf_mobile_os_type", "label":"Mobile OS Type", "label_for_customers":"Mobile OS Type", "position":5, "type":"custom_text", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2020-01-03T09:45:03Z", "updated_at":"2020-01-03T09:45:15Z", "section_mappings":[ { "section_id":1, "position":1 } ] } |
Update a Ticket Field
/api/v2/admin/ticket_fields/[id]
To Edit the contents of a ticket field, use this API
JSON Parameters
Attribute | Type | Description |
---|---|---|
customers_can_edit | boolean | To specify whether the customer can edit the ticket field |
label_for_customers | string | Ticket Field name to be displayed to customers |
displayed_to_customers | boolean | Display Ticket Field to customers |
label | string | Display the name of the Ticket Field |
type | string | Ticket Field type. Can be custom_dropdown, custom_checkbox, custom_text, etc... |
position | number | Position in which the ticket field is displayed in the form. If not given, it will be displayed on top |
required_for_closure | boolean | Set to true if the field is mandatory for closing the ticket |
required_for_agents | boolean | Set to true if the field is mandatory for Agents |
required_for_customers | boolean | Set to true if the field is mandatory in the customer portal |
choices (Applicable for dropdown) | Array of dictionary | Array of key, value pairs containing the value and position of dropdown choices |
dependent_fields | Array of dictionary | Applicable only for dependent fields, this contains details of nested fields |
section_mappings | Array of dictionary | Applicable only if the field is part of a section. This contains the details of a section (ID, position) for which it is been a part of |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label_for_customers":"Issue Type", "label":"Issue Type", "position": 2, choices":[{ "deleted":true,"id":131 },{ "value":"Returns/Refund","id":129 },{ "value":"Faulty Product","id":130 },{ "value":"payments", "position":4 }] }' 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | { "id":23, "name":"cf_issue_type_dropdown", "label":"Issue Type", "label_for_customers":"Issue Type", "position":2, "type":"custom_dropdown", "default":false, "customers_can_edit":true, "required_for_closure":false, "required_for_agents":false, "required_for_customers":false, "displayed_to_customers":true, "created_at":"2019-12-19T06:14:40Z", "updated_at":"2019-12-19T06:56:07Z", "choices":[ { "id":129, "position":1, "value":"Returns/Refund", "parent_choice_id":23, "choices":[ ] }, { "id":130, "position":2, "value":"Faulty Product", "parent_choice_id":23, "choices":[ ] }, { "id":133, "position":3, "value":"Payments", "parent_choice_id":23, "choices":[ ] } ] } |
Delete a Ticket Field
/api/v2/admin/ticket_fields/[id]
Note: Be cautious about deleting a Ticket Field since this action is irreversible. You will not be able to restore a ticket field if you delete it.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22' |
Response
1 | HTTP Status: 204 No Content |
Sections
This feature helps you to configure custom sections/section-fields for your Ticket field.
JSON Parameters
Section Attributes | Description |
---|---|
id | ID of the section |
label | Display name of the section |
parent_ticket_field_id | Ticket Field ID to which the section is mapped |
ticket_field_ids | Ticket Field IDs associated with the section (Ticket fields that are displayed as part of the section) |
is_fsm | Set to true if the ticket field is a FSM field (Field Service Management) |
choice_ids | Set of Choice IDs mapped to the section. The section will be displayed on choosing any one of the choices |
List All Sections for a Ticket Field
/api/v2/admin/ticket_fields/[id]/sections
To view all section details related to a ticket field, use this API.
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/20/sections' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "sections":[ { "id":3, "label":"Environment Type (Mobile)", "parent_ticket_field_id":20, "choice_ids":[ 121 ], "ticket_field_ids":[ 19 ], "is_fsm":false }, { "id":4, "label":"Environment Type (Web)", "parent_ticket_field_id":20, "choice_ids":[ 120 ], "ticket_field_ids":[ ], "is_fsm":false } ] } |
Create a Section
/api/v2/admin/ticket_fields/[id]/sections
To create a new section, use the following APIs.
Parameters
Attribute | Type | Description |
---|---|---|
label | string | Display the name of the section |
choice_ids | Array of numbers | Choice IDs for which the section to be displayed |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "label":"Environment Type (Web)", "choice_ids":[120] }' https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "sections":[ { "id":3, "label":"Environment Type (Mobile)", "parent_ticket_field_id":20, "choice_ids":[ 121 ], "ticket_field_ids":[ 19 ], "is_fsm":false }, { "id":4, "label":"Environment Type (Web)", "parent_ticket_field_id":20, "choice_ids":[ 120 ], "ticket_field_ids":[ ], "is_fsm":false } ] } |
List a specific Section details
/api/v2/admin/ticket_fields/[id]/sections/[section_id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "section":{ "id":3, "label":"Environment Type (Web)", "parent_ticket_field_id":20, "choice_ids":[ 121 ], "ticket_field_ids":[ 19 ], "is_fsm":false } } |
Update a section
/api/v2/admin/ticket_fields/[id]/sections/[section_id]
To Edit the section, use this API
Parameters
Attribute | Type | Description |
---|---|---|
label | string | Display the name of the section |
choice_ids | Array of numbers | Choice IDs for which the section to be displayed |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label":"Environment Type (Mac OS)", "choice_ids":[134] }' 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "section":{ "id":3, "label":"Environment Type (Mac OS)", "parent_ticket_field_id":20, "choice_ids":[ 134 ], "ticket_field_ids":[ 19 ], "is_fsm":false } } |
Delete a section
/api/v2/admin/ticket_fields/[id]/sections/[section_id]
Note:
Be cautious about deleting a Section since this action is irreversible. You will not be able to restore a Section if you delete it.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/admin/ticket_fields/22/sections/3' |
Response
1 | HTTP Status: 204 No Content |
Ticket Forms
Note: Only users with admin privileges can access the following APIs.
Ticket forms allow you to show the right form to your customers depending on what they want to contact you about. You can create forms for different customer issues (eg: Returns, refunds, etc.), different product portals, or both.
JSON Parameters
Form Attributes | Description |
---|---|
id | ID of the ticket form |
title Mandatory | Name of the ticket form |
default | Set to true if the ticket form is the default form |
description | Description of the ticket form |
portals | Lists all the portals that are associated with the ticket form |
fields Mandatory | List of ticket fields which are added to the ticket form. Click here to see mandatory field attributes. |
last_updated_by | ID of the agent that last updated the form |
List All Ticket Forms
/api/v2/ticket-forms
Note:
The agent whose credentials (identified by the API key) are used to make the API call should be authorised to either view the ticket forms or create a new ticket form
Form Attributes
Form Attribute | Description |
---|---|
id | ID of the ticket form |
title | Name of the ticket form |
default | Set to true if the form is the default form |
description | Description of the ticket form |
portals | Lists all the portals that are associated with the ticket form |
widgets | Lists all the widgets that are associated with the ticket form |
last_updated_by | ID of the agent that last updated the form |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms?include=portals' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | [ { "id": 1, "name": "report_an_issue", "title": "Report an issue", "default": true, "description": "This form has all fields that customers can view or edit.", "created_at": "2022-05-25T10:43:01Z", "updated_at": "2022-06-01T10:21:34Z", "last_updated_by": 51020877290, "portals": [] }, { "id": 2, "name": "return_items", "title": "Return items", "default": false, "description": "Form to raise return requests on Acme portal", "created_at": "2022-05-27T10:33:34Z", "updated_at": "2022-05-31T10:06:26Z", "last_updated_by": 51020877290, "portals": [ { "id": 1, "name": "portal 1" } ] } ] |
Create a Ticket Form
/api/v2/ticket-forms
To create a new ticket form, use the following APIs.
Note: A form can not be created without the requester and company field
JSON Parameters
Attribute | Type | Description |
---|---|---|
title Mandatory | string | Name of the ticket form |
description | string | Description of the ticket form |
fields Mandatory | Array of dictionary | The fields the form should contain. Click here to see mandatory field attributes. |
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | # Custom ticket form curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "title": "Custom ticket form", "description": "This is a custom ticket form", "fields": [{ "id": 1, "label_for_customers": "requester", "customers_can_edit": true, "required_for_customers": true, "placeholder_for_customers": "requester", "hint_for_customers": "requester" }, { "id": 2, "label_for_customers": "company", "customers_can_edit": true, "required_for_customers": true, "placeholder_for_customers": "company", "hint_for_customers": "company" }] }' https://domain.freshdesk.com/api/v2/ticket-forms' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 | # custom ticket form { "id": 2, "name": "custom_ticket_form", "title": "Custom ticket form", "default": false, "description": "This is a custom ticket form", "created_at": "2022-06-01T14:10:59Z", "updated_at": "2022-06-01T14:10:59Z", "last_updated_by": 51020877290, "portals": [], "fields": [ { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "requester", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-06-01 14:10:59", "updated_at": "2022-06-01 14:10:59", "archived": false, "portal_cc": "false", "portal_cc_to": "company", "hint_for_customers": "requester", "placeholder_for_customers": "requester" }, { "id": 2, "name": "company", "label": "Company", "label_for_customers": "company", "position": 2, "type": "default_company", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-06-01 14:10:59", "updated_at": "2022-06-01 14:10:59", "archived": false, "hint_for_customers": "company", "placeholder_for_customers": "company" } ] } |
View a Ticket Form
/api/v2/ticket-forms/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | { "id": 2, "name": "return_items", "title": "Return items", "default": true, "description": "Form to raise return requests on Acme portal", "created_at": "2022-05-25T10:43:01Z", "updated_at": "2022-06-01T10:21:34Z", "last_updated_by": 51020877290, "portals": [], "fields": [ { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false, "portal_cc": "false", "portal_cc_to": "company" }, { "id": 2, "name": "subject", "label": "Subject", "label_for_customers": "Subject", "position": 2, "type": "default_subject", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false }, { "id": 3, "name": "status", "label": "Status", "label_for_customers": "Status", "position": 5, "type": "default_status", "default": true, "customers_can_edit": false, "required_for_closure": false, "required_for_agents": true, "required_for_customers": false, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false }, { "id": 4, "name": "agent", "label": "Agent", "label_for_customers": "Assigned to", "position": 8, "type": "default_agent", "default": true, "customers_can_edit": false, "required_for_closure": false, "required_for_agents": false, "required_for_customers": false, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false }, { "id": 5, "name": "description", "label": "Description", "label_for_customers": "Description", "position": 10, "type": "default_description", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false }, { "id": 6, "name": "company", "label": "Company", "label_for_customers": "Company", "position": 11, "type": "default_company", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-27 11:17:47", "archived": false } ] } |
Update a Ticket Form
/api/v2/ticket-forms/[id]
To edit the contents of a ticket form, use the following API
JSON Parameters
Attribute | Type | Description |
---|---|---|
title Mandatory | string | Name of the ticket form |
description | string | Description of the ticket form |
fields Mandatory | Array of dictionary | The fields the form should contain. Click here to see mandatory field attributes. |
Sample code | Curl
1 2 3 4 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "title": "Updated returns form", "description": "New returns form for summer sale" }' 'https://domain.freshdesk.com/api/v2/ticket-forms/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | { "id": 1, "name": "updated_returns_form", "title": "Updated returns form", "default": false, "description": "New returns form for summer sale", "created_at": "2022-05-31T06:53:48Z", "updated_at": "2022-06-01T14:31:25Z", "last_updated_by": 51020877290, "portals": [], "fields": [ { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester details", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-31 06:53:48", "updated_at": "2022-05-31 09:02:28", "archived": false, "portal_cc": "false", "portal_cc_to": null }, { "id": 2, "name": "company", "label": "Company", "label_for_customers": "Company", "position": 2, "type": "default_company", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-31 06:53:48", "updated_at": "2022-05-31 06:53:48", "archived": false } ] } |
Delete a Ticket Form
/api/v2/ticket-forms/[id]
Note: Be cautious about deleting a ticket form since this action is irreversible. You will not be able to restore a ticket form if you delete it.
Sample code | Curl
1 | curl -v -u yourapikey:X -X DELETE 'https://domain.freshdesk.com/api/v2/ticket-forms/2' |
Response
1 | HTTP Status: 204 No Content |
Clone a Ticket Form
/api/v2/ticket-forms/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/2/clone' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 | { "id": 3, "name": "copy_of_custom_ticket_form", "title": "Copy of custom ticket form", "default": false, "description": "", "created_at": "2022-05-25T10:43:01Z", "updated_at": "2022-06-01T10:21:34Z", "last_updated_by": 51020877290, "portals": [], "fields": [ { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false, "portal_cc": "false", "portal_cc_to": "company" }, { "id": 2, "name": "subject", "label": "Subject", "label_for_customers": "Subject", "position": 2, "type": "default_subject", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-25 10:43:01", "updated_at": "2022-05-25 10:43:01", "archived": false } ] } |
Ticket Form Fields
Note: Only users with admin privileges can access the following APIs.
The ticket form fields in Freshdesk have the following properties.
JSON Parameters
Form Fields | Description |
---|---|
id | ID of the form field |
name | Name of the form field |
label | Display name for the form field (as seen by agents) |
label_for_customers Mandatory | Display name for the form field (as seen in the customer portal) |
position | Position in which the form field is displayed in the form |
type | Details on whether the form field is a custom or a default field. If it is a custom field, details on the field type (dropdown, decimal, date, etc.) |
default | True if the form field is a default form field |
customers_can_edit Mandatory | Set to true if the form field can be updated by customers |
required_for_closure | Set to true if the form field is mandatory for closing the ticket |
required_for_agents | Set to true if the form field is mandatory for Agents |
required_for_customers Mandatory | Set to true if the form field is displayed in the portal |
displayed_to_customers | Set to true if the form field is displayed in the portal |
portal_cc | Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket |
portal_cc_to | Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list |
hint_for_customes Mandatory | Can see the tooltip for the form field in the form |
placeholder_for_customers Mandatory | Can see the placeholder for the form field in the form |
View A Ticket Form's Field
/api/v2/ticket-forms/[form-id]/fields/[field-id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/ticket-forms/1/fields/1' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester email", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-27 10:33:34", "updated_at": "2022-05-31 09:25:06", "archived": false, "portal_cc": null, "portal_cc_to": null, "hint_for_customers": "Requester email", "placeholder_for_customers": "Requester Email" } |
Update A Ticket Form's Field
/api/v2/ticket-forms/[form-id]/fields/[field-id]
To edit the contents of a ticket form field, use the following API
JSON Parameters
Attribute | Type | Description |
---|---|---|
id Mandatory * | Integer | ID of the ticket field (* mandatory only when creating a form) |
label_for_customers Mandatory | string | Name of the form field |
customers_can_edit Mandatory | boolean | Set to true if the field can be updated by customers |
required_for_customers Mandatory | boolean | Set to true if the field is displayed in the portal |
hint_for_customers Mandatory | string | Can see the tooltip for the form field in the form |
placeholder_for_customers Mandatory | string | Can see the placeholder for the form field in the form |
position | Integer | Position in which the form field is displayed in the form |
Sample code | Curl
1 2 3 4 5 6 7 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "label_for_customers": "Requester email", "customers_can_edit": true, "required_for_customers": true, "hint_for_customers": "Requester email", "placeholder_for_customers": "Requester Email" }' 'https://domain.freshdesk.com/api/v2/ticket-forms/2' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | { "id": 1, "name": "requester", "label": "Search a requester", "label_for_customers": "Requester email", "position": 1, "type": "default_requester", "default": true, "customers_can_edit": true, "required_for_closure": false, "required_for_agents": true, "required_for_customers": true, "displayed_to_customers": true, "created_at": "2022-05-27 10:33:34", "updated_at": "2022-05-31 09:25:06", "archived": false, "portal_cc": null, "portal_cc_to": null, "hint_for_customers": "Requester email", "placeholder_for_customers": "Requester Email" } |
Conversations
Conversations consist of replies as well as public and private notes added to a ticket. Notes are non-invasive ways of sharing updates about a ticket amongst agents and customers. Private notes are for collaboration between agents and are not visible to the customer. Public notes are visible to, and can be created by, both customers and agents.
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments associated with the conversation. The total size of all of a ticket's attachments cannot exceed 20MB. |
body | string | Content of the conversation in HTML |
body_text | string | Content of the conversation in plain text |
id | number | ID of the conversation |
incoming | boolean | Set to true if a particular conversation should appear as being created from outside (i.e., not through web portal) |
to_emails | array of strings | Email addresses of agents/users who need to be notified about this conversation |
private | boolean | Set to true if the note is private |
source | number | Denotes the type of the conversation. |
support_email | string | Email address from which the reply is sent. For notes, this value will be null. |
ticket_id | number | ID of the ticket to which this conversation is being added |
user_id | number | ID of the agent/user who is adding the conversation |
last_edited_at | datetime | Timestamp when the conversation last edited |
last_edited_user_id | number | ID of the agent who has last edited the conversation |
created_at | datetime | Conversation creation timestamp |
updated_at | datetime | Conversation updated timestamp |
Conversation Properties
Conversation use certain fixed numerical values to denote their Source. These numerical values along with their meanings are given below.
Note:
This source attribute will be returned in the response body of the List All Conversations of a Ticket and View a ticket (only when 'include=conversation' is passed in url) endpoints.
Source | Value | |
---|---|---|
Reply | 0 | |
Note | 2 | |
Created from tweets | 5 | |
Created from survey feedback | 6 | |
Created from Facebook post | 7 |
Source Type | Value | |
---|---|---|
Created from Forwarded Email | 8 | |
Created from Phone | 9 | |
E-Commerce | 11 |
Create a Reply
/api/v2/tickets/[id]/reply
Parameters
Attribute | Type | Description |
---|---|---|
body † | string | Content of the note in HTML format |
attachments | array of attachment objects | Attachments. The total size of all the ticket's attachments (not just this note) cannot exceed 20MB. |
from_email | string | The email address from which the reply is sent. By default the global support email will be used. |
user_id | number | ID of the agent who is adding the note |
cc_emails | array of strings | Email address added in the 'cc' field of the outgoing ticket email. |
bcc_emails | array of strings | Email address added in the 'bcc' field of the outgoing ticket email. |
† Mandatory attribute |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"We are working on this issue. Will keep you posted." }' 'https://domain.freshdesk.com/api/v2/tickets/141/reply' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | { "body_text" : "We are working on this issue. Will keep you posted.", "body" : "<div>We are working on this issue. Will keep you posted.</div>", "id" : 4, "user_id" : 1, "from_email" : "support@yourcompany.com", "cc_emails" : [ ], "bcc_emails" : [ ], "ticket_id" : 141, "replied_to" : [ "sample@yourcustomer.com" ], "attachments" : [ ], "created_at" : "2015-08-24T13:36:42Z", "updated_at" : "2015-08-24T13:36:42Z" } |
Reply to a Ticket With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.txt" -F "body=this is a sample reply" -X POST 'https://domain.freshdesk.com/api/v2/tickets/27/reply' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "body_text" : "this is a sample reply", "body" : "<div>this is a sample reply</div>", "id" : 125, "user_id" : 1, "from_email" : "support@yourcompany.com", "cc_emails" : [ ], "bcc_emails" : [ ], "ticket_id" : 27, "replied_to" : [ "sample@yourcustomer.com" ], "attachments" : [ { "id" : 6013284906, "content_type" : "text/plain", "size" : 98, "name" : "data.txt", "attachment_url" : "https://cdn.freshdesk.com/data/helpdesk/attachments/production/6013284906/original/attachment1.txt", "created_at" : "2016-01-13T07:07:41Z", "updated_at" : "2016-01-13T07:07:41Z" } ], "created_at" : "2016-01-13T07:07:41Z", "updated_at" : "2016-01-13T07:07:41Z" } |
Create a Note
/api/v2/tickets/[ticket_id]/notes
Note:
By default, any note that you add will be private. If you wish to add a public note, set the
Parameters
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments associated with the note. The total size of all of a ticket's attachments cannot exceed 20MB. |
body † | string | Content of the note in HTML |
incoming | boolean | Set to true if a particular note should appear as being created from outside (i.e., not through web portal). The default value is false |
notify_emails | array of strings | Email addresses of agents/users who need to be notified about this note |
private | boolean | Set to true if the note is private. The default value is true. |
user_id | number | ID of the agent/user who is adding the note |
† Mandatory attribute |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "private":false, "notify_emails":["tom@yourcompany.com"] }' 'https://domain.freshdesk.com/api/v2/tickets/3/notes' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "body_text" : "Hi tom, Still Angry", "body" : "<div>Hi tom, Still Angry</div>", "id" : 5, "incoming" : false, "private" : false, "user_id" : 1, "support_email" : null, "ticket_id" : 3, "notified_to" : ["tom@yourcompany.com"], "attachments" : [ ], "created_at" : "2015-08-24T13:49:37Z", "updated_at" : "2015-08-24T13:49:37Z" } |
Create a Note With Attachment
Note:
This API request must have its content-type set to multipart/form-data.
Sample code | Curl
1 | curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.ext" -F "body=Hi tom, Still Angry" -F "notify_emails[]=tom@yourcompany.com" -X POST 'https://domain.freshdesk.com/api/v2/tickets/20/notes' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "body_text" : "Hi tom, Still Angry", "body" : "<div>Hi tom, Still Angry</div>", "id" : 5, "incoming" : false, "private" : false, "user_id" : 1, "support_email" : null, "ticket_id" : 20, "notified_to" : ["tom@yourcompany.com"], "attachments" : [ { "id":4004881085, "content_type":"image/jpeg", "file_size":44115, "name":"attachment1.jpg", "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment1.jpg" "created_at":"2014-07-28T16:20:03+05:30", "updated_at":"2014-07-28T16:20:03+05:30", } ], "created_at" : "2015-08-24T13:49:37Z", "updated_at" : "2015-08-24T13:49:37Z" } |
Update a conversation
/api/v2/conversations/[id]
Note:
Only public & private notes can be edited.
Parameters
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments associated with the note. The total size of all of a ticket's attachments cannot exceed 20MB. |
body | string | Content of the note in HTML |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X PUT -d '{ "body":"Can you provide some screenshots?" }' 'https://domain.freshdesk.com/api/v2/conversations/5' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "body_text" : "Can you provide some screenshots?", "body" : "<div>Can you provide some screenshots?</div>", "id" : 5, "incoming" : false, "private" : false, "user_id" : 1, "support_email" : null, "ticket_id" : 20, "notified_to" : ["tom@yourcompany.com"], "attachments" : [ ], "created_at" : "2015-08-24T13:49:37Z", "updated_at" : "2015-08-24T13:49:37Z" } |
Update a conversation With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F "attachments[]=@/path/to/attachment1.txt" -F "body=updated conversation" -X PUT 'https://domain.freshdesk.com/api/v2/conversations/6' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | { "body_text" : "updated conversation", "body" : "updated conversation", "id" : 6, "incoming" : false, "private" : false, "user_id" : 1, "support_email" : null, "ticket_id" : 20, "attachments" : [ { "id":4004881085, "content_type":"image/jpeg", "file_size":44115, "name":"attachment1.jpg", "attachment_url":"https://cdn.freshdesk.com/data/helpdesk/attachments/production/4004881085/original/attachment1.txt" "created_at":"2014-07-28T16:20:03+05:30", "updated_at":"2014-07-28T16:20:03+05:30", } ], "created_at" : "2015-08-24T13:49:37+05:30", "updated_at" : "2014-07-28T16:20:03+05:30" } |
Reply to Forward
/api/v2/tickets/[id]/reply_to_forward
Attribute | Type | Description |
---|---|---|
body Mandatory | string | Content of the note in HTML format |
body_text | string | Content of the note in plain text |
user_id | number | ID of the agent/user who is replying to the forwarded email |
ticket_id | number | ID of the ticket to which the reply is added |
to_emails Mandatory | array of strings | Emails to which the reply is addressed |
Sample code | Curl
1 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "to_emails": ["user@company.com"]}' 'https://domain.freshdesk.com/api/v2/tickets/3/reply_to_forward' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "body":"<div>Hi tom, Still Angry</div>", "body_text":"Hi tom, Still Angry", "id":35131397084, "incoming":false, "private":true, "user_id":35008297863, "support_email":"support@supporttasks.freshdesk.com", "Source":2, "category":6, "ticket_id":3, "to_emails":["user@company.com"], "from_email":"\"Agent Bob\" <support@domain.freshdesk.com>", "cc_emails":[], "bcc_emails":[], "email_failure_count":null, "outgoing_failures":null, "created_at":"2020-08-24T06:05:34Z", "updated_at":"2020-08-24T06:05:34Z", "attachments":[], "deleted":false, "last_edited_at":null, "last_edited_user_id":null, "cloud_files":[], "has_quoted_text":true } |
View Account
/api/v2/account
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/account' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { organisation_id: 284960733419037820, organisation_name: "dailyplanet.myfreshworks.com", account_id: 1840509, account_name: "Daily Planet", account_domain: "dailyplanet.freshdesk.com", bundle_id: null, hipaa_compliant: false, total_agents: { full_time: 1, occasional: 1, field_service: 0, collaborators: 0 }, timezone: "Eastern Time (US & Canada)", data_center: "US", tier_type: "Forest", address: { country: USA, state: California, city: San Mateo CA , street: S. Delaware Street, postalcode: 94403 }, contact_person: { firstname: "Clark", lastname: "Kent", email: "clarkkent1@gmail.com" } } |
Export Account
api/v2/account/export
You can export your account data depending on the data which you specifically need. You can configure it based on created date range, resources and export format.
Note:
Only Account admin can access the following APIs.
Attribute | Type | Description |
---|---|---|
date_range | dictionary | Provide date range within which the data was created |
resources | Array of dictionary | Provide information about the resources that can be added to the export |
output_format | string | Format of export data. eg: "json" |
Date Range Attribute | Description | |
---|---|---|
start_date | Start date of export data. eg: 2020-04-21T13:03:00Z | |
end_date | End date of export data. eg: 2020-04-21T13:03:00Z |
Resources Attribute | Type | Description | |
---|---|---|---|
name | string | Resources to be included in export data eg. tickets, contacts | |
include | Array of String | Additional resources to be included within resource |
Resource Name | Allowed include parameters | |
---|---|---|
tickets | "notes", "attachments", "ticket_states", "schema_less_ticket", "requester" | |
archive_tickets | "notes", "attachments" | |
contacts | ||
companies | "company_domains" | |
groups | "agent_groups" | |
forums | "posts" | |
canned_responses | "all_canned_responses" | |
surveys | "survey_handles", "survey_results", "survey_questions" | |
solutions |
Sample code | Curl
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | curl -v -u yourapikey:X -H "Content-Type: application/json" -X POST -d '{ "date_range": { "start_date": "2020-04-21T13:03:00Z", "end_date": "2021-04-21T13:03:00Z" }, "resources": [ { "name": "tickets", "include": ["notes", "attachments", "ticket_states"] }, { "name": "archive_tickets", "include": ["notes", "attachments"] }, { "name": "contacts" }, { "name": "companies", "include": ["company_domains"] }, { "name": "groups", "include": ["agent_groups"] }, { "name": "forums", "include": ["posts"] }, { "name": "canned_responses", "include": ["all_canned_responses"] }, { "name": "surveys", "include": ["survey_handles", "survey_results", "survey_questions"] }, { "name": "solutions" } ], "output_format": "json" }' 'https://domain.freshdesk.com/api/v2/account/export' |
Response
1 2 3 4 5 6 7 8 9 | { "job" : { "id" : 432, "link": { "href" : "dailyplanet.freshdesk.com/api/v2/jobs/432", "method" : "GET" } } } |
View a Job
/api/v2/jobs/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/jobs/432' |
Response
1 2 3 4 5 6 7 8 9 | { "id" : "432", "name" : "ACCOUNT::EXPORT", "status" : "IN PROGRESS", "created_at" : "2015-08-28T11:47:58Z", "updated_at" : "2015-08-28T11:47:58Z", "status_updated_at" : "2015-08-28T11:47:58Z", "progress" : 80, } |
Contacts
A contact is a customer or a potential customer who has raised a support ticket through any channel.
Attribute | Type | Description |
---|---|---|
active | boolean | Set to true if the contact has been verified |
address | string | Address of the contact |
avatar | object | Avatar of the contact |
company_id | number | ID of the primary company to which this contact belongs |
view_all_tickets | boolean | Set to true if the contact can see all tickets that are associated with the company to which he belong |
custom_fields | dictionary | Key value pair containing the name and value of the custom fields. Read more here |
deleted | boolean | Set to true if the contact has been deleted. Note that this attribute will only be present for deleted contacts |
description | string | A short description of the contact |
string | Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute | |
id | number | ID of the contact |
job_title | string | Job title of the contact |
language | string | Language of the contact |
mobile | string | Mobile number of the contact |
name | string | Name of the contact |
other_emails | array of strings | Additional emails associated with the contact |
phone | string | Telephone number of the contact |
tags | array of strings | Tags associated with this contact |
time_zone | string | Time zone in which the contact resides |
twitter_id | string | Twitter handle of the contact |
unique_external_id | string | External ID of the contact |
other_companies | array of hashes | Additional companies associated with the contact |
created_at | datetime | Contact creation timestamp |
updated_at | datetime | Contact updated timestamp |
Create a Contact
/api/v2/contacts
Parameters
Attribute | Type | Description |
---|---|---|
nameMandatory | string | Name of the contact |
email *Unique | string | Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute. |
phone * | string | Telephone number of the contact |
mobile * | string | Mobile number of the contact |
twitter_id *Unique | string | Twitter handle of the contact |
unique_external_id *Unique | string | External ID of the contact |
other_emails | array of strings | Additional emails associated with the contact |
company_id | number | ID of the primary company to which this contact belongs |
view_all_tickets | boolean | Set to true if the contact can see all the tickets that are associated with the company to which he belong |
other_companies | array of hashes | Additional companies associated with the contact. This attribute can only be set if the Multiple Companies feature is enabled (Estate plan and above) |
address | string | Address of the contact. |
avatar | object | Avatar image of the contact The maximum file size is 5MB and the supported file types are .jpg, .jpeg, .jpe, and .png |
custom_fields | dictionary | Key value pairs containing the name and value of the custom field. Only dates in the format YYYY-MM-DD are accepted as input for custom date fields. Read more here |
description | string | A small description of the contact |
job_title | string | Job title of the contact |
language | string | Language of the contact. Default language is "en". This attribute can only be set if the Multiple Language feature is enabled (Garden plan and above) |
tags | array of strings | Tags associated with this contact |
time_zone | string | Time zone of the contact. Default value is the time zone of the domain. This attribute can only be set if the Multiple Time Zone feature is enabled (Garden plan and above) |
lookup_parameter | string | This attribute for contacts can only be set if the Custom Objects feature is enabled. The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
*One of these four attributes is mandatory |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "name":"Super Man", "email":"superman@freshdesk.com", "other_emails": ["lex@freshdesk.com", "louis@freshdesk.com"] }' 'https://domain.freshdesk.com/api/v2/contacts' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "active": false, "address": null, "company_id":23, "view_all_tickets":false, "deleted": false, "description": null, "email": "superman@freshdesk.com", "id": 432, "job_title": null, "language": "en", "mobile": null, "name": "Super Man", "phone": null, "time_zone": "Chennai", "twitter_id": null, "other_emails":["lex@freshdesk.com","louis@freshdesk.com"], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "created_at": "2015-08-28T09:08:16Z", "updated_at": "2015-08-28T09:08:16Z", "tags": [ ], "avatar": null } |
Create a contact with a custom object record associated
Note:
1.The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #12345, here the primary_field_value will be “12345”
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X POST -d '{ "name":"Super Man", "email":"superman@freshdesk.com", "other_emails": ["lex@freshdesk.com", "louis@freshdesk.com"], "lookup_parameter" : "primary_field_value", "custom_fields" : { "order_number" : "12345" } }' 'https://domain.freshdesk.com/api/v2/contacts' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | { "active": false, "address": null, "company_id":23, "view_all_tickets":false, "deleted": false, "description": null, "email": "superman@freshdesk.com", "id": 432, "job_title": null, "language": "en", "mobile": null, "name": "Super Man", "phone": null, "time_zone": "Chennai", "twitter_id": null, "other_emails":["lex@freshdesk.com","louis@freshdesk.com"], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "custom_fields":{ "order_number": "12345" }, "created_at": "2015-08-28T09:08:16Z", "updated_at": "2015-08-28T09:08:16Z", "tags": [ ], "avatar": null } |
Create a Contact With Avatar
Note:
1. This API request must have its content-type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F 'avatar=@/path/to/image.ext' -F 'name=Green Lantern' -F 'email=greenlantern@freshdesk.com' -X POST 'https://domain.freshdesk.com/api/v2/contacts' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | { "active":false, "address":null, "company_id":23, "view_all_tickets":false, "deleted":false, "description":null, "email":"greenlantern@freshdesk.com", "id":434, "job_title":null, "language":"en", "mobile":null, "name":"Green Lantern", "phone":null, "time_zone":"Chennai", "twitter_id":null, "other_emails":[ ], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z", "tags":[ ], "avatar":{ "avatar_url":"<AVATAR_URL>", "content_type":"application/octet-stream", "id":4, "name":"lantern.png", "size":13036, "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z" } } |
View a Contact
/api/v2/contacts/[id]
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X GET 'https://domain.freshdesk.com/api/v2/contacts/434' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | { "active": false, "address": null, "company_id":23, "view_all_tickets":false, "description": null, "email": "greenlantern@freshdesk.com", "id": 434, "job_title": null, "language": "en", "mobile": null, "name": "Green Lantern", "phone": null, "time_zone": "Chennai", "twitter_id": null, "other_emails": [], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "created_at": "2015-08-28T10:27:58Z", "updated_at": "2015-08-28T10:27:58Z", "custom_fields": { "department": "Operations" "fb_profile": null, "permanent": false }, "tags": [], "avatar": { "avatar_url": "<AVATAR_URL>", "content_type": "application/octet-stream", "id": 4, "name": "rails.png", "size": 13036, "created_at": "2015-08-28T10:27:58Z", "updated_at": "2015-08-28T10:27:58Z" } } |
List All Contacts
/api/v2/contacts
Use filters to view only specific contacts (those which match the criteria that you choose). The filters listed in the table below can also be combined
Note:
1. When using filters, the query string must be URL encoded
2. All unblocked and undeleted contacts will be returned by default
Filter by | Handle |
---|---|
email, mobile, phone |
/api/v2/contacts?<filter>=<value> Example: /api/v2/contacts?email=superman@freshdesk.com /api/v2/contacts?email=bat%2Bman%40gmail.com (URL encoded bat+man@gmail.com) /api/v2/contacts?mobile=7654367287 /api/v2/contacts?phone=4352789885 |
company_id | /api/v2/contacts?company_id=45653 |
state | /api/v2/contacts?state=[blocked/deleted/unverified/verified] |
updated since | /api/v2/contacts?updated_since=2018-01-19T02:00:00Z |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | [ { "active":false, "address":null, "company_id":null, "description":null, "email":"rachel@freshdesk.com", "id":2, "job_title":null, "language":"en", "mobile":null, "name":"Rachel", "phone":null, "time_zone":"Chennai", "twitter_id":null, "created_at":"2015-08-18T16:18:14Z", "updated_at":"2015-08-24T09:25:19Z", "other_companies": [ 4, 9, 10 ], "custom_fields":{ "department": "Admin" "fb_profile": null, "permanent": true } }, { "active":false, "address":null, "company_id":null, "deleted":false, "description":null, "email":"superman@freshdesk.com", "id":432, "job_title":null, "language":"en", "mobile":null, "name":"Super Man", "phone":null, "time_zone":"Chennai", "twitter_id":null, "created_at":"2015-08-28T09:08:16Z", "updated_at":"2015-08-28T09:08:16Z", "other_companies": [ 29, 30 ], "custom_fields":{ "department": "Production", "fb_profile": "https://www.facebook.com/superman.567384", "permanent": true }, }, { "active":false, "address":null, "company_id":null, "description":null, "email":"greenlantern@freshdesk.com", "id":434, "job_title":null, "language":"en", "mobile":null, "name":"Green Lantern", "phone":null, "time_zone":"Chennai", "twitter_id":null, "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z", "custom_fields":{ "department": "Operations" "fb_profile": null, "permanent": false } }, ... ] |
Additional Examples
1. Get a list of contacts filtered by the email address. Since the email address is unique, you will get only one contact in the list.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?email=superman@gmail.com' |
2. Get the first 20 verified contacts. By default, the contacts will be returned in alphabetical order.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?state=verified&per_page=20' |
3. Get a list of contacts updated after a particular timestamp.
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts?updated_since=2018-01-19T02:00:00Z' |
Search Contacts
/api/v2/contacts/autocomplete?term=[keyword]
Search for a contact using their name.
Note:
1. The search is case insensitive.
2. You cannot search with a substring. For example, a contact "John Jonz" can be looked up using "john", "Joh", "Jonz" and "jon". But it will not be returned when you search for "hn" or "nz".
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/contacts/autocomplete?term=John' |
Response
1 2 3 4 5 6 7 8 9 10 | [ { "id": 33, "name": "John Jonz" }, { "id": 456, "name": "John Steven Jonz" } ] |
Filter ContactsBETA
/api/v2/search/contacts?query=[query]
Use custom contact fields that you have created in your account to filter through the contacts and get a list of contacts matching the specified contact fields.
Note:
1. Deleted contacts will not be included in the results
2. The query must be URL encoded
3. Query can be framed using the name of the contact fields, which can be obtained from Contact Fields endpoint. Contact Fields are case sensitive
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
5. Logical operators AND, OR along with parentheses () can be used to group conditions
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
7. Input for date fields should be in UTC Format
8. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
9. To scroll through the pages add page parameter to the url. The page number starts with 1 and should not exceed 10
10. To filter for fields with no values assigned, use the null keyword
11. Please note that the updates will take a few minutes to get indexed, after which it will be available through API
Supported Contact Fields
Field | Type | Description |
---|---|---|
active | boolean | Set to true if the contact has been verified |
company_id | number | ID of the primary company to which this contact belongs |
twitter_id | string | Twitter handle of the contact |
string | Primary email address associated to the contact | |
phone | string | Telephone number of the contact |
mobile | string | Mobile number of the contact |
tag | string | Tag that has been associated to the contacts |
language | string | Language of the contact |
time_zone | string | Time zone in which the contact resides |
created_at | date | Contact creation date (YYYY-MM-DD) |
updated_at | date | Date (YYYY-MM-DD) when the contact was last updated |
Custom Fields | ||
Single line text | string | |
Number | integer | |
Checkbox | boolean | |
Dropdown | string |
Sample code | Curl
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true"' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "total":22, "results":[ { "active": true, "address": "11 Park Avenue,", "company_id": 331, "description": "alien hero", "email": "john@marsspace.com", "id": 112, "job_title": "Superhero", "language": "en", "mobile": "992339928", "name": "John Jonz", "phone": "+1992842882", "time_zone": "Eastern Time (US & Canada)", "twitter_id": "martian", "custom_fields": { "location": "Watch tower", "sector": "outer space" }, "created_at": "2017-07-19T12:29:36Z", "updated_at": "2017-07-19T12:38:26Z" }, ... ... ... ... ] } |
Additional Examples
1. Get the list of verified users associated to company 2331.
"active:true AND company_id:2331"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="active:true%20AND%20company_id:2331"' |
2. Get the list of users created in the first week of October 2017 in Chennai time zone.
"time_zone:'Chennai' AND (created_at:>'2017-10-01' AND created_at:<'2017-10-07')"
1 | curl -v -u yourapikey:X -X GET 'https://domain.freshdesk.com/api/v2/search/contacts?query="time_zone:%27Chennai%27%20AND%20(created_at:>%272017-10-01%27%20AND%20created_at:<%272017-10-07%27)"' |
Update a Contact
/api/v2/contacts/[id]
Parameters
Attribute | Type | Description |
---|---|---|
name | string | Name of the contact |
email Unique | string | Primary email address of the contact. If you want to associate additional email(s) with this contact, use the other_emails attribute. |
phone | string | Telephone number of the contact |
mobile | string | Mobile number of the contact |
twitter_id Unique | string | Twitter handle of the contact |
unique_external_id Unique | string | External ID of the contact |
other_emails | array of strings | Additional emails associated with the contact |
company_id | number | ID of the primary company to which this contact belongs |
view_all_tickets | boolean | Set to true if the contact can see all the tickets that are associated with the company to which he belong |
other_companies | array of hashes | Additional companies associated with the contact. This attribute can only be updated if the Multiple Companies feature is enabled (Estate plan and above) |
address | string | Address of the contact. |
avatar | object | Avatar image of the contact The maximum file size is 5MB and the supported file types are .jpg, .jpeg, .jpe, and .png |
custom_fields | dictionary | Key value pairs containing the name and value of the custom field. Only dates in the format YYYY-MM-DD are accepted as input for custom date fields. Read more here |
description | string | A small description of the contact |
job_title | string | Job title of the contact |
language | string | Language of the contact. Default language is "en". This attribute can only be updated if the Multiple Language feature is enabled (Garden plan and above) |
tags | array of strings | Tags associated with this contact |
time_zone | string | Time zone of the contact. Default value is the time zone of the domain. This attribute can only be updated if the Multiple Time Zone feature is enabled (Garden plan and above) |
lookup_parameter | string | This attribute for contacts can only be set if the Custom Objects feature is enabled. The value can either be in the form of the display_id (record id) or primary_field_value (user defined record value). The default value is display_id. |
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT -d '{ "name":"Clark Kent", "job_title":"Journalist", "other_emails": ["louis@freshdesk.com", "jonathan.kent@freshdesk.com"] }' 'https://domain.freshdesk.com/api/v2/contacts/432' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "active":false, "address":null, "company_id":23, "view_all_tickets":false, "deleted":false, "description":null, "email":"superman@freshdesk.com", "id":432, "job_title":"Journalist", "language":"en", "mobile":null, "name":"Clark Kent", "phone":null, "time_zone":"Chennai", "twitter_id":null, "other_emails":["louis@freshdesk.com","jonathan.kent@freshdesk.com"], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "created_at":"2015-08-28T09:08:16Z", "updated_at":"2015-08-28T11:37:05Z", "tags":[], "avatar":null } |
Update the lookup field within a contact
Note:
1. The lookup_parameter accepts either “display_id” (record ID) or “primary_field_value” (user defined record value)
2.The default value is “display_id”
3.The display_id can be found in the URL of the record. For example: “_0-1”
4.While the primary_field_value is defined by the user. For example: An ‘Order’ record can have an order number - #98765, here the primary_field_value will be “98765”
Sample code | Curl
1 | curl -v -u yourapikey:X -H 'Content-Type: application/json' -X PUT -d '{ "job_title":"Journalist", "lookup_parameter" : "primary_field_value", "custom_fields" : { "order_number" : "98765" } }' 'https://domain.freshdesk.com/api/v2/contacts/432' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | { "active": false, "address": null, "company_id":23, "view_all_tickets":false, "deleted": false, "description": null, "email": "superman@freshdesk.com", "id": 432, "job_title": "Journalist", "language": "en", "mobile": null, "name": "Super Man", "phone": null, "time_zone": "Chennai", "twitter_id": null, "other_emails":["lex@freshdesk.com","louis@freshdesk.com"], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "custom_fields":{ "order_number": "98765", }, "created_at": "2015-08-28T09:08:16Z", "updated_at": "2015-08-28T09:08:16Z", "tags": [ ], "avatar": null } |
Update a Contact With Avatar
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
Sample code | Curl
1 | curl -v -u yourapikey:X -F 'avatar=@/path/to/image.ext' -F 'job_title=Superhero' -X PUT 'https://domain.freshdesk.com/api/v2/contacts/434' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | { "active":false, "address":null, "company_id":23, "view_all_tickets":false, "deleted":false, "description":null, "email":"greenlantern@freshdesk.com", "id":434, "job_title":'Superhero', "language":"en", "mobile":null, "name":"Green Lantern", "phone":null, "time_zone":"Chennai", "twitter_id":null, "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z", "tags":[], "other_companies":[ { "company_id":25, "view_all_tickets":true }, { "company_id":26, "view_all_tickets":false } ], "avatar":{ "avatar_url":"<AVATAR_URL>", "content_type":"application/octet-stream", "id":4, "name":"lantern.png", "size":13036, "created_at":"2015-08-28T10:27:58Z", "updated_at":"2015-08-28T10:27:58Z" } } |
Soft Delete a Contact
/api/v2/contacts/[id]
Sample code | Curl
1 |