API Reference

Overview

The Freshdesk API

Freshdesk'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 helpdesk.

What can I do with the Freshdesk API?

With the APIs, you can

Read
  1. Browse through tickets, customers - their details and satisfaction ratings.
  2. Apply Filters and get only the data that you want
  3. View topics and arguments in forums.
Write
  1. Create new tickets or users and modify the details of existing ones.
  2. Track the minutes you spend on tickets; Add time entries and start/stop timers.
  3. 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.freshdesk.com/path/to/api.(json|xml)

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

http://domain.freshdesk.com/path/to/api.(json|xml)

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.

Freshdesk 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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/helpdesk/tickets.json

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

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

curl -v -u abcdefghij1234567890:X -H "Content-Type: application/json" -X GET https://domain.freshdesk.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:
http://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 Freshdesk portal "thelocker.freshdesk.com", then to access contacts in your helpdesk, the syntax would be
http://www.thelocker.freshdesk.com/contacts.json
 For tickets, it would be
http://www.thelocker.freshdesk.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 http://yourdomain.freshdesk.com/helpdesk/tickets

What API commands are used by Freshdesk?

Freshdesk APIs have been implemented as plain XML or 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 Freshdesk profile. If your Freshdesk 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, Freshdesk 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@freshdesk.com for further queries.

Code Samples

Code samples for accessing Freshdesk API in various languages including Ruby, PHP, Java, C# are available in the Fresh Samples GitHub project. Third-party wrapper libraries and code samples are listed in the THIRD_PARTY.md document.

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 Freshdesk, it will be added as a new contact. Mandatory
phone † number Phone number of the requester. If no contact exists with this phone number in Freshdesk, it will be added as a new contact. name is a mandatory attribute if phone number is given.Mandatory
twitter_id † string Twitter id of the requester. If no contact exists with this twitter_id in Freshdesk, it will be added as a new contact.Mandatory
name string Name of the requester. If no contact exists with the above mentioned email address in Freshdesk, it will be added as a new contact with this name. Name of the existing contact won't be overwritten by this name.
requester_id number User-id of the requester. For existing contacts, requester_id can be passed instead of email.
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 string Type property field as defined in ticket fields.
cc_emails 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
custom_field dictionary Key value pair of custom field name and value. Read more here.
* Refer Ticket properties table for supported values.
† Any of the three attributes is mandatory if requester doesn't exist in Freshdesk.

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 or user_id of the customer who is adding the note. Read more here to find user_id of an agent.
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
source number Type of the note (2 -> Note, 4 -> Meta info)

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
Forum 4
Twitter 5
Facebook 6
Chat 7
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 help 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":"tom@outerspace.com",
      "priority":1,
      "status":2
  },
  "cc_emails":"ram@freshdesk.com,diana@freshdesk.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" : {
    "cc_email" : {
      "cc_emails" : [
        "ram@freshdesk.com",
        "diana@freshdesk.com"
      ],
      "fwd_emails" : [ ]
    },
    "created_at" : "2014-01-07T18:48:33+05:30",
    "deleted" : false,
    "delta" : true,
    "description" : "Some details on the...",
    "description_html" : "<div>Some details on the...</div>",
    "display_id" : 141,
    "due_by" : "2014-01-10T17:00:00+05:30",
    "email_config_id" : null,
    "frDueBy" : "2014-01-08T17:00:00+05:30",
    "fr_escalated" : false,
    "group_id" : null,
    "id" : 141,
    "isescalated" : false,
    "notes" : [ ],
    "owner_id" : null,
    "priority" : 1,
    "requester_id" : 18,
    "responder_id" : null,
    "source" : 2,
    "spam" : false,
    "status" : 2,
    "subject" : "Support needed..",
    "ticket_type" : "Question",
    "to_email" : null,
    "trained" : false,
    "updated_at" : "2014-01-07T18:48:33+05:30",
    "urgent" : false,
    "status_name" : "Open",
    "requester_status_name" : "Being Processed",
    "priority_name" : "Low",
    "source_name" : "Portal",
    "requester_name" : "tom",
    "responder_name" : "No Agent",
    "product_id" : 123456,
    "to_emails" : null,
    "custom_field" : {
      "weapon_1" : "Laser Gun"
    },
    "attachments" : [ ],
    "tags":[
         {"name": "tag1"},
         {"name": "tag2"}
    ]
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -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@freshdesk.com,diana@freshdesk.com" }' -X POST https://domain.freshdesk.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.freshdesk.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.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
{  
   "helpdesk_ticket":{  
      "cc_email":{  
         "cc_emails":[  

         ],
         "fwd_emails":[  

         ]
      },
      "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,
      "notes":[  

      ],
      "owner_id":null,
      "priority":1,
      "requester_id":8888589,
      "responder_id":null,
      "source":2,
      "spam":false,
      "status":2,
      "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,
      "attachments":[  
         {  
            "content_content_type":"image/jpeg",
            "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.freshdesk.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.freshdesk.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 helpdesk.

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
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
   "helpdesk_ticket":{
      "cc_email":{
         "cc_emails":[
            "ram@freshdesk.com",
            "diana@freshdesk.com"
            ],
         "fwd_emails":[]
      },
      "created_at":"2014-01-07T14:57:55+05:30",
      "deleted":false,
      "delta":true,
      "description":"Details on the issue ...",
      "description_html":"<div>Details on the issue ...</div>",
      "display_id":138,
      "due_by":"2014-01-10T14:57:55+05:30",
      "email_config_id":null,
      "frDueBy":"2014-01-08T14:57:55+05:30",
      "fr_escalated":false,
      "group_id":null,
      "id":138,
      "isescalated":false,
      "notes":[
        {
          "note": {
            "body": "Note body",
            "body_html": "\u003cdiv\u003eNote body\u003c/div\u003e",
            "created_at": "2014-07-31T16:34:25+05:30",
            "deleted": false,
            "id": 4009113846,
            "incoming": false,
            "private": true,
            "source": 2,
            "updated_at": "2014-07-31T16:34:25+05:30",
            "user_id": 8888589,
            "attachments": []
          }
        }
      ],
      "owner_id":null,
      "priority":1,
      "requester_id":17,
      "responder_id":null,
      "source":2,
      "spam":false,
      "status":2,
      "subject":"Support Needed...",
      "ticket_type":"Problem",
      "to_email":null,
      "trained":false,
      "updated_at":"2014-01-07T15:53:21+05:30",
      "urgent":false,
      "status_name":"Open",
      "requester_status_name":"Being Processed",
      "priority_name":"Low",
      "source_name":"Portal",
      "requester_name":"Test",
      "responder_name":"No Agent",
      "product_id":123456,
      "to_emails":null,
      "custom_field":{
         "weapon_1":"Laser Gun"
         },
      "attachments":[],
      "tags":[
         {"name": "tag1"},
         {"name": "tag2"}
      ]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json"  -X GET https://domain.freshdesk.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("http://yourcompany.freshdesk.com/helpdesk/tickets.json?page=1","user@yourcompany.com","test")

#view specific tickets
site = RestClient::Resource.new("https://domain.freshdesk.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 help 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
Predefined filters /helpdesk/tickets/filter/[filter_name]?format=json
The various filters available are all_tickets, new_and_my_open, monitored_by, spam, deleted
Default filter /helpdesk/tickets.json
Uses the new_and_my_open filter.
Requester /helpdesk/tickets/filter/requester/[requester_id]?format=json
Custom ticket views /helpdesk/tickets/view/[view_id]?format=json
Company name /helpdesk/tickets.json?company_name=[name]&filter_name=all_tickets
Company id /helpdesk/tickets.json?company_id=[id]&filter_name=all_tickets
Requester email /helpdesk/tickets.json?email=[email]&filter_name=all_tickets
View all tickets /helpdesk/tickets/filter/all_tickets?format=json
Sort by Handle
created_at, due_by, updated_at, priority, status /helpdesk/tickets/filter/[filter_name]?format=json&wf_order=created_at
Default sort order is created_at
Supports all the above filter handles except custom ticket views
asc, desc /helpdesk/tickets/filter/[filter_name]?format=json&wf_order_type=asc
Default sort order type is desc
Supports all the above filter handles except custom ticket views
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
[{
      "cc_email":{
         "cc_emails":[
            "ram@freshdesk.com",
            "diana@freshdesk.com"
            ],
         "fwd_emails":[]
      },
      "created_at":"2014-01-07T14:57:55+05:30",
      "deleted":false,
      "delta":true,
      "description":"Details on the issue ...",
      "description_html":"<div>Details on the issue ...</div>",
      "display_id":138,
      "due_by":"2014-01-10T14:57:55+05:30",
      "email_config_id":null,
      "frDueBy":"2014-01-08T14:57:55+05:30",
      "fr_escalated":false,
      "group_id":null,
      "id":138,
      "isescalated":false,
      "owner_id":null,
      "priority":1,
      "requester_id":17,
      "responder_id":null,
      "source":2,
      "spam":false,
      "status":2,
      "subject":"Support Needed...",
      "ticket_type":"Problem",
      "to_email":null,
      "trained":false,
      "updated_at":"2014-01-07T15:53:21+05:30",
      "urgent":false,
      "status_name":"Open",
      "requester_status_name":"Being Processed",
      "priority_name":"Low",
      "source_name":"Portal",
      "requester_name":"Test",
      "responder_name":"No Agent",
      "product_id":123456,
      "to_emails":null,
      "custom_field":{
         "weapon_1":"Laser Gun"
      }
}]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET "https://domain.freshdesk.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("http://yourcompany.freshdesk.com/helpdesk/tickets.json?page=1","user@yourcompany.com","test")

#view specific tickets
site = RestClient::Resource.new("https://domain.freshdesk.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
10
11
12
{
  "helpdesk_ticket" : {
    "priority" : 1,
    "status" : 2,
    "custom_field" : {
      "weapon_1" : "Laser Gun"
    }
  },
  "helpdesk" : {
    "tags" : "csv1,csv2"
  }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "ticket" : {
    "deleted" : false,
    "display_id" : 141,
    "subject" : "freshdesk test",
    "status_name" : "Pending",
    "requester_status_name" : "Awaiting your Reply",
    "priority_name" : "High",
    "source_name" : "Portal",
    "requester_name" : "freshdesk",
    "responder_name" : "Support",
    "to_emails" : null
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "helpdesk_ticket": { "priority":1, "status":2 }}' https://domain.freshdesk.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 "http://yourcompany.domain.com/helpdesk/tickets/ticketid.json" [REST standards for update]
site = RestClient::Resource.new("https://domain.freshdesk.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 ↓

Pick a Ticket

This API helps you to pick a particular ticket.

put
/helpdesk/tickets/[id]/pick_tickets.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[
   {
      "ticket":{
         "deleted":false,
         "display_id":138,
         "subject":"test",
         "status_name":"Open",
         "requester_status_name":"Being Processed",
         "priority_name":"Low",
         "source_name":"Portal",
         "requester_name":"tom",
         "responder_name":"Support",
         "to_emails":null
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json"  -X PUT -d '' https//:domain.freshdesk.com/helpdesk/tickets/1/pick_tickets.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

#you can also use apikey instead of user/passwd

#The current user will pick the ticket
site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/tickets/[ticket_id]/pick_tickets.json","user@yourcompany.com","test")

response=site.put(:content_type=>"application/json")

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

Delete a Ticket

This API helps you delete a ticket.

Note:
Rest assured though. Tickets aren't cast into the fiery volcanic Mount Doom. You can always retrieve them using the Restore Ticket API.

delete
/helpdesk/tickets/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json"  -X DELETE https://domain.freshdesk.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.freshdesk.com/helpdesk/tickets/#{value}.json","user@yourcompany.com","test")
response = site.delete(:accept=>"application/json")
puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Restore a Ticket

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

put
/helpdesk/tickets/[id]/restore.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[
  {
    "ticket":{
      "deleted":false,
      "display_id":135,
      "subject":"Support Needed...",
      "status_name":"Open",
      "requester_status_name":"Being Processed",
      "priority_name":"Low",
      "source_name":"Portal",
      "requester_name":"tom",
      "responder_name":"No Agent",
      "to_emails":null
    }
  }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '' https://domain.freshdesk.com/helpdesk/tickets/1/restore.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"

#here you need to specify the ticket id as part of the URL 
# eg: "http://yourcompany.domain.com/helpdesk/tickets/123/restore.json"

site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/tickets/[ticket_id]/restore.json","user@yourcompany.com","test")

#status property is mandatory.
response = site.put({},:content_length=>0)

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

Assign a Ticket

To assign a ticket to one of your agents, use this API.

put
/helpdesk/tickets/[id]/assign.json?responder_id=[user_id]
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[
   {
      "ticket":{
         "deleted":false,
         "display_id":138,
         "subject":"Support Needed...",
         "status_name":"Open",
         "requester_status_name":"Being Processed",
         "priority_name":"Low",
         "source_name":"Portal",
         "requester_name":"tom",
         "responder_name":"Support",
         "to_emails":null
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json"  -X PUT -d '' https://domain.freshdesk.com/helpdesk/tickets/1/assign.json?responder_id=1
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 user_id of the agent to whom this ticket is to be assigned.
site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/tickets/[ticket_id]/assign.json?responder_id=[user_id]","user@yourcompany.com","test")

#status property is mandatory.
response = site.put({},:content_length=>0)

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

Get all Ticket Fields

This API lets you view the fields in a ticket.

Note:
The API key / user id used to execute this API call should have privileges to view the ticket fields.

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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.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.freshdesk.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":"<div>Hi tom, Still Angry</div>",
      "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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "helpdesk_note": { "body":"Hi tom, Still Angry", "private":false }}' https://domain.freshdesk.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.freshdesk.com/helpdesk/tickets/[ticket_id]/conversations/note.json',"user@yourcompany.com","test")
# site = RestClient::Resource.new('http://mycompany.freshdesk.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":"image/jpeg",
            "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.freshdesk.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.freshdesk.com/helpdesk/tickets/[id]/conversations/note.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.
twitter_id string Twitter id of the user.
fb_profile_id string Facebook id 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.
customer_id number ID of the company to which this user belongs.
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 verified.Read-Only
external_id number Internal usage. Read-Only
avatar_attributes[content] object Avatar of the user.
custom_field dictionary Key value pair of custom field name and value. Read more here.
* 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
/contacts.json
Request 
1
2
3
4
5
6
{
  "user":{ 
    "name":"Super Man",
    "email":"ram@freshdesk.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
{
   "user":{
      "active":false,
      "address":null,
      "created_at":"2014-01-07T19:33:43+05:30",
      "customer_id":null,
      "deleted":false,
      "description":null,
      "email":"ram@freshdesk.com",
      "external_id":null,
      "fb_profile_id":null,
      "id":19,
      "job_title":null,
      "language":"en",
      "mobile":null,
      "name":"Super Man",
      "phone":null,
      "time_zone":"Hawaii",
      "twitter_id":null,
      "updated_at":"2014-01-07T19:33:43+05:30",
      "custom_field" : {
         "cf_department" : null,
         "cf_date_of_joining": null
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "user": { "name":"Super Man", "email":"ram@freshdesk.com" }}' https://domain.freshdesk.com/contacts.json
EXPAND ↓
Sample code | Ruby 
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
require "rubygems"
require "net/http"  

uri = URI.parse("https://domain.freshdesk.com/contacts.xml")

    
request = Net::HTTP::Post.new(uri.request_uri)


#replace your user/passwd or the apiKey
  request.basic_auth("user@yourcompany.com","test")


#Set the content type.p
  request['Content-Type']='application/xml'

connection = Net::HTTP.new(uri.host,uri.port)

  #needed only if ssl is enabled
  #connection.use_ssl = true
    #connection.verify_mode = OpenSSL::SSL::VERIFY_NONE


post_data = Hash.new

#The set_form_data does not parse the xml content, and it recognizes only the Map datatype. So either we can parse the xml and construct...
# the map data or we can directly set the data as mentioned below

post_data["user[name]"]='Valluvar'
post_data["user[email]"]='valluvar@tamilnadu.com'


request.set_form_data(post_data)
response= connection.request(request)

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

Create User With Avatar

This API helps you create new users with thier cool avatars. The Email and Name parameters are mandatory though

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

post
/contacts.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
{
   "user":{
      "active":false,
      "address":null,
      "created_at":"2014-01-07T19:33:43+05:30",
      "customer_id":null,
      "deleted":false,
      "description":null,
      "email":"ram@freshdesk.com",
      "external_id":null,
      "fb_profile_id":null,
      "id":19,
      "job_title":null,
      "language":"en",
      "mobile":null,
      "name":"Super Man",
      "phone":null,
      "time_zone":"Hawaii",
      "twitter_id":null,
      "updated_at":"2014-01-07T19:33:43+05:30",
      "custom_field" : {
         "cf_department" : null,
         "cf_date_of_joining": null
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -F "user[name]=Super Man" -F "user[email]=ram@freshdesk.com" -F "user[avatar_attributes][content]=@/path/to/profile_pic.ext" -X POST https://domain.freshdesk.com/contacts.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.freshdesk.com/contacts.json","sample@freshdesk.com","test")

#avatar_attributes is the property to set the image file.
response = site.post({:user=>{:name=>"newcustomer1", :email=>"newcustomer1@freshdesk.com", :avatar_attributes=>{:content=>File.open("mypic.jpg")}},:content_type=>"application/json"})

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

View a User

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

get
/contacts/[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
{
   "user":{
      "active":false,
      "address":null,
      "created_at":"2014-01-07T19:33:43+05:30",
      "customer_id":null,
      "deleted":false,
      "description":null,
      "email":"ram@freshdesk.com",
      "external_id":null,
      "fb_profile_id":null,
      "id":19,
      "job_title":null,
      "language":"en",
      "mobile":null,
      "name":"Super Man",
      "phone":null,
      "time_zone":"Hawaii",
      "twitter_id":null,
      "updated_at":"2014-01-07T19:33:43+05:30",
      "custom_field" : {
         "cf_department" : "IT",
         "cf_date_of_joining": "2014-12-01T00:00:00Z"
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/contacts/19.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"

#contacts can also be filtered by phone,email etc

#state can be of type [verified/unverified/all/deleted]

site=RestClient::Resource.new("https://yourcompany.freshdesk.com/contacts.json?state=all","user@yourcompany.com","test")

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

puts "response: #{response.code} \n #{response.body}"
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 /contacts.json?query=<condition>
Example:
/contacts.json?query=email is user@yourcompany.com
[Note: Do an url encode of the query string]
state /contacts.json?state=[state]
i.e., [verified/unverified/all/deleted]
Filter contacts by name /contacts?letter=[letter]
Example:
/contacts.json?letter=tom
get
/contacts.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
[
   {
      "user": {
         "active":false,
         "address":"",
         "created_at":"2013-12-20T15:04:16+05:30",
         "customer_id":null,
         "deleted":false,
         "description":"",
         "email":"ram@freshdesk.com",
         "external_id":null,
         "fb_profile_id":null,
         "helpdesk_agent":false,
         "id":19,
         "job_title":"Super Hero",
         "language":"en",
         "mobile":"",
         "name":"Super Man",
         "phone":"",
         "time_zone":"Hawaii",
         "twitter_id":"",
         "updated_at":"2013-12-20T15:04:16+05:30",
         "custom_field" : {
            "cf_department" : "Admin",
            "cf_date_of_joining": "2014-12-01T00:00:00Z"
         }
      }
   },
   {
      "user": {
         "active":false,
         "address":"",
         "created_at":"2013-12-20T15:04:16+05:30",
         "customer_id":null,
         "deleted":false,
         "description":"",
         "email":"tom@freshdesk.com",
         "external_id":null,
         "fb_profile_id":null,
         "helpdesk_agent":false,
         "id":18,
         "job_title":"Front Line",
         "language":"en",
         "mobile":"",
         "name":"tom",
         "phone":"",
         "time_zone":"Chennai",
         "twitter_id":"",
         "updated_at":"2013-12-20T15:04:16+05:30",
         "custom_field" : {
            "cf_department" : "IT",
            "cf_date_of_joining": "2014-12-01T00:00:00Z"
         }
      }
   },
   ...
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/contacts.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
require "rubygems"
require "rest_client"
require "json"

#contacts can also be filtered by phone,email etc

params = URI.escape("query=phone is 123245890")

puts "#{params}"

#state can be of type [verified/unverified/all/deleted]

site=RestClient::Resource.new("http://yourcompany.freshdesk.com/contacts.json?#{params}&state=all","user@yourcompany.com","test")

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

puts "response: #{response.code} \n #{response.body}"
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
/contacts/[id].json
Request 
1
2
3
4
5
6
{
  "user": { 
    "name":"Robin",
    "job_title":"Super Hero"
  }
}
EXPAND ↓
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "user": { "name":"Robin", "job_title":"Super Hero" }}' https://domain.freshdesk.com/contacts/19.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

# eg:
#site = RestClient::Resource.new("http://mycompany.freshdesk.com/contacts/5123.json","user@yourcompany.com","test")
site = RestClient::Resource.new("https://domain.freshdesk.com/contacts/[user_id].json","user@yourcompany.com","test")

# response = site.put({:user=>{:name=>"newname",:customer_id=>8}},:content_type=>"application/json")

response = site.put({:user=>{:name=>"newname",:email=>"newmail@abc.com"}},:content_type=>"application/json")
puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Delete a User

This API lets you delete a user.

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

# eg:
#site = RestClient::Resource.new("http://mycompany.freshdesk.com/contacts/5123.json","user@yourcompany.com","test")
site = RestClient::Resource.new("https://domain.freshdesk.com/contacts/[user_id].json","user@yourcompany.com","test")

response = site.delete(:accept=>"application/json")
puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Make Agent

API to convert a contact to agent.

Note:
1. The contact must have an email id to be converted to an agent.
2. If the max limit of agent count is reached for your account plan, the API will fail with HTTP error code 400.
3. The API key / user id used to execute this API call should have privileges to convert a contact to agent.

put
/contacts/[id]/make_agent.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
{  
      "agent":{  
         "active_since":null,
         "available":true,
         "created_at":"2015-01-02T22:56:39-10:00",
         "id":19,
         "occasional":false,
         "points":0,
         "scoreboard_level_id":1,
         "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":4,
            "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"
         },
         "user_id":4
      }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT https://domain.freshdesk.com/contacts/[id]/make_agent.json
EXPAND ↓

Get all Contact Fields

This API lets you view the fields in a contact.

Note:
The API key / user id used to execute this API call should have privileges to view the contact fields.

get
/admin/contact_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
[  
   {  
      "contact_field":{  
         "choices":[  

         ],
         "created_at":"2014-12-12T12:29:46+05:30",
         "deleted":false,
         "editable_in_portal":true,
         "editable_in_signup":true,
         "field_options":null,
         "field_type":"default_name",
         "id":1,
         "label":"Full Name",
         "label_in_portal":"Full Name",
         "name":"name",
         "position":1,
         "required_for_agent":true,
         "required_in_portal":true,
         "updated_at":"2014-12-12T12:29:46+05:30",
         "visible_in_portal":true
      }
   },
   {  
      "contact_field":{  
         "choices":[  

         ],
         "created_at":"2015-01-05T16:07:28+05:30",
         "deleted":false,
         "editable_in_portal":true,
         "editable_in_signup":false,
         "field_options":null,
         "field_type":"custom_text",
         "id":14,
         "label":"Department_id",
         "label_in_portal":"Department_id",
         "name":"cf_department_id",
         "position":2,
         "required_for_agent":false,
         "required_in_portal":false,
         "updated_at":"2015-01-05T16:07:28+05:30",
         "visible_in_portal":true
      }
   },
   ...
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/admin/contact_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.freshdesk.com/admin/contact_fields.json","user@yourcompany.com","test")

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

puts "response: #{response.code} \n #{response.body}"
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
34
35
36
{  
      "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":4,
            "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"
         },
         "user_id":4
      }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/agents/19.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("http://yourcompany.freshdesk.com/agents/1.json","user@yourcompany.com","test")

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

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

View All Agents

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]
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
71
72
73
74
[  
   {  
      "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"
         },
         "user_id":2
      }
   },
   {  
      "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,
            "fb_profile_id":null,
            "helpdesk_agent":true,
            "id":1,
            "job_title":"Agent",
            "language":"en",
            "mobile":"",
            "name":"Bumblebee",
            "phone":"",
            "time_zone":"Chennai",
            "twitter_id":null,
            "updated_at":"2015-01-16T22:21:48-10:00"
         },
         "user_id":1
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/agents.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
require "rubygems"
require "rest_client"
require "json"

#contacts can also be filtered by phone,email etc

params = URI.escape("query=phone is 123245890")

puts "#{params}"

site=RestClient::Resource.new("http://yourcompany.freshdesk.com/agents.json?#{params}","user@yourcompany.com","test")

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

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

Companies

This section lists APIs that help you to deal with the companies a.k.a customers that you do business with.

Attribute Type Description
id number Unique id of the customer. Read-Only
name string Name of the customer. Mandatory
description string Description of the customer.
domains string Domains of the company. Email addresses of contacts that contain this domain will be associated with that company automatically.
note string Any specific note about the customer.
sla-policy-id number ID of the SLA associated with the contact.
custom_field dictionary Key value pair of custom field name and value. Read more here.
cust-identifier number Internal usage. Read-Only

Create Customer

Companies can hold multiple contacts. This API lets you create a new company.

post
/customers.json
Request 
1
2
3
4
5
6
7
{
  "customer":{
    "name":"SuperNova",
    "domains":"supernova,nova",
    "description":"Spaceship Manufacturing Company"
  }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "customer":{
      "created_at":"2014-01-08T09:08:53+05:30",
      "cust_identifier":null,
      "description":"Spaceship Manufacturing Company",
      "domains":"supernova,nova",
      "id":8,
      "name":"SuperNova",
      "note":null,
      "sla_policy_id":1,
      "updated_at":"2014-01-08T09:08:53+05:30",
      "custom_field" : {
         "cf_industry": null,
         "cf_account_created_date": null
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "customer":{ "name":"SuperNova", "domains":"supernova,nova", "description":"Spaceship Manufacturing Company" }}' https://domain.freshdesk.com/customers.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

#you can also use apikey instead of user/passwd
# site = RestClient::Resource.new("http://yourcompany.domain.com/customers.json","user@yourcompany.com","test")
site = RestClient::Resource.new("https://domain.freshdesk.com/customers.json","user@yourcompany.com","test")

# only name is mandatory for the customers. 
response = site.post({:customer=>{:name=>"abcd",:domains=>"abcd",:description=>"My new company"},:content_type=>"application/json"})

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

Update Customer

You can modify a company's details. To do so, use this API. For a list of all parameters that can be modified, see the table given above.

put
/customers/[id].json
Request 
1
2
3
4
5
6
7
{
  "customer":{
    "name":"Super Nova",
    "domains":"supernova,nova,super",
    "description":"Space Shuttle Manufacturing"
  }
}
EXPAND ↓
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "customer": { "name":"Super Nova", "domains":"supernova,nova,super", "description":"Space Shuttle Manufacturing" }}' https://domain.freshdesk.com/customers/8.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

#you can also use apikey instead of user/passwd
# site = RestClient::Resource.new("http://yourcompany.domain.com/customers/[id].json","user@yourcompany.com","test")
site = RestClient::Resource.new("https://domain.freshdesk.com/customers/14.json","user@yourcompany.com","test")

# only name is mandatory for the customers. 
response = site.put({:customer=>{:note=>"ISO 9001 Company",:domains=>"abcde",:description=>"East Coast, USA"},:content_type=>"application/json"})

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

View Customer

To view a particular company amongst all in the roster, use this API

get
/customers/[id].json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "customer":{
      "created_at":"2014-01-08T09:08:53+05:30",
      "cust_identifier":null,
      "description":"Spaceship Manufacturing Company",
      "domains":"supernova,nova",
      "id":8,
      "name":"SuperNova",
      "note":null,
      "sla_policy_id":1,
      "updated_at":"2014-01-08T09:08:53+05:30",
      "custom_field" : {
         "cf_industry": "Galactic",
         "cf_account_created_date": "2014-12-01T00:00:00Z"
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/customers/8.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"

#you can also use apikey instead of user/passwd

#to view all customers 
# site = RestClient::Resource.new("http://yourcompany.domain.com/customers.json","user@yourcompany.com","test")

#to view specific customers
# site = RestClient::Resource.new("http://yourcompany.domain.com/customers/[id].json","user@yourcompany.com","test")
site = RestClient::Resource.new("https://domain.freshdesk.com/customers/3.json","user@yourcompany.com","test")

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

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

View List Of Customers

To view all the companies in your list, use this API.

Use filters to view based on the matching criteria

Filter by Handle
Filter company by name. /customers.json?letter=[:string]
get
/customers.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
[
   {
      "customer":{
         "created_at":"2014-01-08T09:08:53+05:30",
         "cust_identifier":null,
         "description":"Space Shuttle Manufacturing",
         "domains":"supernova,nova",
         "id":8,
         "name":"Super Nova",
         "note":null,
         "sla_policy_id":1,
         "updated_at":"2014-01-08T09:08:53+05:30",
         "custom_field" : {
            "cf_industry": "Galactic",
            "cf_account_created_date": "2014-12-01T00:00:00Z"
         }
      }
   },
   {
      "customer":{
         "created_at":"2014-01-08T09:08:53+05:30",
         "cust_identifier":null,
         "description":"Ship Building Company",
         "domains":"poseidon",
         "id":9,
         "name":"Poseidon",
         "note":null,
         "sla_policy_id":1,
         "updated_at":"2014-01-08T09:08:53+05:30",
         "custom_field" : {
            "cf_industry": "Ship Building",
            "cf_account_created_date": "2014-12-01T00:00:00Z"
         }
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/customers.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"

#you can also use apikey instead of user/passwd

#to view all customers 
# site = RestClient::Resource.new("http://yourcompany.domain.com/customers.json","user@yourcompany.com","test")

#to view specific customers
# site = RestClient::Resource.new("http://yourcompany.domain.com/customers/[id].json","user@yourcompany.com","test")
site = RestClient::Resource.new("https://domain.freshdesk.com/customers/3.json","user@yourcompany.com","test")

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

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

Delete Customer

To delete a company, use this API

Note:
Deleting a company does not delete the customers inside it. Only disbands the company. Once disbanded, the company will stay disbanded. You cannot restore it.

delete
/customers/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshdesk.com/customers/1.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("http://yourcompany.domain.com/customers/[id].json","user@yourcompany.com","test")
site = RestClient::Resource.new("https://domain.freshdesk.com/customers/5123.json","user@yourcompany.com","test")

response = site.delete(:accept=>"application/json")
puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Get all Company Fields

This API lets you view the fields in a company.

Note:
The API key / user id used to execute this API call should have privileges to view the company fields.

get
/admin/company_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
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
[  
   {  
      "company_field":{  
         "choices":[  

         ],
         "created_at":"2014-12-12T12:29:46+05:30",
         "deleted":false,
         "field_options":null,
         "field_type":"default_name",
         "id":1,
         "label":"Company name",
         "name":"name",
         "position":1,
         "required_for_agent":true,
         "updated_at":"2014-12-12T12:29:46+05:30"
      }
   },
   {  
      "company_field":{  
         "choices":[  

         ],
         "created_at":"2014-12-12T12:29:46+05:30",
         "deleted":false,
         "field_options":null,
         "field_type":"default_description",
         "id":2,
         "label":"Description",
         "name":"description",
         "position":2,
         "required_for_agent":false,
         "updated_at":"2014-12-12T12:29:46+05:30"
      }
   },
   {  
      "company_field":{  
         "choices":[  

         ],
         "created_at":"2014-12-12T12:29:46+05:30",
         "deleted":false,
         "field_options":null,
         "field_type":"default_note",
         "id":3,
         "label":"Notes",
         "name":"note",
         "position":3,
         "required_for_agent":false,
         "updated_at":"2014-12-12T12:29:46+05:30"
      }
   },
   {  
      "company_field":{  
         "choices":[  

         ],
         "created_at":"2014-12-12T12:29:46+05:30",
         "deleted":false,
         "field_options":null,
         "field_type":"default_domains",
         "id":4,
         "label":"Domain Names for this company",
         "name":"domains",
         "position":4,
         "required_for_agent":false,
         "updated_at":"2014-12-12T12:29:46+05:30"
      }
   },
   {  
      "company_field":{  
         "choices":[  

         ],
         "created_at":"2015-01-05T15:57:55+05:30",
         "deleted":false,
         "field_options":null,
         "field_type":"custom_text",
         "id":5,
         "label":"Category",
         "name":"cf_category",
         "position":5,
         "required_for_agent":false,
         "updated_at":"2015-01-05T15:57:55+05:30"
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/admin/company_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.freshdesk.com/admin/company_fields.json","user@yourcompany.com","test")

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

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

Forum Category

With these APIs, you can keep peace between the various warring factions in your forums. You create new topics of discussion, respond to old posts and monitor certain topics for the insights they might provide.

Attribute Type Description
id number Unique id of the forum category Read-Only
name string Name of the forum categoryMandatory Unique
description string Description of the forum category
position number The rank of the category in the category listing Read-Only

Forum Properties

Forum Type Value
How To 1
Ideas 2
Problems 3
Announcements 4
Forum Visibility Value
Anyone 1
Logged in Users 2
Agents 3
Topic Stamp Value
Planned 1
Implemented 2
Taken 3

Create Forum Category

To create a new category for discussions in your forums, use this API.

post
/discussions/categories.json
Request 
1
2
3
4
5
6
{
   "forum_category":{
      "name":"How to",
      "description":"Queries on How to ?"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
{
   "forum_category":{
      "created_at":"2014-01-08T06:38:11+05:30",
      "description":"Getting Started",
      "id":3,
      "name":"How to",
      "position":3,
      "updated_at":"2014-01-08T06:38:11+05:30"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "forum_category": { "name":"How to", "description":"Getting Started" }}' https://domain.freshdesk.com/discussions/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.freshdesk.com/discussions/categories.json","user@yourcompany.com","test")

response = site.post({:forum_category=>{:name=>"testing",:description=>"test"}},:content_type=>"application/json")

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

Update Forum Category

To update an existing category, such as change the name of a category or its description, use this API. For a list of all modifiable parameters, look at this

put
/discussions/categories/[id].json
Request 
1
2
3
4
5
6
{
   "forum_category":{
      "name":"Report Problems",
      "description":"Tell us your problems"
   }
}
EXPAND ↓
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
2
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "forum_category": { "name":"Report Problems", "description":"Tell us your problems" }}' 
https://domain.freshdesk.com/discussions/categories/3.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.freshdesk.com/discussions/categories/3.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/categories/[forum_category_id].json","user@yourcompany.com","test")

response = site.put({:forum_category=>{:name=>"testinge forum",:description=>"testupdates"}},:content_type=>"application/json")

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

View Forum Category

To view a specific category in your forums, use this API

get
/discussions/categories/[id].json
Response 
1
2
3
4
5
6
7
8
9
10
11
{
  "forum_category":{
     "created_at":"2014-01-08T06:38:11+05:30",
     "description":"Recently Changed",
     "id":2,
     "name":"Latest Updates",
     "position":4,
     "updated_at":"2014-01-08T06:38:11+05:30",
     "forums": []
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/discussions/categories/2.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
require "rubygems"
require "rest_client"
require "json"

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

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

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

View All Forum Category

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

get
/discussions/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
[
   {
      "forum_category":{
         "created_at":"2014-01-08T06:38:11+05:30",
         "description":"Tell us your problems",
         "id":3,
         "name":"Report Problems",
         "position":3,
         "updated_at":"2014-01-08T06:38:11+05:30"
      }
   },
   {
      "forum_category":{
         "created_at":"2014-01-08T06:38:11+05:30",
         "description":"Recently Changed",
         "id":2,
         "name":"Latest Updates",
         "position":4,
         "updated_at":"2014-01-08T06:38:11+05:30"
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/discussions/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.freshdesk.com/discussions/categories.json","user@yourcompany.com","test")

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

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

Delete Forum Category

To delete a category, use this API.

delete
/discussions/categories/[id].json
Response 
1
2
3
4
5
6
7
8
9
10
{
   "forum_category":{
      "created_at":"2014-01-08T06:38:11+05:30",
      "description":"How to Queries",
      "id":3,
      "name":"How and What?",
      "position":null,
      "updated_at":"2014-01-08T07:13:56+05:30"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshdesk.com/discussions/categories/3.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.freshdesk.com/discussions/categories/2.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/categories/[forum_category_id].json","user@yourcompany.com","test")

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

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

Forum

This set of APIs will let you create, update and delete forums inside each forum category.

Attribute Type Description
id number Unique id of the forum Read-Only
name string Name of the forum Mandatory Unique
description string Description about the forum
forum_category_id number ID of the category of this forum Mandatory
forum_type number Describes the type of forum (Supported types can be referred in Forum properties above )Mandatory
forum_visibility number Describes whether the forum is visible to all or logged in user or Agents or selected companies Mandatory
position number The rank of the forum in the forum listing
posts_count number The number of comments on that forum
topics_count number The number of topics in the forum

Create Forum

To Create a Forum in a particular category, use this API.

post
/discussions/forums.json
Request 
1
2
3
4
5
6
7
8
9
{
   "forum": {
      "description":"Ticket related functions",
      "forum_type":2,
      "forum_category_id":1,
      "forum_visibility":1,
      "name":"Ticket Operations"
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
   "forum":{
      "description":"Ticket related functions",
      "description_html":"\u003Cp\u003ETicket related functions\u003C/p\u003E",
      "forum_category_id":1,
      "forum_type":2,
      "forum_visibility":1,
      "id":2,
      "name":"Ticket Operations",
      "position":5,
      "posts_count":0,
      "topics_count":0
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "forum": { "description": "Ticket related functions", "forum_category_id":1, "forum_type":2, "forum_visibility":1, "name":"Ticket Operations" }}' https://domain.freshdesk.com/discussions/forums.json
EXPAND ↓

Update Forum

To make changes to a forum, such as change forum type or name or (any of these other parameters), use this API.

put
/discussions/forums/[id].json
Request 
1
2
3
4
5
6
7
{
  "forum": {
    "description":"Tickets and Ticket fields related queries",
    "forum_type":2,
    "forum_visibility":1
  }
}
EXPAND ↓
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "forum": { "description":"Tickets and Ticket fields related queries", "forum_type":2, "forum_visibility":1 }}' https://domain.freshdesk.com/discussions/forums/2.json
EXPAND ↓

View Forum

This API lets you view a specific forum.

get
/discussions/forums/[id].json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
   "forum":{
      "description":"Ticket related functions",
      "description_html":"\u003Cp\u003ETicket related functions\u003C/p\u003E",
      "forum_category_id":1,
      "forum_type":2,
      "forum_visibility":1,
      "id":2,
      "name":"Ticket Operations",
      "position":5,
      "posts_count":0,
      "topics_count":0,
      "topics":[]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/discussions/forums/2.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.freshdesk.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 ↓

Delete Forum

You can delete forums using this API.

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

Topic

This set of APIs will let you create, update and delete topics inside each forum.

Attribute Type Description
id number Unique id of the topic Read-Only
title string Title of the topic Mandatory
body_html string Message body of the topic Mandatory
forum_id number ID of the Forum in which this topic is present Mandatory
hits number Number of views of that topic Read-Only
last_post_id number ID of the latest comment on the topic Read-Only
locked boolean Set as true if the topic is locked Mandatory
Posts_count number Number of posts in that topic
sticky number Set as 1 if the topic should stay on top of the forum for additional visibilityMandatory
user_id number ID of the user Read-Only
user_votes number Number of votes in the topic Read-Only
replied_at datetime Timestamp of the latest comment made in the topic Read-Only
replied_by datetime Id of the user who made the latest comment in that topic Read-Only

Create Topic

To create a topic in a forum category, use this API.

post
/discussions/topics.json
Request 
1
2
3
4
5
6
7
8
9
{
  "topic": {
    "sticky":0, 
    "locked":0,
    "forum_id":5,
    "title":"how to create a custom field",
    "body_html":"Can someone give me the steps..."
  }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
   "topic":{
      "account_id":1,
      "created_at":"2014-01-08T08:54:01+05:30",
      "delta":true,
      "forum_id":5,
      "hits":0,
      "id":3,
      "import_id":null,
      "last_post_id":null,
      "locked":false,
      "posts_count":0,
      "replied_at":"2014-01-08T08:54:01+05:30",
      "replied_by":null,
      "stamp_type":null,
      "sticky":0,
      "title":"how to create a custom field",
      "updated_at":"2014-01-08T08:54:01+05:30",
      "user_id":1,
      "user_votes":0
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "topic": { "sticky":0, "locked":0, "forum_id":5, "title":"how to create a custom field", "body_html":"Can someone give me the steps ..." }}' https://domain.freshdesk.com/discussions/topics.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
require "rubygems"
require "rest_client"
require "json"

#Need to specify category_id and forum_id in url
#eg:
#site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/topics.json","user@yourcompany.com","test")

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

#set sticky and locked to be true or false with 1 or 0

response = site.post({:topic=>{:sticky=>0,:locked=>0,:forum_id=>5,:title=>"test topic for freshdesk",:body_html=>"This is the first topic in this post"}},:content_type=>"application/json")

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

Update Topic

To update a topic within forum, be it changing the title of the forum or its status from "Locked" to "Open" for comments, use this API

put
/discussions/topics/[id].json
Request 
1
2
3
4
5
6
7
8
{
  "topic":{
    "sticky":0,
    "locked":0,
    "title":"How to create a new ticket field",
    "body_html": "Steps: Go to Admin tab ..."
  }
}
EXPAND ↓
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "topic": { "sticky":0, "locked":0, "title":"How to create a new ticket field", "body_html":"Steps: Go to Admin tab ..." }}' https://domain.freshdesk.com/discussions/topics/3.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
require "rubygems"
require "rest_client"
require "json"

# Need to specify category_id,forum_id,topic_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/topics/1.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/topics/[topic_id].json","user@yourcompany.com","test")

#set sticky and locked to be true or false with 1 or 0

response=site.put({:topic=>{:sticky=>0,:locked=>1,:title=>"testing topic",:body_html=>"This is the first topic in this post"}},:content_type=>"application/json")

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

View Topic

To view a particular topic in a forum and all conversations in that thread, use this API.

get
/discussions/topics/[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
{
   "topic":{
      "account_id":1,
      "created_at":"2014-01-08T08:54:01+05:30",
      "delta":true,
      "forum_id":5,
      "hits":0,
      "id":3,
      "import_id":null,
      "last_post_id":9,
      "locked":false,
      "posts_count":0,
      "replied_at":"2014-01-08T08:54:01+05:30",
      "replied_by":1,
      "stamp_type":null,
      "sticky":0,
      "title":"How to create a ticket field",
      "updated_at":"2014-01-08T08:54:01+05:30",
      "user_id":1,
      "user_votes":0,
      "posts":[
         {
            "account_id":1,
            "answer":false,
            "body":"Steps: Go to Admin tab ...",
            "body_html":"Steps: Go to Admin tab ...",
            "created_at":"2014-01-08T08:54:01+05:30",
            "forum_id":5,
            "id":9,
            "import_id":null,
            "topic_id":3,
            "updated_at":"2014-01-08T08:54:01+05:30",
            "user_id":1
         }
      ]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/discussions/topics/3.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,forum_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/topics/3.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/topics/[topic_id].json","user@yourcompany.com","test")

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

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

Delete Topic

To delete a particular topic of conversation from the forums, use this API. Word of warning though, deleted posts cannot be brought back to life.

delete
/discussions/topics/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshdesk.com/discussions/topics/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,forum_id,topic_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/topics/4.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/categories/discussions/topics/[topic_id].json","user@yourcompany.com","test")

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

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

Post

You can post your opinions on a forum or delete posts using these APIs

Attribute Type Description
id number Unique ID of the post or comment Read-Only
body string Content of the post in plaintext
body_html string Content of the post in HTML. You can pass either body or body_html Mandatory
forum_id number ID of the forum where the comment was posted
topic_id number ID of the topic where the comment was posted
user_id number ID of the user who posted the comment Read-Only

Create Post

If you wish to post your opinions about a topic in the forums, use this API.

post
/discussions/topics/[id]/posts.json
Request 
1
2
3
4
5
{
  "post": { 
    "body_html":"What type of ticket field you are creating"
    }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "post": {
    "answer": false,
    "body": "What type of ticket field you are creating",
    "body_html": "What type of ticket field you are creating",
    "created_at": "2014-02-07T12:32:34+05:30",
    "forum_id": 1,
    "id": 12,
    "topic_id": 2,
    "updated_at": "2014-02-07T12:32:34+05:30",
    "user_id": 1
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "post": { "body_html":"What type of ticket field you are creating" }}' https://domain.freshdesk.com/discussions/topics/[topic_id]/posts.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 forum_id,category_id,topic_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/topics/2/posts.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/topics/[topic_id]/posts.json","user@yourcompany.com","test")

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

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

Update Post

If you wish to make changes to your post, edit your reply and so on,this API will be useful.

put
/discussions/topics/[id]/posts/[id].json
Request 
1
2
3
4
5
{
  "post": { 
    "body_html":"Ticket field have different types ..." 
    }
}
EXPAND ↓
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "post": { "body_html": "Ticket field have different types ..." }}' https://domain.freshdesk.com/topics/2/posts/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 post_id,forum_id,category_id,topic_id
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/topics/2/posts/1.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/topics/[topic_id]/posts/[post_id].json","user@yourcompany.com","test")

response=site.put({:post=>{:body_html=>"123"}},:content_type=>"application/json")

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

Delete Post

If you wish to delete a topic of conversation and pretend it never happened, well, you can with this API.

delete
/discussions/topics/[id]/posts/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshdesk.com/discussions/topics/1/posts/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 post_id,forum_id,category_id,topic_id in url 
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/topics/4/posts/6.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/topics/[topic_id]/posts/[post_id].json","user@yourcompany.com","test")

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

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

Monitor Topic

It can be a discussion about a much wanted feature or about a tiny bug that could grow into something more. Whatever it may be, this API will help you keep an eye on those topics of "special interest".

post
/discussions/topic/[id]/subscriptions/follow.json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '' "https://domain.freshdesk.com/discussions/topic/1/subscriptions/follow.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,forum_id,topic_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/categories/2/forums/5/topics/1/monitorship.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/categories/[category_id]/forums/[forum_id]/topics/[topic_id]/monitorship.json","user@yourcompany.com","test")

response=site.post(:content_type=>"application/json")

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

Unmonitor Topic

This API lets you stop monitoring a topic.

post
/discussions/topic/[id]/subscriptions/unfollow.json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '' "https://domain.freshdesk.com/discussions/topic/1/subscriptions/unfollow.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,forum_id,topic_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/categories/2/forums/5/topics/1/monitorship.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/categories/[category_id]/forums/[forum_id]/topics/[topic_id]/monitorship.json","user@yourcompany.com","test")

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

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

Monitor Forum

It can be a forum about a much wanted feature sets or about bugs that could grow into something more. Whatever it may be, this API will help you keep an eye on those forums of "special interest".

post
/discussions/forum/[id]/subscriptions/follow.json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '' "https://domain.freshdesk.com/discussions/forum/1/subscriptions/follow.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,forum_id,topic_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/forum/1/subscriptions/follow.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/forum/[forum_id]/subscriptions/follow.json","user@yourcompany.com","test")

response=site.post(:content_type=>"application/json")

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

Unmonitor Forum

This API lets you stop monitoring a forum.

post
/discussions/forum/[id]/subscriptions/unfollow.json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '' "https://domain.freshdesk.com/discussions/forum/1/subscriptions/unfollow.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,forum_id,topic_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/forum/1/subscriptions/unfollow.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.com/discussions/forum/[forum_id]/subscriptions/unfollow.json","user@yourcompany.com","test")

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

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

View Monitored Topics

This Api allows you to fetch the topics monitored by the user

Note:
Only admin can fetch topics for other users. If user_id is not mentioned, the apiKey or user/password passed for the api call will be taken as the user.

get
/support/discussions/user_monitored.json?user_id=[id]
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[{
  "topic": {
    "account_id":16699,
    "created_at":"2013-10-16T17:58:59+05:30",
    "delta":true,
    "forum_id":68251,
    "hits":4,
    "id":35774,
    "import_id":12345,
    "last_post_id":84456,
    "locked":false,
    "posts_count":3,
    "published":true,
    "replied_at":"2013-10-16T18:03:09+05:30",
    "replied_by":1218912,
    "stamp_type":9,
    "sticky":0,
    "title":"Ticket creation",
    "updated_at":"2013-10-16T17:58:59+05:30",
    "user_id":1218912,
    "user_votes":0
    }
}]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/support/discussions/user_monitored.json?user_id=1218912"
EXPAND ↓

Monitoring Status For Topic

This Api allows you to check whether the topic is monitored by the user.

Note:
1. If user_id is not mentioned, the apiKey or user/password passed for the api call will be taken as the user for whom the monitor status is to be checked.
2. Only admin can check monitoring status for other users.

get
/discussions/topic/[id]/subscriptions/is_following.json?user_id=[id]
Response 
1
2
3
4
5
6
7
8
9
{
  "monitorship": { 
    "active":false,
    "id":18112,
    "monitorable_id":15483,
    "monitorable_type":"Topic",
    "user_id":1791107
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/discussions/topic/14583/subscriptions/is_following.json?user_id=1791107"
EXPAND ↓

Monitoring Status For Forum

This Api allows you to check whether the forum is monitored by the user.

Note:
1. If user_id is not mentioned, the apiKey or user/password passed for the api call will be taken as the user for whom the monitor status is to be checked.
2. Only admin can check monitoring status for other users.

get
/discussions/forum/[id]/subscriptions/is_following.json?user_id=[id]
Response 
1
2
3
4
5
6
7
8
9
{
  "monitorship": { 
    "active":false,
    "id":18112,
    "monitorable_id":15481,
    "monitorable_type":"Forum",
    "user_id":1791107
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/discussions/forum/14581/subscriptions/is_following.json?user_id=1791107"
EXPAND ↓

Solution Category

The Solution APIs allow you to perform all activities related to the creation and publishing of solutions to your customers. 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 Unique
description string Description about the solution category
position number The rank of the solution category in the category listing
is_default boolean Set as true if the category is a default one

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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "solution_category": { "name":"API", "description":"API related documents" }}' https://domain.freshdesk.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.freshdesk.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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "solution_category": { "name":"Rest API" }}' https://domain.freshdesk.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.freshdesk.com/solution/categories/6.json","user@yourcompany.com","test")

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

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

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

View Solution Category

To view all the categories available in your helpdesk, 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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.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.freshdesk.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.freshdesk.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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.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.freshdesk.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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshdesk.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.freshdesk.com/solution/categories/4.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.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 Unique
description string Description of the solution folder
position number Describes the position in which the folder is listed
is_default boolean Set as true is it is a default folder
category_id number ID of the category under which the folder is listed
visibility number Accessibility of this folder Mandatory
customer_folder_attributes[ ].customer_id number ID of the companies 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
Company Specific Users 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
{
   "solution_folder": {
      "name":"Ticket API",
      "visibility":1,
      "description":"Ticket CRUD Operations"
   }
}
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":1
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "solution_folder": {"name":"Ticket API", "visibility":1, "description":"Ticket CRUD Operations" }}' https://domain.freshdesk.com/solution/categories/4/folders.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
require "rubygems"
require "rest_client"
require "json"

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

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

#visibility : 1 = All, 2 = Logged in Users, 3 = Agents, 4 = Select Companies [need to provide customer_ids for this option]

response = site.post({:solution_folder=>{:name=>"test topic",:visibility=>4,:customer_folders_attributes=>{:customer_id=>[1,2]},:description=>"This is a new topic"}},:content_type=>"application/json")

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

Update Solution Folder

To update details of your solutions, 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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT '{ "solution_folder": { "visibility":1, "description":"Tickets API related Operations" }}' https://domain.freshdesk.com/solution/categories/4/folders/6.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
require "rubygems"
require "rest_client"
require "json"

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

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

#visibility : 1 = All, 2 = Logged in Users, 3 = Agents, 4 = Select Companies [need to provide customer_ids for this option]

response = site.put({:solution_folder=>{:name=>"test folder1",:visibility=>1,:description=>"This is a new folder"}},:content_type=>"application/json")

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

View Solution Folder

To view folder, and list all the articles in the folder.

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
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
{
  "folder" : {
    "category_id" : 5000082621,
    "created_at" : "2014-11-24T14:24:20+05:30",
    "description" : "Folder description",
    "id" : 5000129957,
    "is_default" : true,
    "name" : "Drafts",
    "position" : 1,
    "updated_at" : "2014-11-24T14:24:20+05:30",
    "visibility" : 3,
    "articles" : [
      {
        "art_type" : 1,
        "created_at" : "2014-11-25T12:09:30+05:30",
        "delta" : true,
        "desc_un_html" : " Description \r\n",
        "description" : "<p>Description</p>\r\n",
        "folder_id" : 5000129957,
        "hits" : 0,
        "id" : 5000511709,
        "modified_at" : "2014-11-25T12:09:30+05:30",
        "position" : 1,
        "seo_data" : {
          "meta_title" : "",
          "meta_description" : "",
          "meta_keywords" : ""
        },
        "status" : 1,
        "thumbs_down" : 0,
        "thumbs_up" : 0,
        "title" : "sdsad",
        "updated_at" : "2014-11-25T12:09:30+05:30",
        "user_id" : 5003080780
      },
      {
        "art_type" : 1,
        "created_at" : "2014-11-25T12:30:40+05:30",
        "delta" : true,
        "desc_un_html" : " \r\n",
        "description" : "<p><br></p>\r\n",
        "folder_id" : 5000129957,
        "hits" : 0,
        "id" : 5000511723,
        "modified_at" : "2014-11-25T12:30:40+05:30",
        "position" : 2,
        "seo_data" : {
          "meta_title" : "",
          "meta_description" : "",
          "meta_keywords" : ""
        },
        "status" : 1,
        "thumbs_down" : 0,
        "thumbs_up" : 0,
        "title" : "testadmin",
        "updated_at" : "2014-11-25T12:30:40+05:30",
        "user_id" : 5003058637
      }
    ]
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/solution/categories/[id]/folders/[id].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.freshdesk.com/solution/categories/4.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.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 ↓

View All Solution Folders

To view all folders present, 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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.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.freshdesk.com/solution/categories/4.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.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 solutions. 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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshdesk.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.freshdesk.com/solution/categories/6/folders/8.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.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
34
{
   "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":1,
      "id":2,
      "position":1,
      "seo_data":{},
      "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":1,
         "is_default":false,
         "name":"Ticket API",
         "position":1,
         "updated_at":"2014-01-08T15:10:40+05:30",
         "visibility":1,
         "customer_folders":[]
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -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.freshdesk.com/solution/categories/1/folders/1/articles.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"

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

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

#Status: 1-Draft,2-Published  
#art_type: 1-Permanent,2-Workaround

response = site.post({:solution_article=>{:title=>"test title",:status=>1,:art_type=>2,:description=>"Testing",:folder_id=>5,:attachments=>{''=>[{:resource=>File.new("/document.rtf", 'rb')}]}}},:content_type=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
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
7
8
9
{
  "solution_article": {
    "title":"Steps to create a ticket",
    "description":"Steps: 1. Fill in the mandatory fields ..."
  },
  "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
34
35
36
{ 
  "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",
      "customer_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,
    "seo_data" : {
      "meta_description" : "",
      "meta_keywords" : "",
      "meta_title" : ""
    },
    "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 -v -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.freshdesk.com/solution/categories/3/folders/7/articles/3.json?tags[name]=test
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"

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

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

#Status: 1-Draft,2-Published  
#art_type: 1-Permanent,2-Workaround

response = site.put({:solution_article=>{:title=>"updated article",:status => 1,:art_type => 1, :description => "Testing",:folder_id=>4}},:content_type=>"application/json")

puts "response: #{response.code} \n #{response.body} \n"
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
36
{
   "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,
      "seo_data":{},
      "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,
         "customer_folders":[

         ]
      }
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET  https://domain.freshdesk.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.freshdesk.com/solution/categories/1813/folders/3216/articles/1355.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.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
32
{
   "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,
            "seo_data":{},
            "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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET  https://domain.freshdesk.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.freshdesk.com/solution/categories/1/folders/2.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.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 -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE  https://domain.freshdesk.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.freshdesk.com/solution/categories/4/folders/5/articles/1.json","user@yourcompany.com","test")

site = RestClient::Resource.new("https://domain.freshdesk.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 ↓

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.

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
customer_name string The customer name in the response from the ticket_id Read-Only
contact_email string The requester email in the response from the ticket_id Read-Only

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
/helpdesk/tickets/[ticket_id]/time_sheets.json
Request 
1
2
3
4
5
6
7
{ 
   "time_entry": {
      "note": "Invoice Prepartion",
      "hhmm": 10.40,
      "user_id": 1
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "time_entry":{
      "agent_email":"user@yourcompany.com",
      "agent_name":"Support",
      "billable":true,
      "contact_email":"ram@freshdesk.com",
      "created_at":"2013-12-18T19:32:51+05:30",
      "customer_name":"Poseidon",
      "executed_at":"2013-12-18T19:32:51+05:30",
      "id":2,
      "note":"Invoice Preparation",
      "start_time":"2013-12-18T19:32:51+05:30",
      "ticket_id":41,
      "timer_running":false,
      "timespent":"10.40",
      "updated_at":"2013-12-18T19:32:51+05:30",
      "user_id":1,
      "workable_type":"Helpdesk::Ticket"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "time_entry": {"note":"Invoice Prepartion", "hhmm":10.40, "user_id":1 }}' https://domain.freshdesk.com/helpdesk/tickets/41/time_sheets.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/tickets/[ticket_id]/time_sheets.json","user@yourcompany.com","test")

#default billable =false
#user_id can be any of your agent's user_id. this is the only mandatory attribute.
#hhmm can be used to set a time spent, setting this will by default disable timer_running to false. 
response = site.post({:time_entry=>{:user_id=>1234,:billable=>false,:hhmm=>10.40,:note=>"new time entry sample"}},:content_type=>"application/json")

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

View By Ticket Time Entry

To view existing Time Entries, use this API.

get
/helpdesk/tickets/[ticket_id]/time_sheets.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
   {
      "time_entry":{
         "agent_email":"user@yourcompany.com",
         "agent_name":"Support",
         "billable":true,
         "contact_email":"ram@freshdesk.com",
         "created_at":"2013-12-18T19:32:51+05:30",
         "customer_name":"Poseidon",
         "executed_at":"2013-12-18T19:32:51+05:30",
         "id":2,
         "note":"Invoice Preparation",
         "start_time":"2013-12-18T19:32:51+05:30",
         "ticket_id":41,
         "timer_running":false,
         "timespent":"10.40",
         "updated_at":"2013-12-18T19:32:51+05:30",
         "user_id":1,
         "workable_type":"Helpdesk::Ticket"
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/helpdesk/tickets/41/time_sheets.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/tickets/[ticket_id]/time_sheets.json","user@yourcompany.com","test")

#default billable =false
#user_id can be any of your agent's user_id. this is the only mandatory attribute.
#hhmm can be used to set a time spent, setting this will by default disable timer_running to false. 
response = site.post({:time_entry=>{:user_id=>1234,:billable=>false,:hhmm=>10.40,:note=>"new time entry sample"}},:content_type=>"application/json")

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

View List Of Time Entries

This API lets you view the time sheets. Timesheets can be filtered using the following criterias. All the below criterias can also be used in combinations

Filter by Handle
Customer ID /helpdesk/time_sheets.json?customer_id=[value]
Company Name /helpdesk/time_sheets.json?company_name=[value]
Company Email /helpdesk/time_sheets.json?company_email=[value]
Agent ID /helpdesk/time_sheets.json?agent_id=[value]
Agent Email /helpdesk/time_sheets.json?email=[value]
Start Time /helpdesk/time_sheets.json?start_date=[value]
End Time /helpdesk/time_sheets.json?end_date=[value]
Billable /helpdesk/time_sheets.json?billable=[value]
get
/helpdesk/time_sheets.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
[
   {
      "time_entry":{
         "agent_email":"user@yourcompany.com",
         "agent_name":"Support",
         "billable":true,
         "contact_email":"ram@freshdesk.com",
         "created_at":"2013-12-18T19:32:51+05:30",
         "customer_name":"Poseidon",
         "executed_at":"2013-12-18T19:32:51+05:30",
         "id":2,
         "note":"Invoice Preparation",
         "start_time":"2013-12-18T19:32:51+05:30",
         "ticket_id":41,
         "timer_running":false,
         "timespent":"10.40",
         "updated_at":"2013-12-18T19:32:51+05:30",
         "user_id":1,
         "workable_type":"Helpdesk::Ticket"
      }
   },
   {
      "time_entry":{
         "agent_email":"user@yourcompany.com",
         "agent_name":"Support",
         "billable":true,
         "contact_email":"nikki@outerspace.com",
         "created_at":"2013-12-18T19:32:03+05:30",
         "customer_name":"SuperNova",
         "executed_at":"2013-12-18T19:32:03+05:30",
         "id":1,
         "note":"Log Analysis",
         "start_time":"2013-12-18T19:32:03+05:30",
         "ticket_id":40,
         "timer_running":false,
         "timespent":"10.40",
         "updated_at":"2013-12-18T19:32:03+05:30",
         "user_id":1,
         "workable_type":"Helpdesk::Ticket"
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET https://domain.freshdesk.com/helpdesk/time_sheets.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/tickets/[ticket_id]/time_sheets.json","user@yourcompany.com","test")

#default billable =false
#user_id can be any of your agent's user_id. this is the only mandatory attribute.
#hhmm can be used to set a time spent, setting this will by default disable timer_running to false. 
response = site.post({:time_entry=>{:user_id=>1234,:billable=>false,:hhmm=>10.40,:note=>"new time entry sample"}},:content_type=>"application/json")

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

Update Time Entry

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

put
/helpdesk/tickets/[ticket_id]/time_sheets/[id].json
Request 
1
2
3
4
5
6
7
{ 
   "time_entry": { 
      "note": "Monthly Invoice Prepartion",
      "hhmm": 11.40,
      "user_id": 1
   }
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "time_entry":{
      "agent_email":"user@yourcompany.com",
      "agent_name":"Support",
      "billable":true,
      "contact_email":"ram@outerspace.com",
      "created_at":"2013-12-18T19:32:03+05:30",
      "customer_name":"Test",
      "executed_at":"2013-12-18T19:32:03+05:30",
      "id":1,
      "note":"Monthly Invoice Preparation",
      "start_time":"2013-12-18T19:32:03+05:30",
      "ticket_id":41,
      "timer_running":false,
      "timespent":"11.40",
      "updated_at":"2013-12-18T19:32:03+05:30",
      "user_id":1,
      "workable_type":"Helpdesk::Ticket"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "time_entry": {"billable":true, "note":"Monthly Invoice Preparation", "hhmm":11.40, "user_id":1 }}' https://domain.freshdesk.com/helpdesk/tickets/41/time_sheets/1.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
require "rubygems"
require "rest_client"
require "json"

#you can also use apikey instead of user/passwd

#update time_sheets.
# site = RestClient::Resource.new("http://yourcompany.freshdesk.com/helpdesk/tickets/62/time_sheets/4.json","user@yourcompany.com","test")
site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/tickets/[ticket_id]/time_sheets/[id].json","user@yourcompany.com","test")


response = site.put({:time_entry=>{:note=>"testing"}},:content_type=>"application/json")

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

Start/Stop Timer

This API helps you start or stop the timer.

put
/helpdesk/time_sheets/[time_entry_id]/toggle_timer.json
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "time_entry":{
      "agent_email":"user@yourcompany.com",
      "agent_name":"Support",
      "billable":true,
      "contact_email":"ram@outerspace.com",
      "created_at":"2013-12-18T19:32:03+05:30",
      "customer_name":"Test",
      "executed_at":"2013-12-18T21:32:03+05:30",
      "id":3,
      "note":"Monthly Invoice Preparation",
      "start_time":"2013-12-18T21:32:03+05:30",
      "ticket_id":41,
      "timer_running":true,
      "timespent":"11.40",
      "updated_at":"2013-12-18T19:32:03+05:30",
      "user_id":1,
      "workable_type":"Helpdesk::Ticket"
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '' http://localhost/helpdesk/time_sheets/3/toggle_timer.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

#you can also use apikey instead of user/passwd

#toggling the timer. If the timer_running is true, this will be set to false and vice-versa.
site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/time_sheets/[id]/toggle_timer.json","user@yourcompany.com","test")

response = site.put(:content_type=>"application/json",:content_length=>0)

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

Delete Time Entry

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

delete
/helpdesk/tickets/[ticket_id]/time_sheets/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE https://domain.freshdesk.com/helpdesk/tickets/228/time_sheets/1.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
require "rubygems"
require "rest_client"

site = RestClient::Resource.new("https://domain.freshdesk.com/helpdesk/tickets/[ticket_id]/time_sheets/[id].xml","user@yourcompany.com","test")

response = site.delete(:accept=>"application/xml")
puts "response: #{response.code} \n #{response.body}"
EXPAND ↓

Survey

You can add customer satisfaction scores or view them via the APIs listed here.

Attribute Type Description
id number Unique id of the survey result Read-Only
agent_id number ID of the agent to whom the ticket is assigned Read-Only
survey_id number Internal ID of the survey Read-Only
group_id number ID of the Group to which the ticket is assigned Read-Only
customer_id number ID of the requester of the ticket Read-Only
rating number Rating given by the user Mandatory
response_note_id number The ID of the conversation/note in the ticket for which the survey was sent Read-Only
surveyable_id number Id of the ticket Read-Only

Survey Properties

Rating Type Value
Awesome 1
Just Okay 2
Not Good 3

Create Survey

This API allows you to add a satisfaction rating to a ticket.

post
/helpdesk/tickets/[ticket_id]/surveys/rate.json?rating=[rating_val]
Request 
1
2
3
{
  "feedback":"Great support Thanks"
}
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ 
  "survey_result" : { 
    "agent_id" : null,
    "created_at" : "2014-02-06T15:29:39+02:00",
    "customer_id" : 17,
    "group_id" : null,
    "id" : 2,
    "rating" : 1,
    "response_note_id" : null,
    "survey_id" : 1,
    "surveyable_id" : 62,
    "surveyable_type" : "Helpdesk::Ticket",
    "updated_at" : "2014-02-06T15:29:39+02:00"
  }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test  -H "Content-Type: application/json" -d '{ "feedback":"Great support Thanks" }' -X POST https://domain.freshdesk.com/helpdesk/tickets/62/surveys/rate.json?rating=1
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
require 'rubygems'
require "rest_client"
require 'json'


# rating possible values : [1=Awesome,2=Just Okay,3=Not Good]
#Specify your [ticket_id] in the below URL with your ticket id 
# site = RestClient::Resource.new('http://yourcompany.freshdesk.com/helpdesk/tickets/[ticket_id]/surveys/rate.json?rating=[rate_val]',"user@yourcompany.com","test")
site = RestClient::Resource.new('https://domain.freshdesk.com/helpdesk/tickets/91/surveys/rate.json?rating=1',"user@yourcompany.com","test")

#attachments should be of the form array of Hash with files mapped to the key 'resource'. 
payload = {:feedback=>"fast response"}

response = site.post(payload,:content_type=>"application/json")


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

View Survey

This API allows you to view customer satisfaction ratings.

get
/helpdesk/tickets/[ticket_id]/surveys.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
[
    { 
        "survey_result" : { 
            "agent_id" : null,
            "created_at" : "2013-08-24T12:58:48+05:30",
            "customer_id" : 4722354,
            "group_id" : null,
            "id" : 163649,
            "rating" : 1,
            "response_note_id" : null,
            "survey_id" : 16609,
            "surveyable_id" : 13714431,
            "surveyable_type" : "Helpdesk::Ticket",
            "updated_at" : "2013-08-24T12:58:48+05:30"
        } 
    },
    { 
        "survey_result" : { 
            "agent_id" : null,
            "created_at" : "2014-02-06T18:52:34+05:30",
            "customer_id" : 4722354,
            "group_id" : null,
            "id" : 357586,
            "rating" : 1,
            "response_note_id" : null,
            "survey_id" : 16609,
            "surveyable_id" : 13714431,
            "surveyable_type" : "Helpdesk::Ticket",
            "updated_at" : "2014-02-06T18:52:34+05:30"
        } 
    }
]
EXPAND ↓
Sample code | Curl 
1
curl -u ram@freshdesk.com:test -X GET https://domain.freshdesk.com/helpdesk/tickets/62/surveys.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'


# rating possible values : [1=Awesome,2=Just Okay,3=Not Good]
#Specify your [ticket_id] in the below URL with your ticket id
# site = RestClient::Resource.new('http://yourcompany.domain.com/helpdesk/tickets/[ticket_id]/surveys.json',"user@yourcompany.com","test")
site = RestClient::Resource.new('https://domain.freshdesk.com/helpdesk/tickets/91/surveys.json',"user@yourcompany.com","test")

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

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

Groups

APIs for groups allow you create, view or update existing groups of agents. These APIs can help you increase responsiveness to a ticket as dedicated groups for each trouble type can turn down ticket response times.

Attribute Type Description
id number Unique id of the group Read-Only
name string Name of the group Mandatory
description string Description of the group
escalate_to number The user to whom the escalation email is sent of a ticket is unassigned
assign_time datetime The time after which an escalation email will be sent if a ticket remains unassigned
ticket_assign_type number Describes the automatic ticket assignment type
agent_list string The CSV of agent user ids. Instructions on getting the agent's user id.

Create Group

Create a new group using this API.

post
/groups.json
Request 
1
2
3
4
5
6
7
8
{
   "group":{ 
      "name":"Entertainment",
      "description":"Singers and dancers",
      "assign_time":2400,
      "agent_list":"1,16"
   }
}
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
{
   "group":{
      "assign_time":2400,
      "business_calendar_id":null,
      "created_at":"2014-01-08T07:53:41+05:30",
      "description":"Singers and dancers",
      "escalate_to":null,
      "id":5,
      "name":"Entertainment",
      "ticket_assign_type":0,
      "updated_at":"2014-01-08T07:53:41+05:30",
      "agents":[{
            "active":true,
            "address":null,
            "created_at":"2013-12-11T18:11:27+05:30",
            "customer_id":null,
            "deleted":false,
            "description":null,
            "email":"rockstar@yourcompany.com",
            "external_id":null,
            "fb_profile_id":null,
            "helpdesk_agent":true,
            "id":1,
            "job_title":null,
            "language":"en",
            "mobile":null,
            "name":"Rock Star",
            "phone":null,
            "time_zone":"Chennai",
            "twitter_id":null,
            "updated_at":"2014-01-07T12:56:45+05:30"
         },
         {
            "active":true,
            "address":null,
            "created_at":"2013-12-11T18:11:27+05:30",
            "customer_id":null,
            "deleted":false,
            "description":null,
            "email":"popstart@yourcompany.com",
            "external_id":null,
            "fb_profile_id":null,
            "helpdesk_agent":true,
            "id":16,
            "job_title":null,
            "language":"en",
            "mobile":null,
            "name":"Pop Star",
            "phone":null,
            "time_zone":"Chennai",
            "twitter_id":null,
            "updated_at":"2014-01-07T12:56:45+05:30"
         }]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X POST -d '{ "group": { "name":"Entertainment", "description":"Singers and dancers", "assign_time":2400, "agent_list":"1,16" }}' https://domain.freshdesk.com/groups.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
require "rubygems"
require "rest_client"
require "json"

site = RestClient::Resource.new("http://domain.freshdesk/groups.json","user@yourcompany.com","test")

#agent_list contains the user_id of the agents
#escalate_to is the user_id of agent to whom it should be escalated

response = site.post({:group=>{:name=>"new group",:description=>"new group description",:assign_time=>1200,:escalate_to=>16,:agent_list=>[16,1]}},:content_type=>"application/json")

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

Update Group

If you wish to change descriptions of a group or make any changes to a group, use this API. For a list of all that can be changed, look at the table given above.

put
/groups/[id].json
Request 
1
2
3
4
5
6
7
{
  "group": {
    "name":"Entertainers",
    "description":"Singers dancers and stand up comedians",
    "agent_list":"1,16"
  }
}
EXPAND ↓
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X PUT -d '{ "group": { "name":"Entertainers", "description":"Singers dancers and stand up comedians", "agent_list":[1,16] }}' https://domain.freshdesk.com/groups/1.json
EXPAND ↓
Sample code | Ruby 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
require "rubygems"
require "rest_client"
require "json"


# Need to specify group_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/groups/2.json","user@yourcompany.com","test")

site = RestClient::Resource.new("http://domain.freshdesk/groups/[group_id].json","user@yourcompany.com","test")

response = site.put({:group=>{:name=>"ne group",:description=>"new group description",:assign_time=>1200,:escalate_to=>16,:agent_list=>[16,1]}},:content_type=>"application/json")

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

View Group

To spy on a specific group amongst all in your roster, use this API.

get
/groups.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
{
   "group":{
      "assign_time":2400,
      "business_calendar_id":null,
      "created_at":"2014-01-08T07:53:41+05:30",
      "description":"Singers dancers and stand up comedians",
      "escalate_to":null,
      "id":5,
      "name":"Entertainers",
      "ticket_assign_type":0,
      "updated_at":"2014-01-08T11:49:25+05:30",
      "agents":[{
            "active":true,
            "address":null,
            "created_at":"2013-12-11T18:11:27+05:30",
            "customer_id":null,
            "deleted":false,
            "description":null,
            "email":"rockstar@yourcompany.com",
            "external_id":null,
            "fb_profile_id":null,
            "helpdesk_agent":true,
            "id":1,
            "job_title":null,
            "language":"en",
            "mobile":null,
            "name":"Rock Star",
            "phone":null,
            "time_zone":"Chennai",
            "twitter_id":null,
            "updated_at":"2014-01-07T12:56:45+05:30"
         },
         {
            "active":true,
            "address":null,
            "created_at":"2013-12-11T18:11:27+05:30",
            "customer_id":null,
            "deleted":false,
            "description":null,
            "email":"popstart@yourcompany.com",
            "external_id":null,
            "fb_profile_id":null,
            "helpdesk_agent":true,
            "id":16,
            "job_title":null,
            "language":"en",
            "mobile":null,
            "name":"Pop Star",
            "phone":null,
            "time_zone":"Chennai",
            "twitter_id":null,
            "updated_at":"2014-01-07T12:56:45+05:30"
         }]
   }
}
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET  https://domain.freshdesk.com/groups/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 group_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/groups/5.json","user@yourcompany.com","test")

site = RestClient::Resource.new("http://domain.freshdesk/groups/[group_id].json","user@yourcompany.com","test")

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

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

View All Group

To view a list of all the groups in your helpdesk, use this API.

get
/groups.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
[
   {
      "group":{
         "assign_time":2400,
         "business_calendar_id":null,
         "created_at":"2014-01-08T07:53:41+05:30",
         "description":"Singers dancers and stand up comedians",
         "escalate_to":null,
         "id":5,
         "name":"Entertainers",
         "ticket_assign_type":0,
         "updated_at":"2014-01-08T11:49:25+05:30",
         "agents":[{
               "active":true,
               "address":null,
               "created_at":"2013-12-11T18:11:27+05:30",
               "customer_id":null,
               "deleted":false,
               "description":null,
               "email":"rockstar@yourcompany.com",
               "external_id":null,
               "fb_profile_id":null,
               "helpdesk_agent":true,
               "id":1,
               "job_title":null,
               "language":"en",
               "mobile":null,
               "name":"Rock Star",
               "phone":null,
               "time_zone":"Chennai",
               "twitter_id":null,
               "updated_at":"2014-01-07T12:56:45+05:30"
            },
            {
               "active":true,
               "address":null,
               "created_at":"2013-12-11T18:11:27+05:30",
               "customer_id":null,
               "deleted":false,
               "description":null,
               "email":"popstart@yourcompany.com",
               "external_id":null,
               "fb_profile_id":null,
               "helpdesk_agent":true,
               "id":16,
               "job_title":null,
               "language":"en",
               "mobile":null,
               "name":"Pop Star",
               "phone":null,
               "time_zone":"Chennai",
               "twitter_id":null,
               "updated_at":"2014-01-07T12:56:45+05:30"
            }]
      }
   }
]
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X GET  https://domain.freshdesk.com/groups.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("http://domain.freshdesk/groups.json","user@yourcompany.com","test")

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

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

Delete Group

To make a group walk the plank, use this API. Deleting a Group will only disband the group and not delete its members. Deleted groups cannot be restored.

delete
/groups/[id].json
Response 
1
HTTP Status: 200 OK
EXPAND ↓
Sample code | Curl 
1
curl -v -u user@yourcompany.com:test -H "Content-Type: application/json" -X DELETE  https://domain.freshdesk.com/groups/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 group_id in url
# eg:
# site = RestClient::Resource.new("https://domain.freshdesk.com/groups/2.json","user@yourcompany.com","test")

site = RestClient::Resource.new("http://domain.freshdesk/groups/[group_id].json","user@yourcompany.com","test")

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

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

This documentation is for the v1.0 APIs. We recommend you use the newer v2.0 APIs instead.