API Reference

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.

  1. Higher rate limits as a result of significant performance enhancements
  2. Improved error handling - errors will return appropriate HTTP status codes and an error body
  3. 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
  4. Only JSON is supported in V2
  5. Only SSL calls (HTTPS) will be allowed
  6. Works only via Freshservice domains and not via custom CNAMEs
  7. Support for page sizes up to 100 has been added

Rate limit

The number of API calls per hour is based on your plan. This limit is applied on an account wide basis irrespective of factors such as the number of agents or IP addresses used to make the calls.

PLAN RATE LIMIT/HR
Sprout 1000
Blossom 3000
Garden 3000
ESM 4000
Estate 5000
Forest 5000

Note:
1. Please follow the best practices to stay under the rate limit.
2. If you need more than the default limit, please contact us.
3. Even invalid requests will count towards the rate limit.
4. 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

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?

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

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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{ "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": true, "spam": false, "email_config_id": null, "group_id": null, "priority": 4, "requester_id": 1000000542, "responder_id": null, "source": 2, "status": 2, "subject": "New child ticket via Agent Login -qhxorxcb", "to_emails": null, "sla_policy_id": 1000000029, "department_id": 1000000226, "id": 259, "type": "Incident", "due_by": "2017-09-06T12:32:14Z", "fr_due_by": "2017-09-06T09:32:14Z", "is_escalated": true, "description": "<div style=\"font-size: 13px; font-family: Helvetica Neue,Helvetica,Arial,sans-serif;\">New child ticket ticket via Agent Login</div>", "description_text": "New child ticket ticket via Agent Login", "custom_fields": { "auto_checkbox": false }, "created_at": "2017-09-06T08:32:14Z", "updated_at": "2017-09-06T08:32:14Z", "urgency": 1, "impact": 1, "category": null, "sub_category": null, "item_category": null, "deleted": false, "attachments": [], "requester": { "id": 1000000542, "name": "FS Requester1", "email": "fs.req12@gmail.com", "mobile": "", "phone": "" } } }
EXPAND ↓

Attachments

Attachments are supported for the following endpoints

Please follow the guidelines listed below

  • Only files on your local machine can be attached using API.
  • The Content-Type should always be multipart/form-data for create/update requests with attachments.
  • The name of the file is preserved after it is attached i.e the filename sent in the response will be the same as the one in the request.

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
1
2
3
4
5
6
7
8
9
10
{ "description":"Validation failed", "errors":[ { "field":"name", "message":"Mandatory attribute missing", "code":"missing_field" } ] }
EXPAND ↓

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
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.
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.
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
Email 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 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
Email 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
post
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{ "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, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "to_emails": null, "department_id": null, "id": 264, "type": "Incident", "due_by": "2017-09-11T10:26:17Z", "fr_due_by": "2017-09-09T10:26:17Z", "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": { "auto_checkbox": null }, "created_at": "2017-09-08T10:26:17Z", "updated_at": "2017-09-08T10:26:17Z", "tags": [], "attachments": [] } }
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
9
10
#Create a ticket with custom fields, cc_emails attributes. require "rubygems" require "rest_client" require "json" site = RestClient::Resource.new("https://domain.freshservice.com/helpdesk/tickets.json","user@yourcompany.com","test") response = site.post({:helpdesk_ticket=>{:description=>"Test ticket creation with attachments",:subject=>"new ticket sample",:email=>"test@abc.com",:custom_field=>{:license_1=>"ABCDEF"}},:cc_emails=>"myemail@gmail.com,test@gmail.com"},:content_type=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Create a Ticket With Custom Fields

Note:
Refer this solution article for more details regarding 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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{ "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, "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": [] } }
EXPAND ↓

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[]=@/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 'https://domain.freshservice.com/api/v2/tickets'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{ "ticket": { "cc_emails": [ ], "fwd_emails": [ ], "reply_cc_emails": [ ], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 3, "requester_id": 1000000678, "responder_id": null, "source": 2, "status": 2, "subject": "Ticket Title", "to_emails": null, "department_id": null, "id": 266, "type": "Incident", "due_by": "2017-09-08T23:03:44Z", "fr_due_by": "2017-09-08T15:03:44Z", "is_escalated": false, "description": "<div>this is a sample ticket<\/div>", "description_text": "this is a sample ticket", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "custom_text": null, "auto_checkbox": null }, "created_at": "2017-09-08T11:03:44Z", "updated_at": "2017-09-08T11:03:44Z", "tags": [ ], "attachments": [ { "id": 1000000343, "content_type": "text\/plain", "size": 5, "name": "attachment.txt", "Attachment_url: "https://cdn.freshservice/data/Helpdesk/attachments/production/19852343/original/attachment.txt", "created_at": "2017-09-08T11:03:45Z", "updated_at": "2017-09-08T11:03:45Z" } ] } }
EXPAND ↓

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
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 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
get
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{ "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 3, "requester_id": 1000000678, "responder_id": null, "source": 2, "status": 2, "subject": "Ticket Title", "to_emails": null, "sla_policy_id": 1000000029, "department_id": null, "id": 266, "type": "Incident", "due_by": "2017-09-08T23:03:44Z", "fr_due_by": "2017-09-08T15:03:44Z", "is_escalated": false, "description": "<div>this is a sample ticket</div>", "description_text": "this is a sample ticket", "custom_fields": { "custom_text": null, "auto_checkbox": false }, "created_at": "2017-09-08T11:03:44Z", "updated_at": "2017-09-08T11:37:01Z", "urgency": 1, "impact": 1, "category": null, "sub_category": null, "item_category": null, "deleted": false, "attachments": [ { "content_type": "text/plain", "size": 5, "name": "attachment.txt", "attachment_url": "https://cdn.freshservice/data/Helpdesk/attachments/production/19852343/original/attachment.txt", "created_at": "2017-09-08T11:03:45Z", "updated_at": "2017-09-08T11:03:45Z" } ] } }
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#view tickets require "rubygems" require "rest_client" require "json" #you can also use apikey instead of user/passwd # to view all tickets #pass 'page' attribute to see the specific page. Default only 30 tickets per page is listed # site = RestClient::Resource.new("https://yourcompany.freshservice.com/helpdesk/tickets.json?page=1","user@yourcompany.com","test") #view specific tickets site = RestClient::Resource.new("https://domain.freshservice.com/helpdesk/tickets/[id].json","user@yourcompany.com","test") #avatar_attributes is the property to set the image file. response = site.get(:accept=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓
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'
EXPAND ↓

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

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

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
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.
get
/api/v2/tickets
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
[ { "tickets": [ { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 3, "requester_id": 1000000678, "responder_id": null, "source": 2, "status": 2, "subject": "Ticket Title", "to_emails": null, "department_id": null, "id": 266, "type": "Incident", "due_by": "2017-09-08T23:03:44Z", "fr_due_by": "2017-09-08T15:03:44Z", "is_escalated": false, "description": "<div>this is a sample ticket</div>", "description_text": "this is a sample ticket", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "custom_text": null, "auto_checkbox": false }, "created_at": "2017-09-08T11:03:44Z", "updated_at": "2017-09-08T11:37:01Z", "deleted": false }, { "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, "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", "deleted": false } ] } ]
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#view tickets require "rubygems" require "rest_client" require "json" #you can also use apikey instead of user/passwd # to view all tickets #pass 'page' attribute to see the specific page. Default only 30 tickets per page is listed # site = RestClient::Resource.new("https://yourcompany.freshservice.com/helpdesk/tickets.json?page=1","user@yourcompany.com","test") #view specific tickets site = RestClient::Resource.new("https://domain.freshservice.com/helpdesk/tickets/[id].json","user@yourcompany.com","test") #avatar_attributes is the property to set the image file. response = site.get(:accept=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓
Additional examples

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

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/tickets?filter=watching'
EXPAND ↓

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

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

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

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

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

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

Update a Ticket

This API lets you make changes to the parameters of a ticket from updating statuses to changing ticket type.

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 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 ticket
associate_problem_id number Associate this problem id to ticket
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.
* 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
Email 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
put
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{ "ticket": { "cc_emails": [ "ram@freshservice.com", "diana@freshservice.com" ], "fwd_emails": [], "reply_cc_emails": [ "ram@freshservice.com", "diana@freshservice.com" ], "spam": false, "email_config_id": null, "fr_escalated": true, "group_id": null, "priority": 3, "requester_id": 1000000675, "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": { "custom_text": "This is a custom text box", "auto_checkbox": null }, "id": 1, "type": "Incident", "to_emails": null, "department_id": null, "is_escalated": false, "tags": [ "hello", "how", "are", "you", "now" ], "due_by": "2017-09-09T04:04:28+05:30", "fr_due_by": "2017-09-08T20:04:28+05:30", "created_at": "2017-09-08T10:34:28Z", "updated_at": "2017-09-11T07:27:07Z", "attachments": [] } }
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
9
10
11
require "rubygems" require "rest_client" require "json" #here you need to specify the ticket id as part of the URL "https://yourcompany.domain.com/helpdesk/tickets/ticketid.json" [REST standards for update] site = RestClient::Resource.new("https://domain.freshservice.com/helpdesk/tickets/5.json","user@yourcompany.com","test") #status property is mandatory. response = site.put({:helpdesk_ticket=>{:priority=>1,:status=>2}},:content_type=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

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.

delete
/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'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
require "rubygems" require "rest_client" require "json" value = 58 #pass the ticket display_id here. site = RestClient::Resource.new("https://domain.freshservice.com/helpdesk/tickets/#{value}.json","user@yourcompany.com","test") response = site.delete(:accept=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Restore a Ticket

The API mentioned previously. If you deleted some tickets and regret doing so now, this API will help you restore them.

get
/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'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
9
10
11
12
13
require "rubygems" require "rest_client" require "json" #here you need to specify the ticket id as part of the URL # eg: "https://yourcompany.domain.com/helpdesk/tickets/123/restore.json" site = RestClient::Resource.new("https://domain.freshservice.com/helpdesk/tickets/[ticket_id]/restore.json","user@yourcompany.com","test") #status property is mandatory. response = site.put({},:content_length=>0) puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

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
Email 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
post
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{ "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, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "to_emails": null, "department_id": null, "id": 264, "type": "Incident", "due_by": "2017-09-11T10:26:17Z", "fr_due_by": "2017-09-09T10:26:17Z", "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": { "auto_checkbox": null }, "created_at": "2017-09-08T10:26:17Z", "updated_at": "2017-09-08T10:26:17Z", "tags": [], "attachments": [] } }
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
9
10
#Create a ticket with custom fields, cc_emails attributes. require "rubygems" require "rest_client" require "json" site = RestClient::Resource.new("https://domain.freshservice.com/api/v2/tickets/20/create_child_ticket","user@yourcompany.com","test") response = site.post({:helpdesk_ticket=>{:description=>"Test ticket creation with attachments",:subject=>"new ticket sample",:email=>"test@abc.com",:custom_field=>{:license_1=>"ABCDEF"}},:cc_emails=>"myemail@gmail.com,test@gmail.com"},:content_type=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

List All Ticket Fields

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]
get
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
{ "ticket_fields": [ { "id": 1000000472, "name": "custom_text", "label": "custom_text", "description": "", "position": 1, "required_for_closure": false, "required_for_agents": false, "type": "custom_text", "default": false, "customers_can_edit": true, "label_for_customers": "custom_text", "required_for_customers": false, "displayed_to_customers": true, "created_at": "2017-09-08T10:33:06Z", "updated_at": "2017-09-08T10:33:06Z" }, { "id": 1000000379, "name": "auto_checkbox", "label": "auto_checkbox", "description": "", "position": 2, "required_for_closure": false, "required_for_agents": false, "type": "custom_checkbox", "default": false, "customers_can_edit": true, "label_for_customers": "auto_checkbox", "required_for_customers": false, "displayed_to_customers": true, "created_at": "2017-09-04T08:11:03Z", "updated_at": "2017-09-08T10:33:06Z" }, { "id": 1000000354, "name": "requester", "label": "Search a requester", "description": "Ticket requester", "position": 3, "required_for_closure": false, "required_for_agents": true, "type": "default_requester", "default": true, "customers_can_edit": true, "label_for_customers": "Requester", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z", "portal_cc": true, "portal_cc_to": "company" }, { "id": 1000000355, "name": "subject", "label": "Subject", "description": "Ticket subject", "position": 4, "required_for_closure": true, "required_for_agents": true, "type": "default_subject", "default": true, "customers_can_edit": true, "label_for_customers": "Subject", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z" }, { "id": 1000000356, "name": "ticket_type", "label": "Type", "description": "Ticket type", "position": 5, "required_for_closure": false, "required_for_agents": false, "type": "default_ticket_type", "default": true, "customers_can_edit": false, "label_for_customers": "Type", "required_for_customers": false, "displayed_to_customers": false, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z", "choices": [ "Incident", "Service Request" ] }, { "id": 1000000357, "name": "source", "label": "Source", "description": "Ticket source", "position": 6, "required_for_closure": false, "required_for_agents": false, "type": "default_source", "default": true, "customers_can_edit": false, "label_for_customers": "Source", "required_for_customers": false, "displayed_to_customers": false, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z", "choices": { "Email": 1, "Portal": 2, "Phone": 3, "Chat": 4, "Feedback Widget": 5, "Yammer": 6, "AWS CloudWatch": 7, "Pagerduty": 8, "Walk-up": 9, "Slack": 10 } }, { "id": 1000000358, "name": "status", "label": "Status", "description": "Ticket status", "position": 7, "required_for_closure": true, "required_for_agents": true, "type": "default_status", "default": true, "customers_can_edit": true, "label_for_customers": "Status", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z", "choices": { "2": [ "Open", "Being Processed" ], "3": [ "Pending", "Awaiting your Reply" ], "4": [ "Resolved", "This ticket has been Resolved" ], "5": [ "Closed", "This ticket has been Closed" ], "6": [ "Waiting on Customer", "Waiting on Customer" ] } }, { "id": 1000000359, "name": "urgency", "label": "Urgency", "description": "Ticket urgency", "position": 8, "required_for_closure": false, "required_for_agents": false, "type": "default_urgency", "default": true, "customers_can_edit": true, "label_for_customers": "Urgency", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z" }, { "id": 1000000360, "name": "impact", "label": "Impact", "description": "Ticket impact", "position": 9, "required_for_closure": false, "required_for_agents": false, "type": "default_impact", "default": true, "customers_can_edit": true, "label_for_customers": "Impact", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z" }, { "id": 1000000361, "name": "priority", "label": "Priority", "description": "Ticket priority", "position": 10, "required_for_closure": true, "required_for_agents": true, "type": "default_priority", "default": true, "customers_can_edit": true, "label_for_customers": "Priority", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z", "choices": { "Low": 1, "Medium": 2, "High": 3, "Urgent": 4 } }, { "id": 1000000362, "name": "group", "label": "Group", "description": "Ticket group", "position": 11, "required_for_closure": false, "required_for_agents": false, "type": "default_group", "default": true, "customers_can_edit": true, "label_for_customers": "Group", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z", "choices": { "Capacity Management Team": 1000000376, "Change Team": 1000000372, "Common Group for All Scopes": 1000000382, "Database Team": 1000000374, "dispatcher_group1": 1000000383, "dispatcher_group2": 1000000384, "Global Access Agent Group": 1000000388, "Group Access Agent Group": 1000000389, "Hardware Team": 1000000375, "Incident Team": 1000000368, "Major Incident Team": 1000000369, "Observer group 1": 1000000385, "Problem Management Team": 1000000371, "Release Team": 1000000373, "Restricted Access Agent Group": 1000000387, "Service Design Team": 1000000378, "Service Request Fulfillment Team": 1000000370, "Supplier Management Team": 1000000377, "Tickets Automation": 1000000386 } }, { "id": 1000000363, "name": "agent", "label": "Agent", "description": "Agent", "position": 12, "required_for_closure": false, "required_for_agents": false, "type": "default_agent", "default": true, "customers_can_edit": true, "label_for_customers": "Agent", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z", "choices": { "bla": 1000000559, "FSAgent1": 1000000533, "FSAgent2": 1000000534, "FSAgent3": 1000000535, "FSAgent5": 1000000536, "FSAgent7": 1000000537, "newage": 1000000599, "RestrictedAgent1": 1000000540, "RestrictedAgent2": 1000000541, "SDAgent1": 1000000538, "SDAgent2": 1000000539, "zubin": 1000000493 } }, { "id": 1000000364, "name": "department", "label": "Department", "description": "Select the department, the ticket belongs to.", "position": 13, "required_for_closure": false, "required_for_agents": false, "type": "default_department", "default": true, "customers_can_edit": true, "label_for_customers": "Department", "required_for_customers": false, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z" }, { "id": 1000000365, "name": "description", "label": "Description", "description": "Ticket description", "position": 14, "required_for_closure": true, "required_for_agents": true, "type": "default_description", "default": true, "customers_can_edit": true, "label_for_customers": "Description", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z" }, { "id": 1000000366, "name": "category", "label": "Category", "description": "Ticket category", "position": 15, "required_for_closure": false, "required_for_agents": false, "type": "default_category", "default": true, "customers_can_edit": false, "label_for_customers": "Category", "required_for_customers": false, "displayed_to_customers": false, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z" } ] }
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
9
10
11
require "rubygems" require "rest_client" require "json" #you can also use apikey instead of user/passwd site = RestClient::Resource.new("https://domain.freshservice.com/ticket_fields.json","user@yourcompany.com","test") response = site.get(:accept=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓
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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{ "ticket_fields": [ { "id": 1000000354, "name": "requester", "label": "Search a requester", "description": "Ticket requester", "position": 3, "required_for_closure": false, "required_for_agents": true, "type": "default_requester", "default": true, "customers_can_edit": true, "label_for_customers": "Requester", "required_for_customers": true, "displayed_to_customers": true, "created_at": "2017-08-30T06:36:57Z", "updated_at": "2017-09-08T10:33:06Z", "portal_cc": true, "portal_cc_to": "company" } ] }
EXPAND ↓

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.

post
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "time_entry": { "id": 20, "created_at": "2019-07-19T10:17:23Z", "updated_at": "2019-07-19T13:18:40Z", "start_time": "2019-07-19T13:18:09Z", "timer_running": false, "billable": true, "time_spent": "03:00", "executed_at": "2019-07-18T18:30:00Z", "task_id": null, "note": "test_entry", "agent_id": 1 } }
EXPAND ↓
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'
EXPAND ↓

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

View a Time Entry

This API call helps to list a particular Time Entry.

get
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "time_entry": { "id": 20, "created_at": "2019-07-19T10:17:23Z", "updated_at": "2019-07-19T13:18:40Z", "start_time": "2019-07-19T13:18:09Z", "timer_running": false, "billable": true, "time_spent": "03:00", "executed_at": "2019-07-18T18:30:00Z", "task_id": null, "note": "view time_entry", "agent_id": 1 } }
EXPAND ↓

List All Time Entries of a Ticket

This API helps to view all time entries of a particular ticket.

get
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{ "time_entries": [ { "id": 20, "created_at": "2019-07-19T10:17:23Z", "updated_at": "2019-07-19T13:18:40Z", "start_time": "2019-07-19T13:18:09Z", "timer_running": false, "billable": true, "time_spent": "03:00", "executed_at": "2019-07-18T18:30:00Z", "task_id": null, "note": "time entry 1", "agent_id": 1 }, { "id": 21, "created_at": "2019-07-19T10:18:23Z", "updated_at": "2019-07-19T13:19:40Z", "start_time": "2019-07-19T13:19:09Z", "timer_running": false, "billable": true, "time_spent": "03:00", "executed_at": "2019-07-18T18:30:00Z", "task_id": null, "note": "time entry 2", "agent_id": 1 } ] }
EXPAND ↓

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
put
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "time_entry": { "id": 20, "created_at": "2019-07-19T14:33:48Z", "updated_at": "2019-07-19T14:33:48Z", "start_time": "2019-07-19T14:33:48Z", "timer_running": false, "billable": true, "time_spent": "00:01", "executed_at": "2019-07-19T14:33:48Z", "task_id": null, "note": "text_update", "agent_id": 1 } }
EXPAND ↓

Delete a Time Entry

This API can be used to delete an existing Time Entry. Deleted time entries cannot be restored.

delete
/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'
EXPAND ↓
Response
1
HTTP Status: 200 OK
EXPAND ↓

Conversations

Conversations consist of replies as well as public and private notes added to a ticket. Notes are non-invasive ways of sharing updates about a ticket amongst agents and 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
email 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
post
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "conversation": { "id": 1000005176, "user_id": 1000000493, "from_email": "helpdesk@zubin.freshbase.co", "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": 265, "to_emails": [ "tom@outerspace.com" ], "attachments": [], "created_at": "2017-09-11T09:54:36Z", "updated_at": "2017-09-11T09:54:36Z" } }
EXPAND ↓

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[]=@/path/to/attachment.txt" -F "body=this is a sample reply" -X POST 'https://domain.freshservice.com/api/v2/tickets/27/reply'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{ "conversation": { "id": 1000005177, "user_id": 1000000493, "from_email": "helpdesk@zubin.freshbase.co", "cc_emails": [], "bcc_emails": [], "body": "<div>this is a sample reply<\/div>", "body_text": "this is a sample reply", "ticket_id": 27, "to_emails": [ "tom@outerspace.com" ], "attachments": [ { "id": 1000000360, "content_type": "application\/octet-stream", "size": 46695, "name": "attachment.txt", "attachment_url": "https://cdn.freshservice/data/Helpdesk/attachments/production/19852343/original/attachment.txt", "created_at": "2017-09-11T09:59:25Z", "updated_at": "2017-09-11T09:59:25Z" } ], "created_at": "2017-09-11T09:59:25Z", "updated_at": "2017-09-11T09:59:25Z" } }
EXPAND ↓

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
post
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{ "conversation": { "id": 1000005178, "incoming": false, "private": false, "user_id": 1000000493, "support_email": null, "body": "<div>Hi tom, Still Angry</div>", "body_text": "Hi tom, Still Angry", "ticket_id": 265, "to_emails": [], "attachments": [], "created_at": "2017-09-11T10:06:17Z", "updated_at": "2017-09-11T10:06:17Z" } }
EXPAND ↓

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[]=@/path/to/attachment1.ext" -F "body=Hi tom, Still Angry" -F "notify_emails[]=tom@yourcompany.com" -X POST 'https://domain.freshservice.com/api/v2/tickets/265/notes'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{ "conversation": { "id": 1000005179, "incoming": false, "private": true, "user_id": 1000000493, "support_email": null, "body": "<div>this is a sample reply<\/div>", "body_text": "this is a sample reply", "ticket_id": 265, "to_emails": [], "attachments": [ { "id": 1000000361, "content_type": "application\/octet-stream", "size": 46695, "name": "attachment.txt", "attachment_url": "https://cdn.freshservice/data/Helpdesk/attachments/production/19852343/original/attachment.txt", "created_at": "2017-09-11T10:07:54Z", "updated_at": "2017-09-11T10:07:54Z" } ], "created_at": "2017-09-11T10:07:54Z", "updated_at": "2017-09-11T10:07:54Z" } }
EXPAND ↓

Update a Conversation


Note:
Only public & private notes can be edited.

Attribute Type Description
body string Content of the note in HTML format
put
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{ "conversation": { "id": 5, "incoming": false, "private": false, "user_id": 1000000493, "support_email": null, "body": "Can you provide some screenshots?", "body_text": "Can you provide some screenshots?", "ticket_id": 265, "to_emails": [], "attachments": [ { "id": 1000000361, "content_type": "application/octet-stream", "size": 46695, "name": "attachment.txt", "Attachment_url": “https://cdn.freshservice/data/Helpdesk/attachments/production/19852343/original/attachment.txt", "created_at": "2017-09-11T10:07:54Z", "updated_at": "2017-09-11T10:07:54Z" } ], "created_at": "2017-09-11T10:07:54Z", "updated_at": "2017-09-11T10:12:54Z" } }
EXPAND ↓

Update a conversation With Attachment

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

Sample code | Curl
1
curl -v -u user@yourcompany.com:test -F "attachments[]=@/path/to/attachment1.txt" -F "body=updated conversation" -X PUT 'https://domain.freshservice.com/api/v2/conversations/6'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ "conversation": { "id": 143, "incoming": false, "private": false, "user_id": 1, "support_email": null, "body": "Hi tom, no need to worry", "body_text": "Hi tom, no need to worry", "ticket_id": 3000, "to_emails": [], "attachments": [{ "id": 13, "content_type": "image/jpeg", "size": 201599, "name": "zub.jpg", "attachment_url": "https://cdn.freshservice.com/data/helpdesk/attachments/production/4004881085/original/zub.jpg", "created_at": "2017-10-11T11:06:58Z", "updated_at": "2017-10-11T11:06:58Z" }], "created_at": "2017-10-11T11:06:58Z", "updated_at": "2017-10-11T12:58:00Z" } }
EXPAND ↓

Delete a Conversation

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

List All Conversations of a Ticket

This API helps you List All Conversations of a Ticket.

get
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{ "conversations": [ { "id": 1000005175, "body": "<div style='font-size: 13px; font-family: \"Helvetica Neue\", Helvetica, Arial, sans-serif;'>\n<div>Is this still a problem</div>\r\n</div>", "body_text": "Is this still a problem", "incoming": false, "private": false, "created_at": "2017-09-11T09:28:52Z", "updated_at": "2017-09-11T09:28:52Z", "user_id": 1000000493, "support_email": null, "source": 2, "ticket_id": 1, "to_emails": [], "from_email": null, "cc_emails": [], "bcc_emails": null, "attachments": [] } ] }
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
require "rubygems" require "rest_client" require "json" value = 58 #pass the ticket display_id here. site = RestClient::Resource.new("https://domain.freshservice.com/helpdesk/tickets/#{value}.json","user@yourcompany.com","test") response = site.delete(:accept=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓
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'
EXPAND ↓

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.
created_at DateTime Timestamp at which change was created. Read-Only
updated_at DateTime Timestamp at which change was last updated. Read-Only
* 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

post
/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 }' -X POST 'https://domain.freshservice.com/api/v2/changes'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{ "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": {} } }
EXPAND ↓

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, "custom_fields" : { "custom_text" : "This is a custom text box" } }' -X POST 'https://domain.freshservice.com/api/v2/changes'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{ "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": "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": {} } }
EXPAND ↓

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, resolved_at and first_responded_at time
get
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{ "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": {} } }
EXPAND ↓
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'
EXPAND ↓

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?filter=[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
Embed Handle
stats /api/v2/changes?include=stats
Will return the change’s closed_at, resolved_at and first_responded_at time.
get
/api/v2/changes
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{ "changes": [ { "id": 2, "agent_id": null, "description": "", "description_text": null, "requester_id": 3, "group_id": null, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2019-08-01T14:15:42Z", "planned_end_date": "2019-08-01T14:15:42Z", "subject": "Upgrade Web Server", "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2019-07-18T14:15:42Z", "updated_at": "2019-07-18T14:15:42Z" }, { "id": 1, "agent_id": null, "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": 4, "group_id": null, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2019-08-01T14:15:22Z", "planned_end_date": "2019-08-01T14:15:22Z", "subject": "Getting ES3 back up to speed", "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2019-07-18T14:15:22Z", "updated_at": "2019-07-18T14:15:22Z" } ] }
EXPAND ↓
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'
EXPAND ↓

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

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

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

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

Update a Change

Update an existing Change request in Freshservice

put
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{ "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": 3, "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": {} } }
EXPAND ↓

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.

delete
/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'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓
Sample code | Ruby
1
2
3
4
5
6
7
8
require "rubygems" require "rest_client" require "json" value = 58 #pass the change display_id here. site = RestClient::Resource.new("https://domain.freshservice.com/itil/changes/#{value}.json","user@yourcompany.com","test") response = site.delete(:accept=>"application/json") puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Restore a Change

The API mentioned previously. If you deleted some changes and regret doing so now, this API will help you restore them.

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

List All Change Fields

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
get
/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'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
{ "change_fields": [ { "id": 1, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-18T14:15:19Z", "name": "requester", "label": "Requester", "description": "Change requester", "field_type": "default_requester", "required": true, "required_for_closure": false, "default_field": true, "choices": [ ], "nested_fields": [ ] }, { "id": 2, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-21T04:50:32Z", "name": "subject", "label": "Subject", "description": "Change subject", "field_type": "default_subject", "required": false, "required_for_closure": false, "default_field": true, "choices": [ ], "nested_fields": [ ] }, { "id": 3, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-22T15:31:08Z", "name": "change_type", "label": "Type", "description": "Change Type", "field_type": "default_change_type", "required": false, "required_for_closure": false, "default_field": true, "choices": { "1": "Minor", "2": "Standard", "3": "Major", "4": "Emergency" }, "nested_fields": [ ] }, { "id": 4, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-22T15:31:08Z", "name": "status", "label": "Status", "description": "Change status", "field_type": "default_status", "required": false, "required_for_closure": false, "default_field": true, "choices": { "1": "Open", "2": "Planning", "3": "Awaiting Approval", "4": "Pending Release", "5": "Pending Review", "6": "Closed" }, "nested_fields": [ ] }, { "id": 5, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-22T15:31:08Z", "name": "priority", "label": "Priority", "description": "Change priority", "field_type": "default_priority", "required": false, "required_for_closure": false, "default_field": true, "choices": { "1": "Low", "2": "Medium", "3": "High", "4": "Urgent" }, "nested_fields": [ ] }, { "id": 6, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-22T15:31:08Z", "name": "impact", "label": "Impact", "description": "Change impact", "field_type": "default_impact", "required": false, "required_for_closure": false, "default_field": true, "choices": { "1": "Low", "2": "Medium", "3": "High" }, "nested_fields": [ ] }, { "id": 7, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-22T15:31:08Z", "name": "risk", "label": "Risk", "description": "Change Risk", "field_type": "default_risk", "required": false, "required_for_closure": false, "default_field": true, "choices": { "1": "Low", "2": "Medium", "3": "High", "4": "Very High" }, "nested_fields": [ ] }, { "id": 8, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-22T15:31:08Z", "name": "group", "label": "Group", "description": "Change Group", "field_type": "default_group", "required": false, "required_for_closure": false, "default_field": true, "choices": [ ], "nested_fields": [ ] }, { "id": 9, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-22T15:31:09Z", "name": "agent", "label": "Assigned To", "description": "Assigned To", "field_type": "default_agent", "required": false, "required_for_closure": false, "default_field": true, "choices": [ ], "nested_fields": [ ] }, { "id": 10, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-21T04:50:32Z", "name": "description", "label": "Description", "description": "Change description", "field_type": "default_description", "required": false, "required_for_closure": false, "default_field": true, "choices": [ ], "nested_fields": [ ] }, { "id": 11, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-21T04:50:32Z", "name": "planned_start_date", "label": "Planned Start Date", "description": "Planned Start Date", "field_type": "default_planned_start_date", "required": false, "required_for_closure": false, "default_field": true, "choices": [ ], "nested_fields": [ ] }, { "id": 12, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-21T04:50:32Z", "name": "planned_end_date", "label": "Planned End Date", "description": "Planned End Date", "field_type": "default_planned_end_date", "required": false, "required_for_closure": false, "default_field": true, "choices": [ ], "nested_fields": [ ] }, { "id": 13, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-18T14:15:19Z", "name": "department", "label": "Department", "description": "Select the department, the change belongs to.", "field_type": "default_department", "required": false, "required_for_closure": false, "default_field": true, "choices": [ ], "nested_fields": [ ] }, { "id": 14, "created_at": "2019-07-18T14:15:19Z", "updated_at": "2019-07-18T14:15:19Z", "name": "category", "label": "Category", "description": "Change category", "field_type": "default_category", "required": false, "required_for_closure": false, "default_field": true, "choices": [ [ "Hardware", "Hardware", [ [ "Computer", "Computer", [ [ "Mac", "Mac" ], [ "PC", "PC" ] ] ], [ "Printer", "Printer", [ ] ], [ "Phone", "Phone", [ ] ], [ "Peripherals", "Peripherals", [ [ "Router", "Router" ], [ "Switch", "Switch" ], [ "Access point", "Access point" ] ] ] ] ], [ "Software", "Software", [ [ "MS Office", "MS Office", [ ] ], [ "Adobe Reader", "Adobe Reader", [ ] ], [ "Windows", "Windows", [ ] ], [ "Chrome", "Chrome", [ ] ] ] ], [ "Network", "Network", [ [ "Access", "Access", [ ] ], [ "Connectivity", "Connectivity", [ ] ] ] ], [ "Other", "Other", [ ] ] ], "nested_fields": [ { "name": "sub_category", "label": "Sub-Category", "level": 2 }, { "name": "item_category", "label": "Item", "level": 3 } ] } ] }
EXPAND ↓

Notes

This section lists all API that can be used to create, edit or otherwise manipulate Change 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 change request in freshservice.

post
/api/v2/changes/[id]/notes
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "body": "<div> body of the change note </div> "}' -X POST 'https://domain.freshservice.com/api/v2/changes/1/notes'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
{ "note": { "id": 1, "created_at": "2019-06-20T16:47:04Z", "updated_at": "2019-06-20T16:47:16Z", "body": "<div> body of the change note </div> ", "body_text": "body of the change note", "user_id": 1, "notify_emails": null } }
EXPAND ↓

View a note

Retrieve a note on a Change request with the given ID from Freshservice.

get
api/v2/changes/[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/changes/1/notes/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
{ "note": { "id": 1, "created_at": "2019-06-20T16:47:04Z", "updated_at": "2019-06-20T16:47:16Z", "body": "<div> body of the change note </div> ", "body_text": "body of the change note", "user_id": 1, "notify_emails": null } }
EXPAND ↓

View all notes

Retrieve a list of all notes on a Change request with the given ID from Freshservice.

get
/api/v2/changes/[id]/notes
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/changes/1/notes'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{ "notes": [ { "id": 1, "created_at": "2019-06-20T16:47:04Z", "updated_at": "2019-06-20T16:47:16Z", "body": "<div> body of the change note </div>", "body_text": "body of the change note", "user_id": 1, "notify_emails": ["user@yourcompany.com"] }, { "id": 2, "created_at": "2019-06-20T16:49:04Z", "updated_at": "2019-06-20T16:49:16Z", "body": "<div> body of the change note </div>", "body_text": "body of the change note", "user_id": 1, "notify_emails": ["user@yourcompany.com"] } ] }
EXPAND ↓

Update a note

Update an existing note on an existing Change request in Freshservice.

put
/api/v2/changes/[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 change note </div> }' 'https://domain.freshservice.com/api/v2/changes/1/notes/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
{ "note": { "id": 1, "created_at": "2019-06-20T16:47:04Z", "updated_at": "2019-06-20T16:47:16Z", "body": "<div> updated change note </div> ", "body_text": "updated change note", "user_id": 1, "notify_emails": null } }
EXPAND ↓

Delete a note

Delete the note on a Change request with the given ID from Freshservice.

Note: Deleted Notes are permanently lost. You can't retrieve them once it's get deleted.

delete
/api/v2/changes/[id]/notes/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/changes/1/notes/1'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Time Entries

These APIs help you track exactly how much time you've spent on each change*, 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 change request in freshservice.

post
/api/v2/changes/[id]/time_entries
Request
1
2
3
4
5
6
7
{ "time_entry": { "note":"test_entry", "time_spent":"03:00", "agent_id":"1", } }
EXPAND ↓
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/changes/1/time_entries'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "time_entry": { "id": 1, "created_at": "2019-06-26T15:44:11Z", "updated_at": "2019-06-26T16:32:11Z", "start_time": "2019-06-26T15:44:11Z", "timer_running": false, "billable": true, "time_spent": "03:00", "executed_at": "2019-06-26T15:44:11Z", "task_id": null, "note": "test_entry", "agent_id": 1 } }
EXPAND ↓

View a Time Entry

Retrieve a time entry on a Change request with the given ID from Freshservice.

get
/api/v2/changes/[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/changes/1/time_entries/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "time_entry": { "id": 1, "created_at": "2019-06-26T15:44:11Z", "updated_at": "2019-06-26T16:32:11Z", "start_time": "2019-06-26T15:44:11Z", "timer_running": false, "billable": true, "time_spent": "03:00", "executed_at": "2019-06-26T15:44:11Z", "task_id": null, "note": "test_entry", "agent_id": 1 } }
EXPAND ↓

List All Time Entries

Retrieve the time entries on a Change request with the given ID from Freshservice.

get
/api/v2/changes/[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/changes/1/time_entries'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{ "time_entries": [ { "id": 1, "created_at": "2019-06-26T15:44:11Z", "updated_at": "2019-06-26T16:32:11Z", "start_time": "2019-06-26T15:44:11Z", "timer_running": false, "billable": true, "time_spent": "00:48", "executed_at": "2019-06-26T15:44:11Z", "task_id": null, "note": "time_entry 1", "agent_id": 1 }, { "id": 2, "created_at": "2019-06-26T15:44:02Z", "updated_at": "2019-06-26T15:44:11Z", "start_time": "2019-06-26T15:44:02Z", "timer_running": false, "billable": true, "time_spent": "00:00", "executed_at": "2019-06-26T15:44:02Z", "task_id": null, "note": "time_entry 2", "agent_id": 1 } ] }
EXPAND ↓

Update a Time Entry

Update an existing time entry on an existing Change request in Freshservice.

put
/api/v2/changes/[id]/time_entries/[id]
Request
1
2
3
4
5
6
{ "time_entry": { "note":"time entry update", "billable":"false" } }
EXPAND ↓
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/changes/1/time_entries/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "time_entry": { "id": 1, "created_at": "2019-06-26T15:44:11Z", "updated_at": "2019-06-26T16:32:11Z", "start_time": "2019-06-26T15:44:11Z", "timer_running": false, "billable": false, "time_spent": "03:00", "executed_at": "2019-06-26T15:44:11Z", "task_id": null, "note": "time entry update", "agent_id": 1 } }
EXPAND ↓

Delete a Time Entry

Delete the time entry on a Change request with the given ID from Freshservice.

delete
/api/v2/changes/[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/changes/1/time_entries/1'
EXPAND ↓
Response
1
HTTP Status: 200 OK
EXPAND ↓

Requesters

Requesters are Freshservice users who consume services provided by the agent teams.

Attribute Type Description
id number User ID of the requester.
first_name string First name of the requester.Mandatory
last_name string Last name of the requester.
job_title string Job title of the requester.
primary_email* string Primary email address of the requester.
secondary_emails array of strings Additional/secondary emails associated with the requester.
work_phone_number* number Work phone number of the requester.
mobile_phone_number* number Mobile phone number of the requester.
department_ids array of numbers Unique IDs of the departments associated with the requester
can_see_all_tickets_from_associated_departments boolean Set to true if the requester must be allowed to view tickets filed by other members of the department, and false otherwise
reporting_manager_id number User ID of the requester’s reporting manager.
address string Address of the requester.
time_zone string Time zone of the requester. Read more here.
time_format string Time format for the requester.Possible values:
12h (12 hour format)
24h (24 hour format)
language string Language used by the requester. The default language is “en” (English). Read more here.
location_id number Unique ID of the location associated with the requester.
background_information string Background information of the requester.
custom_fields hash Key-value pair containing the names and values of the (custom) requester fields.
created_at datetime Date and time when the requester was created
updated_at datetime Date and time when the requester was last updated
* primary_email, work_phone_number or mobile_phone_number - one of three is mandatory to create a requester.

Create a Requester

This operation allows you to create a new requester.

Attribute Type Description
first_name string First name of the requester.Mandatory
last_name string Last name of the requester.
job_title string Job title of the requester.
primary_email* string Primary email address of the requester.
secondary_emails array of strings Additional/secondary emails associated with the requester.
work_phone_number* number Work phone number of the requester.
mobile_phone_number* number Mobile phone number of the requester.
department_ids array of numbers Unique IDs of the departments associated with the requester
can_see_all_tickets_from_associated_departments boolean Set to true if the requester must be allowed to view tickets filed by other members of the department, and false otherwise
reporting_manager_id number User ID of the requester’s reporting manager.
address string Address of the requester.
time_zone string Time zone of the requester. Read more here.
time_format string Time format for the requester.Possible values:
12h (12 hour format)
24h (24 hour format)
language string Language used by the requester. The default language is “en” (English). Read more here.
location_id number Unique ID of the location associated with the requester.
background_information string Background information of the requester.
custom_fields hash Key-value pair containing the names and values of the (custom) requester fields.
* primary_email, work_phone_number or mobile_phone_number - one of three is mandatory to create a requester.
post
/api/v2/requesters
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"first_name":"Ron","last_name":"Weasley","job_title":"Student","primary_email":"ronald.weasley@hogwarts.edu","secondary_emails":["ronald.weasley@freshservice.com", ronald.weasley@freshworks.com"],"work_phone_number":"62443","mobile_phone_number":"77762443","department_ids":[554],"can_see_all_tickets_from_associated_departments":false,"reporting_manager_id":656,"address":"Gryffindor Tower","time_zone":"Edinburgh","language":"en","location_id":23,"background_information":"","custom_fields":{"quidditch_role":null,"hogsmeade_permission":true}}' 'https://domain.freshservice.com/api/v2/requesters'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{ "requester":{ "id":888, "first_name":"Ron", "last_name":"Weasley", "job_title":"Student", "primary_email":"ronald.weasley@hogwarts.edu", "secondary_emails":[ "ronald.weasley@freshservice.com", "ronald.weasley@freshworks.com" ], "work_phone_number":"62443", "mobile_phone_number":"77762443", "department_ids":[ 554 ], "can_see_all_tickets_from_associated_departments":false, "reporting_manager_id":656, "address":"Gryffindor Tower", "time_zone":"Edinburgh", "time_format":"12h", "language":"en", "location_id":23, "background_information":"", "custom_fields":{ "quidditch_role":null, "hogsmeade_permission":true } } }
EXPAND ↓

View a Requester

This operation allows you to view information about a particular requester.

get
/api/v2/requesters/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/requesters/777'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{ "requester":{ "id":777, "first_name":"Harry", "last_name":"Potter", "job_title":"Student", "primary_email":"harry.potter@hogwarts.edu", "secondary_emails":[ "harry.potter@freshservice.com", "harry.potter@freshworks.com" ], "work_phone_number":"62442", "mobile_phone_number":"77762442", "department_ids":[ 554 ], "can_see_all_tickets_from_associated_departments":false, "reporting_manager_id":656, "address":"Gryffindor Tower", "time_zone":"Edinburgh", "time_format":"12h", "language":"en", "location_id":23, "background_information":"", "custom_fields":{ "quidditch_role":"Seeker", "hogsmeade_permission":true } } }
EXPAND ↓

List All Requesters

This operation allows you to view information about all requesters in the account.Use filters to view only specific requesters (those who match the criteria that you choose). The filters listed in the table below can also be combined.

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

Filter by Handle
email, mobile_phone_number, work_phone_number /api/v2/requesters?[filter]=[value]
Example:
/api/v2/requesters?email=harry.potter@hogwarts.edu
/api/v2/requesters?mobile_phone_number=77762442
/api/v2/requesters?work_phone_number=62442
get
/api/v2/requesters
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/requesters'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{ "requesters":[ { "id":777, "first_name":"Harry", "last_name":"Potter", "job_title":"Student", "primary_email":"harry.potter@hogwarts.edu", "secondary_emails":[ "harry.potter@freshservice.com", "harry.potter@freshworks.com" ], "work_phone_number":"62442", "mobile_phone_number":"77762442", "department_ids":[ 554 ], "can_see_all_tickets_from_associated_departments":false, "reporting_manager_id":656, "address":"Gryffindor Tower", "time_zone":"Edinburgh", "time_format":"12h", "language":"en", "location_id":23, "background_information":"", "custom_fields":{ "quidditch_role":"Seeker", "hogsmeade_permission":true } }, { "id":888, "first_name":"Ron", "last_name":"Weasley", "job_title":"Student", "primary_email":"ronald.weasley@hogwarts.edu", "secondary_emails":[ "ronald.weasley@freshservice.com", "ronald.weasley@freshworks.com" ], "work_phone_number":"62443", "mobile_phone_number":"77762443", "department_ids":[ 554 ], "can_see_all_tickets_from_associated_departments":false, "reporting_manager_id":656, "address":"Gryffindor Tower", "time_zone":"Edinburgh", "time_format":"12h", "language":"en", "location_id":23, "background_information":"", "custom_fields":{ "quidditch_role":null, "hogsmeade_permission":true } } ] }
EXPAND ↓
Additional examples

Get the first 20 full-time requesters. By default, the requesters will be returned in alphabetical order and the first page will be displayed.

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/requesters?per_page=20&page=2'
EXPAND ↓

List All Requester Fields

This operation allows you to view all the built-in and custom fields for requesters in your Freshservice account.

REQUESTER FIELD DESCRIPTION
editable_in_signup Set to true if the field can be updated by requesters during signup.
id ID of the requester field.
label Display name for the field (as seen by agents).
name Name of the requester field.
position Position of the requester field.
type For custom requester fields, type of value associated with the field will be given (Examples custom_date, custom_text...).
requesters_can_edit Requesters can edit the field in the support portal.
label_for_requesters Display name for the field (as seen in the support portal).
required_for_requesters Set to true if the field is mandatory in the support portal.
displayed_for_requesters Requesters can see the field in the support portal.
required_for_agents Set to true if the field is mandatory for agents.
choices List of values supported by the field.
get
/api/v2/requester_fields
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/contact_fields'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
{ "requester_fields":[ { "editable_in_signup":true, "id":1, "name":"first_name", "label":"First Name", "position":1, "required_for_agents":true, "type":"default_first_name", "default":true, "customers_can_edit":true, "label_for_customers":"First Name", "required_for_customers":true, "displayed_for_customers":true, "created_at":"2018-10-17T05:39:34Z", "updated_at":"2018-10-17T05:39:34Z" }, { "editable_in_signup":true, "id":2, "name":"last_name", "label":"Last Name", "position":2, "required_for_agents":false, "type":"default_last_name", "default":true, "customers_can_edit":true, "label_for_customers":"Last Name", "required_for_customers":false, "displayed_for_customers":true, "created_at":"2018-10-17T05:39:34Z", "updated_at":"2018-10-17T05:39:34Z" }, { "editable_in_signup":false, "id":3, "name":"job_title", "label":"Title", "position":3, "required_for_agents":false, "type":"default_job_title", "default":true, "customers_can_edit":true, "label_for_customers":"Title", "required_for_customers":false, "displayed_for_customers":true, "created_at":"2018-10-17T05:39:34Z", "updated_at":"2018-10-17T05:39:34Z" }, { "editable_in_signup":true, "id":4, "name":"email", "label":"Email", "position":4, "required_for_agents":true, "type":"default_email", "default":true, "customers_can_edit":false, "label_for_customers":"Email", "required_for_customers":true, "displayed_for_customers":true, "created_at":"2018-10-17T05:39:34Z", "updated_at":"2018-10-17T05:39:34Z" }, ... { "editable_in_signup":false, "id":12, "name":"language", "label":"Language", "position":12, "required_for_agents":false, "type":"default_language", "default":true, "customers_can_edit":true, "label_for_customers":"Language", "required_for_customers":false, "displayed_for_customers":true, "created_at":"2018-10-17T05:39:34Z", "updated_at":"2018-10-17T05:39:34Z", "choices":{ "ar":"Arabic", "ca":"Catalan", "zh-CN":"Chinese", "cs":"Czech", "da":"Danish", "nl":"Dutch", "en":"English", "et":"Estonian", "fi":"Finnish", "fr":"French", "de":"German", "hu":"Hungarian", "id":"Indonesian", "it":"Italian", "ja-JP":"Japanese", "ko":"Korean", "nb-NO":"Norwegian", "pl":"Polish", "pt-BR":"Portuguese (BR)", "pt-PT":"Portuguese/Portugal", "ru-RU":"Russian", "sk":"Slovak", "sl":"Slovenian", "es":"Spanish", "es-LA":"Spanish (Latin America)", "sv-SE":"Swedish", "th":"Thai", "tr":"Turkish", "vi":"Vietnamese", "cy-GB":"Welsh" } }, { "editable_in_signup":false, "id":13, "name":"location_id", "label":"Location", "position":13, "required_for_agents":false, "type":"default_location_id", "default":true, "customers_can_edit":true, "label_for_customers":"Location", "required_for_customers":false, "displayed_for_customers":true, "created_at":"2018-10-17T05:39:34Z", "updated_at":"2018-10-17T05:39:34Z" }, { "editable_in_signup":false, "id":14, "name":"description", "label":"Background information", "position":14, "required_for_agents":false, "type":"default_description", "default":true, "customers_can_edit":false, "label_for_customers":"Background information", "required_for_customers":false, "displayed_for_customers":false, "created_at":"2018-10-17T05:39:34Z", "updated_at":"2018-10-17T05:39:34Z" }, { "editable_in_signup":false, "id":15, "name":"quidditch_role", "label":"quidditch_role", "position":15, "required_for_agents":false, "type":"custom_text", "default":false, "requesters_can_edit":true, "label_for_requesters":"quidditch_role", "required_for_requesters":false, "displayed_for_requesters":true, "created_at":"2018-10-17:11:06Z", "updated_at":"2018-10-17:11:06Z" }, { "editable_in_signup":false, "id":16, "name":"hogsmeade_permission", "label":"hogsmeade_permission", "position":16, "required_for_agents":false, "type":"custom_checkbox", "default":false, "requesters_can_edit":true, "label_for_requesters":"hogsmeade_permission", "required_for_requesters":false, "displayed_for_requesters":true, "created_at":"2018-10-17:11:06Z", "updated_at":"2018-10-17:11:06Z" } ] }
EXPAND ↓

Update a Requester

This operation allows you to modify the profile of a particular requester.

Attribute Type Description
first_name string First name of the requester.
last_name string Last name of the requester.
job_title string Job title of the requester.
primary_email string Primary email address of the requester.
secondary_emails array of strings Additional/secondary emails associated with the requester.
work_phone_number number Work phone number of the requester.
mobile_phone_number number Mobile phone number of the requester.
department_ids array of numbers Unique IDs of the departments associated with the requester
can_see_all_tickets_from_associated_departments boolean Set to true if the requester must be allowed to view tickets filed by other members of the department, and false otherwise
reporting_manager_id number User ID of the requester’s reporting manager.
address string Address of the requester.
time_zone string Time zone of the requester. Read more here.
time_format string Time format for the requester.Possible values:
12h (12 hour format)
24h (24 hour format)
language string Language used by the requester. The default language is “en” (English). Read more here.
location_id number Unique ID of the location associated with the requester.
background_information string Background information of the requester.
custom_fields hash Key-value pair containing the names and values of the (custom) requester fields.
put
/api/v2/requesters/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H 'Content-Type: application/json' -X PUT -d '{ "first_name":"Ronald", "last_name":"Weasley","time_format":"24h" }' 'https://domain.freshservice.com/api/v2/requesters/888'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{ "requester":{ "id":888, "first_name":"Ronald", "last_name":"Weasley", "job_title":"Student", "primary_email":"ronald.weasley@hogwarts.edu", "secondary_emails":[ "ronald.weasley@freshservice.com", "ronald.weasley@freshworks.com" ], "work_phone_number":"62443", "mobile_phone_number":"77762443", "department_ids":[ 554 ], "can_see_all_tickets_from_associated_departments":false, "reporting_manager_id":656, "address":"Gryffindor Tower", "time_zone":"Edinburgh", "time_format":"24h", "language":"en", "location_id":23, "background_information":"", "custom_fields":{ "quidditch_role":null, "hogsmeade_permission":true } } }
EXPAND ↓

Delete a Requester

This operation allows you to delete a requester.

delete
/api/v2/requesters/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/requesters/888'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Convert To Agent

Convert a requester to an occasional agent with SD Agent role and no group memberships.

put
/api/v2/requesters/[id]/convert_to_agent
Sample code | Curl
1
curl -v -u api.user@hogwarts.edu:test -H 'Content-Type: application/json' -X PUT -d '' 'https://domain.freshservice.com/api/v2/requesters/888/convert_to_agent'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{ "agent":{ "id":888, "first_name":"Rubeus", "last_name":"Hagrid", "occasional":true, "job_title":"Gamekeeper", "email":"rubeus.hagrid@hogwarts.edu", "work_phone_number":5564435, "mobile_phone_number":664345, "reporting_manager_id":32, "signature":null, "time_zone":"Edinburgh", "language":"en", "location_id":34, "scoreboard_level_id":null, "scopes": { "ticket":"Global Access", "problem":"Global Access", "change":"Global Access", "release":"Global Access", "asset":"Global Access" }, "group_ids":[], "role_ids":[ 4 ], "last_login_at":"2019-05-28T07:46:41Z" } }
EXPAND ↓

Agents

Agents in Freshservice can be “full-time” or “occasional”. Full-time agents are those in your core support team who will log in to your help desk every day. Occasional agents are those who would only need to log in a few times every month, such as the CEO or field staff.

Attribute Type Description
id number User ID of the agent.
first_name string First name of the agent.Mandatory
last_name string Last name of the agent.
occasional boolean True if the agent is an occasional agent, and false if full-time agent.
job_title string Job title of the agent.
email string Email address of the agent.Mandatory
work_phone_number number Work phone number of the agent.
mobile_phone_number number Mobile phone number of the agent.
reporting_manager_id number User ID of the agent's reporting manager.
time_zone string Time zone of the agent. Read more here.
time_format string Time format for the agent.Possible values:
12h (12 hour format)
24h (24 hour format)
language string Language used by the agent. The default language is “en” (English). Read more here.
location_id number Unique ID of the location associated with the agent.
scoreboard_level_id number Unique ID of the level of the agent in the Arcade. Possible values:
1 (Beginner)
2 (Intermediate)
3 (Professional)
4 (Expert)
5 (Master)
6 (Guru)
ticket_scope string Ticket scope of the agent.
problem_scope string Problem scope of the agent.
change_scope string Change scope of the agent.
release_scope string Release scope of the agent.
group_ids array of numbers Unique IDs of the groups that the agent is a member of.
role_ids array of numbers Unique IDs of the roles that are granted to the agent.Mandatory
last_login_at timestamp Timestamp of the agent's last successful login.
custom_fields hash Key-value pair containing the names and values of the (custom) agent fields.
created_at datetime Date and time when the agent was created
updated_at datetime Date and time when the agent was last updated

Create an Agent

This operation allows you to create a new agent in Freshservice.

Attribute Type Description
first_name string First name of the agent.Mandatory
last_name string Last name of the agent.
occasional boolean True if the agent is an occasional agent, and false if full-time agent.
job_title string Job title of the agent.
email string Email address of the agent.Mandatory
work_phone_number number Work phone number of the agent.
mobile_phone_number number Mobile phone number of the agent.
reporting_manager_id number User ID of the agent's reporting manager.
time_zone string Time zone of the agent. Read more here.
time_format string Time format for the agent.Possible values:
12h (12 hour format)
24h (24 hour format)
language string Language used by the agent. The default language is “en” (English). Read more here.
location_id number Unique ID of the location associated with the agent.
scoreboard_level_id number Unique ID of the level of the agent in the Arcade. Possible values:
1 (Beginner)
2 (Intermediate)
3 (Professional)
4 (Expert)
5 (Master)
6 (Guru)
group_ids array of numbers Unique IDs of the groups that the agent is a member of.
role_ids array of numbers Unique IDs of the roles that are granted to the agent.Mandatory
signature string Signature of the agent in HTML format.
custom_fields hash Key-value pair containing the names and values of the (custom) agent fields.
post
/api/v2/agents
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"first_name":"Rolanda","last_name":"Hooch","occasional":false,"job_title":"Flying Instructor","email":"rolanda.hooch@hogwarts.edu","work_phone_number":"443532","mobile_phone_number":"553632","reporting_manager_id":2,"time_zone":"Edinburgh","language":"en","location_id":34,"scoreboard_level_id":1,"group_ids":[2,3],"role_ids":[1],"custom_fields":{"quidditch_role":null,"hogsmeade_permission":true}}' 'https://domain.freshservice.com/api/v2/agents'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{ "agent":{ "id":4453, "first_name":"Rolanda", "last_name":"Hooch", "occasional":false, "job_title":"Flying Instructor", "email":"rolanda.hooch@hogwarts.edu", "work_phone_number":"443532", "mobile_phone_number":"553632", "reporting_manager_id":2, "time_zone":"Edinburgh", "time_format":"12h", "language":"en", "location_id":34, "scoreboard_level_id":2, "scopes":{ "ticket":"Global Access", "problem":"Global Access", "change":"Global Access", "release":"Global Access" } "group_ids":[ 2, 3 ], "role_ids":[ 1 ], "last_login_at":"2017-08-30T07:46:41Z", "custom_fields":{ "house": null } } }
EXPAND ↓

View an Agent

This operation allows you to view information about a particular agent.

get
/api/v2/agents/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/agents/1434'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{ "agent":{ "id":1434, "first_name":"Rubeus", "last_name":"Hagrid", "occasional":false, "job_title":"Gamekeeper", "email":"rubeus.hagrid@hogwarts.edu", "work_phone_number":"5564435", "mobile_phone_number":"664345", "reporting_manager_id":32, "time_zone":"Edinburgh", "time_format":"12h", "language":"en", "location_id":34, "scoreboard_level_id":1, "scopes":{ "ticket":"Global Access", "problem":"Global Access", "change":"Global Access", "release":"Global Access" }, "group_ids":[ 2, 3 ], "role_ids":[ 1 ], "last_login_at":"2018-08-30T07:46:41Z", "custom_fields":{ "house": "Gryffindor" } } }
EXPAND ↓

List All Agents

This operation allows you to view information about all agents in the account. Use filters to view only specific agents (those who match the criteria that you choose). The filters listed in the table below can also be combined.

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

Filter by Handle
email, mobile_phone_number, work_phone_number /api/v2/agents?[filter]=[value]
Example:
/api/v2/agents?email=rubeus.hagrid@hogwarts.edu
/api/v2/agents?mobile_phone_number=664345
/api/v2/agents?work_phone_number=5564435
state /api/v2/agents?state=[fulltime/occasional]
Example:
/api/v2/agents?state=fulltime
/api/v2/agents?state=occasional
get
/api/v2/agents
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/agents'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
{ "agents":[ { "id":1434, "first_name":"Rubeus", "last_name":"Hagrid", "occasional":false, "job_title":"Gamekeeper", "email":"rubeus.hagrid@hogwarts.edu", "work_phone_number":"5564435", "mobile_phone_number":"664345", "reporting_manager_id":32, "time_zone":"Edinburgh", "time_format":"12h", "language":"en", "location_id":34, "scoreboard_level_id":1, "scopes":{ "ticket":"Global Access", "problem":"Global Access", "change":"Global Access", "release":"Global Access" }, "group_ids":[ 2, 3 ], "role_ids":[ 1 ], "last_login_at":"2018-08-30T07:46:41Z", "custom_fields":{ "house": "Gryffindor" } }, { "id":1434, "first_name":"Filius", "last_name":"Flitwick", "occasional":false, "job_title":"Professor - Charms", "email":"filius.flitwick@hogwarts.edu", "work_phone_number":"5564436", "mobile_phone_number":"664346", "reporting_manager_id":32, "time_zone":"Edinburgh", "time_format":"12h", "language":"en", "location_id":34, "scoreboard_level_id":1, "scopes":{ "ticket":"Global Access", "problem":"Global Access", "change":"Global Access", "release":"Global Access" }, "group_ids":[ 3, 4 ], "role_ids":[ 1, 2 ], "last_login_at":"2018-09-01T07:46:41Z", "custom_fields":{ "house": "Ravenclaw" } } ] }
EXPAND ↓
Additional examples

Get the first 20 full-time agents. By default, the agents will be returned in alphabetical order and the first page will be displayed.

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/agents?state=fulltime&per_page=20&page=2’
EXPAND ↓

Update an Agent

This operation allows you to modify the profile of a particular agent.

Attribute Type Description
occasional boolean True if the agent is an occasional agent, and false if full-time agent.
email string Email address of the agent.
reporting_manager_id number User ID of the agent's reporting manager.
time_zone string Time zone of the agent. Read more here.
time_format string Time format for the agent.Possible values:
12h (12 hour format)
24h (24 hour format)
language string Language used by the agent. The default language is “en” (English). Read more here.
location_id number Unique ID of the location associated with the agent.
scoreboard_level_id number Unique ID of the level of the agent in the Arcade. Possible values:
1 (Beginner)
2 (Intermediate)
3 (Professional)
4 (Expert)
5 (Master)
6 (Guru)
group_ids array of numbers Unique IDs of the groups that the agent is a member of.
role_ids array of numbers Unique IDs of the roles that are granted to the agent.
signature string Signature of the agent in HTML format.
custom_fields hash Key-value pair containing the names and values of the (custom) agent fields.
put
/api/v2/agents/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H 'Content-Type: application/json' -X PUT -d '{ "scoreboard_level_id": 2, "time_format":"24h"}' 'https://domain.freshservice.com/api/v2/agents/1434'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{ "agent":{ "id":1434, "first_name":"Filius", "last_name":"Flitwick", "occasional":false, "job_title":"Professor - Charms", "email":"filius.flitwick@hogwarts.edu", "work_phone_number":"5564436", "mobile_phone_number":"664346", "reporting_manager_id":32, "time_zone":"Edinburgh", "time_format":"24h", "language":"en", "location_id":34, "scoreboard_level_id":2, "scopes":{ "ticket":"Global Access", "problem":"Global Access", "change":"Global Access", "release":"Global Access" }, "group_ids":[ 3, 4 ], "role_ids":[ 1, 2 ], "last_login_at":"2018-09-01T07:46:41Z", "custom_fields":{ "house": "Ravenclaw" } } }
EXPAND ↓

Delete an Agent

This operation allows you to delete a particular agent.

Note: Deleting an agent will convert the agent into a requester/contact.

delete
/api/v2/agents/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/agents/1434'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

List All Agent Fields

This operation allows you to view all the built-in and custom fields for requesters in your Freshservice account.

AGENT FIELD DESCRIPTION
name Name of the agent field.
label_for_admins Field label shown to admins while editing an agent’s profile
editable_by_admins Signifies whether admins can edit the field value.
mandatory_for_admins Signifies whether admins have to necessarily provide a value for this field.
label_for_agents Field label shown to agents while viewing their own profile
visible_to_agents Signifies whether the field is shown to agents while viewing their own profile
editable_by_agents Signifies whether the field is editable by agents while viewing their own profile
mandatory_for_agents Signifies whether agents have to necessarily provide a value for this field while viewing their own profile.
type Type of data stored in this field
default_field Indicates whether it is a default field or user-defined custom field
get
/api/v2/agent_fields
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/agent_fields'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
{ "agent_fields": [ { "name":"name", "label_for_admins":"Full Name", "mandatory_for_admins":true, "editable_by_admins":false, "label_for_agents":"Full Name", "editable_by_agents":true, "mandatory_for_agents":true, "visible_to_agents":true, "type":"name", "default_field":true }, { "name":"email", "label_for_admins":"Email", "mandatory_for_admins":true, "editable_by_admins":true, "label_for_agents":"Email", "editable_by_agents":false, "mandatory_for_agents":true, "visible_to_agents":true, "type":"email", "default_field":true }, { "name":"job_title", "label_for_admins":"Title", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Title", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"job_title", "default_field":true }, { "name":"work_phone", "label_for_admins":"Work Phone", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Work Phone", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"work_phone", "default_field":true }, { "name":"mobile_phone", "label_for_admins":"Mobile Phone", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Mobile Phone", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"mobile_phone", "default_field":true }, { "name":"location", "label_for_admins":"Location", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Location", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"location", "default_field":true }, { "name":"reporting_manager", "label_for_admins":"Reporting Manager", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Reporting Manager", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"reporting_manager", "default_field":true }, { "name":"groups", "label_for_admins":"Groups", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Groups", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"groups", "default_field":true }, { "name":"role", "label_for_admins":"Roles", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Roles", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"role", "default_field":true }, { "name":"time_zone", "label_for_admins":"Time Zone", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Time Zone", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"time_zone", "default_field":true }, { "name":"time_format", "label_for_admins":"Time Format", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Time Format", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"time_format", "default_field":true }, { "name":"language", "label_for_admins":"Language", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Language", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"language", "default_field":true }, { "name":"level", "label_for_admins":"Level", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Level", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"level", "default_field":true }, { "name":"nickname", "label_for_admins":"Nickname", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Nickname", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"custom_text", "default_field":false }, { "name":"work_history", "label_for_admins":"Work History", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Work History", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"custom_paragraph", "default_field":false }, { "name":"contract_worker", "label_for_admins":"contract_worker", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"contract_worker", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"custom_checkbox", "default_field":false }, { "name":"previous_years_of_experience", "label_for_admins":"Previous Years of Experience", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Previous Years of Experience", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"custom_number", "default_field":false }, { "name":"job_family", "label_for_admins":"Job Family", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Job Family", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"custom_dropdown", "default_field":false }, { "name":"date_of_joining", "label_for_admins":"Date of Joining", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Date of Joining", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"custom_date", "default_field":false }, { "name":"home_phone_number", "label_for_admins":"Home Phone Number", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Home Phone Number", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"custom_phone_number", "default_field":false }, { "name":"google_profile_url", "label_for_admins":"Google Profile URL", "mandatory_for_admins":false, "editable_by_admins":true, "label_for_agents":"Google Profile URL", "editable_by_agents":true, "mandatory_for_agents":false, "visible_to_agents":true, "type":"custom_url", "default_field":false } ] }
EXPAND ↓

Agent Roles

Roles allow you to manage access permissions for agents.

Note:
Only users with "Play God with Super Admin controls" can access the following APIs

Attribute Type Description
description string Description of the role
id number Unique ID of the role
name string Name of the role
scopes json Access scope of the role in various modules
default boolean Set to true if it is a default role, and false otherwise
created_at datetime Date and time when the agent role was created
updated_at datetime Date and time when the agent role was last updated

View a Role

get
/api/v2/roles/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/roles/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{ "role":{ "id": 1, "name": "Account Admin", "description": "Has complete control over the help desk including access to Account or Billing related information, and receives Invoices.", "default": true, "scopes": { "ticket": "Global Access", "problem": "Global Access", "change": "Global Access", "release": "Global Access" }, "created_at": "2018-10-03T10:08:48Z", "updated_at": "2018-10-03T10:08:48Z" } }
EXPAND ↓

List All Roles

get
/api/v2/roles/
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/roles'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{ "roles": [ { "id": 1, "name": "Account Admin", "description": "Has complete control over the help desk including access to Account or Billing related information, and receives Invoices.", "default": true, "scopes": { "ticket": "Global Access", "problem": "Global Access", "change": "Global Access", "release": "Global Access" }, "created_at": "2018-09-27T13:38:18Z", "updated_at": "2018-09-27T13:38:18Z" }, { "id": 2, "name": "Admin", "description": "Can configure all features through the Admin tab, but is restricted from viewing Account or Billing related information.", "default": true, "scopes": { "ticket": "Global Access", "problem": "Global Access", "change": "Global Access", "release": "Global Access" }, "created_at": "2018-09-27T13:38:18Z", "updated_at": "2018-09-27T13:38:18Z" }, { "id": 3, "name": "SD Supervisor", "description": "Can perform all agent related activities and access reports, but cannot access or change configurations in the Admin tab.", "default": true, "scopes": { "ticket": "Global Access", "problem": "Global Access" }, "created_at": "2018-09-27T13:38:18Z", "updated_at": "2018-09-27T13:38:18Z" } ] }
EXPAND ↓

Agent Groups

You can organize your agents into groups like “Linux Support” and “Mac Support”. Segmenting agents into groups lets you easily assign tickets, create specific canned responses, manage workflows and generate group-level reports. The same agent can be a member of multiple groups as well.

Note:
Only users with "Play God with Super Admin controls" privilege can access the following APIs.

Attribute Type Description
name string Name of the group.Mandatory
description string Description of the group.
unassigned_for string The time after which an escalation email is sent if a ticket in the group remains unassigned. The accepted values are “30m” for 30 minutes, “1h” for 1 hour, “2h” for 2 hours“, “4h” for 4 hours, “8h” for 8 hours, “12h” for 12 hours, “1d” for 1 day, “2d” for 2 days, and “3d” for 3 days.
business_hours_id number Unique ID of the business hours configuration associated with the group.
escalate_to number The Unique ID of the user to whom an escalation email is sent if a ticket in this group is unassigned. To create/update a group with an escalate_to value of ‘none’, please set the value of this parameter to ‘null’.
agent_ids array Array of agent user IDs separated by commas.
auto_ticket_assign boolean Describes the automatic ticket assignment type. Will not be supported if the "Round Robin" feature is disabled for the account. Set to true if automatic ticket assignment is enabled, and false otherwise.
created_at datetime Date and time when the agent group was created
updated_at datetime Date and time when the agent group was last updated

Create a Group

Attribute Type Description
name string Name of the group.Mandatory
description string Description of the group.
unassigned_for string The time after which an escalation email is sent if a ticket in the group remains unassigned. The accepted values are “30m” for 30 minutes, “1h” for 1 hour, “2h” for 2 hours“, “4h” for 4 hours, “8h” for 8 hours, “12h” for 12 hours, “1d” for 1 day, “2d” for 2 days, and “3d” for 3 days.
business_hours_id number Unique ID of the business hours configuration associated with the group.
escalate_to number The Unique ID of the user to whom an escalation email is sent if a ticket in this group is unassigned. To create/update a group with an escalate_to value of ‘none’, please set the value of this parameter to ‘null’.
agent_ids array Array of agent user IDs separated by commas.
auto_ticket_assign boolean Describes the automatic ticket assignment type. Will not be supported if the "Round Robin" feature is disabled for the account. Set to true if automatic ticket assignment is enabled, and false otherwise.
post
/api/v2/groups
Sample code | Curl
1
2
curl -v -u user@yourcompany.com:test -H "Content-Type:application/json" -X POST -d '{ "name":"Linux Support", "description":"Support team for Linux VMs, workstations, and servers", "unassigned_for":"30m", "agent_ids":[1,16] }' 'https://domain.freshservice.com/api/v2/groups'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{ group:{ "id":5, "name":"Linux Support", "description":"Support team for Linux VMs, workstations, and servers", "business_hours_id":null, "escalate_to":1, "unassigned_for":"30m", "agent_ids":[ 1, 16 ], "auto_ticket_assign":true, "created_at":"2014-01-08T07:53:41+05:30", "updated_at":"2014-01-08T07:53:41+05:30" } }
EXPAND ↓

View a Group

get
/api/v2/groups/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/groups/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{ "group":{ "id":1, "name":"Linux Support", "description":"Support team for Linux VMs, workstations, and servers", "business_hours_id":null, "escalate_to":1, "unassigned_for":"30m", "agent_ids":[ 2, 15 ], "auto_ticket_assign":true, "created_at":"2014-01-08T07:53:41+05:30", "updated_at":"2014-01-08T07:53:41+05:30" } }
EXPAND ↓

List All Groups

get
/api/v2/groups
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/groups'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[ { "group":{ "id":1, "name":"Linux Support", "description":"Support team for Linux VMs, workstations, and servers", "business_hours_id":null, "escalate_to":1, "unassigned_for":"30m", "agent_ids":[ 2, 15 ], "auto_ticket_assign":true, "created_at":"2014-01-08T07:53:41+05:30", "updated_at":"2014-01-08T07:53:41+05:30" } } ]
EXPAND ↓

Update a Group

Note:
To delete all the agents associated with a group, update the group with "agent_ids"= [ ] (empty array)

Attribute Type Description
name string Name of the group.Mandatory
description string Description of the group.
unassigned_for string The time after which an escalation email is sent if a ticket in the group remains unassigned. The accepted values are “30m” for 30 minutes, “1h” for 1 hour, “2h” for 2 hours“, “4h” for 4 hours, “8h” for 8 hours, “12h” for 12 hours, “1d” for 1 day, “2d” for 2 days, and “3d” for 3 days.
business_hours_id number Unique ID of the business hours configuration associated with the group.
escalate_to number The Unique ID of the user to whom an escalation email is sent if a ticket in this group is unassigned. To create/update a group with an escalate_to value of ‘none’, please set the value of this parameter to ‘null’.
agent_ids array Array of agent user IDs separated by commas.
auto_ticket_assign boolean Describes the automatic ticket assignment type. Will not be supported if the "Round Robin" feature is disabled for the account. Set to true if automatic ticket assignment is enabled, and false otherwise.
put
/api/v2/groups/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "name":"Linux Support", "description":"Support team for Linux VMs, workstations, and servers", "unassigned_for":"30m", "agent_ids":[1,16] }' 'https://domain.freshservice.com/api/v2/groups/2'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{ "group": { "id":2, "name":"Mac Support", "description":"Support team for iMacs, Mac Minis, and MacBooks", "business_hours_id":null, "escalate_to":2, "unassigned_for":"30m", "agent_ids":[ 2, 15 ], "auto_ticket_assign":true, "created_at":"2015-01-08T07:53:41+05:30", "updated_at":"2015-01-08T07:53:41+05:30" } }
EXPAND ↓

Delete a Group

Note:
1. Deleting a Group will only disband the group and not delete its members.
2. Deleted groups cannot be restored.

delete
/api/v2/groups/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/groups/5'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Locations

Locations refer to cities, campuses, offices and rooms where assets and users can be found.

Attribute Type Description
id number Unique ID of the location.
name string Name of the location.Mandatory
parent_location_id number ID of the parent location.
primary_contact_id number User ID of the primary contact (must be a user in Freshservice).
line1 string Address line 1.
line2 string Address line 2.
city string Name of the City.
state string Name of the State.
country string Name of the Country.
zipcode string Zipcode of the location.
created_at datetime Date and time when the location was created
updated_at datetime Date and time when the location was last updated

Create a Location

This operation allows you to create a new location in Freshservice.

Attribute Type Description
id number Unique ID of the location.
name string Name of the location.Mandatory
parent_location_id number ID of the parent location.
primary_contact_id number User ID of the primary contact (must be a user in Freshservice)
line1 string Address line 1.
line2 string Address line 2.
city string Name of the Country.
state string Name of the State.
country string Name of the Country.
zipcode string Zipcode of the location.
post
/api/v2/locations
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"name": "HQ", "parent_location_id": 2, "primary_contact_id": null, "address": {"line1": "1250 Bayhill Drive","line2": "Suite 315", "city": "San Bruno","state": "California","country": "US","zipcode": "94066"}}' 'https://domain.freshservice.com/api/v2/locations'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "location": { "id": 15, "name": "HQ", "parent_location_id": 2, "primary_contact_id": null, "address": { "line1": "1250 Bayhill Drive", "line2": "Suite 315", "city": "San Bruno", "state": "California", "country": "US", "zipcode": "94066" }, "created_at": "2018-12-18T10:03:48Z", "updated_at": "2018-12-18T10:03:48Z" } }
EXPAND ↓

View a Location

This operation allows you to view information about a particular location.

get
/api/v2/locations/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/locations/15’
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "location": { "id": 15, "name": "HQ", "parent_location_id": 2, "primary_contact_id": null, "address": { "line1": "1250 Bayhill Drive", "line2": "Suite 315", "city": "San Bruno", "state": "California", "country": "US", "zipcode": "94066" }, "created_at": "2018-12-18T10:03:48Z", "updated_at": "2018-12-18T10:22:11Z" } }
EXPAND ↓

List all Locations

This operation allows you to view information about all the locations in the account.

get
/api/v2/locations
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/locations’
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{ "locations": [ { "id": 1, "name": "America", "parent_location_id": null, "primary_contact_id": null, "address": { "line1": null, "line2": null, "city": null, "state": null, "country": null, "zipcode": null }, "created_at": "2018-10-31T10:00:07Z", "updated_at": "2018-10-31T10:00:07Z" }, { "id": 2, "name": "Europe", "parent_location_id": null, "primary_contact_id": null, "address": { "line1": null, "line2": null, "city": null, "state": null, "country": null, "zipcode": null }, "created_at": "2018-10-31T10:00:08Z", "updated_at": "2018-10-31T10:00:08Z" } ] }
EXPAND ↓

Update a Location

This operation allows you to update an existing location.

Attribute Type Description
id number Unique ID of the location.
name string Name of the location.
parent_location_id number ID of the parent location.
primary_contact_id number User ID of the primary contact (must be a user in Freshservice).
line1 string Address line 1.
line2 string Address line 2.
city string Name of the City.
state string Name of the State.
country string Name of the Country.
zipcode string Zipcode of the location.
put
/api/v2/locations/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{"name": "HeadQuaters","parent_location_id": 2,"primary_contact_id": null,"address": {"line1": "1250 Bayhill Drive","line2": "Suite 315","city": "San Bruno","state": "California","country": "US","zipcode": "94066"}}' 'https://domain.freshservice.com/api/v2/locations/15'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "location": { "id": 15, "name": "HeadQuaters", "parent_location_id": 2, "primary_contact_id": null, "address": { "line1": "1250 Bayhill Drive", "line2": "Suite 315", "city": "San Bruno", "state": "California", "country": "US", "zipcode": "94066" }, "created_at": "2018-12-18T10:03:48Z", "updated_at": "2018-12-18T10:22:11Z" } }
EXPAND ↓

Delete a Location

This operation allows you to delete a particular location.

delete
/api/v2/locations/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/locations/15’
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Products

When assets refer to individual items existing in an organization, a product refers to a specific model of the asset. For example, every laptop in an organization is an asset while Macbook Pro 15 inches 2019 model is a product. The product catalog contains all the products that were used, are in use or will be used in the organization.

Attribute Type Description
id number Unique ID of the product.
name string Name of the Product.Mandatory
asset_type_id number ID of the asset type(must be a type in Freshservice)Mandatory
manufacturer string Manufacturer of the product
status string Status of the product.
mode_of_procurement string Mode of procurement of the product.
depreciation_type_id number ID of the depreciation type.
description string HTML Content of the product.
description_text string Description of the product in plain text.
created_at string Date and time when the product was created
updated_at string Date and time when the product was last updated

Product Properties

For the following attributes, the supported values are listed below.

Attribute Supported Values Comments
status In Production, In Pipeline, Retired The default value is "In Production"
mode_of_procurement Buy, Lease, Both The default value is "Buy"

Create a Product

This operation allows you to create a new product in Freshservice.

Attribute Type Description
id number Unique ID of the product.
name string Name of the Product.Mandatory
asset_type_id number ID of the asset type(must be a type in Freshservice)Mandatory
manufacturer string Manufacturer of the product
status string Status of the product.
mode_of_procurement string Mode of procurement of the product.
depreciation_type_id number ID of the depreciation type.
description string HTML Content of the product.
description_text string Description of the product in plain text.
created_at string Date and time when the product was created
updated_at string Date and time when the product was last updated

Product Properties

For the following attributes, the supported values are listed below.

Attribute Supported Values Comments
status In Production, In Pipeline, Retired The default value is "In Production"
mode_of_procurement Buy, Lease, Both The default value is "Buy"
post
/api/v2/products
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"name": "XBox", "asset_type_id": 3, "manufacturer": "Flex", "status":"In Pipeline", "mode_of_procurement":"Buy","depreciation_type_id":1,"description":"The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series."}' 'https://domain.freshservice.com/api/v2/products'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "product": { "id": 7, "name": "XBox", "asset_type_id": 3, "manufacturer": "Flex", "status": "In Pipeline", "mode_of_procurement": "Buy", "depreciation_type_id": 1, "description": "<div>The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series.</div>", "description_text": "The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series.", "created_at": "2019-02-12T10:56:44Z", "updated_at": "2019-02-12T10:56:44Z" } }
EXPAND ↓

View a Product

This operation allows you to view a particular product.

get
/api/v2/products/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/products/7'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "product": { "id": 7, "name": "XBox", "asset_type_id": 3, "manufacturer": "Flex", "status": "In Pipeline", "mode_of_procurement": "Buy", "depreciation_type_id": 1, "description": "<div>The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series.</div>", "description_text": "The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series.", "created_at": "2019-02-12T10:56:44Z", "updated_at": "2019-02-12T10:56:44Z" } }
EXPAND ↓

List All Products

This operation allows you to view information about all products in the account.

get
/api/v2/products
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/products'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{ "products": [ { "id": 2, "name": "iPhone 8", "asset_type_id": 28, "manufacturer": "Apple", "status": "In Production", "mode_of_procurement": "Lease", "depreciation_type_id": 2, "description": "", "description_text": "" "created_at": "2019-01-03T06:56:05Z", "updated_at": "2019-01-03T06:56:05Z" }, { "id": 7, "name": "XBox", "asset_type_id": 3, "manufacturer": "Flex", "status": "In Pipeline", "mode_of_procurement": "Buy", "depreciation_type_id": 1, "description": "<div>The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series.</div>", "description_text": "The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series.", "created_at": "2019-02-12T10:56:44Z", "updated_at": "2019-02-12T10:56:44Z" } ] }
EXPAND ↓

Update a Product

This operation allows you to update an existing product.

Attribute Type Description
id number Unique ID of the product.
name string Name of the Product.Mandatory
asset_type_id number ID of the asset type(must be a type in Freshservice)Mandatory
manufacturer string Manufacturer of the product
status string Status of the product.
mode_of_procurement string Mode of procurement of the product.
depreciation_type_id number ID of the depreciation type.
description string HTML Content of the product.
description_text string Description of the product in plain text.
created_at string Date and time when the product was created
updated_at string Date and time when the product was last updated

Product Properties

For the following attributes, the supported values are listed below.

Attribute Supported Values Comments
status In Production, In Pipeline, Retired The default value is "In Production"
mode_of_procurement Buy, Lease, Both The default value is "Buy"
put
/api/v2/products/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"name": "XBox", "asset_type_id": 3, "manufacturer": "Flex", "status":"In Production", "mode_of_procurement":"Buy","depreciation_type_id":2,"description":"The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series."}' 'https://domain.freshservice.com/api/v2/products/7'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "product": { "id": 7, "name": "XBox", "asset_type_id": 3, "manufacturer": "Flex", "status": "In Production", "mode_of_procurement": "Buy", "depreciation_type_id": 2, "description": "The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series.", "description_text": "The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series.", "created_at": "2019-02-12T10:56:44Z", "updated_at": "2019-02-12T10:59:31Z" } }
EXPAND ↓

Delete a Product

This operation allows you to delete a particular product.

delete
/api/v2/products/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/products/7’
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Vendors

Vendors refer to third-party companies and service providers who provide the necessary assets or services to your organization.

Attribute Type Description
id number Unique ID of the vendor.
name string Name of the vendor.Mandatory
description string Description of the vendor.
primary_contact_id number User ID of the primary contact (must be a user in Freshservice).
line1 string Address line 1.
line2 string Address line 2.
city string Name of the city.
state string Name of the state.
country string Name of the country.
zipcode string Zipcode of the location.
created_at datetime Date and time when the vendor was created
updated_at datetime Date and time when the vendor was last updated

Create a Vendor

This operation allows you to create a vendor.

Attribute Type Description
name string Name of the vendor.Mandatory
description string Description of the vendor.
primary_contact_id number User ID of the primary contact (must be a user in Freshservice).
line1 string Address line 1.
line2 string Address line 2.
city string Name of the city.
state string Name of the state.
country string Name of the country.
zipcode string Zipcode of the location.
post
/api/v2/vendors
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"name": "Intel","description": "Intel Corp", "primary_contact_id": null, "address": {"line1": "1250 Bayhill Drive","line2": "Suite 315", "city": "San Bruno","state": "California","country": "US","zipcode": "94066"}}' 'https://domain.freshservice.com/api/v2/vendors'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "vendor": { "id": 15, "name": "Intel", "description": "Intel Corp", "primary_contact_id": null, "address": { "line1": "1250 Bayhill Drive", "line2": "Suite 315", "city": "San Bruno", "state": "California", "country": "US", "zipcode": "94066" }, "created_at": "2018-12-18T10:03:48Z", "updated_at": "2018-12-18T10:03:48Z" } }
EXPAND ↓

View a Vendor

This operation allows you to view a particular vendor.

get
/api/v2/vendors/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/vendors/15'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "vendor": { "id": 15, "name": "Intel", "description": "Intel Corp", "primary_contact_id": 2, "address": { "line1": "1250 Bayhill Drive", "line2": "Suite 315", "city": "San Bruno", "state": "California", "country": "US", "zipcode": "94066" }, "created_at": "2018-12-18T10:03:48Z", "updated_at": "2018-12-18T10:22:11Z" } }
EXPAND ↓

List All Vendors

This operation allows you to view information about all vendors in the account.

get
/api/v2/vendors
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/vendors'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{ "vendors": [ { "id": 1, "name": "Apple", "description": "AAPL", "primary_contact_id": null, "address": { "line1": null, "line2": null, "city": null, "state": null, "country": null, "zipcode": null }, "created_at": "2018-10-31T10:00:08Z", "updated_at": "2018-10-31T10:00:08Z" }, { "id": 15, "name": "Intel", "description": "Intel Corp", "primary_contact_id": 2, "address": { "line1": "1250 Bayhill Drive", "line2": "Suite 315", "city": "San Bruno", "state": "California", "country": "US", "zipcode": "94066" }, "created_at": "2018-10-31T10:00:07Z", "updated_at": "2018-10-31T10:00:07Z" } ] }
EXPAND ↓

Update a Vendor

This operation allows you to update a vendor.

Attribute Type Description
name string Name of the vendor.Mandatory
description string Description of the vendor.
primary_contact_id number User ID of the primary contact (must be a user in Freshservice).
line1 string Address line 1.
line2 string Address line 2.
city string Name of the city.
state string Name of the state.
country string Name of the country.
zipcode string Zipcode of the location.
put
/api/v2/vendors/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{"name": "Apple","description": "AAPL","primary_contact_id": null,"address": {"line1": "‎1 Infinite Loop","city": "Cupertino","state": "California","country": "US","zipcode": "95014"}}' 'https://domain.freshservice.com/api/v2/vendors/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "vendor": { "id": 1, "name": "Apple", "description": "AAPL", "primary_contact_id": null, "address": { "line1": "‎1 Infinite Loop", "line2": null, "city": "Cupertino", "state": "California", "country": "US", "zipcode": "95014" }, "created_at": "2018-12-18T10:03:48Z", "updated_at": "2018-12-18T10:03:48Z" } }
EXPAND ↓

Delete a Vendor

This operation allows you to delete a vendor.

delete
/api/v2/vendors/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/vendors/5'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Assets

Assets are any items that are owned and managed in an organization. These include laptops, servers, monitors, printers, routers, etc. The Assets module in Freshservice allows you to manage the entire lifecycle of an asset, right from its procurement to retirement. During the reporting of an IT issue, the asset is often tagged along with the ticket either by the requester or the agent.

Attribute Type Description
id number Unique ID of the asset.
display_id numbers Display ID of the asset.
name string Name of the asset.Mandatory
description string Description of the asset.
asset_type_id number ID of the asset type.Mandatory
asset_tag string Asset tag of the asset.
impact string Impact of the asset.
author_type string Indicates whether the asset was created by a user or discovery tools (Probe or Agent).Read Only
usage_type string Usage type of the asset (Loaner / Permanent).
user_id number ID of the associated user (Used By).
location_id number ID of the associated location.
department_id number ID of the associated department.
agent_id number ID of the associated agent (Managed By).
group_id number ID of the associated agent group (Managed By Group).
assigned_on datetime Date and time when the asset was assigned.
created_at datetime Date and time when the asset was created.Read Only
updated_at datetime Date and time when the asset was updated.Read Only

Asset Properties

For the following attributes, the supported values are listed below.

Attribute Supported Values Comments
impact low, medium, high The default value is “low”
usage_type permanent, loaner The default value is “permanent”

Create an Asset

This operation allows you to create a new asset in Freshservice.

Attribute Type Description
id number Unique ID of the asset.
display_id numbers Display ID of the asset.
name string Name of the asset.Mandatory
description string Description of the asset.
asset_type_id number ID of the asset type.Mandatory
asset_tag string Asset tag of the asset.
impact string Impact of the asset.
author_type string Indicates whether the asset was created by a user or discovery tools (Probe or Agent).Read Only
usage_type string Usage type of the asset (Loaner / Permanent).
user_id number ID of the associated user (Used By).
location_id number ID of the associated location.
department_id number ID of the associated department.
agent_id number ID of the associated agent (Managed By).
group_id number ID of the associated agent group (Managed By Group).
assigned_on datetime Date and time when the asset was assigned.
created_at datetime Date and time when the asset was created.Read Only
updated_at datetime Date and time when the asset was updated.Read Only

Asset Properties

For the following attributes, the supported values are listed below.

Attribute Supported Values Comments
impact low, medium, high The default value is “low”
usage_type permanent, loaner The default value is “permanent”
post
/api/v2/assets
Sample code | Curl
1
2
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "name": "Macbook Pro","asset_type_id": 25, "asset_tag":"ASSET-9", "impact":"low", "usage_type":"permanent", "description":"13.3-inch (diagonal) LED-backlit glossy widescreen display,1440-by-900 resolution", "location_id":null, "agent_id":null, "department_id":null, "group_id":9, "assigned_on": "2014-07-26T12:25:04+05:30", "type_fields": { "product_25" : 10, "vendor_25" : 14, "cost_25":5000 , "salvage":100, "depreciation_id":30, "warranty_25":20, "acquisition_date_25":"2018-07-26T12:25:04+05:30", "warranty_expiry_date_25":"2018-07-26T12:25:04+05:30", "domain_25":1, "asset_state_25":"In Use", "serial_number_25":"SW12131133", "last_audit_date_25":"2014-07-26T12:25:04+05:30" } }' 'https://domain.freshservice.com/api/v2/assets'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{ "asset": { "id": 10, "display_id": 11, "name": "Macbook Pro", "description": "13.3-inch (diagonal) LED-backlit glossy widescreen display,1440-by-900 resolution", "asset_type_id": 25, "impact": "low", "author_type": "User", "usage_type": "permanent", "asset_tag": "ASSET-9", "user_id": null, "department_id": null, "location_id": null, "agent_id": null, "group_id": 9, "assigned_on": "2014-07-26T06:55:04Z", "created_at": "2019-03-07T09:27:09Z", "updated_at": "2019-03-07T09:27:09Z", "type_fields": { "product_25" : 10, "vendor_25" : 14, "cost_25":5000 , "salvage":100, "depreciation_id":30, "warranty_25":20, "acquisition_date_25":"2018-07-26T12:25:04+05:30", "warranty_expiry_date_25":"2018-07-26T12:25:04+05:30", "domain_25":1, "asset_state_25":"In Use", "serial_number_25":"SW12131133", "last_audit_date_25":"2014-07-26T12:25:04+05:30", } } }
EXPAND ↓

View an Asset

This operation allows you to view a particular asset.

Use 'include' to embed additional details in the response. Each include will consume an additional API credit.

Embed Handle
type_fields /api/v2/assets/[display_id]?include=type_fields
Will return all fields that are specific to each asset type. For example, for Hardware Asset Type, including type_fields will return fields such as Product_ID, Vendor_ID and Serial_number
get
/api/v2/assets/[display_id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets/11'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{ "asset": { "id": 10, "display_id": 11, "name": "Macbook Pro", "description": "13.3-inch (diagonal) LED-backlit glossy widescreen display,1440-by-900 resolution", "asset_type_id": 3, "impact": "low", "author_type": "User", "usage_type": "permanent", "asset_tag": "ASSET-9", "user_id": null, "department_id": null, "location_id": null, "agent_id": null, "group_id": 9, "assigned_on": "2014-07-26T06:55:00Z", "created_at": "2019-03-06T09:34:37Z", "updated_at": "2019-03-06T10:23:06Z" } }
EXPAND ↓
Additional examples

1. Get the associated type fields along with the asset response.

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets/11?include=type_fields'
EXPAND ↓

List All Assets

Lists all the assets in your Freshservice account.

Use Asset Filters to view only specific assets (those which match the criteria that you choose). By default only assets that are not in trash will be returned unless you use the 'trashed' filter.

Note:
1. By default, assets will be sorted based on "created_at" date (most recent on top).
2. By default, only the base attributes of the asset will be retrieved.
3. To get all the attributes, including asset type specific fields, use 'include' to embed additional details in the response.
4. Each include will consume an additional 2 credits. For example, if you embed the 'type_fields' information you will be charged a total of 3 API credits for the call.

Sort by Handle
id, created_at, updated_at /api/v2/assets?order_by=created_at
Default order by is created_at.
asc, desc /api/v2/assets?order_type=asc
Default sort order is desc.
Embed Handle
type_fields /api/v2/assets?include=type_fields
Will return all fields that are specific to each asset type. For example, for Hardware Asset Type, including type_fields will return fields such as Product_ID, Vendor_ID, Serial_number, etc.
trashed /api/v2/assets?trashed=true
Will return all the assets that are in trash.
get
/api/v2/assets
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{ "assets": [ { "id": 65, "display_id": 65, "name": "Asset-65", "description": "", "asset_type_id": 25, "impact": "low", "author_type": "User", "usage_type": "permanent", "asset_tag": "ASSET-65", "user_id": null, "location_id": null, "department_id": null, "agent_id": null, "assigned_on": null, "created_at": "2018-08-03T07:48:11Z", "updated_at": "2018-08-03T07:48:11Z" }, { "id": 64, "display_id": 64, "name": "Asset_64", "description": "", "asset_type_id": 25, "impact": "low", "author_type": "User", "usage_type": "permanent", "asset_tag": "ASSET-64", "user_id": null, "location_id": null, "department_id": null, "agent_id": null, "assigned_on": null, "created_at": "2018-08-03T07:48:04Z", "updated_at": "2018-08-03T07:48:04Z" } ] }
EXPAND ↓
Additional examples

1. Get the second page (assets from 31-60) of a list of all active filter_assets.

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets?per_page=30&page=2'
EXPAND ↓

2. Get the first page of a list of assets including all type fields. The assets will be listed in descending order by Created at Date.

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets?include=type_fields'
EXPAND ↓

3. Get the first page of a list of assets by updated_at date sorted in descending order.

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets?order_by=updated_at&order_type=desc'
EXPAND ↓

4. Get the first page of a list of assets in trash.

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets?trashed=true'
EXPAND ↓

Filter Assets

Use asset attributes to filter your list.

Note:
1. Filtered results cannot be sorted. By default it is sorted by created_at in descending order.
2. The query must be URL encoded (see example).
3. Query can be framed using the name of the asset fields, which can be obtained from Supported Asset Fields section.
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters.
5. Logical operators AND, OR along with parentheses () can be used to group conditions.
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields.
7. Input for date fields should be in UTC Format.
8. The number of objects returned per page is 30. The total count of the results will be returned along with the result (In the headers).
9. To scroll through the pages add page parameter to the url. The page number starts with 1 and should not exceed 40.
10. To filter for fields with no values assigned, use the null keyword.
11. Please note that any updates made to assets either in Freshservice application or through APIs may take a few minutes to get indexed, after which the updated results will be available through API.

Supported Asset Fields

Field Type Description
asset_type_id integer ID of the asset type.
department_id integer ID of the department to which the asset belongs.
location_id integer ID of the location.
asset_state string Status of the asset (Eg. IN USE).
user_id integer ID of the user to whom the asset is assigned.
agent_id integer ID of the agent by whom the asset is managed.
name string Display name of the asset.
asset_tag string Tag that is assigned to the asset.
created_at date Date (YYYY-MM-DD) when the asset is created.Read Only
updated_at date Date (YYYY-MM-DD) when the asset is updated.Read Only
get
/api/v2/assets?query=[query]
Additional examples

1. Get the second page of assets (including asset type specific fields) that are In Stock and created since 2018-08-10.

" asset_state:'IN STOCK' AND created_at:>'2018-08-10' "

1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets?include=type_fields&query="asset_state:%27IN%20STOCK%27%20AND%20created_at:>%272018-08-10%27"&page=2'
EXPAND ↓

Update an Asset

This operation allows you to update an existing asset.

Attribute Type Description
id number Unique ID of the asset.
display_id numbers Display ID of the asset.
name string Name of the asset.
description string Description of the asset.
asset_type_id number ID of the asset type.
asset_tag string Asset tag of the asset.
impact string Impact of the asset.
author_type string Indicates whether the asset was created by a user or discovery tools (Probe or Agent).Read Only
usage_type string Usage type of the asset (Loaner / Permanent).
user_id number ID of the associated user (Used By).
location_id number ID of the associated location.
department_id number ID of the associated department.
agent_id number ID of the associated agent (Managed By).
group_id number ID of the associated agent group (Managed By Group).
assigned_on datetime Date and time when the asset was assigned.
created_at datetime Date and time when the asset was created.Read Only
updated_at datetime Date and time when the asset was updated.Read Only

Asset Properties

For the following attributes, the supported values are listed below.

Attribute Supported Values Comments
impact low, medium, high The default value is “low”
usage_type permanent, loaner The default value is “permanent”
put
/api/v2/assets/[display_id]
Sample code | Curl
1
2
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "name": "Macbook Pro 2","asset_type_id": 25, "asset_tag":"ASSET-9", "impact":"high", "usage_type":"loaner", "description":"13.3-inch (diagonal) LED-backlit glossy widescreen display,1440-by-900 resolution", "location_id":null, "agent_id":null, "department_id":null, "group_id":9, "assigned_on": "2014-07-26T12:25:04+05:30", "type_fields": { "product_25" : 10, "vendor_25" : 14, "cost_25":5000 , "salvage":100, "depreciation_id":30, "warranty_25":20, "acquisition_date_25":"2018-07-26T12:25:04+05:30", "warranty_expiry_date_25":"2018-07-26T12:25:04+05:30", "domain_25":1, "asset_state_25":"In Use", "serial_number_25":"SW12131133", "last_audit_date_25":"2014-07-26T12:25:04+05:30" } }' 'https://domain.freshservice.com/api/v2/assets/11'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{ "asset": { "id": 10, "display_id": 11, "name": "Macbook Pro 2", "description": "13.3-inch (diagonal) LED-backlit glossy widescreen display,1440-by-900 resolution", "asset_type_id": 25, "impact": "high", "author_type": "User", "usage_type": "loaner", "asset_tag": "ASSET-9", "user_id": null, "department_id": null, "location_id": null, "agent_id": null, "group_id": 9, "assigned_on": "2014-07-26T06:55:04Z", "created_at": "2019-03-07T09:27:09Z", "updated_at": "2019-03-07T09:27:09Z", "type_fields": { "product_25" : 10, "vendor_25" : 14, "cost_25":5000 , "salvage":100, "depreciation_id":30, "warranty_25":20, "acquisition_date_25":"2018-07-26T12:25:04+05:30", "warranty_expiry_date_25":"2018-07-26T12:25:04+05:30", "domain_25":1, "asset_state_25":"In Use", "serial_number_25":"SW12131133", "last_audit_date_25":"2014-07-26T12:25:04+05:30", } } }
EXPAND ↓

Delete an Asset

This operation allows you to delete a particular asset.

delete
/api/v2/assets/[display_id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/assets/9’
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Restore an Asset

This operation allows you to restore a deleted asset.

put
/api/v2/assets/[display_id]/restore
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X PUT 'https://domain.freshservice.com/api/v2/assets/9/restore’
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

Delete an Asset Permanently

This operation allows you to permanently delete an asset which cannot be restored later.

put
/api/v2/assets/[display_id]/delete_forever
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X PUT 'https://domain.freshservice.com/api/v2/assets/9/delete_forever’
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

List all Asset Components

This operation allows you to view information about all the components of an asset in the account.

Attribute Type Description
id number Unique ID of the component.
component_type string Type of the Component. (Example: Processor, Memory)
component_data json Details of the Component.
created_at datetime Date and time when the component was created.Read Only
updated_at datetime Date and time when the component was updated.Read Only
get
/api/v2/assets/[display_id]/components
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets/1/components'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{ "components": [ { "id": 989, "created_at": "2019-04-03T07:24:08Z", "updated_at": "2019-04-03T07:24:21Z", "component_type": "Processor", "component_data": [ { "manufacturer": "Intel_0", "cpu_speed": "2.1 GHz", "no_of_cores": "4", "model": "Core i7 (7th Generation)", "socket": "8", "cores_per_socket": "2", "logical_processor": "8", "hyperthread": "Yes" }, { "manufacturer": "Intel_1", "cpu_speed": "2.1 GHz", "no_of_cores": "4", "model": "Core i7 (7th Generation)", "socket": "8", "cores_per_socket": "2", "logical_processor": "8", "hyperthread": "Yes" } ] }, { "id": 990, "created_at": "2019-04-03T07:24:09Z", "updated_at": "2019-04-03T07:24:22Z", "component_type": "Memory", "component_data": [ { "socket": "4", "capacity": "1 TB", "module_tag": "Tag 9", "memory_type": "SATA", "model": "M210", "manufacturer": "Intel", "speed": "2100 RPM" } ] } ] }
EXPAND ↓

List All Associated Requests

This operation allows you to view a list of all the requests associated to the asset in the account.

Attribute Type Description
id number Unique ID of the request.
request_type string Type of the request associated to the Asset. (Example: Ticket, Change...etc).
request_id string Display ID of the request. (Example: #INC-1).
request_details string Subject of the request.
request_status string Status of the request.
created_at datetime Date and time when the request was created.Read Only
updated_at datetime Date and time when the request was updated.Read Only
get
/api/v2/assets/[display_id]/requests
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets/1/requests'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{ "requests": [ { "id": 1, "created_at": "2019-04-29T15:54:22Z", "updated_at": "2019-04-29T15:54:22Z", "request_type": "Ticket", "request_id": "INC-61", "request_details": "What’s wrong with my email?", "request_status": "Open" }, { "id": 2, "created_at": "2019-04-29T15:55:24Z", "updated_at": "2019-04-29T15:55:24Z", "request_type": "Problem", "request_id": "PRB-1", "request_details": "Unable to reach email server", "request_status": "Change Requested" }, { "id": 3, "created_at": "2019-04-29T15:55:41Z", "updated_at": "2019-04-29T15:55:41Z", "request_type": "Change", "request_id": "CHN-2", "request_details": "Upgrade Web Server", "request_status": "Awaiting Approval" }, { "id": 4, "created_at": "2019-04-29T15:56:20Z", "updated_at": "2019-04-29T15:56:20Z", "request_type": "Release", "request_id": "REL-1", "request_details": "Replacing Exchange Server 3 (ES3)", "request_status": "In Progress" } ] }
EXPAND ↓

List all associated Contracts

This operation allows you to get a list of all the contracts that an asset has been associated to.

Attribute Type Description
id string Contract ID specific to your account. Read-Only
contract_id string Unique Contract Number. Mandatory
contract_type string Type of the Contract.(Example: Lease, Maintenance) Mandatory
contract_name string Subject/Title of the Contract Mandatory
contract_status string Status of the contract.(Example: Active, Draft) Read-Only
get
/api/v2/assets/[display_id]/contracts
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/assets/1/contracts'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ contracts: [ { id: 1, contract_id: "CNTR-1", contract_type: "Maintenance", contract_name: "Contract Title", contract_status: "Active" }, { id: 2, contract_id: "CNTR-2", contract_type: "Lease", contract_name: "New Contract", contract_status: "Draft" } ] }
EXPAND ↓

Asset Types

Asset types are a broad classification of different collection of assets. In Freshservice, several default asset types are provided out of the box and custom asset types can be created at the root level or within another asset type. The default asset types can be enabled or disabled as needed as well.

Attribute Type Description
id number Unique ID of the asset type.
name string Name of the asset type.Mandatory
description string Short description of the asset type.
parent_asset_type_id number ID of the parent asset type.
visible boolean Visibility of the default asset type. Set to true if the asset type is visible. Custom asset types are set to true by default and cannot be modified.
created_at datetime Date and time when the asset type was created
updated_at datetime Date and time when the asset type was last updated

Create an Asset Type

This operation allows you to create an asset type in Freshservice.

Attribute Type Description
name string Name of the asset type.Mandatory
description string Short description of the asset type.
parent_asset_type_id number ID of the parent asset type.
post
/api/v2/asset_types
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"name": "Chromebook", "parent_asset_type_id": 8, "description":"Asset type for all chromebooks"}' 'https://domain.freshservice.com/api/v2/asset_types'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
{ "asset_type": { "id": 50, "name": "Chromebook", "parent_asset_type_id": 11, "description": "Asset type for all chromebooks", "visible": true "created_at": "2019-02-14T10:03:02Z", "updated_at": "2019-02-14T10:03:02Z" } }
EXPAND ↓

View an Asset Type

This operation allows you to view information about a particular asset type

get
/api/v2/asset_types/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/asset_types/50’
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
{ "asset_type": { "id": 50, "name": "Chromebook", "parent_asset_type_id": 8, "description": "Asset type for all Chromebooks", "visible": true "created_at": "2019-02-14T10:03:02Z", "updated_at": "2019-02-14T10:03:02Z" } }
EXPAND ↓

List all Asset Types

This operation allows you to view information about all the asset types in the account.

get
/api/v2/asset_types
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/asset_types’
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{ "asset_types": [ { "id": 1, "name": "Services", "parent_asset_type_id": null, "description": "", "visible": true "created_at": "2019-02-14T10:08:02Z", "updated_at": "2019-02-14T10:08:02Z" }, { "id": 2, "name": "Cloud", "parent_asset_type_id": null, "description": "", "visible": true "created_at": "2019-02-14T10:03:02Z", "updated_at": "2019-02-14T10:03:02Z" } ] }
EXPAND ↓

Update an Asset Type

This operation allows you to update an existing asset type.

Attribute Type Description
name string Name of the asset type.
description string Short description of the asset type.
visibile boolean Visibility of the default asset type. Set to true if the asset type is visible. Custom asset types are set to true by default and cannot be modified
put
/api/v2/asset_types/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{"description":"Chromebooks Asset Type", "visible": false}' 'https://domain.freshservice.com/api/v2/asset_types/50'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
{ "asset_type": { "id": 50, "name": "Chromebook", "parent_asset_type_id": 8, "description": "Chromebooks Asset Type", "visible": false "created_at": "2019-02-14T10:03:02Z", "updated_at": "2019-02-14T10:03:02Z" } }
EXPAND ↓

Delete an Asset Type

This operation allows you to delete a particular asset type.

delete
/api/v2/asset_types/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X DELETE 'https://domain.freshservice.com/api/v2/asset_types/50’
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

List all Fields of an Asset Type

This operation allows you to view information about all the fields in a particular asset type in the account.

get
/api/v2/asset_types/[id]/fields
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/asset_types/636/fields’
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
{ "asset_type_fields": [ { "field_header": "General", "fields": [ { "id": null, "created_at": null, "updated_at": null, "asset_type_id": null, "name": "name", "label": "Display Name", "field_type": "text", "data_type": "string", "required": true, "is_unique": false, "default_field": true, }, { "id": null, "created_at": null, "updated_at": null, "asset_type_id": null, "name": "asset_tag", "label": "Asset Tag", "field_type": "text", "data_type": "string", "required": false, "is_unique": false, "default_field": true }, { "id": null, "created_at": null, "updated_at": null, "asset_type_id": null, "name": "asset_type_id", "label": "Asset Type", "field_type": "dropdown", "data_type": "integer", "required": true, "is_unique": false, "default_field": true }, { "id": null, "created_at": null, "updated_at": null, "asset_type_id": null, "name": "description", "label": "Description", "field_type": "paragraph", "data_type": "text", "required": false, "is_unique": false, "default_field": true } ] }, { "field_header": "Assignment", "fields": [ { "id": null, "created_at": null, "updated_at": null, "asset_type_id": null, "name": "location_id", "label": "Location", "field_type": "dropdown", "data_type": "integer", "required": false, "is_unique": false, "default_field": true }, { "id": null, "created_at": null, "updated_at": null, "asset_type_id": null, "name": "department_id", "label": "Department", "field_type": "dropdown", "data_type": "integer", "required": false, "is_unique": false, "default_field": true } ] }, { "field_header": "Hardware", "fields": [ { "id": 1631, "created_at": "2019-03-07T09:46:17Z", "updated_at": "2019-03-07T09:46:17Z", "asset_type_id": 636, "name": "product_636", "label": "Product", "field_type": "dropdown", "data_type": "integer", "required": true, "is_unique": false, "default_field": true }, { "id": 1632, "created_at": "2019-03-07T09:46:17Z", "updated_at": "2019-03-07T09:46:17Z", "asset_type_id": 636, "name": "vendor_636", "label": "Vendor", "field_type": "dropdown", "data_type": "integer", "required": false, "is_unique": false, "default_field": true }, { "id": 1638, "created_at": "2019-03-07T09:46:17Z", "updated_at": "2019-03-07T09:46:17Z", "asset_type_id": 636, "name": "asset_state_636", "label": "Asset State", "field_type": "dropdown", "data_type": "string", "required": true, "is_unique": false, "default_field": true, "choices": [ [ "In Stock", 4 ], [ "In Transit", 3 ], [ "In Use", 1 ], [ "Missing", 2 ], [ "Retired", 5 ] ] }, { "id": 1639, "created_at": "2019-03-07T09:46:17Z", "updated_at": "2019-03-07T09:46:17Z", "asset_type_id": 636, "name": "serial_number_636", "label": "Serial Number", "field_type": "text", "data_type": "string", "required": false, "is_unique": false, "default_field": true, } ] } ] }
EXPAND ↓

Departments / Companies

Attribute Type Description
id integer Unique identifier of the department
name string Name of the departmentMandatory
description string Description about the department
head_user_id integer Unique identifier of the agent or requester who serves as the head of the department
prime_user_id integer Unique identifier of the agent or requester who serves as the prime user of the department
domains array of strings Email domains associated with the department
custom_fields hash Custom fields that are associated with departments
created_at date-time Timestamp at which the department was created
updated_at date-time Timestamp at which the department was last modified

Create a Department

Create a new Department (or Company in MSP Mode) in Freshservice.

Attribute Type Description
id integer Unique identifier of the department
name string Name of the departmentMandatory
description string Description about the department
head_user_id integer Unique identifier of the agent or requester who serves as the head of the department
prime_user_id integer Unique identifier of the agent or requester who serves as the prime user of the department
domains array of strings Email domains associated with the department
custom_fields hash Custom fields that are associated with departments
created_at date-time Timestamp at which the department was created
updated_at date-time Timestamp at which the department was last modified
post
/api/v2/departments
Sample code | Curl
1
curl -v -u api.user@ministryofmagic.gov:test -H 'Content-Type: application/json' -X POST -d '{"name":"Department for the Regulation and Control of Magical Creatures","description":"Beast, Being and Spirit Divisions, and Pest Advisory Bureau.","head_user_id":5,"prime_user_id":6,"domains":["creatures.ministryofmagic.gov"],"custom_fields":{"location":"Level 3"}}' 'https://domain.freshservice.com/api/v2/departments'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "department":{ "id":3, "name":"Department for the Regulation and Control of Magical Creatures", "description":"Beast, Being and Spirit Divisions, and Pest Advisory Bureau.", "head_user_id":5, "prime_user_id":6, "domains":[ "creatures.ministryofmagic.gov" ], "custom_fields":{ "location":"Level 3" } } }
EXPAND ↓

View a Department

Retrieve the Department (or Company in MSP Mode) with the given ID from Freshservice

get
/api/v2/departments/[id]
Sample code | Curl
1
curl -v -u api.user@ministryofmagic.gov:test -X GET 'https://domain.freshservice.com/api/v2/departments/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "department":{ "id":1, "name":"Department of Magical Law Enforcement", "description":"Improper Use of Magic Office, Auror Headquarters, and Wizengamot Administration Services.", "head_user_id":1, "prime_user_id":2, "domains":[ "law.ministryofmagic.gov" ], "custom_fields":{ "location":"Level 2" } } }
EXPAND ↓

List All Departments

Retrieve a list of all Departments (or Companies in MSP Mode) in Freshservice

get
/api/v2/departments
Sample code | Curl
1
curl -v -u api.user@ministryofmagic.govhogwarts.edu:test -X GET 'https://domain.freshservice.com/api/v2/departments'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{ "departments":[ { "id":1, "name":"Department of Magical Law Enforcement", "description":"Improper Use of Magic Office, Auror Headquarters, and Wizengamot Administration Services.", "head_user_id":1, "prime_user_id":2, "domains":[ "law.ministryofmagic.gov" ], "custom_fields":{ "location":"Level 2" }, "created_at":"2019-04-04T04:45:15.983Z", "updated_at":"2019-04-04T04:45:15.983Z" }, { "id":2, "name":"Department of Magical Accidents and Catastrophes", "description":"Accidental Magic Reversal Squad, Obliviator Headquarters, and Muggle-Worthy Excuses Committee.", "head_user_id":3, "prime_user_id":4, "domains":[ "accidents.ministryofmagic.gov" ], "custom_fields":{ "location":"Level 3" }, "created_at":"2019-04-04T04:45:15.983Z", "updated_at":"2019-04-04T04:45:15.983Z" } ] }
EXPAND ↓

Update a Department

Update an existing Department (or Company in MSP Mode) in Freshservice.

Attribute Type Description
id integer Unique identifier of the department
name string Name of the departmentMandatory
description string Description about the department
head_user_id integer Unique identifier of the agent or requester who serves as the head of the department
prime_user_id integer Unique identifier of the agent or requester who serves as the prime user of the department
domains array of strings Email domains associated with the department
custom_fields hash Custom fields that are associated with a Freshservice entity
created_at date-time Timestamp at which the department was created
updated_at date-time Timestamp at which the department was last modified
put
/api/v2/departments/[id]
Sample code | Curl
1
curl -v -u api.user@hogwarts.edu:test -H 'Content-Type: application/json' -X PUT -d '{"name":"Department for the Regulation and Control of Magical Creatures","description":"Beast, Being and Spirit Divisions, and Pest Advisory Bureau.","head_user_id":5,"prime_user_id":7,"domains":["creatures.ministryofmagic.gov"],"custom_fields":{"location":"Level 3"}}' 'https://domain.freshservice.com/api/v2/departments/3'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "department":{ "id":3, "name":"Department for the Regulation and Control of Magical Creatures", "description":"Beast, Being and Spirit Divisions, and Pest Advisory Bureau.", "head_user_id":5, "prime_user_id":7, "domains":[ "creatures.ministryofmagic.gov" ], "custom_fields":{ "location":"Level 3" } } }
EXPAND ↓

Delete a Department

Delete the Department (or Company in MSP Mode) with the given ID from Freshservice.

delete
/api/v2/departments/[id]
Sample code | Curl
1
curl -v -u api.user@hogwarts.edu:test -X DELETE 'https://domain.freshservice.com/api/v2/departments/3'
EXPAND ↓
Response
1
HTTP Status: 204 No Content
EXPAND ↓

List All Department Fields

Retrieve the Department Fields (or Company Fields in MSP Mode) from Freshservice. The fields will be returned in the sequence that they are displayed on the UI.

get
/api/v2/department_fields
Sample code | Curl
1
curl -v -u api.user@hogwarts.edu:test -X GET 'https://domain.freshservice.com/api/v2/department_fields'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{ "department_fields":[ { "created_at":"2019-04-02 09:31:52", "updated_at":"2019-04-02 10:30:46", "name":"name", "label":"Department Name", "mandatory":true, "is_default_field":true }, { "created_at":"2019-04-02 10:30:18", "updated_at":"2019-04-02 10:30:46", "name":"location", "label":"Location", "mandatory":false, "is_default_field":false }, { "created_at":"2019-04-02 09:31:52", "updated_at":"2019-04-02 10:30:46", "name":"description", "label":"Description", "mandatory":false, "is_default_field":true }, { "created_at":"2019-04-02 09:31:52", "updated_at":"2019-04-02 10:30:46", "name":"domain_names", "label":"Domains for this Department", "mandatory":false, "is_default_field":true }, { "created_at":"2019-04-02 09:31:52", "updated_at":"2019-04-02 10:30:46", "name":"head_name", "label":"Department Head", "mandatory":false, "is_default_field":true }, { "created_at":"2019-04-02 09:31:52", "updated_at":"2019-04-02 10:30:46", "name":"prime_user_name", "label":"Prime User", "mandatory":false, "is_default_field":true } ] }
EXPAND ↓

Business Hours

Attribute Type Description
id integer Unique identifier of the business hours configuration
name string Name of the business hours configuration
description string Description about the business hours configuration
is_default boolean true if the business hours configuration is the default present in Freshservice
time_zone string Time zone that the business hours configuration functions in. Click here for more information.
service_desk_hours hash Contains the time at which the workday begins and ends for the seven days of the week.
list_of_holidays array of hashes Contains the list of dates and names of holidays for the year. Dates are in ISO --MM-DD format.
created_at date-time Timestamp at which the business hours configuration was created
updated_at date-time Timestamp at which the business hours configuration was last modified

View a Business Hours Configuration

Retrieve the Business Hours Configuration with the given ID from Freshservice

get
/api/v2/business_hours/[id]
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/business_hours/1'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
{ "business_hours":{ "id": 1, "created_at": "2019-05-07T13:58:42Z", "updated_at": "2019-05-13T07:20:04Z", "name": "Default", "description": "Default Business Calendar", "is_default": true, "time_zone": "Chennai", "service_desk_hours": { "monday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" }, "tuesday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" }, "wednesday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" }, "thursday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" }, "friday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" } }, "list_of_holidays": [ { "holiday_date": "--01-01", "holiday_name": "New Year’s Day" }, { "holiday_date": "--01-16", "holiday_name": "Birthday of Martin Luther King Jr" }, { "holiday_date": "--02-20", "holiday_name": "Washington’s Birthday" }, { "holiday_date": "--05-28", "holiday_name": "Memorial Day" }, { "holiday_date": "--07-04", "holiday_name": "Independence Day" }, { "holiday_date": "--09-03", "holiday_name": "Labor Day" }, { "holiday_date": "--10-08", "holiday_name": "Columbus Day" }, { "holiday_date": "--11-11", "holiday_name": "Veterans Day" }, { "holiday_date": "--11-22", "holiday_name": "Thanksgiving Day" }, { "holiday_date": "--12-25", "holiday_name": "Christmas Day" } ] } }
EXPAND ↓

List All Business Hours Configurations

Retrieve a list of all Business Hours Configurations in Freshservice

get
/api/v2/business_hours
Sample code | Curl
1
curl -v -u user@yourcompany.com:test -X GET 'https://domain.freshservice.com/api/v2/business_hours'
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
{ "business_hours": [ { "id": 1, "created_at": "2019-05-07T13:58:42Z", "updated_at": "2019-05-13T07:20:04Z", "name": "Default", "description": "Default Business Calendar", "is_default": true, "time_zone": "Chennai", "service_desk_hours": { "monday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" }, "tuesday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" }, "wednesday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" }, "thursday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" }, "friday": { "beginning_of_workday": "08:00", "end_of_workday": "17:00" } }, "list_of_holidays": [ { "holiday_date": "--01-01", "holiday_name": "New Year’s Day" }, { "holiday_date": "--01-16", "holiday_name": "Birthday of Martin Luther King Jr" }, { "holiday_date": "--02-20", "holiday_name": "Washington’s Birthday" }, { "holiday_date": "--05-28", "holiday_name": "Memorial Day" }, { "holiday_date": "--07-04", "holiday_name": "Independence Day" }, { "holiday_date": "--09-03", "holiday_name": "Labor Day" }, { "holiday_date": "--10-08", "holiday_name": "Columbus Day" }, { "holiday_date": "--11-11", "holiday_name": "Veterans Day" }, { "holiday_date": "--11-22", "holiday_name": "Thanksgiving Day" }, { "holiday_date": "--12-25", "holiday_name": "Christmas Day" } ] }, { "id": 2, "created_at": "2019-05-09T11:31:45Z", "updated_at": "2019-05-13T07:04:49Z", "name": "Round-the-clock Support Team", "description": "24 x 7 Business Calendar", "is_default": false, "time_zone": "Chennai", "service_desk_hours": { "monday": { "beginning_of_workday": "00:00", "end_of_workday": "23:59" }, "tuesday": { "beginning_of_workday": "00:00", "end_of_workday": "23:59" }, "wednesday": { "beginning_of_workday": "00:00", "end_of_workday": "23:59" }, "thursday": { "beginning_of_workday": "00:00", "end_of_workday": "23:59" }, "friday": { "beginning_of_workday": "00:00", "end_of_workday": "23:59" }, "saturday": { "beginning_of_workday": "00:00", "end_of_workday": "23:59" }, "sunday": { "beginning_of_workday": "00:00", "end_of_workday": "23:59" } }, "list_of_holidays": [ { "holiday_date": "--01-01", "holiday_name": "New Year’s Day" }, { "holiday_date": "--12-25", "holiday_name": "Christmas Day" } ] } ] }
EXPAND ↓

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