Introduction
The Freshservice API
Freshservice is a cloud-based IT Service Management solution that was designed using ITIL best practices. Freshservice helps IT organizations streamline their service delivery processes with a strong focus on user experience and employee happiness.
Freshservice'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 service desk. 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 Freshservice?
Freshservice 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 / Restore an object |
DELETE | Remove an object |
Note: All API requests should hit the secured endpoint i.e. only HTTPS
What's New?
Version 2 of the API brings several new features as well as changes to the previous APIs. This section highlights some of the new features introduced in v2.
- Higher rate limits as a result of significant performance enhancements
- Improved error handling - errors will return appropriate HTTP status codes and an error body
- 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
- Only JSON is supported in V2
- Only SSL calls (HTTPS) will be allowed
- Works only via Freshservice domains and not via custom CNAMEs
- Support for page sizes up to 100 has been added
Rate limit
Freshservice accounts created on or after 01-Sep-2020 will use minute-level rate limiting. The limits vary based on the Freshservice plan. Certain API operations also have sublimits within the overall limit. 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.
Action | Rate Limit/Min | |||
---|---|---|---|---|
Starter | Growth | Pro | Enterprise | |
Overall Limit | 100 | 200 | 400 | 500 |
Sub Limits | ||||
List All Tickets | 40 | 70 | 120 | 140 |
View Ticket | 50 | 80 | 140 | 160 |
Create Ticket | 50 | 80 | 140 | 160 |
Update Ticket | 50 | 80 | 140 | 160 |
List All Assets | 40 | 70 | 120 | 140 |
Update Asset | 50 | 80 | 140 | 160 |
List All Agents | 40 | 70 | 120 | 140 |
List All Requesters | 40 | 70 | 120 | 140 |
Accounts created before 01-Sep-2020 will eventually be migrated to minute-level rate limiting. The previous limits would continue to apply until the migration is completed.
PLAN | RATE LIMIT/HR |
---|---|
Starter | 1000 |
Growth | 2500 |
Pro | 5000 |
Enterprise | 7500 |
Note:
1. Please follow the best practices to stay under the rate limit.
2. If you need more than the default limit, please contact us.
3. Even invalid requests will count towards the rate limit.
4. Embedding additional resources will consume 1 credit if performed from a SHOW action, and 3 credits if performed from a LIST action.
5. Some custom apps (freshplugs) consume API calls which also count towards the rate limit.
You can check your current rate limit status by looking at the following HTTP headers which are returned in response to every API request.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Ratelimit-Total: 3000
X-Ratelimit-Remaining: 998
X-Ratelimit-Used-CurrentRequest: 1
X-Freshservice-Api-Version: latest=v2; requested=v2
HEADER NAME | DESCRIPTION |
---|---|
X-RateLimit-Total | Total number of API calls allowed per hour. |
X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. |
X-RateLimit-Used-CurrentRequest | The number of API calls consumed by the current request. Most API requests consume one call, however, including additional information in the response will consume more calls. |
Retry-After | The number in seconds that you will have to wait to fire your next API request. This header will be returned only when the rate limit has been reached. |
If your API request is received after the rate limit has been reached, Freshservice will return an error in the response. The Retry-After value in the response header will tell you how long you need to wait before you can send another API request.
HTTP/1.1 429
Content-Type: application/json; charset=utf-8
Retry-After: 1521
Policies
Freshservice APIs are classified into either production or beta APIs. A production API is one that has been made 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. Please note that the following policies apply to production APIs only.
Deprecation Policy
The scope of the V2 API is currently limited to only tickets and conversations. Once all modules are made available through the API, API V1 would be deprecated after a given notice period.
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
Sept 2017
- Initial version - V2 APIs for tickets and conversations
Authentication
Note: Username/Password-based authentication is not supported for accounts created after 31-Aug-2021.
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 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.freshservice.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.freshservice.com/api/v2/tickets'
Where can I find my API key?
- Login 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
Freshservice also uses Basic Access Authorization. This means that for authentication, you can use the same username and password that you use when you log in to your helpdesk.
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X 'GET https://domain.freshservice.com/api/v2/tickets'
Note:
If you are sure that your password and username are correct, but are still unable to access your helpdesk, make sure that your "username:password" (or "APIkey:X") is Base64-encoded before passing it as an "Authorization" header.
What are the resources available via the API?
Every single piece of information - be it a customer's ID or the priority of a specific ticket - can be identified by its own unique identifier or "URI". If you want your data from the helpdesk, whether via your smartphone app or via a third party service, you need this identifier. All URIs follow a specific format and that format is:
https://your_helpdesk_domain_name/api/v2/resource_name
For example, if you are the admin of the Freshservice portal "acmeinc.freshservice.com", then to access the tickets in your helpdesk, the syntax would be
https://acmeinc.freshservice.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.freshservice.com/api/v2/tickets
Will everyone have the same access rights?
No, everyone will not have the same access rights. Your ability to access data depends on the permissions available for your freshservice profile. If your freshservice Agent Role is "Newbie Agent" who is not allowed to answer to tickets, but is only allowed to view them, then the APIs will restrict you from answering and you'll only be able to view the tickets.
Schema
Blank Fields:
Blank fields are included as null instead of being omitted.
Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. ( Example : 2016-02-13T23:27:49Z )
Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm
If the time zone information is not present, it will be assumed to be in UTC.
( some valid datefields : 2016-02-15T21:16:25Z, 2012-12-24T12:56:15+05:30, 2010-03-23T12:00 )
For more details on date format : ISO 8601
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.freshservice.com/api/v2/tickets/1
Embedding
Our previous version of APIs returned a large number of fields by default. In order to increase performance and reduce data usage, we have removed several of these fields in our v2.0 APIs. For example, when you view a ticket, we no longer return the requester's name or the company name. However, there may be situations where these fields are required and hence, we have included a mechanism to embed additional resources into an API call in order to minimise the number of required API calls.
Note: Embedding resources into an API that returns a single object will consume an additional API call credit per embedded resource while embedding into APIs that return a collection of objects will consume two additional credits.
You can request for additional resources using the "include" keyword. For example you can embed the requester's details within the ticket view API by using the following command
Request
1 | curl -v -u 'abcdefgh12345678:X' -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=requester' |
Response
Attachments
Attachments are supported for the following endpoints
Please follow the guidelines listed below
- Only files on your local machine can be attached using API.
- The Content-Type should always be multipart/form-data for create/update requests with attachments.
- The name of the file is preserved after it is attached i.e the filename sent in the response will be the same as the one in the request.
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 for 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 Freshservice 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/Freshservice domain in the URL or an invalid URL itself. For example, an API call to retrieve a ticket with an invalid ID will return an 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 an 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. |
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 Freshservice domain has been exhausted. |
500 | Unexpected Server Error | You can't do much here. This indicates an error at Freshservice's side. Please email us your script which invokes our API, along with the response headers. We will work with you to fix the issue. |
Error Response
In addition to the HTTP status code, most errors will also return a response body that contains more information to help you debug the error. A sample error response is shown below. The format of the error response body is explained after the example.
Error Response Fields
FIELD | DESCRIPTION |
---|---|
field | The request field that triggered this error. Applicable to HTTP 400 errors only. |
message | Detailed error message. |
code | Custom error code that is machine-parseable. |
Error Codes
In addition to the the error message, the error response will also contain an 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 Ticket without the mandatory description 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. |
datatype_mismatch | Indicates that the field value doesn't match the expected data type. For instance, 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 since a specific feature has to be enabled in your Freshservice 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. |
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. |
Response
Pagination
API responses that return a list of objects, such as View List of Tickets are paginated. To scroll through the pages, add the parameter page to the query string. The page number starts with 1.
https://domain.freshservice.com/api/v2/tickets?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.freshservice.com/api/v2/tickets?per_page=10
The per_page and page parameters can also be used together. The following example will retrieve the 11th to 20th tickets.
https://domain.freshservice.com/api/v2/tickets?per_page=10&page=2
The 'link' header in the response will hold URL of the next page, if it exists. If you have reached the last page of objects, then the link header will not be set.
Headers:
"link":< https://domain.freshservice.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 needed.
Others
- Avoid making API calls directly from a mobile app. Instead, 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 Freshservice.
- When retrieving a list of objects, avoid making calls referencing page numbers over 500 (deep pagination). These are performance intensive calls and you may suffer from extremely long response times.
API Index
CATEGORY | CREATE | VIEW | VIEW LIST | UPDATE | DELETE | ||
---|---|---|---|---|---|---|---|
Tickets | Yes | Yes | Yes | Yes | Yes | ||
Conversations | Yes | No | Yes | Yes | Yes | ||
Requesters | Yes | Yes | Yes | Yes | Yes | ||
Agents | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
Roles | No | Yes | Yes | No | No | ||
Groups | Yes | Yes | Yes | Yes | Yes | ||
Locations | Yes | Yes | Yes | Yes | Yes | ||
Products | Yes | Yes | Yes | Yes | Yes | ||
Vendors | Yes | Yes | Yes | Yes | Yes | ||
Assets | Yes | Yes | Yes | Yes | Yes | ||
Asset Types | Yes | Yes | Yes | Yes | Yes |
Tickets
A ticket can be an incident or a service request. An incident is a disruption to an existing service, and a service request is a formal request from a user for something to be provided. Tickets are assigned to agents based on the agent's expertise and on the subject of the ticket.
Attribute | Type | Description |
---|---|---|
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 15MB. |
cc_emails | array of strings | Email addresses added in the 'cc' field of the incoming ticket email. |
department_id | number | ID of the department 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 Freshservice, 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) |
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 a result of the first response time being breached. |
fwd_emails | array of strings | Email addresses 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 Freshservice, 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. |
category | number | Ticket Category. |
sub_category | string | Ticket sub category. |
item_category | string | Ticket item category. |
reply_cc_emails | array of strings | Email addresses 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. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. [Support for only type ‘incident’ as of now] |
created_at | datetime | Ticket creation timestamp. |
updated_at | datetime | Ticket updated timestamp. |
urgency | number | Ticket urgency. |
impact | number | Ticket impact. |
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 Type | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 4 |
Feedback widget | 5 |
Yammer | 6 |
AWS Cloudwatch | 7 |
Pagerduty | 8 |
Walkup | 9 |
Slack | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Create a Ticket
This API helps you to create a new ticket in your service desk.
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 Freshservice, it will be added as a new contact. |
phone * | string | Phone number of the requester. If no contact exists with this phone number in Freshservice, 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. |
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 incident. * As of now, API v2 supports only type ‘incident’ |
status * | number | Status of the ticket. |
priority * | number | Priority of the ticket. |
description | string | HTML content of the ticket. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 15MB. |
cc_emails | array of strings | Email address added in the 'cc' field of the incoming ticket email. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved. |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
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 |
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 |
department_id | number | Department ID of the requester. |
category | string | Ticket category |
sub_category | string | Ticket sub category |
item_category | string | Ticket item category |
associate_ci | hash | Search for asset and associate with ticketTo be Deprecated |
assets | hash | List of assets associated with the ticket |
urgency | number | Ticket urgency |
impact | number | Ticket impact |
problem | hash | Problem that need to be associated with ticket (problem display id) |
change_initiating_ticket | hash | Change causing the ticket that needs to be associated with ticket (change display id) |
change_initiated_by_ticket | hash | Change needed for the ticket to be fixed that needs to be associated with ticket (change display id) |
* Refer to the 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 Status and Priorities. These numerical values along with their meanings are given below.
Source Type | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 4 |
Feedback widget | 5 |
Yammer | 6 |
AWS Cloudwatch | 7 |
Pagerduty | 8 |
Walkup | 9 |
Slack | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
/api/v2/tickets
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshservice.com","diana@freshservice.com"] }' -X POST 'https://domain.freshservice.com/api/v2/tickets' |
Response
Create a Ticket With Custom Fields
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshservice.com","diana@freshservice.com"], "custom_fields" : { "custom_text" : "This is a custom text box" } }' -X POST 'https://domain.freshservice.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 | { "ticket": { "cc_emails": [ "ram@freshservice.com", "diana@freshservice.com" ], "fwd_emails": [], "reply_cc_emails": [ "ram@freshservice.com", "diana@freshservice.com" ], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 1, "requester_id": 1000000675, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "to_emails": null, "department_id": null, "id": 265, "type": "Incident", "due_by": "2017-09-11T10:34:28Z", "fr_due_by": "2017-09-09T10:34:28Z", "is_escalated": false, "description": "<div>Details about the issue...</div>", "description_text": "Details about the issue...", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "custom_text": "This is a custom text box", "auto_checkbox": null }, "created_at": "2017-09-08T10:34:28Z", "updated_at": "2017-09-08T10:34:28Z", "tags": [], "attachments": [] } } curl -v -u user@yourcompany.com:test -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -F "status=2" -F "priority=3" -X POST '/tickets' |
Create 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 user@yourcompany.com:test -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'subject=Support Needed...' -F 'description=Details about the issue...' -F 'email=tom@outerspace.com' -F 'priority=1' -F 'status=2' -X POST 'https://domain.freshservice.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 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 1, "requester_id": 1232528431, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "to_emails": null, "department_id": null, "id": 51, "type": "Incident", "due_by": "2021-04-22T06:01:08Z", "fr_due_by": "2021-04-15T03:01:08Z", "is_escalated": false, "description": "<div>Details about the issue...</div>", "description_text": "Details about the issue...", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "new_number": null, "time_info": null, "number_test": null }, "created_at": "2021-04-12T06:01:08Z", "updated_at": "2021-04-12T06:01:08Z", "tags": [], "attachments": [ { "id": 368553, "content_type": "image/png", "size": 115399, "name": "api_attach.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api_attach.png", "created_at": "2021-04-12T06:01:08Z", "updated_at": "2021-04-12T06:01:08Z" } ] } } |
Create Ticket with assets
Note:
1. assets" key: contains comma (,) separated hash of the assets, each with key display id.
2. When "assets" is included as request parameter in PUT or POST request, the associated assets are returned implicitly in the response.
3. The existing request format to link a single asset ("associate_ci" : { "serial_no " : 123, "name " : "Andrea's Laptop " , "user ": "Andrea "}) will be deprecated soon.
4. If both "assets" and "associate_ci" keys are given in the request, assets key would be considered preferably and associate_ci would be ignored.
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "description": "Create ticket with assets linked", "status": 2, "email": "sample@freshservice.com", "priority": 1, "subject": "Create ticket with assets linked", "assets": [{ "display_id": 8 }, { "display_id": 9 }]}' -X POST 'https://domain.freshservice.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 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 1, "requester_id": 1, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Create ticket with assets linked", "to_emails": null, "department_id": null, "id": 433, "type": "Incident", "due_by": "2020-02-06T11:30:00Z", "fr_due_by": "2020-01-30T08:30:00Z", "is_escalated": false, "description": "<div>Create ticket with assets linked</div>", "description_text": "Create ticket with assets linked", "category": null, "sub_category": null, "item_category": null, "custom_fields": { }, "created_at": "2020-01-27T12:08:06Z", "updated_at": "2020-01-27T12:08:06Z", "tags": [], "attachments": [], "assets": [ { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null }, { "name": "Logitech Mouse", "description": null, "ci_type_id": 4, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 9, "salvage": null } ] } } |
Create Ticket with associations
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "problem": {"display_id": 2}, "change_initiating_ticket": {"display_id": 4}, "change_initiated_by_ticket": {"display_id": 5} }' -X POST 'https://domain.freshservice.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 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 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 1, "requester_id": 1232695482, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "to_emails": null, "department_id": null, "id": 78, "type": "Incident", "due_by": "2021-04-30T10:39:46Z", "fr_due_by": "2021-04-28T10:39:46Z", "is_escalated": false, "description": "<div>Details about the issue...</div>", "description_text": "Details about the issue...", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "deve": null, "locaite": null }, "created_at": "2021-04-27T10:39:46Z", "updated_at": "2021-04-27T10:39:46Z", "tags": [], "attachments": [], "problem": { "subject": "Unable to reach email server", "priority": 1, "status": 1, "impact": 1, "due_by": "2021-04-29T10:24:00Z", "display_id": 2, "requester_id": 1001536865, "owner_id": 1232265829, "group_id": null, "change_id": null, "deleted": false, "known_error": false, "created_at": "2021-04-27T10:25:20Z", "updated_at": "2021-04-27T10:25:20Z", "department_id": null, "email_config_id": null, "category": null, "sub_category": null, "item_category": null }, "change_initiating_ticket": { "display_id": 4, "requester_id": 1001536865, "owner_id": 1232265829, "group_id": null, "release_id": null, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "deleted": false, "subject": "Getting ES3 back up to speed", "created_at": "2021-04-27T10:26:54Z", "updated_at": "2021-04-27T10:26:54Z", "cc_email": {}, "planned_start_date": "2021-04-19T18:45:00Z", "planned_end_date": "2021-04-19T23:15:00Z", "department_id": null, "email_config_id": null, "category": null, "sub_category": null, "item_category": null }, "change_initiated_by_ticket": { "display_id": 5, "requester_id": 1001536865, "owner_id": 1232265829, "group_id": null, "release_id": null, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "deleted": false, "subject": "Upgrade Web Server", "created_at": "2021-04-27T10:28:48Z", "updated_at": "2021-04-27T10:28:48Z", "cc_email": {}, "planned_start_date": "2021-04-21T01:00:00Z", "planned_end_date": "2021-04-21T05:30:00Z", "department_id": 683112, "email_config_id": null, "category": null, "sub_category": null, "item_category": null } } } |
View a Ticket
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, tags 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 Conversationsof a Ticket API. |
requester | /api/v2/tickets/[id]?include=requester Will return requester details like id, name, mobile, phone |
requested_for | /api/v2/tickets/[id]?include=requested_for Will return details of the user on behalf of whom the request has been raised |
stats | /api/v2/tickets/[id]?include=stats Will return the ticket’s closed_at, resolved_at and first_responded_at time |
problem | /api/v2/tickets/[id]?include=problem Returns details of associated problem |
assets | /api/v2/tickets/[id]?include=assets Returns set of associated asset details |
change | /api/v2/tickets/[id]?include=change Returns associated change and causing change details |
related_tickets | /api/v2/tickets/[id]?include=related_tickets Returns child ticket ids / parent ticket ids based on ticket. No ids returned for parent tickets with no children |
/api/v2/tickets/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/20' |
Response
Additional examples
1. Get the associated conversations along with the ticket response.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=conversations' |
2. Get the associated tags and requester information along with the ticket response.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=tags,requester' |
3. Get the associated stats information along with the ticket response.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=stats' |
Filter Tickets
Custom ticket fields that you have created in your account can also be used to filter through the tickets and get a list of tickets matching the specified ticket fields.
Query Format(query) - "(ticket_field:integer OR ticket_field:'string') AND ticket_field:boolean"
Note:
1. The query must be URL encoded
2. Query can be framed using the ticket field name in snake case, which can be obtained from Ticket Fields endpoint. Ticket Fields are case sensitive
3. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
4. Logical operators AND, OR along with parentheses () can be used to group conditions
5. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
6. Input for date fields should be in UTC Format
7. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
8. To scroll through the pages add page parameter to the url
9. To filter for agent and group with no values assigned, use the null keyword
Supported Ticket Fields
Field | Type | Description |
---|---|---|
agent_id | number | ID of the agent to whom the ticket has been assigned |
group_id | number | ID of the group to which the ticket has been assigned |
priority | number | Priority of the ticket |
status | number | Status of the ticket |
impact | number | Ticket impact |
urgency | number | Ticket urgency |
tag | string | Tag 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) |
Custom Fields
Field Type | Type |
---|---|
Number | number |
Checkbox | boolean |
Dropdown | string |
Date | date(YYYY-MM-DD) |
Note:
Queries can be combined using AND or OR.
https://domain.freshservice.com/api/v2/tickets/filter?query="priority: 1 AND status: 2 OR urgency: 3"
Supported operators 1. priority: 1 (priority equal to 1)
2. priority:> 1 (priority greater than 1)
3. priority :< 1 (priority less than 1)
Formatting 1. String fields to be enclosed in single quotes ('')
2. Number fields to be given as number without quotes.
3. Date and date_time fields to be enclosed in single quotes('yyyy-mm-dd')
4. only :> and :< are supported for date and date_time fields. Both fields expect input in the same format as 'yyyy-mm-dd'
/api/v2/tickets/filter?query=[query]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="priority:3"' |
Response
Additional examples
1. Get the list of Urgent and High priority tickets ('priority:4 OR priority:3')
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?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 user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?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 user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="priority:>3%20AND%20group_id:11%20AND%20status:2"' |
4. Get the list of tickets having Custom Dropdown selected as First Choice or Custom Checkbox false (Custom Fields: custom_dropdown, custom_checkbox) '(custom_dropdown:'First Choice' OR custom_checkbox: true)'
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query=%22custom_dropdown:%27First%20Choice%27%20OR%20custom_checkbox:true%22 |
5. Get the list of Urgent priority tickets created after a particular day ("priority:4 AND created_at:>'2021-01-01'")
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query=%22%20priorIty:%203%20AND%20created_at:%3E%272020-01-01%27%20AND%20created_at:%3C%272021-01-01%27%22' |
6. Get list of tickets with tag abc ("tag: 'abc'")
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query=%22tag:%27abc%27%22' |
7. Get list of tickets with no agent assigned ('Responder_id: null')
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query=%agent_id:null%22' |
List All 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. 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 (1 credit for the API call, and 2 credits for the additional stats embedding).
Filter by | Handle |
---|---|
Predefined filters | /api/v2/tickets?filter=[filter_name] The filters available are new_and_my_open, watching, spam, deleted. |
Requester | /api/v2/tickets?requester_id=[id] /api/v2/tickets?email=[requester_email] Example: /api/v2/tickets?email=superman@freshservice.com /api/v2/tickets?email=bat%2Bman%40gmail.com (URL encoded bat+man@gmail.com) |
Updated since | /api/v2/tickets?updated_since=2015-01-19T02:00:00Z |
Type | For Incidents: /api/v2/tickets?type=Incident For Service Requests: /api/v2/tickets?type=Service+Request |
Sort by | Handle |
---|---|
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. |
Requested For | /api/v2/tickets?include=requested_for Will return details of the user on behalf of whom the request has been raised |
/api/v2/tickets
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets' |
Response
Additional examples
1. Get the first page of a list of tickets that are being watched by the agent whose credentials were used to make this API call.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets?filter=watching' |
2. Get the first page of a list of tickets from the specified requestor. The tickets will be returned in the descending order.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets?requester_id=1230&order_type=desc' |
3. Get the second page (tickets from 11-20) of a list of all tickets.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets?per_page=10&page=2' |
4. Get the first page of a list of tickets that have shown any activity since the 17th of August, 2015.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets?updated_since=2015-08-17' |
5. Get the associated stats information along with the ticket response.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets?include=stats' |
6. Filter tickets based on the following requester email (super+man@gmail.com) which needs to be URL encoded.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets?email=super%2Bman%40gmail.com' |
Update a Ticket
This API lets you make changes to the parameters of a ticket from updating statuses to changing ticket type.
Note:
While updating tags, all the tags that need to stay associated with the Ticket should be provided in the PUT request payload.
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 Freshservice, it will be added as a new contact. | |
phone | string | Phone number of the requester. If no contact exists with this phone number in Freshservice, 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. |
subject | string | Subject of the ticket. The default value is null. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is null. |
status * | number | Status of the ticket. The default Value is 2. |
priority * | number | Priority of the ticket. The default value is 1. |
description | string | HTML content of the ticket. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 15MB. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
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. |
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. |
associate_ci | Hash | Search for asset and associate with ticketTo be Deprecated |
assets | Hash | List of assets associated with the ticket |
associate_problem_id | number | Associate this problem id to ticketTo be Deprecated |
urgency | number | Ticket urgency |
impact | number | Ticket impact |
category | String | Ticket category |
sub_category | String | Ticket sub-category |
item_category | String | Ticket item category |
department_id | number | Department ID of the requester. |
problem | hash | Problem need to be associated with ticket display_id: problem display id |
change_initiating_ticket | hash | Ticket causing change need to be associated display_id: change display id |
change_initiated_by_ticket | hash | Change need to be associated with ticket display_id: change 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 Type | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 4 |
Feedback widget | 5 |
Yammer | 6 |
AWS Cloudwatch | 7 |
Pagerduty | 8 |
Walkup | 9 |
Slack | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
/api/v2/tickets/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "priority": 3 }' 'https://domain.freshservice.com/api/v2/tickets/1' |
Response
Response
1 | curl -v -u user@yourcompany.com:test -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -F "status=2" -F "priority=3" -X POST '/tickets' |
Update 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 user@yourcompany.com:test -F 'attachments[]=@/Users/user/Desktop/api2.png' -F 'priority=1' -X PUT 'https://domain.freshservice.com/api/v2/tickets/51' |
Response
1 2 3 4 5 6 7 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 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "spam": false, "email_config_id": null, "fr_escalated": false, "group_id": null, "priority": 1, "requester_id": 1232528431, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "description": "<div>Details about the issue...</div>", "description_text": "Details about the issue...", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "new_number": null, "time_info": null, "number_test": null }, "id": 51, "type": "Incident", "to_emails": null, "department_id": null, "is_escalated": false, "tags": [], "due_by": "2021-04-22T06:01:08Z", "fr_due_by": "2021-04-15T03:01:08Z", "created_at": "2021-04-12T06:01:08Z", "updated_at": "2021-04-12T06:01:08Z", "attachments": [ { "id": 368553, "content_type": "image/png", "size": 115399, "name": "api_attach.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api_attach.png", "created_at": "2021-04-12T06:01:08Z", "updated_at": "2021-04-12T06:01:08Z" }, { "id": 368554, "content_type": "image/png", "size": 274688, "name": "api2.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api2.png", "created_at": "2021-04-12T06:26:40Z", "updated_at": "2021-04-12T06:26:40Z" } ] } } |
Update Ticket with assets
Note:
1. Existing assets, if they are different from what are given in request, are destroyed and the current ones are linked to the ticket. So, all the assets that need to stay associated with the Ticket need to be provided in the PUT/POST calls
2. "assets" key: contains comma (,) separated hash of the assets, each with key display id.
3. When "assets" is included as request parameter in PUT or POST request, the associated assets are returned implicitly in the response.
4. The existing request format to link a single asset ("associate_ci" : { "serial_no " : 123, "name " : "Andrea's Laptop " , "user ": "Andrea "}) will be deprecated soon.
5. If both "assets" and "associate_ci" keys are given in the request, assets key would be considered preferably and associate_ci would be ignored.
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "description": "Update ticket with assets", "status": 2, "email": "sample@freshservice.com", "priority": 1, "subject": "Update ticket with assets", "assets": [ { "display_id": 7 }, { "display_id": 8 }]}' 'https://domain.freshservice.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 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 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "spam": false, "email_config_id": null, "fr_escalated": false, "group_id": null, "priority": 1, "requester_id": 1, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Update ticket with assets", "description": "Update ticket with assets", "description_text": "Update ticket with assets", "category": null, "sub_category": null, "item_category": null, "custom_fields": {}, "id": 433, "type": "Incident", "to_emails": null, "department_id": null, "is_escalated": false, "tags": [], "due_by": "2020-02-06T17:00:00+05:30", "fr_due_by": "2020-01-30T14:00:00+05:30", "created_at": "2020-01-27T12:08:06Z", "updated_at": "2020-01-27T12:13:39Z", "attachments": [], "assets": [ { "name": "Andrea's Laptop", "description": null, "ci_type_id": 25, "impact": 2, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": 2, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 7, "salvage": null }, { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null } ] } } |
Delete a Ticket
This API helps you delete a ticket.
Note: Deleted tickets are not permanently lost. You can retrieve them using the Restore Ticket API.
/api/v2/tickets/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/tickets/1' |
Response
Delete a Ticket Attachment
This API helps you delete an attachment from a ticket.
/api/v2/tickets/[ticket_id]/attachments/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/tickets/1/attachments/1' |
Response
Restore a Ticket
The API mentioned previously. If you deleted some tickets and regret doing so now, this API will help you restore them.
/api/v2/tickets/[id]/restore
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshservice.com/api/v2/tickets/1/restore' |
Response
Create a Child Ticket
This API lets you to create a new child ticket on an existing ticket
Note:
1. Association of child tickets is not available in the Sprout plan.
2. Association of child tickets to a service request is not possible.
3. Association of child tickets to a deleted or a spammed ticket is not allowed.
4. Nesting of a child ticket under another child ticket is not supported.
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 Freshservice, it will be added as a new contact. |
phone * | string | Phone number of the requester. If no contact exists with this phone number in Freshservice, 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. |
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 incident. * As of now, API v2 supports only type ‘incident’ |
status * | number | Status of the ticket. |
priority * | number | Priority of the ticket. |
description | string | HTML content of the ticket. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 15MB. |
cc_emails | array of strings | Email address added in the 'cc' field of the incoming ticket email. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved. |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
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 |
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 |
department_id | number | Department ID of the requester. |
category | string | Ticket category |
sub_category | string | Ticket sub category |
item_category | string | Ticket item category |
associate_ci | hash | Search for asset and associate with ticket |
urgency | number | Ticket urgency |
impact | number | Ticket impact |
* Refer to the 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 Status and Priorities. These numerical values along with their meanings are given below.
Source Type | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 4 |
Feedback widget | 5 |
Yammer | 6 |
AWS Cloudwatch | 7 |
Pagerduty | 8 |
Walkup | 9 |
Slack | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
/api/v2/tickets/[parent_id]/create_child_ticket
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshservice.com","diana@freshservice.com"] }' -X POST 'https://domain.freshservice.com/api/v2/tickets/20/create_child_ticket' |
Response
List All Ticket Fields (Old)
Note: This API is going to be deprecated by June 30th 2020. Please refer to the new List All Ticket Fields (New) API.
This API lets you view the fields in a ticket.
Note: The agent whose credentials (API key or username/password) are being used to make this API call should be authorised to either view the ticket fields or create a new ticket.
Ticket Fields
Ticket field | Description |
---|---|
id | ID of the ticket field |
default | Set to true if the field is not a custom field |
description | Description of the ticket field |
label | Display name for the field (as seen by agents) |
name | Name of the ticket field |
position | Position in which the ticket field is displayed in the form |
required_for_closure | Set to true if the field is mandatory for closing the ticket |
type | For custom ticket fields, type of value associated with the field will be given (Examples custom_date, custom_text...) |
required_for_agents | Set to true if the field is mandatory for Agents |
required_for_customers | Set to true if the field is mandatory in the customer portal |
label_for_customers | Display name for the field (as seen in the customer portal) |
customers_can_edit | Set to true if the field can be updated by customers |
displayed_to_customers | Set to true if the field is displayed in the customer portal |
portal_cc | Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket |
portal_cc_to | Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list |
choices | List of values supported by the field |
nested_ticket_fields | Applicable only for dependent fields, this contain details of nested fields (see the sample response given below) |
To view only specific ticket fields (that is, those which match only the criteria you choose) use the filters given below.
Filter by | Handle |
---|---|
type | /api/v2/ticket_fields?type=[type] |
/api/v2/ticket_fields
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/ticket_fields' |
Response
Additional examples
1. List the ticket_field that is of type 'default_requester'
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/ticket_fields?type=default_requester' |
Response
List All Ticket Fields (New)
Retrieve all the Fields that constitute the Ticket Object
Ticket Fields
Change field | Description |
---|---|
id | Unique ID of the Field |
created_at | Date time at which the field was added |
updated_at | Date time at which the field was modified |
name | Name of the field |
label | Label of the field for display |
description | Description of the field |
field_type | Indicates if the field is a checkbox, dropdown, text field |
required | True if the field is marked mandatory |
required_for_closure | True if the field is marked mandatory while closing the Release item |
default_field | True if the field is a default field. False if customm |
choices | List of values supported by the field |
nested_fields | contain details of nested fields |
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 |
date_only | Applicable only for custom_date field. When ‘Request time information’ is selected, the field date_only returns false and if unchecked, date_only returns true |
/api/v2/ticket_form_fields
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/ticket_form_fields' |
Response
Get Ticket Activites
/api/v2/tickets/[id]/activities
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/api/v2/tickets/152/activities |
Response
Time Entries
These APIs help to track exactly how much time an agent has spent on each ticket, start/stop timers and perform a lot of other time tracking and monitoring tasks to ensure that the support team is always performing at its peak efficiency.
Attribute | Type | Description |
---|---|---|
id | Number | Id of the time entry READ-ONLY |
created_at | DateTime | Time at which this time-entry is created READ-ONLY |
updated_at | DateTime | Time at which the time-entry is updated READ-ONLY |
start_time | DateTime | The time at which the time-entry is added. If a timer, which is in stopped state, is started again, this holds date_time at which the timer is started again READ-ONLY |
timer_running | Boolean | Set to true if timer is currently running. Default value is false. At a time, only one timer can be running for an agent across the account |
billable | Boolean | Set as true if the time-entry is billable. Default value is true |
time_spent | String | The total amount of time spent by the timer in hh::mm format. This field cannot be set if timer_running is true. Mandatory if timer_running is false |
executed_at | DateTime | Time at which the timer is executed. Default value (unless given in request) is the time at which timer is added. Should be less than or equal to current date_time |
task_id | Number | Id of the task assigned to the time-entry. Task should be valid on the given ticket and assigned to agent_id |
note | String | Description of the time-entry |
agent_id | Number | The user/agent to whom this time-entry is assigned MANDATORY |
Create a Time Entry
This API helps to create a Time Entry.
Note:
1. If timer_running is not specified in the request, it is considered as false and time_spent is mandatory in this scenario.
2. time_spent can be set only if timer_running is false or not set.
/api/v2/tickets/[ticket_id]/time_entries
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{"time_entry":{"note":"test_entry","time_spent":"03:00","agent_id":1}}' -X POST 'https://domain.freshservice.com/api/v2/tickets/1/time_entries' |
Response
Additional examples
1. Create a time-entry along with time spent value. Timer will not be started
1 | curl -v -u user@yourcompany.com:test -H 'Content-Type: application/json' -d '{"time_entry":{"note":"test_entry","time_spent":"03:00","agent_id":1}}' -X POST 'https://domain.freshservice.com/api/v2/tickets/1/time_entries' |
2. Create a time-entry with timer running
1 | curl -v -u user@yourcompany.com:test -H 'Content-Type: application/json' -d '{"time_entry":{"note":"test_entry","timer_running":true,"agent_id":1}}' -X POST 'https://domain.freshservice.com/api/v2/tickets/1/time_entries' |
View a Time Entry
This API call helps to list a particular Time Entry.
/api/v2/tickets/[ticket_id]/time_entries/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/time_entries/20' |
Response
List All Time Entries of a Ticket
This API helps to view all time entries of a particular ticket.
/api/v2/tickets/[ticket_id]/time_entries
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/time_entries' |
Response
Update a Time Entry
This API can be used to update/modify existing time entry.
Note:
1. For a running timer, time_spent cannot be updated without stopping it.
Attribute | Type | Description |
---|---|---|
id | Number | Id of the time entry READ-ONLY |
created_at | DateTime | Time at which this time-entry is created READ-ONLY |
updated_at | DateTime | Time at which this time-entry is updated READ-ONLY |
start_time | DateTime | The time at which the time-entry is added. If a timer, which is in stopped state, is started again, date_time at which the timer is started again READ-ONLY |
timer_running | Boolean | Cannot update timer_running to the same existing value. |
billable | Boolean | Can be set to true or false |
time_spent | String | The total amount of time spent by the timer in hh::mm format. |
executed_at | DateTime | Time at which the timer is executed. Default value (unless given in request) is the time at which timer is added. Should be less than or equal to current date_time. |
task_id | Number | Id of the task assigned to the time-entry. Task should be valid on the given ticket and should be assigned to the agent_id |
note | String | Description of the time-entry |
agent_id | Number | The user/agent to whom this time-entry is to be assigned MANDATORY |
/api/v2/tickets/[ticket_id]/time_entries/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{"time_entry":{"note":"text_update","agent_id":1}}' 'https://domain.freshservice.com/api/v2/tickets/1/time_entries/20' |
Response
Delete a Time Entry
This API can be used to delete an existing Time Entry. Deleted time entries cannot be restored.
/api/v2/tickets/[ticket_id]/time_entries/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE 'https://domain.freshservice.com/api/v2/tickets/1/time_entries/20' |
Response
Create a Source
This API helps you create a new Ticket Source.
Attribute | Type | Description |
---|---|---|
name | string | Name of the source |
/api/v2/ticket_fields/sources
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "name": "Source Name" }' -X POST 'https://domain.freshservice.com/api/v2/ticket_fields/sources' |
Response
Service Request
This section lists all API that are related to service requests
Create a Service Request
This API helps you create a service request
Note 1:
The service requested will be created with the requester specified in “email” attribute. If no email is provided, the request is created on behalf of the agent
Note 2:
Fields in the API behave like the agent portal's new service request page. If a field is not visible in self service portal, you can still provide a value for that field using the api. If a field is marked mandatory but not visible in portal in service item, you must provide a value for it in the api.
Request Attrubutes
Attribute | Type | Description |
---|---|---|
quantity | number | Quantity needed by the requested |
requested_for | Email id of the requester on whose behalf the service request is created | |
Email id of the requester | ||
child_items | - | Service items that are included as child items. Provide the display id as service_item_id for each child item. |
custom_fields | - | Values of custom fields present in the service item form |
Response Attrubutes
Attribute | Type | Description |
---|---|---|
Ticket Attributes | - | Refer to Ticket attributes for complete list here |
requested_items | - | Items requested as part of service request |
approval_status | number | Current approval status of the service request. ‘1’ if approved, ‘2’ if rejected |
approval_status_name | string | Display name of the approval status |
custom_fields | - | Custom fields present in the ticket form |
/api/v2/service_catalog/items/{display_id}/place_request
Request
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | { "quantity": 1, "email": "sample@freshservice.com", "custom_fields":{ "hello" : "test", "link" : "https://freshservice.com/" }, "child_items" : [{ "service_item_id": 22, "quantity": 1, "custom_fields" : { "child_1": "test" } }] } |
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{"email": "tom@outerspace.com", “quantity” : 1 }' -X POST 'https://domain.freshservice.com/api/v2/service_catalog/items/1/place_request' |
Response
View Requested Items of a Service Request
This api helps you to view requested items attached to a service request
Attribute | Type | Description |
---|---|---|
id | number | Unique id of the requested item |
created_at | datetime | Timestamp at which the requested item was attached to service request |
updated_at | datetime | Timestamp at which the requested item was updated in the service request |
quantity | number | Number of units of the item needed by the requester. By default it is 1 |
stage | number | Current stage of the requested item |
loaned | boolean | Indicated whether the requested item is a loaner item |
cost_per_request | number | Cost of the requested service item |
remarks | string | Remarks related to a requested item |
delivery_time | number | Estimated delivery time (in hrs) |
is_parent | boolean | Boolean indicating whether this is the parent service item |
service_item_id | number | Display id of service item unique to your account |
Stages
Stage | Value |
---|---|
Requested | 1 |
Delivered | 2 |
Cancelled | 3 |
Fulfilled | 4 |
Partially Fulfilled | 5 |
/api/v2/tickets/[id]/requested_items
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/requested_items' |
Response
Update Requested Items of a Service Request
This api helps you to update the requested items attached to a service request
/api/v2/tickets/[id]/requested_items/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{"quantity":2, "stage":2, "custom_fields":{"additional_property_1": "value1"}}' 'https://domain.freshservice.com/api/v2/tickets/1/requested_items/1' |
Response
Tasks
This section lists all API that can be used to create, edit or otherwise manipulate Ticket Tasks.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the task. |
agent_id | number | Id of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | DateTime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
created_at | DateTime | Timestamp at which the task was created |
updated_at | DateTime | Timestamp at which the task was updated |
closed_at | DateTime | Timestamp at which the task was closed |
group_id | number | Unique ID of the group to which the task is assigned |
Create a Task
Create a new task on a ticket request in freshservice
/api/v2/tickets/[id]/tasks
Sample code | Curl
1 2 3 4 5 6 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "due_date": "2020-04-03T10:26:13.067Z", "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!" }' -X POST 'https://domain.freshservice.com/api/v2/tickets/1/tasks' |
Response
View a Task
Retrieve a task on a Ticket with the given ID from Freshservice
api/v2/tickets/[id]/tasks/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/tasks/1' |
Response
View all Tasks
Retrieve the tasks on a Ticket with the given ID from Freshservice.
/api/v2/tickets/[id]/tasks
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/1/tasks' |
Response
Update a Task
Update an existing task on an existing Ticket in Freshservice
/api/v2/tickets/[id]/tasks/[id]
Sample code | Curl
1 2 3 4 5 6 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "status": 3, "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!" }' 'https://domain.freshservice.com/api/v2/tickets/1/tasks/1' |
Response
Delete a Task
Delete the task on a Ticket with the given ID from Freshservice
Note: Deleted tasks are permanently lost. You can't retrieve them once it's get deleted.
/api/v2/tickets/[id]/tasks/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/tickets/1/tasks/1' |
Response
CSAT
This section lists all API that can be used to view Ticket CSAT Response.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the survey response. |
overall_rating_text | string | Overall feedback text of the survey response |
overall_rating | number | Feedback code of the survey response |
primary_question | string | Primary survey question |
questionnaire_responses | array of hashes | Contains the list of responded questions and answer(s) chosen.
|
created_at | DateTime | Timestamp at which the survey response was created |
updated_at | DateTime | Timestamp at which the survey response was updated |
CSAT Response
Retrieve a csat response of a Ticket with the given ID from Freshservice
/api/v2/tickets/id]/csat_response
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/csat_response' |
Response
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 requesters. Private notes are for collaboration between agents and are not visible to the requester. Public notes are visible to, and can be created by, both requesters and agents.
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments associated with the conversation. The total size of all of a ticket's attachments cannot exceed 15MB. |
body | string | Content of the conversation in HTML |
body_text | string | Content of the conversation in plain text |
id | number | ID of the conversation |
incoming | boolean | Set to true if a particular conversation should appear as being created from the outside (i.e., not through the web portal) |
to_emails | array of strings | Email addresses of agents/users who need to be notified about this conversation |
private | boolean | Set to true if the note is private |
source | number | Denotes the type of the conversation. |
support_email | string | Email address from which the reply is sent. For notes, this value will be null. |
ticket_id | number | ID of the ticket to which this conversation is being added |
user_id | number | ID of the agent/user who is adding the conversation |
created_at | datetime | Conversation creation timestamp |
updated_at | datetime | Conversation updated timestamp |
Conversation Properties
Conversations 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 Type | Value |
---|---|
0 | |
form | 1 |
note | 2 |
status | 3 |
meta | 4 |
feedback | 5 |
forward_email | 6 |
Create a Reply
Attribute | Type | Description |
---|---|---|
body * | string | Content of the note in HTML format |
attachments | array of attachment objects | Attachments. The total size of all the ticket's attachments (not just this note) cannot exceed 15MB. |
from_email | string | The email address from which the reply is sent. By default the global support email will be used. |
user_id | number | ID of the agent/user who is adding the note |
cc_emails | array of strings | Email address added in the 'cc' field of the outgoing ticket email. |
bcc_emails | array of strings | Email address added in the 'bcc' field of the outgoing ticket email. |
* Mandatory attribute |
/api/v2/tickets/[id]/reply
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "body":"We are working on this issue. Will keep you posted." }''https://domain.freshservice.com/api/v2/tickets/141/reply' |
Response
Reply to a Ticket With Attachments
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 user@yourcompany.com:test -F 'attachments[]=@/Users/user/Desktop/api2.png' -F 'body=We are working on this issue. Will keep you posted.' -X POST 'https://domain.freshservice.com/api/v2/tickets/51/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 27 28 | { "conversation": { "id": 4289865, "user_id": 1232463344, "from_email": "user@yourcompany.com", "cc_emails": [], "bcc_emails": [], "body": "<div>We are working on this issue. Will keep you posted.</div>", "body_text": "We are working on this issue. Will keep you posted.", "ticket_id": 51, "to_emails": [ "tom@outerspace.com" ], "attachments": [ { "id": 368557, "content_type": "image/png", "size": 274688, "name": "api2.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api2.png", "created_at": "2021-04-12T07:41:03Z", "updated_at": "2021-04-12T07:41:04Z" } ], "created_at": "2021-04-12T07:41:04Z", "updated_at": "2021-04-12T07:41:04Z" } } |
Create a Note
Note: By default, any note that you add will be private. If you wish to add a public note, set the parameter to false.
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments. The total size of all the ticket's attachments (not just this note) cannot exceed 15MB. |
body * | string | Content of the note in HTML format |
incoming | boolean | Set to true if a particular note should appear as being created from the outside (i.e., not through the 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 |
/api/v2/tickets/[ticket_id]/notes
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "private":false }' 'https://domain.freshservice.com/api/v2/tickets/265/notes' |
Response
Create a Note With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'body=Hi tom, Still Angry' -F 'private=false' -X POST 'https://domain.freshservice.com/api/v2/tickets/51/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 25 26 | { "conversation": { "id": 4289856, "incoming": false, "private": false, "user_id": 1232463344, "support_email": null, "body": "<div>Hi tom, Still Angry</div>", "body_text": "Hi tom, Still Angry", "ticket_id": 51, "to_emails": [], "attachments": [ { "id": 368555, "content_type": "image/png", "size": 115399, "name": "api_attach.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api_attach.png", "created_at: "2021-04-12T06:44:09Z", "updated_at": "2021-04-12T06:44:09Z" } ], "created_at": "2021-04-12T06:44:09Z", "updated_at": "2021-04-12T06:44:09Z" } } |
Update a Conversation
Note:
Only public & private notes can be edited.
Attribute | Type | Description |
---|---|---|
body | string | Content of the note in HTML format |
/api/v2/conversations/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "body":"Can you provide some screenshots?" } 'https://domain.freshservice.com/api/v2/conversations/5' |
Response
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 user@yourcompany.com:test -F 'attachments[]=@/Users/user/Desktop/api2.png' -F 'body=Can you provide some screenshots?' -X PUT 'https://domain.freshservice.com/api/v2/conversations/4289856' |
Response
1 2 3 4 5 6 7 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 | { "conversation": { "id": 4289856, "incoming": false, "private": false, "user_id": 1232463344, "support_email": null, "body": "Can you provide some screenshots?", "body_text": "Can you provide some screenshots?", "ticket_id": 51, "to_emails": [], "attachments": [ { "id": 368555, "content_type": "image/png", "size": 115399, "name": "api_attach.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api_attach.png", "created_at": "2021-04-12T06:44:09Z", "updated_at": "2021-04-12T06:44:09Z" }, { "id": 368556, "content_type": "image/png", "size": 274688, "name": "api2.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api2.png", "created_at": "2021-04-12T06:48:53Z", "updated_at": "2021-04-12T06:48:53Z" } ], "created_at": "2021-04-12T06:44:09Z", "updated_at": "2021-04-12T06:48:53Z" } } |
Delete a Conversation
/api/v2/conversations/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/conversations/5' |
Response
Delete a Conversation Attachment
This API helps you delete an attachment from a conversation.
/api/v2/conversations/[conversation_id]/attachments/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/conversations/1/attachments/1' |
Response
List All Conversations of a Ticket
This API helps you List All Conversations of a Ticket.
/api/v2/tickets/[id]/conversations
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/20/conversations' |
Response
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 user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets/1/conversations?page=2' |
Problems
This section lists all API that can be used to create, edit or otherwise manipulate Problem.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the Problem Read-Only |
agent_id | number | Unique identifier of the agent to whom the Problem is assigned |
requester_id * | number | Unique identifier of the initiator of the problem. Mandatory |
group_id | number | Unique identifier of the agent group to which the Problem is assigned |
description * | string | HTML content of the problem. Description and description_html should not be passed together Mandatory |
description_text | string | Plain text content of the problem Read-Only |
priority * | number | Priority of the Problem 1-Low, 2-Medium, 3-High, 4-Urgent |
status * | number | Status identifier of the Problem. 1-Open, 2-Change Requested, 3-Closed Mandatory |
impact * | number | Impact of the Problem. 1-Low, 2-Medium, 3-High Mandatory |
known_error | boolean | States that the problem is known issue or not. true or false |
subject * | string | Subject of the Problem Mandatory |
due_by * | DateTime | Timestamp at which Problem due ends Mandatory |
department_id | number | Unique ID of the department initiating the Problem |
category | string | Category of the Problem |
sub_category | string | Sub-category of the Problem |
item_category | string | Item of the Problem |
created_at | DateTime | Timestamp at which Problem was created Read-Only |
updated_at | DateTime | Timestamp at which Problem was last updated Read-Only |
associated_change | number | Unique ID of the Change associated with the Problem Read-Only |
custom_fields | Hash | Key value pairs containing the names and values of custom fields. |
analysis_fields | Hash | Key value pairs containing the names and values of Problem Cause, Problem Symptom and Problem Impact |
assets | hash | List of assets associated with the problem |
Create a Problem
Create a new problem request in Freshservice
/api/v2/problems
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 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d ' { "subject": "Unable to reach email server", "email": "sample@freshservice.com", "description": "<div>Hi guys, <br/><br/>We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.<br/><br/>Regards<br/> Rachel<br/> </div>", "due_by": "2020-07-20T16:18:46Z", "priority": 2, "status": 2, "impact": 1, "category": "Hardware", "sub_category": "Peripherals", "item_category": "Router", "agent_id": 1, "group_id": 1, "department_id": 1, "custom_fields": { "sample_text_field": "Sample Text" }, "analysis_fields": { "problem_cause": { "description": "Problem cause description" }, "problem_symptom": { "description": "Problem symptom description" }, "problem_impact": { "description": "Problem impact description" } } } ' -X POST 'https://domain.freshservice.com/api/v2/problems' |
Response
Response
1 | curl -v -u user@yourcompany.com:test -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -F "status=2" -F "priority=3" -X POST '/tickets' |
Create Problem 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 user@yourcompany.com:test -F 'subject=Unable to reach email server' -F 'description=Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.' -F 'priority=2' -F 'status=2' -F 'impact=1' -F 'due_by=2021-04-21T16:18:46Z' -F 'email=user@yourcompany.coom' -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -X POST 'https://domain.freshservice.com/api/v2/problems' |
Response
1 2 3 4 5 6 7 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 | { "problem": { "id": 47, "agent_id": null, "description": "<div>Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.</div>", "description_text": "Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.", "requester_id": 1232463344, "subject": "Unable to reach email server", "group_id": null, "priority": 2, "impact": 1, "status": 2, "due_by": "2021-04-21T16:18:46Z", "known_error": false, "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2021-04-12T11:22:54Z", "updated_at": "2021-04-12T11:22:54Z", "associated_change": null, "assets": [] "custom_fields": { "requester": null, "subject": null, "description": null, "status": null, "priority": null, "impact": null, "due_by": null, "group": null, "agent": null, "department": null, "category": null }, "analysis_fields": {} } } |
Create Problem with assets
Note:
"assets" key: contains comma (,) separated hash of the assets, each with key display id.
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 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d ' { "subject": "Unable to reach email server", "email": "sample@freshservice.com", "description": "<div>Hi guys, <br/><br/>We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.<br/><br/>Regards<br/> Rachel<br/> </div>", "due_by": "2020-07-20T16:18:46Z", "priority": 2, "status": 2, "impact": 1, "category": "Hardware", "sub_category": "Peripherals", "item_category": "Router", "agent_id": 1, "group_id": 1, "department_id": 1, "custom_fields": { "sample_text_field": "Sample Text" }, "analysis_fields": { "problem_cause": { "description": "Problem cause description" }, "problem_symptom": { "description": "Problem symptom description" }, "problem_impact": { "description": "Problem impact description" } }, "assets": [ { "display_id": 8 }, { "display_id": 9 } ] } ' -X POST 'https://domain.freshservice.com/api/v2/problems' |
Response
1 2 3 4 5 6 7 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 | { "problem": { "id": 1, "agent_id": null, "requester_id": 1, "description": "<div>Hi guys, <br/><br/>We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.<br/><br/>Regards<br/> Rachel<br/> </div> ", "description_text": "Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here. Regards Rachel", "due_by": "2020-07-20T16:18:46Z", "subject": "Unable to reach email server", "group_id": null, "priority": 2, "impact": 1, "status": 2, "known_error": false, "department_id": null, "category": "Hardware", "sub_category": "Peripherals", "item_category": "Router", "created_at": "2020-02-04T05:50:57Z", "updated_at": "2020-02-04T05:50:57Z", "associated_change": 1, "custom_fields": { "sample_text_field": "Sample Text" }, "analysis_fields": { "problem_cause": { "description": "<div> Problem cause description </div>", "description_text": "Problem cause description" }, "problem_symptom": { "description": "<div> Problem symptom description </div>", "description_text": "Problem symptom description" }, "problem_impact": { "description": "<div> Problem impact description </div>", "description_text": "Problem impact description" } }, "assets": [ { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null }, { "name": "Logitech Mouse", "description": null, "ci_type_id": 4, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 9, "salvage": null } ] } } |
View a Problem
Retrieve the problem with the given ID from Freshservice
/api/v2/problems/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com//api/v2/problems/1' |
Response
List All Problems
Retrieve a list of all Problems in Freshservice
/api/v2/problems
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/problems' |
Response
Update a Problem
Update an existing Problem in Freshservice
/api/v2/problems/[id]
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 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "subject": "Unable to reach email server", "email": "sample@freshservice.com", "description": "<div>Hi guys, <br/><br/>We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.<br/><br/>Regards<br/> Rachel<br/> </div>", "due_by": "2020-07-20T16:18:46Z", "priority": 2, "status": 3, "impact": 2, "category": "Hardware", "sub_category": "Peripherals", "item_category": "Router", "agent_id": 1, "group_id": 1, "department_id": 1, "custom_fields": { "sample_text_field": "Sample Text" }, "analysis_fields": { "problem_cause": { "description": "Problem cause description" }, "problem_symptom": { "description": "Problem symptom description" }, "problem_impact": { "description": "Problem impact description" } } }' 'https://domain.freshservice.com/api/v2/problems/1' |
Response
Response
1 | curl -v -u user@yourcompany.com:test -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -F "status=2" -F "priority=3" -X POST '/tickets' |
Update Problem 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 user@yourcompany.com:test -F 'subject=Unable to reach email server' -F 'description=Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.' -F 'priority=2' -F 'status=2' -F 'impact=1' -F 'due_by=2021-04-21T16:18:46Z' -F 'email=fuser@yourcompany.com' -F 'attachments[]=@/Users/user/Desktop/api2.png' -X PUT 'https://domain.freshservice.com/api/v2/problems/47' |
Response
1 2 3 4 5 6 7 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 | { "problem": { "id": 47, "agent_id": null, "description": "Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.", "description_text": "Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.", "requester_id": 1232463344, "subject": "Unable to reach email server", "group_id": null, "priority": 2, "impact": 1, "status": 2, "due_by": "2021-04-21T16:18:46Z", "known_error": false, "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2021-04-12T11:22:54Z", "updated_at": "2021-04-12T11:22:54Z", "assets": [], "associated_change": null, "custom_fields": { "requester": null, "subject": null, "description": null, "status": null, "priority": null, "impact": null, "due_by": null, "group": null, "agent": null, "department": null, "category": null }, "analysis_fields": {} } } |
Delete a Problem
Delete the Problem with the given ID from Freshservice
/api/v2/problems/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/problems/1' |
Response
Restore a Problem
The API mentioned previously. If you deleted some problems and regret doing so now, this API will help you restore them.
/api/v2/problems/[id]/restore
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshservice.com/api/v2/problems/1/restore' |
Response
List All Problem Fields
Retrieve all the Fields that constitute the Problem Object
Problem Fields
Problem field | Description |
---|---|
id | Unique ID of the Field |
created_at | Date time at which the field was added |
updated_at | Date time at which the field was modified |
name | Name of the field |
label | Label of the field for display |
description | Description of the field |
field_type | Indicates if the field is a checkbox, dropdown, text field |
required | True if the field is marked mandatory |
required_for_closure | True if the field is marked mandatory while closing the problem item |
default_field | True if the field is a default field. False if customm |
choices | List of values supported by the field |
nested_fields | contain details of nested fields |
/api/v2/problem_form_fields
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/problem_form_fields' |
Response
Notes
This section lists all API that can be used to create, edit or otherwise manipulate Problem Notes.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the note. Read-Only |
user_id | number | Id of the user who created the note.Read-Only |
body | string | The body of the note in HTML format.Mandatory |
body_text | string | The body of the note in plain text format. Read-Only |
notify_emails | Array of strings | Addresses to which the note must be notified to |
created_at | date | Date time at which the note was created. Read-Only |
updated_at | date | Date time at which the note was updated. Read-Only |
Create a note
Create a new note on a problem request in freshservice.
/api/v2/problems/[id]/notes
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "body": "<div> body of the problem note </div> "}' -X POST 'https://domain.freshservice.com/api/v2/problems/1/notes' |
Response
View a note
Retrieve a note on a Problem request with the given ID from Freshservice.
api/v2/problems/[id]/notes/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/problems/1/notes/1' |
Response
View all notes
Retrieve a list of all notes on a Problem request with the given ID from Freshservice.
/api/v2/problems/[id]/notes
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/problems/1/notes' |
Response
Update a note
Update an existing note on an existing Problem request in Freshservice.
/api/v2/problems/[id]/notes/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "body":<div> updated problem note </div> }' 'https://domain.freshservice.com/api/v2/problems/1/notes/1' |
Response
Delete a note
Delete the note on a Problem request with the given ID from Freshservice.
Note: Deleted Notes are permanently lost. You can't retrieve them once it's get deleted.
/api/v2/problems/[id]/notes/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/problems/1/notes/1' |
Response
Time Entries
These APIs help you track exactly how much time you've spent on each Problem*, start/stop timers and perform a whole other lot of time tracking and monitoring tasks to ensure that your support team is always performing at peak efficiency.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the time entry Read-Only |
task_id | number | Unique ID of the task associated with the time entry |
executed_at | datetime | Date time at which the time entry is executed |
billable | boolean | True if billable, false otherwise. |
note | string | Description note of the time entry |
start_time | datetime | Time at which the timer started |
timer_running | boolean | True if timer is running, false otherwise |
time_spent | string | Duration of time spent in seconds |
agent_id | number | Unique ID of the user who created the time entry Mandatory |
created_at | datetime | Timestamp at which the time entry is created Read-Only |
updated_at | datetime | Time stamp at which the time entry is updated Read-Only |
Create a Time Entry
Create a new time entry on a problem request in freshservice.
/api/v2/problems/[id]/time_entries
Request
1 2 3 4 5 6 7 | { "time_entry": { "note":"test_entry", "time_spent":"03:00", "agent_id":"1", } } |
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{"note":"test_entry","time_spent":"03:00","agent_id":1,"billable":true}' -X POST 'https://domain.freshservice.com/api/v2/problems/1/time_entries' |
Response
View a Time Entry
Retrieve a time entry on a Problem request with the given ID from Freshservice.
/api/v2/problems/[id]/time_entries/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/problems/1/time_entries/1' |
Response
List All Time Entries
Retrieve the time entries on a Problems request with the given ID from Freshservice.
/api/v2/problems/[id]/time_entries
Sample code | Curl
1 | curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/problems/1/time_entries' |
Response
Update a Time Entry
Update an existing time entry on an existing Problem request in Freshservice.
/api/v2/problems/[id]/time_entries/[id]
Request
1 2 3 4 5 6 | { "time_entry": { "note":"time entry update", "billable":"false" } } |
Sample code | Curl
1 | curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{"note":"time entry update","billable":false}' 'https://domain.freshservice.com/api/v2/problems/1/time_entries/1' |
Response
Delete a Time Entry
Delete the time entry on a Problem request with the given ID from Freshservice.
/api/v2/problems/[id]/time_entries/[id]
Sample code | Curl
1 | curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE 'https://domain.freshservice.com/api/v2/problems/1/time_entries/1' |
Response
Tasks
This section lists all API that can be used to create, edit or otherwise manipulate Problem Tasks.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the task. |
agent_id | number | Id of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | DateTime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
created_at | DateTime | Timestamp at which the task was created |
updated_at | DateTime | Timestamp at which the task was updated |
closed_at | DateTime | Timestamp at which the task was closed |
group_id | number | Unique ID of the group to which the task is assigned |
Create a Task
Create a new task on a problem in freshservice
/api/v2/problems/[id]/tasks
Sample code | Curl
1 2 3 4 5 6 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "due_date": "2020-04-27T13:23:20.813Z", "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!" }' -X POST 'https://domain.freshservice.com/api/v2/problems/1/tasks' |
Response
View a Task
Retrieve a task on a Problem with the given ID from Freshservice
api/v2/problems/[id]/tasks/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/problems/1/tasks/1' |
Response
View all Tasks
Retrieve the tasks on a Problem with the given ID from Freshservice
/api/v2/problems/[id]/tasks
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/problems/1/tasks' |
Response
Update a Task
Update an existing task on an existing Problem in Freshservice
/api/v2/problems/[id]/tasks/[id]
Sample code | Curl
1 2 3 4 5 6 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "status": 3, "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!" }' 'https://domain.freshservice.com/api/v2/problems/1/tasks/1' |
Response
Delete a Task
Delete the task on a Problem with the given ID from Freshservice
Note: Deleted tasks are permanently lost. You can't retrieve them once it's get deleted.
/api/v2/problems/[id]/tasks/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/problems/1/tasks/1' |
Response
Changes
This section lists all API that can be used to create, edit or otherwise manipulate changes. You can create filters to sift through changes and to find the ones you want.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the change Read-Only |
agent_id | number | Unique identifier of the agent to whom the change is assigned. |
description | string | HTML content of the change. Description and description_html should not be passed together |
description_text | string | Plain text content of the change Read-Only |
requester_id | number | Unique identifier of the initiator of the change. Mandatory |
group_id | number | Unique identifier of the agent group to which the change is assigned. |
priority * | number | Priority of the change. |
impact * | number | Impact of the change. |
status * | number | Status of the change. |
risk * | number | Risk of the change. |
change_type * | number | Type of the change. |
approval_status | number | Approval status of the change. |
planned_start_date | number | Timestamp at which change is starting. |
planned_end_date | number | Timestamp at which change is ending. |
subject | string | change subject. |
department_id | number | Unique ID of the department initiating the change. |
category | String | Category of the change |
sub_category | String | Sub-category of the change |
item_category | String | Item of the change |
custom_fields | Hash | Key value pairs containing the names and values of custom fields. |
maintenance_window | Hash | Details about the associated Maintenance Window. |
blackout_window | Hash | Details about the overlapping Blackout Window. Read-Only |
created_at | DateTime | Timestamp at which change was created. Read-Only |
updated_at | DateTime | Timestamp at which change was last updated. Read-Only |
assets | hash | List of assets associated with the change |
* Refer Change properties table for supported values. |
Change Properties
With every change having certain fixed values to denote Source, State and Priorities, the numerical value for each state (open, closed etc.) is given below
Status | Value |
---|---|
Open | 1 |
Planning | 2 |
Approval | 3 |
Pending Release | 4 |
Pending Review | 5 |
closed | 6 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Impact | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Change Type | Value |
---|---|
Minor | 1 |
Standard | 2 |
Major | 3 |
Emergency | 4 |
Risk | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Very High | 4 |
Create a Change
Create a new Change request in Freshservice
/api/v2/changes
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "description": "<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "subject": "Getting ES3 back up to speed", "email": "tom@outerspace.com", "priority": 1, "status": 1, "group_id": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2019-03-20T16:18:46Z", "planned_end_date": "2019-03-23T16:18:46Z", "department_id": 1, "agent_id": 1, "maintenance_window": {"id": 1} }' -X POST 'https://domain.freshservice.com/api/v2/changes' |
Response
Create a Change With Custom Fields
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "description": "<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "subject": "Getting ES3 back up to speed", "email": "tom@outerspace.com", "priority": 1, "status": 1, "group_id": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2019-03-20T16:18:46Z", "planned_end_date": "2019-03-23T16:18:46Z", "department_id": 1, "agent_id": 1, "maintenance_window": {"id": 1}, "custom_fields" : { "custom_text" : "This is a custom text box" } }' -X POST 'https://domain.freshservice.com/api/v2/changes' |
Response
1 2 3 4 5 6 7 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 | curl -v -u user@yourcompany.com:test -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -F "status=2" -F "priority=3" -X POST '/tickets' { "change": { "id": 1, "agent_id": 1, "description":"<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "description_text": "Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel",, "requester_id": 1, "group_id": 1, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2021-01-10T17:47:11.030Z", "planned_end_date": "2021-02-10T17:47:11.030Z", "subject": "Getting ES3 back up to speed", "department_id": 1, "category": null, "sub_category": null, "item_category": null, "created_at": "2019-07-11T06:30:45Z", "updated_at": "2019-07-11T06:30:45Z", "custom_fields": { "custom_text": "This is a custom text box", "custom_paragraph": null, "custom_checkbox": false, "custom_number": null, "custom_dropdown": null, "custom_date": null, "custom_decimal": null }, "planning_fields": {}, "assets": [], "maintenance_window": { "id": 1, "name": "Weekly Maintenance Window", "description": "Weekly Maintenance Window.", "window_start_date": "2021-01-10T17:47:11.030Z", "window_end_date": "2021-02-10T17:47:11.030Z" }, "blackout_window": { "id": 1, "name": "Monthly Downtime", "description": "Monthly Downtime.", "window_start_date": "2021-01-10T17:47:11.030Z", "window_end_date": "2021-02-10T17:47:11.030Z" } } } |
Create Change 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 user@yourcompany.com:test -F 'subject=Getting ES3 back up to speed' -F 'description=Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel' -F 'priority=2' -F 'status=2' -F 'impact=1' -F 'change_type=1' -F 'email=user@yourcompany.com' -F 'risk=1' -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'planned_start_date=2021-04-20T16:18:46Z' -F 'planned_end_date=2021-05-20T16:18:46Z' -X POST 'https://domain.freshservice.com/api/v2/changes' |
Response
1 2 3 4 5 6 7 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 | { "change": { "id": 25, "agent_id": null, "description": "<div>Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel</div>", "description_text": "Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel", "maintenance_window": {}, "blackout_window": {}, "requester_id": 1232463344, "group_id": null, "priority": 2, "impact": 1, "status": 2, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2021-04-20T16:18:46Z", "planned_end_date": "2021-05-20T16:18:46Z", "change_window_id": null, "subject": "Getting ES3 back up to speed", "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2021-04-12T16:59:07Z", "updated_at": "2021-04-12T16:59:07Z", "custom_fields": { "requester": null, "subject": null, "change_type": null, "status": null, "priority": null, "impact": null, "risk": null, "group": null, "agent": null, "description": null, "planned_start_date": null, "planned_end_date": null, "department": null, "category": null, "change_window": null }, "planning_fields": { "custom_fields": {} }, "assets": [] } } |
Create Change with assets
Note:
"assets" key: contains comma (,) separated hash of the assets, each with key display id.
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "description": "<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "subject": "Getting ES3 back up to speed", "email": "tom@outerspace.com", "priority": 1, "status": 1, "group_id": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2019-03-20T16:18:46Z", "planned_end_date": "2019-03-23T16:18:46Z", "department_id": 1, "agent_id": 1, "maintenance_window": {"id": 1}, "assets": [{ "display_id": 8 }, { "display_id": 9 }] }' -X POST 'https://domain.freshservice.com/api/v2/changes' |
Response
1 2 3 4 5 6 7 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 | { "change": { "id": 1, "agent_id": 1, "description":"<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "description_text": "Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel",, "requester_id": 1, "group_id": 1, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2019-03-20T16:18:46Z", "planned_end_date": "2019-03-23T16:18:46Z", "subject": "Getting ES3 back up to speed", "department_id": 1, "category": null, "sub_category": null, "item_category": null, "created_at": "2019-07-11T06:30:45Z", "updated_at": "2019-07-11T06:30:45Z", "custom_fields": { "custom_text": null, "custom_paragraph": null, "custom_checkbox": false, "custom_number": null, "custom_dropdown": null, "custom_date": null, "custom_decimal": null, "planning_fields": {}, "maintenance_window": { "id": 4, "name": "Details about the associated Maintenance Window", "description": "Details about the associated Maintenance Window.", "window_start_date": "2021-01-10T17:47:11.030Z", "window_end_date": "2021-01-10T17:47:11.030Z" }, "blackout_window": { "id": 1, "name": "Details about the overlapping Blackout Window", "description": "Details about the overlapping Blackout Window.", "window_start_date": "2021-01-10T17:47:11.030Z", "window_end_date": "2021-01-10T17:47:11.030Z" }, "assets": [ { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null }, { "name": "Logitech Mouse", "description": null, "ci_type_id": 4, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 9, "salvage": null } ] } } |
View a Change
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, stats field will not be included in the response. They can be retrieved via the embedding functionality.
Embed | Handle |
---|---|
stats | /api/v2/changes/[id]?include=stats Will return the change’s closed_at, assigned_at and approval_at time |
/api/v2/changes/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/changes/1' |
Response
Additional examples
1. Get the associated stats information along with the change response.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes/1?include=stats' |
List All Changes
Use filters to view only specific changes (those which match the criteria that you choose). By default only changes that have not been deleted or marked as spam will be returned, unless you use the 'deleted' filter.
Note:
1. By default only changes that have been created within the past 30 days will be returned. For older changes, use the updated_since filter.
2. 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 (1 credit for the API call, and 2 credits for the additional stats embedding).
Filter by | Handle |
---|---|
Predefined filters | /api/v2/changes?type=[filter_name] The filters available are my_open, unassigned, closed, release_requested, requester_id. |
Updated since | /api/v2/changes?updated_since=2015-01-19T02:00:00Z |
Sort by | Handle |
---|---|
asc, desc | /api/v2/changes?order_type=asc Default sort order type is desc |
/api/v2/changes
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes' |
Response
Additional examples
1. Get the list of changes that are being unassigned to the agent whose credentials were used to make this API call.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes?filter=unassigned' |
2. Get the first page of a list of changes from the specified requestor. The changes will be returned in the descending order.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes?requester_id=1230&order_type=desc' |
3. Get the second page (changes from 11-20) of a list of all changes.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes?per_page=10&page=2' |
4. Get the first page of a list of changes that have shown any activity since the 17th of August, 2015.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes?updated_since=2015-08-17' |
5. Get the associated stats information along with the change response.
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes?include=stats' |
Update a Change
Update an existing Change request in Freshservice
/api/v2/changes/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "priority": 3 }' 'https://domain.freshservice.com/api/v2/changes/1' |
Response
Response
1 | curl -v -u user@yourcompany.com:test -F "attachments[]=@/path/to/attachment2.ext" -F "email=example@example.com" -F "subject=Ticket Title" -F "description=this is a sample ticket" -F "status=2" -F "priority=3" -X POST '/tickets' |
Update Change 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 user@yourcompany.com:test -F 'priority=2' -F 'impact=2' -F 'risk=2' -F 'attachments[]=@/Users/user/Desktop/api2.png' -X PUT 'https://domain.freshservice.com/api/v2/changes/25' |
Response
1 2 3 4 5 6 7 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 | { "change": { "id": 25, "agent_id": null, "description": "<div>Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel</div>", "description_text": "Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel", "maintenance_window": {}, "blackout_window": {}, "requester_id": 1232463344, "group_id": null, "priority": 2, "impact": 2, "status": 2, "risk": 2, "change_type": 1, "approval_status": 4, "planned_start_date": "2021-04-20T16:18:46Z", "planned_end_date": "2021-05-20T16:18:46Z", "change_window_id": null, "subject": "Getting ES3 back up to speed", "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2021-04-12T16:59:07Z", "updated_at": "2021-04-12T17:04:41Z", "custom_fields": { "requester": null, "subject": null, "change_type": null, "status": null, "priority": null, "impact": null, "risk": null, "group": null, "agent": null, "description": null, "planned_start_date": null, "planned_end_date": null, "department": null, "category": null, "change_window": null }, "planning_fields": { "custom_fields": {} }, "assets": [] } } |
Delete a Change
Delete the Change request with the given ID from Freshservice.
Note: Deleted changes are not permanently lost. You can retrieve them using the Restore Change API.
/api/v2/changes/[id]
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/changes/1' |
Response
Restore a Change
The API mentioned previously. If you deleted some changes and regret doing so now, this API will help you restore them.
/api/v2/changes/[id]/restore
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshservice.com/api/v2/changes/1/restore' |
Response
List All Change Fields (Old)
Note: This API is going to be deprecated by June 30th 2020. Please refer to the new List All Change Fields (New) API.
This API lets you view the fields in a change.
Note: The agent whose credentials (API key or username/password) are being used to make this API call should be authorised to either view the change fields or create a new change.
Change Fields
Change field | Description |
---|---|
id | Unique identifier of the change field. Read-Only |
name | Name of the change field |
name | Name of the change field |
label | Display name for the field (as seen by agents) |
description | Description of the change field |
field_type | Type of the change field |
required | Set to true if the field is mandatory. |
required_for_closure | Set to true if the field is mandatory for closing the change. |
default_field | Set to true if the field is default field. |
choices | List of values supported by the field |
nested_fields | Applicable only for dependent fields, this contain details of nested fields |
created_at | Timestamp at which change field was created. Read-Only |
updated_at | Timestamp at which change field was updated. Read-Only |
/api/v2/change_fields
Sample code | Curl
1 | curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/change_fields' |
Response
List All Change Fields (New)
Retrieve all the Fields that constitute the Change Object
Change Fields
Change field | Description |
---|---|
id | Unique ID of the Field |
created_at | Date time at which the field was added |
updated_at | Date time at which the field was modified |
name | Name of the field |
label | Label of the field for display |
description | Description of the field |
field_type | Indicates if the field is a checkbox, dropdown, text field |
required | True if the field is marked mandatory |
required_for_closure | True if the field is marked mandatory while closing the Release item |
default_field | True if the field is a default field. False if customm |
choices | List of values supported by the field |
nested_fields | contain details of nested fields |