API Reference

Overview

The freshservice API

Freshservice's APIs belong to the REpresentational State Transfer (REST) category. This allows you to perform "RESTful" operations like read, modify, add or delete data from your service desk.

What can I do with the freshservice API?

With the APIs, you can

Read
  1. Browse through tickets, users - their details and satisfaction ratings.
  2. Apply Filters and get only the data that you want
Write
  1. Create new tickets or users and modify the details of existing ones.
  2. Create solutions and answer FAQs.
Support
  1. Carry on conversations about a ticket using public or private notes.
  2. Assign tickets to the right people for the job.
  3. Collaborate with fellow agents via "Private Notes" in a ticket.
  4. Escalate unsolved problems.

API Endpoints and SSL

API endpoints are mapped to your account domain:

https://domain.freshservice.com/path/to/api.json

If you have disabled ssl under admin settings for your freshservice domain, your API calls must point to the normal endpoint—simply change the https:// part of the endpoint to http://.

http://domain.freshservice.com/path/to/api.json

For brevity, all further references in document relating to API endpoints will use the default https.

Authentication

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

"Thou shall not pass." Unless you authenticate your ID

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 "login" in the same way as you login into your helpdesk's web portal.

Freshservice uses Basic Access Authorization. This means, for authentication, you can use the same username and password you use when logging into your helpdesk. Or, you can use your personal API key provided by us. If you use the API Key, there is no need for any password. You can use any set of characters as a dummy password.

curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/helpdesk/tickets.json

curl -u apikey:X -H "Content-Type: application/json" -X GET https://domain.freshservice.com/helpdesk/tickets.json

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.

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

How do I access the information? What are the resources available via the API?

Every single piece of information or data - 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/resource_name

For example: If you are Davy Jones and you are managing the drowned souls and their problems via your freshservice portal "thelocker.freshservice.com", then to access contacts in your helpdesk, the syntax would be
https://www.thelocker.freshservice.com/itil/requesters.json
 For tickets, it would be
https://www.thelocker.freshservice.com/helpdesk/tickets.json

Note:
We have shortened API resource URL throughout this document. Prefix your support domain name to the resource handle.
Example:
/helpdesk/tickets is actually https://yourdomain.freshservice.com/helpdesk/tickets

What API commands are used by freshservice?

Freshservice APIs have been implemented as plain JSON over HTTP and use the following REST Commands:

Command Purpose
POST Create one or more items
GET Fetch one or more items
PUT Update one or more existing items
DELETE Remove one or more items that already exist

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.

Rate Limit

The number of API calls per hour is restricted to 1000. If your API request is received after the limit has been reached, freshservice will give you an error response. The "retry-after" value in the response header will tell you how long you need to wait before you send another API request.

Response
HTTP STATUS: HTTP 403 Forbidden
Headers:
"Retry-After": <seconds>

Please contact support@freshservice.com for further queries.

Ticket

This section lists all API that can be used to create, edit or otherwise manipulate tickets. If you wish to create Tags to better identify tickets, this section also lists the APIs for creating and manipulating those tags.

Attribute Type Description
display_id number Ticket ID specific to your account Read-Only
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 Mandatory
requester_id number User-id of the requester. For existing contacts, requester_id can be passed instead of email
assoc_problem_id number id of the associated problem to the ticket
assoc_change_id number id of the change initiating the ticket
assoc_change_cause_id number id of the change causing the ticket
assoc_asset_id number id of the asset associated to the ticket
subject string Ticket subject
description string Plain text content of the ticket
description_html string HTML content of the ticket. Description and description_html should not be passed together Mandatory
status * number Status of the ticket
priority * number Priority of the ticket
source * number The channel through which the ticket was created
deleted boolean Set as true if the ticket is deleted/trashed. Deleted tickets will not be considered in any views except "deleted" filter
spam boolean Set as true if the ticket is marked as spam
responder_id number ID of the agent to whom the ticket is assigned
group_id number Id of Group to which the ticket is assigned
ticket_type number Type property field as defined in ticket fields
to_email array of strings Email address to which the incoming ticket email was sent
cc_email array of strings Email address added in the 'cc' field of the incoming ticket email
email_config_id number Id of email config which is used for this ticket
(i.e., support@yourcompany.com/sales@yourcompany.com)
isescalated boolean Set to true if an escalation was sent
due_by datetime Ticket due-by time
id number unique ID of the ticket Read-Only
attachments array of objects Attached files of the ticket Read-Only
category string Ticket category
sub_category string Ticket sub category
item_category string Ticket item category
* Refer Ticket properties table for supported values.

Note/Conversations Attributes

Attribute Type Description
Id number Id of the note Read-Only
body string Content of the note in plain text
body_html string Content of the note in HTML format. Either body or body_html has to be passed Mandatory
attachments - Attachments associated with the note Read-Only
user_id number user_id of the agent who is adding the note
private boolean Set as true if the note is private
to_emails array of strings Array of agent email addresses, who need to be notified
deleted boolean Set to true if a particular note is deleted

Ticket Properties

With every ticket having certain fixed values to denote Source, State and Priorities, the numerical value for each state (open, closed, from email, from portal etc.) is given below

Source Type Value
Email 1
Portal 2
Phone 3
Chat 4
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.

post
/helpdesk/tickets.json
Request 
1
2
3
4
5
6
7
8
9
{
  "helpdesk_ticket":{
      "description":"Some details on the issue ...",
      "subject":"Support needed..",
      "email":"hulk@outerspace.com",
      "priority":1, "status":2, "source":2,"ticket_type":"Incident"
  },
  "cc_emails":"superman@marvel.com,avengers@marvel.com"
}
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
{
  "helpdesk_ticket":{
    "category":"Hardware",
    "cc_email":{
         "cc_emails":[],
         "fwd_emails":[],
         "reply_cc":[],
         "tkt_cc":[]
    },
    "created_at":"2014-03-05T17:23:43+05:30",
    "deleted":false,
    "delta":true,
    "description":"Some details on the issue ...",
    "description_html":"<div>Some details on the issue ...</div>",
    "display_id":24,
    "due_by":"2014-03-05T18:23:43+05:30",
    "email_config_id":null,
    "frDueBy":"2014-03-05T17:53:43+05:30",
    "fr_escalated":false,
    "group_id":null,
    "id":55,
    "isescalated":false,
    "item_category":"Mac",
    "notes":[],
    "owner_id":null,
    "priority":1,
    "requester_id":216,
    "responder_id":null,
    "source":2,
    "spam":false,
    "status":2,
    "sub_category":"Computer",
    "subject":"Support needed..",
    "ticket_type":"Incident",
    "to_email":null,
    "trained":false,
    "updated_at":"2014-03-05T17:23:43+05:30",
    "urgent":false,
    "status_name":"Open",
    "requester_status_name":"Being Processed",
    "priority_name":"Low",
    "source_name":"Portal",
    "requester_name":"hulk",
    "responder_name":"No Agent",
    "to_emails":null,
    "department_name":null,
    "assoc_change_id":"Getting ES3 back up to speed1",
    "assoc_problem_id":null,
    "assoc_change_cause_id":null,
    "custom_field":{},
    "attachments":[]
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "helpdesk_ticket": { "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/helpdesk/tickets.json
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 Ticket with attachment

This API helps you to create a new ticket in your help desk with attachments.

Note:
The API request must be sent as multipart/form-data content-type.

post
/helpdesk/tickets/[id].json
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
{  
   "helpdesk_ticket":{ 
      "category":"Hardware", 
      "cc_email":{
         "cc_emails":[],
         "fwd_emails":[],
         "reply_cc":[],
         "tkt_cc":[]
      },
      "created_at":"2014-07-28T16:20:03+05:30",
      "deleted":false,
      "delta":true,
      "description":"this is a sample ticket",
      "description_html":"\u003Cdiv\u003Ethis is a sample ticket\u003C/div\u003E",
      "display_id":111,
      "due_by":"2014-07-31T16:20:03+05:30",
      "email_config_id":null,
      "frDueBy":"2014-07-29T16:20:03+05:30",
      "fr_escalated":false,
      "group_id":null,
      "id":4007602889,
      "isescalated":false,
      "item_category":"Mac",
      "notes":[  

      ],
      "owner_id":null,
      "priority":1,
      "requester_id":8888589,
      "responder_id":null,
      "source":2,
      "spam":false,
      "status":2,
      "sub_category":"Computer",
      "subject":"Ticket Title",
      "ticket_type":null,
      "to_email":null,
      "trained":false,
      "updated_at":"2014-07-28T16:20:03+05:30",
      "urgent":false,
      "status_name":"Open",
      "requester_status_name":"Being Processed",
      "priority_name":"Low",
      "source_name":"Portal",
      "requester_name":"sathishbabu",
      "responder_name":"No Agent",
      "to_emails":null,
      "department_name": "Development",
      "assoc_problem_id": null,
      "assoc_change_id": null,
      "assoc_change_cause_id": null,
      "assoc_asset_id": null,
      "attachments":[  
         {  
            "content_content_type":"application/octet-stream",
            "content_file_name":"attachment1.jpg",
            "content_file_size":44115,
            "created_at":"2014-07-28T16:20:03+05:30",
            "id":4004881085,
            "updated_at":"2014-07-28T16:20:03+05:30",
            "attachment_url":"https://cdn.freshservice.com/data/helpdesk/attachments/production/4004881085/original/attachment.jpg"
         }
      ],
      "custom_field":{  
         "your_custom_field_1":null
      },
      "tags":[
         {"name": "tag1"},
         {"name": "tag2"}
      ]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -F "helpdesk_ticket[attachments][][resource]=@/path/to/attachment1.ext" -F "helpdesk_ticket[attachments][][resource]=@/path/to/attachment2.ext" -F "helpdesk_ticket[email]=example@example.com" -F "helpdesk_ticket[subject]=Ticket Title" -F "helpdesk_ticket[description]=this is a sample ticket" -X POST https://domain.freshservice.com/helpdesk/tickets.json
EXPAND ↓

View a Ticket

This API lets you retrieve and view a specific ticket and all conversations related to it in your service desk.

get
/helpdesk/tickets/[id].json
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
{
   "helpdesk_ticket":{
      "category":"Hardware",
      "cc_email":{
         "cc_emails":[],
         "fwd_emails":[],
         "reply_cc":[],
         "tkt_cc":[]
      },
      "created_at":"2014-03-05T17:23:43+05:30",
      "deleted":false,
      "delta":true,
      "description":"Some details on the issue ...",
      "description_html":"<div>Some details on the issue ...</div>",
      "display_id":24,
      "due_by":"2014-03-05T18:23:43+05:30",
      "email_config_id":null,
      "frDueBy":"2014-03-05T17:53:43+05:30",
      "fr_escalated":false,
      "group_id":null,
      "id":55,
      "isescalated":false,
      "item_category":"Mac",
      "notes":[],
      "owner_id":null,
      "priority":1,
      "requester_id":216,
      "responder_id":null,
      "source":2,
      "spam":false,
      "status":2,
      "sub_category":"Computer",
      "subject":"Support needed..",
      "ticket_type":"Incident",
      "to_email":null,
      "trained":false,
      "updated_at":"2014-03-05T17:23:43+05:30",
      "urgent":false,
      "status_name":"Open",
      "requester_status_name":"Being Processed",
      "priority_name":"Low",
      "source_name":"Portal",
      "requester_name":"hulk",
      "responder_name":"No Agent",
      "to_emails":null,
      "department_name":null,
      "assoc_change_id":"Getting ES3 back up to speed1",
      "assoc_problem_id":null,
      "assoc_change_cause_id":null,
      "custom_field":{},
      "attachments":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json"  -X GET https://domain.freshservice.com/helpdesk/tickets/1.json
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 ↓

View list of Tickets

This API helps you to view the tickets in your service desk.

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

Note:
All the below requests are paginated to return only 30 tickets per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

Filter by Handle
Default filters: /helpdesk/tickets/filter/[filter_name]?format=json
The various filters available are all_tickets, new_my_open, monitored_by, spam, deleted
Requester /helpdesk/tickets/filter/requester/[requester_id]?format=json
Custom ticket views /helpdesk/tickets/view/[view_id]?format=json
Requester email /helpdesk/tickets.json?email=[email]&filter_name=all_tickets
View All Tickets helpdesk/tickets.json
get
/helpdesk/tickets.json
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
[
   {
      "category":"Hardware",
      "cc_email":{
         "cc_emails":[],
         "fwd_emails":[],
         "reply_cc":[],
         "tkt_cc":[]
      },
      "created_at":"2014-03-05T17:23:43+05:30",
      "deleted":false,
      "delta":true,
      "description":"Some details on the issue ...",
      "description_html":"<div>Some details on the issue ...</div>",
      "display_id":24,
      "due_by":"2014-03-05T18:23:43+05:30",
      "email_config_id":null,
      "frDueBy":"2014-03-05T17:53:43+05:30",
      "fr_escalated":false,
      "group_id":null,
      "id":55,
      "isescalated":false,
      "item_category":"Mac",
      "notes":[],
      "owner_id":null,
      "priority":1,
      "requester_id":216,
      "responder_id":null,
      "source":2,
      "spam":false,
      "status":2,
      "sub_category":"Computer",
      "subject":"Support needed..",
      "ticket_type":"Incident",
      "to_email":null,
      "trained":false,
      "updated_at":"2014-03-05T17:23:43+05:30",
      "urgent":false,
      "status_name":"Open",
      "requester_status_name":"Being Processed",
      "priority_name":"Low",
      "source_name":"Portal",
      "requester_name":"hulk",
      "responder_name":"No Agent",
      "to_emails":null,
      "department_name":null,
      "assoc_change_id":"Getting ES3 back up to speed1",
      "assoc_problem_id":null,
      "assoc_change_cause_id":null,
      "custom_field":{},
      "attachments":[]
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json"  -X GET https://domain.freshservice.com/helpdesk/tickets/filter/all_tickets?format=json&page=1
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 ↓

Update a Ticket

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

put
/helpdesk/tickets/[id].json
Request 
1
2
3
4
5
6
7
8
9
{
   "helpdesk_ticket": { 
      "priority":1,
      "status":2,
      "custom_field":{
         "weapon_1":"Laser Gun"
      }
   }
}
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
{
   "helpdesk_ticket":{
      "category":"Hardware",
      "cc_email":{
         "cc_emails":[],
         "fwd_emails":[],
         "reply_cc":[],
         "tkt_cc":[]
      },
      "created_at":"2014-03-05T17:23:43+05:30",
      "deleted":false,
      "delta":true,
      "description":"Some details on the issue ...",
      "description_html":"<div>Some details on the issue ...</div>",
      "display_id":24,
      "due_by":"2014-03-05T18:23:43+05:30",
      "email_config_id":null,
      "frDueBy":"2014-03-05T17:53:43+05:30",
      "fr_escalated":false,
      "group_id":null,
      "id":55,
      "isescalated":false,
      "item_category":"Mac",
      "notes":[],
      "owner_id":null,
      "priority":1,
      "requester_id":216,
      "responder_id":null,
      "source":2,
      "spam":false,
      "status":2,
      "sub_category":"Computer",
      "subject":"Support needed..",
      "ticket_type":"Incident",
      "to_email":null,
      "trained":false,
      "updated_at":"2014-03-05T17:23:43+05:30",
      "urgent":false,
      "status_name":"resolved",
      "requester_status_name":"Being Processed",
      "priority_name":"medium",
      "source_name":"Portal",
      "requester_name":"hulk",
      "responder_name":"No Agent",
      "to_emails":null,
      "department_name":null,
      "assoc_change_id":"Getting ES3 back up to speed1",
      "assoc_problem_id":null,
      "assoc_change_cause_id":null,
      "custom_field":{
         "weapon_1":"Laser Gun"
      },
      "attachments":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "helpdesk_ticket": { "priority":1, "status":2 }}' https://domain.freshservice.com/helpdesk/tickets/1.json
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.

delete
/helpdesk/tickets/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json"  -X DELETE https://domain.freshservice.com/helpdesk/tickets/1.json
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 ↓

Get all Ticket Fields

This API lets you view the fields in a ticket.

get
/ticket_fields.json
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
[
    {
        "ticket_field": {
            "active": true,
            "created_at": "2013-12-11T18:11:30+05:30",
            "description": "Ticket requester",
            "editable_in_portal": true,
            "field_options": {
                "portalcc": false,
                "portalcc_to": "company"
            },
            "field_type": "default_requester",
            "flexifield_def_entry_id": null,
            "id": 1,
            "label": "Search a requester",
            "label_in_portal": "Requester",
            "name": "requester",
            "position": 1,
            "required": true,
            "required_for_closure": false,
            "required_in_portal": true,
            "updated_at": "2013-12-11T18:39:01+05:30",
            "visible_in_portal": true,
            "choices": [],
            "nested_ticket_fields": []
        }
    },
    {
        "ticket_field": {
            "active": true,
            "created_at": "2013-12-11T18:39:01+05:30",
            "description": "",
            "editable_in_portal": false,
            "field_options": null,
            "field_type": "custom_text",
            "flexifield_def_entry_id": 1,
            "id": 11,
            "label": "Weapon",
            "label_in_portal": "Weapon",
            "name": "weapon_1",
            "position":2,"required": false,
            "required_for_closure": false,
            "required_in_portal": false,
            "updated_at": "2014-01-30T16:20:01+05:30",
            "visible_in_portal": true,
            "choices": [],
            "nested_ticket_fields": []
        }
    }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/ticket_fields.json
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 ↓

Add note to a Ticket

If you wish to add notes to a ticket - private or public - this API lets you do so. Any note that you add using this API, by default, is Private. If you wish a public note, set the parameter to false.

post
/helpdesk/tickets/[:ticket_id]/conversations/note.json
Request 
1
2
3
4
5
6
{
  "helpdesk_note": {
    "body":"Hi tom, Still Angry",
    "private":false
  }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "note":{
      "body":"Hi tom, Still Angry",
      "body_html":"\u003Cdiv\u003EHi tom, Still Angry\u003C/div\u003E",
      "created_at":"2014-01-07T19:19:09+05:30",
      "deleted":false,
      "id":4,
      "incoming":false,
      "private":false,
      "source":2,
      "updated_at":"2014-01-07T19:19:09+05:30",
      "user_id":1,
      "attachments":[
      
      ]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "helpdesk_note": { "body":"Hi tom, Still Angry", "private":false }}' https://domain.freshservice.com/helpdesk/tickets/141/conversations/note.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
require 'rubygems'
require "rest_client"
require 'json'

#Specify your [ticket_id] in the below URL with your ticket id for which you wish to add note.
site = RestClient::Resource.new('https://domain.freshservice.com/helpdesk/tickets/[ticket_id]/conversations/note.json',"user@yourcompany.com","test")
# site = RestClient::Resource.new('https://mycompany.freshservice.com/helpdesk/tickets/91/conversations/note.json',"user@yourcompany.com","test")

#you can set private to false to make it a public note
#attachments should be of the form array of Hash with files mapped to the key 'resource'. 
temp = {:body_html=>"<strong>Hi there</strong>Notes with attachment added 1",:private=>true,:attachments=>{''=>[{:resource=>File.new("tommy.jpg", 'rb')},{:resource=>File.new("tommy1.jpg", 'rb')}]}}

response = site.post({:helpdesk_note=>temp},:content_type=>"application/json")


puts "#{response} ::: #{response.code}"
EXPAND ↓

Add note with attachment

Use this API to create notes with attachment.

Note:
The API request must be sent as multipart/form-data content-type.

post
/helpdesk/tickets/[:ticket_id]/conversations/note.json
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
{  
   "note":{  
      "body":"Note content",
      "body_html":"\u003Cdiv\u003ENote content\u003C/div\u003E",
      "created_at":"2014-07-28T16:18:46+05:30",
      "deleted":false,
      "id":4008899787,
      "incoming":false,
      "private":true,
      "source":2,
      "updated_at":"2014-07-28T16:18:46+05:30",
      "user_id":8888589,
      "attachments":[  
         {  
            "content_content_type":"application/octet-stream",
            "content_file_name":"attachment1.ext",
            "content_file_size":44115,
            "created_at":"2014-07-28T16:18:46+05:30",
            "id":4004881013,
            "updated_at":"2014-07-28T16:18:46+05:30",
            "attachment_url":"https://cdn.freshservice.com/data/helpdesk/attachments/production/4004881013/original/attachment1.ext"
         }
      ]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -F "helpdesk_note[attachments][][resource]=@/path/to/attachment1.ext"  -F "helpdesk_note[body]=Note content" -F "helpdesk_note[private]=false" -X POST https://domain.freshservice.com/helpdesk/tickets/[id]/conversations/note.json
EXPAND ↓

Associate a CI/Asset to a Ticket

This API helps you associate an asset to a ticket in your service desk.

post
/helpdesk/tickets.json
Request 
1
2
3
4
5
6
7
8
9
10
{
  "helpdesk_ticket":{
      "description":"Some details on the issue ...",
      "subject":"Support needed..",
      "email":"hulk@outerspace.com",
      "priority":1, "status":2, "source":2,"ticket_type":"Incident"
  },
  "associate_ci":{"serial_no":"ABC12345","name":"my printer","user":"rachel@freshdesk.com"},
  "cc_emails":"superman@marvel.com,avengers@marvel.com"
}
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
{
  "helpdesk_ticket":{
    "category":"Hardware",
    "cc_email":{
         "cc_emails":[],
         "fwd_emails":[],
         "reply_cc":[],
         "tkt_cc":[]
    },
    "created_at":"2014-03-05T17:23:43+05:30",
    "deleted":false,
    "delta":true,
    "description":"Some details on the issue ...",
    "description_html":"<div>Some details on the issue ...</div>",
    "display_id":24,
    "due_by":"2014-03-05T18:23:43+05:30",
    "email_config_id":null,
    "frDueBy":"2014-03-05T17:53:43+05:30",
    "fr_escalated":false,
    "group_id":null,
    "id":55,
    "isescalated":false,
    "item_category":"Mac",
    "notes":[],
    "owner_id":null,
    "priority":1,
    "requester_id":216,
    "responder_id":null,
    "source":2,
    "spam":false,
    "status":2,
    "sub_category":"Computer",
    "subject":"Support needed..",
    "ticket_type":"Incident",
    "to_email":null,
    "trained":false,
    "updated_at":"2014-03-05T17:23:43+05:30",
    "urgent":false,
    "status_name":"Open",
    "requester_status_name":"Being Processed",
    "priority_name":"Low",
    "source_name":"Portal",
    "requester_name":"hulk",
    "responder_name":"No Agent",
    "to_emails":null,
    "department_name":null,
    "assoc_change_id":"Getting ES3 back up to speed1",
    "assoc_problem_id":null,
    "assoc_change_cause_id":null,
    "assoc_asset_id":"1",
    "custom_field":{},
    "attachments":[]
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "helpdesk_ticket": { "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2 }, "associate_ci":{"serial_no":"ABC12345","name":"my printer","user":"rachel@freshdesk.com"}  }' -X POST https://domain.freshservice.com/helpdesk/tickets.json
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 ↓

Problem

This section lists all API that can be used to create, edit or otherwise manipulate problems. You can also create filters to sift through problems.

Attribute Type Description
display_id number Problem ID specific to your account Read-Only
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 Mandatory
requester_id number User-id of the requester. For existing contacts, requester_id can be passed instead of email
assoc_change_id number id of the associated change to the problem
subject string Problem subject
description string Plain text content of the problem
description_html string HTML content of the problem. Description and description_html should not be passed together Mandatory
status * number Status of the problem
priority * number Priority of the problem
impact * number Impact of the problem
deleted boolean Set as true if the problem is deleted/trashed. Deleted problems will not be considered in any views except "deleted" filter
owner_id number Id of the agent to whom the problem is assigned
group_id number Id of Group to which the problem is assigned
due_by datetime Problem due-by time
id number unique ID of the problem Read-Only
attachments array of objects Attached files of the problem Read-Only
category string Problem category
sub_category string Problem sub category
item_category string Problem item category
* Refer Problem properties table for supported values.

Note/Conversations Attributes

Attribute Type Description
Id number Id of the note Read-Only
body string Content of the note in plain text
body_html string Content of the note in HTML format. Either body or body_html has to be passed Mandatory
attachments - Attachments associated with the note Read-Only
user_id number user_id of the agent who is adding the note
to_emails array of strings Array of agent email addresses, who need to be notified
deleted boolean Set to true if a particular note is deleted

Problem Properties

With every problem having certain fixed values to denote Source, State and Priorities, the numerical value for each state (open, closed etc.) is given below

Priority Value
Low 1
Medium 2
High 3
Urgent 4
Status Value
Open 1
Pending 2
Resolved 3
Closed 4
Impact Value
Low 1
Medium 2
High 3

Create a Problem

This API helps you to create a new problem in your service desk.

post
/itil/problems.json
Request 
1
2
3
4
5
6
7
8
9
10
{
  "itil_problem":{
    "subject":"change needed..",
    "email":"hulk@outerspace.com",
    "priority":1, "status":1, "impact":1,
    "custom_field_attributes":{
      "problem_range_1":"serious"
    }
  }
}
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
{
    "itil_problem": {
        "category": null,
        "created_at": "2018-08-27T11:40:26+05:30",
        "deleted": false,
        "department_id": null,
        "display_id": 4,
        "due_by": "2018-08-29T11:40:26+05:30",
        "email_config_id": null,
        "group_id": null,
        "id": 4,
        "impact": 1,
        "import_id": null,
        "item_category": null,
        "known_error": false,
        "owner_id": null,
        "priority": 1,
        "requester_id": 12,
        "status": 1,
        "sub_category": null,
        "subject": "Support Needed...",
        "updated_at": "2018-08-27T11:40:26+05:30",
        "wf_event_id": null,
        "status_name": "Open",
        "impact_name": "Low",
        "priority_name": "Low",
        "requester_name": "Hulk",
        "owner_name": null,
        "group_name": null,
        "description": "Not given.",
        "assoc_change_id": null,
        "associated_assets": [
          1
        ],
        "attachments": [],
        "notes": [],
        "custom_field_values": {}
    }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "itil_problem": { "subject": "Support Needed...", "email": "hulk@outerspace.com", "priority": 1, "status": 1,"impact":1,"custom_field_attributes":{"problem_range_1":"serious"},"cmdb_requests_attributes":{"item_ids":"1"} }}' -X POST https://domain.freshservice.com/itil/problems.json
EXPAND ↓

View a Problem

This API lets you retrieve and view a specific problem and all conversations related to it in your service desk.

get
/itil/problems/[id].json
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
{
   "itil_problem":{
      "category":"Hardware",
      "change_id":null,
      "created_at":"2014-05-26T00:06:17+05:30",
      "deleted":false,
      "department_id":null,
      "display_id":17,
      "due_by":"2014-05-27T23:54:00+05:30",
      "email_config_id":null,
      "group_id":null,
      "id":18,
      "impact":1,
      "item_category":"Mac",
      "known_error":false,
      "notes":[],
      "owner_id":null,
      "priority":1,
      "requester_id":214,
      "status":1,
      "sub_category":"Computer",
      "subject":"change needed..",
      "updated_at":"2014-05-26T00:06:17+05:30",
      "status_name":"Open",
      "impact_name":"Low",
      "priority_name":"Low",
      "requester_name":"hulk",
      "owner_name":null,
      "group_name":null,
      "assoc_change_id":null,
      "associated_assets":[],
      "custom_field_values":{
         "problem_range_1":"serious"
      },
      "attachments":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/problems/17.json
EXPAND ↓

View list of Problems

This API helps you to view all the problems in your service desk.

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

Note:
All the below requests are paginated to return only 30 problems per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

Filter by Handle
Default filters: /itil/problems/filter/[filter_name]?format=json
The various filters available are all,new_my_open and deleted
get
/itil/problems.json
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
[
   {
      "category":"Hardware",
      "change_id":null,
      "created_at":"2014-05-26T00:06:17+05:30",
      "deleted":false,
      "department_id":null,
      "display_id":17,
      "due_by":"2014-05-27T23:54:00+05:30",
      "email_config_id":null,      
      "group_id":null,
      "id":18,
      "impact":1,
      "item_category":"Mac",
      "known_error":false,
      "notes":[],
      "owner_id":null,
      "priority":1,
      "requester_id":214,
      "status":1,
      "sub_category":"Computer",
      "subject":"change needed..",
      "updated_at":"2014-05-26T00:06:17+05:30",
      "status_name":"Open",
      "impact_name":"Low",
      "priority_name":"Low",
      "requester_name":"hulk",
      "owner_name":null,
      "group_name":null,
      "assoc_change_id":null,
      "associated_assets":[],
      "custom_field_values":{
         "problem_range_1":"serious"
      },
      "attachments":[]
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/problem/filter/all?format=json&page=1
EXPAND ↓

Update a Problem

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

put
/itil/problems/[id].json
Request 
1
2
3
4
5
6
7
8
9
10
{ 
   "itil_problem": {
      "priority":4,
      "status":3,
      "impact":3,
      "custom_field_attributes":{
         "problem_range_1":"serious"
      }
   }
}
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
{
   "itil_problem":{
      "category":"Hardware",
      "change_id":null,
      "created_at":"2014-05-26T00:06:17+05:30",
      "deleted":false,
      "department_id":null,      
      "display_id":17,
      "due_by":"2014-05-27T23:54:00+05:30",
      "email_config_id":null,      
      "group_id":null,
      "id":18,
      "impact":3,
      "item_category":"Mac",
      "known_error":false,
      "notes":[],
      "owner_id":null,
      "priority":4,
      "requester_id":214,
      "status":3,
      "sub_category":"Computer",
      "subject":"change needed..",
      "updated_at":"2014-05-26T00:06:17+05:30",
      "status_name":"Closed",
      "impact_name":"High",
      "priority_name":"Urgent",
      "requester_name":"hulk",
      "owner_name":null,
      "group_name":null,
      "assoc_change_id":null,
      "custom_field_values":{
         "problem_range_1":"serious"
      },
      "attachments":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "itil_problem": { "priority":4, "status":3, "impact":3,"custom_field_attributes":{"problem_range_1":"serious"} }}' https://domain.freshservice.com/itil/problems/17.json
EXPAND ↓

Delete a Problem

This API helps you delete a problem.

delete
/itil/problems/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/itil/problems/17.json
EXPAND ↓

Get all Problem Fields

This API lets you view the fields in a problem.

get
itil/problem_fields.json
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
{
    "itil_problem_fields":[
        {
            "account_id":1,
            "active":true,
            "column_name":null,
            "created_at":"2014-02-19T09:39:45Z",
            "deleted":false,
            "description":"Problem requester",
            "field_options":null,
            "field_type":"default_requester",
            "id":20,
            "label":"Requester",
            "name":"requester",
            "position":1,
            "required":true,
            "required_for_closure":false,
            "updated_at":"2014-03-24T14:08:36Z"
        },
        {
            "account_id":1,
            "active":true,
            "column_name":null,
            "created_at":"2014-02-19T09:39:46Z",
            "deleted":false,
            "description":"Problem title",
            "field_options":null,
            "field_type":"default_subject",
            "id":21,
            "label":"Subject",
            "name":"subject",
            "position":2,
            "required":true,
            "required_for_closure":false,
            "updated_at":"2014-03-24T14:08:36Z"
        }
    ] 
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/problem_fields.json
EXPAND ↓

Add note to a Problem

If you wish to add notes to a problem

post
/itil/problems/[:problem_id]/notes.json
Request 
1
2
3
4
5
{
  "itil_note": {
    "body":"Hi Hulk, Still Angry"
  }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "note":{
    "account_id":1,
    "body":"Hi Hulk, Still Angry",
    "body_html":"<div>Hi Hulk, Still Angry</div>",
    "cc_emails":null,
    "created_at":"2014-05-06T17:26:58+05:30",
    "deleted":false,
    "header_info":null,
    "id":24,
    "notable_id":5,
    "notable_type":"Itil::Problem",
    "to_emails":null,
    "updated_at":"2014-05-06T17:26:58+05:30",
    "user_id":1
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "itil_note": { "body":"Hi Hulk, Still Angry"}}' https://domain.freshservice.com/itil/problems/17/notes.json
EXPAND ↓

Detach Asset from a Problem

This API lets you to detach the associated assets from a problem

put
/itil/problems/[id]/detach_ci.json
Request 
1
2
3
4
5
{ 
  "itil_problem": { 
    "asset_ids": [1, 2] 
  } 
}
EXPAND ↓
Response 
1
{ "success": true }
EXPAND ↓
Sample code | Curl 
1
curl -u  user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "itil_problem": {"asset_ids": [1, 2] }}' -X PUT https://domain.freshservice.com/itil/problems/1/detach_ci.json
EXPAND ↓

Change

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
display_id number Change ID specific to your account Read-Only
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 Mandatory
requester_id number User-id of the requester. For existing contacts, requester_id can be passed instead of email
assoc_release_id number id of the associated change to the change
subject string change subject
description string Plain text content of the change
description_html string HTML content of the change. Description and description_html should not be passed together Mandatory
status * number Status of the change
priority * number Priority of the change
impact * number Impact 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 datetime Planned Start date
planned_end_date datetime Planned End date
deleted boolean Set as true if the change is deleted/trashed. Deleted changes will not be considered in any views except "deleted" filter
owner_id number Id of the agent to whom the change is assigned
group_id number Id of Group to which the change is assigned
id number unique ID of the change Read-Only
attachments array of objects Attached files of the change Read-Only
category string Change category
sub_category string Change sub category
item_category string Change item category
* Refer change properties table for supported values.

Note/Conversations Attributes

Attribute Type Description
Id number Id of the note Read-Only
body string Content of the note in plain text
body_html string Content of the note in HTML format. Either body or body_html has to be passed Mandatory
attachments - Attachments associated with the note Read-Only
user_id number user_id of the agent who is adding the note
to_emails array of strings Array of agent email addresses, who need to be notified
deleted boolean Set to true if a particular note is deleted

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

This API helps you to create a new change in your service desk.

post
/itil/changes.json
Request 
1
2
3
4
5
6
7
8
9
10
{
    "itil_change":{
        "subject":"change for support",
        "email":"hulk@outerspace.com",
        "priority":1, "status":1,"change_type":1,"impact":1,"risk":1,
        "custom_field_attributes":{
            "change_range_1":"normal"
        }
    }
}
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
{
    "itil_change": {
        "approval_status": 4,
        "approval_type": null,
        "category": null,
        "cc_email": {},
        "change_type": 1,
        "created_at": "2018-08-27T11:38:54+05:30",
        "deleted": false,
        "department_id": null,
        "display_id": 10,
        "email_config_id": null,
        "group_id": null,
        "id": 11,
        "impact": 1,
        "import_id": null,
        "item_category": null,
        "owner_id": null,
        "planned_end_date": null,
        "planned_start_date": null,
        "priority": 1,
        "project_id": null,
        "requester_id": 12,
        "risk": 1,
        "state_flow_id": null,
        "state_traversal": [
          1
        ],
        "status": 1,
        "sub_category": null,
        "subject": "change for support",
        "updated_at": "2018-08-27T11:38:54+05:30",
        "wf_event_id": null,
        "status_name": "Open",
        "impact_name": "Low",
        "priority_name": "Low",
        "requester_name": "Hulk",
        "owner_name": null,
        "group_name": null,
        "risk_type": "Low",
        "change_type_name": "Minor",
        "approval_status_name": "Not Requested",
        "description": "Not given.",
        "assoc_release_id": null,
        "associated_assets": [
          1
        ],
        "attachments": [],
        "notes": [],
        "custom_field_values": {}
    }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "itil_change": { "subject": "change for support", "email": "hulk@outerspace.com", "priority":1,"status":1,"risk":1,"impact":1,"change_type":1,"custom_field_attributes":{"change_range_1":"normal"},"cmdb_requests_attributes":{"item_ids":"1"}}}' -X POST https://domain.freshservice.com/itil/changes.json
EXPAND ↓

View a Change

This API lets you retrieve and view a specific change and all conversations related to it in your service desk.

get
/itil/changes/[id].json
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
{
   "itil_change":{
      "category":"Hardware",
      "approval_status":null,
      "change_type":1,
      "created_at":"2014-04-29T15:52:35+05:30",
      "deleted":false,
      "department_id":null,      
      "display_id":3,
      "email_config_id":null,
      "group_id":null,
      "id":8,
      "impact":1,
      "item_category":"Mac",
      "notes":[],
      "owner_id":null,
      "planned_end_date":"null",
      "planned_start_date":"null",
      "priority":1,
      "release_id":null,
      "requester_id":1,
      "risk":1,
      "status":1,
      "sub_category":"Computer",
      "subject":"change for support",
      "updated_at":"2014-04-29T15:52:35+05:30",
      "status_name":"Open",
      "impact_name":"Low",
      "priority_name":"Low",
      "requester_name":"Support",
      "owner_name":null,
      "group_name":null,
      "risk_type":"Low",
      "change_type_name":"Minor",
      "approval_status_name":"Not Requested",
      "assoc_release_id":null,
      "associated_assets":[],
      "custom_field_values":{
         "change_range_1":"normal"
      },
      "attachments":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/changes/3.json
EXPAND ↓

View list of Changes

This API helps you to view all the changes in your service desk.

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

Note:
All the below requests are paginated to return only 30 changes per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

Filter by Handle
Default filters: /itil/changes/filter/[filter_name]?format=json
The various filters available are all,new_my_open and deleted
get
/itil/changes.json
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
[
   {
      "category":"Hardware",
      "approval_status":null,
      "change_type":1,
      "created_at":"2014-04-29T15:52:35+05:30",
      "deleted":false,
      "department_id":null,
      "display_id":3,
      "email_config_id":null,
      "group_id":null,
      "id":8,
      "impact":1,
      "item_category":"Mac",
      "notes":[],
      "owner_id":null,
      "planned_end_date":"null",
      "planned_start_date":"null",
      "priority":1,
      "release_id":null,
      "requester_id":1,
      "risk":1,
      "status":1,
      "sub_category":"Computer",
      "subject":"change for support",
      "updated_at":"2014-04-29T15:52:35+05:30",
      "status_name":"Open",
      "impact_name":"Low",
      "priority_name":"Low",
      "requester_name":"Support",
      "owner_name":null,
      "group_name":null,
      "risk_type":"Low",
      "change_type_name":"Minor",
      "approval_status_name":"Not Requested",
      "assoc_release_id":null,
      "associated_assets":[],
      "custom_field_values":{
         "change_range_1":"normal"
      },
      "attachments":[]
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/changes/filter/all?format=json&page=1
EXPAND ↓

Update a Change

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

put
/itil/changes/[id].json
Request 
1
2
3
4
5
6
7
8
9
10
{
   "itil_change":{
      "priority":2,
      "status":2,
      "impact":2,
      "custom_field_attributes":{
         "change_range_1":"normal"
      }
   }
}
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
{
   "itil_change":{
      "category":"Hardware",
      "approval_status":null,
      "change_type":1,
      "created_at":"2014-04-29T15:52:35+05:30",
      "deleted":false,
      "department_id":null,      
      "display_id":3,
      "email_config_id":null,      
      "group_id":null,
      "id":8,
      "impact":1,
      "item_category":"Mac",
      "notes":[],
      "owner_id":null,
      "planned_end_date":"null",
      "planned_start_date":"null",
      "priority":1,
      "release_id":null,
      "requester_id":1,
      "risk":1,
      "status":1,
      "sub_category":"Computer",
      "subject":"change for support",
      "updated_at":"2014-04-29T15:52:35+05:30",
      "status_name":"Planning",
      "impact_name":"Medium",
      "priority_name":"Mediun",
      "requester_name":"Support",
      "owner_name":null,
      "group_name":null,
      "risk_type":"Low",
      "change_type_name":"Minor",
      "approval_status_name":"Not Requested",
      "assoc_release_id":null,
      "custom_field_values":{
         "change_range_1":"normal"
      },
      "attachments":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "itil_change":{"priority":2,"status":2,"impact":2,"custom_field_attributes":{"change_range_1":"normal"} }}'https://domain.freshservice.com/itil/changes/3.json
EXPAND ↓

Delete a Change

This API helps you delete a change.

delete
/itil/changes/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/itil/changes/3.json
EXPAND ↓

Get all Change Fields

This API lets you view the fields in a change.

get
itil/change_fields.json
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
{
    "itil_change_fields":[
        {
            "account_id":1,
            "active":true,
            "column_name":null,
            "created_at":"2014-02-19T09:39:42Z",
            "deleted":false,
            "description":"Change requester",
            "field_options":null,
            "field_type":"default_requester",
            "id":1,
            "label":"Requester",
            "name":"requester",
            "position":1,
            "required":true,
            "required_for_closure":false,
            "updated_at":"2014-03-24T14:09:24Z"
        },
        {
            "account_id":1,
            "active":true,
            "column_name":null,
            "created_at":"2014-02-19T09:39:42Z",
            "deleted":false,
            "description":"Change title",
            "field_options":null,
            "field_type":"default_subject",
            "id":2,
            "label":"Subject",
            "name":"subject",
            "position":2,
            "required":true,
            "required_for_closure":false,
            "updated_at":"2014-03-24T14:09:24Z"
        }
    ]
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/change_fields.json
EXPAND ↓

Add note to a Change

If you wish to add notes to a change

post
/itil/changes/[:change_id]/notes.json
Request 
1
2
3
4
5
{
  "itil_note": {
    "body":"Hi Hulk, Still Angry"
  }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "note":{
    "account_id":1,
    "body":"Hi Hulk, Still Angry",
    "body_html":"<div>Hi Hulk, Still Angry</div>",
    "cc_emails":null,
    "created_at":"2014-05-06T17:26:58+05:30",
    "deleted":false,
    "header_info":null,
    "id":24,
    "notable_id":5,
    "notable_type":"Itil::Change",
    "to_emails":null,
    "updated_at":"2014-05-06T17:26:58+05:30",
    "user_id":1
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "itil_note": { "body":"Hi Hulk, Still Angry"}}' https://domain.freshservice.com/itil/changes/17/notes.json
EXPAND ↓

Detach Asset from a Change

This API lets you to detach the associated assets from a change

put
/itil/changes/[id]/detach_ci.json
Request 
1
2
3
4
5
{ 
  "itil_change": { 
    "asset_ids": [1, 2] 
  } 
}
EXPAND ↓
Response 
1
{ "success": true }
EXPAND ↓
Sample code | Curl 
1
curl -u  user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "itil_change": {"asset_ids": [1, 2] }}' -X PUT https://domain.freshservice.com/itil/changes/1/detach_ci.json
EXPAND ↓

Release

This section lists all API that can be used to create, edit or otherwise manipulate releases. You can create filters to sift through releases.

Attribute Type Description
display_id number Release ID specific to your account Read-Only
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 Mandatory
requester_id number User-id of the requester. For existing contacts, requester_id can be passed instead of email
subject string Release subject
description string Plain text content of the release
description_html string HTML content of the release. Description and description_html should not be passed together Mandatory
status * number Status of the release
priority * number Priority of the release
release_type * number Type of the release
approval_status number Approval status of the release
planned_start_date datetime Planned start date
planned_end_date datetime Planned end date
work_start_date datetime actual start date
work_end_date datetime actual end date
deleted boolean Set as true if the release is deleted/trashed. Deleted releases will not be considered in any views except "deleted" filter
owner_id number Id of the agent to whom the release is assigned
group_id number Id of Group to which the release is assigned
id number unique ID of the release Read-Only
attachments array of objects Attached files of the release Read-Only
category string Release category
sub_category string Release sub category
item_category string Release item category
* Refer release properties table for supported values.

Note/Conversations Attributes

Attribute Type Description
Id number Id of the note Read-Only
body string Content of the note in plain text
body_html string Content of the note in HTML format. Either body or body_html has to be passed Mandatory
attachments - Attachments associated with the note Read-Only
user_id number user_id of the agent who is adding the note
to_emails array of strings Array of agent email addresses, who need to be notified
deleted boolean Set to true if a particular note is deleted

Release Properties

With every release having certain fixed values to denote Source, State and release type, the numerical value for each state (open, closed etc.) is given below

Status Value
Open 2
Onhold 3
Inprogress 4
Incomplete 5
completed 6
Priority Value
Low 1
Medium 2
High 3
Urgent 4
Release Type Value
Minor 1
Standard 2
Major 3
Emergency 4

Create a Release

This API helps you to create a new release in your service desk.

post
/itil/releases.json
Request 
1
2
3
4
5
6
7
8
9
10
{
    "itil_release":{
        "subject":"release for support",
        "priority":1, "status":2,"release_type":1
        "custom_field_attributes":{
            "release_range_1":"normal"
        },
        "cc_emails":"superman@marvel.com,avengers@marvel.com"
    }
}
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
{
    "itil_release": {
        "approval_status": null,
        "category": null,
        "created_at": "2018-08-27T11:33:43+05:30",
        "deleted": false,
        "department_id": null,
        "display_id": 6,
        "email_config_id": null,
        "group_id": null,
        "id": 6,
        "import_id": null,
        "item_category": null,
        "owner_id": null,
        "planned_end_date": null,
        "planned_start_date": null,
        "priority": 1,
        "release_type": 1,
        "requester_id": 1,
        "status": 2,
        "sub_category": null,
        "subject": "Release for support.",
        "updated_at": "2018-08-27T11:33:43+05:30",
        "wf_event_id": null,
        "work_end_date": null,
        "work_start_date": null,
        "status_name": "On Hold",
        "priority_name": "Low",
        "requester_name": "Support",
        "owner_name": null,
        "group_name": null,
        "rel_type_name": "Minor",
        "description": "Not given.",
        "associated_assets": [
          1
        ],
        "attachments": [],
        "notes": [],
        "custom_field_values": {}
    }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "itil_release": { "subject": "Release for support.", "email": "hulk@outerspace.com", "priority": 1, "status": 2,"release_type":1,"custom_field_attributes":{"release_range_1":"normal"},"cmdb_requests_attributes":{"item_ids":"1"} }}' -X POST https://domain.freshservice.com/itil/releases.json
EXPAND ↓

View a Release

This API lets you retrieve and view a specific release and all conversations related to it in your service desk.

get
/itil/releases/[id].json
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
{
      "itil_release":{
            "category":"Hardware",
            "approval_status":null,
            "created_at":"2014-05-22T11:53:46+05:30",
            "deleted":false,
            "department_id":null,            
            "display_id":11,
            "email_config_id":null,
            "group_id":null,
            "id":12,
            "item_category":"Mac",
            "notes":[],
            "owner_id":null,
            "planned_end_date":"2014-05-22T11:53:45+05:30",
            "planned_start_date":"2014-05-22T11:53:45+05:30",
            "priority":1,
            "release_type":1,
            "requester_id":1,
            "status":2,
            "sub_category":"Computer",
            "subject":"release for support1",
            "updated_at":"2014-05-22T11:53:46+05:30",
            "work_end_date":"2014-05-22T11:53:45+05:30",
            "work_start_date":"2014-05-22T11:53:45+05:30",
            "status_name":"On Hold",
            "priority_name":"Low",
            "requester_name":"Support",
            "owner_name":null,
            "group_name":null,
            "rel_type_name":"minor",
            "associated_assets":[],
            "custom_field_values":{
                  "release_range_1":"normal"
            },
            "attachments":[]
      }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/releases/11.json
EXPAND ↓

View list of Releases

This API helps you to view all the releases in your service desk.

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

Note:
All the below requests are paginated to return only 30 releases per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

Filter by Handle
Default filters: /itil/releases/filter/[filter_name]?format=json
The various filters available are all,new_my_open and deleted
get
/itil/releases.json
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
[
   {
      "category":"Hardware",
      "approval_status":null,
      "created_at":"2014-05-22T11:53:46+05:30",
      "deleted":false,
      "department_id":null,
      "display_id":11,
      "email_config_id":null,
      "group_id":null,
      "id":12,
      "item_category":"Mac",
      "notes":[],
      "owner_id":null,
      "planned_end_date":"2014-05-22T11:53:45+05:30",
      "planned_start_date":"2014-05-22T11:53:45+05:30",
      "priority":1,
      "release_type":1,
      "requester_id":1,
      "status":2,
      "sub_category":"Computer",
      "subject":"release for support1",
      "updated_at":"2014-05-22T11:53:46+05:30",
      "work_end_date":"2014-05-22T11:53:45+05:30",
      "work_start_date":"2014-05-22T11:53:45+05:30",
      "status_name":"On Hold",
      "priority_name":"Low",
      "requester_name":"Support",
      "owner_name":null,
      "group_name":null,
      "rel_type_name":"minor",
      "associated_assets":[],
      "custom_field_values":{
         "release_range_1":"normal"
      },
      "attachments":[]
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/releases/filter/all?format=json&page=1
EXPAND ↓

Update a Release

This API lets you make changes to the parameters of a releses from updating statuses to changing release priority.

put
/itil/releases/[id].json
Request 
1
2
3
4
5
6
{
  "itil_release": { 
     "priority":2,
     "status":3
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
   "itil_release":{
      "category":"Hardware",
      "approval_status":null,
      "created_at":"2014-05-22T11:53:46+05:30",
      "deleted":false,
      "department_id":null,
      "display_id":11,
      "email_config_id":null,
      "group_id":null,
      "id":12,
      "item_category":"Mac",
      "notes":[],
      "owner_id":null,
      "planned_end_date":"2014-05-22T11:53:45+05:30",
      "planned_start_date":"2014-05-22T11:53:45+05:30",
      "priority":2,
      "release_type":1,
      "requester_id":1,
      "status":3,
      "sub_category":"Computer",
      "subject":"release for support1",
      "updated_at":"2014-05-22T11:53:46+05:30",
      "work_end_date":"2014-05-22T11:53:45+05:30",
      "work_start_date":"2014-05-22T11:53:45+05:30",
      "status_name":"In Progress",
      "priority_name":"Medium",
      "requester_name":"Support",
      "owner_name":null,
      "group_name":null,
      "rel_type_name":"minor",
      "custom_field_values":{},
      "attachments":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "itil_release": { "priority":2, "status":3 }}' https://domain.freshservice.com/itil/releases/11.json
EXPAND ↓

Delete a Release

This API helps you delete a release.

delete
/itil/releases/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/itil/releases/11.json
EXPAND ↓

Get all Release Fields

This API lets you view the fields in a release.

get
itil/release_fields.json
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
{
    "itil_release_fields":[
        {
            "account_id":1,
            "active":true,
            "column_name":null,
            "created_at":"2014-02-19T09:39:45Z",
            "deleted":false,
            "description":"Release subject",
            "field_options":null,
            "field_type":"default_subject",
            "id":11,
            "label":"Subject",
            "name":"subject",
            "position":1,
            "required":true,
            "required_for_closure":false,
            "updated_at":"2014-03-24T14:09:52Z"
        },
        {
            "account_id":1,
            "active":true,
            "column_name":null,
            "created_at":"2014-02-19T09:39:45Z",
            "deleted":false,
            "description":"Release description",
            "field_options":null,
            "field_type":"default_description",
            "id":12,
            "label":"Description",
            "name":"description",
            "position":2,
            "required":true,
            "required_for_closure":false,
            "updated_at":"2014-03-24T14:09:52Z"
        }
    ]
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/release_fields.json
EXPAND ↓

Add note to a Release

If you wish to add notes to a release

post
/itil/releases/[:release_id]/notes.json
Request 
1
2
3
4
5
{
  "itil_note": {
    "body":"Hi Hulk, Still Angry"
  }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "note":{
    "account_id":1,
    "body":"Hi Hulk, Still Angry",
    "body_html":"<div>Hi Hulk, Still Angry</div>",
    "cc_emails":null,
    "created_at":"2014-05-06T17:26:58+05:30",
    "deleted":false,
    "header_info":null,
    "id":24,
    "notable_id":5,
    "notable_type":"Itil::Release",
    "to_emails":null,
    "updated_at":"2014-05-06T17:26:58+05:30",
    "user_id":1
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "itil_note": { "body":"Hi Hulk, Still Angry"}}' https://domain.freshservice.com/itil/releases/17/notes.json
EXPAND ↓

Detach Asset from a Release

This API lets you to detach the associated assets from a release

put
/itil/releases/[id]/detach_ci.json
Request 
1
2
3
4
5
{ 
  "itil_release": { 
    "asset_ids": [1, 2] 
  } 
}
EXPAND ↓
Response 
1
{ "success": true }
EXPAND ↓
Sample code | Curl 
1
curl -u  user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "itil_release": {"asset_ids": [1, 2] }}' -X PUT https://domain.freshservice.com/itil/releases/1/detach_ci.json
EXPAND ↓

Time Entries

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

* - You can use any of the modules here - incident, problem, change or release.

Attribute Type Description
id number Id of the time entry Read-Only
executed_at datetime Time at which this time-entry id added/created
billable boolean Set as true if the entry is billable
note string Description on this time-entry
start_time datetime The time at which the time-entry is added or the time of the last invoked "start-timer" action using a toggle
timer_running boolean Set to true if the start-timer is invoked and is currently running.
hhmm string The number of hours (in hh:mm format). Used to set the total time_spent. If this property is set via update call the timer_running will be stopped and reset to the passed value
ticket_id* number The ID of the ticket* to which this time-entry is associated. Id is passed as part of the handle url Read-Only
user_id number The user/agent to whom this time-entry is associated Mandatory
agent_name string System fills the agent name in the response from the above user_id Read-Only
agent_email string The agent email in the response from the above user_id Read-Only

Note:
1. * - You can use any of the modules here - incident, problem, change or release.
2. {module_name} - You can use any of the modules here - tickets, problems, changes or releases.

Create Time Entry

This API helps you create a Time Entry.

Note:
1. If you don't specify in the API command, the timer-running attribute will be set to 'true' and the activities will get clocked once the timesheet is created.

post
/itil/{module_name}/{module_item_id}/time_sheets.json
Request 
1
2
3
4
5
6
7
8
{
 "time_entry": { 
      "note":"test_entry",
      "hhmm":"03:00",
      "user_id":"1",
      "billable":"true"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "time_entry":{
      "agent_email":"sample@freshservice.com",
      "agent_name":"sample",
      "billable":true,
      "created_at":"2014-12-10T12:36:03+05:30",
      "executed_at":"2014-10-10T05:52:58+05:30",
      "id":33,
      "note":"test_entry",
      "start_time":"2014-12-10T15:07:54+05:30",
      "ticket_id":44,
      "timer_running":false,
      "timespent":"3.02",
      "updated_at":"2014-12-10T15:08:17+05:30",
      "user_id":1 
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"time_entry":{"note":"test_entry","hhmm":"03:00","user_id":"1","billable":"true"}}'  https://domain.freshservice.com/itil/tickets/44/time_sheets.json
EXPAND ↓

View By Module Time Entry

To view existing Time Entries, use this API.

get
/itil/{module_name}/{module_item_id}/time_sheets.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "time_entry":{
      "agent_email":"sample@freshservice.com",
      "agent_name":"sample",
      "billable":true,
      "created_at":"2014-12-10T12:36:03+05:30",
      "executed_at":"2014-10-10T05:52:58+05:30",
      "id":33,
      "note":"test_entry",
      "start_time":"2014-12-10T15:07:54+05:30",
      "ticket_id":44,
      "timer_running":false,
      "timespent":"3.02",
      "updated_at":"2014-12-10T15:08:17+05:30",
      "user_id":1 
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/tickets/44/time_sheets.json
EXPAND ↓

Update Time Entry

You can use this API to update/modify existing time entries.

put
/itil/{module_name}/{module_item_id}/time_sheets/[id].json
Request 
1
2
3
4
5
6
{
   "time_entry": { 
      "note":"test_entry_update",
      "billable":"false"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "time_entry":{
      "agent_email":"sample@freshservice.com",
      "agent_name":"sample",
      "billable":false,
      "created_at":"2014-12-10T12:36:03+05:30",
      "executed_at":"2014-10-10T05:52:58+05:30",
      "id":33,
      "note":"test_entry_update",
      "start_time":"2014-12-10T15:07:54+05:30",
      "ticket_id":44,
      "timer_running":false,
      "timespent":"3.02",
      "updated_at":"2014-12-10T15:08:17+05:30",
      "user_id":1 
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{"time_entry":{"note":"test_entry_update","billable":"false"}}'  https://domain.freshservice.com/itil/tickets/44/time_sheets/33.json
EXPAND ↓

Start/Stop Timer

This API helps you start or stop the timer.

put
/itil/{module_name}/{module_item_id}/time_sheets/[id]/toggle_timer.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "time_entry":{
      "agent_email":"sample@freshservice.com",
      "agent_name":"sample",
      "billable":false,
      "created_at":"2014-12-10T12:36:03+05:30",
      "executed_at":"2014-10-10T05:52:58+05:30",
      "id":33,
      "note":"test_entry_update",
      "start_time":"2014-12-10T15:07:54+05:30",
      "ticket_id":44,
      "timer_running":true,
      "timespent":"3.02",
      "updated_at":"2014-12-10T15:08:17+05:30",
      "user_id":1 
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT https://domain.freshservice.com/itil/tickets/44/time_sheets/33/toggle_timer.json
EXPAND ↓

Delete Time Entry

You can use this API to delete an existing Time Entry. You cannot restore deleted time entries.

delete
/itil/{module_name}/{module_item_id}/time_sheets/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/itil/tickets/44/time_sheets/33.json
EXPAND ↓

Tasks

These APIs let you manage tasks within modules, right from creating new tasks to updating and even deleting them.

* - You can use any of the modules here - incident, problem, change or release.

Attribute Type Description
id number Id of the time entry Read-Only
owner_id number user_id of the assigned agent
status number Status of the task
due_date datetime Due date of the task
notify_before number Time before the due_date at which agent should be notified
deleted boolean set to true if the task is deleted.Read-Only
title string title of the task Mandatory
description string description of the task
group_id number id of the group assigned to the task
ticket_id number id of the ticket to which the task is associated. Read-Only
user_id number id of the user creating the task. Read-Only

TASK PROPERTIES

With every task having certain fixed values to denote the ‘notify before’ time and status, the equivalent values are given below

NOTIFY BEFORE VALUE
never never
15 minutes fifteen
30 minutes thirty
45 minutes fortyfive
1 hour onehour
2 hours twohour
STATUS VALUE
open 1
inprogress 2
completed 3

Note:
1. * - You can use any of the modules here - incident, problem, change or release.
2. {module_name} - You can use any of the modules here - tickets, problems, changes or releases.

Create a Task

This API helps you create tasks for tickets, problems, changes and releases in your service desk.

post
/itil/{module_name}/{module_item_id}/it_tasks.json
Request 
1
2
3
4
5
6
7
8
9
10
11
{
   "it_task":{
      "title":"Supply lightsabers to all the Jedis",
      "description":"We need to re-supply to win the war!.",
      "group_id":"5",
      "owner_id":"3",
      "due_date":"2015-01-06 09:41:20",
      "status":"1",
      "notify_before":"fifteen"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "it_task":{
      "closed_at":null,
      "created_at":"2015-05-13T18:07:56+05:30",
      "deleted":false,
      "description":"We need to re-supply to win the war!.",
      "display_id":null,
      "due_date":"2015-01-06 09:41:20",
      "group_id":5,
      "id":13,
      "owner_id":3,
      "status":1,
      "ticket_id":2,
      "title":"Supply lightsabers to all the Jedis",
      "updated_at":"2015-05-13T18:07:56+05:30",
      "user_id":1,
      "notify_time":"15 Minutes"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{"it_task":{"title":"Supply lightsabers to all the Jedis","description":"We need to re-supply to win the war!.","group_id":"5","owner_id":"3","due_date":"2015-01-06 09:41:20","status":"1","notify_before":"fifteen"}}'   https://domain.freshservice.com/itil/tickets/2/it_tasks.json
EXPAND ↓

View My Tasks

This API helps you view all the tasks of the user currently logged in.

get
/itil/it_tasks.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "it_task":{
      "closed_at":null,
      "created_at":"2015-05-13T18:07:56+05:30",
      "deleted":false,
      "description":"We need to resupply to win the war!.",
      "display_id":null,
      "due_date":"2015-01-06 09:41:20",
      "group_id":5,
      "id":13,
      "owner_id":3,
      "status":1,
      "ticket_id":2,
      "title":"Supply lightsabers to all the Jedis",
      "updated_at":"2015-05-13T18:07:56+05:30",
      "user_id":1,
      "notify_time":"15 Minutes"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET -d https://domain.freshservice.com/itil/it_tasks.json
EXPAND ↓

View a Specific Task

This API helps you view a specific task within a particular module.

get
/itil/{module_name}/{module_item_id}/it_tasks/{task_id}.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "it_task":{
      "closed_at":null,
      "created_at":"2015-05-13T18:07:56+05:30",
      "deleted":false,
      "description":"We need to re-supply to win the war!.",
      "display_id":null,
      "due_date":"2015-01-06 09:41:20",
      "group_id":5,
      "id":13,
      "owner_id":3,
      "status":1,
      "ticket_id":2,
      "title":"Supply lightsabers to all the Jedis",
      "updated_at":"2015-05-13T18:07:56+05:30",
      "user_id":1,
      "notify_time":"15 Minutes"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET -d https://domain.freshservice.com/itil/tickets/2/it_tasks/13.json
EXPAND ↓

View Task By Module Item

This API helps you view tasks from a particular module in your service desk.

get
/itil/{module_name}/{module_item_id}/it_tasks.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "it_task":{
      "closed_at":null,
      "created_at":"2015-05-13T18:07:56+05:30",
      "deleted":false,
      "description":"We need to re-supply to win the war!.",
      "display_id":32,
      "due_date":"2015-01-06 09:41:20",
      "group_id":5,
      "id":53,
      "owner_id":3,
      "status":1,
      "ticket_id":2,
      "title":"Supply lightsabers to all the Jedis",
      "updated_at":"2015-05-13T18:07:56+05:30",
      "user_id":1,
      "notify_time":"15 Minutes"
   }
}
EXPAND ↓
Sample code | Curl 
1
2
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET -d 
https://domain.freshservice.com/itil/tickets/13/it_tasks.json
EXPAND ↓

Update a Task

This API helps you to update a particular task from the modules in your service desk.

put
/itil/{module_name}/{module_item_id}/it_tasks/{task_id}.json
Request 
1
2
3
4
5
6
7
8
9
10
{
   "it_task":{
      "title":"Supply medi-kits to all the base stations",
      "description":"This is very important!.",
      "owner_id":"5",
      "due_date":"2015-05-13 12:47:02",
      "status":"2",
      "notify_before":"thirty"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "it_task":{
      "closed_at":null,
      "created_at":"2015-05-13T18:07:56+05:30",
      "deleted":false,
      "description":"This is very important!.",
      "display_id":null,
      "due_date":"2015-01-06 09:41:20",
      "group_id":5,
      "id":13,
      "owner_id":5,
      "status":2,
      "ticket_id":2,
      "title":"Supply medi-kits to all the base stations",
      "updated_at":"2015-05-13 12:44:44",
      "user_id":1,
      "notify_time":"30 Minutes"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "it_task":{"title":"Supply medi-kits to all the base stations","description":"This is very important!.","owner_id":"5","due_date":"2015-05-13 12:47:02","status":"2","notify_before":"thirty"}}' https://domain.freshservice.com/itil/tickets/2/it_tasks/13.json
EXPAND ↓

Delete a Task

This API helps you delete a particular task from the modules in your service desk.

delete
/itil/{module_name}/{module_item_id}/it_tasks/{task_id}.json
Response 
1
"deleted"
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE  https://domain.freshservice.com/itil/tickets/14/it_tasks/13.json
EXPAND ↓

Agent

You can view agents information using the following APIs. Only users with admin privileges can access the following APIs.

Attribute Type Description
id number Id of an agent
occasional boolean Set to true if occasional agent (true => occasional, false=> full-time )
signature_html string Signature of an agent in HTML format
points string Points scored by an agent
scoreboard_level_id number Scoreboard level id of an agent
ticket_permission number Ticket permission given to an agent (1 -> Global Access, 2 -> Group Access, 3 -> Restricted Access)
user_id number User id of an agent
user[name] string Name of an agent
user[email] string Email id of an agent
user[job_title] string Job Title of an agent
user[phone] number Telephone number of an agent
user[mobile] number Mobile number of an agent
user[language] string Language of an agent. Default language is "en"
user[time_zone] string Time zone of an agent
user[helpdesk_agent] boolean Set to true for an agent

View Agent

If you want to view a particular agent, this API can be used.

get
/agents/[id].json
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
{  
      "agent":{  
         "active_since":null,
         "available":true,
         "created_at":"2015-01-02T22:56:39-10:00",
         "id":19,
         "occasional":false,
         "points":2500,
         "scoreboard_level_id":5,
         "signature":null,
         "signature_html":"\u003Cp\u003E\u003Cbr\u003E\u003C/p\u003E\r\n",
         "ticket_permission":1,
         "updated_at":"2015-01-04T23:09:52-10:00",
         "user":{  
            "active":false,
            "address":null,
            "created_at":"2014-12-30T18:49:39-10:00",
            "deleted":false,
            "description":null,
            "email":"prime@transformers.com",
            "external_id":null,
            "helpdesk_agent":true,
            "id":4,
            "job_title":"Agent",
            "language":"en",
            "mobile":"",
            "name":"Optimus Prime",
            "phone":"",
            "time_zone":"Chennai",
            "updated_at":"2015-01-04T23:09:51-10:00"
         }
      }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/agents/19.json
EXPAND ↓

View All Agent

If you want to view a list of agents, this API can be used.

To view only specific agents (that is, those which match only the criteria you choose) use filters.

Filter by Handle
email, mobile, phone /agents.json?query= <condition>
Example:
/agents.json?query=email is user@yourcompany.com
[Note: Do an url encode of the query string and supports only is operator]
state /agents/filter/[state]?format=json i.e., [active/occasional]

Only all active agents will be listed using "/agents.json" api. To view all occasional agents "/agents/filter/occasional?format=json" api can be used.

get
/agents.json
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
[  
   {  
      "agent":{  
         "active_since":null,
         "available":true,
         "created_at":"2015-01-02T22:56:39-10:00",
         "id":19,
         "occasional":false,
         "points":2500,
         "scoreboard_level_id":5,
         "signature":null,
         "signature_html":"\u003Cp\u003E\u003Cbr\u003E\u003C/p\u003E\r\n",
         "ticket_permission":1,
         "updated_at":"2015-01-04T23:09:52-10:00",
         "user":{  
            "active":false,
            "address":null,
            "created_at":"2014-12-30T18:49:39-10:00",
            "deleted":false,
            "description":null,
            "email":"prime@transformers.com",
            "external_id":null,
            "fb_profile_id":null,
            "helpdesk_agent":true,
            "id":2,
            "job_title":"Agent",
            "language":"en",
            "mobile":"",
            "name":"Optimus Prime",
            "phone":"",
            "time_zone":"Chennai",
            "twitter_id":null,
            "updated_at":"2015-01-04T23:09:51-10:00"
         }
      }
   },
   {  
      "agent":{  
         "active_since":null,
         "available":true,
         "created_at":"2014-12-11T21:20:10-10:00",
         "id":20,
         "occasional":false,
         "points":100,
         "scoreboard_level_id":2,
         "signature":null,
         "signature_html":"\u003Cp\u003E\u003Cbr\u003E\u003C/p\u003E\r\n",
         "ticket_permission":2,
         "updated_at":"2014-12-11T21:20:11-10:00",
         "user":{  
            "active":false,
            "address":null,
            "created_at":"2014-12-11T21:20:10-10:00",
            "deleted":false,
            "description":null,
            "email":"bee@transformers.com",
            "external_id":null,
            "helpdesk_agent":true,
            "id":1,
            "job_title":"Agent",
            "language":"en",
            "mobile":"",
            "name":"Bumblebee",
            "phone":"",
            "time_zone":"Chennai",
            "updated_at":"2015-01-16T22:21:48-10:00"
         }
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/agents.json
EXPAND ↓

User

You can create users, view and update user information using the following APIs

Attribute Type Description
id number Id of the user Read-Only
name string Name of the user Mandatory
email * string Email for the user Mandatory
address string Address of the user
description string A small description about the user
job_title string Job Title of the user
phone * number Telephone number of the user
mobile * number Mobile number of the user
language string Language of the user. Default language is "en"
time_zone string Time zone of the user
deleted boolean Set to true if the contacts is deleted
helpdesk_agent boolean Indicates if the contact is an agent Read-Only
active boolean Set to true if the user is verifiedRead-Only
* Email, Phone or Mobile - one of three is mandatory to create an user.

Create a User

This API helps you create new users. The Email and Name parameters are mandatory

post
/itil/requesters.json
Request 
1
2
3
4
5
6
7
8
9
{
  "user":{ 
    "name":"Super Man",
    "email":"ram@freshservice.com",
    "department_users_attributes":{
        "department_id": "2,3" 
    }
  }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "user":{
      "active":false,
      "address":null,
      "created_at":"2014-01-07T19:33:43+05:30",
      "deleted":false,
      "description":null,
      "email":"ram@freshservice.com",
      "external_id":null,
      "id":19,
      "job_title":null,
      "language":"en",
      "mobile":null,
      "name":"Super Man",
      "phone":null,
      "time_zone":"Hawaii",
      "updated_at":"2014-01-07T19:33:43+05:30",
      "department_names":["Sales", "Customer Support"]
    }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "user": { "name":"Super Man", "email":"ram@freshservice.com","department_users_attributes":{ "department_id": "2,3" } }}' https://domain.freshservice.com/itil/requesters.json
EXPAND ↓

View a User

If you want to view/spy/stalk a particular user, this API can be used.

get
/itil/requesters/[id].json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "user":{
      "active":false,
      "address":null,
      "created_at":"2014-01-07T19:33:43+05:30",
      "deleted":false,
      "description":null,
      "email":"ram@freshservice.com",
      "external_id":null,
      "id":19,
      "job_title":null,
      "language":"en",
      "mobile":null,
      "name":"Super Man",
      "phone":null,
      "time_zone":"Hawaii",
      "updated_at":"2014-01-07T19:33:43+05:30",
      "department_names":["Sales", "Customer Support"]
    }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/requesters/19.json
EXPAND ↓

View list of Users

If you want to view a list of users, this API can be used.

To view only specific users (that is, those which match only the criteria you choose) use filters. All the below criterias can also be used in combinations

Filter by Handle
email, mobile, phone /itil/requesters.json?query=<condition>
Example:
/itil/requesters.json?query=email is user@yourcompany.com
[Note: Do an url encode of the query string]
state /itil/requesters?state=[state]
i.e., [verified/unverified/all/deleted]

Note:
This request is paginated to return only 50 users per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

get
/itil/requesters.json
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
[
   {
      "user":{
         "active":false,
         "address":null,
         "created_at":"2014-01-07T19:33:43+05:30",
         "deleted":false,
         "description":null,
         "email":"ram@freshservice.com",
         "external_id":null,
         "id":19,
         "job_title":null,
         "language":"en",
         "mobile":null,
         "name":"Super Man",
         "phone":null,
         "time_zone":"Hawaii",
         "updated_at":"2014-01-07T19:33:43+05:30",
         "department_names":["Sales", "Customer Support"]
       }
   },
   {
      "user":{
         "active":false,
         "address":null,
         "created_at":"2014-01-07T19:33:43+05:30",
         "deleted":false,
         "description":null,
         "email":"sam@freshservice.com",
         "external_id":null,
         "id":20,
         "job_title":null,
         "language":"en",
         "mobile":null,
         "name":"Iron Man",
         "phone":null,
         "time_zone":"Hawaii",
         "updated_at":"2014-01-07T19:33:43+05:30",
         "department_names":["IT", "Finance"]
       }
   },
   ...
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/requesters.json
EXPAND ↓

Update a User

This API helps you modify the details of an existing user. For a list of all details that can be modified, view the table given above.

put
/itil/requesters/[id].json
Request 
1
2
3
4
5
6
7
8
9
{
  "user":{ 
    "name":"Super Man",
    "email":"ram@freshservice.com",
    "department_users_attributes":{
        "department_id": "5,6" 
    }
  }
}
EXPAND ↓
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "user": { "name":"Super Man", "email":"ram@freshservice.com","department_users_attributes":{ "department_id": "5,6" } }}' https://domain.freshservice.com/itil/requesters/19.json
EXPAND ↓

Delete a User

This API lets you delete a user.

delete
/itil/requesters/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/itil/requesters/19.json
EXPAND ↓

Department

This section lists all API that can be used to create, edit or delete departments.

Attribute Type Description
id number Unique id of the department Read-Only
name string Name of the department
description string Description of the department
head_id number id of the head_user
prime_user_id number id of the prime_user

Create a Department

This API helps you to create a new department in your service desk.

post
/itil/departments.json
Request 
1
2
3
4
5
6
7
8
9
{
    "itil_department":{
        "name":"SuperNova",
        "description":"Spaceship Manufacturing Company"
        "department_users_attributes":{
            "head_id":"34"
        }
    }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "itil_department":{
        "created_at":"2014-04-30T09:49:02+05:30",
        "description":"Spaceship Manufacturing Company",
        "head_id":34,
        "id":8,
        "name":"SuperNova",
        "prime_user_id":null,
        "updated_at":"2014-04-30T09:49:02+05:30",
        "head_name": "downey",
        "prime_user_name":"null"
    }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "itil_department":{ "name":"SuperNova", "description":"Spaceship Manufacturing Company", "head_id":"34"}}' https://domain.freshservice.com/itil/departments.json
EXPAND ↓

View a Department

This API lets you view a particular department.

get
/itil/departments/[id].json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
      "itil_department":{
            "created_at":"2014-04-30T09:49:02+05:30",
            "description":"Spaceship Manufacturing Company",
            "head_id":34,
            "id":8,
            "name":"SuperNova",
            "prime_user_id":36,
            "updated_at":"2014-04-30T09:49:02+05:30",
            "head_name": "downey",
            "prime_user_name":"robert",
            "custom_fields":{
              "Product category": "shipping containers",
              "Transport medium" :"roadways"
            }

      }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/departments/8.json
EXPAND ↓

View list of Departments

This API lets you view all the departments in your list.

get
/itil/departments.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[
   {
      "itil_department":{
         "created_at":"2014-04-30T09:49:02+05:30",
         "description":"Spaceship Manufacturing Company",
         "head_id":34,
         "id":8,
         "name":"SuperNova",
         "prime_user_id":36,
         "updated_at":"2014-04-30T09:49:02+05:30",
         "head_name": "downey",
         "prime_user_name":"robert",
         "custom_fields":{
            "Product category": "shipping containers",
            "Transport medium" :"roadways"
         }
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/itil/departments.json
EXPAND ↓

Update a Department

This API lets you modify department details.

put
/itil/departments/[id].json
Request 
1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "itil_department":{
      "name":"Super Nova",
      "description":"Space Shuttle Manufacturing",
      "department_user_attributes":{
         "prime_user_id":"36",
         "custom_fields":{
            "Product category": "shipping containers",
            "Transport medium" :"roadways"
         }         
      }
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "itil_department":{
      "created_at":"2014-04-30T09:49:02+05:30",
      "description":"Spaceship Manufacturing Company",
      "head_id":34,
      "id":8,
      "name":"SuperNova",
      "prime_user_id":36,
      "updated_at":"2014-04-30T09:49:02+05:30",
      "head_name": "downey",
      "prime_user_name":"robert",
      "custom_fields":{
         "Product category": "shipping containers",
         "Transport medium" :"roadways"
      }      
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "itil_department": { "name":"Super Nova", "description":"Space Shuttle Manufacturing", "prime_user_id":"36"}}' https://domain.freshservice.com/itil/departments/8.json
EXPAND ↓

Delete a Department

This API lets you delete a department.

delete
/itil/departments/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/itil/departments/8.json
EXPAND ↓

Asset

This section lists all API that can be used to create, edit or delete Assets.

Attribute Type Description
id number Unique id of the item Read-Only
name string Name of the itemMandatory
description string Description of the item
ci_type_id number id of the item typeMandatory
impact* number Impact of the item
user_id number Id of the item_user
department_id number Id of the associated department
agent_id number Id of the associated agent
assigned_on datetime Date at which the item is assigned
deleted number Sets true if the item is deleted
display_id number Display_id of the item
root_id number Id of the ancestor
location_id string Name of the location associated to the item
asset_tag string Asset tag of the item

Asset Properties

Each asset has a distinct property named impact for which the fixed values have been given below,
Impact Value
low 1
medium 2
high 3

Create a Asset

This API helps you to create a new asset in your service desk.

post
/cmdb/items.json
Request 
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
{ 
    "cmdb_config_item":{
        "user_id":"214",
        "department_id":"4",
        "impact":"2",
        "location_id":"america",
        "assigned_on":"2014-07-18 03:54:18",
        "agent_id":"215",
        "asset_tag":"batch_2017",
        "name":"Windows 8",
        "ci_type_id":"3",
        "level_field_attributes":{
            "product_3":"windows_os",
            "vendor_3":"microsoft",
            "cost":"8000",
            "license_validity_3":"24",
            "installation_date_3":"2014-07-24 13:33:35",
            "license_expiry_date_3":"2016-07-24 13:33:35",
            "license_key_3":"234-423-543-534",
            "version_3":"2.0",
            "license_type_3":"commercial",
            "installed_machine_3":"Andrea's laptop",
            "installation_path_3":"null",
            "last_audit_date_3":"2014-07-16 14:27:48"
        }
    }
}
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
{
    "config_item":{
        "agent_id":215,
        "asset_tag":batch_2017,
        "assigned_on":"2014-07-18T03:54:18+05:30",
        "ci_type_id":3,
        "created_at":"2014-07-25T14:25:04+05:30",
        "deleted":false,
        "department_id":4,
        "depreciation_id":null,
        "description":null,
        "disabled":false,
        "display_id":113,
        "expiry_notified":false,
        "id":113,
        "impact":2,
        "location_id":1,
        "name":"windows_8",
        "salvage":null,
        "trashed":false,
        "updated_at":"2014-07-25T14:25:04+05:30",
        "user_id":214,
        "department_name":"Finance",
        "used_by":"Rachel",
        "business_impact":"Medium",
        "agent_name":"Andrea",
        "levelfield_values":{
            "product_3":100,
            "vendor_3":43,
            "cost_3":4000,
            "license_validity_3":24,
            "installation_date_3":"2014-07-25T14:25:04+05:30",
            "license_expiry_date_3":"2016-07-25T00:00:00+05:30",
            "license_key_3":234-423-543-534,
            "version_3":2.0,
            "license_type_3":"commercial",
            "installed_machine_3":"Andrea’s computer",
            "installation_path_3":null,
            "last_audit_date_3":"2014-07-25T14:25:04+05:30"
        },
        "ci_type_name":"Software",
        "product_name":"windows_os",
        "vendor_name":"micosoft",
        "state_name":null,
        "location_name":"America"
    }
}
EXPAND ↓
Sample code | Curl 
1
curl -u sample@freshservice.com:test -H "Content-Type: application/json" -d '{ "cmdb_config_item":{"user_id":"214","department_id":"4","impact":"2","location_id":"america","assigned_on":"2014-07-18 03:54:18","agent_id":"215","asset_tag":"batch_2017","name":"Windows 8","ci_type_id":"3","level_field_attributes":{"product_3":"windows_os","vendor_3":"microsoft","cost":"8000","license_validity_3":"24","installation_date_3":"2014-07-24 13:33:35","license_expiry_date_3":"2016-07-2413:33:35","license_key_3":"234-423-543-534","version_3":"2.0","license_type_3":"commercial","installed_machine_3":"Andrea's laptop","installation_path_3":"null","last_audit_date_3":"2014-07-16 14:27:48"}}}' -X POST https://domain.freshservice.com/cmdb/items.json
EXPAND ↓

Get All CI/Asset Types

This API helps you to fetch all the available config item types in your help desk.

get
/cmdb/ci_types.json
Response 
1
2
3
4
5
6
7
8
9
10
Response:-
[
	{
		"created_at":"2014-02-19T15:09:49+05:30",
		"description":"",
		"id":18,
		"label":"Access Point",
		"updated_at":"2014-02-19T15:09:49+05:30"
	}
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/cmdb/ci_types .json
EXPAND ↓

Get All CI/Asset Type Fields

This API helps you to fetch all the config item type fields related to a particular config item type in your help desk.

get
/cmdb/ci_types/[id].json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Response:-
[
	{
		"active":true,
		"ci_type_id":2,
		"created_at":"2014-02-19T15:09:50+05:30",
		"deleted":false,
		"description":"",
		"id":1,
		"label":"Product",
		"name":"product_2",
		"position":1,
		"required":true,
		"updated_at":"2014-02-19T15:09:50+05:30"
	}
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/cmdb/ci_types/10 .json
EXPAND ↓

View a Asset

This API lets you view a particular asset.

get
/cmdb/items/[id].json
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
{
  "config_item": {
    "agent_id": 215,
    "asset_tag": batch_2017,
    "assigned_on": "2014-07-18T03:54:18+05:30",
    "ci_type_id": 3,
    "created_at": "2014-07-25T14:25:04+05:30",
    "deleted": false,
    "department_id": 4,
    "depreciation_id": null,
    "description": null,
    "disabled": false,
    "display_id": 113,
    "expiry_notified": false,
    "id": 113,
    "impact": 3,
    "location_id": 21,
    "name": "windows 7",
    "salvage": null,
    "trashed": false,
    "updated_at": "2014-07-25T14:25:04+05:30",
    "user_id": 214,
    "department_name": "Finance",
    "used_by": "Rachel",
    "business_impact": "Medium",
    "agent_name": "Andrea",
    "levelfield_values": {
      "product_3": 100,
      "vendor_3": 43,
      "cost_3": 4000,
      "license_validity_3": 24,
      "installation_date_3": "2014-07-25T14:25:04+05:30",
      "license_expiry_date_3": "2016-07-25T00:00:00+05:30",
      "license_key_3": "234_423_543_534",
      "version_3": 2,
      "license_type_3": "commercial",
      "installed_machine_3": "Andrea’s computer",
      "installation_path_3": null,
      "last_audit_date_3": "2014-07-25T14:25:04+05:30"
    },
    "ci_type_name": "Software",
    "product_name": "windows_os",
    "vendor_name": "micosoft",
    "state_name": null,
    "location_name": "America"
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/cmdb/items/113.json
EXPAND ↓

View list of Assets

This API lets you view all the assets in your list.

Note:
This request is paginated to return only 50 assets per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

get
/cmdb/items.json
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
{
  "config_item": {
    "agent_id": 215,
    "asset_tag": batch_2017,
    "assigned_on": "2014-07-18T03:54:18+05:30",
    "ci_type_id": 3,
    "created_at": "2014-07-25T14:25:04+05:30",
    "deleted": false,
    "department_id": 4,
    "depreciation_id": null,
    "description": null,
    "disabled": false,
    "display_id": 113,
    "expiry_notified": false,
    "id": 113,
    "impact": 3,
    "location_id": 21,
    "name": "windows 7",
    "salvage": null,
    "trashed": false,
    "updated_at": "2014-07-25T14:25:04+05:30",
    "user_id": 214,
    "department_name": "Finance",
    "used_by": "Rachel",
    "business_impact": "Medium",
    "agent_name": "Andrea",
    "levelfield_values": {
      "product_3": 100,
      "vendor_3": 43,
      "cost_3": 4000,
      "license_validity_3": 24,
      "installation_date_3": "2014-07-25T14:25:04+05:30",
      "license_expiry_date_3": "2016-07-25T00:00:00+05:30",
      "license_key_3": "234_423_543_534",
      "version_3": 2,
      "license_type_3": "commercial",
      "installed_machine_3": "Andrea’s computer",
      "installation_path_3": null,
      "last_audit_date_3": "2014-07-25T14:25:04+05:30"
    },
    "ci_type_name": "Software",
    "product_name": "windows_os",
    "vendor_name": "micosoft",
    "state_name": null,
    "location_name": "America"
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/cmdb/items.json
EXPAND ↓

Update a Asset

This API lets you modify asset details.

put
/cmdb/items/[id].json
Request 
1
2
3
4
5
6
7
8
{
   "cmdb_config_item": { 
      "name": "windows 7",
      "impact": "high",
      "asset_tag": "win7_1",
      "location_id":"Italy"
   }
}
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
{
   "config_item":{
      "agent_id":215,
      "asset_tag":win7_1,
      "assigned_on":"2014-07-18T03:54:18+05:30",
      "ci_type_id":3,
      "created_at":"2014-07-25T14:25:04+05:30",
      "deleted":false,
      "department_id":4,
      "depreciation_id":null,
      "description":null,
      "disabled":false,
      "display_id":113,
      "expiry_notified":false,
      "id":113,
      "impact":3,
      "location_id":21,
      "name":"windows 7",
      "salvage":null,
      "trashed":false,
      "updated_at":"2014-07-25T14:25:04+05:30",
      "user_id":214,
      "department_name":"Finance",
      "used_by":"Rachel",
      "business_impact":"Medium",
      "agent_name":"Andrea",
      "levelfield_values":{
         "product_3":100,
         "vendor_3":43,
         "cost_3":4000,
         "license_validity_3":24,
         "installation_date_3":"2014-07-25T14:25:04+05:30",
         "license_expiry_date_3":"2016-07-25T00:00:00+05:30",
         "license_key_3":234-423-543-534,
         "version_3":2.0,
         "license_type_3":"commercial",
         "installed_machine_3":"Andrea’s computer",
         "installation_path_3":null,
         "last_audit_date_3":"2014-07-25T14:25:04+05:30"
      },
      "ci_type_name":"Software",
      "product_name":"windows_os",
      "vendor_name":"micosoft",
      "state_name":null,
      "location_name":"Italy"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "cmdb_config_item": { "name": "windows 7", "impact": "high","asset_tag": "win7_1","location_id":"Italy"}}' -X PUT https://domain.freshservice.com/cmdb/items/113.json
EXPAND ↓

Delete a Asset

This API lets you delete a asset.

delete
/cmdb/items/[id].json
Response 
1
{ "success":true }
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/cmdb/items/16.json
EXPAND ↓

Restore a Asset

If you deleted or disabled some assets and regret doing so now, this API will help you restore them.

put
/cmdb/items/[id]/restore.json
Response 
1
{ "success":true }
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT https://domain.freshservice.com/cmdb/items/16/restore.json
EXPAND ↓

Search Assets

This API lets you search for assets based on the some attributes.

Attribute Type Description
field_param string Specify the field which should be used to search for an asset.Mandatory
Allowed Parameters :
‘name’
‘asset_tag’
‘serial_number’
query_param string Search textMandatory

Note:
All the below requests are paginated to return only 25 results per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

get
/cmdb/items/list.json?field=[field_param]&q=[query_param]
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
{
  "config_items": [
    {
      "agent_id": null,
      "asset_tag": batch_2017,
      "assigned_on": null,
      "ci_type_id": 30,
      "created_at": "2017-08-07T17:37:50+05:30",
      "department_id": null,
      "depreciation_id": null,
      "description": null,
      "display_id": 1,
      "id": 1,
      "impact": 2,
      "location_id": null,
      "name": "Andrea's Laptop",
      "salvage": null,
      "updated_at": "2017-08-07T17:37:50+05:30",
      "usage_type": 1,
      "user_id": 2,
      "department_name": null,
      "used_by": "Andrea",
      "business_impact": "Medium",
      "agent_name": null,
      "levelfield_values": {
        "product_3": 5,
        "vendor_3": null,
        "cost_3": null,
        "warranty_3": null,
        "acquisition_date_3": null,
        "warranty_expiry_date_3": null,
        "domain_3": null,
        "asset_state_3": 1,
        "serial_number_3": null,
        "last_audit_date_3": null,
        "os_9": "Mac",
        "os_version_9": "OS X",
        "os_service_pack_9": null,
        "memory_9": null,
        "disk_space_9": null,
        "cpu_speed_9": null,
        "cpu_core_count_9": null,
        "mac_address_9": null,
        "uuid_9": null,
        "hostname_9": null
      },
      "ci_type_name": "Laptop",
      "product_name": "Apple MacBook Air 13",
      "vendor_name": null,
      "state_name": "In Use",
      "location_name": null
    }
  ]
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/cmdb/items/list.json?field=name&q=andrea'
EXPAND ↓

Asset Relationships

This section lists all the APIs that can be used to perform operations related to Asset Relationships such as Creating, Deleting and Viewing relationships for an asset.

Attribute Type Description
id number Unique ID of an item
type string Relationships can be created between an asset and a requester, agent, department or another asset.
Allowed parameters:
‘requesters' -> to associate an asset to requesters
'agents' -> to associate an asset to agents
‘departments' -> to associate an asset to departments
'config_items' -> to associate an asset to another asset
type_id number ID or list of IDs of the Requesters, Agents, Departments or Assets that is to be associated to an Asset.
relationship_type_id number ID of the relationship type
relationship_type string Indicates whether the relationship should be a forward or inverse relationship.
Allowed parameters:
‘forward_relationship’
‘backward_relationship’
relationship_id number Unique ID of a relationship

List Relationship Types

This API lets you view the list of all the relationship types configured in your helpdesk. The id obtained in the response can then be used to create new relationships.

get
/cmdb/relationship_types/list.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[
  {
    "backward_relationship": "Used By",
    "created_at": "2017-08-07T17:37:43+05:30",
    "forward_relationship": "Depends On",
    "id": 1,
    "updated_at": "2017-08-07T17:37:43+05:30"
  },
  {
    "backward_relationship": "Used By",
    "created_at": "2017-08-07T17:37:43+05:30",
    "forward_relationship": "Uses",
    "id": 2,
    "updated_at": "2017-08-07T17:37:43+05:30"
  }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/cmdb/relationship_types/list.json
EXPAND ↓

Create a Relationship

This API lets you create a new relationship to an asset, requestor, agent or department

Note:
To link multiple items to an asset, provide comma separated strings (["1","2","3"]). Even for a single id the array is mandatory.

post
/cmdb/items/[id]/associate.json
Request 
1
2
3
4
5
6
{
  "type":"config_items",
  "type_id":["10","11"],
  "relationship_type_id":"2",
  "relationship_type":"forward_relationship"
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "relationships":[
    {
        "id":1,
        "relationship_type": "forward_relationship",
        "relationship_type_id": 2,
        "config_item": {
            "display_id":10
        }
    },
    {
        "id":2,
        "relationship_type": "forward_relationship",
        "relationship_type_id": 2,
        "config_item": {
            "display_id":11
        }
    }
  ]
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{"type":"config_items", "type_id":["10"], "relationship_type_id":"2", "relationship_type":"forward_relationship"}' -X POST https://domain.freshservice.com/cmdb/items/1/associate.json
EXPAND ↓

Delete a Relationship

This API lets you delete an existing relationship of an asset.

Note:
The "relationship_id" param is the "id" of the relationship which is found either as a response after creating a relationship or from the View Relationships API

delete
/cmdb/items/[id]/detach_relationship.json
Request 
1
2
3
{
	"relationship_id":"1"
}
EXPAND ↓
Response 
1
"deleted"
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/cmdb/items/1/detach_relationship.json -d '{"relationship_id":"1"}'
EXPAND ↓

View Relationships

This API lets you view all the relationships of an asset.

get
/cmdb/items/[id]/relationships.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "relationships":[
    {
        "id":1,
        "relationship_type": "forward_relationship",
        "relationship_type_id": 2,
        "config_item": {
            "display_id":10
        }
    },
    {
        "id":2,
        "relationship_type": "forward_relationship",
        "relationship_type_id": 2,
        "config_item": {
            "display_id":11
        }
    }
  ]
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/cmdb/items/1/relationships.json
EXPAND ↓

Solution Category

The Solution APIs allow you to perform all activities related to the creation and publishing of solutions to your requesters. You can create, modify or delete solutions from anywhere you want using the Solutions API.

The API is divided into 3 categories:
1. Solution Category,
2. Solution Folder
3. Solution Article

Attribute Type Description
id number Unique id of the solution category Read-Only
name string Name of the solution category Mandatory
description string Description about the solution category
position number The rank of the solution category in the category listing Read-Only
is_default boolean Set as true if the category is a default one Read-Only

Create Solution Category

Use this API to create a new category of solutions.

post
/solution/categories.json
Request 
1
2
3
4
5
6
{
   "solution_category": {
      "name":"API",
      "description":"API related documents"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
{
   "category":{
      "created_at":"2014-01-08T11:53:32+05:30",
      "description":"API related documents",
      "id":4,
      "is_default":false,
      "name":"API",
      "position":4,
      "updated_at":"2014-01-08T11:53:32+05:30"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "solution_category": { "name":"API", "description":"API related documents" }}' https://domain.freshservice.com/solution/categories.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
require "rubygems"
require "rest_client"
require "json"

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories.json","user@yourcompany.com","test")

response = site.post({:solution_category=>{:name=>"new category",:description=>"Testing solution category"}},:content_type=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

Update Solution Category

Use this API to update solution categories. For a list of all attributes that can be updated, look here

put
/solution/categories/[id].json
Request 
1
2
3
4
5
{
   "solution_category": {
      "name":"Rest API"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
{
   "category":{
      "created_at":"2014-01-08T11:53:32+05:30",
      "description":"API related documents",
      "id":4,
      "is_default":false,
      "name":"Rest API",
      "position":4,
      "updated_at":"2014-01-08T11:54:36+05:30"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "solution_category": { "name":"Rest API" }}' https://domain.freshservice.com/solution/categories/4.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
require "rubygems"
require "rest_client"
require "json"

# Need category_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/6.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/[category_id].json","user@yourcompany.com","test")

response = site.put({:solution_category=>{:name=>"Freshservice",:description=>"Testing solution category"}},:content_type=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

View Solution Category

To view the category available in your service desk, use this

get
/solution/categories/[id].json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
{
   "category":{
      "created_at":"2014-01-08T11:53:32+05:30",
      "description":"API related documents",
      "id":4,
      "is_default":false,
      "name":"Rest API",
      "position":4,
      "updated_at":"2014-01-08T11:53:32+05:30",
      "folders":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/solution/categories/4.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
require "rubygems"
require "rest_client"
require "json"

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories.json","user@yourcompany.com","test")

response = site.get(:accept=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

View All Solution Category

This API lets you view all the categories in a forum.

get
/solution/categories.json
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
[ 
  {
    "category" : {
    "created_at" : "2014-03-03T15:42:36+05:30",
    "description" : "All emails sent to kbase@yourcompany.freshservice.com
     will be stored here as drafts",
      "folders" : [ {
        "category_id" : 1,
        "created_at" : "2014-03-03T15:42:37+05:30",
        "description" : "All emails sent to ...",
        "id" : 3,
        "is_default" : true,
        "name" : "Drafts",
        "position" : 1,
        "updated_at" : "2014-03-03T15:42:37+05:30",
        "visibility" : 3
        } ],
    "id": 1,
    "is_default" : true,
    "name" : "Default Category",
    "position" : 1,
    "updated_at" : "2014-03-03T15:42:36+05:30"
    }
  },
  {
    "category" : {
      "created_at" : "2014-03-04T13:55:54+05:30",
      "description" : "API related documents",
      "folders" : [ {
        "category_id" : 3,
        "created_at" : "2014-03-04T15:13:33+05:30",
        "description" : "Ticket CRUD Operations",
        "id" : 4,
        "is_default" : false,
        "name" : "Ticket API",
        "position" : 1,
        "updated_at" : "2014-03-04T15:13:33+05:30",
        "visibility" : 1
      } ],
      "id" : 4,
      "is_default" : false,
      "name" : "Rest API",
      "position" : 3,
      "updated_at" : "2014-03-04T15:11:13+05:30"
    }
  }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/solution/categories.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
require "rubygems"
		require "rest_client"
		require "json"

		site = RestClient::Resource.new("https://domain.freshservice.com/categories.json","user@yourcompany.com","test")

		response=site.get(:accept=>"application/json")

		puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Delete Solution Category

To delete certain Categories, use this API.

delete
/solution/categories/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/solution/categories/1.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
require "rubygems"
require "rest_client"
require "json"

# Need to specify category_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/4.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/[category_id].json","user@yourcompany.com","test")

response = site.delete(:accept=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

Solution Folder

Know your way around the solution folders using these APIs

Attribute Type Description
id number Unique id of the solution folder Read-Only
name string Name of the solution folder Mandatory
description string Description of the solution folder
position number Describes the position in which the folder is listed Read-Only
is_default boolean Set as true is it is a default folder Read-Only
category_id number ID of the category under which the folder is listed
visibility number Accessibility of this folder
department_folders_attributes[ ].department_id number ID of the department to which this solution folder is visible. ( Mandatory if visibility is set to '4')

Solution Folder Properties

Visibility Type Value
All 1
Logged in Users 2
Agents Only 3
Departments 4

Create Solution Folder

Use this API to create a new folder in your solutions.

post
/solution/categories/[id]/folders.json
Request 
1
2
3
4
5
6
7
8
9
10
11
12
{
   "solution_folder": {
      "name":"Ticket API",
      "visibility":4,
      "description":"Ticket CRUD Operations",
      "department_folders_attributes": {
         "department_id": [
            "4","5"
         ]
      }
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "folder":{
      "category_id":4,
      "created_at":"2014-01-08T11:57:29+05:30",
      "description":"Ticket CRUD Operations",
      "id":6,
      "is_default":false,
      "name":"Ticket API",
      "position":2,
      "updated_at":"2014-01-08T11:57:29+05:30",
      "visibility":4
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "solution_folder": {"name":"Ticket API", "visibility":4, "description":"Ticket CRUD Operations", "department_folders_attributes": { "department_id": [ "4","5" ] } }}' https://domain.freshservice.com/solution/categories/4/folders.json
EXPAND ↓

Update Solution Folder

To update details of your solution folder, use this API. You can change the name, description and with this API.

put
/solution/categories/[id]/folders/[id].json
Request 
1
2
3
4
5
6
{
   "solution_folder": {
      "visibility":1,
      "description":"Tickets API related Operations"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
{
   "folder":{
      "category_id":4,
      "created_at":"2014-01-08T12:04:33+05:30",
      "description":"Tickets API related Operations",
      "id":6,
      "is_default":false,
      "name":"Ticket API",
      "position":2,
      "updated_at":"2014-01-08T12:10:16+05:30",
      "visibility":1
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "solution_folder": { "visibility":1, "description":"Tickets API related Operations" }}' https://domain.freshservice.com/solution/categories/4/folders/6.json
EXPAND ↓

View Solution Folder

To view all folders present in a category, use this API.

get
/solution/categories/[id].json
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
{
   "category":{
      "created_at":"2013-12-23T10:51:51+05:30",
      "description":"API related documents",
      "id":4,
      "is_default":false,
      "name":"Rest API",
      "position":3,
      "updated_at":"2013-12-23T10:51:51+05:30",
      "folders":[{
            "category_id":3,
            "created_at":"2013-12-23T10:53:04+05:30",
            "description":"Tickets API related Operations",
            "id":6,
            "is_default":false,
            "name":"Ticket API",
            "position":1,
            "updated_at":"2013-12-23T10:53:04+05:30",
            "visibility":1
         },
         {
            "category_id":3,
            "created_at":"2014-01-08T11:57:29+05:30",
            "description":"User API related Operations",
            "id":5,
            "is_default":false,
            "name":"User API",
            "position":2,
            "updated_at":"2014-01-08T11:57:29+05:30",
            "visibility":1
         }]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/solution/categories/4.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
require "rubygems"
require "rest_client"
require "json"

# Need to specify category_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/4.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/[category_id].json","user@yourcompany.com","test")

response = site.get(:accept=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

Delete Solution Folder

This API can be used to delete solution folder. Deleted solution folders cannot be restored.

delete
/solution/categories/[id]/folders/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/solution/categories/1/folders/1.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
require "rubygems"
require "rest_client"
require "json"

# Need to specify category_id and folder_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/6/folders/8.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/[category_id]/folders/[folder_id].json","user@yourcompany.com","test")

response = site.delete(:accept=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

Solution Article

With these APIs, create new solution articles, update existing ones, and more.

Attribute Type Description
id number Unique id of the solution article Read-Only
title string Title of the solution article Mandatory
description string Description of the solution article Mandatory
position number The rank of the solution article in the article listing Read-Only
art_type number The type of the article. ( 1 - permanent, 2 - workaround )
folder_id number ID of the folder under which the article is listed Mandatory
status number Status of the article. ( 1 - draft, 2 - published )
thumbs_up number Number of upvotes for the article Read-Only
thumbs_down number Number of down votes for the article Read-Only
user_id number ID of the user who created the article Read-Only

Create Solution Article

To write a new solution in a category, use this API.

Note:
It is also possible to send tags via URL:
/solution/categories/[id]/folders/[id]/articles.json?tags%5Bname%5D=csv

post
/solution/categories/[id]/folders/[id]/articles.json
Request 
1
2
3
4
5
6
7
8
9
10
11
12
{
  "solution_article": {
    "title": "Create a ticket",
    "status": 1,
    "art_type": 2,
    "description": "Steps: Fill in the mandatory fields ...",
    "folder_id": 1
  },
  "tags": {
    "name": "tag1, tag2"
  }
}
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
{
   "article":{
      "art_type":2,
      "created_at":"2014-01-08T15:14:22+05:30",
      "delta":true,
      "desc_un_html":"Steps: Fill in the mandatory fields ...",
      "description":"<p>Steps: Fill in the mandatory fields ...</p>",
      "folder_id":8,
      "id":2,
      "position":1,
      "status":1,
      "thumbs_down":0,
      "thumbs_up":0,
      "title":"Create a ticket",
      "updated_at":"2014-01-08T15:14:22+05:30",
      "user_id":1,
      "tags":[{
         "name":"api"
      }],
      "folder":{
         "category_id":5,
         "created_at":"2014-01-08T15:10:40+05:30",
         "description":"Ticket CRUD Operations",
         "id":8,
         "is_default":false,
         "name":"Ticket API",
         "position":1,
         "updated_at":"2014-01-08T15:10:40+05:30",
         "visibility":1,
         "department_folders":[]
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "solution_article": { "title":"Create a ticket", "status":1, "art_type":2, "description":"Steps: Fill in the mandatory fields ...","folder_id":1 }, "tags":{"name": "tag1,tag2"}}' https://domain.freshservice.com/solution/categories/1/folders/1/articles.json
EXPAND ↓

Update Solution Article

To update an article, use this API.

Note:
It is also possible to send tags via URL:
/solution/categories/[id]/folders/[id]/articles/[id].json?tags%5Bname%5D=csv

put
/solution/categories/[id]/folders/[id]/articles/[id].json
Request 
1
2
3
4
5
6
{
  "solution_article": {
    "title":"Steps to create a ticket",
    "description":"Steps: 1. Fill in the mandatory 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
{ 
  "article" : {
    "art_type" : 2,
    "created_at" : "2014-01-29T16:14:03+05:30",
    "delta" : true,
    "desc_un_html" : "Steps: 1. Fill in the mandatory fields ...",
    "description" : "<p>Steps: 1.Fill in the mandatory fields ...</p>",
    "folder" : { 
      "category_id" : 3,
      "created_at" : "2014-01-08T15:05:09+05:30",
      "department_folders" : [ ],
      "description" : "Ticket CRUD Operations",
      "id" : 7,
      "is_default" : false,
      "name" : "Ticket API",
      "position" : 2,
      "updated_at" : "2014-01-08T15:05:09+05:30",
      "visibility" : 1
      },
    "folder_id" : 7,
    "id" : 3,
    "position" : 1,
    "status" : 1,
    "tags" : [ { "name" : "test" } ],
    "thumbs_down" : 1,
    "thumbs_up" : 1,
    "title" : "Steps to create a ticket",
    "updated_at" : "2014-01-29T16:23:40+05:30",
    "user_id" : 1
    } 
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "solution_article": { "title":"Steps to create a ticket", description":"Steps: 1. Fill in the mandatory fields ..." }}' https://domain.freshservice.com/solution/categories/3/folders/7/articles/3.json
EXPAND ↓

View Solution Article

If there is a specific article which you wish to view, use this API. Article ID is a must though.

get
/solution/categories/[id]/folders/[id]/articles/[id].json
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
{
   "article":{
      "art_type":2,
      "created_at":"2014-01-08T15:14:22+05:30",
      "delta":true,
      "desc_un_html":"Steps: 1. Fill in the mandatory fields ...",
      "description":"<p>Steps: 1. Fill in the mandatory fields ...</p>",
      "folder_id":8,
      "id":2,
      "position":1,
      "status":1,
      "thumbs_down":0,
      "thumbs_up":0,
      "title":"Steps to create a ticket",
      "updated_at":"2014-01-08T15:14:22+05:30",
      "user_id":1,
      "tags":[{
         "name":"test"
      }],
      "folder":{
         "category_id":5,
         "created_at":"2014-01-08T15:10:40+05:30",
         "description":"Ticket CRUD Operations",
         "id":8,
         "is_default":false,
         "name":"Ticket API",
         "position":1,
         "updated_at":"2014-01-08T15:10:40+05:30",
         "visibility":1,
         "department_folders":[

         ]
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET  https://domain.freshservice.com/solution/categories/1/folders/1/articles/1.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
require "rubygems"
require "rest_client"
require "json"

# Need to specify category_id,folder_id,article_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/1813/folders/3216/articles/1355.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/[category_id]/folders/[folder_id]/articles/[article_id].json","user@yourcompany.com","test")

response = site.get(:accept=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

View All Solution Article

To view all the articles, use this API.

get
/solution/categories/[id]/folders/[id].json
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
{
   "folder":{
      "category_id":5,
      "created_at":"2014-01-08T15:10:40+05:30",
      "description":"Ticket CRUD Operations",
      "id":8,
      "is_default":false,
      "name":"Ticket API",
      "position":1,
      "updated_at":"2014-01-08T15:10:40+05:30",
      "visibility":1,
      "articles":[
         {
            "art_type":2,
            "created_at":"2014-01-08T15:14:22+05:30",
            "delta":true,
            "desc_un_html":"Steps: 1. Fill in the mandatory fields ...",
            "description":"<p>Steps: 1. Fill in the mandatory fields ...</p>",
            "folder_id":8,
            "id":2,
            "position":1,
            "status":1,
            "thumbs_down":0,
            "thumbs_up":0,
            "title":"Steps to create a ticket",
            "updated_at":"2014-01-08T15:14:22+05:30",
            "user_id":1
         }
      ]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET  https://domain.freshservice.com/solution/categories/5/folders/8.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
require "rubygems"
require "rest_client"
require "json"

# Need to specify category_id,folder_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/1/folders/2.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/[category_id]/folders/folder_id.json","user@yourcompany.com","test")

response = site.get(:accept=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

Delete Solution Article

To delete an article, use this API.

delete
/solution/categories/[id]/folders/[id]/articles/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE  https://domain.freshservice.com/solution/categories/1/folders/1/articles/1.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
require "rubygems"
require "rest_client"
require "json"

# Need to specify category_id,folder_id,article_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/4/folders/5/articles/1.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshservice.com/solution/categories/[category_id]/folders/[folder_id]/articles/[article_id].json","user@yourcompany.com","test")

response = site.delete(:accept=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
EXPAND ↓

Service Catalog

This section lists all APIs that can be used to create or manipulate Service Requests.

Note:
The visibility and request of items can be restricted by using this parameter "requester_email=[requester_email]".

Attribute Type Description
id number Unique ID of the item
name string Name of the item
display_id number Item ID specific to your account
category_id number Unique ID of the category
configs object Have subject as a key with value that is used as service request subject.
attachment_visibility boolean Set to True if requester is allowed to attach a file
cost number Cost of the item
cost_visibility boolean Set to True if cost should be visible to the requester
create_child boolean Applicable to bundles. Set to True if additional items needs to be created as child tickets.
deleted boolean Set to True if the item is deleted
delivery_time number Estimated delivery time of the item
delivery_time_visibility boolean Set to True if delivery time of the item should be visible to the requester
group_visibility number Set ‘1’ for visibility to all requesters. Set ‘2’ for restricted visibility.
visibility number Set ‘1’ for draft and ‘2’ for published.
icon_name string Name of the icon
package boolean Set to True for bundles
product_id number The ID of the product mapped to the item
quantity number Quantity needed by the requester
quantity_visibility boolean Set as True to allow the requester to request for more than 1 quantity
short_description string Short description of the item
description string Description of the item
created_at datetime The time at which the item was created
updated_at datetime The time at with the item was updated

Category fields

Attribute Type Description
id number Unique ID of the item
name string Name of the item
description string Description of the item
position number Display order
visibility number Set ‘1’ for draft and ‘2’ for published.
group_visibility number Set ‘1’ for visibility to all requesters. Set ‘2’ for restricted visibility.
created_date datetime The time at which the item was created
updated_date datetime The time at with the item was updated

Custom fields

Attribute Type Description
field_type string Type of field
item_id number ID of the item
label string Displayed label name
name string Stored label name
required boolean Set as True for mandatory field
visible_in_portal boolean Set as True to make this field visible only for agents.
Field Type in Custom Fields
custom_checkbox
custom_date
custom_decimal
custom_number
custom_text
nested_field

Create a service request

This API helps you create a service request with agent as requester

Note:
The service request will be created with the requester as “requester_email” if specified. If “requester_email” is not specified, then the service request will be created with Agent as Requester.

Note 2:
If a service item is not made visible to a requester and if that requester’s email is given in ‘requester_email’, then the Service Request will not get created.

post
/catalog/request_items/[item_display_id]/service_request.json
Request 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "requested_item_values":{
    "[item_display_id]":{
      "item_id":"123",
      "quantity":"3"
    },
    "[item_display_id]":{
      "item_id":"124",
      "requested_item_value_attributes":{
        "employee_name_124":"Sample",
        "role_124":"developer",
        "employee_email_id_124":"sample@yourcompany.com",
        "city_124":"new york"
      }
    }
  },
  "requested_for":"sample@yourcompany.com",
  "requester_email":"sample@yourcompany.com"
}
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
{
  "service_request":{
    "created_at":"2017-01-11T14:39:40+05:30",
    "deleted":false,
    "department_id_value":null,
    "display_id":2000,
    "due_by":"2017-01-12T14:39:40+05:30",
    "email_config_id":null,
    "frDueBy":"2017-01-12T13:39:40+05:30",
    "fr_escalated":false,
    "group_id":null,
    "id":200,
    "impact":1,
    "isescalated":false,
    "owner_id":null,
    "priority":2,
    "requester_id":1,
    "responder_id":null,
    "source":2,
    "spam":false,
    "status":2,
    "subject":"Request for Richard : Employee Onboarding",
    "ticket_type":"Service Request",
    "to_email":null,
    "updated_at":"2017-01-11T14:39:40+05:30",
    "urgency":1,
    "requested_catalog_items":[
      {
        "created_at":"2017-01-11T14:39:40+05:30",
        "id":203,
        "is_parent":true,
        "item_id":124,
        "quantity":1,
        "remarks":null,
        "service_request_id":200,
        "stage":1,
        "updated_at":"2017-01-11T14:39:40+05:30",
        "custom_field_values":{
          "employee_name_124":"Sample",
          "role_124":"developer",
          "employee_email_id_124":"sample@yourcompany.com",
          "city_124":"new york"
        }
      },
      {
        "created_at":"2017-01-11T14:39:40+05:30",
        "id":204,
        "is_parent":false,
        "item_id":123,
        "quantity":1,
        "remarks":null,
        "service_request_id":200,
        "stage":1,
        "updated_at":"2017-01-11T14:39:40+05:30",
        "custom_field_values":{

        }
      }
    ]
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST https://domain.freshservice.com/catalog/request_items/1/service_request.json -d '{ "requested_item_values": { "1": {"item_id": "1", "requested_item_value_attributes": {} },"31":{"item_id": "31"} }, "requested_for": "sample@yourcompany.com","requester_email": "sample@yourcompany.com" }'
EXPAND ↓

View all service items

This API helps you to view all the service items in your service desk.

Note:
The requests are paginated to return only 20 items per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

get
/catalog/items.json
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
[
  {
    "attachment_visibility":false,
    "category_id":7,
    "configs":null,
    "cost":null,
    "cost_visibility":null,
    "create_child":null,
    "created_at":"2016-10-07T17:12:54+05:30",
    "deleted":false,
    "delivery_time":null,
    "delivery_time_visibility":null,
    "description":"Request to process event registration",
    "display_id":23,
    "group_visibility":1,
    "icon_name":"service-catalog-event-registration",
    "id":23,
    "name":"Event Registration",
    "package":null,
    "product_id":null,
    "quantity":null,
    "quantity_visibility":null,
    "short_description":"Request to process event registration",
    "updated_at":"2016-10-07T17:12:54+05:30",
    "visibility":2
  },
  {
    "attachment_visibility":false,
    "category_id":3,
    "configs":{
      "subject":"Request for {{requested_for}} : {{item.name}}"
    },
    "cost":null,
    "cost_visibility":false,
    "create_child":false,
    "created_at":"2016-10-07T17:12:53+05:30",
    "deleted":false,
    "delivery_time":null,
    "delivery_time_visibility":false,
    "description":"Request for exit interview",
    "display_id":14,
    "group_visibility":1,
    "icon_name":"service-catalog-exit-interview",
    "id":14,
    "name":"Exit Interview",
    "package":true,
    "product_id":null,
    "quantity":null,
    "quantity_visibility":false,
    "short_description":"Request for exit interview",
    "updated_at":"2016-10-25T18:07:58+05:30",
    "visibility":2
  }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/catalog/items.json?page=2
EXPAND ↓

View all service categories

This API helps you to view all the service categories in your service desk.

get
/catalog/categories.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
  {
    "created_at":"2016-10-07T17:12:53+05:30",
    "description":"",
    "group_visibility":1,
    "id":1,
    "name":"Hardware Provisioning",
    "position":1,
    "updated_at":"2016-10-07T17:12:53+05:30",
    "visibility":2
  },
  {
    "created_at":"2016-10-07T17:12:53+05:30",
    "description":"desc",
    "group_visibility":1,
    "id":2,
    "name":"Software Installation",
    "position":2,
    "updated_at":"2016-12-21T11:57:23+05:30",
    "visibility":2
  }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/catalog/categories.json
EXPAND ↓

View all items in a Category

This API helps you to view all the service items in a particular category in your service desk.

Note:
The requests are paginated to return only 20 items per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

get
/catalog/categories/[category_id]/items.json
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
[
  {
    "attachment_visibility":false,
    "category_id":2,
    "configs":null,
    "cost":null,
    "cost_visibility":null,
    "create_child":null,
    "created_at":"2016-10-07T17:12:54+05:30",
    "deleted":false,
    "delivery_time":null,
    "delivery_time_visibility":null,
    "description":"Request for design software",
    "display_id":29,
    "group_visibility":1,
    "icon_name":"service-catalog-software-design-kit",
    "id":29,
    "name":"Design Software Kit",
    "package":true,
    "product_id":null,
    "quantity":null,
    "quantity_visibility":null,
    "short_description":"Request for design software",
    "updated_at":"2016-10-07T17:12:54+05:30",
    "visibility":2
  },
  {
    "attachment_visibility":false,
    "category_id":2,
    "configs":null,
    "cost":"499.0",
    "cost_visibility":true,
    "create_child":null,
    "created_at":"2016-10-07T17:12:53+05:30",
    "deleted":false,
    "delivery_time":24,
    "delivery_time_visibility":true,
    "description":"Microsoft Office 2013, a productivity suite for Microsoft Windows",
    "display_id":3,
    "group_visibility":1,
    "icon_name":"service-catalog-msoffice",
    "id":3,
    "name":"Microsoft Office 2013",
    "package":null,
    "product_id":null,
    "quantity":null,
    "quantity_visibility":true,
    "short_description":"Request a new MS Office license",
    "updated_at":"2016-10-07T17:12:53+05:30",
    "visibility":2
  }
]
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/catalog/categories/[category_id]/items.json?page=1
EXPAND ↓

View item details for a particular item

This API helps you to view the details of a service item in your service desk.

get
/catalog/items/[display_id].json
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
{
  "catalog_item":{
    "attachment_visibility":true,
    "category_id":1,
    "configs":{
      "subject":"Request for {{requested_for}} : {{item.name}}"
    },
    "cost":"1099.0",
    "cost_visibility":true,
    "create_child":false,
    "created_at":"2016-10-07T17:12:53+05:30",
    "deleted":false,
    "delivery_time":48,
    "delivery_time_visibility":true,
    "description":"<p>27-inch (diagonal) LED-backlit display with IPS technology</p><p>PRODUCT FEATURES</p><p>8GB (two 4GB) of 1600 MHz DDR3 memory</p><p>1TB (7200-rpm) hard drive</p><p>NVIDIA GeForce GT 755M graphics processor with 1GB of GDDR5 memory</p><p>FaceTime HD camera</p>",
    "display_id":12,
    "group_visibility":1,
    "icon_name":"service-catalog-apple-imac",
    "id":12,
    "name":"Apple iMac",
    "package":true,
    "product_id":null,
    "quantity":null,
    "quantity_visibility":true,
    "short_description":"Request for a new Apple iMac.",
    "updated_at":"2016-12-19T14:27:39+05:30",
    "visibility":2,
    "additional_item":[
      {
        "custom_fields":[

        ],
        "id":31,
        "mandatory":0,
        "name":"Adobe indesign"
      },
      {
        "custom_fields":[
          {
            "created_at":"2016-10-07T17:12:54+05:30",
            "deleted":false,
            "description":"",
            "field_type":"custom_dropdown",
            "id":24,
            "item_id":14,
            "label":"Department",
            "name":"department_14",
            "position":4,
            "required":true,
            "updated_at":"2016-10-07T17:12:54+05:30",
            "visible_in_portal":true,
            "choices":[
              [
                "HR",
                "HR"
              ],
              [
                "Marketing",
                "Marketing"
              ]
            ],
            "nested_fields":[

            ]
          },
          {
            "created_at":"2016-10-07T17:12:54+05:30",
            "deleted":false,
            "description":"",
            "field_type":"custom_date",
            "id":26,
            "item_id":14,
            "label":"End Date",
            "name":"end_date_14",
            "position":6,
            "required":true,
            "updated_at":"2016-10-07T17:12:54+05:30",
            "visible_in_portal":true,
            "choices":[

            ],
            "nested_fields":[

            ]
          },
          {
            "created_at":"2016-10-13T15:28:30+05:30",
            "deleted":false,
            "description":"",
            "field_type":"nested_field",
            "id":138,
            "item_id":14,
            "label":"Dpdnt1",
            "name":"dpdnt1_14",
            "position":9,
            "required":false,
            "updated_at":"2016-10-13T15:28:31+05:30",
            "visible_in_portal":true,
            "nested_field_choices":[
              [
                "category 1",
                "category 1",
                [
                  [
                    "subcategory 1",
                    "subcategory 1",
                    [
                      [
                        "item 1",
                        "item 1"
                      ],
                      [
                        "item 2",
                        "item 2"
                      ]
                    ]
                  ],
                  [
                    "subcategory 2",
                    "subcategory 2",
                    [
                      [
                        "item 1",
                        "item 1"
                      ],
                      [
                        "item 2",
                        "item 2"
                      ]
                    ]
                  ],
                  [
                    "subcategory 3",
                    "subcategory 3",
                    [

                    ]
                  ]
                ]
              ],
              [
                "category 2",
                "category 2",
                [
                  [
                    "subcategory 1",
                    "subcategory 1",
                    [
                      [
                        "item 1",
                        "item 1"
                      ],
                      [
                        "item 2",
                        "item 2"
                      ]
                    ]
                  ]
                ]
              ]
            ],
            "nested_fields":[
              {
                "created_at":"2016-10-13T15:28:31+05:30",
                "deleted":false,
                "description":"",
                "id":7,
                "item_field_id":138,
                "label":"level1",
                "level":2,
                "name":"level1_138",
                "updated_at":"2016-10-13T15:28:31+05:30"
              },
              {
                "created_at":"2016-10-13T15:28:31+05:30",
                "deleted":false,
                "description":"",
                "id":8,
                "item_field_id":138,
                "label":"l3",
                "level":3,
                "name":"l3_138",
                "updated_at":"2016-10-13T15:28:31+05:30"
              }
            ]
          }
        ],
        "id":14,
        "mandatory":0,
        "name":"Exit Interview"
      }
    ],
    "custom_fields":[
      {
        "created_at":"2016-10-13T20:17:43+05:30",
        "deleted":false,
        "description":"",
        "field_type":"custom_text",
        "id":139,
        "item_id":12,
        "label":"Mac details",
        "name":"mac_details_12",
        "position":2,
        "required":false,
        "updated_at":"2016-10-13T20:17:43+05:30",
        "visible_in_portal":true,
        "choices":[

        ],
        "nested_fields":[

        ]
      }
    ]
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshservice.com/catalog/items/[display_id].json
EXPAND ↓

Contracts

This section lists all the APIs that can be used to perform operations related to Contracts such as creating, viewing and managing approvals.

Attribute Type Description
id number Unique ID of the contract Read-Only
name string Subject/Title of the Contract Mandatory
contract_id number Unique Contract Number Mandatory
product_id number Product ID of software Mandatory for Software type
vendor_id number Vendor ID of the Contract Mandatory
contract_type number Number specifies Contract Type Mandatory
notify_expiry boolean 0 or 1 which specifies whether notification on expiry required or not
notify_before number Number which specifies days before when to notify
expiry_notified boolean 0 or 1 which specifies expiry notified already or not
to_emails Array of Strings List of email addresses to notify expiry
license_type number Type of software licenseMandatory for Software Type
display_id number Contract ID specific to your account Read-Only
description string Plain text content of the contract
description_html string HTML content of the contract
attachments array of objects Attached files of the contract

Notes

Contract Type

Description Value
Lease 1
Maintenance 2
Software license 3

Get the Custom Contract Type ID’s from ADMIN/Contract Types in portal.

License Type

Description Values
Open Source 1
Commercial 2

Notify Before

Possible Values in Days
7
30
60

Contract Renewal

This API lets you renew an existing Contract in your service desk.

In the contract life cycle, data in fields such as Product, Vendor and Notification Recipient are constant and are shown as contract attributes. Variables such as start date, end date and cost are stored as separate entities. The entities of a contract which are currently in effect are shown as current data attributes.

Attribute Type Description
id number Unique ID for each renewal Read-Only
contract_id number ID of contract to which renewal is associated to Mandatory
requester_id number User ID of the requester for renewal Mandatory for Software type
approver_id number Approval ID is user ID of approver who approves the contract Mandatory if approval required
license_count number Number of licenses count Mandatory for software type
status number Number which specifies contract statusRead-only
renewal_type number Number which specifies Type of renewal Renewal or Extension
cost decimal Cost of the Contract Mandatory
comments string Comments made on rejection Mandatory on Rejection
start_date datetime Start Date of the ContractMandatory
end_date datetime End Date of the Contract Mandatory
delegatee_id number Read only

Notes

Status(Read-Only)

Description Value
Draft 1
Pending 2
Approved 3
Active 4
Expired 5
Rejected 6
Cancelled 7
Pending_ESign 8
ESigned 9
Decline_ESign 10

Renewal Type

Description Values
Renewal 1
Extension 2

License Count Max value is 2147483647

Cost value has max value is 99999999.99

Create a contract

This API lets you create a new Contract in your service desk.

post
/cmdb/contracts.json
Request 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
   "cmdb_contract":{
      "name":"Contract Title",
      "contract_id":"CNTR-1234",
      "contract_type":1,
      "vendor_id":12345,
      "current_data_attributes":{
         "approver_id":12345,
         "cost":22,
         "start_date":"2016-12-13",
         "end_date":"2016-12-30"
      }
   }
}
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
{
   "success":true,
   "contract":{
      "contract":{
         "contract_id":"CNTR-1234",
         "contract_type":1,
         "created_at":"2016-12-06T10:29:56+05:30",
         "description":"Sample Description.",
         "display_id":3,
         "expiry_notified":false,
         "id":12345,
         "license_type":null,
         "name":"Contract Title",
         "notify_before":null,
         "notify_expiry":false,
         "product_id":null,
         "to_emails":null,
         "updated_at":"2016-12-06T10:29:56+05:30",
         "vendor_id":12345,
         "product_name":null,
         "type_name":"Lease",
         "vendor_name":"Sample Vendor Name",
         "license_type_name":null,
         "asset_ids":[

         ],
         "attachments":[

         ],
         "current_data":{
            "approver_id":12345,
            "comments":null,
            "cost":"22.0",
            "created_at":"2016-12-06T10:29:56+05:30",
            "delegatee_id":null,
            "end_date":"2016-12-30T23:59:59+05:30",
            "id":12345,
            "license_count":null,
            "renewal_type":null,
            "requester_id":12345,
            "start_date":"2016-12-13T00:00:00+05:30",
            "status":1,
            "updated_at":"2016-12-06T10:29:56+05:30",
            "approver_name":"Sample Approver Name",
            "requester_name":"Sample Requester Name",
            "status_name":"Draft",
            "renewal_type_name":null,
            "delegatee_name":null,
            "custom_field":{

            }
         }
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "cmdb_contract" : { "name" : "Contract Title" ,"contract_id": "CNTR-1234", "contract_type": 1, "vendor_id":12345 ,"current_data_attributes" : { "approver_id" : 12345, "cost" : 22, "start_date" : "2016-12-13", "end_date" : "2016-12-30"}}}' -X POST https://domain.freshservice.com/cmdb/contracts.json
EXPAND ↓

Create a contract with attachment

This API lets you create a new Contract with Attachments in your service desk.

post
/cmdb/contracts.json
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
{
  "success":true,
  "contract":{
    "contract":{
      "contract_id":"C13",
      "contract_type":1,
      "created_at":"2016-12-14T14:29:46+05:30",
      "description":"Sample Description.",
      "display_id":6,
      "expiry_notified":false,
      "id":12345,
      "license_type":null,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":null,
      "to_emails":null,
      "updated_at":"2016-12-14T14:29:46+05:30",
      "vendor_id":12345,
      "product_name":null,
      "type_name":"Lease",
      "vendor_name":"Sample Vendor Name",
      "license_type_name":null,
      "asset_ids":[

      ],
      "attachments":[
        {
          "content_content_type":"application/octet-stream",
          "content_file_name":"attachment.ext",
          "content_file_size":4086,
          "created_at":"2016-12-14T14:29:46+05:30",
          "id":12345,
          "updated_at":"2016-12-14T14:29:46+05:30",
          "attachment_url":"path/to/attachment"
        }
      ],
      "current_data":{
        "approver_id":12345,
        "comments":null,
        "cost":"123.0",
        "created_at":"2016-12-14T14:29:46+05:30",
        "delegatee_id":null,
        "end_date":"2017-12-02T23:59:59+05:30",
        "id":5000015054,
        "license_count":null,
        "renewal_type":null,
        "requester_id":12345,
        "start_date":"2016-12-01T00:00:00+05:30",
        "status":1,
        "updated_at":"2016-12-14T14:29:46+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Draft",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -F “cmdb_contract[attachments][][resource]=@/path/to/ attachment.ext” -F "cmdb_contract[name]=Contract Title" -F "cmdb_contract[contract_id]=C13" -F "cmdb_contract[contract_type]=1" -F "cmdb_contract[vendor_id]=12345" -F "cmdb_contract[current_data_attributes][approver_id]=12345" -F "cmdb_contract[current_data_attributes][start_date]=2016-12-1" -F "cmdb_contract[current_data_attributes][end_date]=2017-12-2" -F "cmdb_contract[current_data_attributes][cost]=123" -X POST https://domain.freshservice.com/cmdb/contracts.json
EXPAND ↓

Create a contract with asset/ci attachment

This API lets you create a new Contract with associated Assets (CIs) in your service desk.

post
/cmdb/contracts.json
Request 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "cmdb_contract":{
    "name":"Contract Title",
    "contract_id":"CNTR-1332222",
    "contract_items_attributes":{
      "item_ids":"12345"
    },
    "contract_type":1,
    "vendor_id":12345,
    "current_data_attributes":{
      "approver_id":"12345",
      "cost":"22",
      "start_date":"2016-09-13",
      "end_date":"2016-12-30"
    }
  }
}
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
{
  "success":true,
  "contract":{
    "contract":{
      "contract_id":"CNTR-1332222",
      "contract_type":1,
      "created_at":"2016-12-14T14:55:20+05:30",
      "description":"Sample Description.",
      "display_id":8,
      "expiry_notified":false,
      "id":12345,
      "license_type":null,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":null,
      "to_emails":null,
      "updated_at":"2016-12-14T14:55:20+05:30",
      "vendor_id":12345,
      "product_name":null,
      "type_name":"Lease",
      "vendor_name":"Sample Vendor Name",
      "license_type_name":null,
      "asset_ids":[
        12345
      ],
      "attachments":[

      ],
      "current_data":{
        "approver_id":12345,
        "comments":null,
        "cost":"22.0",
        "created_at":"2016-12-14T14:55:20+05:30",
        "delegatee_id":null,
        "end_date":"2016-12-30T23:59:59+05:30",
        "id":12345,
        "license_count":null,
        "renewal_type":null,
        "requester_id":12345,
        "start_date":"2016-09-13T00:00:00+05:30",
        "status":1,
        "updated_at":"2016-12-14T14:55:20+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Draft",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  }
}
EXPAND ↓
Sample code | Curl 
1
2
3
4
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "cmdb_contract" :
{ "name" : "Contract Title" ,"contract_id": "CNTR-1332222", "contract_items_attributes" :
{ "item_ids" : "12345" }, "contract_type": 1, "vendor_id": 12345 ,"current_data_attributes" :
{ "approver_id" : "12345", "cost" : "22", "start_date" : "2016-09-13", "end_date" : "2016-12-30"}}}' -X POST https://domain.freshservice.com/cmdb/contracts.json
EXPAND ↓

View a contract

This API lets you retrieve and view a specific contract and its properties.

get
/cmdb/contracts/[id].json
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
{
  "contract":{
    "contract_id":"C13",
    "contract_type":1,
    "created_at":"2016-12-14T14:29:46+05:30",
    "description":"Sample Description.",
    "display_id":6,
    "expiry_notified":false,
    "id":12345,
    "license_type":null,
    "name":"Contract Title",
    "notify_before":null,
    "notify_expiry":false,
    "product_id":null,
    "to_emails":null,
    "updated_at":"2016-12-14T14:29:46+05:30",
    "vendor_id":12345,
    "product_name":null,
    "type_name":"Lease",
    "vendor_name":"Sample Vendor Name",
    "license_type_name":null,
    "asset_ids":[

    ],
    "attachments":[
      {
        "content_content_type":"application/octet-stream",
        "content_file_name":"attachment.ext",
        "content_file_size":4086,
        "created_at":"2016-12-14T14:29:46+05:30",
        "id":12345,
        "updated_at":"2016-12-14T14:29:46+05:30",
        "attachment_url":"path/to/attachment.ext"
      }
    ],
    "current_data":{
      "approver_id":12345,
      "comments":null,
      "cost":"123.0",
      "created_at":"2016-12-14T14:29:46+05:30",
      "delegatee_id":null,
      "end_date":"2017-12-02T23:59:59+05:30",
      "id":12345,
      "license_count":null,
      "renewal_type":null,
      "requester_id":12345,
      "start_date":"2016-12-01T00:00:00+05:30",
      "status":1,
      "updated_at":"2016-12-14T14:29:46+05:30",
      "approver_name":"Sample Approver Name",
      "requester_name":"Sample Requester Name",
      "status_name":"Draft",
      "renewal_type_name":null,
      "delegatee_name":null,
      "custom_field":{

      }
    }
  }
}
EXPAND ↓
Sample code | Curl 
1
2
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://
domain.freshservice.com/cmdb/contracts/id.json
EXPAND ↓

View list of contracts

This API lets you retrieve a list of all contracts in your service desk.

Note:
All the listing requests and default and custom filters are paginated to return only 30 contracts per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.

Filter by Handle
Default filters: /cmdb/contracts/filter/[filter_name]?format=json
The various filters available are all, active, expired, lease, maintenance, software_license, expiry_range
Requester /helpdesk/tickets/filter/requester/[requester_id]?format=json
View All Contracts helpdesk/tickets.json
get
/cmdb/contracts.json
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
[
  {
    "contract":{
      "contract_id":"C13",
      "contract_type":1,
      "created_at":"2016-12-14T14:29:46+05:30",
      "description":"Sample Description.",
      "display_id":6,
      "expiry_notified":false,
      "id":12345,
      "license_type":null,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":null,
      "to_emails":null,
      "updated_at":"2016-12-14T14:29:46+05:30",
      "vendor_id":12345,
      "product_name":null,
      "type_name":"Lease",
      "vendor_name":"Sample Vendor Name",
      "license_type_name":null,
      "asset_ids":[

      ],
      "attachments":[
        {
          "content_content_type":"application/octet-stream",
          "content_file_name":"attachment.ext",
          "content_file_size":4086,
          "created_at":"2016-12-14T14:29:46+05:30",
          "id":12345,
          "updated_at":"2016-12-14T14:29:46+05:30",
          "attachment_url":"path/to/attachment.ext"
        }
      ],
      "current_data":{
        "approver_id":12345,
        "comments":null,
        "cost":"123.0",
        "created_at":"2016-12-14T14:29:46+05:30",
        "delegatee_id":null,
        "end_date":"2017-12-02T23:59:59+05:30",
        "id":12345,
        "license_count":null,
        "renewal_type":null,
        "requester_id":12345,
        "start_date":"2016-12-01T00:00:00+05:30",
        "status":1,
        "updated_at":"2016-12-14T14:29:46+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Draft",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  },
  {
    "contract":{
      "contract_id":"CNTR-5",
      "contract_type":3,
      "created_at":"2016-12-06T11:06:16+05:30",
      "description":"",
      "display_id":5,
      "expiry_notified":false,
      "id":12345,
      "license_type":1,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":12345,
      "to_emails":null,
      "updated_at":"2016-12-06T11:06:16+05:30",
      "vendor_id":12345,
      "product_name":"Sample Product Name",
      "type_name":"Software License",
      "vendor_name":"Name",
      "license_type_name":"Open Source",
      "asset_ids":[

      ],
      "attachments":[

      ],
      "current_data":{
        "approver_id":12345,
        "comments":null,
        "cost":"2222.0",
        "created_at":"2016-12-06T11:06:16+05:30",
        "delegatee_id":null,
        "end_date":"2016-12-29T23:59:59+05:30",
        "id":12345,
        "license_count":2222,
        "renewal_type":null,
        "requester_id":12345,
        "start_date":"2016-12-01T00:00:00+05:30",
        "status":1,
        "updated_at":"2016-12-06T11:06:16+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Draft",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  },
  {
    "contract":{
      "contract_id":"CNTR-4",
      "contract_type":2,
      "created_at":"2016-12-06T11:05:40+05:30",
      "description":"",
      "display_id":4,
      "expiry_notified":false,
      "id":12345,
      "license_type":null,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":null,
      "to_emails":null,
      "updated_at":"2016-12-06T11:05:40+05:30",
      "vendor_id":12345,
      "product_name":null,
      "type_name":"Maintenance",
      "vendor_name":"Sample Vendor Name",
      "license_type_name":null,
      "asset_ids":[

      ],
      "attachments":[

      ],
      "current_data":{
        "approver_id":12345,
        "comments":null,
        "cost":"94949.0",
        "created_at":"2016-12-06T11:05:40+05:30",
        "delegatee_id":null,
        "end_date":"2016-12-28T23:59:59+05:30",
        "id":12345,
        "license_count":null,
        "renewal_type":null,
        "requester_id":12345,
        "start_date":"2016-12-01T00:00:00+05:30",
        "status":1,
        "updated_at":"2016-12-06T11:05:40+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Draft",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  },
  {
    "contract":{
      "contract_id":"CNTR-2134",
      "contract_type":1,
      "created_at":"2016-12-06T10:29:56+05:30",
      "description":"Sample Description.",
      "display_id":3,
      "expiry_notified":false,
      "id":12345,
      "license_type":null,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":null,
      "to_emails":null,
      "updated_at":"2016-12-06T10:38:52+05:30",
      "vendor_id":12345,
      "product_name":null,
      "type_name":"Lease",
      "vendor_name":"Sample Vendor Name",
      "license_type_name":null,
      "asset_ids":[

      ],
      "attachments":[

      ],
      "current_data":{
        "approver_id":12345,
        "comments":"Some details on rejection...",
        "cost":"24.0",
        "created_at":"2016-12-06T10:29:56+05:30",
        "delegatee_id":null,
        "end_date":"2016-12-30T23:59:59+05:30",
        "id":5000013923,
        "license_count":null,
        "renewal_type":null,
        "requester_id":12345,
        "start_date":"2016-12-13T00:00:00+05:30",
        "status":6,
        "updated_at":"2016-12-06T10:42:49+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Rejected",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  },
  {
    "contract":{
      "contract_id":"CNTR-123",
      "contract_type":1,
      "created_at":"2016-12-05T17:09:19+05:30",
      "description":"Sample Description.",
      "display_id":2,
      "expiry_notified":false,
      "id":12345,
      "license_type":null,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":null,
      "to_emails":null,
      "updated_at":"2016-12-05T17:09:19+05:30",
      "vendor_id":12345,
      "product_name":null,
      "type_name":"Lease",
      "vendor_name":"Sample Vendor Name",
      "license_type_name":null,
      "asset_ids":[

      ],
      "attachments":[

      ],
      "current_data":{
        "approver_id":12345,
        "comments":null,
        "cost":"22.0",
        "created_at":"2016-12-05T17:09:19+05:30",
        "delegatee_id":null,
        "end_date":"2016-09-30T23:59:59+05:30",
        "id":12345,
        "license_count":null,
        "renewal_type":null,
        "requester_id":12345,
        "start_date":"2016-09-13T00:00:00+05:30",
        "status":5,
        "updated_at":"2016-12-05T17:09:19+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Expired",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  },
  {
    "contract":{
      "contract_id":"CNTR-1",
      "contract_type":3,
      "created_at":"2016-12-05T12:29:05+05:30",
      "description":"Sample Description.",
      "display_id":1,
      "expiry_notified":false,
      "id":12345,
      "license_type":2,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":12345,
      "to_emails":null,
      "updated_at":"2016-12-05T12:29:05+05:30",
      "vendor_id":12345,
      "product_name":"Sample Product Name",
      "type_name":"Software License",
      "vendor_name":"Sample Vendor Name",
      "license_type_name":"Commercial",
      "asset_ids":[

      ],
      "attachments":[

      ],
      "current_data":{
        "approver_id":12345,
        "comments":null,
        "cost":"6990.0",
        "created_at":"2016-12-05T12:29:05+05:30",
        "delegatee_id":null,
        "end_date":"2017-12-05T22:29:59+05:30",
        "id":12345,
        "license_count":10,
        "renewal_type":null,
        "requester_id":5000251250,
        "start_date":"2016-12-05T05:30:00+05:30",
        "status":4,
        "updated_at":"2016-12-05T12:29:05+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Active",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  }
]
EXPAND ↓
Sample code | Curl 
1
2
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://
domain.freshservice.com/cmdb/contracts?format=json&page=1
EXPAND ↓

Update a contract

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

put
/cmdb/contracts/id.json
Request 
1
2
3
4
5
6
7
8
9
10
11
12
{
  "cmdb_contract":{
    "name":"Contract Title",
    "contract_id":"CNTR-2134",
    "current_data_attributes":{
      "id":12345,
      "cost":24,
      "start_date":"2016-12-13",
      "end_date":"2016-12-30"
    }
  }
}
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
{
  "success":true,
  "contract":{
    "contract":{
      "contract_id":"CNTR-2134",
      "contract_type":1,
      "created_at":"2016-12-06T10:29:56+05:30",
      "description":"Sample Description.",
      "display_id":3,
      "expiry_notified":false,
      "id":12345,
      "license_type":null,
      "name":"Contract Title",
      "notify_before":null,
      "notify_expiry":false,
      "product_id":null,
      "to_emails":null,
      "updated_at":"2016-12-06T10:32:57+05:30",
      "vendor_id":12345,
      "product_name":null,
      "type_name":"Lease",
      "vendor_name":"Sample Vendor Name",
      "license_type_name":null,
      "asset_ids":[

      ],
      "attachments":[

      ],
      "current_data":{
        "approver_id":12345,
        "comments":null,
        "cost":"24.0",
        "created_at":"2016-12-06T10:29:56+05:30",
        "delegatee_id":null,
        "end_date":"2016-12-30T23:59:59+05:30",
        "id":12345,
        "license_count":null,
        "renewal_type":null,
        "requester_id":12345,
        "start_date":"2016-12-13T00:00:00+05:30",
        "status":1,
        "updated_at":"2016-12-06T10:32:57+05:30",
        "approver_name":"Sample Approver Name",
        "requester_name":"Sample Requester Name",
        "status_name":"Draft",
        "renewal_type_name":null,
        "delegatee_name":null,
        "custom_field":{

        }
      }
    }
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -d '{ "cmdb_contract" : { "name" : "Contract Title" ,"contract_id": "CNTR-2134","current_data_attributes" : { "id" : 12345, "cost" : 24, "start_date" : "2016-12-13", "end_date" : "2016-12-30"}}}' -X PUT https://domain.freshservice.com/cmdb/contracts/id.json
EXPAND ↓

Submit for approval

This API lets you send a contract for approval in your service desk.

put
/cmdb/contracts/id/submit_for_approval.json
Response 
1
2
3
4
{
  "success":true,
  "message":"Contract Title was submitted for approval."
}
EXPAND ↓
Sample code | Curl 
1
2
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT https://
domain.freshservice.com/cmdb/contracts/id/submit_for_approval.json
EXPAND ↓

Approve a contract

This API lets you approve a contract that was sent for approval in your service desk.

put
/cmdb/contracts/id/approve.json
Response 
1
2
3
4
{
  "success":true,
  "message":"Contract Approved !"
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT https:// domain.freshservice.com/cmdb/contracts/id/approve.json
EXPAND ↓

Reject a contract

This API lets you reject a contract that was sent for approval in your service desk.

put
/cmdb/contracts/id/reject.json
Request 
1
2
3
4
5
{
  "cmdb_contract":{
    "comments":"Some details on rejection ..."
  }
}
EXPAND ↓
Response 
1
2
3
4
{
  "success":true,
  "message":"Contract Rejected !"
}
EXPAND ↓
Sample code | Curl 
1
curl -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{"cmdb_contract" : {"comments" : "Some details on rejection ..."}}' https:// domain.freshservice.com/cmdb/contracts/id/reject.json
EXPAND ↓

This documentation is for the v1.0 APIs. The documentation for the beta version of the v2.0 APIs is available here.