Introduction
The Freshservice API
Freshservice is a cloud-based IT Service Management solution that was designed using ITIL best practices. Freshservice helps IT organizations streamline their service delivery processes with a strong focus on user experience and employee happiness.
Freshservice's APIs belong to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding or deleting data from your service desk. The APIs also support Cross-Origin Resource Sharing (CORS).
Note: This documentation is for the v2.0 of the APIs. Documentation for the v1.0 APIs can be found here.
What API commands are used by Freshservice?
Freshservice APIs are plain JSON over HTTP and use the following HTTP verbs:
Command | Purpose |
---|---|
POST | Create an object |
GET | Fetch one or more objects |
PUT | Update an object / Restore an object |
DELETE | Remove an object |
Note: All API requests should hit the secured endpoint i.e. only HTTPS
What's New?
Version 2 of the API brings several new features as well as changes to the previous APIs. This section highlights some of the new features introduced in v2.
- Higher rate limits as a result of significant performance enhancements
- Improved error handling - errors will return appropriate HTTP status codes and an error body
- New APIs that enable you to Reply to a ticket and enhancements to existing APIs that enable you to Update a ticket's description, Update a ticket's notes, and Retrieve a list of tickets that have been recently modified
- Only JSON is supported in V2
- Only SSL calls (HTTPS) will be allowed
- Works only via Freshservice domains and not via custom CNAMEs
- Support for page sizes up to 100 has been added
Rate limit
Freshservice accounts created on or after 01-Sep-2020 will use minute-level rate limiting. The limits vary based on the Freshservice plan. Certain API operations also have sublimits within the overall limit. This limit is applied on an account wide basis irrespective of factors such as the number of agents or IP addresses used to make the calls.
Action | Rate Limit/Min | |||
---|---|---|---|---|
Starter | Growth | Pro | Enterprise | |
Overall Limit | 100 | 200 | 400 | 500 |
Sub Limits | ||||
List All Tickets | 40 | 70 | 120 | 140 |
View Ticket | 50 | 80 | 140 | 160 |
Create Ticket | 50 | 80 | 140 | 160 |
Update Ticket | 50 | 80 | 140 | 160 |
List All Assets | 40 | 70 | 120 | 140 |
Update Asset | 50 | 80 | 140 | 160 |
List All Agents | 40 | 70 | 120 | 140 |
List All Requesters | 40 | 70 | 120 | 140 |
Note:
1. Please follow the best practices to stay under the rate limit.
2. If you need more than the default limit, please contact us.
3. Even invalid requests will count towards the rate limit.
4. Embedding additional resources will consume 1 credit if performed from a SHOW action, and 3 credits if performed from a LIST action.
5. Some custom apps (freshplugs) consume API calls which also count towards the rate limit.
You can check your current rate limit status by looking at the following HTTP headers which are returned in response to every API request.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Ratelimit-Total: 3000
X-Ratelimit-Remaining: 998
X-Ratelimit-Used-CurrentRequest: 1
X-Freshservice-Api-Version: latest=v2; requested=v2
Header Name | Description |
---|---|
X-RateLimit-Total | Total number of API calls allowed per hour. |
X-RateLimit-Remaining | The number of requests remaining in the current rate limit window. |
X-RateLimit-Used-CurrentRequest | The number of API calls consumed by the current request. Most API requests consume one call, however, including additional information in the response will consume more calls. |
Retry-After | The number in seconds that you will have to wait to fire your next API request. This header will be returned only when the rate limit has been reached. |
If your API request is received after the rate limit has been reached, Freshservice will return an error in the response. The Retry-After value in the response header will tell you how long you need to wait before you can send another API request.
HTTP/1.1 429
Content-Type: application/json; charset=utf-8
Retry-After: 1521
Policies
Freshservice APIs are classified into either production or beta APIs. A production API is one that has been made available for public use and is stable. A beta API is one that is still in development or is for internal or limited use and whose stability cannot be guaranteed. Beta APIs may be removed or modified at any time without advance notice. Please note that the following policies apply to production APIs only.
Deprecation Policy
The scope of the V2 API is currently limited to only tickets and conversations. Once all modules are made available through the API, API V1 would be deprecated after a given notice period.
Breaking Change Policy
Changes that do not break an API, such as adding a new attribute can be made at any time. Changes that break a production level API such as removing attributes or making major changes to the API’s behavior will only be done with an advance notice of 60 days. However, there may be rare occasions where due to legal, performance, or security reasons, we are forced to make breaking changes without advance notice.
Changelog
- Freshservice APIs support Oauth authentication. Refer scopes required against the respective APIs.
- 'Create a Child Ticket' API allows creating incidents as child tickets for SR/Case/Query/Issue/Request apart from an incident.
- 'Create a Child Service Request' API allows creating SR/Case/Query/Issue/Request as child ticket for an Incident/Major Incident also.
- List All Groups will return agent groups only from the specified workspace, or the primary workspace if workspace_id is not specified.
- Restricted groups are supported in all workspaces
- Audit logs of requesters ("type": ["requester"]) can be exported
- Audit logs of a requester ("requester_id": number) can be exported
Following attributes are no longer supported:
In the object "Agent"
- Attribute ticket_scope is no longer supported. Instead use roles -> assignment_scope
- Attribute problem_scope is no longer supported. Instead use roles -> assignment_scope
- Attribute change_scope is no longer supported. Instead use roles -> assignment_scope
- Attribute release_scope is no longer supported. Instead use roles -> assignment_scope
- Attribute scopes is no longer supported. Instead use roles -> assignment_scope
- Attribute group_ids is no longer supported. Instead use member_of and observer_of
- Attribute role_ids is no longer supported. Instead use roles -> role_id
In the object "group"
- Attribute agent_ids is no longer supported. Instead use members and observers
- Username and password-based basic authentication of Freshservice APIs is no longer supported. Instead use basic auth with API Key authentication.
- Initial version - V2 APIs for tickets and conversations
Authentication
How does it work? Who can access my helpdesk? Can everybody see my data?
Before you can set the priority of a ticket or change a customer's name or use any of the APIs listed above, you need to "authenticate your ID" or "log in" in the same way you log in to your helpdesk's web portal.
You can use your personal API key to authenticate the request. If you use the API key, there is no need for a password. You can use any set of characters as a dummy password.
curl -v -u apikey:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets'
For example, if your API key is abcdefghij1234567890, the curl command to use is:
curl -v -u abcdefghij1234567890:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets'
Where can I find my API key?
- Login to your Support Portal
- Click on your profile picture on the top right corner of your portal
- Go to Profile settings Page
- Your API key will be available below the change password section to your right
Freshservice supports Basic Access Authorization only with API key.
curl -v -u api_key:X -H "Content-Type: application/json" -X 'GET https://domain.freshservice.com/api/v2/tickets'
- If you are sure that your API key is correct, but are still unable to access your helpdesk, make sure that your "APIkey:X" is Base64-encoded before passing it as an "Authorization" header.
- Username/password basic authentication is deprecated as of May 31st 2023. See the solution here for more details.
What are the resources available via the API?
Every single piece of information - be it a customer's ID or the priority of a specific ticket - can be identified by its own unique identifier or "URI". If you want your data from the helpdesk, whether via your smartphone app or via a third party service, you need this identifier. All URIs follow a specific format and that format is:
https://your_helpdesk_domain_name/api/v2/resource_name
For example, if you are the admin of the Freshservice portal "acmeinc.freshservice.com", then to access the tickets in your helpdesk, the syntax would be
https://acmeinc.freshservice.com/api/v2/tickets
Note: We have shortened API resource URLs throughout this document by omitting the domain name. For example, /api/v2/tickets is actually https://domain.freshservice.com/api/v2/tickets
Will everyone have the same access rights?
No, everyone will not have the same access rights. Your ability to access data depends on the permissions available for your freshservice profile. If your freshservice Agent Role is "Newbie Agent" who is not allowed to answer to tickets, but is only allowed to view them, then the APIs will restrict you from answering and you'll only be able to view the tickets.
Schema
Blank Fields:
Blank fields are included as null instead of being omitted.
Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. ( Example : 2016-02-13T23:27:49Z )
Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm
If the time zone information is not present, it will be assumed to be in UTC.
( some valid datefields : 2016-02-15T21:16:25Z, 2012-12-24T12:56:15+05:30, 2010-03-23T12:00 )
For more details on date format : ISO 8601
Location Header:
POST requests will contain the Location Header in the response that points to the URL of the created resource.
Response
HTTP STATUS: HTTP 201 Created
Headers:
"Location": https://domain.freshservice.com/api/v2/tickets/1
Embedding
Our previous version of APIs returned a large number of fields by default. In order to increase performance and reduce data usage, we have removed several of these fields in our v2.0 APIs. For example, when you view a ticket, we no longer return the requester's name or the company name. However, there may be situations where these fields are required and hence, we have included a mechanism to embed additional resources into an API call in order to minimise the number of required API calls.
Note: Embedding resources into an API that returns a single object will consume an additional API call credit per embedded resource while embedding into APIs that return a collection of objects will consume two additional credits.
You can request for additional resources using the "include" keyword. For example you can embed the requester's details within the ticket view API by using the following command
1 | curl -v -u 'abcdefgh12345678:X' -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=requester' |
Attachments
Attachments are supported for the following endpoints
Please follow the guidelines listed below
- Only files on your local machine can be attached using API.
- The Content-Type should always be multipart/form-data for create/update requests with attachments.
- The name of the file is preserved after it is attached i.e the filename sent in the response will be the same as the one in the request.
Errors
I have encountered an error. How do I debug it?
API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error. You can use the table below to understand what each code means.
HTTP STATUS CODE | TEXT | DESCRIPTION |
---|---|---|
400 | Client or Validation Error | The request body/query string is not in the correct format. For example, the Create a ticket API requires the requester_id field to be sent as part of the request and if it is missing, this status code is returned. Also, requests containing a deprecated or invalid attribute will result in this error. For example, if ticket_scope, problem_scope or any of the deprecated attributes are sent in the API requests to /api/v2/agents then this error is returned. |
401 | Authentication Failure | Indicates that the Authorization header is either missing or incorrect. For example, if you send an API request containing username/password then authentication will fail with this error. You can learn more about the Authorization header here. |
403 | Access Denied | This indicates that the agent whose credentials were used for making this request was not authorized to perform this API call. It could be that this API call requires admin level credentials or perhaps the Freshservice portal doesn't have the corresponding feature enabled. It could also indicate that the user has reached the maximum number of failed login attempts or that the account has reached the maximum number of agents. |
404 | Requested Resource not Found | This status code is returned when the request contains invalid ID/Freshservice domain in the URL or an invalid URL itself. For example, an API call to retrieve a ticket with an invalid ID will return an HTTP 404 status code to let you know that no such ticket exists. |
405 | Method not allowed | This API request used the wrong HTTP verb/method. For example an API PUT request on /api/v2/tickets endpoint will return an HTTP 405 as /api/v2/tickets allows only GET and POST requests. |
406 | Unsupported Accept Header | Only application/json and */* are supported. When uploading files multipart/form-data is supported. |
409 | Inconsistent/Conflicting State | The resource that is being created/updated is in an inconsistent or conflicting state. |
415 | Unsupported Content-type | Content type application/xml is not supported. Only application/json is supported. |
429 | Rate Limit Exceeded | The API rate limit allotted for your Freshservice domain has been exhausted. |
500 | Unexpected Server Error | You can't do much here. This indicates an error at Freshservice's side. Please email us your script which invokes our API, along with the response headers. We will work with you to fix the issue. |
Error Response
In addition to the HTTP status code, most errors will also return a response body that contains more information to help you debug the error. A sample error response is shown below. The format of the error response body is explained after the example.
Error Response Fields
FIELD | DESCRIPTION |
---|---|
field | The request field that triggered this error. Applicable to HTTP 400 errors only. |
message | Detailed error message. |
code | Custom error code that is machine-parseable. |
Error Codes
In addition to the the error message, the error response will also contain an error code that is machine-parseable. The following table lists the error codes and their descriptions.
CODE | DESCRIPTION |
---|---|
missing_field | A mandatory attribute is missing. For example, calling Create a Ticket without the mandatory description in the request will result in this error. |
invalid_value | This code indicates that a request contained an incorrect or blank value, or was in an invalid format. |
duplicate_value | Indicates that this value already exists. |
datatype_mismatch | Indicates that the field value doesn't match the expected data type. For instance, entering text in a numerical field would trigger this error. |
invalid_field | An unexpected field was part of the request. If any additional field is included in the request payload (other than what is specified in the API documentation), this error will occur. |
invalid_json | Request parameter is not a valid JSON. We recommend that you validate the JSON payload with a JSON validator before firing the API request. |
invalid_credentials | Incorrect or missing API credentials. As the name suggests, it indicates that the API request was made with invalid credentials. Forgetting to apply Base64 encoding on the API key is a common cause of this error. |
access_denied | Insufficient privileges to perform this action. An agent attempting to access admin APIs will result in this error. |
require_feature | Not allowed since a specific feature has to be enabled in your Freshservice portal for you to perform this action. |
account_suspended | Account has been suspended. |
ssl_required | HTTPS is required in the API URL. |
readonly_field | Read only field cannot be altered. |
password_lockout | The agent has reached the maximum number of failed login attempts. |
password_expired | The agent's password has expired. |
no_content_required | No JSON data required. |
inaccessible_field | The agent is not authorized to update this field. |
incompatible_field | The field cannot be updated due to the current state of the record. |
unsupported_authentication_type | API request is made with an unsupported authentication type such as username/password. |
access_token_expired | API request is made with an expired Oauth access token. Obtain a new access token using the refresh token and retry the request. |
access_token_invalid | API request is made with Oauth token with invalid signature or invalid scope(s) or an account which is no longer part of the Freshworks organization for which the token was issued. |
Pagination
API responses that return a list of objects, such as View List of Tickets are paginated. To scroll through the pages, add the parameter page to the query string. The page number starts with 1.
https://domain.freshservice.com/api/v2/tickets?page=2
By default, the number of objects returned per page is 30. This can be adjusted by adding the per_page parameter to the query string. The maximum number of objects that can be retrieved per page is 100. Invalid values and values greater than 100 will result in an error.
https://domain.freshservice.com/api/v2/tickets?per_page=10
The per_page and page parameters can also be used together. The following example will retrieve the 11th to 20th tickets.
https://domain.freshservice.com/api/v2/tickets?per_page=10&page=2
The 'link' header in the response will hold URL of the next page, if it exists. If you have reached the last page of objects, then the link header will not be set.
Headers:
"link":< https://domain.freshservice.com/api/v2/tickets?filter=all_tickets&page=2>;rel="next"
Best Practices
Rate Limit
- Whenever possible, please queue API calls at your end. This ensures that you can buffer calls on your end to avoid hitting the rate limit and retry API calls when you hit the rate limit after the retry-after time.
- Cache non-volatile data on your end whenever it is feasible. For e.g. the mapping between agent name and ID is extremely unlikely to change. Hence, by caching it on the client side, you will be able to avoid API calls.
- As soon as you recognise that a rate limit increase will be required in the future, contact us. This will make it possible for us to ensure that we are prepared to increase the limit as and when needed.
Others
- Avoid making API calls directly from a mobile app. Instead, send the request to your servers and make the API calls from there. This ensures that in the event of an API endpoint being modified, you will be able to make and deploy the change to your server rather than updating your app and forcing your users to the latest version.
- Always use HTTP connection/multiplexing when making the API request. This will save some time while opening TCP connection to Freshservice.
- When retrieving a list of objects, avoid making calls referencing page numbers over 500 (deep pagination). These are performance intensive calls and you may suffer from extremely long response times.
API Index
Category | Create | View | View List | Update | Delete | Others |
---|---|---|---|---|---|---|
Tickets | Yes | Yes | Yes | Yes | Yes | 29 more |
Conversations | Yes | No | Yes | Yes | Yes | 2 more |
Problems | Yes | Yes | Yes | Yes | Yes | 18 more |
Changes | Yes | Yes | Yes | Yes | Yes | 18 more |
Releases | Yes | Yes | Yes | Yes | Yes | 19 more |
CABs | Yes | Yes | Yes | Yes | Yes | |
Workspaces | No | Yes | Yes | No | No | |
Approvals | No | No | Yes | No | No | |
Requesters | Yes | Yes | Yes | Yes | Yes | 7 more |
Agents | Yes | Yes | Yes | Yes | Yes | 6 more |
Agent Roles | No | Yes | Yes | No | No | |
Agent Groups | Yes | Yes | Yes | Yes | Yes | |
Requester Groups | Yes | Yes | Yes | Yes | Yes | 3 more |
Locations | Yes | Yes | Yes | Yes | Yes | 1 more |
Products | Yes | Yes | Yes | Yes | Yes | |
Vendors | Yes | Yes | Yes | Yes | Yes | |
Assets | Yes | Yes | Yes | Yes | Yes | 15 more |
Purchase Order | Yes | Yes | Yes | Yes | Yes | 1 more |
Asset Types | Yes | Yes | Yes | Yes | Yes | 1 more |
Software | Yes | Yes | Yes | Yes | Yes | 12 more |
Contracts | Yes | Yes | Yes | Yes | No | 10 more |
Departments | Yes | Yes | Yes | Yes | Yes | 2 more |
Business Hours | No | Yes | Yes | No | No | |
Projects | Yes | Yes | Yes | Yes | Yes | 2 more |
Project Tasks | Yes | Yes | Yes | Yes | Yes | |
Projects NewGen | Yes | Yes | Yes | Yes | Yes | 9 more |
Project Tasks NewGen | Yes | Yes | Yes | Yes | Yes | 17 more |
Solution Category | Yes | Yes | Yes | Yes | Yes | |
Solution Folder | Yes | Yes | Yes | Yes | Yes | 1 more |
Solution Article | Yes | Yes | Yes | Yes | Yes | 6 more |
Service Catalog | Yes | Yes | Yes | No | No | 2 more |
Announcements | Yes | Yes | Yes | Yes | Yes | |
Employee Onboarding | Yes | Yes | Yes | No | No | 2 more |
Employee Offboarding | Yes | Yes | Yes | No | No | 2 more |
Oncall management | Yes | Yes | Yes | Yes | Yes | 19 more |
Custom Objects | Yes | No | Yes | Yes | Yes | 2 more |
SLA Policies | No | No | Yes | No | No | |
Canned Responses | No | Yes | Yes | No | No | 3 more |
Audit Logs | No | No | No | No | No | 1 more |
Attachment | No | Yes | No | No | No | 1 more |
Tickets
This section lists all API that can be used to create, edit or otherwise manipulate tickets.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the ticket. |
workspace_id | number | ID of the workspace that the ticket belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 40 MB. |
cc_emails | array of strings | Email addresses added in the 'cc' field of the incoming ticket email. |
department_id | number | ID of the department to which this ticket belongs. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
deleted | boolean | Set to true if the ticket has been deleted/trashed. Deleted tickets will not be displayed in any views except the "deleted" filter. |
description | string | HTML content of the ticket. |
description_text | string | Content of the ticket in plain text. |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved. |
string | Email address of the requester. If no contact exists with this email address in Freshservice, it will be added as a new contact. | |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
fr_due_by | datetime | Timestamp that denotes when the first response is due. |
fr_escalated | boolean | Set to true if the ticket has been escalated as a result of the first response time being breached. |
fwd_emails | array of strings | Email addresses added while forwarding a ticket. |
group_id | number | ID of the group to which the ticket has been assigned. |
is_escalated | boolean | Set to true if the ticket has been escalated for any reason. |
name | string | Name of the requester. |
phone | string | Phone number of the requester. If no contact exists with this phone number in Freshservice, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory. |
priority | number | Priority of the ticket. |
category | number | Ticket Category. |
sub_category | string | Ticket sub category. |
item_category | string | Ticket item category. |
reply_cc_emails | array of strings | Email addresses added while replying to a ticket. |
requester_id | number | User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email. |
responder_id | number | ID of the agent to whom the ticket has been assigned. |
source | number | The channel through which the ticket was created. |
spam | boolean | Set to true if the ticket has been marked as spam. |
status | number | Status of the ticket. |
subject | string | Subject of the ticket. |
tags | array of strings | Tags that have been associated with the ticket. |
to_emails | Array of strings | Email addresses to which the ticket was originally sent. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. [Support for only type ‘incident’ as of now] |
created_at | datetime | Ticket creation timestamp. |
updated_at | datetime | Ticket updated timestamp. |
urgency | number | Ticket urgency. |
impact | number | Ticket impact. |
resolution_notes | string | Content of the ticket resolution note in plain text |
resolution_notes_html | string | HTML content of the ticket resolution note |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Status and Priorities. These numerical values along with their meanings are given below.
Source Type | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 4 |
Feedback widget | 5 |
Yammer | 6 |
AWS Cloudwatch | 7 |
Pagerduty | 8 |
Walkup | 9 |
Slack | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Create a Ticket
This API helps you to create a new ticket in your service desk.
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Status and Priorities. These numerical values along with their meanings are given below.
Source Type | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 4 |
Feedback widget | 5 |
Yammer | 6 |
AWS Cloudwatch | 7 |
Pagerduty | 8 |
Walkup | 9 |
Slack | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshservice.com","diana@freshservice.com"], "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/tickets' |
Create a Ticket With Custom Fields
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshservice.com","diana@freshservice.com"], "custom_fields" : { "custom_text" : "This is a custom text box" }, "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/tickets' |
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 | { "ticket": { "cc_emails": [ "ram@freshservice.com", "diana@freshservice.com" ], "fwd_emails": [], "reply_cc_emails": [ "ram@freshservice.com", "diana@freshservice.com" ], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 1, "requester_id": 1000000675, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "to_emails": null, "department_id": null, "id": 265, "type": "Incident", "due_by": "2017-09-11T10:34:28Z", "fr_due_by": "2017-09-09T10:34:28Z", "is_escalated": false, "description": "<div>Details about the issue...</div>", "description_text": "Details about the issue...", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "custom_text": "This is a custom text box", "auto_checkbox": null }, "created_at": "2017-09-08T10:34:28Z", "updated_at": "2017-09-08T10:34:28Z", "tags": [], "attachments": [], "workspace_id": 3, "resolution_notes": "Resolution note for the ticket...", "resolution_notes_html": "<div>Resolution note for the ticket...</div>" } } |
Create Ticket with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'subject=Support Needed...' -F 'description=Details about the issue...' -F 'email=tom@outerspace.com' -F 'priority=1' -F 'status=2' -F 'workspace_id=3' -X POST 'https://domain.freshservice.com/api/v2/tickets' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 1, "requester_id": 1232528431, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "to_emails": null, "department_id": null, "id": 51, "type": "Incident", "due_by": "2021-04-22T06:01:08Z", "fr_due_by": "2021-04-15T03:01:08Z", "is_escalated": false, "description": "<div>Details about the issue...</div>", "description_text": "Details about the issue...", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "new_number": null, "time_info": null, "number_test": null }, "created_at": "2021-04-12T06:01:08Z", "updated_at": "2021-04-12T06:01:08Z", "tags": [], "attachments": [ { "id": 368553, "content_type": "image/png", "size": 115399, "name": "api_attach.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api_attach.png", "created_at": "2021-04-12T06:01:08Z", "updated_at": "2021-04-12T06:01:08Z" } ], "workspace_id": 3, "resolution_notes": "Resolution note for the ticket...", "resolution_notes_html": "<div>Resolution note for the ticket...</div>" } } |
Create Ticket with assets
Note:
1. assets" key: contains comma (,) separated hash of the assets, each with key display id.
2. When "assets" is included as request parameter in PUT or POST request, the associated assets are returned implicitly in the response.
3. The existing request format to link a single asset ("associate_ci" : { "serial_no " : 123, "name " : "Andrea's Laptop " , "user ": "Andrea "}) will be deprecated soon.
4. If both "assets" and "associate_ci" keys are given in the request, assets key would be considered preferably and associate_ci would be ignored.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "description": "Create ticket with assets linked", "status": 2, "email": "sample@freshservice.com", "priority": 1, "subject": "Create ticket with assets linked", "assets": [{ "display_id": 8 }, { "display_id": 9 }] "workspace_id": 3}' -X POST 'https://domain.freshservice.com/api/v2/tickets' |
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 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 1, "requester_id": 1, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Create ticket with assets linked", "to_emails": null, "department_id": null, "id": 433, "type": "Incident", "due_by": "2020-02-06T11:30:00Z", "fr_due_by": "2020-01-30T08:30:00Z", "is_escalated": false, "description": "<div>Create ticket with assets linked</div>", "description_text": "Create ticket with assets linked", "category": null, "sub_category": null, "item_category": null, "resolution_notes":null, "resolution_notes_html":null, "custom_fields": { }, "created_at": "2020-01-27T12:08:06Z", "updated_at": "2020-01-27T12:08:06Z", "tags": [], "attachments": [], "workspace_id": 3, "assets": [ { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null }, { "name": "Logitech Mouse", "description": null, "ci_type_id": 4, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 9, "salvage": null } ] } } |
Create Ticket with associations
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "problem": {"display_id": 2}, "change_initiating_ticket": {"display_id": 4}, "change_initiated_by_ticket": {"display_id": 5}, "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/tickets' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "fr_escalated": false, "spam": false, "email_config_id": null, "group_id": null, "priority": 1, "requester_id": 1232695482, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "to_emails": null, "department_id": null, "id": 78, "type": "Incident", "due_by": "2021-04-30T10:39:46Z", "fr_due_by": "2021-04-28T10:39:46Z", "is_escalated": false, "description": "<div>Details about the issue...</div>", "description_text": "Details about the issue...", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "deve": null, "locaite": null }, "created_at": "2021-04-27T10:39:46Z", "updated_at": "2021-04-27T10:39:46Z", "tags": [], "attachments": [], "workspace_id": 3, "problem": { "subject": "Unable to reach email server", "priority": 1, "status": 1, "impact": 1, "due_by": "2021-04-29T10:24:00Z", "display_id": 2, "requester_id": 1001536865, "owner_id": 1232265829, "group_id": null, "change_id": null, "deleted": false, "known_error": false, "created_at": "2021-04-27T10:25:20Z", "updated_at": "2021-04-27T10:25:20Z", "department_id": null, "email_config_id": null, "category": null, "sub_category": null, "item_category": null }, "change_initiating_ticket": { "display_id": 4, "requester_id": 1001536865, "owner_id": 1232265829, "group_id": null, "release_id": null, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "deleted": false, "subject": "Getting ES3 back up to speed", "created_at": "2021-04-27T10:26:54Z", "updated_at": "2021-04-27T10:26:54Z", "cc_email": {}, "planned_start_date": "2021-04-19T18:45:00Z", "planned_end_date": "2021-04-19T23:15:00Z", "department_id": null, "email_config_id": null, "category": null, "sub_category": null, "item_category": null }, "change_initiated_by_ticket": { "display_id": 5, "requester_id": 1001536865, "owner_id": 1232265829, "group_id": null, "release_id": null, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "deleted": false, "subject": "Upgrade Web Server", "created_at": "2021-04-27T10:28:48Z", "updated_at": "2021-04-27T10:28:48Z", "cc_email": {}, "planned_start_date": "2021-04-21T01:00:00Z", "planned_end_date": "2021-04-21T05:30:00Z", "department_id": 683112, "email_config_id": null, "category": null, "sub_category": null, "item_category": null } } } |
View a Ticket
Use 'include' to embed additional details in the response. Each include will consume an additional credit. For example if you embed the requester and company information you will be charged a total of 3 API credits for the call.
Note:
By default, certain fields such as conversations, tags and requester email will not be included in the response. They can be retrieved via the embedding functionality.
Embed | Handle |
---|---|
conversations | /api/v2/tickets/[id]?include=conversations Will return up to ten conversations sorted by "created_at" in ascending order. Including conversations will consume two API calls. In order to access more than ten conversations belonging to a ticket, use the List All Conversationsof a Ticket API. |
requester | /api/v2/tickets/[id]?include=requester Will return requester details like id, name, mobile, phone |
requested_for | /api/v2/tickets/[id]?include=requested_for Will return details of the user on behalf of whom the request has been raised |
stats | /api/v2/tickets/[id]?include=stats Will return the ticket’s closed_at, resolved_at and first_responded_at time |
problem | /api/v2/tickets/[id]?include=problem Returns details of associated problem |
assets | /api/v2/tickets/[id]?include=assets Returns set of associated asset details |
changes | /api/v2/tickets/[id]?include=changes Returns list of associated changes and causing changes details |
related_tickets | /api/v2/tickets/[id]?include=related_tickets Returns child ticket ids / parent ticket ids based on ticket. No ids returned for parent tickets with no children |
onboarding_context | /api/v2/tickets/[id]?include=onboarding_context Returns onboarding data mapped to the ticket |
offboarding_context | /api/v2/tickets/[id]?include=offboarding_context Returns offboarding data mapped to the ticket |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/20' |
1. Get the associated conversations along with the ticket response.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=conversations' |
2. Get the associated tags and requester information along with the ticket response.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=tags,requester' |
3. Get the associated stats information along with the ticket response.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=stats' |
4. Get the associated onboarding information along with the ticket response.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=onboarding_context' |
5. Get the associated offboarding information along with the ticket response.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/20?include=offboarding_context' |
Filter Tickets
Custom ticket fields that you have created in your account can also be used to filter through the tickets and get a list of tickets matching the specified ticket fields.
Query Format(query) - "(ticket_field:integer OR ticket_field:'string') AND ticket_field:boolean"
Note:
1. The query must be URL encoded
2. Query can be framed using the ticket field name in snake case, which can be obtained from Ticket Fields endpoint. Ticket Fields are case sensitive
3. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
4. Logical operators AND, OR along with parentheses () can be used to group conditions
5. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields
6. Input for date fields should be in UTC Format
7. The number of objects returned per page is 30 also the total count of the results will be returned along with the result
8. To scroll through the pages add page parameter to the url
9. To filter for agent and group with no values assigned, use the null keyword
10. By default, only tickets from the primary workspace will be returned for accounts on the Employee Support Mode. For tickets from other workspaces, use the workspace_id query parameter.
Supported Ticket Fields
Field | Type | Description |
---|---|---|
workspace_id | number | Workspace ID of the ticket. This attribute is applicable only to accounts on the Employee Support Mode. The value 0 for workspace_id will return tickets from all workspaces, with only global level fields. |
requester_id | number | User ID of the requester |
string | Email address of the requester | |
agent_id | number | ID of the agent to whom the ticket has been assigned |
group_id | number | ID of the group to which the ticket has been assigned |
priority | number | Priority of the ticket |
status | number | Status of the ticket |
impact | number | Ticket impact |
urgency | number | Ticket urgency |
tag | string | Tag that has been associated to the tickets |
due_by | date | Date (YYYY-MM-DD) when the ticket is due to be resolved |
fr_due_by | date | Date (YYYY-MM-DD) when the first response is due |
created_at | date | Ticket creation date (YYYY-MM-DD) |
Custom Fields
Field Type | Type |
---|---|
Number | number |
Checkbox | boolean |
Dropdown | string |
Date | date(YYYY-MM-DD) |
Note:
Queries can be combined using AND or OR.
https://domain.freshservice.com/api/v2/tickets/filter?query="priority: 1 AND status: 2 OR urgency: 3"
Supported operators 1. priority: 1 (priority equal to 1)
2. priority:> 1 (priority greater than or equal to 1)
3. priority :< 1 (priority less than or equal to 1)
Formatting 1. String fields to be enclosed in single quotes ('')
2. Number fields to be given as number without quotes.
3. Date and date_time fields to be enclosed in single quotes('yyyy-mm-dd')
4. only :> and :< are supported for date and date_time fields. Both fields expect input in the same format as 'yyyy-mm-dd'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="priority:3"' |
1. Get the list of Urgent and High priority tickets ('priority:4 OR priority:3')
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="priority:4%20OR%20priority:3"' |
2. Get the second page of Open and Pending tickets ('status:3 OR status:4')
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="status:3%20OR%20status:4"&page=2' |
3. Get the list of Urgent and High priority tickets in Open Status belong to the group_id 11 ('priority:3 AND group_id:11 AND status:2')
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="priority:>3%20AND%20group_id:11%20AND%20status:2"' |
4. Get the list of tickets having Custom Dropdown selected as First Choice or Custom Checkbox false (Custom Fields: custom_dropdown, custom_checkbox) '(custom_dropdown:'First Choice' OR custom_checkbox: true)'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="custom_dropdown:%27First%20Choice%27%20OR%20custom_checkbox:true"' |
5. Get the list of Urgent priority tickets created after a particular day ("priority:4 AND created_at:>'2021-01-01'")
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="%20priorIty:%203%20AND%20created_at:%3E%272020-01-01%27%20AND%20created_at:%3C%272021-01-01%27"' |
6. Get list of tickets with tag abc ("tag: 'abc'")
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?query="tag:%27abc%27"' |
7. Get list of tickets with no agent assigned ('agent_id: null') from a particular workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?workspace_id=2&query="agent_id%3Anull"' |
8. Get the list of Urgent and High priority tickets ('priority:4 OR priority:3') from all accessible workspaces
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/filter?workspace_id=0&query="priority%3A4%20OR%20priority%3A3"' |
View List of Tickets
Use filters to view only specific tickets (those which match the criteria that you choose). By default only tickets that have not been deleted or marked as spam will be returned, unless you use the 'deleted' filter.
Note:
1. By default only tickets that have been created within the past 30 days will be returned. For older tickets, use the updated_since filter.
2. Use 'include' to embed additional details in the response. Each include will consume an additional 2 credits. For example if you embed the stats information you will be charged a total of 3 API credits (1 credit for the API call, and 2 credits for the additional stats embedding).
3. If a workspace_id is not specified as a URL parameter, only tickets from the primary workspace will be included in the response. If workspace_id is specified as 0, tickets from across all workspaces will be included in the response with just the global fields. Applicable only to accounts on the Employee Support Mode.
Filter by | Handle |
---|---|
Predefined filters | /api/v2/tickets?filter=[filter_name] The filters available are new_and_my_open, watching, spam, deleted. |
Requester | /api/v2/tickets?requester_id=[id] /api/v2/tickets?email=[requester_email] Example: /api/v2/tickets?email=superman@freshservice.com /api/v2/tickets?email=bat%2Bman%40gmail.com (URL encoded bat+man@gmail.com) |
Updated since | /api/v2/tickets?updated_since=2015-01-19T02:00:00Z |
Type | For Incidents: /api/v2/tickets?type=Incident For Service Requests: /api/v2/tickets?type=Service+Request |
Workspace | /api/v2/tickets?workspace_id=2 |
Sort by | Handle |
---|---|
asc, desc | /api/v2/tickets?order_type=asc Default sort order type is desc |
Embed | Handle |
---|---|
stats | /api/v2/tickets?include=stats Will return the ticket’s closed_at, resolved_at and first_responded_at time. |
Requester | /api/v2/tickets?include=requester Will return the requester's email, id, mobile, name, and phone. |
Requested For | /api/v2/tickets?include=requested_for Will return details of the user on behalf of whom the request has been raised |
onboarding_context | /api/v2/tickets?include=onboarding_context Will return details of the onboarding data mapped to the ticket |
offboarding_context | /api/v2/tickets?include=offboarding_context Will return details of the offboarding data mapped to the ticket |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets' |
1. Get the first page of a list of tickets that are being watched by the agent whose credentials were used to make this API call.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets?filter=watching' |
2. Get the first page of a list of tickets from the specified requestor. The tickets will be returned in the descending order.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets?requester_id=1230&order_type=desc' |
3. Get the second page (tickets from 11-20) of a list of all tickets.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets?per_page=10&page=2' |
4. Get the first page of a list of tickets that have shown any activity since the 17th of August, 2015.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets?updated_since=2015-08-17' |
5. Get the associated stats information along with the ticket response.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets?include=stats' |
6. Filter tickets based on the following requester email (super+man@gmail.com) which needs to be URL encoded.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets?email=super%2Bman%40gmail.com' |
7. Get the list of all tickets from workspaces to which the user has access.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets?workspace_id=0' |
8. Get the list of tickets from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets?workspace_id=3' |
Update a Ticket
This API lets you make changes to the parameters of a ticket from updating statuses to changing ticket type.
Note:
1. While updating tags, all the tags that need to stay associated with the Ticket should be provided in the PUT request payload.
2. The requested_for_id field can be updated only for Service Request tickets.
3. The workspace_id attribute cannot be updated through the Update operation. It can only be updated through the Move operation.
Query Parameters | Handle |
---|---|
bypass_mandatory | To bypass mandatory fields check while updating the ticket except for requester_id, source. Any business rules trying to mandate certain fields will also be bypassed. All fields configured as mandatory upon closing or resolving the ticket will be skipped while updating the ticket. This can only be passed by an admin. Example: api/v2/ticket/{ticket_id}?bypass_mandatory=true |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Source, Status, and Priorities. These numerical values along with their meanings are given below.
Source Type | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 4 |
Feedback widget | 5 |
Yammer | 6 |
AWS Cloudwatch | 7 |
Pagerduty | 8 |
Walkup | 9 |
Slack | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "priority": 3 }' 'https://domain.freshservice.com/api/v2/tickets/1' |
Update Ticket with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api2.png' -F 'priority=1' -X PUT 'https://domain.freshservice.com/api/v2/tickets/51' |
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 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "spam": false, "email_config_id": null, "fr_escalated": false, "group_id": null, "priority": 1, "requester_id": 1232528431, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Support Needed...", "description": "<div>Details about the issue...</div>", "description_text": "Details about the issue...", "category": null, "sub_category": null, "item_category": null, "custom_fields": { "new_number": null, "time_info": null, "number_test": null }, "id": 51, "type": "Incident", "to_emails": null, "department_id": null, "is_escalated": false, "tags": [], "due_by": "2021-04-22T06:01:08Z", "fr_due_by": "2021-04-15T03:01:08Z", "created_at": "2021-04-12T06:01:08Z", "updated_at": "2021-04-12T06:01:08Z", "resolution_notes":null, "resolution_notes_html":null, "attachments": [ { "id": 368553, "content_type": "image/png", "size": 115399, "name": "api_attach.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api_attach.png", "created_at": "2021-04-12T06:01:08Z", "updated_at": "2021-04-12T06:01:08Z" }, { "id": 368554, "content_type": "image/png", "size": 274688, "name": "api2.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api2.png", "created_at": "2021-04-12T06:26:40Z", "updated_at": "2021-04-12T06:26:40Z" } ], "workspace_id": 3 } } |
Update Ticket with assets
Note:
1. Existing assets, if they are different from what are given in request, are destroyed and the current ones are linked to the ticket. So, all the assets that need to stay associated with the Ticket need to be provided in the PUT/POST calls
2. "assets" key: contains comma (,) separated hash of the assets, each with key display id.
3. When "assets" is included as request parameter in PUT or POST request, the associated assets are returned implicitly in the response.
4. The existing request format to link a single asset ("associate_ci" : { "serial_no " : 123, "name " : "Andrea's Laptop " , "user ": "Andrea "}) will be deprecated soon.
5. If both "assets" and "associate_ci" keys are given in the request, assets key would be considered preferably and associate_ci would be ignored.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "description": "Update ticket with assets", "status": 2, "email": "sample@freshservice.com", "priority": 1, "subject": "Update ticket with assets", "assets": [ { "display_id": 7 }, { "display_id": 8 }]}' 'https://domain.freshservice.com/api/v2/tickets/1' |
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 | { "ticket": { "cc_emails": [], "fwd_emails": [], "reply_cc_emails": [], "spam": false, "email_config_id": null, "fr_escalated": false, "group_id": null, "priority": 1, "requester_id": 1, "requested_for_id": 1000000670, "responder_id": null, "source": 2, "status": 2, "subject": "Update ticket with assets", "description": "Update ticket with assets", "description_text": "Update ticket with assets", "category": null, "sub_category": null, "item_category": null, "custom_fields": {}, "id": 433, "type": "Incident", "to_emails": null, "department_id": null, "is_escalated": false, "tags": [], "due_by": "2020-02-06T17:00:00+05:30", "fr_due_by": "2020-01-30T14:00:00+05:30", "created_at": "2020-01-27T12:08:06Z", "updated_at": "2020-01-27T12:13:39Z", "attachments": [], "workspace_id": 3, "resolution_notes":null, "resolution_notes_html":null, "assets": [ { "name": "Andrea's Laptop", "description": null, "ci_type_id": 25, "impact": 2, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": 2, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 7, "salvage": null }, { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null } ] } } |
Move a Ticket
This API moves a ticket to a different workspace, while also allowing the assigned group and agent to be modified.
Note:
This endpoint is applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X PUT -d '{ "workspace_id": 3, "group_id": 3, "responder_id": 4 }' 'https://domain.freshservice.com/api/v2/tickets/1/move_workspace' |
Delete a Ticket
This API helps you delete a ticket.
Note:
1. Deleted tickets are not permanently lost. You can retrieve them using the Restore Ticket API.
2. When a parent SR is deleted all the child tickets will also be deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/tickets/1' |
Delete a Ticket Attachment
This API helps you delete an attachment from a ticket.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/tickets/1/attachments/1' |
Restore a Ticket
The API mentioned previously. If you deleted some tickets and regret doing so now, this API will help you restore them.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshservice.com/api/v2/tickets/1/restore' |
Create a Child Ticket
This API lets you to create a new child ticket on an existing ticket
Note:
1. Association of child tickets is not available in the Sprout plan.
2. Association of child tickets to a deleted or a spammed ticket is not allowed.
3. Nesting of a child ticket under another child ticket is not supported.
Attribute | Type | Description |
---|---|---|
workspace_id | number | ID of the workspace to which this ticket belongs. This attribute is applicable only to accounts on the Employee Support Mode. The default value is the ID of the parent ticket's workspace. |
name | string | Name of the requester |
requester_id * | number | User ID of the requester. For existing contacts, the requester_id can be passed instead of the requester's email. |
email * | string | Email address of the requester. If no contact exists with this email address in Freshservice, it will be added as a new contact. |
phone * | string | Phone number of the requester. If no contact exists with this phone number in Freshservice, it will be added as a new contact. If the phone number is set and the email address is not, then the name attribute is mandatory. |
subject | string | Subject of the ticket. The default value is null. |
type | string | Helps categorize the ticket according to the different kinds of issues your support team deals with. The default Value is incident. * As of now, API v2 supports only type ‘incident’ |
status * | number | Status of the ticket. |
priority * | number | Priority of the ticket. |
description | string | HTML content of the ticket. |
responder_id | number | ID of the agent to whom the ticket has been assigned |
attachments | array of objects | Ticket attachments. The total size of these attachments cannot exceed 40 MB. |
cc_emails | array of strings | Email address added in the 'cc' field of the incoming ticket email. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
due_by | datetime | Timestamp that denotes when the ticket is due to be resolved. |
email_config_id | number | ID of email config which is used for this ticket. (i.e., support@yourcompany.com/sales@yourcompany.com) |
fr_due_by | datetime | Timestamp that denotes when the first response is due |
group_id | number | ID of the group to which the ticket has been assigned. The default value is the ID of the group that is associated with the given email_config_id |
source * | number | The channel through which the ticket was created. The default value is 2. |
tags | array of strings | Tags that have been associated with the ticket |
department_id | number | Department ID of the requester. |
category | string | Ticket category |
sub_category | string | Ticket sub category |
item_category | string | Ticket item category |
associate_ci | hash | Search for asset and associate with ticket |
urgency | number | Ticket urgency |
impact | number | Ticket impact |
* Refer to the Ticket properties table for supported values. * Any of the five attributes is mandatory. |
Ticket Properties
Every ticket uses certain fixed numerical values to denote its Status and Priorities. These numerical values along with their meanings are given below.
Source Type | Value |
---|---|
1 | |
Portal | 2 |
Phone | 3 |
Chat | 4 |
Feedback widget | 5 |
Yammer | 6 |
AWS Cloudwatch | 7 |
Pagerduty | 8 |
Walkup | 9 |
Slack | 10 |
Status | Value |
---|---|
Open | 2 |
Pending | 3 |
Resolved | 4 |
Closed | 5 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "description": "Details about the issue...", "subject": "Support Needed...", "email": "tom@outerspace.com", "priority": 1, "status": 2, "cc_emails": ["ram@freshservice.com","diana@freshservice.com"], "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/tickets/20/create_child_ticket' |
List All Ticket Fields
Retrieve all the Fields that constitute the Ticket Object
Note:
By default, only global fields and fields from the primary workspace will be returned for accounts on the Employee Support Mode. For fields from other workspaces, use the workspace_id filter.
Change field | Description |
---|---|
id | Unique ID of the Field |
workspace_id | ID of the workspace to which this ticket field belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
created_at | Date time at which the field was added |
updated_at | Date time at which the field was modified |
name | Name of the field |
label | Label of the field for display |
description | Description of the field |
field_type | Indicates if the field is a checkbox, dropdown, text field |
required | True if the field is marked mandatory |
required_for_closure | True if the field is marked mandatory while closing the Release item |
default_field | True if the field is a default field. False if customm |
choices | List of values supported by the field |
nested_fields | contain details of nested fields |
required_for_agents | Set to true if the field is mandatory for Agents |
required_for_customers | Set to true if the field is mandatory in the customer portal |
label_for_customers | Display name for the field (as seen in the customer portal) |
customers_can_edit | Set to true if the field can be updated by customers |
displayed_to_customers | Set to true if the field is displayed in the customer portal |
portal_cc | Applicable only for the requester field. Set to true if customer can add additional requesters to a ticket |
portal_cc_to | Applicable only if portal_cc is set to true. Value will be all when a customer can add any requester to the CC list and company when a customer can add only company contacts to the CC list |
date_only | Applicable only for custom_date field. When ‘Request time information’ is selected, the field date_only returns false and if unchecked, date_only returns true |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/ticket_form_fields' |
1. Get the list of ticket fields from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/ticket_form_fields?workspace_id=2' |
Get Ticket Activites
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/152/activities' |
Time Entries
These APIs help to track exactly how much time an agent has spent on each ticket, start/stop timers and perform a lot of other time tracking and monitoring tasks to ensure that the support team is always performing at its peak efficiency.
Attribute | Type | Description |
---|---|---|
id | Number | Id of the time entry READ-ONLY |
workspace_id | Number | ID of the workspace to which the time entry belongs(inherited from the ticket's workspace). This attribute is applicable only to accounts on the Employee Support Mode. READ-ONLY |
created_at | DateTime | Time at which this time-entry is created READ-ONLY |
updated_at | DateTime | Time at which the time-entry is updated READ-ONLY |
start_time | DateTime | The time at which the time-entry is added. If a timer, which is in stopped state, is started again, this holds date_time at which the timer is started again READ-ONLY |
timer_running | Boolean | Set to true if timer is currently running. Default value is false. At a time, only one timer can be running for an agent across the account |
billable | Boolean | Set as true if the time-entry is billable. Default value is true |
time_spent | String | The total amount of time spent by the timer in hh::mm format. This field cannot be set if timer_running is true. Mandatory if timer_running is false |
executed_at | DateTime | Time at which the timer is executed. Default value (unless given in request) is the time at which timer is added. Should be less than or equal to current date_time |
task_id | Number | Id of the task assigned to the time-entry. Task should be valid on the given ticket and assigned to agent_id |
note | String | Description of the time-entry |
agent_id | Number | The user/agent to whom this time-entry is assigned MANDATORY |
Create a Time Entry
This API helps to create a Time Entry.
Note:
1. If timer_running is not specified in the request, it is considered as false and time_spent is mandatory in this scenario.
2. time_spent can be set only if timer_running is false or not set.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{"time_entry":{"note":"test_entry","time_spent":"03:00","agent_id":1}}' -X POST 'https://domain.freshservice.com/api/v2/tickets/1/time_entries' |
1. Create a time-entry along with time spent value. Timer will not be started
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -d '{"time_entry":{"note":"test_entry","time_spent":"03:00","agent_id":1}}' -X POST 'https://domain.freshservice.com/api/v2/tickets/1/time_entries' |
2. Create a time-entry with timer running
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -d '{"time_entry":{"note":"test_entry","timer_running":true,"agent_id":1}}' -X POST 'https://domain.freshservice.com/api/v2/tickets/1/time_entries' |
View a Time Entry
This API call helps to list a particular Time Entry.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/time_entries/20' |
List All Time Entries of a Ticket
This API helps to view all time entries of a particular ticket.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/time_entries' |
Update a Time Entry
This API can be used to update/modify existing time entry.
Note:
1. For a running timer, time_spent cannot be updated without stopping it.
Attribute | Type | Description |
---|---|---|
id | Number | Id of the time entry READ-ONLY |
workspace_id | Number | Workspace ID of the time entry(inherited from the ticket). This attribute is applicable only to accounts on the Employee Support Mode. READ-ONLY |
created_at | DateTime | Time at which this time-entry is created READ-ONLY |
updated_at | DateTime | Time at which this time-entry is updated READ-ONLY |
start_time | DateTime | The time at which the time-entry is added. If a timer, which is in stopped state, is started again, date_time at which the timer is started again READ-ONLY |
timer_running | Boolean | Cannot update timer_running to the same existing value. |
billable | Boolean | Can be set to true or false |
time_spent | String | The total amount of time spent by the timer in hh::mm format. |
executed_at | DateTime | Time at which the timer is executed. Default value (unless given in request) is the time at which timer is added. Should be less than or equal to current date_time. |
task_id | Number | Id of the task assigned to the time-entry. Task should be valid on the given ticket and should be assigned to the agent_id |
note | String | Description of the time-entry |
agent_id | Number | The user/agent to whom this time-entry is to be assigned MANDATORY |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"time_entry":{"note":"text_update","agent_id":1}}' 'https://domain.freshservice.com/api/v2/tickets/1/time_entries/20' |
Delete a Time Entry
This API can be used to delete an existing Time Entry. Deleted time entries cannot be restored.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X DELETE 'https://domain.freshservice.com/api/v2/tickets/1/time_entries/20' |
Create a Source
This API helps you create a new Ticket Source.
Attribute | Type | Description |
---|---|---|
name | string | Name of the source |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "name": "Source Name" }' -X POST 'https://domain.freshservice.com/api/v2/ticket_fields/sources' |
Service Request
This section lists all API that are related to service requests
Create a Service Request
This API helps you create a service request
Note 1:
The service requested will be created with the requester specified in “email” attribute. If no email is provided, the request is created on behalf of the agent
Note 2:
Fields in the API behave like the agent portal's new service request page. If a field is not visible in self service portal, you can still provide a value for that field using the api. If a field is marked mandatory but not visible in portal in service item, you must provide a value for it in the api.
Request Attrubutes
Attribute | Type | Description |
---|---|---|
quantity | number | Quantity needed by the requested |
requested_for | Email id of the requester on whose behalf the service request is created | |
Email id of the requester | ||
child_items | - | Service items that are included as child items. Provide the display id as service_item_id for each child item. |
custom_fields | - | Values of custom fields present in the service item form |
Response Attrubutes
Attribute | Type | Description |
---|---|---|
Ticket Attributes | - | Refer to Ticket attributes for complete list here |
requested_items | - | Items requested as part of service request |
approval_status | number | Current approval status of the service request. ‘1’ if approved, ‘2’ if rejected |
approval_status_name | string | Display name of the approval status |
custom_fields | - | Custom fields present in the ticket form |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{"email": "tom@outerspace.com", “quantity” : 1 }' -X POST 'https://domain.freshservice.com/api/v2/service_catalog/items/1/place_request' |
Create a Child Service Request
This API helps you to create a new child ticket on an existing ticket
Note 1:
Association of child Service Request to a deleted or a spammed ticket is not allowed.
Note 2:
Nesting of a child Service Request under another child Service Request is not supported.
Request Attributes
Attribute | Type | Description |
---|---|---|
quantity | number | Quantity needed by the requested |
requested_for | Email id of the requester on whose behalf the service request is created | |
Email id of the requester | ||
child_items | - | Service items that are included as child items. Provide the display id as service_item_id for each child item. |
custom_fields | - | Values of custom fields present in the service item form |
parent_ticket_id | number | Display ID of the parent Service Request/Case/Query/Issue/Request/Incident/Major Incident |
Response Attributes
Attribute | Type | Description |
---|---|---|
Ticket Attributes | - | Refer to Ticket attributes for complete list here |
requested_items | - | Items requested as part of service request |
approval_status | number | Current approval status of the service request. ‘1’ if approved, ‘2’ if rejected |
approval_status_name | string | Display name of the approval status |
custom_fields | - | Custom fields present in the ticket form |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{"email": "tom@outerspace.com", “quantity” : 1 , "parent_ticket_id":17894}' -X POST 'https://domain.freshservice.com/api/v2/service_catalog/items/1/place_request' |
View Requested Items of a Service Request
This api helps you to view requested items attached to a service request
Attribute | Type | Description |
---|---|---|
id | number | Unique id of the requested item |
created_at | datetime | Timestamp at which the requested item was attached to service request |
updated_at | datetime | Timestamp at which the requested item was updated in the service request |
quantity | number | Number of units of the item needed by the requester. By default it is 1 |
stage | number | Current stage of the requested item |
loaned | boolean | Indicated whether the requested item is a loaner item |
cost_per_request | number | Cost of the requested service item |
remarks | string | Remarks related to a requested item |
delivery_time | number | Estimated delivery time (in hrs) |
is_parent | boolean | Boolean indicating whether this is the parent service item |
service_item_id | number | Display id of service item unique to your account |
Stages
Stage | Value |
---|---|
Requested | 1 |
Delivered | 2 |
Cancelled | 3 |
Fulfilled | 4 |
Partially Fulfilled | 5 |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/requested_items' |
Update Requested Items of a Service Request
This api helps you to update the requested items attached to a service request
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"quantity":2, "stage":2, "custom_fields":{"additional_property_1": "value1"}}' 'https://domain.freshservice.com/api/v2/tickets/1/requested_items/1' |
Approvals
This section lists all API that can be used to create, edit or otherwise manipulate Service Request Approvals.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the approval |
created_at | datetime | Approval creation timestamp |
updated_at | datetime | Approval updated timestamp |
approver_id | number | User ID of the approver |
approver_name | string | Name of the approver |
approval_type | number | Helps define the type of approval in case there are more than one approvers |
user_id | number | User ID of the initiator of the approval |
user_name | string | Name of the initiator of the approval |
level | number | Indicates the level information for multi-level approvals |
approval_status | hash | Status ID and Name of the approval |
delegatee | hash | User ID and Name of the delegatee for the approval |
latest_remark | string | Remarks given by the approver |
email_content | string | HTML content of the approval email (only available for “Request Approval” and “View an Approval” APIs) |
Approval Properties
Approvals use certain fixed numerical values to denote its status and types. These numerical values along with their meanings are given below:
Approval Type | Value |
---|---|
To be approved by Everyone | 1 |
To be approved by Anyone | 2 |
To be approved by Majority | 3 |
To be approved by First Responder | 4 |
Status | Value |
---|---|
Requested | 0 |
Approved | 1 |
Rejected | 2 |
Cancelled | 3 |
Request Approval For A Service Request
Send a Service Request for approval
Note: "email_content" is an optional parameter for sending approval. If not provided, the default approval notification will be sent to approvers.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{"approver_id":39479, "approval_type": 2,"email_content": "Your approval email body goes here."}' -X POST 'https://domain.freshservice.com/api/v2/tickets/20/approvals' |
List All Ticket Approvals
Retrieve all approvals on a Service Request with the given ID from Freshservice.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/20/approvals' |
View An Approval
Retrieve an approval on a Service Request with the given ID from Freshservice
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/20/approvals/1' |
Cancel An approval
Cancel an existing approval on a Service Request
Note: You can only update the approval status of a request to "cancelled" state through this API. Any other status change will be done based on the approver's action.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "approval_status":{ "id":3 }}' -X PUT 'https://domain.freshservice.com/api/v2/tickets/20/approvals/1' |
Send Reminder For An Approval
Resends a reminder for a specific Approval raised for the ticket
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '' -X PUT 'https://domain.freshservice.com/api/v2/tickets/20/approvals/1/remind' |
Tasks
This section lists all API that can be used to create, edit or otherwise manipulate Ticket Tasks.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the task. |
agent_id | number | Id of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | DateTime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
created_at | DateTime | Timestamp at which the task was created |
updated_at | DateTime | Timestamp at which the task was updated |
closed_at | DateTime | Timestamp at which the task was closed |
group_id | number | Unique ID of the group to which the task is assigned |
Create a Task
Create a new task on a ticket request in freshservice
Attribute | Type | Description |
---|---|---|
workspace_id | number | ID of the workspace to which the task belongs. This attribute is applicable only to accounts on the Employee Support Mode. The default value is the ID of the workspace of the ticket. |
agent_id | number | ID of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | datetime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
group_id | number | Unique ID of the group to which the task is assigned |
1 2 3 4 5 6 7 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "due_date": "2020-04-03T10:26:13.067Z", "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!", "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/tickets/1/tasks' |
View a Task
Retrieve a task on a Ticket with the given ID from Freshservice
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/tasks/1' |
View all Tasks
Retrieve the tasks on a Ticket with the given ID from Freshservice.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/1/tasks' |
Update a Task
Update an existing task on an existing Ticket in Freshservice
1 2 3 4 5 6 7 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "status": 3, "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!", "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/tickets/1/tasks/1' |
Delete a Task
Delete the task on a Ticket with the given ID from Freshservice
Note: Deleted tasks are permanently lost. You can't retrieve them once it's get deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/tickets/1/tasks/1' |
CSAT
This section lists all API that can be used to view Ticket CSAT Response.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the survey response. |
overall_rating_text | string | Overall feedback text of the survey response |
overall_rating | number | Feedback code of the survey response |
primary_question | string | Primary survey question |
questionnaire_responses | array of hashes | Contains the list of responded questions and answer(s) chosen.
|
created_at | DateTime | Timestamp at which the survey response was created |
updated_at | DateTime | Timestamp at which the survey response was updated |
CSAT Response
Retrieve a csat response of a Ticket with the given ID from Freshservice
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/1/csat_response' |
Conversations
Conversations consist of replies as well as public and private notes added to a ticket. Notes are non-invasive ways of sharing updates about a ticket amongst agents and requesters. Private notes are for collaboration between agents and are not visible to the requester. Public notes are visible to, and can be created by, both requesters and agents.
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments associated with the conversation. The total size of all of a ticket's attachments cannot exceed 40 MB. |
body | string | Content of the conversation in HTML |
body_text | string | Content of the conversation in plain text |
id | number | ID of the conversation |
incoming | boolean | Set to true if a particular conversation should appear as being created from the outside (i.e., not through the web portal) |
to_emails | array of strings | Email addresses of agents/users who need to be notified about this conversation |
private | boolean | Set to true if the note is private |
source | number | Denotes the type of the conversation. |
support_email | string | Email address from which the reply is sent. For notes, this value will be null. |
ticket_id | number | ID of the ticket to which this conversation is being added |
user_id | number | ID of the agent/user who is adding the conversation |
created_at | datetime | Conversation creation timestamp |
updated_at | datetime | Conversation updated timestamp |
Conversation Properties
Conversations use certain fixed numerical values to denote their source. These numerical values along with their meanings are given below.
Note : This source attribute will be returned in the response body of the List All Conversations of a Ticket and View a ticket (only when 'include=conversation' is passed in url) endpoints.
Source Type | Value |
---|---|
0 | |
form | 1 |
note | 2 |
status | 3 |
meta | 4 |
feedback | 5 |
forward_email | 6 |
Create a Reply
Attribute | Type | Description |
---|---|---|
body * | string | Content of the note in HTML format |
attachments | array of attachment objects | Attachments. The total size of all the ticket's attachments (not just this note) cannot exceed 40 MB. |
from_email | string | The email address from which the reply is sent. By default the global support email will be used. |
user_id | number | ID of the agent/user who is adding the note |
cc_emails | array of strings | Email address added in the 'cc' field of the outgoing ticket email. |
bcc_emails | array of strings | Email address added in the 'bcc' field of the outgoing ticket email. |
* Mandatory attribute |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "body":"We are working on this issue. Will keep you posted." }''https://domain.freshservice.com/api/v2/tickets/141/reply' |
Reply to a Ticket With Attachments
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api2.png' -F 'body=We are working on this issue. Will keep you posted.' -X POST 'https://domain.freshservice.com/api/v2/tickets/51/reply' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "conversation": { "id": 4289865, "user_id": 1232463344, "from_email": "user@yourcompany.com", "cc_emails": [], "bcc_emails": [], "body": "<div>We are working on this issue. Will keep you posted.</div>", "body_text": "We are working on this issue. Will keep you posted.", "ticket_id": 51, "to_emails": [ "tom@outerspace.com" ], "attachments": [ { "id": 368557, "content_type": "image/png", "size": 274688, "name": "api2.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api2.png", "created_at": "2021-04-12T07:41:03Z", "updated_at": "2021-04-12T07:41:04Z" } ], "created_at": "2021-04-12T07:41:04Z", "updated_at": "2021-04-12T07:41:04Z" } } |
Create a Note
Note: By default, any note that you add will be private. If you wish to add a public note, set the parameter to false.
Attribute | Type | Description |
---|---|---|
attachments | array of attachment objects | Attachments. The total size of all the ticket's attachments (not just this note) cannot exceed 40 MB. |
body * | string | Content of the note in HTML format |
incoming | boolean | Set to true if a particular note should appear as being created from the outside (i.e., not through the web portal). The default value is false |
notify_emails | array of strings | Email addresses of agents/users who need to be notified about this note |
private | boolean | Set to true if the note is private. The default value is true. |
user_id | number | ID of the agent/user who is adding the note |
* Mandatory attribute |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "body":"Hi tom, Still Angry", "private":false }' 'https://domain.freshservice.com/api/v2/tickets/265/notes' |
Create a Note With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'body=Hi tom, Still Angry' -F 'private=false' -X POST 'https://domain.freshservice.com/api/v2/tickets/51/notes' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "conversation": { "id": 4289856, "incoming": false, "private": false, "user_id": 1232463344, "support_email": null, "body": "<div>Hi tom, Still Angry</div>", "body_text": "Hi tom, Still Angry", "ticket_id": 51, "to_emails": [], "attachments": [ { "id": 368555, "content_type": "image/png", "size": 115399, "name": "api_attach.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api_attach.png", "created_at: "2021-04-12T06:44:09Z", "updated_at": "2021-04-12T06:44:09Z" } ], "created_at": "2021-04-12T06:44:09Z", "updated_at": "2021-04-12T06:44:09Z" } } |
Update a Conversation
Note:
Only public & private notes can be edited.
Attribute | Type | Description |
---|---|---|
body | string | Content of the note in HTML format |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "body":"Can you provide some screenshots?" } 'https://domain.freshservice.com/api/v2/conversations/5' |
Update a conversation With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api2.png' -F 'body=Can you provide some screenshots?' -X PUT 'https://domain.freshservice.com/api/v2/conversations/4289856' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | { "conversation": { "id": 4289856, "incoming": false, "private": false, "user_id": 1232463344, "support_email": null, "body": "Can you provide some screenshots?", "body_text": "Can you provide some screenshots?", "ticket_id": 51, "to_emails": [], "attachments": [ { "id": 368555, "content_type": "image/png", "size": 115399, "name": "api_attach.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api_attach.png", "created_at": "2021-04-12T06:44:09Z", "updated_at": "2021-04-12T06:44:09Z" }, { "id": 368556, "content_type": "image/png", "size": 274688, "name": "api2.png", "attachment_url": "https://s3.amazonaws.com/cdn.freshgenie.com/data/helpdesk/attachments/production/19852343/original/api2.png", "created_at": "2021-04-12T06:48:53Z", "updated_at": "2021-04-12T06:48:53Z" } ], "created_at": "2021-04-12T06:44:09Z", "updated_at": "2021-04-12T06:48:53Z" } } |
Delete a Conversation
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/conversations/5' |
Delete a Conversation Attachment
This API helps you delete an attachment from a conversation.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/conversations/1/attachments/1' |
List All Conversations of a Ticket
This API helps you List All Conversations of a Ticket.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets/20/conversations' |
1. This ticket's conversation has more than 30 entries. This request returns the second page (entries from 31 to 60).
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/tickets/1/conversations?page=2' |
Problems
This section lists all API that can be used to create, edit or otherwise manipulate Problem.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the Problem Read-Only |
workspace_id | number | ID of the workspace that the problem belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
agent_id | number | Unique identifier of the agent to whom the Problem is assigned |
requester_id * | number | Unique identifier of the initiator of the problem. Mandatory |
group_id | number | Unique identifier of the agent group to which the Problem is assigned |
description * | string | HTML content of the problem. Description and description_html should not be passed together Mandatory |
description_text | string | Plain text content of the problem Read-Only |
priority * | number | Priority of the Problem 1-Low, 2-Medium, 3-High, 4-Urgent |
status * | number | Status identifier of the Problem. 1-Open, 2-Change Requested, 3-Closed Mandatory |
impact * | number | Impact of the Problem. 1-Low, 2-Medium, 3-High Mandatory |
known_error | boolean | States that the problem is known issue or not. true or false |
subject * | string | Subject of the Problem Mandatory |
due_by * | DateTime | Timestamp at which Problem due ends Mandatory |
department_id | number | Unique ID of the department initiating the Problem |
category | string | Category of the Problem |
sub_category | string | Sub-category of the Problem |
item_category | string | Item of the Problem |
created_at | DateTime | Timestamp at which Problem was created |
updated_at | DateTime | Timestamp at which Problem was last updated |
associated_change | number | Unique ID of the Change associated with the Problem Read-Only |
custom_fields | Hash | Key value pairs containing the names and values of custom fields. |
analysis_fields | Hash | Key value pairs containing the names and values of Problem Cause, Problem Symptom and Problem Impact |
assets | hash | List of assets associated with the problem |
Create a Problem
Create a new problem request in Freshservice
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 | curl -v -u api_key:X -H "Content-Type: application/json" -d ' { "subject": "Unable to reach email server", "email": "sample@freshservice.com", "description": "<div>Hi guys, <br/><br/>We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.<br/><br/>Regards<br/> Rachel<br/> </div>", "due_by": "2020-07-20T16:18:46Z", "priority": 2, "status": 2, "impact": 1, "category": "Hardware", "sub_category": "Peripherals", "item_category": "Router", "agent_id": 1, "group_id": 1, "department_id": 1, "custom_fields": { "sample_text_field": "Sample Text" }, "analysis_fields": { "problem_cause": { "description": "Problem cause description" }, "problem_symptom": { "description": "Problem symptom description" }, "problem_impact": { "description": "Problem impact description" } }, "workspace_id": 3 } ' -X POST 'https://domain.freshservice.com/api/v2/problems' |
Create Problem with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'subject=Unable to reach email server' -F 'description=Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.' -F 'priority=2' -F 'status=2' -F 'impact=1' -F 'due_by=2021-04-21T16:18:46Z' -F 'email=user@yourcompany.coom' -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'workspace_id=3' -X POST 'https://domain.freshservice.com/api/v2/problems' |
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 | { "problem": { "id": 47, "agent_id": null, "description": "<div>Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.</div>", "description_text": "Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.", "requester_id": 1232463344, "subject": "Unable to reach email server", "group_id": null, "priority": 2, "impact": 1, "status": 2, "due_by": "2021-04-21T16:18:46Z", "known_error": false, "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2021-04-12T11:22:54Z", "updated_at": "2021-04-12T11:22:54Z", "workspace_id": 3, "associated_change": null, "assets": [] "custom_fields": { "requester": null, "subject": null, "description": null, "status": null, "priority": null, "impact": null, "due_by": null, "group": null, "agent": null, "department": null, "category": null }, "analysis_fields": {} } } |
Create Problem with assets
Note:
"assets" key: contains comma (,) separated hash of the assets, each with key display id.
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 | curl -v -u api_key:X -H "Content-Type: application/json" -d ' { "subject": "Unable to reach email server", "email": "sample@freshservice.com", "description": "<div>Hi guys, <br/><br/>We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.<br/><br/>Regards<br/> Rachel<br/> </div>", "due_by": "2020-07-20T16:18:46Z", "priority": 2, "status": 2, "impact": 1, "category": "Hardware", "sub_category": "Peripherals", "item_category": "Router", "agent_id": 1, "group_id": 1, "department_id": 1, "workspace_id": 2, "custom_fields": { "sample_text_field": "Sample Text" }, "analysis_fields": { "problem_cause": { "description": "Problem cause description" }, "problem_symptom": { "description": "Problem symptom description" }, "problem_impact": { "description": "Problem impact description" } }, "assets": [ { "display_id": 8 }, { "display_id": 9 } ] } ' -X POST 'https://domain.freshservice.com/api/v2/problems' |
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 | { "problem": { "id": 1, "agent_id": null, "requester_id": 1, "description": "<div>Hi guys, <br/><br/>We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.<br/><br/>Regards<br/> Rachel<br/> </div> ", "description_text": "Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here. Regards Rachel", "due_by": "2020-07-20T16:18:46Z", "subject": "Unable to reach email server", "group_id": null, "priority": 2, "impact": 1, "status": 2, "known_error": false, "department_id": null, "category": "Hardware", "sub_category": "Peripherals", "item_category": "Router", "created_at": "2020-02-04T05:50:57Z", "updated_at": "2020-02-04T05:50:57Z", "workspace_id": 3, "associated_change": 1, "custom_fields": { "sample_text_field": "Sample Text" }, "analysis_fields": { "problem_cause": { "description": "<div> Problem cause description </div>", "description_text": "Problem cause description" }, "problem_symptom": { "description": "<div> Problem symptom description </div>", "description_text": "Problem symptom description" }, "problem_impact": { "description": "<div> Problem impact description </div>", "description_text": "Problem impact description" } }, "assets": [ { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null }, { "name": "Logitech Mouse", "description": null, "ci_type_id": 4, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 9, "salvage": null } ] } } |
View a Problem
Retrieve the problem with the given ID from Freshservice
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com//api/v2/problems/1' |
View List of Problems
Retrieve a list of all Problems in Freshservice
Note:
If a workspace_id is not specified as a URL parameter, only problems from the primary workspace will be included in the response. If workspace_id is specified as 0, problems from across all workspaces will be included in the response with just the global fields. Applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/problems' |
1. Get the list of all problems from workspaces to which the user has access.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/problems?workspace_id=0' |
2. Get the list of problems from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/problems?workspace_id=3' |
Update a Problem
Update an existing Problem in Freshservice
Note:
The workspace_id attribute cannot be updated through the Update operation. It can only be updated through the Move operation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "subject": "Unable to reach email server", "email": "sample@freshservice.com", "description": "<div>Hi guys, <br/><br/>We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.<br/><br/>Regards<br/> Rachel<br/> </div>", "due_by": "2020-07-20T16:18:46Z", "priority": 2, "status": 3, "impact": 2, "category": "Hardware", "sub_category": "Peripherals", "item_category": "Router", "agent_id": 1, "group_id": 1, "department_id": 1, "custom_fields": { "sample_text_field": "Sample Text" }, "analysis_fields": { "problem_cause": { "description": "Problem cause description" }, "problem_symptom": { "description": "Problem symptom description" }, "problem_impact": { "description": "Problem impact description" } } }' 'https://domain.freshservice.com/api/v2/problems/1' |
Update Problem with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'subject=Unable to reach email server' -F 'description=Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.' -F 'priority=2' -F 'status=2' -F 'impact=1' -F 'due_by=2021-04-21T16:18:46Z' -F 'email=fuser@yourcompany.com' -F 'attachments[]=@/Users/user/Desktop/api2.png' -X PUT 'https://domain.freshservice.com/api/v2/problems/47' |
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 | { "problem": { "id": 47, "agent_id": null, "description": "Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.", "description_text": "Hi guys, We have been facing issues when we try to reach Email Server 3. Looks like there is something wrong here.", "requester_id": 1232463344, "subject": "Unable to reach email server", "group_id": null, "priority": 2, "impact": 1, "status": 2, "due_by": "2021-04-21T16:18:46Z", "known_error": false, "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2021-04-12T11:22:54Z", "updated_at": "2021-04-12T11:22:54Z", "workspace_id": 3, "assets": [], "associated_change": null, "custom_fields": { "requester": null, "subject": null, "description": null, "status": null, "priority": null, "impact": null, "due_by": null, "group": null, "agent": null, "department": null, "category": null }, "analysis_fields": {} } } |
Move a Problem
This API moves a problem to a different workspace, while also allowing the assigned group and agent to be modified.
Note:
This endpoint is applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X PUT -d '{ "workspace_id": 3, "group_id": 3, "owner_id": 4 }' 'https://domain.freshservice.com/api/v2/problems/1/move_workspace' |
Delete a Problem
Delete the Problem with the given ID from Freshservice
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/problems/1' |
Restore a Problem
The API mentioned previously. If you deleted some problems and regret doing so now, this API will help you restore them.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshservice.com/api/v2/problems/1/restore' |
List All Problem Fields
Retrieve all the Fields that constitute the Problem Object
Note:
By default, only global fields and fields from the primary workspace will be returned for accounts on the Employee Support Mode. For fields from other workspaces, use the workspace_id filter.
Problem field | Description |
---|---|
id | Unique ID of the Field |
workspace_id | ID of the workspace to which this problem field belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
created_at | Date time at which the field was added |
updated_at | Date time at which the field was modified |
name | Name of the field |
label | Label of the field for display |
description | Description of the field |
field_type | Indicates if the field is a checkbox, dropdown, text field |
required | True if the field is marked mandatory |
required_for_closure | True if the field is marked mandatory while closing the problem item |
default_field | True if the field is a default field. False if customm |
choices | List of values supported by the field |
nested_fields | contain details of nested fields |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/problem_form_fields' |
1. Get the list of problem fields from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/problem_form_fields?workspace_id=2' |
Notes
This section lists all API that can be used to create, edit or otherwise manipulate Problem Notes.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the note. Read-Only |
user_id | number | Id of the user who created the note.Read-Only |
body | string | The body of the note in HTML format.Mandatory |
body_text | string | The body of the note in plain text format. Read-Only |
notify_emails | Array of strings | Addresses to which the note must be notified to |
created_at | date | Date time at which the note was created. |
updated_at | date | Date time at which the note was updated. |
Create a note
Create a new note on a problem request in freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "body": "<div> body of the problem note </div> "}' -X POST 'https://domain.freshservice.com/api/v2/problems/1/notes' |
View a note
Retrieve a note on a Problem request with the given ID from Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/problems/1/notes/1' |
View all notes
Retrieve a list of all notes on a Problem request with the given ID from Freshservice.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/problems/1/notes' |
Update a note
Update an existing note on an existing Problem request in Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "body":<div> updated problem note </div> }' 'https://domain.freshservice.com/api/v2/problems/1/notes/1' |
Delete a note
Delete the note on a Problem request with the given ID from Freshservice.
Note: Deleted Notes are permanently lost. You can't retrieve them once it's get deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/problems/1/notes/1' |
Time Entries
These APIs help you track exactly how much time you've spent on each Problem*, start/stop timers and perform a whole other lot of time tracking and monitoring tasks to ensure that your support team is always performing at peak efficiency.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the time entry Read-Only |
workspace_id | number | ID of the workspace to which the time entry belongs(inherited from the problem's workspace). This attribute is applicable only to accounts on the Employee Support Mode. |
task_id | number | Unique ID of the task associated with the time entry |
executed_at | datetime | Date time at which the time entry is executed |
billable | boolean | True if billable, false otherwise. |
note | string | Description note of the time entry |
start_time | datetime | Time at which the timer started |
timer_running | boolean | True if timer is running, false otherwise |
time_spent | string | Duration of time spent in seconds |
agent_id | number | Unique ID of the user who created the time entry Mandatory |
created_at | datetime | Timestamp at which the time entry is created Read-Only |
updated_at | datetime | Time stamp at which the time entry is updated Read-Only |
Create a Time Entry
Create a new time entry on a problem request in freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{"note":"test_entry","time_spent":"03:00","agent_id":1,"billable":true}' -X POST 'https://domain.freshservice.com/api/v2/problems/1/time_entries' |
View a Time Entry
Retrieve a time entry on a Problem request with the given ID from Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/problems/1/time_entries/1' |
List All Time Entries
Retrieve the time entries on a Problems request with the given ID from Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/problems/1/time_entries' |
Update a Time Entry
Update an existing time entry on an existing Problem request in Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"note":"time entry update","billable":false}' 'https://domain.freshservice.com/api/v2/problems/1/time_entries/1' |
Delete a Time Entry
Delete the time entry on a Problem request with the given ID from Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X DELETE 'https://domain.freshservice.com/api/v2/problems/1/time_entries/1' |
Tasks
This section lists all API that can be used to create, edit or otherwise manipulate Problem Tasks.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the task. |
agent_id | number | Id of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | DateTime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
created_at | DateTime | Timestamp at which the task was created |
updated_at | DateTime | Timestamp at which the task was updated |
closed_at | DateTime | Timestamp at which the task was closed |
group_id | number | Unique ID of the group to which the task is assigned |
Create a Task
Create a new task on a problem in freshservice
Attribute | Type | Description |
---|---|---|
workspace_id | number | ID of the workspace to which the task belongs. This attribute is applicable only to accounts on the Employee Support Mode. The default value is the ID of the workspace of the problem. |
agent_id | number | ID of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | datetime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
group_id | number | Unique ID of the group to which the task is assigned |
1 2 3 4 5 6 7 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "due_date": "2020-04-27T13:23:20.813Z", "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!", "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/problems/1/tasks' |
View a Task
Retrieve a task on a Problem with the given ID from Freshservice
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/problems/1/tasks/1' |
View all Tasks
Retrieve the tasks on a Problem with the given ID from Freshservice
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/problems/1/tasks' |
Update a Task
Update an existing task on an existing Problem in Freshservice
1 2 3 4 5 6 7 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "status": 3, "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!", "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/problems/1/tasks/1' |
Delete a Task
Delete the task on a Problem with the given ID from Freshservice
Note: Deleted tasks are permanently lost. You can't retrieve them once it's get deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/problems/1/tasks/1' |
Changes
This section lists all API that can be used to create, edit or otherwise manipulate changes. You can create filters to sift through changes and to find the ones you want.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the change Read-Only |
workspace_id | number | ID of the workspace that the change belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
agent_id | number | Unique identifier of the agent to whom the change is assigned. |
description | string | HTML content of the change. Description and description_html should not be passed together |
description_text | string | Plain text content of the change Read-Only |
requester_id | number | Unique identifier of the initiator of the change. Mandatory |
group_id | number | Unique identifier of the agent group to which the change is assigned. |
priority * | number | Priority of the change. |
impact * | number | Impact of the change. |
status * | number | Status of the change. |
risk * | number | Risk of the change. |
change_type * | number | Type of the change. |
approval_status | number | Approval status of the change. |
planned_start_date | number | Timestamp at which change is starting. |
planned_end_date | number | Timestamp at which change is ending. |
subject | string | change subject. |
department_id | number | Unique ID of the department initiating the change. |
category | String | Category of the change |
sub_category | String | Sub-category of the change |
item_category | String | Item of the change |
custom_fields | Hash | Key value pairs containing the names and values of custom fields. |
maintenance_window | Hash | Details about the associated Maintenance Window. |
blackout_window | Hash | Details about the overlapping Blackout Window. Read-Only |
created_at | DateTime | Timestamp at which change was created. |
updated_at | DateTime | Timestamp at which change was last updated. |
assets | hash | List of assets associated with the change |
impacted_services | hash | List of Impacted Services associated with the change |
* Refer Change properties table for supported values. |
Change Properties
With every change having certain fixed values to denote Source, State and Priorities, the numerical value for each state (open, closed etc.) is given below
Status | Value |
---|---|
Open | 1 |
Planning | 2 |
Approval | 3 |
Pending Release | 4 |
Pending Review | 5 |
closed | 6 |
Priority | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Impact | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Change Type | Value |
---|---|
Minor | 1 |
Standard | 2 |
Major | 3 |
Emergency | 4 |
Risk | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Very High | 4 |
Create a Change
Create a new Change request in Freshservice
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "description": "<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "subject": "Getting ES3 back up to speed", "email": "tom@outerspace.com", "priority": 1, "status": 1, "group_id": 1, "risk": 1, "change_type": 1, "impact": 1, "planned_start_date": "2019-03-20T16:18:46Z", "planned_end_date": "2019-03-23T16:18:46Z", "department_id": 1, "agent_id": 1, "maintenance_window": {"id": 1}, "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/changes' |
Create a Change With Custom Fields
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "description": "<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "subject": "Getting ES3 back up to speed", "email": "tom@outerspace.com", "priority": 1, "status": 1, "group_id": 1, "risk": 1, "change_type": 1, "impact": 3, "planned_start_date": "2019-03-20T16:18:46Z", "planned_end_date": "2019-03-23T16:18:46Z", "department_id": 1, "agent_id": 1, "maintenance_window": {"id": 1}, "custom_fields" : { "custom_text" : "This is a custom text box" }, "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/changes' |
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 | { "change": { "id": 1, "agent_id": 1, "description":"<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "description_text": "Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel",, "workspace_id": 3, "requester_id": 1, "group_id": 1, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2021-01-10T17:47:11.030Z", "planned_end_date": "2021-02-10T17:47:11.030Z", "subject": "Getting ES3 back up to speed", "department_id": 1, "category": null, "sub_category": null, "item_category": null, "created_at": "2019-07-11T06:30:45Z", "updated_at": "2019-07-11T06:30:45Z", "custom_fields": { "custom_text": "This is a custom text box", "custom_paragraph": null, "custom_checkbox": false, "custom_number": null, "custom_dropdown": null, "custom_date": null, "custom_decimal": null }, "planning_fields": {}, "assets": [], "maintenance_window": { "id": 1, "name": "Weekly Maintenance Window", "description": "Weekly Maintenance Window.", "window_start_date": "2021-01-10T17:47:11.030Z", "window_end_date": "2021-02-10T17:47:11.030Z" }, "blackout_window": { "id": 1, "name": "Monthly Downtime", "description": "Monthly Downtime.", "window_start_date": "2021-01-10T17:47:11.030Z", "window_end_date": "2021-02-10T17:47:11.030Z" } } } |
Create Change with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'subject=Getting ES3 back up to speed' -F 'description=Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel' -F 'priority=2' -F 'status=2' -F 'impact=1' -F 'change_type=1' -F 'email=user@yourcompany.com' -F 'risk=1' -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'planned_start_date=2021-04-20T16:18:46Z' -F 'planned_end_date=2021-05-20T16:18:46Z' -F 'workspace_id=3' -X POST 'https://domain.freshservice.com/api/v2/changes' |
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 | { "change": { "id": 25, "agent_id": null, "description": "<div>Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel</div>", "description_text": "Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel", "maintenance_window": {}, "blackout_window": {}, "workspace_id": 3, "requester_id": 1232463344, "group_id": null, "priority": 2, "impact": 1, "status": 2, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2021-04-20T16:18:46Z", "planned_end_date": "2021-05-20T16:18:46Z", "change_window_id": null, "subject": "Getting ES3 back up to speed", "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2021-04-12T16:59:07Z", "updated_at": "2021-04-12T16:59:07Z", "custom_fields": { "requester": null, "subject": null, "change_type": null, "status": null, "priority": null, "impact": null, "risk": null, "group": null, "agent": null, "description": null, "planned_start_date": null, "planned_end_date": null, "department": null, "category": null, "change_window": null }, "planning_fields": { "custom_fields": {} }, "assets": [] } } |
Create Change with assets
Note:
"assets" key: contains comma (,) separated hash of the assets, each with key display id.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "description": "<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "subject": "Getting ES3 back up to speed", "email": "tom@outerspace.com", "priority": 1, "status": 1, "group_id": 1, "risk": 1, "change_type": 1, "impact": 3, "planned_start_date": "2019-03-20T16:18:46Z", "planned_end_date": "2019-03-23T16:18:46Z", "department_id": 1, "agent_id": 1, "maintenance_window": {"id": 1}, "assets": [{ "display_id": 8 }, { "display_id": 9 }], "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/changes' |
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 | { "change": { "id": 1, "agent_id": 1, "description":"<div>Hi Team, <br/><br/> One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. <br/><br/>Regards<br/> Rachel<br/> </div>", "description_text": "Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel",, "workspace_id": 3, "requester_id": 1, "group_id": 1, "priority": 1, "impact": 1, "status": 1, "risk": 1, "change_type": 1, "approval_status": 4, "planned_start_date": "2019-03-20T16:18:46Z", "planned_end_date": "2019-03-23T16:18:46Z", "subject": "Getting ES3 back up to speed", "department_id": 1, "category": null, "sub_category": null, "item_category": null, "created_at": "2019-07-11T06:30:45Z", "updated_at": "2019-07-11T06:30:45Z", "custom_fields": { "custom_text": null, "custom_paragraph": null, "custom_checkbox": false, "custom_number": null, "custom_dropdown": null, "custom_date": null, "custom_decimal": null, "planning_fields": {}, "maintenance_window": { "id": 4, "name": "Details about the associated Maintenance Window", "description": "Details about the associated Maintenance Window.", "window_start_date": "2021-01-10T17:47:11.030Z", "window_end_date": "2021-01-10T17:47:11.030Z" }, "blackout_window": { "id": 1, "name": "Details about the overlapping Blackout Window", "description": "Details about the overlapping Blackout Window.", "window_start_date": "2021-01-10T17:47:11.030Z", "window_end_date": "2021-01-10T17:47:11.030Z" }, "assets": [ { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null }, { "name": "Logitech Mouse", "description": null, "ci_type_id": 4, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 9, "salvage": null } ] } } |
View a Change
Use 'include' to embed additional details in the response. Each include will consume an additional credit. For example if you embed the requester and company information you will be charged a total of 3 API credits for the call.
Note:
By default, stats field will not be included in the response. They can be retrieved via the embedding functionality.
Embed | Handle |
---|---|
stats | /api/v2/changes/[id]?include=stats Will return the change’s closed_at, assigned_at and approval_at time |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/changes/1' |
1. Get the associated stats information along with the change response.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes/1?include=stats' |
View List of Changes
Use filters to view changes based on the criteria that you choose. By default only changes that have not been deleted or marked as spam will be returned unless you use the 'deleted' filter.
Note:
1. By default, only changes from the primary workspace will be returned for accounts on the Employee Support Mode. For Changes from other workspaces, use the workspace_id query parameter.
2. If a workspace_id is not specified as a URL parameter, only changes from the primary workspace will be included in the response. If workspace_id is defined as 0, changes from across all workspaces will be included in the response with just the global fields. Applicable only to accounts in the Employee Support Mode.
3. The view and query parameters can only be used in isolation in an API request and cannot be used together.
Filter by | Handle |
---|---|
Query | /api/v2/changes?query="priority:4%20OR%20priority:3" Filter your results using the query parameter. Use Freshservice fields to filter out records based on field values. Query Format - "(change_field:integer OR change_field:'string') AND change_field:boolean" |
View | /api/v2/changes?view=my_open Accepts the name or ID of the views created in the Change management module. Accepts values of the default view or the ID of a custom view. |
Updated since | /api/v2/changes?updated_since=2024-10-19T02:00:00Z Changes updated since the specified date. |
Workspace ID | /api/v2/changes?workspace_id=2 Filters changes based on the workspace ID. |
Sort by | Handle |
---|---|
Order by | /api/v2/changes?order_by=priority The field by which the results should be sorted |
Order type | /api/v2/changes?order_type=asc The order of sorting. Values can be asc for ascending and desc for descending. Order is desc by default. |
Pagination | Handle |
---|---|
Per page | /api/v2/changes?per_page=50 The number of results to display per page. The default is 30, and users can set this to any value between 1 and 100 |
Page | /api/v2/changes?page=5 The page number to retrieve. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes' |
Filter your results using the query parameter. Use Freshservice fields to filter out records based on field values. You may also use custom fields created in your account to filter through changes and obtain a list of changes matching the specified fields.
FILTER QUERY FORMAT:
/api/v2/changes?query="'change_field1' OR 'change_field2'"
Note:
1. The query must be URL-encoded
2. A query can be framed using the change field name in the snake case, which can be obtained from Change Fields endpoint. Change Fields are case-sensitive
3. Query string must be enclosed between a pair of double quotes and can have up to 512 characters
4. Logical operators AND, OR within parentheses () can be used to group conditions.
For example: Queries can be combined using AND or OR.
https://domain.freshservice.com/api/v2/changes?query="priority: 1 AND status: 2 OR urgency: 3"
5. Supported operators
a. Use ':' for equal to (=)
b. Use ':>' for greater than or equal to (≧)
c. Use ':<' for less than or equal to (≦)
d. Use '!:' for not equals (≠)
Please note: Only :> and :< are supported for date and date_time fields
6. Formatting:
a. String fields: To be enclosed in single quotes ('')
b. Number fields: To be given as a number without quotes.
c. Date fields: Date and date_time fields to be enclosed in single quotes('yyyy-mm-dd'). Input for date fields should be in UTC Format
7. The default number of objects returned per page is 30. The total count of the results will be returned along with the result.
8. To scroll through pages, add the page parameter to the URL
9. To filter for agents and groups with no values assigned, use the null keyword
1. Get the list of changes that are being unassigned to the agent whose credentials were used to make this API call.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes?view=unassigned' |
2. Get the first page of a list of changes from the specified requestor. The changes will be returned in the descending order.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes?requester_id=1230&order_type=desc' |
3. Get the second page (changes from 11-20) of a list of all changes.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes?per_page=10&page=2' |
4. Get the first page of a list of changes that have shown any activity since the 17th of August, 2015.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes?updated_since=2015-08-17' |
5. Get the list of Urgent and High priority changes ('priority:4 OR priority:3').
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes?query="priority:4%20OR%20priority:3"' |
6. Get the list of Urgent and High priority changes in Open Status belong to the group_id 11 ('priority:3 AND group_id:11 AND status:1')
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes?query="priority:>3%20AND%20group_id:11%20AND%20status:1"' |
7. Get the list of Urgent and High priority changes ('priority:4 OR priority:3') from all accessible workspaces
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes?workspace_id=0&query="priority%3A4%20OR%20priority%3A3"' |
Update a Change
Update an existing Change request in Freshservice
Note:
The workspace_id attribute cannot be updated through the Update operation. It can only be updated through the Move operation.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "priority": 3 }' 'https://domain.freshservice.com/api/v2/changes/1' |
Update Change with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'priority=2' -F 'impact=2' -F 'risk=2' -F 'attachments[]=@/Users/user/Desktop/api2.png' -X PUT 'https://domain.freshservice.com/api/v2/changes/25' |
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 | { "change": { "id": 25, "agent_id": null, "description": "<div>Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel</div>", "description_text": "Hi Team, One of our email servers, Exchange Server (ES3) has been acting up. We tried rebooting it, but that didn’t help. We need to get it replaced ASAP. Regards Rachel", "maintenance_window": {}, "blackout_window": {}, "workspace_id": 3, "requester_id": 1232463344, "group_id": null, "priority": 2, "impact": 2, "status": 2, "risk": 2, "change_type": 1, "approval_status": 4, "planned_start_date": "2021-04-20T16:18:46Z", "planned_end_date": "2021-05-20T16:18:46Z", "change_window_id": null, "subject": "Getting ES3 back up to speed", "department_id": null, "category": null, "sub_category": null, "item_category": null, "created_at": "2021-04-12T16:59:07Z", "updated_at": "2021-04-12T17:04:41Z", "custom_fields": { "requester": null, "subject": null, "change_type": null, "status": null, "priority": null, "impact": null, "risk": null, "group": null, "agent": null, "description": null, "planned_start_date": null, "planned_end_date": null, "department": null, "category": null, "change_window": null }, "planning_fields": { "custom_fields": {} }, "assets": [] } } |
Move a Change
This API moves a change to a different workspace, while also allowing the assigned group and agent to be modified.
Note:
This endpoint is applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X PUT -d '{ "workspace_id": 3, "group_id": 3, "owner_id": 4 }' 'https://domain.freshservice.com/api/v2/changes/1/move_workspace' |
Delete a Change
Delete the Change request with the given ID from Freshservice.
Note: Deleted changes are not permanently lost. You can retrieve them using the Restore Change API.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/changes/1' |
Restore a Change
The API mentioned previously. If you deleted some changes and regret doing so now, this API will help you restore them.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshservice.com/api/v2/changes/1/restore' |
List All Change Fields
Retrieve all the Fields that constitute the Change Object
Note:
By default, only global fields and fields from the primary workspace will be returned for accounts on the Employee Support Mode. For fields from other workspaces, use the workspace_id filter.
Change field | Description |
---|---|
id | Unique ID of the Field |
workspace_id | ID of the workspace to which this change field belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
created_at | Date time at which the field was added |
updated_at | Date time at which the field was modified |
name | Name of the field |
label | Label of the field for display |
description | Description of the field |
field_type | Indicates if the field is a checkbox, dropdown, text field |
required | True if the field is marked mandatory |
required_for_closure | True if the field is marked mandatory while closing the Release item |
default_field | True if the field is a default field. False if customm |
choices | List of values supported by the field |
nested_fields | contain details of nested fields |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/change_form_fields' |
1. Get the list of change fields from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/change_form_fields?workspace_id=2' |
Notes
This section lists all API that can be used to create, edit or otherwise manipulate Change Notes.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the note. Read-Only |
user_id | number | Id of the user who created the note.Read-Only |
body | string | The body of the note in HTML format.Mandatory |
body_text | string | The body of the note in plain text format. Read-Only |
notify_emails | Array of strings | Addresses to which the note must be notified to |
created_at | date | Date time at which the note was created. |
updated_at | date | Date time at which the note was updated. |
Create a note
Create a new note on a change request in freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "body": "<div> body of the change note </div> "}' -X POST 'https://domain.freshservice.com/api/v2/changes/1/notes' |
View a note
Retrieve a note on a Change request with the given ID from Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/changes/1/notes/1' |
View all notes
Retrieve a list of all notes on a Change request with the given ID from Freshservice.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes/1/notes' |
Update a note
Update an existing note on an existing Change request in Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "body":<div> updated change note </div> }' 'https://domain.freshservice.com/api/v2/changes/1/notes/1' |
Delete a note
Delete the note on a Change request with the given ID from Freshservice.
Note: Deleted Notes are permanently lost. You can't retrieve them once it's get deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/changes/1/notes/1' |
Time Entries
These APIs help you track exactly how much time you've spent on each change*, start/stop timers and perform a whole other lot of time tracking and monitoring tasks to ensure that your support team is always performing at peak efficiency.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the time entry Read-Only |
workspace_id | number | ID of the workspace to which the time entry belongs(inherited from the change's workspace). This attribute is applicable only to accounts on the Employee Support Mode. |
task_id | number | Unique ID of the task associated with the time entry |
executed_at | datetime | Date time at which the time entry is executed |
billable | boolean | True if billable, false otherwise. |
note | string | Description note of the time entry |
start_time | datetime | Time at which the timer started |
timer_running | boolean | True if timer is running, false otherwise |
time_spent | string | Duration of time spent in seconds |
agent_id | number | Unique ID of the user who created the time entry Mandatory |
created_at | datetime | Timestamp at which the time entry is created Read-Only |
updated_at | datetime | Time stamp at which the time entry is updated Read-Only |
Create a Time Entry
Create a new time entry on a change request in freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{"note":"test_entry","time_spent":"03:00","agent_id":1,"billable":true}' -X POST 'https://domain.freshservice.com/api/v2/changes/1/time_entries' |
View a Time Entry
Retrieve a time entry on a Change request with the given ID from Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/changes/1/time_entries/1' |
List All Time Entries
Retrieve the time entries on a Change request with the given ID from Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/changes/1/time_entries' |
Update a Time Entry
Update an existing time entry on an existing Change request in Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"note":"time entry update","billable":false}' 'https://domain.freshservice.com/api/v2/changes/1/time_entries/1' |
Delete a Time Entry
Delete the time entry on a Change request with the given ID from Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X DELETE 'https://domain.freshservice.com/api/v2/changes/1/time_entries/1' |
Tasks
This section lists all API that can be used to create, edit or otherwise manipulate Change Tasks.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the task. |
agent_id | number | Id of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | DateTime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
created_at | DateTime | Timestamp at which the task was created |
updated_at | DateTime | Timestamp at which the task was updated |
closed_at | DateTime | Timestamp at which the task was closed |
group_id | number | Unique ID of the group to which the task is assigned |
Create a Task
Create a new task on a change request in freshservice.
Attribute | Type | Description |
---|---|---|
workspace_id | number | ID of the workspace to which the task belongs. This attribute is applicable only to accounts on the Employee Support Mode. The default value is the ID of the workspace of the change. |
agent_id | number | ID of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | datetime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
group_id | number | Unique ID of the group to which the task is assigned |
1 2 3 4 5 6 7 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "due_date": "2020-04-03T10:26:13.067Z", "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!", "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/changes/1/tasks' |
View a Task
Retrieve a task on a Change request with the given ID from Freshservice
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/changes/1/tasks/1' |
View all Tasks
Retrieve the tasks on a Change request with the given ID from Freshservice.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/changes/1/tasks' |
Update a Task
Update an existing task on an existing Change request in Freshservice
1 2 3 4 5 6 7 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "status": 3, "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!", "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/changes/1/tasks/1' |
Delete a Task
Delete the task on a Change request with the given ID from Freshservice
Note: Deleted tasks are permanently lost. You can't retrieve them once it's get deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/changes/1/tasks/1' |
Releases
This section lists all API that can be used to create, edit or otherwise manipulate Release.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the Release Read-Only |
workspace_id | number | ID of the workspace that the release belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
agent_id | number | Unique identifier of the agent to whom the Release is assigned |
group_id | number | Unique identifier of the agent group to which the Release is assigned |
priority | number | Priority of the Release 1-Low, 2-Medium, 3-High, 4-Urgent |
status | number | Status identifier of the Release. 1-Open, 2-On hold, 3-In Progress, 4-Incomplete, 5-Completed |
release_type | number | Type of the Release 1-minor, 2-standard, 3-major, 4-emergency |
subject | string | Subject of the Release |
description | string | HTML description of the release. Description and description_html should not be passed together |
planned_start_date | DateTime | Timestamp at which release is starting |
planned_end_date | DateTime | Timestamp at which release is ending |
work_start_date | DateTime | Timestamp at which release work started |
work_end_date | DateTime | Timestamp at which release work ended |
department_id | number | Unique ID of the department initiating the Release |
category | string | Category of the Release |
sub_category | string | Sub-category of the Release |
item_category | string | Item of the Release |
created_at | DateTime | Timestamp at which Release was created Read-Only |
updated_at | DateTime | Timestamp at which Release was last updated Read-Only |
associated_assets | Array of numbers | Unique IDs of the assets associated with the Release request Read-Only |
associated_changes | Array of numbers | Unique IDs of the Changes associated with the Release Read-Only |
custom_fields | Hash | Key value pairs containing the names and values of custom fields. |
planning_fields | Hash | Key value pairs containing the names and values of Rollout Plan and Backout Plan |
assets | hash | List of assets associated with the release |
Create a Release
Create a new Release request in Freshservice
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | curl -v -u api_key:X -H "Content-Type: application/json" -d ' { "agent_id": 1, "group_id": null, "priority": 1, "status": 1, "release_type": 1, "subject": "string", "planned_start_date": "2020-03-31T10:35:47.462Z", "planned_end_date": "2020-03-31T10:35:47.462Z", "department_id": null, "category": "string", "sub_category": "string", "item_category": "string", "custom_fields": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "workspace_id": 2, } ' -X POST 'https://domain.freshservice.com/api/v2/releases' |
Create Release with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'subject=Scheduled Release 1' -F 'description=Scheduled release of the first product' -F 'planned_start_date=2021-04-20T16:18:46Z' -F 'planned_end_date=2021-05-20T16:18:46Z' -F 'priority=1' -F 'status=2' -F 'release_type=1' -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'workspace_id=2' -X POST 'https://domain.freshservice.com/api/v2/releases' |
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 | { "release": { "id": 24, "agent_id": 1, "description": "<div>Scheduled release of the first product</div>", "description_text": "Scheduled release of the first product", "workspace_id": 2, "group_id": null, "department_id": null, "subject": "Scheduled Release 1", "category": null, "sub_category": null, "item_category": null, "assets": [], "planned_start_date": "2021-04-20T16:18:46Z", "planned_end_date": "2021-05-20T16:18:46Z", "status": 2, "priority": 1, "release_type": 1, "work_start_date": "2021-04-20T16:18:46Z", "work_end_date": "2021-05-20T16:18:46Z", "created_at": "2021-04-12T17:39:15Z", "updated_at": "2021-04-12T17:39:15Z", "associated_change_ids": [], "custom_fields": { "subject": null, "description": null, "planned_start_date": null, "planned_end_date": null, "status": null, "priority": null, "release_type": null, "group": null, "agent": null, "department": null, "category": null }, "planning_fields": {} } } |
Create Release with assets
Note:
"assets" key: contains comma (,) separated hash of the assets, each with key display id.
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 | curl -v -u api_key:X -H "Content-Type: application/json" -d ' { "agent_id": 1, "group_id": null, "priority": 1, "status": 3, "release_type": 1, "subject": "string", "planned_start_date": "2020-03-31T10:35:47.462Z", "planned_end_date": "2020-03-31T10:35:47.462Z", "department_id": null, "category": "string", "sub_category": "string", "item_category": "string", "custom_fields": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "assets": [ { "display_id": 8 }, { "display_id": 9 } ], "workspace_id": 2, } ' -X POST 'https://domain.freshservice.com/api/v2/releases' |
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 | { "agent_id": 1, "workspace_id": 2, "group_id": null, "priority": 1, "status": 3, "release_type": 1, "subject": "string", "planned_start_date": "2020-03-31T10:35:47.462Z", "planned_end_date": "2020-03-31T10:35:47.462Z", "work_start_date": "2020-03-31T10:35:47.462Z", "work_end_date": "2020-03-31T10:35:47.462Z", "department_id": null, "category": "string", "sub_category": "string", "item_category": "string", "assets": [], "custom_fields": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "planning_fields": { "build_plan": { "description": "string" }, "test_plan": { "description": "string" } }, "assets": [ { "name": "Dell Monitor", "description": null, "ci_type_id": 12, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 8, "salvage": null }, { "name": "Logitech Mouse", "description": null, "ci_type_id": 4, "impact": 1, "created": "2019-12-13T12:31:47+05:30", "updated": "2019-12-13T12:31:47+05:30", "user_id": null, "department_id": null, "assigned_on": null, "agent_id": null, "author_id": 2, "author_type": "User", "deleted": false, "display_id": 9, "salvage": null } ] } |
View a Release
Retrieve the Release with the given ID from Freshservice
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/releases/1' |
Update a Release
Update an existing Release in Freshservice
Note:
The workspace_id attribute cannot be updated through the Update operation. It can only be updated through the Move operation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "agent_id": 0, "group_id": 0, "priority": 1, "status": 0, "release_type": 1, "subject": "string", "planned_start_date": "2020-03-31T11:24:09.019Z", "planned_end_date": "2020-03-31T11:24:09.019Z", "work_start_date": "2020-03-31T11:24:09.019Z", "work_end_date": "2020-03-31T11:24:09.019Z", "department_id": 0, "category": "string", "sub_category": "string", "item_category": "string", "custom_fields": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "planning_fields": { "build_plan": { "description": "string" }, "test_plan": { "description": "string" } } }' 'https://domain.freshservice.com/api/v2/releases/1' |
Update Release with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'priority=2' -F 'attachments[]=@/Users/user/Desktop/api2.png' -X PUT 'https://domain.freshservice.com/api/v2/releases/24' |
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 | { "release": { "id": 24, "agent_id": null, "description": "<div>Scheduled release of the first product</div>", "description_text": "Scheduled release of the first product", "group_id": null, "department_id": null, "subject": "Scheduled Release 1", "category": null, "sub_category": null, "item_category": null, "planned_start_date": "2021-04-20T16:18:46Z", "planned_end_date": "2021-05-20T16:18:46Z", "status": 2, "priority": 2, "release_type": 1, "work_start_date": "2021-04-20T16:18:46Z", "work_end_date": "2021-05-20T16:18:46Z", "created_at": "2021-04-12T17:39:15Z", "updated_at": "2021-04-12T17:43:14Z", "workspace_id": 2, "associated_change_ids": [], "custom_fields": { "subject": null, "description": null, "planned_start_date": null, "planned_end_date": null, "status": null, "priority": null, "release_type": null, "group": null, "agent": null, "department": null, "category": null }, "planning_fields": {} } } |
Move a Release
This API moves a release to a different workspace, while also allowing the assigned group and agent to be modified.
Note:
This endpoint is applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X PUT -d '{ "workspace_id": 3, "group_id": 3, "owner_id": 4 }' 'https://domain.freshservice.com/api/v2/releases/1/move_workspace' |
Delete a Release
Delete the Release with the given ID from Freshservice
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/releases/1' |
Filter Releases
This API helps you to view all the releases in your service desk.
To view only specific releases (that is, those which match only the criteria you choose) use the filters given below.
Note:
All the below requests are paginated to return only 30 releases per page. Append the parameter "page=[:page_no]" in the url to traverse through pages.
Filter by | Handle |
---|---|
Default filters: | /api/v2/releases?filter_name=[filter_name] The various filters available are all, my_open, unassigned, completed, incompleted, deleted and deleted |
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET https://domain.freshservice.com/api/v2/releases?filter_name=all |
View list of Releases
Retrieve a list of all Releases in Freshservice
Note:
If a workspace_id is not specified as a URL parameter, only releases from the primary workspace will be included in the response. If workspace_id is specified as 0, releases from across all workspaces will be included in the response with just the global fields. Applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/releases' |
1. Get the list of all releases from workspaces to which the user has access.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/releases?workspace_id=0' |
2. Get the list of releases from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/releases?workspace_id=3' |
Restore a Release
The API mentioned previously. If you deleted some releases and regret doing so now, this API will help you restore them.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '' 'https://domain.freshservice.com/api/v2/releases/1/restore' |
View All Release Fields
Retrieve all the Fields that constitute the Release Object
Note:
By default, only global fields and fields from the primary workspace will be returned for accounts on the Employee Support Mode. For fields from other workspaces, use the workspace_id filter.
Release field | Description |
---|---|
id | Unique ID of the Field |
workspace_id | ID of the workspace to which this release field belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
created_at | Date time at which the field was added |
updated_at | Date time at which the field was modified |
name | Name of the field |
label | Label of the field for display |
description | Description of the field |
field_type | Indicates if the field is a checkbox, dropdown, text field |
required | True if the field is marked mandatory |
required_for_closure | True if the field is marked mandatory while closing the Release item |
default_field | True if the field is a default field. False if customm |
choices | List of values supported by the field |
nested_fields | contain details of nested fields |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/release_form_fields' |
1. Get the list of release fields from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/release_form_fields?workspace_id=2' |
Notes
This section lists all API that can be used to create, edit or otherwise manipulate Release Notes.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the note. Read-Only |
user_id | number | Id of the user who created the note.Read-Only |
body | string | The body of the note in HTML format.Mandatory |
body_text | string | The body of the note in plain text format. Read-Only |
notify_emails | Array of strings | Addresses to which the note must be notified to |
created_at | date | Date time at which the note was created. Read-Only |
updated_at | date | Date time at which the note was updated. Read-Only |
Create a note
Create a new note on a release request in freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "body": "<div> body of the release note </div> "}' -X POST 'https://domain.freshservice.com/api/v2/releases/1/notes' |
View a note
Retrieve a note on a Release request with the given ID from Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/releases/1/notes/1' |
View all notes
Retrieve a list of all notes on a Release request with the given ID from Freshservice.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/releases/1/notes' |
Update a note
Update an existing note on an existing Release request in Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "body":<div> updated release note </div> }' 'https://domain.freshservice.com/api/v2/releases/1/notes/1' |
Delete a note
Delete the note on a Release request with the given ID from Freshservice.
Note: Deleted Notes are permanently lost. You can't retrieve them once it's get deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/releases/1/notes/1' |
Time Entries
These APIs help you track exactly how much time you've spent on each release*, start/stop timers and perform a whole other lot of time tracking and monitoring tasks to ensure that your support team is always performing at peak efficiency.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the time entry Read-Only |
workspace_id | number | ID of the workspace to which the time entry belongs(inherited from the release's workspace). This attribute is applicable only to accounts on the Employee Support Mode. |
task_id | number | Unique ID of the task associated with the time entry |
executed_at | datetime | Date time at which the time entry is executed |
billable | boolean | True if billable, false otherwise. |
note | string | Description note of the time entry |
start_time | datetime | Time at which the timer started |
timer_running | boolean | True if timer is running, false otherwise |
time_spent | string | Duration of time spent in seconds |
agent_id | number | Unique ID of the user who created the time entry Mandatory |
created_at | datetime | Timestamp at which the time entry is created Read-Only |
updated_at | datetime | Time stamp at which the time entry is updated Read-Only |
Create a Time Entry
Create a new time entry on a release request in freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{"note":"test_entry","time_spent":"03:00","agent_id":1,"billable":true}' -X POST 'https://domain.freshservice.com/api/v2/releases/1/time_entries' |
View a Time Entry
Retrieve a time entry on a Release request with the given ID from Freshservice.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/releases/1/time_entries/1' |
List All Time Entries
Retrieve the time entries on a Release request with the given ID from Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/releases/1/time_entries' |
Update a Time Entry
Update an existing time entry on an existing Release request in Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"note":"time entry update","billable":false}' 'https://domain.freshservice.com/api/v2/releases/1/time_entries/1' |
Delete a Time Entry
Delete the time entry on a Release request with the given ID from Freshservice.
1 | curl -u api_key:X -H "Content-Type: application/json" -X DELETE 'https://domain.freshservice.com/api/v2/releases/1/time_entries/1' |
Tasks
This section lists all API that can be used to create, edit or otherwise manipulate Release Tasks.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the task. |
agent_id | number | Id of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | DateTime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
created_at | DateTime | Timestamp at which the task was created |
updated_at | DateTime | Timestamp at which the task was updated |
closed_at | DateTime | Timestamp at which the task was closed |
group_id | number | Unique ID of the group to which the task is assigned |
Create a Task
Create a new task on a release in freshservice
Attribute | Type | Description |
---|---|---|
workspace_id | number | ID of the workspace to which the task belongs. This attribute is applicable only to accounts on the Employee Support Mode. The default value is the ID of the workspace of the release. |
agent_id | number | ID of the agent to whom the task is assigned |
status | number | Status of the task, 1-Open, 2-In Progress, 3-Completed |
due_date | datetime | Due date of the task |
notify_before | number | Time in seconds before which notification is sent prior to due date |
title | string | Title of the task |
description | string | Description of the task |
group_id | number | Unique ID of the group to which the task is assigned |
1 2 3 4 5 6 7 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "due_date": "2020-04-27T13:23:20.813Z", "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!", "workspace_id": 3 }' -X POST 'https://domain.freshservice.com/api/v2/releases/1/tasks' |
View a Task
Retrieve a task on a Release with the given ID from Freshservice
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/releases/1/tasks/1' |
View all Tasks
Retrieve the tasks on a Release with the given ID from Freshservice
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/releases/1/tasks' |
Update a Task
Update an existing task on an existing Release in Freshservice
1 2 3 4 5 6 7 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "status": 3, "notify_before": 0, "title": "Supply lightsabers to all the Jedis", "description": "We need to re-supply to win the war!", "workspace_id: 2" }' 'https://domain.freshservice.com/api/v2/releases/1/tasks/1' |
Delete a Task
Delete the task on a Release with the given ID from Freshservice
Note: Deleted tasks are permanently lost. You can't retrieve them once it's get deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/releases/1/tasks/1' |
CABs
A Change Advisory Board, or a CAB consists of a set of agents who have been nominated to verify new changes in the service desk. They help managers to assess changes and finalize them before implementation. The members of the each CAB include experts in a particular area, who go through every change before they approve or reject it.
Freshservice lets you create custom CABs and fill them up with specific experts from your team. Whenever a change needs approval, the Change Manager can select any of the available CABs and also pick out individual members of the CAB who will get to review it.
Note:
Only users with "Manage Users" privilege can access all the CAB APIs. Users with "Edit Changes" privilege can access only List All Cabs API and View A Cab API.
Attribute | Type | Description |
---|---|---|
name | string | Name of the CABMandatory |
description | string | Description of the CAB |
created_at | datetime | Date and time when the CAB was created |
updated_at | datetime | Date and time when the CAB was last updated |
members | array | A comma separated array of user IDs of members of this group |
member_details | array | A comma separated array of member details like id, name, email, mobile, phone |
Create a CAB
Note: A maximum of 100 user IDs can be be passed to add_members at a time.
Attribute | Type | Description |
---|---|---|
name | string | Name of the CAB.Mandatory |
description | string | Description of the CAB. |
add_members | array | A comma separated array of user IDs of agents who are to be added as members to this CAB. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"name":"Change Planning", "description":"Change Plan Acceptance Board", "members":[1,16]}' 'https://domain.freshservice.com/api/v2/cabs' |
1. Create a CAB with members
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"name":"Change Management", "description":"Change Plan Acceptance Board", "add_members": [1, 16]}' 'https://domain.freshservice.com/api/v2/cabs' |
2. Create a CAB with no members
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"name":"Change Management", "description":"Change Plan Acceptance Board"}' 'https://domain.freshservice.com/api/v2/cabs' |
List All CABs
Note:
All the below requests are paginated to return only 30 CABS per page as default. Append the parameter "page=[:page_no]" in the url to traverse through pages & "per_page=[:cabs_per_page]" to specify CABS needed to be returned in a page.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/cabs' |
List the CABs present in an account 5 per page, from first page
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/cabs?page=1&per_page=5' |
View a CAB
Use 'include' to embed additional details in the response. Include will consume 2 additional credits. For example if you embed the member_details you will be charged a total of 3 API credits for the call.
Note:
By default, member_details field will not be included in the response. They can be retrieved via the embedding functionality.
Embed | Handle |
---|---|
member_details | /api/v2/cabs/[id]?include=member_details Will return details of the members of this CAB. Including member_details will consume three API calls. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/cabs/26' |
View the CAB's details with included details of its members
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/cabs/26?include=member_details' |
Update a CAB
Note: A maximum of 100 user IDs can be be passed to add_members or remove_members at a time.
Attribute | Type | Description |
---|---|---|
name | string | Name of the CAB.Mandatory |
description | string | Description of the CAB. |
add_members | array | A comma separated array of user IDs of agents who are to be added as members to this CAB. |
remove_members | array | A comma separated array of user IDs of agents who are to be removed from members in a CAB. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PATCH -d '{"name":"Change Planning", "description":"Change Plan Acceptance Board", "members":[1,16]}' 'https://domain.freshservice.com/api/v2/cabs/2' |
1. Add members to an existing CAB
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PATCH -d '{"add_members": [1, 16]}' 'https://domain.freshservice.com/api/v2/cabs/2' |
2. Update the Name of an existing CAB
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PATCH -d '{"name":"Change Management"}' 'https://domain.freshservice.com/api/v2/cabs/2' |
Delete a CAB
Note:
1. Deleting a CAB will only disband the CAB and delete the CAB's details. It does not delete the members/users.
2. Deleted CABs cannot be restored.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/cabs/5' |
Workspaces
This section describes the APIs to retrieve information about a specific or all workspaces in an account.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the WorkspaceRead-Only |
name | string | Name of the workspace |
description | string | Description of the workspace |
primary | boolean | Signifies if the workspace is assigned as the primary workspace of the account |
restricted | boolean | Signifies if the workspace is marked as restricted |
state | string | Status of the workspace. Possible values: active: The workspace is in active state draft: The workspace is in draft state |
template_name | string | The template from which the workspace was created |
created_at | datetime | date and time when the workspace was created |
updated_at | datetime | date and time when the workspace was updated |
List All Workspaces
Retrieves information about all the workspaces created in the account
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/workspaces' |
View a Workspace
Retrieves information about a particular workspace in the account
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/workspaces/2' |
Approvals
This section lists API that can be used for approval requests across ticket and change modules.
Approval Properties
Approvals use certain fixed numerical values to denote its status and types. These numerical values along with their meanings are given below:
Approval Type | Value |
---|---|
To be approved by Everyone | 1 |
To be approved by Anyone | 2 |
To be approved by Majority | 3 |
To be approved by First Responder | 4 |
Status | Value |
---|---|
Requested | 0 |
Approved | 1 |
Rejected | 2 |
Cancelled | 3 |
List All Approvals
The approval properties can be used to filter approvals from ticket and change module and get a list of approval requests matching the specified filters.
Note:
1. This API is paginated and will return at max 30 approval requests. Use “page” filter with the page number to fetch more requests.
2. You need to pass the “parent” filter along with one of the following filters mandatorily to fetch the approval requests through this API: approver_id, status, parent_id or delegatee_id.
3. The results will be sorted in ascending order of their created date.
Supported filters
Attribute | Type | Description |
---|---|---|
parent | string | Parent module of the approval (ticket/change)Mandatory |
parent_id* | number | ID of the parent module |
status* | string | Status of the approval request |
approver_id* | number | User ID of the approver |
level | number | Level of approval |
delegatee_id* | number | User ID of the delegatee |
* Any of the four attributes is mandatory. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/approvals?parent=ticket&approver_id=123&status=requested&parent_id=12&level=1&page=1 |
Requesters
Requesters are Freshservice users who consume services provided by the agent teams.
Attribute | Type | Description |
---|---|---|
id | number | User ID of the requester. |
first_name | string | First name of the requester.Mandatory |
last_name | string | Last name of the requester. |
job_title | string | Job title of the requester. |
primary_email* | string | Primary email address of the requester. |
secondary_emails | array of strings | Additional/secondary emails associated with the requester. |
work_phone_number* | number | Work phone number of the requester. |
mobile_phone_number* | number | Mobile phone number of the requester. |
department_ids | array of numbers | Unique IDs of the departments associated with the requester |
can_see_all_tickets_from_associated_departments | boolean | Set to true if the requester must be allowed to view tickets filed by other members of the department, and false otherwise |
reporting_manager_id | number | User ID of the requester’s reporting manager. |
address | string | Address of the requester. |
time_zone | string | Time zone of the requester. Read more here. |
time_format | string | Time format for the requester.Possible values: 12h (12 hour format) 24h (24 hour format) |
language | string | Language used by the requester. The default language is “en” (English). Read more here. |
location_id | number | Unique ID of the location associated with the requester. |
background_information | string | Background information of the requester. |
custom_fields | hash | Key-value pair containing the names and values of the (custom) requester fields. |
active | boolean | Set to true if the user is active, and false if the user account has been deactivated. |
has_logged_in | boolean | Set to true if the user has logged in to Freshservice at least once, and false otherwise. | created_at | datetime | Date and time when the requester was created |
updated_at | datetime | Date and time when the requester was last updated |
is_agent | boolean | Set to true if the user is an agent, false if the user is a requesterRead-Only |
* primary_email, work_phone_number or mobile_phone_number - one of three is mandatory to create a requester. |
Create a Requester
This operation allows you to create a new requester.
Attribute | Type | Description |
---|---|---|
first_name | string | First name of the requester.Mandatory |
last_name | string | Last name of the requester. |
job_title | string | Job title of the requester. |
primary_email* | string | Primary email address of the requester. |
secondary_emails | array of strings | Additional/secondary emails associated with the requester. |
work_phone_number* | number | Work phone number of the requester. |
mobile_phone_number* | number | Mobile phone number of the requester. |
department_ids | array of numbers | Unique IDs of the departments associated with the requester |
can_see_all_tickets_from_associated_departments | boolean | Set to true if the requester must be allowed to view tickets filed by other members of the department, and false otherwise |
reporting_manager_id | number | User ID of the requester’s reporting manager. |
address | string | Address of the requester. |
time_zone | string | Time zone of the requester. Read more here. |
time_format | string | Time format for the requester.Possible values: 12h (12 hour format) 24h (24 hour format) |
language | string | Language used by the requester. The default language is “en” (English). Read more here. |
location_id | number | Unique ID of the location associated with the requester. |
background_information | string | Background information of the requester. |
custom_fields | hash | Key-value pair containing the names and values of the (custom) requester fields. |
* primary_email, work_phone_number or mobile_phone_number - one of three is mandatory to create a requester. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"first_name":"Ron","last_name":"Weasley","job_title":"Student","primary_email":"ronald.weasley@hogwarts.edu","secondary_emails":["ronald.weasley@freshservice.com", ronald.weasley@freshworks.com"],"work_phone_number":"62443","mobile_phone_number":"77762443","department_ids":[554],"can_see_all_tickets_from_associated_departments":false,"reporting_manager_id":656,"address":"Gryffindor Tower","time_zone":"Edinburgh","language":"en","location_id":23,"background_information":"","custom_fields":{"quidditch_role":null,"hogsmeade_permission":true}}' 'https://domain.freshservice.com/api/v2/requesters' |
View a Requester
This operation allows you to view information about a user.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters/777' |
List All Requesters
This operation returns a list of all requesters in the account. Adding "include_agents=true" to the query string will include agents in the response. Use filters to view only specific users (those who match the criteria that you choose).
Note: When using filters, the query string must be URL encoded.
Filter by | Handle |
---|---|
email, mobile_phone_number, work_phone_number | /api/v2/requesters?[filter]=[value] Example: /api/v2/requesters?email=harry.potter@hogwarts.edu /api/v2/requesters?mobile_phone_number=77762442 /api/v2/requesters?work_phone_number=62442 |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters' |
Retrieve the second page of the list of users. (This list contains information about 30 users by default, and is always sorted by the first name of the user.)
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?per_page=20&page=2' |
Get an agent by their work phone number
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?work_phone_number=234234&include_agents=true' |
Filter Requesters
Use Requester attributes to filter your list.
Note:
1. Filtered results cannot be sorted. By default it is sorted by created_at in descending order.
2. Adding "include_agents=true" to the query string will include agents in the response. The default response includes only requesters and not agents. Only users who also have the "Manage Agents" permission will be able to use this modifier.
3. The query must be URL encoded (see example).
4. Query can be framed using the name of the requester fields, which can be obtained from the Supported Requester Fields Section.
5. Query string must be enclosed between a pair of double quotes and can have up to 512 characters.
6. Logical operators AND, OR along with parenthesis( ) can be used to group conditions.
7. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields.
8. Input for date field should be in UTC Format.
9. The number of objects returned per page is 30.
10. To scroll through the pages add the page parameter to the url. The page number starts with 1 and should not exceed 40.
11. To filter for fields with no values assigned, use the null keyword.
12. The "~" query operator can be used for "starts with" text searches. "Starts with" search is supported for one or more of the following attributes: first_name, last_name, name, primary_email, mobile_phone_number, work_phone_number. The query format is https://domain.freshservice.com/api/v2/requesters?query="~[attribute_1|attribute_2]:'somestring'". The query needs to be URL encoded. This would return a list of users for whom attribute_1 OR attribute_2 starts with "somestring". Refer to examples 13, 14, and 15.
13. Please note that any update made to requester either in Freshservice application or through API may take a few minutes to get indexed, after which the updated results will be available through API.
Supported Requester Fields
Field | Type | Description |
---|---|---|
first_name | string | First name of the requester. |
last_name | string | Last name of the requester. |
name | string | Concatenation of first_name and last_name with single space in-between fields. |
job_title | string | Title of the requester. |
primary_email | string | Email address of the requester. |
work_phone_number | string | Work phone of the requester. |
mobile_phone_number | string | Mobile phone of the requester. |
department_id | integer | ID of the department(s) assigned to the requester. |
reporting_manager_id | integer | ID of the reporting manager. |
time_zone | string | ID of the department. |
language | string | Language code(Eg. en, ja-JP). |
location_id | integer | ID of the location. |
created_at | date | Date (YYYY-MM-DD) when the requester is created. |
updated_at | date | Date (YYYY-MM-DD) when the requester is updated. |
Custom Fields Supported | Type |
---|---|
Single line text | string |
Number | integer |
Dropdown | string |
Date | date |
Phone number | string |
1. Get the requester by primary email: 'requester@yourcompany.com'.
"primary_email:'requester@yourcompany.com'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="primary_email:%27requester%40yourcompany.com%27"' |
2. Get all the requesters by job title: 'Staff Engineer'.
"job_title : 'Staff Engineer'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="job_title:%27Staff%20Engineer%27"' |
3. Get the requester by work phone number: '(91)99999 10001'.
"work_phone_number : '(91)99999 10001'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="work_phone_number:%2891%2999999%2010001"' |
4. Get the agents and requesters whose mobile phone number is not set: null.
"mobile_phone_number :null"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="mobile_phone_number:null"'&include_agents=true |
5. Get all the requesters by time zone: Eastern Time (US & Canada) AND language: 'en'.
"time_zone:'Eastern Time (US & Canada)' AND language:'en'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="time_zone%3A%27Eastern%20Time%20(US%20%26%20Canada)%27%20AND%20language%3A%27en%27"' |
6. Get all the requesters by location_id: '5678 AND reporting manager id: 100001'.
"location_id:5678 AND reporting_manager_id:100001"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="location_id%3A5678%20AND%20reporting_manager_id%3A100001"' |
7. Get all the requesters whose department ID is '12345' or '67890'.
"department_id:12345 OR department_id:67890"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="department_id:12345%20OR%20department_id:67890"' |
8. Using greater than(>) operator.
"created_at :> '2020-01-01'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="created_at%3A%3E%272020-01-01%27"' |
9. Using AND, OR, Parenthesis ( ) operator'
"job_title : 'Customer Success Specialist' AND (department_id:4001 OR department_id:5001) AND (location_id:200 OR location_id:300)"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query ="job_title%20%3A%20%27Customer%20Success%20Specialist%27%20AND%20(department_id%3A4001%20OR%20department_id%3A5001) %20AND%20(location_id%3A200%20OR%20location_id%3A300)"' |
10. Using custom fields: Labels defined as 'Product Name' AND 'Date of Joining'.
"product_name : 'Fresh Service' AND date_of_joining:<'2015-06-30'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="product_name%20%3A%20%27Fresh%20Service%27%20AND%20date_of_joining%3A%3C%272015-06-30%27"' |
11. Include both requesters and agents in the response
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?include_agents=true' |
12. Include both requesters and agents in the response whose language is French
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="language:'fr'"&include_agents=true' |
13. List all requesters whose first name starts with 'John'
'query="~[first_name]:'John'"'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="~%5Bfirst_name%5D%3A%27John%27' |
14. List all requesters whose first name or last name starts with 'John'
'query="~[first_name|last_name]:'John'"'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="~%5Bfirst_name%7Clast_name%5D%3A%27John%27"' |
15. List all requesters whose primary_email firstname, lastname, or domain.ext starts with 'John' (where their email format is firstname.lastname@domain.ext). Searching by the email attribute searches all these three components automatically.
'query="~[primary_email]:'John'"'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requesters?query="~%5Bprimary_email%5D%3A%27John%27' |
Validation errors:
invalid_field: 'Time period'.
"time_period :<'2020-02-02'"
1 | { "description": "Validation failed", "errors": [ { "field": "time_period", "message": "[:invalid_field]", "code": "invalid_value" } ] } |
invalid_value: 'Datatype validation'.
"department_id : 'abc'"
1 | { "description": "Validation failed", "errors": [ { "field": "department_id", "message": "[\"It should be a/an Positive Integer\"]", "code": "invalid_value" } ] } |
invalid_value: 'Dropdown choice validation'.
"country : 'not-exist'"
1 | { "description": "Validation failed", "errors": [ { "field": "country", "message": "[\"It should be one of the choice value.\"]", "code": "invalid_value" } ] } |
List All Requester Fields
This operation allows you to view all the built-in and custom fields for requesters in your Freshservice account. Use 'include' to embed additional details in the response. Each include will consume an additional credit. For example if you embed the user field groups you will be charged a total of 3 API credits for the call.
Note:
By default, user field groups details will not be included in the response. They can be retrieved via the embedding functionality.
Embed | Handle |
---|---|
user_field_groups | /api/v2/requester_fields?include=user_field_groups Will return user field groups details like id, label |
REQUESTER FIELD | DESCRIPTION |
---|---|
editable_in_signup | Set to true if the field can be updated by requesters during signup. |
id | ID of the requester field. |
label | Display name for the field (as seen by agents). |
name | Name of the requester field. |
position | Position of the requester field. |
user_field_group_id | ID of the user field group. |
type | For custom requester fields, type of value associated with the field will be given (Examples custom_date, custom_text...). |
requesters_can_edit | Requesters can edit the field in the support portal. |
label_for_requesters | Display name for the field (as seen in the support portal). |
required_for_requesters | Set to true if the field is mandatory in the support portal. |
displayed_for_requesters | Requesters can see the field in the support portal. |
required_for_agents | Set to true if the field is mandatory for agents. |
choices | List of values supported by the field. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contact_fields' |
Update a Requester
This operation allows you to modify the profile of a particular requester.
Note:
can_see_all_tickets_from_associated_departments will automatically be set to false unless it is explicitly set to true in the payload, irrespective of the previous value of the field.
Attribute | Type | Description |
---|---|---|
first_name | string | First name of the requester. |
last_name | string | Last name of the requester. |
job_title | string | Job title of the requester. |
primary_email | string | Primary email address of the requester. |
secondary_emails | array of strings | Additional/secondary emails associated with the requester. |
work_phone_number | number | Work phone number of the requester. |
mobile_phone_number | number | Mobile phone number of the requester. |
department_ids | array of numbers | Unique IDs of the departments associated with the requester |
can_see_all_tickets_from_associated_departments | boolean | Set to true if the requester must be allowed to view tickets filed by other members of the department, and false otherwise |
reporting_manager_id | number | User ID of the requester’s reporting manager. |
address | string | Address of the requester. |
time_zone | string | Time zone of the requester. Read more here. |
time_format | string | Time format for the requester.Possible values: 12h (12 hour format) 24h (24 hour format) |
language | string | Language used by the requester. The default language is “en” (English). Read more here. |
location_id | number | Unique ID of the location associated with the requester. |
background_information | string | Background information of the requester. |
custom_fields | hash | Key-value pair containing the names and values of the (custom) requester fields. |
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -X PUT -d '{ "first_name":"Ronald", "last_name":"Weasley","time_format":"24h" }' 'https://domain.freshservice.com/api/v2/requesters/888' |
Deactivate a Requester
This operation allows you to deactivate a requester.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/requesters/888' |
Forget a Requester
This operation allows you to permanently delete a requester and the tickets that they requested.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/requesters/888/forget' |
Convert To Agent
Convert a requester to an occasional agent with SD Agent role and no group memberships.
1 | curl -v -u api.user@hogwarts.edu:test -H 'Content-Type: application/json' -X PUT -d '' 'https://domain.freshservice.com/api/v2/requesters/888/convert_to_agent' |
Merge Requesters
Merge secondary requesters into a primary requester.
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -X PUT -d '' 'https://domain.freshservice.com/api/v2/requesters/111/merge?secondary_requesters=222,333,444' |
Reactivate a Requester
This operation allows you to reactivate a particular deactivated requester.
1 | curl -v -u api.user@hogwarts.edu:test -H 'Content-Type: application/json' -X PUT -d '' 'https://domain.freshservice.com/api/v2/requesters/4021/reactivate' |
User Assignment History
This operation retrieves the assignment history of a specific user in Freshservice.
1 | curl -v -u api_key:X -X "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/users/2/assignment-history' |
Agents
Agents in Freshservice can be “full-time” or “occasional”. Full-time agents are those in your core support team who will log in to your help desk every day. Occasional agents are those who would only need to log in a few times every month, such as the CEO or field staff.
Note: As announced in Nov 2022, following are the behavior changes post May 31st 2023:
1. Following attributes are no longer supported in the agent object in all API requests and responses: ticket_scope, problem_scope, change_scope, release_scope, scopes, group_ids, role_ids.
2. API requests containing the above mentioned unsupported attributes will fail with HTTP 400 Bad Request error. API responses will not contain these attributes.
Attribute | Type | Description |
---|---|---|
id | number | User ID of the agent. |
first_name | string | First name of the agent.Mandatory |
last_name | string | Last name of the agent. |
occasional | boolean | True if the agent is an occasional agent, and false if full-time agent. |
job_title | string | Job title of the agent. |
string | Email address of the agent.Mandatory | |
work_phone_number | number | Work phone number of the agent. |
mobile_phone_number | number | Mobile phone number of the agent. |
department_ids | array of numbers | Unique IDs of the departments associated with the agent |
can_see_all_tickets_from_associated_departments | boolean | Set to true if the agent must be allowed to view tickets filed by other members of the department, and false otherwise |
reporting_manager_id | number | User ID of the agent's reporting manager. |
address | string | Address of the agent. |
time_zone | string | Time zone of the agent. Read more here. |
time_format | string | Time format for the agent.Possible values: 12h (12 hour format) 24h (24 hour format) |
language | string | Language used by the agent. The default language is “en” (English). Read more here. |
location_id | number | Unique ID of the location associated with the agent. |
background_information | string | Background information of the agent. |
scoreboard_level_id | number | Unique ID of the level of the agent in the Arcade. Possible values: 1 (Beginner) 2 (Intermediate) 3 (Professional) 4 (Expert) 5 (Master) 6 (Guru) |
ticket_scope | string | Ticket scope of the agent.Unsupported Note: Unsupported since May 31st 2023. Use roles -> assignment_scope instead. |
problem_scope | string | Problem scope of the agent.Unsupported Note: Unsupported since May 31st 2023. Use roles -> assignment_scope instead. |
change_scope | string | Change scope of the agent.Unsupported Note: Unsupported since May 31st 2023. Use roles -> assignment_scope instead. |
release_scope | string | Release scope of the agent.Unsupported Note: Unsupported since May 31st 2023. Use roles -> assignment_scope instead. |
group_ids | array of numbers | Unique IDs of the groups that the agent is a member of.Unsupported Note: Unsupported since May 31st 2023. Use member_of and observer_of instead. |
member_of | array of numbers | Unique IDs of the groups that the agent is a member of. The input value for this field should also include the IDs of approval-enabled restricted groups for which the agent’s member access is pending approval by a group leader. The response value for this field would only contain the list of groups that the agent is an approved member of. The member_of_pending_approval read-only attribute in the response will include the list of groups for which the agent’s member access is pending approval by a group leader. |
observer_of | array of numbers | Unique IDs of the groups that the agent is an observer of. The input value for this field should also include the IDs of approval-enabled restricted groups for which the agent’s observer access is pending approval by a group leader. The response value for this field would only contain the list of groups that the agent is an approved observer of. The observer_of_pending_approval read-only attribute in the response will include the list of groups for which the agent’s observer access is pending approval by a group leader. |
member_of_pending_approval | array of numbers | Unique IDs of the restricted groups to which the agent’s addition as a member is pending approval..Read only |
observer_of_pending_approval | array of numbers | Unique IDs of the restricted groups to which the agent’s addition as an observer is pending approval.Read only |
role_ids | array of numbers | Unique IDs of the roles that are granted to the agent.Unsupported Note: Unsupported since May 31st 2023. Use roles -> role_id instead. |
roles | array of hashes | Each individual role is a hash Mandatory in the roles array that contains the attributes.
|
last_login_at | timestamp | Timestamp of the agent's last successful login. |
last_active_at | timestamp | Timestamp of the agent's recent activity. |
custom_fields | hash | Key-value pair containing the names and values of the (custom) agent fields. |
has_logged_in | boolean | Set to true if the user has logged in to Freshservice at least once, and false otherwise. |
active | boolean | True if the agent is active, false if the agent has been deactivated. | created_at | datetime | Date and time when the agent was created |
updated_at | datetime | Date and time when the agent was last updated |
Create an Agent
This operation allows you to create a new agent in Freshservice.
Attribute | Type | Description |
---|---|---|
first_name | string | First name of the agent.Mandatory |
last_name | string | Last name of the agent. |
occasional | boolean | True if the agent is an occasional agent, and false if full-time agent. |
job_title | string | Job title of the agent. |
string | Email address of the agent.Mandatory | |
work_phone_number | number | Work phone number of the agent. |
mobile_phone_number | number | Mobile phone number of the agent. |
department_ids | array of numbers | Unique IDs of the departments associated with the agent |
can_see_all_tickets_from_associated_departments | boolean | Set to true if the agent must be allowed to view tickets filed by other members of the department, and false otherwise |
reporting_manager_id | number | User ID of the agent's reporting manager. |
address | string | Address of the agent. |
time_zone | string | Time zone of the agent. Read more here. |
time_format | string | Time format for the agent.Possible values: 12h (12 hour format) 24h (24 hour format) |
language | string | Language used by the agent. The default language is “en” (English). Read more here. |
location_id | number | Unique ID of the location associated with the agent. |
background_information | string | Background information of the agent. |
scoreboard_level_id | number | Unique ID of the level of the agent in the Arcade. Possible values: 1 (Beginner) 2 (Intermediate) 3 (Professional) 4 (Expert) 5 (Master) 6 (Guru) |
group_ids | array of numbers | Unique IDs of the groups that the agent is a member of.Unsupported Note: Unsupported since May 31st 2023. Use member_of and observer_of instead. |
member_of | array of numbers | Unique IDs of the groups that the agent is a member of. The response value for this field would only contain the list of groups that the agent is an approved member of. The member_of_pending_approval read-only attribute in the response will include the list of groups for which the agent’s member access is pending approval by a group leader. |
observer_of | array of numbers | Unique IDs of the groups that the agent is an observer of. The response value for this field would only contain the list of groups that the agent is an approved observer of. The observer_of_pending_approval read-only attribute in the response will include the list of groups for which the agent’s observer access is pending approval by a group leader. |
role_ids | array of numbers | Unique IDs of the roles that are granted to the agent.Unsupported Note: Unsupported since May 31st 2023. Use roles -> role_id instead. |
roles | array of hashes | Each individual role is a hash Mandatory in the roles array that contains the attributes.
|
signature | string | Signature of the agent in HTML format. |
custom_fields | hash | Key-value pair containing the names and values of the (custom) agent fields. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"first_name":"Rolanda","last_name":"Hooch","occasional":false,"job_title":"Flying Instructor","email":"rolanda.hooch@hogwarts.edu","work_phone_number":"443532","mobile_phone_number":"553632","department_ids":[554],"can_see_all_tickets_from_associated_departments":false,"reporting_manager_id":2,"address":"Gryffindor Tower","time_zone":"Edinburgh","language":"en","location_id":34,"background_information":"","scoreboard_level_id":1,"member_of":[4, 5], "observer_of":[7], "roles":[{"role_id": 7, "assignment_scope": "specified_groups", "groups": [4, 5]}, {"role_id": 9, "assignment_scope": "assigned_items"}, {"role_id": 10, "assignment_scope": "specified_groups", "groups": [7]}],"custom_fields":{"quidditch_role":null,"hogsmeade_permission":true}}' 'https://domain.freshservice.com/api/v2/agents' |
View an Agent
This operation allows you to view information about a particular agent.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents/1434' |
List All Agents
This operation allows you to view information about all agents in the account. Use filters to view only specific agents (those who match the criteria that you choose). The filters listed in the table below can also be combined.
Note: When using filters, the query string must be URL encoded.
Filter by | Handle |
---|---|
email, mobile_phone_number, work_phone_number, active | /api/v2/agents?[filter]=[value] Example: /api/v2/agents?email=rubeus.hagrid@hogwarts.edu /api/v2/agents?mobile_phone_number=664345 /api/v2/agents?work_phone_number=5564435 /api/v2/agents?active=[true/false] |
state | /api/v2/agents?state=[fulltime/occasional] Example: /api/v2/agents?state=fulltime /api/v2/agents?state=occasional |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents' |
Retrieve the second page of the list of full-time agents. (This list contains information about 30 agents by default, and is always sorted by the first name of the agent.)
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?state=fulltime&per_page=20&page=2’ |
Filter Agents
Use Agent attributes to filter your list.
Note:
1. Filtered results cannot be sorted. By default it is sorted by created_at in descending order.
2. The query must be URL encoded (see example).
3. Query can be framed using the name of the agent fields, which can be obtained from the Supported Agent Fields Section.
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters.
5. Logical operators AND, OR along with parenthesis( ) can be used to group conditions.
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields.
7. Input for date field should be in UTC Format.
8. The number of objects returned per page is 30.
9. To scroll through the pages add the page parameter to the url. The page number starts with 1 and should not exceed 40.
10. To filter for fields with no values assigned, use the null keyword.
11. The "~" query operator can be used for "starts with" text searches. "Starts with" search is supported for one or more of the following attributes: first_name, last_name, name, email, mobile_phone_number, work_phone_number. The query format is https://domain.freshservice.com/api/v2/agents?query="~[attribute_1|attribute_2]:'somestring'". The query needs to be URL encoded. This would return a list of users for whom attribute_1 OR attribute_2 starts with "somestring". Refer to examples 11, 12, and 13.
12. Please note that any update made to an agent either in Freshservice application or through API may take a few minutes to get indexed, after which the updated results will be available through API.
Supported Agent Fields
Field | Type | Description |
---|---|---|
first_name | string | First name of the agent. |
last_name | string | Last name of the agent. |
name | string | Concatenation of first_name and last_name with single space in-between fields. |
job_title | string | Title of the agent. |
string | Email address of the agent. | |
work_phone_number | string | Work phone of the agent. |
mobile_phone_number | string | Mobile phone of the agent. |
department_id | integer | ID of the department(s) assigned to the agent. |
reporting_manager_id | integer | ID of the reporting manager. |
time_zone | string | ID of the department. |
language | string | Language code(Eg. en, ja-JP). |
location_id | integer | ID of the location. |
created_at | date | Date (YYYY-MM-DD) when the agent is created. |
updated_at | date | Date (YYYY-MM-DD) when the agent is updated. |
Custom Fields Supported | Type |
---|---|
Single line text | string |
Number | integer |
Dropdown | string |
Date | date |
Phone number | string |
1. Get the agent by email: 'agent@yourcompany.com'.
"email:'agent@yourcompany.com'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="email:%27agent%40yourcompany.com%27"' |
2. Get the agent(s) by name: ''.
"name : 'Lara Croft'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="name:%27Lara%20Croft%27"' |
3. Get the agent by work phone number: '(91)99999 10001'.
"work_phone_number : '(91)99999 10001'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="work_phone_number:%2891%2999999%2010001"' |
4. Get the agents whose mobile phone number is not set: null.
"mobile_phone_number :null"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="mobile_phone_number:null"' |
5. Get the agents by time zone: Eastern Time (US & Canada) AND language: 'en'.
"time_zone:'Eastern Time (US & Canada)' AND language:'en'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="time_zone%3A%27Eastern%20Time%20(US%20%26%20Canada)%27%20AND%20language%3A%27en%27"' |
6. Get all the agents by location_id: '5678 AND reporting manager id: 100001'.
"location_id:5678 AND reporting_manager_id:100001"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="location_id%3A5678%20AND%20reporting_manager_id%3A100001"' |
7. Get all the agents whose department ID is '12345' or '67890'.
"department_id:12345 OR department_id:67890"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="department_id:12345%20OR%20department_id:67890"' |
8. Using greater than(>) operator.
"created_at :> '2020-01-01'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="created_at%3A%3E%272020-01-01%27"' |
9. Using AND, OR, Parenthesis ( ) operator'
"job_title : 'Customer Success Specialist' AND (department_id:4001 OR department_id:5001) AND (location_id:200 OR location_id:300)"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query ="job_title%20%3A%20%27Customer%20Success%20Specialist%27%20AND%20(department_id%3A4001%20OR%20department_id%3A5001) %20AND%20(location_id%3A200%20OR%20location_id%3A300)"' |
10. Using custom fields: Labels defined as 'Product Name' AND 'Date of Joining'.
"product_name : 'Fresh Service' AND date_of_joining:<'2015-06-30'"
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="product_name%20%3A%20%27Fresh%20Service%27%20AND%20date_of_joining%3A%3C%272015-06-30%27"' |
11. List all agents whose first name starts with 'John'
'query="~[first_name]:'John'"'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="~%5Bfirst_name%5D%3A%27John%27' |
12. List all agents whose first name or last name starts with 'John'
'query="~[first_name|last_name]:'John'"'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="~%5Bfirst_name%7Clast_name%5D%3A%27John%27"' |
13. List all agents whose email firstname, lastname, or domain.ext starts with 'John' (where their email format is firstname.lastname@domain.ext). Searching by the email attribute searches all these three components automatically.
'query="~[email]:'John'"'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agents?query="~%5Bemail%5D%3A%27John%27' |
Validation errors:
invalid_field: 'Time period'.
"time_period :<'2020-02-02'"
1 | { "description": "Validation failed", "errors": [ { "field": "time_period", "message": "[:invalid_field]", "code": "invalid_value" } ] } |
invalid_value: 'Datatype validation'.
"department_id : 'abc'"
1 | { "description": "Validation failed", "errors": [ { "field": "department_id", "message": "[\"It should be a/an Positive Integer\"]", "code": "invalid_value" } ] } |
invalid_value: 'Dropdown choice validation'.
"country : 'not-exist'"
1 | { "description": "Validation failed", "errors": [ { "field": "country", "message": "[\"It should be one of the choice value.\"]", "code": "invalid_value" } ] } |
Update an Agent
This operation allows you to modify the profile of a particular agent.
Note:
can_see_all_tickets_from_associated_departments will automatically be set to false unless it is explicitly set to true in the payload, irrespective of the previous value of the field.
Attribute | Type | Description |
---|---|---|
occasional | boolean | True if the agent is an occasional agent, and false if full-time agent. |
string | Email address of the agent. | |
department_ids | array of numbers | Unique IDs of the departments associated with the agent |
can_see_all_tickets_from_associated_departments | boolean | Set to true if the agent must be allowed to view tickets filed by other members of the department, and false otherwise |
reporting_manager_id | number | User ID of the agent's reporting manager. |
address | string | Address of the agent. |
time_zone | string | Time zone of the agent. Read more here. |
time_format | string | Time format for the agent.Possible values: 12h (12 hour format) 24h (24 hour format) |
language | string | Language used by the agent. The default language is “en” (English). Read more here. |
location_id | number | Unique ID of the location associated with the agent. |
background_information | string | Background information of the agent. |
scoreboard_level_id | number | Unique ID of the level of the agent in the Arcade. Possible values: 1 (Beginner) 2 (Intermediate) 3 (Professional) 4 (Expert) 5 (Master) 6 (Guru) |
group_ids | array of numbers | Unique IDs of the groups that the agent is a member of.Unsupported Note: Unsupported since May 31st 2023. Use member_of and observer_of instead. |
member_of | array of numbers | Unique IDs of the groups that the agent is a member of. The input value for this field should also include the IDs of approval-enabled restricted groups for which the agent’s member access is pending approval by a group leader. The response value for this field would only contain the list of groups that the agent is an approved member of. The member_of_pending_approval read-only attribute in the response will include the list of groups for which the agent’s member access is pending approval by a group leader. |
observer_of | array of numbers | Unique IDs of the groups that the agent is an observer of. The input value for this field should also include the IDs of approval-enabled restricted groups for which the agent’s observer access is pending approval by a group leader. The response value for this field would only contain the list of groups that the agent is an approved observer of. The observer_of_pending_approval read-only attribute in the response will include the list of groups for which the agent’s observer access is pending approval by a group leader. |
role_ids | array of numbers | Unique IDs of the roles that are granted to the agent.Unsupported Note: Unsupported since May 31st 2023. Use roles -> role_id instead. |
roles | array of hashes | Each individual role is a hash Mandatory in the roles array that contains the attributes.
|
signature | string | Signature of the agent in HTML format. |
custom_fields | hash | Key-value pair containing the names and values of the (custom) agent fields. |
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -X PUT -d '{ "scoreboard_level_id": 2, "time_format":"24h", "roles":[{"role_id": 7, "assignment_scope":"assigned_items"}]}' 'https://domain.freshservice.com/api/v2/agents/1434' |
Update an agent to add them as a member to a Restricted Group with approvals required
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -X PUT -d '{ "member_of": [7, 8, 25]}' 'https://domain.freshservice.com/api/v2/agents/1434' |
Deactivate an Agent
This operation allows you to deactivate a particular agent.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/agents/1434' |
Forget an Agent
This operation allows you to permanently delete a agent and the tickets that they requested.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/agents/888/forget' |
Reactivate an Agent
This operation allows you to reactivate a particular deactivated agent.
1 | curl -v -u api_key:X -X PUT 'https://domain.freshservice.com/api/v2/agents/1434/reactivate' |
Convert To Requester
This operation allows you to convert a particular agent into a requester.
1 | curl -v -u api_key:X -X PUT 'https://domain.freshservice.com/api/v2/agents/1434/convert_to_requester' |
List All Agent Fields
This operation allows you to view all the built-in and custom fields for agents in your Freshservice account. Use 'include' to embed additional details in the response. Each include will consume an additional credit. For example if you embed the user field groups you will be charged a total of 3 API credits for the call.
Note:
By default, user field groups details will not be included in the response. They can be retrieved via the embedding functionality.
Embed | Handle |
---|---|
user_field_groups | /api/v2/requester_fields?include=user_field_groups Will return user field groups details like id, label |
AGENT FIELD | DESCRIPTION |
---|---|
name | Name of the agent field. |
user_field_group_id | ID of the user field group. |
label_for_admins | Field label shown to admins while editing an agent’s profile |
editable_by_admins | Signifies whether admins can edit the field value. |
mandatory_for_admins | Signifies whether admins have to necessarily provide a value for this field. |
label_for_agents | Field label shown to agents while viewing their own profile |
visible_to_agents | Signifies whether the field is shown to agents while viewing their own profile |
editable_by_agents | Signifies whether the field is editable by agents while viewing their own profile |
mandatory_for_agents | Signifies whether agents have to necessarily provide a value for this field while viewing their own profile. |
type | Type of data stored in this field |
default_field | Indicates whether it is a default field or user-defined custom field |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/agent_fields' |
User Assignment History
This operation retrieves the asset assignment history of a specific agent in Freshservice.
1 | curl -v -u api_key:X -X "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/users/2/assignment-history' |
Agent Roles
Roles allow you to manage access permissions for agents.
Note:
Only users with "Play God with Super Admin controls" can access the following APIs
Attribute | Type | Description |
---|---|---|
description | string | Description of the role |
id | number | Unique ID of the role |
name | string | Name of the role |
scopes | json | Access scope of the role in various modules To be Deprecated |
default | boolean | Set to true if it is a default role, and false otherwise | created_at | datetime | Date and time when the agent role was created |
updated_at | datetime | Date and time when the agent role was last updated |
View a Role
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/roles/1' |
List All Roles
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/roles' |
Agent Groups
You can organize your agents into groups like “Linux Support” and “Mac Support”. Segmenting agents into groups lets you easily assign tickets, create specific canned responses, manage workflows and generate group-level reports. The same agent can be a member of multiple groups as well.
Note:
Only users with "Play God with Super Admin controls" privilege can access the following APIs.
Attribute | Type | Description |
---|---|---|
name | string | Name of the group.Mandatory |
description | string | Description of the group. |
workspace_id | number | ID of the workspace to which this agent group belongs. The attribute is applicable only for accounts with the 'Workspaces' feature enabled. The default value is the ID of the primary workspace of the account. The response contains workspace_id to which an agent group belongs. |
unassigned_for | string | The time after which an escalation email is sent if a ticket in the group remains unassigned. The accepted values are “30m” for 30 minutes, “1h” for 1 hour, “2h” for 2 hours“, “4h” for 4 hours, “8h” for 8 hours, “12h” for 12 hours, “1d” for 1 day, “2d” for 2 days, and “3d” for 3 days. |
business_hours_id | number | Unique ID of the business hours configuration associated with the group. |
escalate_to | number | The Unique ID of the user to whom an escalation email is sent if a ticket in this group is unassigned. To create/update a group with an escalate_to value of ‘none’, please set the value of this parameter to ‘null’. |
agent_ids | array | Array of agent user IDs separated by commas.Unsupported Note: Unsupported since May 31st 2023. Use members and observers instead. |
members | array | A comma separated array of user IDs of agents who are members of this group. If the group is restricted and approvals-enabled, the input value for this field should also include the user IDs of agents whose member access to the group is pending approval by a group leader. The response value for this field would only contain the list of approved members. The members_pending_approval read-only attribute in the response will include the list of members whose approval is pending. |
observers | array | A comma separated array of user IDs of agents who are observers of this group. If the group is restricted and approvals-enabled, the input value for this field should also include the user IDs of agents whose observer access to the group is pending approval by a group leader. The response value for this field would only contain the list of approved observers. The observers_pending_approval read-only attribute in the response will include the list of observers whose approval is pending. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
restricted | boolean | Signifies whether a group is marked as restricted. Set to true if the group is restricted, and false otherwise. |
leaders | array | A comma separated array of user IDs of agents who are leaders of this group. If the group is restricted and approvals-enabled, the input value for this field should also include the user IDs of agents whose leader access to the group is pending approval by another group leader. The response value for this field would only contain the list of approved leaders. The leaders_pending_approval read-only attribute in the response will include the list of leaders whose approval is pending. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
members_pending_approval | array | A comma-separated array of user IDs of agents whose member access to the group is pending approval by a group leader. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled.Read only |
observers_pending_approval | array | A comma-separated array of user IDs of agents whose observer access to the group is pending approval by a group leader. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled.Read only |
leaders_pending_approval | array | A comma-separated array of user IDs of agents whose leader access to the group is pending approval by an existing group leader. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled.Read only |
approval_required | boolean | Signifies whether the restricted group requires approvals for membership changes. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
auto_ticket_assign | boolean | Describes the automatic ticket assignment type. Will not be supported if the "Round Robin" feature is disabled for the account. Set to true if automatic ticket assignment is enabled, and false otherwise. | created_at | datetime | Date and time when the agent group was created |
updated_at | datetime | Date and time when the agent group was last updated |
Create a Group
Note:
1. When creating groups with approval required only the leaders will be added to the groups immediately while the members and observers would get added after their membership approval is approved.
Attribute | Type | Description |
---|---|---|
name | string | Name of the group.Mandatory |
description | string | Description of the group. |
workspace_id | number | ID of the workspace to which this agent group should belong. The attribute is applicable only for accounts with the 'Workspaces' feature enabled. If not specified, the value is defaulted to the ID of the primary workspace of the account. |
unassigned_for | string | The time after which an escalation email is sent if a ticket in the group remains unassigned. The accepted values are “30m” for 30 minutes, “1h” for 1 hour, “2h” for 2 hours“, “4h” for 4 hours, “8h” for 8 hours, “12h” for 12 hours, “1d” for 1 day, “2d” for 2 days, and “3d” for 3 days. |
business_hours_id | number | Unique ID of the business hours configuration associated with the group. |
escalate_to | number | The Unique ID of the user to whom an escalation email is sent if a ticket in this group is unassigned. To create/update a group with an escalate_to value of ‘none’, please set the value of this parameter to ‘null’. |
agent_ids | array | Array of agent user IDs separated by commas.Unsupported Note: Unsupported since May 31st 2023. Use members and observers instead. |
members | array | A comma separated array of user IDs of agents who are members of this group. The response value for this field would only contain the list of approved members. The members_pending_approval read-only attribute in the response will include the list of members whose approval is pending. |
observers | array | A comma separated array of user IDs of agents who are observers of this group. The response value for this field would only contain the list of approved observers. The observers_pending_approval read-only attribute in the response will include the list of observers whose approval is pending. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
restricted | boolean | Signifies whether a group is marked as restricted. Set to true if the group is restricted, and false otherwise. |
leaders | array | A comma separated array of user IDs of agents who are leaders of this group. The response value for this field would only contain the list of approved leaders. The leaders_pending_approval read-only attribute in the response will include the list of leaders whose approval is pending. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
approval_required | boolean | Signifies whether the restricted group requires approvals for membership changes. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
auto_ticket_assign | boolean | Describes the automatic ticket assignment type. Will not be supported if the "Round Robin" feature is disabled for the account. Set to true if automatic ticket assignment is enabled, and false otherwise. |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{"name":"Linux Support", "description":"Support team for Linux VMs, workstations, and servers", "unassigned_for":"30m", "escalate_to":1155, "members": [1], "observers": [16]}' 'https://domain.freshservice.com/api/v2/groups' |
1. Create a Restricted Group and mark a particular agent as its leader
1 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{"name":"HR Group", "description":"To handle all HR related sensitive tickets", "restricted":true, "members": [15], "leaders": [15]}' 'https://domain.freshservice.com/api/v2/groups' |
2. Create a Restricted Group with approvals required
1 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{"name":"Payroll Queries", "description":"To handle all employee payroll-related disputes.", "restricted":true, "approval_required": true, "members": [10003024749, 10002590061], "leaders": [10003024749]}' 'https://domain.freshservice.com/api/v2/groups' |
3. Create a Restricted Group in a workspace
1 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{"name":"Payroll Queries", "description":"To handle all employee payroll-related disputes.", "restricted":true, "approval_required": true, "members": [10003024749, 10002590061], "leaders": [10003024749], "workspace_id": 4}' 'https://domain.freshservice.com/api/v2/groups' |
View a Group
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/groups/1' |
List All Groups
Note:
List of agent groups belonging to a particular workspace can be retrieved by passing query parameter as workspace_id=[number]. It is not possible to retrieve the list of agent groups across all workspaces.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/groups' |
1. List all the Agent Groups present in a Workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/groups?workspace_id=4' |
Update a Group
Note:
1. To delete all the agents associated with a group, update the group with "members"= [ ] (empty array)
2. Appending the pending users from "members_pending_approval", "observers_pending_approval", "leaders_pending_approval" to "members", "observers", "leaders" keys respectively will retain the pending approval request for these users. Not doing so would withdraw their membership approval request.
3. When a restricted group that required approvals is either marked unrestricted or approval required is set to false the pending membership request will get auto approved.
Attribute | Type | Description |
---|---|---|
name | string | Name of the group.Mandatory |
description | string | Description of the group. |
workspace_id | number | Workspace ID of the agent group to be updated. The attribute is applicable only for accounts with the 'Workspaces' feature enabled. The workspace_id of an agent group cannot be modified.Read only |
unassigned_for | string | The time after which an escalation email is sent if a ticket in the group remains unassigned. The accepted values are “30m” for 30 minutes, “1h” for 1 hour, “2h” for 2 hours“, “4h” for 4 hours, “8h” for 8 hours, “12h” for 12 hours, “1d” for 1 day, “2d” for 2 days, and “3d” for 3 days. |
business_hours_id | number | Unique ID of the business hours configuration associated with the group. |
escalate_to | number | The Unique ID of the user to whom an escalation email is sent if a ticket in this group is unassigned. To create/update a group with an escalate_to value of ‘none’, please set the value of this parameter to ‘null’. |
agent_ids | array | Array of agent user IDs separated by commas.Unsupported Note: Unsupported since May 31st 2023. Use members and observers instead. |
members | array | A comma separated array of user IDs of agents who are members of this group. If the group is restricted and approvals-enabled, the input value for this field should also include the user IDs of agents whose member access to the group is pending approval by a group leader. The response value for this field would only contain the list of approved members. The members_pending_approval read-only attribute in the response will include the list of members whose approval is pending. |
observers | array | A comma separated array of user IDs of agents who are observers of this group. If the group is restricted and approvals-enabled, the input value for this field should also include the user IDs of agents whose observer access to the group is pending approval by a group leader. The response value for this field would only contain the list of approved observers. The observers_pending_approval read-only attribute in the response will include the list of observers whose approval is pending. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
restricted | boolean | Signifies whether a group is marked as restricted. Set to true if the group is restricted, and false otherwise. |
leaders | array | A comma separated array of user IDs of agents who are leaders of this group. If the group is restricted and approvals-enabled, the input value for this field should also include the user IDs of agents whose leader access to the group is pending approval by another group leader. The response value for this field would only contain the list of approved leaders. The leaders_pending_approval read-only attribute in the response will include the list of leaders whose approval is pending. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
approval_required | boolean | Signifies whether the restricted group requires approvals for membership changes. This attribute is only applicable for accounts which have the “Access Controls Pro” feature enabled. |
auto_ticket_assign | boolean | Describes the automatic ticket assignment type. Will not be supported if the "Round Robin" feature is disabled for the account. Set to true if automatic ticket assignment is enabled, and false otherwise. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"name":"Linux Support", "description":"Support team for Linux VMs, workstations, and servers", "unassigned_for":"30m", "members":[1,16]}' 'https://domain.freshservice.com/api/v2/groups/2' |
1. Mark an existing group as restricted and assign an agent as its leader
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"restricted":true, "members": [1, 16], "leaders": [16]}' 'https://domain.freshservice.com/api/v2/groups/2' |
2. Update the existing Payroll group to add another agent to the group
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"members": [10003024749, 10002590061, 10002973932]}' 'https://domain.freshservice.com/api/v2/groups/10000378431' |
3. Update the existing Payroll group to add another agent to a group in a workspace
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"members": [10003024749, 10002590061, 10002973932], "workspace_id": 2}' 'https://domain.freshservice.com/api/v2/groups/10000378431' |
Delete a Group
Note:
1. Deleting a Group will only disband the group and not delete its members.
2. Deleted groups cannot be restored.
3. When deleting a group, agents who have their only role in this group being deleted will be rescoped to the "assigned_items" scope from "specified_groups" for this role.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/groups/5' |
Requester Groups
Note:
Only groups of type “manual” can be created or updated through APIs.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the requester groupRead Only |
name | string | Name of the requester group.Mandatory |
description | string | Description of the requester group. |
type | string | Method of requester addition. “manual” if individual requesters can be chosen manually, and “rule_based” if members are automatically added based on rules.Read Only |
Create a Requester Group
Note:
Only groups of type “manual” can be created through this API.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the requester groupRead Only |
name | string | Name of the requester group.Mandatory |
description | string | Description of the requester group. |
type | string | Method of requester addition. “manual” if individual requesters can be chosen manually, and “rule_based” if members are automatically added based on rules.Read Only |
1 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{ "name":"Branch Managers", "description":"Requester group for branch managers across all locations"}' 'https://domain.freshservice.com/api/v2/requester_groups' |
View a Requester Group
Note:
Groups of both types (“manual”/”rule_based”) can be viewed through this API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requester_groups/21' |
List All Requester Groups
Note:
Groups of both types (“manual”/”rule_based”) can be listed through this API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requester_groups' |
Get the second page (requests from 31-60) of all the requester groups in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requester_groups?per_page=30&page=2' |
Update a Requester Group
Note:
Only groups of type “manual” can be updated through this API.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the requester groupRead Only |
name | string | Name of the requester group.Mandatory |
description | string | Description of the requester group. |
type | string | Method of requester addition. “manual” if individual requesters can be chosen manually, and “rule_based” if members are automatically added based on rules.Read Only |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "name":"Human Resources", "description":"Requester group all employees whose department is HR" }' 'https://domain.freshservice.com/api/v2/requester_group/8' |
Delete a Requester Group
Note:
1. Deleting a Requester Group will only disband the requester group and will not delete its members.
2. Deleted requester groups cannot be restored.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/requester_groups/5' |
Add Requester to Requester Group
Note:
1.Requesters can be added only to manual requester groups.
2.Requester can be added one at a time.
1 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST 'https://domain.freshservice.com/api/v2/requester_groups/1/members/77' |
Delete Requester from Requester Group
Note:
1.Requesters can be removed only from manual requester groups.
2.Requester can be removed one at a time.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/requester_groups/1/members/77' |
List Requester Group Members
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requester_groups/1/members' |
Get the second page (requests from 31-60) of requesters who are associated to requester groups.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/requester_groups/1/members?per_page=30&page=2' |
Locations
Locations refer to cities, campuses, offices and rooms where assets and users can be found.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the location. |
name | string | Name of the location.Mandatory |
parent_location_id | number | ID of the parent location. |
primary_contact_id | number | User ID of the primary contact (must be a user in Freshservice). |
line1 | string | Address line 1. |
line2 | string | Address line 2. |
city | string | Name of the City. |
state | string | Name of the State. |
country | string | Name of the Country. |
zipcode | string | Zipcode of the location. |
created_at | datetime | Date and time when the location was created |
updated_at | datetime | Date and time when the location was last updated |
Create a Location
This operation allows you to create a new location in Freshservice.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the location. |
name | string | Name of the location.Mandatory |
parent_location_id | number | ID of the parent location. |
primary_contact_id | number | User ID of the primary contact (must be a user in Freshservice) |
line1 | string | Address line 1. |
line2 | string | Address line 2. |
city | string | Name of the Country. |
state | string | Name of the State. |
country | string | Name of the Country. |
zipcode | string | Zipcode of the location. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"name": "HQ", "parent_location_id": 2, "primary_contact_id": null, "address": {"line1": "1250 Bayhill Drive","line2": "Suite 315", "city": "San Bruno","state": "California","country": "US","zipcode": "94066"}}' 'https://domain.freshservice.com/api/v2/locations' |
View a Location
This operation allows you to view information about a particular location.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/locations/15’ |
List all Locations
This operation allows you to view information about all the locations in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/locations’ |
1. Get the second page (locations from 31-60) of a list of all the locations in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/locations?per_page=30&page=2' |
Filter Locations
You can filter locations by their Name. Please note that the query string needs to be URL encoded.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/locations?query="name:%United%20Kingdom%27"' |
Update a Location
This operation allows you to update an existing location.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the location. |
name | string | Name of the location. |
parent_location_id | number | ID of the parent location. |
primary_contact_id | number | User ID of the primary contact (must be a user in Freshservice). |
line1 | string | Address line 1. |
line2 | string | Address line 2. |
city | string | Name of the City. |
state | string | Name of the State. |
country | string | Name of the Country. |
zipcode | string | Zipcode of the location. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"name": "HeadQuaters","parent_location_id": 2,"primary_contact_id": null,"address": {"line1": "1250 Bayhill Drive","line2": "Suite 315","city": "San Bruno","state": "California","country": "US","zipcode": "94066"}}' 'https://domain.freshservice.com/api/v2/locations/15' |
Delete a Location
This operation allows you to delete a particular location.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/locations/15’ |
Products
When assets refer to individual items existing in an organization, a product refers to a specific model of the asset. For example, every laptop in an organization is an asset while Macbook Pro 15 inches 2019 model is a product. The product catalog contains all the products that were used, are in use or will be used in the organization.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the product. |
name | string | Name of the Product.Mandatory |
asset_type_id | number | ID of the asset type(must be a type in Freshservice)Mandatory |
manufacturer | string | Manufacturer of the product |
status | string | Status of the product. |
mode_of_procurement | string | Mode of procurement of the product. |
depreciation_type_id | number | ID of the depreciation type. |
description | string | HTML Content of the product. |
description_text | string | Description of the product in plain text. |
created_at | string | Date and time when the product was created |
updated_at | string | Date and time when the product was last updated |
Product Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
status | In Production, In Pipeline, Retired | The default value is "In Production" |
mode_of_procurement | Buy, Lease, Both | The default value is "Buy" |
Create a Product
This operation allows you to create a new product in Freshservice.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the product. |
name | string | Name of the Product.Mandatory |
asset_type_id | number | ID of the asset type(must be a type in Freshservice)Mandatory |
manufacturer | string | Manufacturer of the product |
status | string | Status of the product. |
mode_of_procurement | string | Mode of procurement of the product. |
depreciation_type_id | number | ID of the depreciation type. |
description | string | HTML Content of the product. |
description_text | string | Description of the product in plain text. |
created_at | string | Date and time when the product was created |
updated_at | string | Date and time when the product was last updated |
Product Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
status | In Production, In Pipeline, Retired | The default value is "In Production" |
mode_of_procurement | Buy, Lease, Both | The default value is "Buy" |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"name": "XBox", "asset_type_id": 3, "manufacturer": "Flex", "status":"In Pipeline", "mode_of_procurement":"Buy","depreciation_type_id":1,"description":"The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series."}' 'https://domain.freshservice.com/api/v2/products' |
View a Product
This operation allows you to view a particular product.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/products/7' |
List All Products
This operation allows you to view information about all products in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/products' |
1. Get the second page (products from 31-60) of a list of all the products in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/products?per_page=30&page=2' |
Update a Product
This operation allows you to update an existing product.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the product. |
name | string | Name of the Product.Mandatory |
asset_type_id | number | ID of the asset type(must be a type in Freshservice)Mandatory |
manufacturer | string | Manufacturer of the product |
status | string | Status of the product. |
mode_of_procurement | string | Mode of procurement of the product. |
depreciation_type_id | number | ID of the depreciation type. |
description | string | HTML Content of the product. |
description_text | string | Description of the product in plain text. |
created_at | string | Date and time when the product was created |
updated_at | string | Date and time when the product was last updated |
Product Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
status | In Production, In Pipeline, Retired | The default value is "In Production" |
mode_of_procurement | Buy, Lease, Both | The default value is "Buy" |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"name": "XBox", "asset_type_id": 3, "manufacturer": "Flex", "status":"In Production", "mode_of_procurement":"Buy","depreciation_type_id":2,"description":"The Xbox 360 is a home video game console developed by Microsoft. As the successor to the original Xbox, it is the second console in the Xbox series."}' 'https://domain.freshservice.com/api/v2/products/7' |
Delete a Product
This operation allows you to delete a particular product.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/products/7’ |
Vendors
Vendors refer to third-party companies and service providers who provide the necessary assets or services to your organization.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the vendor. |
name | string | Name of the vendor.Mandatory |
description | string | Description of the vendor. |
primary_contact_id | number | User ID of the primary contact (must be a user in Freshservice). |
line1 | string | Address lines. |
city | string | Name of the city. |
state | string | Name of the state. |
country | string | Name of the country. |
zipcode | string | Zipcode of the location. |
created_at | datetime | Date and time when the vendor was created |
updated_at | datetime | Date and time when the vendor was last updated |
Create a Vendor
This operation allows you to create a vendor.
Attribute | Type | Description |
---|---|---|
name | string | Name of the vendor.Mandatory |
description | string | Description of the vendor. |
primary_contact_id | number | User ID of the primary contact (must be a user in Freshservice). |
line1 | string | Address lines. |
city | string | Name of the city. |
state | string | Name of the state. |
country | string | Name of the country. |
zipcode | string | Zipcode of the location. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"name": "Intel","description": "Intel Corp", "primary_contact_id": null, "address": {"line1": "1250 Bayhill Drive", "city": "San Bruno","state": "California","country": "US","zipcode": "94066"}}' 'https://domain.freshservice.com/api/v2/vendors' |
View a Vendor
This operation allows you to view a particular vendor.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/vendors/15' |
List All Vendors
This operation allows you to view information about all vendors in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/vendors' |
1. Get the second page (vendors from 31-60) of a list of all the vendors in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/vendors?per_page=30&page=2' |
Update a Vendor
This operation allows you to update a vendor.
Attribute | Type | Description |
---|---|---|
name | string | Name of the vendor.Mandatory |
description | string | Description of the vendor. |
primary_contact_id | number | User ID of the primary contact (must be a user in Freshservice). |
line1 | string | Address lines. |
city | string | Name of the city. |
state | string | Name of the state. |
country | string | Name of the country. |
zipcode | string | Zipcode of the location. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"name": "Apple","description": "AAPL","primary_contact_id": null,"address": {"line1": "1 Infinite Loop","city": "Cupertino","state": "California","country": "US","zipcode": "95014"}}' 'https://domain.freshservice.com/api/v2/vendors/1' |
Delete a Vendor
This operation allows you to delete a vendor.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/vendors/5' |
Assets
Assets are any items that are owned and managed in an organization. These include laptops, servers, monitors, printers, routers, etc. The Assets module in Freshservice allows you to manage the entire lifecycle of an asset, right from its procurement to retirement. During the reporting of an IT issue, the asset is often tagged along with the ticket either by the requester or the agent.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the asset. |
workspace_id | number | ID of the workspace that the asset belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
display_id | numbers | Display ID of the asset. |
name | string | Name of the asset.Mandatory |
description | string | Description of the asset. |
asset_type_id | number | ID of the asset type.Mandatory |
asset_tag | string | Asset tag of the asset. |
impact | string | Impact of the asset. |
author_type | string | Indicates whether the asset was created by a user or discovery tools (Probe or Agent).Read Only |
usage_type | string | Usage type of the asset (Loaner / Permanent). |
user_id | number | ID of the associated user (Used By). |
location_id | number | ID of the associated location. |
department_id | number | ID of the associated department. |
agent_id | number | ID of the associated agent (Managed By). |
group_id | number | ID of the associated agent group (Managed By Group). |
assigned_on | datetime | Date and time when the asset was assigned. |
created_at | datetime | Date and time when the asset was created.Read Only |
updated_at | datetime | Date and time when the asset was updated.Read Only |
Asset Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
impact | low, medium, high | The default value is “low” |
usage_type | permanent, loaner | The default value is “permanent” |
Asset Assignment History
This operation retrieves the user assignment history for a specific asset in Freshservice.
1 | curl -v -u api_key:X -X "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/assets/8/assignment-history' |
Create an Asset
This operation allows you to create a new asset in Freshservice.
Asset Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
impact | low, medium, high | The default value is “low” |
usage_type | permanent, loaner | The default value is “permanent” |
1 2 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "name": "Macbook Pro","asset_type_id": 25, "asset_tag":"ASSET-9", "impact":"low", "usage_type":"permanent", "description":"13.3-inch (diagonal) LED-backlit glossy widescreen display,1440-by-900 resolution", "location_id":null, "agent_id":null, "department_id":null, "group_id":9, "workspace_id":3, "assigned_on": "2014-07-26T12:25:04+05:30", "type_fields": { "product_25" : 10, "vendor_25" : 14, "cost_25":5000 , "salvage":100, "depreciation_id":30, "warranty_25":20, "acquisition_date_25":"2018-07-26T12:25:04+05:30", "warranty_expiry_date_25":"2018-07-26T12:25:04+05:30", "domain_25":1, "asset_state_25":"In Use", "serial_number_25":"SW12131133", "last_audit_date_25":"2014-07-26T12:25:04+05:30" } }' 'https://domain.freshservice.com/api/v2/assets' |
View an Asset
This operation allows you to view a particular asset.
Use 'include' to embed additional details in the response. Each include will consume an additional API credit.
Embed | Handle |
---|---|
type_fields | /api/v2/assets/[display_id]?include=type_fields Will return all fields that are specific to each asset type. For example, for Hardware Asset Type, including type_fields will return fields such as Product_ID, Vendor_ID and Serial_number |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets/11' |
1. Get the associated type fields along with the asset response.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets/11?include=type_fields' |
View List of Assets
Lists all the assets in your Freshservice account.
Use Asset Filters to view only specific assets (those which match the criteria that you choose) and Asset Search to search specific assets from your list. By default only assets that are not in trash will be returned unless you use the 'trashed' filter.
Note:
1. By default, assets will be sorted based on "created_at" date (most recent on top).
2. By default, only the base attributes of the asset will be retrieved.
3. To get all the attributes, including asset type specific fields, use 'include' to embed additional details in the response.
4. Each include will consume an additional 2 credits. For example, if you embed the 'type_fields' information you will be charged a total of 3 API credits for the call.
5. If a workspace_id is not specified as a URL parameter, only assets from the primary workspace will be included in the response. If workspace_id is specified as 0, assets from across all workspaces will be included in the response. Applicable only to accounts on the Employee Support Mode.
Filter by | Handle |
---|---|
Workspace | /api/v2/assets?workspace_id=[id] 'workspace_id' is applicable only to accounts on the Employee Support Mode. The value 0 for workspace_id will return assets from all workspaces, with only global level fields. |
Sort by | Handle |
---|---|
id, created_at, updated_at | /api/v2/assets?order_by=created_at Default order by is created_at. |
asc, desc | /api/v2/assets?order_type=asc Default sort order is desc. |
Embed | Handle |
---|---|
type_fields | /api/v2/assets?include=type_fields Will return all fields that are specific to each asset type. For example, for Hardware Asset Type, including type_fields will return fields such as Product_ID, Vendor_ID, Serial_number, etc. |
trashed | /api/v2/assets?trashed=true Will return all the assets that are in trash. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets' |
1. Get the second page (assets from 31-60) of a list of all active filter_assets.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?per_page=30&page=2' |
2. Get the first page of a list of assets including all type fields. The assets will be listed in descending order by Created at Date.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?include=type_fields' |
3. Get the first page of a list of assets by updated_at date sorted in descending order.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?order_by=updated_at&order_type=desc' |
4. Get the first page of a list of assets in trash.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?trashed=true' |
5. Get the list of all assets from workspaces to which the user has access.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?workspace_id=0' |
6. Get the list of assets from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?workspace_id=3' |
Search Assets
Use asset attributes to search from your list.
Note:
1. Search results cannot be sorted. By default it is sorted by created_at in descending order.
2. The search query must be URL encoded (see example).
3. Query can be framed using the asset fields, which can be obtained from Supported Asset Fields section.
4. Search query string must be enclosed between a pair of double quotes.
5. If the search query string contains apostrophe, it must be escaped (see example).
6. The number of objects returned per page is 30. The total count of the results will be returned along with the result (In the headers).
7. Please note that any updates made to assets either in Freshservice application or through APIs may take a few minutes to get indexed, after which the updated results will be available through API.
Supported Asset Fields
Field | Type | Description |
---|---|---|
name | string | Display name of the asset. |
asset_tag | string | Tag that is assigned to the asset. |
serial_number | string | Serial number of the asset. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?search="name%3A%27dell%27"' |
1. Search assets in trash which has name dell.
search=" name:'dell' "
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?search="name%3A%27dell%27"&trashed=true' |
2. Search string must be escaped if it contains apostrophe.
search=" name:'andrea\'s laptop' "
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?search="name%3A%27andrea%5C%27s%20laptop%27"' |
Filter Assets
Use asset attributes to filter your list.
Note:
1. Filtered results cannot be sorted. By default it is sorted by created_at in descending order.
2. The query must be URL encoded (see example).
3. Query can be framed using the name of the asset fields, which can be obtained from Supported Asset Fields section.
4. Query string must be enclosed between a pair of double quotes and can have up to 512 characters.
5. Logical operators AND, OR along with parentheses () can be used to group conditions.
6. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields and numeric fields.
7. Input for date fields should be in UTC Format.
8. The number of objects returned per page is 30. The total count of the results will be returned along with the result (In the headers).
9. The maximum number of pages returned is 40.
10. To filter for fields with no values assigned, use the null keyword.
11. Please note that any updates made to assets either in Freshservice application or through APIs may take a few minutes to get indexed, after which the updated results will be available through API.
12. By default, only assets from the primary workspace will be returned for accounts on the Employee Support Mode. For assets from other workspaces, use the workspace_id filter.
Supported Asset Fields
Field | Type | Description |
---|---|---|
workspace_id | number | Workspace ID of the ticket. This attribute is applicable only to accounts on the Employee Support Mode. The value 0 for workspace_id will return assets from all workspaces |
asset_type_id | integer | ID of the asset type. |
department_id | integer | ID of the department to which the asset belongs. |
location_id | integer | ID of the location. |
asset_state | string | Status of the asset (Eg. IN USE). |
user_id | integer | ID of the user to whom the asset is assigned. |
agent_id | integer | ID of the agent by whom the asset is managed. |
name | string | Display name of the asset. |
asset_tag | string | Tag that is assigned to the asset. |
created_at | date | Date (YYYY-MM-DD) when the asset is created.Read Only |
updated_at | date | Date (YYYY-MM-DD) when the asset is updated.Read Only |
Deprecation Warning:
The older filter pattern "query=[query]" will be deprecated by end of June 2022 and would remain backward compatible until then. We recommend you to use the new filter query pattern shown above.
1. Get the second page of assets (including asset type specific fields) that are In Stock and created since 2018-08-10 across all workspaces.
" asset_state:'IN STOCK' AND created_at:>'2018-08-10' "
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?include=type_fields&filter="asset_state:%27IN%20STOCK%27%20AND%20created_at:>%272018-08-10%27"&page=2' |
2. Combining search and filter to get the assets that are In Stock and which has the serial number starting with HSN from a particular workspace.
search=" serial_number:'HSN' " and filter=" asset_state:'IN STOCK' AND workspace_id: 3 "
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets?search="serial_number%3A%27HSN%27"&filter="asset_state%3A%27IN%20STOCK%27%20AND%20workspace_id%3A%202"' |
Update an Asset
This operation allows you to update an existing asset.
Note:
The workspace_id attribute cannot be updated through the Update operation. It can only be updated through the Move operation.
Asset Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
impact | low, medium, high | The default value is “low” |
usage_type | permanent, loaner | The default value is “permanent” |
1 2 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "name": "Macbook Pro 2","asset_type_id": 25, "asset_tag":"ASSET-9", "impact":"high", "usage_type":"loaner", "description":"13.3-inch (diagonal) LED-backlit glossy widescreen display,1440-by-900 resolution", "location_id":null, "agent_id":null, "department_id":null, "group_id":9, "assigned_on": "2014-07-26T12:25:04+05:30", "type_fields": { "product_25" : 10, "vendor_25" : 14, "cost_25":5000 , "salvage":100, "depreciation_id":30, "warranty_25":20, "acquisition_date_25":"2018-07-26T12:25:04+05:30", "warranty_expiry_date_25":"2018-07-26T12:25:04+05:30", "domain_25":1, "asset_state_25":"In Use", "serial_number_25":"SW12131133", "last_audit_date_25":"2014-07-26T12:25:04+05:30" } }' 'https://domain.freshservice.com/api/v2/assets/11' |
Delete an Asset
This operation allows you to delete a particular asset.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/assets/9’ |
Restore an Asset
This operation allows you to restore a deleted asset.
1 | curl -v -u api_key:X -X PUT 'https://domain.freshservice.com/api/v2/assets/9/restore’ |
Delete an Asset Permanently
This operation allows you to permanently delete an asset which cannot be restored later.
1 | curl -v -u api_key:X -X PUT 'https://domain.freshservice.com/api/v2/assets/9/delete_forever’ |
Move an Asset
This API moves an asset to a different workspace, while also allowing the assigned group and agent to be modified.
Note:
This endpoint is applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X PUT -d '{ "workspace_id": 2, "agent_id": 16216, "group_id": 28509 }' 'https://domain.freshservice.com/api/v2/assets/19277/move_workspace' |
List all Asset Components
This operation allows you to view information about all the components of an asset in the account.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the component. |
component_type | string | Type of the Component. (Example: Processor, Memory) |
component_data | json | Details of the Component. |
created_at | datetime | Date and time when the component was created.Read Only |
updated_at | datetime | Date and time when the component was updated.Read Only |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets/1/components' |
List All Associated Requests
This operation allows you to view a list of all the requests associated to the asset in the account.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the request. |
request_type | string | Type of the request associated to the Asset. (Example: Ticket, Change...etc). |
request_id | string | Display ID of the request. (Example: #INC-1). |
request_details | string | Subject of the request. |
request_status | string | Status of the request. |
created_at | datetime | Date and time when the request was created.Read Only |
updated_at | datetime | Date and time when the request was updated.Read Only |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets/1/requests' |
1. Get the second page (requests from 31-60) of all the requests associated to the asset in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets/1/requests?per_page=30&page=2' |
List all associated Contracts
This operation allows you to get a list of all the contracts that an asset has been associated to.
Attribute | Type | Description |
---|---|---|
id | string | Contract ID specific to your account. Read-Only |
contract_id | string | Unique Contract Number. Mandatory |
contract_type | string | Type of the Contract.(Example: Lease, Maintenance) Mandatory |
contract_name | string | Subject/Title of the Contract Mandatory |
contract_status | string | Status of the contract.(Example: Active, Draft) Read-Only |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets/1/contracts' |
1. Get the second page (contracts from 31-60) of all the contracts associated to the asset in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets/1/contracts?per_page=30&page=2' |
Create Relationships in bulk
This operation allows you to create new relationships in bulk.
Note:
1. This is an asynchronous operation and is performed using background jobs. The response of the api contains the job id, which can be used to query the status of the job.
2. After the first 5 relationships, every additional 5 relationships created using this api consumes one API credit.
Attribute | Type | Description |
---|---|---|
relationship_type_id | number | ID of the relationship type.Mandatory |
primary_id | number | ID of the entity from which the relationship will be created.Mandatory |
primary_type | string | Type of the entity from which the relationship will be created.Mandatory |
secondary_id | number | ID of the entity to which the relationship will be created.Mandatory |
secondary_type | string | Type of the entity to which the relationship will be created.Mandatory |
Relationship Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values |
---|---|
primary_type, secondary_type | asset, requester, agent, department, software |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"relationships": [{"relationship_type_id": 1,"primary_id": 38806,"primary_type": "asset","secondary_id": 38805,"secondary_type": "asset"}, {"relationship_type_id": 2,"primary_id": 38806,"primary_type": "asset","secondary_id": 33228,"secondary_type": "agent"},{"relationship_type_id": 3,"primary_id": 38809,"primary_type": "asset","secondary_id": 290058,"secondary_type": "requester"}] }' 'https://domain.freshservice.com/api/v2/relationships/bulk-create' |
Background Jobs API
Background Jobs api can be used to query the status of the background job. What various "status" values indicate is represented in the below table
Status | Comments |
---|---|
queued | Job is queued and ready to be executed |
in progress | Job execution started |
partial | Job completed. Few relationships created successfully, but few failed |
success | Job completed. All relationships are created |
failed | Job completed. No relationships are created |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/jobs/25cf5d0b-b2cd-4224-9715-bd48cb89896d' |
View a Relationship
This operation allows you to view a particular relationship in your Freshservice account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/relationships/20' |
List all Relationships in the Account
Lists all the relationships in your Freshservice account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/relationships' |
List all Relationships for an Asset
Lists all the relationships of a particular asset.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/assets/16867/relationships' |
Delete Relationships in bulk
Delete relationships in your Freshservice account in bulk.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/relationships?ids=20,21' |
List all Relationship Types
Lists all the relationship types in your Freshservice account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/relationship_types' |
Purchase Order
A purchase order (PO) is an official document issued by a buyer to a seller indicating the types, quantities, and agreed prices for products or services.
This section lists all API that can be used to create, list, edit or delete purchase order.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the purchase order. |
workspace_id | number | ID of the workspace that the purchase order belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
vendor_id | number | ID of the vendor with whom the order is placed. |
name | string | Title of the purchase order.Mandatory |
po_number | string | Unique Purchase order number.Mandatory |
vendor_details | string | Details of the vendor with whom the order is placed.Mandatory |
expected_delivery_date | string | Expected delivery date of the purchase order. |
created_at | string | Created date and time of the purchase order. |
updated_at | string | Updated date and time of the purchase order. |
created_by | string | ID of the agent who created purchase order.Read Only |
status | number | Status of the purchase order(Used By). |
shipping_address | string | Address to which the order should be shipped.Mandatory |
billing_same_as_shipping | boolean | True if Billing address is same as Shipping address. |
billing_address | string | Address to which the order should be billed.Mandatory |
currency_code | string | Currency unit used in the transaction.Mandatory |
conversion_rate | decimal | Conversion rate to convert selected currency unit to helpdesk currency. |
department_id | integer | Unique ID of the department. |
discount_percentage | integer | Percentage of discount on the order. |
tax_percentage | integer | Percentage of tax on the order. |
shipping_cost | integer | Total cost of shipping the order. |
custom_fields | object | Any Custom field required for purchase order. |
purchase_items | array | Items to be ordered.Mandatory |
Purchase Items
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
item_type | integer | Type of item to be ordered. Mandatory |
item_name | string | Name of the items to be ordered. Mandatory |
description | string | Item description. |
cost | decimal | Cost of the item. Mandatory |
quantity | integer | Quantity of item to be ordered. Mandatory |
tax_percentage | decimal | Percentage of tax on item cost. Mandatory |
Custom Fields
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
terms_and_conditions | string | The default value is null. |
Create a new Purchase Order
This operation allows you to Create a new Purchase Order in Freshservice.
1 2 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"vendor_id":0,"name":"string","po_number":"string","vendor_details":"string", "expected_delivery_date":"2021-02-11T14:07:44.514Z","created_at":"2021-02-11T14:07:44.514Z","updated_at":"2021-02-11T14:07:44.514Z","shipping_address":"string","billing_same_as_shipping":true,"billing_address":"string","currency_code":"string","department_id":0,"discount_percentage":0,"tax_percentage":0,"shipping_cost":0,"custom_fields":{},"purchase_items":[{"item_name":"string","description":"string","cost":0,"quantity":0,"tax_percentage":0}], "workspace_id": 2}' 'https://domain.freshservice.com/api/v2/purchase_orders' |
List All Purchase Orders
Filter by | Handle |
---|---|
Workspace | /api/v2/purchase_orders?workspace_id=[id] If a workspace_id is not specified as a URL parameter, only purchase orders from the primary workspace will be included in the response. If workspace_id is specified as 0, purchase orders from across all workspaces will be included in the response. Applicable only to accounts on the Employee Support Mode. |
This operation allows you to view information about all the purchase orders in Freshservice.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/purchase_orders’ |
1. Get the second page (purchase orders from 31-60) of a list of all the purchase orders in the account.The list will be in descending order of creation time.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/purchase_orders?per_page=30&page=2' |
2. Get the list of all purchase orders from workspaces to which the user has access.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/purchase_orders?workspace_id=0' |
3. Get the list of purchase orders from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/purchase_orders?workspace_id=3' |
4. Get the list of all purchase orders including custom fields
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/purchase_orders?include=custom_fields' |
5. Get the list of all purchase orders including purchase items
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/purchase_orders?include=purchase_items' |
6. Get the list of all purchase orders including custom fields and purchase items
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/purchase_orders?include=custom_fields,purchase_items' |
Move a Purchase Order
This API moves a purchase order to a different workspace.
Note:
This endpoint is applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X PUT -d '{ "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/purchase_orders/2/move_workspace' |
View a Purchase Order
This operation allows you to view a particular purchase order.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/purchase_orders/11' |
Update a Purchase Order
This operation allows you to update an existing purchase order.
Note:
The workspace_id attribute cannot be updated through the Update operation. It can only be updated through the Move operation.
Purchase Items
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
item_type | integer | Type of item to be ordered. Mandatory |
item_name | string | Name of the items to be ordered. Mandatory |
description | string | Item description. |
cost | integer | Cost of the item. Mandatory |
quantity | integer | Quantity of item to be ordered. Mandatory |
tax_percentage | integer | Percentage of tax on item cost. Mandatory |
Custom Fields
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
terms_and_conditions | string | The default value is null. |
1 2 3 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '"{"vendor_id":0,"name":"string","po_number":"string","vendor_details":"string", "expected_delivery_date":"2021-02-11T17:20:07.999Z","created_at":"2021-02-11T17:20:07.999Z","updated_at":"2021-02-11T17:20:07.999Z","shipping_address":"string", "billing_same_as_shipping":true,"billing_address":"string","currency_code":"string","department_id":0,"discount_percentage":0,"tax_percentage":0,"shipping_cost":0,"custom_fields":{},"purchase_items":[{"item_name":"string","description":"string","cost":0,"quantity":0,"tax_percentage":0}, "workspace_id": 2]}' 'https://domain.freshservice.com/api/v2/purchase_orders/11' |
Delete a Purchase Order
This operation allows you to delete a particular purchase order.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/purchase_order/9’ |
Asset Types
Asset types are a broad classification of different collection of assets. In Freshservice, several default asset types are provided out of the box and custom asset types can be created at the root level or within another asset type. The default asset types can be enabled or disabled as needed as well.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the asset type. |
name | string | Name of the asset type.Mandatory |
description | string | Short description of the asset type. |
parent_asset_type_id | number | ID of the parent asset type. |
visible | boolean | Visibility of the default asset type. Set to true if the asset type is visible. Custom asset types are set to true by default and cannot be modified. |
created_at | datetime | Date and time when the asset type was created |
updated_at | datetime | Date and time when the asset type was last updated |
Create an Asset Type
This operation allows you to create an asset type in Freshservice.
Attribute | Type | Description |
---|---|---|
name | string | Name of the asset type.Mandatory |
description | string | Short description of the asset type. |
parent_asset_type_id | number | ID of the parent asset type. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"name": "Chromebook", "parent_asset_type_id": 8, "description":"Asset type for all chromebooks"}' 'https://domain.freshservice.com/api/v2/asset_types' |
View an Asset Type
This operation allows you to view information about a particular asset type
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/asset_types/50’ |
List all Asset Types
This operation allows you to view information about all the asset types in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/asset_types’ |
1. Get the second page (asset types from 31-60) of a list of all the asset types in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/asset_types?per_page=30&page=2' |
Update an Asset Type
This operation allows you to update an existing asset type.
Attribute | Type | Description |
---|---|---|
name | string | Name of the asset type. |
description | string | Short description of the asset type. |
visibile | boolean | Visibility of the default asset type. Set to true if the asset type is visible. Custom asset types are set to true by default and cannot be modified |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"description":"Chromebooks Asset Type", "visible": false}' 'https://domain.freshservice.com/api/v2/asset_types/50' |
Delete an Asset Type
This operation allows you to delete a particular asset type.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/asset_types/50’ |
List all Fields of an Asset Type
This operation allows you to view information about all the fields in a particular asset type in the account.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/asset_types/636/fields’ |
Software
This section lists all API that can be used to create, list, edit or delete Software.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the software Read-Only |
workspace_id | number | ID of the workspace that the software belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
name | string | Name of the software |
description | string | Description of the software |
application_type | string | Type of the software |
status | string | Status of the software |
publisher_id | number | ID of the Vendor |
managed_by_id | number | ID of the user managing the software (must be a user in Freshservice) |
notes | string | Notes about the software |
category | string | Category of the software |
source | string | Name of the source from where the software details are updated (API, Okta, Google...etc). |
user_count | number | Number of users using this softwareRead-Only |
installation_count | number | Number of devices installed this softwareRead-Only |
created_at | datetime | Date at which the software is createdRead-Only |
updated_at | datetime | Date at which the software is last updatedRead-Only |
Software Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
application_type | desktop, saas, mobile | The default value is "desktop" |
status | blacklisted, ignored, managed |
Create a Software
This operation allows you to create a new software in Freshservice.
Software Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
application_type | desktop, saas, mobile | The default value is "desktop" |
status | blacklisted, ignored, managed |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "application": { "name": "Freshservice", "description": "Cloud based ITSM software for service desk", "application_type": "saas", "category": "service desk application", "status": "managed", "source": "API", "managed_by_id": 79560,"notes": "monthly renewal", "workspace_id": 2 } }' -X POST 'https://domain.freshservice.com/api/v2/applications' |
Update a Software
This operation allows you to update an existing software.
Note:
The workspace_id attribute cannot be updated through the Update operation. It can only be updated through the Move operation.
Software Properties
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
application_type | desktop, saas, mobile | |
status | blacklisted, ignored, managed |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{"application": {"name": "Freshservice New","description": "Cloud based ITSM software","application_type":"saas","category": null, "status": "managed", "source": "API", "managed_by_id": 79560, "notes": "monthly renewal", "workspace_id": 2}}' -X PUT 'https://domain.freshservice.com/api/v2/applications/31027' |
View a Software
This operation allows you to view a particular software.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/applications/31027' |
List all Software
Filter by | Handle |
---|---|
Workspace | /api/v2/applications?workspace_id=[id] If a workspace_id is not specified as a URL parameter, only software from the primary workspace will be included in the response. If workspace_id is specified as 0, software from across all workspaces will be included in the response. Applicable only to accounts on the Employee Support Mode. |
This operation allows you to list all software.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/applications' |
1. Get the list of all softwares from workspaces to which the user has access.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/applications?workspace_id=0' |
2. Get the list of softwares from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/applications?workspace_id=3' |
List all Licenses
This operation allows you to list all licenses of a software.
Attribute | Type | Description |
---|---|---|
id | number | ID of the software contract |
contract_id | number | Contract Number of the contract |
created_time | datetime | Date at which the software contract is created |
updated_time | datetime | Date at which the software contract is last updated |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/applications/31027/licenses' |
Delete a Software
This operation allows you to delete a particular software.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/applications/10’ |
Delete multiple Software
This operation allows you to delete multiple software.
Attribute | Type | Description |
---|---|---|
ids | number | Array of id of software to be deleted.Mandatory |
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/applications?ids=9216,9218’ |
Software Users
This section lists all API that can be used to add, view, list, edit or remove Users of a Software.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the application user.Read Only |
user_id | number | ID of the User using the Software. Mandatory |
license_id | number | Display ID of the allocated Software License Contract. |
allocated_date | datetime | Date and time when the license was allocated. |
first_used | datetime | Date and time when the application was first used by the user. |
last_used | datetime | Date and time when the application was last used by the user. |
source | string | source from where the user details are updated (API, Okta, Google...etc). |
created_at | datetime | Date and time when the installation was created.Read Only |
updated_at | datetime | Date and time when the installation was last updated.Read Only |
Add Users to a Software in bulk
This operation allows you to add Users to a Software in bulk.
Attribute | Type | Description |
---|---|---|
user_id | number | ID of the User using the Software. Mandatory |
license_id | number | Display ID of the allocated Software License Contract. |
allocated_date | datetime | Date and time when the license was allocated. |
first_used | datetime | Date and time when the application was first used by the user. |
last_used | datetime | Date and time when the application was last used by the user. |
source | strings | Name of the source from where the user details are updated (API, Okta, Google...etc). |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"application_users": [{"user_id": 16442,"license_id": 10,"allocated_date": "2019-10-10T00:00:00Z","first_used": "2019-11-10T00:00:00Z","last_used": "2020-01-10T00:00:00Z", "source": "Okta"},{"user_id": 16443,"license_id": 11,"allocated_date": "2019-10-10T00:00:00Z","first_used": "2019-11-10T00:00:00Z","last_used": "2020-01-10T00:00:00Z", "source": "API"}]}' 'https://domain.freshservice.com/api/v2/applications/99/users' |
View a Software User
This operation allows you to view a particular Software User.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/applications/99/users/1000029614' |
Move a Software
This API moves a software to a different workspace.
Note:
This endpoint is applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X PUT -d '{ "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/applications/1/move_workspace' |
List all Users of a Software
This operation allows you to view the list of users using a particular Software.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/applications/99/users |
Update Users of a Software in bulk
This operation allows you to update Users of a Software in bulk.
Attribute | Type | Description |
---|---|---|
user_id | number | ID of the User using the Software. Mandatory |
license_id | number | Display ID of the allocated Software License Contract. |
allocated_date | datetime | Date when the license was allocated. |
first_used | datetime | Date and time when the application was first used by the user. |
last_used | datetime | Date and time when the application was last used by the user. |
source | strings | Name of the source from where the user details are updated (API, Okta, Google...etc). |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"application_users": [{"user_id": 16442,"license_id": 12,"allocated_date": "2019-11-10T00:00:00Z","first_used": "2019-12-10T00:00:00Z","last_used": "2020-01-10T00:00:00Z", "source": "Okta"},{"user_id": 16443,"license_id": 13,"allocated_date": "2019-11-10T00:00:00Z","first_used": "2019-11-10T00:00:00Z","last_used": "2020-01-10T00:00:00Z", "source": "API"}]}' 'https://domain.freshservice.com/api/v2/applications/99/users' |
Remove Users from a Software in bulk
This operation allows you to remove Users from a Software in bulk.
Attribute | Type | Description |
---|---|---|
user_ids | Array of numbers | IDs of Users using the software. Mandatory |
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/applications/99/installations?user_ids=16442,16443' |
Software Installations
This section lists all API that can be used to add, list or remove Installations of a Software.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the installation.Read Only |
installation_machine_id | number | Display ID of device where the software is installed in. Mandatory |
installation_path | string | Path where the software is installed. |
version | string | Version of the installed software. |
user_id | number | ID of the User using the Device(Used By).Read Only |
department_id | number | ID of the department the device belongs to.Read Only |
installation_date | datetime | Date and time when the application was installed. |
created_at | datetime | Date and time when the installation was created.Read Only |
updated_at | datetime | Date and time when the installation was last updated.Read Only |
Add a device to a Software
This operation allows you to add a new device to a Software.
Attribute | Type | Description |
---|---|---|
installation_machine_id | number | Display ID of device where the software is installed in. Mandatory |
installation_path | string | Path where the software is installed. |
version | string | Version of the installed software. |
installation_date | datetime | Date and time when the application was installed. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"installation_machine_id": 12, "installation_path": "/Applications/Atom.app", "version": "1.41.0", "installation_date": "2019-02-05T10:23:28Z"}' 'https://domain.freshservice.com/api/v2/applications/99/installations' |
List all installations of a Software
This operation allows you to view the list of all the devices where the Software is installed in.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/applications/99/installations’ |
Remove devices from a Software in bulk
This operation allows you to remove devices from a Software in bulk.
Attribute | Type | Description |
---|---|---|
device_ids | Array of numbers | List of Display IDs of the devices where the software is installed in. Mandatory |
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/applications/99/installations?device_ids=102,103' |
List all Relationships for a Software
Lists all the relationships of a particular software.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/applications/16867/relationships' |
Contracts
This section lists all the APIs that can be used to perform operations related to Contracts such as creating, viewing and managing approvals.
Attribute | Type | Description |
---|---|---|
workspace_id | number | ID of the workspace that the contract belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
id | number | Unique ID of the contractRead only |
name | string | Name of the ContractMandatory |
description | string | Description of the Contract |
vendor_id | number | ID of the VendorMandatory |
auto_renew | boolean | True (1) if the contract is set to Auto Renew. Default is False (0) |
notify_expiry | boolean | True (1) if the expiry notification is set up for the contract. Default is False (0) |
notify_before | number | Number of days before contract expiry date when the expiry notifications need to be sent. Cannot exceed 365 days |
approver_id | number | ID of the agent who needs to approve the contract. Not mandatory for software contractsMandatory | start_date | datetime | Start date of the contract. Not mandatory for software contractsMandatory |
end_date | datetime | End date of the contract. Not mandatory for software contractsMandatory |
cost | number | Cost of the contract. Not mandatory for software contractsMandatory |
status | string | Status of the contract. Allowed values: draft, pending, approved, active, expired, rejected, cancelled, pending_esign, esigned, decline_esignRead only |
contract_number | string | User entered ID for the contract. This has to be unique. Mandatory |
contract_type_id | number | ID of the contract type and it cannot be updatedMandatory |
visible_to_id | number | ID of agent group in Freshservice to control visibility of the contract |
notify_to | array of strings | List of email addresses to notify expiry |
custom_fields | object | Key value pairs containing the names and values of custom fields |
future_contract_id | number | If the contract has an approved renewal, it gives a URL to see the details of the renewalRead only |
has_associated_assets | boolean | Indicates whether the contract has associated assets.Read only |
has_attachments | boolean | Indicates whether the contract has attachmentsRead only |
expiry_notified | boolean | True if the expiry of the contract is notified. False if not notifiedRead only |
requester_id | number | Denotes the user who creates the contract and renew the contractRead only |
delegatee_id | number | ID of the agent whom the contract approval is delegated toRead only |
created_at | datetime | Timestamp at which the contract was createdRead Only |
updated_at | datetime | Timestamp at which the contract was updatedRead Only |
Software contract attributes
Additional attributes specific to the software contracts
Attribute | Type | Description |
---|---|---|
software_id | number | ID of the software and it cannot be updatedMandatory |
license_type | string | Type of the license and it cannot be updated |
billing_cycle | string | Represents the contract term period |
license_key | string | License key for the contract |
item_cost_details | array of objects | Item cost details of the contract. First line_item will be marked with allocate_license true as in UI. |
Item cost detail attributes
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the line item |
item_name | string | Name of the particular line item |
pricing_model | string | Represents the pricing unit of a particular line item |
cost | number | Represents the cost of a particular line item |
count | number | Represents the number of units of a particular line item |
comments | string | To add any additional comments for a particular line item |
created_at | datetime | Timestamp at which the item line item was createdRead Only |
updated_at | datetime | Timestamp at which the item line item was updatedRead Only |
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
license_type | volume, enterprise, trial, open_source, free | The default value is “volume” |
billing_cycle | monthly, quarterly, half_yearly, annual, one_time | The default value is "one_time” |
pricing_model | per_unit, fixed, one_time | The default value is "per_unit" |
List all contract types
This operation allows you to view a list of all contract type.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the contract type field |
name | string | Name of the contract type field |
description | string | Description of the contract type |
needs_approval | boolean | Indicates whether the contract needs approval |
is_default | boolean | Indicates whether the type is a default type or a custom type |
created_at | datetime | Timestamp at which the contract type was createdRead Only |
updated_at | datetime | Timestamp at which the contract type was updatedRead Only |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contract_types' |
List all fields of a contract type
This operation allows you to view all fields of a contract type.
Attribute | Type | Description |
---|---|---|
label | string | Lable of the contract type field |
name | string | Name of the contract type field |
required | boolean | Mandatoriness of this field when creating or updating a contract |
field_type | string | Field type of the contract type field. Allowed values: text, paragraph, dropdown, number, integer, datetime, checkbox, Array |
data_type | string | Data type of the contract type field. Allowed values: string, integer, decimal, date, boolean |
visible_in_renewal | boolean | Indicates whether the field is visible in contract renewal page |
default_field | boolean | Indicates whether the field is a default field or a custom field |
choices | array of strings | Choices of dropdown field(only for dropdown field) |
created_at | datetime | Timestamp at which the contract type field was createdRead Only |
updated_at | datetime | Timestamp at which the contract type field was updatedRead Only |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contract_types/3/fields' |
View a contract
This operation allows you to view a particular contract.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contracts/1' |
List all contracts
This operation allows you to view a list of all contracts.
Filter by | Handle |
---|---|
Workspace | /api/v2/contracts?workspace_id=[id] If a workspace_id is not specified as a URL parameter, only contracts from the primary workspace will be included in the response. If workspace_id is specified as 0, contracts from across all workspaces will be included in the response. Applicable only to accounts on the Employee Support Mode. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contracts' |
1. Get the list of all contracts from workspaces to which the user has access.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contracts?workspace_id=0' |
2. Get the list of contracts from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contracts?workspace_id=3' |
Move a Contract
This API moves a contract to a different workspace, while also allowing the visibility group to be modified.
Note:
This endpoint is applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -X PUT -d '{ "workspace_id": 2, "visible_to_id": 28509 }' 'https://domain.freshservice.com/api/v2/contracts/3/move_workspace' |
Create a Contract
This operation allows you to create a new contract in Freshservice.
Attribute | Type | Description |
---|---|---|
workspace_id | number | ID of the workspace that the contract belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
id | number | Unique ID of the contractRead only |
name | string | Name of the ContractMandatory |
description | string | Description of the Contract |
vendor_id | number | ID of the VendorMandatory |
auto_renew | boolean | True (1) if the contract is set to Auto Renew. Default is False (0) |
notify_expiry | boolean | True (1) if the expiry notification is set up for the contract. Default is False (0) |
notify_before | number | Number of days before contract expiry date when the expiry notifications need to be sent. Cannot exceed 365 days |
approver_id | number | ID of the agent who needs to approve the contract. Not mandatory for software contractsMandatory | start_date | datetime | Start date of the contract. Not mandatory for software contractsMandatory |
end_date | datetime | End date of the contract. Not mandatory for software contractsMandatory |
cost | number | Cost of the contract. Not mandatory for software contractsMandatory |
status | string | Status of the contract. Allowed values: draft, pending, approved, active, expired, rejected, cancelled, pending_esign, esigned, decline_esignRead only |
contract_number | string | User entered ID for the contract. This has to be unique. Mandatory |
contract_type_id | number | ID of the contract type and it cannot be updatedMandatory |
visible_to_id | number | ID of agent group in Freshservice to control visibility of the contract |
notify_to | array of strings | List of email addresses to notify expiry |
custom_fields | object | Key value pairs containing the names and values of custom fields |
future_contract_id | number | If the contract has an approved renewal, it gives a URL to see the details of the renewalRead only |
has_associated_assets | boolean | Indicates whether the contract has associated assets.Read only |
has_attachments | boolean | Indicates whether the contract has attachmentsRead only |
expiry_notified | boolean | True if the expiry of the contract is notified. False if not notifiedRead only |
requester_id | number | Denotes the user who creates the contract and renew the contractRead only |
delegatee_id | number | ID of the agent whom the contract approval is delegated toRead only |
created_at | datetime | Timestamp at which the contract was createdRead Only |
updated_at | datetime | Timestamp at which the contract was updatedRead Only |
Software contract attributes
Additional attributes specific to the software contracts
Attribute | Type | Description |
---|---|---|
software_id | number | ID of the software and it cannot be updatedMandatory |
license_type | string | Type of the license and it cannot be updated |
billing_cycle | string | Represents the contract term period |
license_key | string | License key for the contract |
item_cost_details | array of objects | Item cost details of the contract. First line_item will be marked with allocate_license true as in UI. |
Item cost detail attributes
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the line item |
item_name | string | Name of the particular line item |
pricing_model | string | Represents the pricing unit of a particular line item |
cost | number | Represents the cost of a particular line item |
count | number | Represents the number of units of a particular line item |
comments | string | To add any additional comments for a particular line item |
created_at | datetime | Timestamp at which the item line item was createdRead Only |
updated_at | datetime | Timestamp at which the item line item was updatedRead Only |
For the following attributes, the supported values are listed below.
Attribute | Supported Values | Comments |
---|---|---|
license_type | volume, enterprise, trial, open_source, free | The default value is “volume” |
billing_cycle | monthly, quarterly, half_yearly, annual, one_time | The default value is "one_time” |
pricing_model | per_unit, fixed, one_time | The default value is "per_unit" |
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 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d ' { "name": "Adobe contract", "description": "", "vendor_id": 7, "auto_renew": true, "notify_expiry": true, "notify_before": 30, "approver_id": 12, "start_date": "2021-06-11T10:26:17Z", "end_date": "2022-06-11T10:26:17Z", "cost": 1500.33, "contract_number": "ADB12", "contract_type_id": 3, "visible_to_id": 4, "notify_to": ["agent_name@freshworks.com"], "custom_fields": { "cf_vendor_location": "Chennai" }, "software_id": 3, "billing_cycle": "annual", "item_cost_details": [ { "item_name": "Installation", "pricing_model": "per_unit", "cost": 200, "count": 1 } ], "future_contract_id": 6, "requester_id": 4, "delegatee_id": 2, "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/contracts' |
Create a Contract with associated assets
This API lets you create a new Contract with associated Assets (CIs) in your service desk.
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 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d ' { "associated_asset_ids": [10,11], "name": "Adobe contract", "description": "", "vendor_id": 7, "auto_renew": true, "notify_expiry": true, "notify_before": 30, "approver_id": 12, "start_date": "2021-06-11T10:26:17Z", "end_date": "2022-06-11T10:26:17Z", "cost": 1500.33, "contract_number": "ADB12", "contract_type_id": 3, "visible_to_id": 4, "notify_to": ["agent_name@freshworks.com"], "custom_fields": { "cf_vendor_location": "Chennai" }, "software_id": 3, "billing_cycle": "annual", "item_cost_details": [ { "item_name": "Installation", "pricing_model": "per_unit", "cost": 200, "count": 1 } ], "future_contract_id": 6, "requester_id": 4, "delegatee_id": 2, "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/contracts' |
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 | { "contract": { "id": 15, "name": "Adobe contract", "description": "Not given.", "vendor_id": 7, "auto_renew": true, "notify_expiry": true, "notify_before": 30, "approver_id": 12, "start_date": "2021-06-11T10:26:17Z", "end_date": "2022-06-11T10:26:17Z", "cost": 1500.33, "status": "active", "contract_number": "ADB12", "contract_type_id": 3, "visible_to_id": 4, "notify_to": [ "agent_name@freshworks.com" ], "custom_fields": { "cf_vendor_location": "Chennai" }, "software_id": 3, "license_type": "volume", "billing_cycle": "annual", "license_key": null, "item_cost_details": [ { "id": 1, "item_name": "Installation", "pricing_model": "per_unit", "cost": 200.0, "comments": null, "count": 1, "created_at": "2021-12-16T12:06:03Z", "updated_at": "2021-12-16T12:06:03Z" } ], "future_contract_id": 6, "has_associated_assets": true, "has_attachments": false, "expiry_notified": false, "requester_id": 4, "delegatee_id": 2, "created_at": "2021-12-16T12:06:03Z", "updated_at": "2021-12-16T12:06:03Z", "workspace_id": 2 } } |
Create a Contract with attachment
Create a Contract with attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
2. For more information on attachment refer to this section.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api2.png' -F 'name=Sample Apple Contract' -F 'vendor_id=7' -F 'approver_id=12' -F 'start_date=2021-06-11T10:26:17Z' -F 'end_date=2022-06-11T10:26:17Z' -F 'workspace_id=2' -F 'cost=1500.33' -F 'contract_number=APL-2' -F 'contract_type_id=1' -X PUT 'https://domain.freshservice.com/api/v2/contracts' |
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 | { "contract": { "id": 12, "name": "Sample Apple Contract", "description": "Not given.", "vendor_id": 7, "auto_renew": false, "notify_expiry": false, "notify_before": null, "approver_id": 12, "start_date": "2021-06-11T10:26:17Z", "end_date": "2022-06-11T10:26:17Z", "cost": 1500.33, "status": "draft", "contract_number": "APL-2", "contract_type_id": 1, "visible_to_id": null, "notify_to": null, "custom_fields": { "cf_2": null, "cf_untitled": null, "cf_mlt": null }, "future_contract_id": null, "has_associated_assets": false, "has_attachments": true, "expiry_notified": false, "requester_id": null, "delegatee_id": null, "created_at": "2021-12-21T09:37:08Z", "updated_at": "2021-12-21T09:37:08Z", "workspace_id": 2 } } |
Update a Contract
Note:
The workspace_id attribute cannot be updated through the Update operation. It can only be updated through the Move operation.
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 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d ' { "name": "Adobe contract", "description": "", "vendor_id": 7, "auto_renew": true, "notify_expiry": true, "notify_before": 30, "approver_id": 12, "start_date": "2021-06-11T10:26:17Z", "end_date": "2022-06-11T10:26:17Z", "cost": 1500.33, "contract_number": "ADB12", "visible_to_id": 4, "notify_to": ["agent_name@freshworks.com"], "custom_fields": { "cf_vendor_location": "Chennai" }, "billing_cycle": "annual", "item_cost_details": [ { "id" : 1, "item_name": "Installation", "pricing_model": "per_unit", "cost": 200, "count": 1 } ], "future_contract_id": 6, "requester_id": 4, "delegatee_id": 2, "associated_asset_ids": [10,11], "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/contracts/1' |
Submit a contract for approval
This operation allows you to submit a contract for approval in the account.
1 | curl -v -u api_key:X -X PUT 'https://domain.freshservice.com/api/v2/contracts/1?operation=submit-for-approval' |
Approve a Contract
This operation allows you to approve a contract in the account.
1 | curl -v -u api_key:X -X PUT 'https://domain.freshservice.com/api/v2/contracts/1?operation=approve' |
Reject a Contract
This operation allows you to reject a contract in the account.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"reason_to_reject": "Terms need to be reviewed again"}' 'https://domain.freshservice.com/api/v2/contracts/1?operation=reject' |
List all associated assets of a contract
This operation allows you to view information about all the associated asset of a contract.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contracts/1/associated-assets' |
List all attachments of a contract
This operation allows you to view information about all the attachments of a contract.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the attachment. |
content_type | string | Type of the attachment. (Example: jpg, png, ...) |
size | number | Size of the attached file. |
name | string | Name of the attachment. |
attachment_url | string | URL of the attachment. |
canonical_url | string | Canonical URL of the attachment. |
created_at | datetime | Timestamp at which the attachment was created.Read Only |
updated_at | datetime | Timestamp at which the attachment was updated.Read Only |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/contracts/1/attachments' |
Departments / Companies
Attribute | Type | Description |
---|---|---|
id | integer | Unique identifier of the department |
name | string | Name of the departmentMandatory |
description | string | Description about the department |
head_user_id | integer | Unique identifier of the agent or requester who serves as the head of the department |
prime_user_id | integer | Unique identifier of the agent or requester who serves as the prime user of the department |
domains | array of strings | Email domains associated with the department |
custom_fields | hash | Custom fields that are associated with departments |
created_at | date-time | Timestamp at which the department was created |
updated_at | date-time | Timestamp at which the department was last modified |
Create a Department
Create a new Department (or Company in MSP Mode) in Freshservice.
Attribute | Type | Description |
---|---|---|
id | integer | Unique identifier of the department |
name | string | Name of the departmentMandatory |
description | string | Description about the department |
head_user_id | integer | Unique identifier of the agent or requester who serves as the head of the department |
prime_user_id | integer | Unique identifier of the agent or requester who serves as the prime user of the department |
domains | array of strings | Email domains associated with the department |
custom_fields | hash | Custom fields that are associated with departments |
created_at | date-time | Timestamp at which the department was created |
updated_at | date-time | Timestamp at which the department was last modified |
1 | curl -v -u api.user@ministryofmagic.gov:test -H 'Content-Type: application/json' -X POST -d '{"name":"Department for the Regulation and Control of Magical Creatures","description":"Beast, Being and Spirit Divisions, and Pest Advisory Bureau.","head_user_id":5,"prime_user_id":6,"domains":["creatures.ministryofmagic.gov"],"custom_fields":{"location":"Level 3"}}' 'https://domain.freshservice.com/api/v2/departments' |
View a Department
Retrieve the Department (or Company in MSP Mode) with the given ID from Freshservice
1 | curl -v -u api.user@ministryofmagic.gov:test -X GET 'https://domain.freshservice.com/api/v2/departments/1' |
List All Departments
Retrieve a list of all Departments (or Companies in MSP Mode) in Freshservice
1 | curl -v -u api.user@ministryofmagic.govhogwarts.edu:test -X GET 'https://domain.freshservice.com/api/v2/departments' |
Filter Departments
Use Departments (or Companies in MSP Mode) attributes to filter your list.
Note:
1. The query must be URL encoded (see example).
2. Query can be framed using the name of the department fields, which can be obtained from Supported Department Fields section.
3. Query string must be enclosed between a pair of double quotes and can have up to 512 characters.
4. Filtered results cannot be sorted. By default it is sorted by created_at in descending order.
Supported Department Fields
Field | Type | Description |
---|---|---|
name | string | Name of the department. |
Get the department whose display name is 'Sales'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/departments?query="name:%27Sales%27" |
Update a Department
Update an existing Department (or Company in MSP Mode) in Freshservice.
Attribute | Type | Description |
---|---|---|
id | integer | Unique identifier of the department |
name | string | Name of the departmentMandatory |
description | string | Description about the department |
head_user_id | integer | Unique identifier of the agent or requester who serves as the head of the department |
prime_user_id | integer | Unique identifier of the agent or requester who serves as the prime user of the department |
domains | array of strings | Email domains associated with the department |
custom_fields | hash | Custom fields that are associated with a Freshservice entity |
created_at | date-time | Timestamp at which the department was created |
updated_at | date-time | Timestamp at which the department was last modified |
1 | curl -v -u api.user@hogwarts.edu:test -H 'Content-Type: application/json' -X PUT -d '{"name":"Department for the Regulation and Control of Magical Creatures","description":"Beast, Being and Spirit Divisions, and Pest Advisory Bureau.","head_user_id":5,"prime_user_id":7,"domains":["creatures.ministryofmagic.gov"],"custom_fields":{"location":"Level 3"}}' 'https://domain.freshservice.com/api/v2/departments/3' |
Delete a Department
Delete the Department (or Company in MSP Mode) with the given ID from Freshservice.
1 | curl -v -u api.user@hogwarts.edu:test -X DELETE 'https://domain.freshservice.com/api/v2/departments/3' |
List All Department Fields
Retrieve the Department Fields (or Company Fields in MSP Mode) from Freshservice. The fields will be returned in the sequence that they are displayed on the UI.
1 | curl -v -u api.user@hogwarts.edu:test -X GET 'https://domain.freshservice.com/api/v2/department_fields' |
Business Hours
Attribute | Type | Description |
---|---|---|
id | integer | Unique identifier of the business hours configuration |
workspace_id | number | ID of the workspace to which the business hours belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
name | string | Name of the business hours configuration |
description | string | Description about the business hours configuration |
is_default | boolean | true if the business hours configuration is the default present in Freshservice |
time_zone | string | Time zone that the business hours configuration functions in. Click here for more information. |
service_desk_hours | hash | Contains the time at which the workday begins and ends for the seven days of the week. |
list_of_holidays | array of hashes | Contains the list of dates and names of holidays for the year. Dates are in ISO --MM-DD format. |
created_at | date-time | Timestamp at which the business hours configuration was created |
updated_at | date-time | Timestamp at which the business hours configuration was last modified |
View a Business Hours Configuration
Retrieve the Business Hours Configuration with the given ID from Freshservice
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/business_hours/1' |
View List of Business Hours Configurations
Retrieve a list of all business hours configurations in Freshservice
Note:
By default, only business hours from the primary workspace will be returned for accounts on the Employee Support Mode. For business hours from other workspaces, use the workspace_id filter.
Filter by | Handle |
---|---|
Workspace | /api/v2/business_hours?workspace_id=[id] 'workspace_id' is applicable only for accounts on the Employee Support Mode. The value 1 for workspace_id will return all global business hours |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/business_hours?workspace_id=2' |
Projects (Legacy)
Note:
Following Project APIs are for legacy project management. We are currently migrating customers from legacy to the new-gen project management. APIs for new-gen can be accessed here.
With the ability to create new projects from scratch or even from tickets or changes, plan all your IT projects within the service desk. Prioritize, manage, and track projects from the beginning till wrap-up, while associating multiple tickets, changes, or even assets to these projects.
Note:
Only users with "View or Manage Projects" privilege can access the following APIs.
Attribute | Type | Description |
---|---|---|
id | number | Unique id of the project. Read-Only |
title | string | Title of the project.Mandatory |
description | string | Description of the project as HTML. |
description_text | string | Description of the project in plain text. Read-Only |
start_date | date | Start date of the project.Mandatory |
end_date | date | End date of the project.Mandatory |
user_id | number | User who created the project. Read-Only |
owner_id | number | Owner of the project. |
deleted | boolean | Denotes whether a project is archived or not. Read-Only |
status | number | Current Status of the project. |
closed_at | datetime | Date and time of completion of the project. Read-Only |
priority | number | Priority of the project. |
attachments | array of objects | Project Attachments. Read-Only | created_at | datetime | Date and time when the project was created. Read-Only |
updated_at | datetime | Date and time when the project was last updated. Read-Only |
Project Properties
Every project uses certain fixed numerical values to denote its Status and Priorities. These numerical values along with their meanings are given below.
Status | Value |
---|---|
Open | 1 |
In Progress | 2 |
Completed | 3 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Critical | 4 |
Create a Project
Attribute | Type | Description |
---|---|---|
title | string | Title of the project.Mandatory |
description | string | Description of the project as HTML. |
start_date | date | Start date of the project.Mandatory |
end_date | date | End date of the project.Mandatory |
status | number | Current Status of the project. |
priority | number | Priority of the project. |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{ "title":"Intranet Site Development", "description":"Project for Intranet Site Development", "start_date":"2019-02-07", "end_date":"2019-02-10","status":1,"priority":2}' 'https://domain.freshservice.com/api/v2/projects' |
Update a Project
Attribute | Type | Description |
---|---|---|
title | string | Title of the project. |
description | string | Description of the project as HTML. |
start_date | date | Start date of the project. |
end_date | date | End date of the project. |
owner_id | number | Owner of the project. |
status | number | Current Status of the project. |
priority | number | Priority of the project. |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X PUT -d '{ "title":"Intranet Site Development", "description":"Project for Intranet Site Development", "start_date":"2019-02-07", "end_date":"2019-02-10","status":1,"priority":2}' 'https://domain.freshservice.com/api/v2/projects/1' |
View a Project
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/projects/1' |
List All Projects
Query Parameters | Handle |
---|---|
filter | Filter projects based on given value. Allowed values are ['all', 'completed', 'archived'] Example: api/v2/projects/?filter=completed |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/projects' |
Delete a Project
This API helps you permanently delete a project. Deleted projects cannot be restored.
Note: Only archived projects can be deleted.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/projects/2' |
Archive a Project
This API helps you archive a project.
Note: Archived projects are not permanently lost. You can retrieve them using the Restore Project API.
1 | curl -v -u api_key:X -X POST 'https://domain.freshservice.com/api/v2/projects/1/archive' |
Restore a Project
You can restore an archived project using this API.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '' 'https://domain.freshservice.com/api/v2/projects/1/restore' |
Projects Tasks (Legacy)
Note:
Following Project Task APIs are for legacy project management. We are currently migrating customers from legacy to the new-gen project management. APIs for new-gen can be accessed here.
Manage projects by organizing them into tasks and nested subtasks, and easily assign them to individual owners. Collaborate and discuss, attach files for context, view dependencies, and use the activity log to monitor progress.
Note:
Only users with "View or Manage Projects" privilege can access the following APIs.
Attribute | Type | Description |
---|---|---|
id | number | Unique id of the task. Read-Only |
title | string | Title of the task.Mandatory |
description | string | Description of the task. |
start_date | datetime | Start date of the task. |
end_date | datetime | End date of the task. |
user_id | number | User who created the task. Read-Only |
owner_id | number | Owner of the task. |
status | number | Current Status of the task. |
parent_id | number | Parent task id in case of a subtask |
notify | Object | Notification details for the task. |
attachments | array of objects | Task Attachments. Read-Only | created_at | datetime | Date and time when the task was created. Read-Only |
updated_at | datetime | Date and time when the task was last updated. Read-Only |
Task Notify Attribute details
The following keys should be present inside the notify attribute in the request payload for creating or updating a task.
Name | Value |
---|---|
type | BEFORE_START_DATE or BEFORE_END_DATE |
value | The time value in number |
time_unit | Unit of time. Allowed values ('minutes', 'hours', 'days', 'weeks') |
Create a Project Task
Attribute | Type | Description |
---|---|---|
title | string | Title of the task.Mandatory |
description | string | Description of the task. |
start_date | datetime | Start date of the task. |
end_date | datetime | End date of the task. |
owner_id | number | Owner of the task. |
status | number | Current Status of the task. |
parent_id | number | Parent task id in case of a subtask |
notify | Object | Notification details for the task. |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{ "title":"Gather/Validate Requirements", "description":"Gather/Validate Requirements", "start_date":"2019-02-07T00:00:00.000+05:30", "end_date":"2019-02-10T00:00:00.000+05:30", "notify": {"type": "BEFORE_START_DATE","value": "20","time_unit": "minutes"},status":1}' 'https://domain.freshservice.com/api/v2/projects/1/tasks' |
Update a Project Task
Attribute | Type | Description |
---|---|---|
title | string | Title of the task.Mandatory |
description | string | Description of the task. |
start_date | datetime | Start date of the task. |
end_date | datetime | End date of the task. |
owner_id | number | Owner of the task. |
status | number | Current Status of the task. |
notify | Object | Notification details for the task. |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X PUT -d '{ "title":"Gather/Validate Requirements", "start_date":"2019-02-07T00:00:00.000+05:30", "end_date":"2019-02-10T00:00:00.000+05:30", "status":1}' 'https://domain.freshservice.com/api/v2/projects/1/tasks/1' |
View a Project Task
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/projects/1/tasks/1' |
List All Project Tasks
Query Parameters | Handle |
---|---|
parent_id | List the subtasks for a task. Example: api/v2/projects/1/tasks?parent_id=10 |
filter | Allowed filters are ['all','completed','inprogress','open','overdue','unassigned','root'] Example: /api/v2/projects/1/tasks?filter=all. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/projects/1/tasks' |
Delete a Project Task
This API helps you delete a project task.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/projects/2/tasks/1' |
Projects
Note:
The following Project APIs are for new-gen project management and these are not compatible with our legacy project management module. You can find the APIs for legacy project management here.
With the ability to create new projects from scratch or even from tickets or changes, plan all your projects within the service desk. Prioritize, manage, and track projects from the beginning till wrap-up, while associating multiple tickets, changes, or even assets to these projects.
Note:
Only users with "View or Manage Projects" privilege can access the following APIs.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the project.Read-Only |
name | string | Name of the project. The maximum number of characters allowed is 255. |
description | string | Description of the project in plain text or HTML format. |
key | string | Project Key. The key should start with a letter followed by a combination of letters, numbers or both. The maximum length is 10 characters. |
status_id | number | Status of the project. |
priority_id | number | Priority of the project. |
project_type | number | Type of the Project - Business or Software. |
manager_id | number | User ID of the project manager. |
start_date | date | Start date of the project. The acceptable format is yyyy-mm-dd. |
end_date | date | End date of the project. The acceptable format is yyyy-mm-dd. |
visibility | number | Visibility of the project - Public / Private. |
sprint_duration | number | Sprint duration in days for the project. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
archived | boolean | Denotes whether a project is archived or not. Read-Only |
created_at | datetime | Date and time of project creation. Read-Only |
updated_at | datetime | Date and time at which the project was last updated. Read-Only |
Project Properties
Every project uses certain fixed numerical values to denote its Status and Priority. These numerical values along with their meanings are given below.
Status | Value |
---|---|
Yet to start | 1 |
In Progress | 2 |
Completed | 3 |
Priorities | Value |
---|---|
Low | 1 |
Medium | 2 |
High | 3 |
Urgent | 4 |
Project Type | Value |
---|---|
Software Project | 0 |
Business Project | 1 |
Visibility | Value |
---|---|
0 | Private |
1 | Public |
Create a Project
This API helps you create a new project in your service desk
Attribute | Type | Description |
---|---|---|
name | string | Name of the project. The maximum number of characters allowed is 255.Mandatory |
description | string | Description of the project in plain text or HTML format. |
project_type | number | Type of the project.Mandatory |
key | string | Project Key. The key should start with a letter followed by a combination of letters, numbers or both. The maximum length is 10 characters. Without the key value, a default key will be created from the project name. |
status_id | number | The status value is set to "Yet to start".Read-Only |
priority_id | number | Priority of the project. The default priority is 'Medium' (Value = 2). |
manager_id | number | User ID of the project manager. The default value is of the person creating the project. |
start_date | date | Start date of the project. The acceptable format is yyyy-mm-dd. The default value is the project creation date. |
end_date | date | End date of the project. The acceptable format is yyyy-mm-dd. The default value is the project creation date + 10 days. |
visibility | number | Visibility of the project - Public / Private. The default visibility is 'Public' (Value = 1). |
sprint_duration | number | Sprint duration in days for the project. The default value is 14. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
project_template_id | number | Project template being used. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "name": "Intranet Site Development", "key": "SP3", "description": "<div>Project for Intranet Site Development</div>", "priority_id": 2, "sprint_duration": 14, "project_type": 0, "start_date": "2021-04-01", "end_date": "2021-06-30", "visibility": 1, "manager_id": 43423, "custom_fields": { "custom_text": "This is a custom text box" } }' -X POST 'https://domain.freshservice.com/api/v2/pm/projects' |
Create a Project With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'name=Intranet Site Development' -F 'description=Project for Intranet Site Development' -F 'project_type=0' -X POST 'https://domain.freshservice.com/api/v2/pm/projects' |
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 | { "project": { "id": 1, "name": "Intranet Site Development", "key": "ISD", "description": "<div>Project for Intranet Site Development</div>", "priority_id": 1, "sprint_duration": 14, "project_type": 0, "start_date": null, "end_date": null, "archived": false, "attachments": [ { "id": 25634, "content_type": "application/png", "attachment_url": "https://domain.freshrelease.com/documents/25634", "size": 552562, "name": "api_attach.png", "created_at": "2024-05-14T12:04:38.000Z", "updated_at": "2024-05-14T12:04:38.000Z" } ], "visibility": 1, "manager_id": 43423, "created_at": "2021-04-01T07:16:45Z", "updated_at": "2021-04-01T07:16:45Z", "custom_fields": {} } } |
Update a Project
This API lets you update the properties of a project.
Attribute | Type | Description |
---|---|---|
name | string | Name of the project. The maximum number of characters allowed is 255. |
key | string | Project Key. The key should start with a letter followed by a combination of letters, numbers or both. The maximum length is 10 characters. |
description | string | Description of the project in plain text or HTML format. |
status_id | number | Status of the project. |
priority_id | number | Priority of the project. |
manager_id | number | User ID of the project manager. |
start_date | date | Start date of the project. The acceptable format is yyyy-mm-dd. |
end_date | date | End date of the project. The acceptable format is yyyy-mm-dd. |
visibility | number | Visibility of the project - Public / Private. |
sprint_duration | number | Sprint duration in days for the project. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X PUT -d '{ "name": "Intranet Site Development 3", "description": "<div>Project for Intranet Site Development</div>", "key": "SP3", "status_id": 2, "priority_id": 2, "manager_id": 43423, "start_date": "2021-04-01", "end_date": "2021-06-30", "visibility": 1, "sprint_duration": 14, "custom_fields": { "custom_text": "This is a custom text box" } }' 'https://domain.freshservice.com/api/v2/pm/projects/1' |
Update a Project With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'name=Intranet Site Development 3' -F 'description=Project for Intranet Site Development 3' -X PUT 'https://domain.freshservice.com/api/v2/pm/projects/1' |
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 | { "project": { "id": 1, "name": "Intranet Site Development 3", "key": "ISD", "description": "<div>Project for Intranet Site Development 3</div>", "priority_id": 1, "sprint_duration": 14, "project_type": 0, "start_date": null, "end_date": null, "archived": false, "attachments": [ { "id": 25634, "content_type": "application/png", "attachment_url": "https://domain.freshrelease.com/documents/25634", "size": 552562, "name": "api_attach.png", "created_at": "2024-05-14T12:04:38.000Z", "updated_at": "2024-05-14T12:04:38.000Z" } ], "visibility": 1, "manager_id": 43423, "created_at": "2021-04-01T07:16:45Z", "updated_at": "2021-04-01T07:16:45Z", "custom_fields": {} } } |
View a Project
This API lets you view the details of a project.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1' |
List All Projects
Query Parameters | Type | Handle |
---|---|---|
filter | string | Filter projects based on given value. The filters available are ['completed', 'incomplete', 'archived', 'open', 'in_progress']. By default open and completed projects are listed. 'Incomplete' will display all open and in progress projects. Example: api/v2/pm/projects?filter=completed |
page | number | The page number to retrieve. Example: api/v2/pm/projects?page=1 |
per page | number | The number of entries to retrieve in each page of a paginated list. The default value is 30 and the maximum value is 100. Example: api/v2/pm/projects?per_page=20 |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects' |
Delete a Project
This API lets you permanently delete a project. Deleted projects cannot be restored.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/pm/projects/2' |
Archive a Project
Note: Archived projects are not permanently lost. You can retrieve them using the Restore Project API.
1 | curl -v -u api_key:X -X POST 'https://domain.freshservice.com/api/v2/pm/projects/1/archive' |
Restore a Project
You can restore an archived project using this API.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '' 'https://domain.freshservice.com/api/v2/pm/projects/1/restore' |
View Project Fields
Attribute | Description |
---|---|
label | Display name of the field (as seen by project members). |
name | Name of the field. |
type | Indicates if the field is a text, number, date, paragraph, checkbox,or dropdown. For default fields, the term ‘default’ is prefixed to the field name. |
default | Set to true if the field is a default field. |
choices | List of values supported by the field. |
mandatory | Set to true if the field is mandatory. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/project-fields' |
View Project Templates
Attribute | Description |
---|---|
name | Name of the template |
id | Template ID |
description | Description of the template |
template_type | Template type i.e 0 for Software, 1 for Business |
visibility | Visibility of the template i.e. visible only to project members or to everyone |
created_at | Date created at |
updated_at | Date updated at |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/project_templates' |
Add Members
This API allows you to add one or more members to a project.
Note:
This is an asynchronous operation and is performed using background jobs. The response of the api contains the job id, which can be used to query the status of the job.
Attribute | Type | Description |
---|---|---|
id | number | ID of the project. |
string | email address of the user.Mandatory | |
role | string | Project Key. The key should start with a letter followed by a combination of letters, numbers or both. The maximum length is 10 characters. Without the key value, a default key will be created from the project name. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "members": [{ "email": "alex@xyz.com", "role": 1 }, { "email": "angela@xyz.com" }, { "email": "abc@xyz.com", role: 2 }] }' -X POST 'https://domain.freshservice.com//api/v2/pm/projects/1/members' |
Background Jobs API
Background Jobs api can be used to query the status of the background job. What various "status" values indicate is represented in the below table
Status | Comments |
---|---|
queued | Job is queued and ready to be executed |
in progress | Job execution started |
partial | Job completed. Few relationships created successfully, but few failed |
success | Job completed. All relationships are created |
failed | Job completed. No relationships are created |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/jobs/25cf5d0b-b2cd-4224-9715-bd48cb89896d' |
Create Associations
This API allows you to associate a Project with specific Tickets, Problems, Changes or Assets.
Attribute | Type | Description |
---|---|---|
ids | array of numbers | Unique ID(s) of the Ticket/Problem/Change/Asset being associatedMandatory |
module_name | string | Name of the module being associated with. This can be Tickets, Problems, Changes or Assets.Mandatory |
project_id | number | Unique ID of the projectMandatory |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "ids":[1,2] }' -X POST 'https://domain.freshservice.com/api/v2/pm/projects/1/tickets' |
View Associations
This API allows you to delete an association of a project.
Attribute | Type | Description |
---|---|---|
module_name | string | Name of the module for which associations need to be viewed. This can be Tickets, Problems, Changes or Assets.Mandatory |
project_id | number | Unique ID of the projectMandatory |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tickets' |
Delete Association
This API allows you to delete an association of a project.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the Ticket/Problem/Change/AssetMandatory |
module_name | string | Name of the module. This can be Tickets, Problems, Changes or Assets.Mandatory |
project_id | number | Unique ID of the projectMandatory |
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/pm/projects/1/tickets/1' |
Delete Attachment of a Project
This API allows you to delete an attachment of a project.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/projects/1/attachments/1' |
Projects Tasks
Note:
Following Project Task APIs are for new-gen project management and these are not compatible with our legacy project management module. You can find the task APIs for legacy project management here.
Manage projects by organizing them into tasks and nested subtasks, and easily assign them to individual owners. Collaborate and discuss, attach files for context, view dependencies, and use the activity log to monitor progress.
Note:
Only users with "View or Manage Projects" privilege can access the following APIs.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the task. Read-Only |
title | string | Title of the task. |
description | string | Description of the task in plain text or HTML format. |
type_id | number | ID of the task type. Examples of task types are epic, user story, etc. It can be obtained from here. |
reporter_id | number | User ID of the person who reported the task. |
assignee_id | number | User ID of the person to whom the task is assigned. |
planned_start_date | datetime | Planned start date of the task. The acceptable format is yyyy-mm-ddThh:mm:ssZ. |
planned_end_date | datetime | Planned end date of the task. The acceptable format is yyyy-mm-ddThh:mm:ssZ. |
planned_effort | string | Planned effort of the task. The acceptable format is '1w 2d 3h 4m'. |
planned_duration | string | Planned duration of the task. It is the difference between the planned end and start dates. The acceptable format is ‘1w 2d 3h 4m’. |
status_id | number | Status of the task. The id can be obtained from here. |
priority_id | number | Priority of the task. The id can be obtained here. |
parent_id | number | ID of the parent task (if this field is applicable). In the case of subtasks, it is the ID of the parent task it is a part of. In the case of standard tasks, it is the ID of the Epic/Task_List it is a part of. The id can be obtained here. |
story_points | number | Story Points of the task (if this field is applicable). |
sprint_id | number | ID of the sprint this task should be a part of (if this field is applicable). It can be obtained from here. |
version_id | number | ID of the version this task is a part of (if this field is applicable). It can be obtained from here. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
created_at | datetime | Date and time when the task was created. Read-Only |
updated_at | datetime | Date and time when the task was last updated. Read-Only |
Create a Project Task
This API lets you create a project task.
Attribute | Type | Description |
---|---|---|
title | string | Name of the task.Mandatory |
description | string | Description of the task in plain text or HTML format. |
type_id | number | The type of task to be created . Examples of task types are epic, user story, etc. The id can be obtained from here.Mandatory |
reporter_id | number | User ID of the person who reported the task. The default value is of the person creating the task. |
assignee_id | number | User ID of the person to whom the task is to be assigned. |
planned_start_date | datetime | Planned start date of the task. The acceptable format is yyyy-mm-ddThh:mm:ssZ. |
planned_end_date | datetime | Planned end date of the task. The acceptable format is yyyy-mm-ddThh:mm:ssZ. |
planned_effort | string | Planned effort of the task. The acceptable format is '1w 2d 3h 4m'. |
status_id | number | Status of the task. The id can be obtained from here. The default status is "Open". |
priority_id | number | Priority of the task. The id can be obtained from here. |
parent_id | number | ID of the parent task (if this field is applicable). In the case of subtasks, it is the ID of the parent task it is a part of. In the case of standard tasks, it is the ID of the Epic/Task_List it is a part of. |
story_points | number | Story Points of the task (if this field is applicable). |
sprint_id | number | ID of the sprint this task should be a part of (if this field is applicable). It can be obtained from here. |
version_id | number | ID of the version this task is a part of (if this field is applicable). It can be obtained from here. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{ "title": "Clear backlog", "description": "Clear backlog", "status_id": 1, "priority_id": 4567, type_id": 456789, "assignee_id": 984793, "planned_start_date": "2021-06-11T07:16:45Z", "planned_end_date": "2021-06-20T07:16:45Z", "planned_effort": null, "parent_id": 34534, "story_points": 1, "reporter_id": 789621, "sprint_id": 7892913, "version_id": 789271, "custom_fields": { "custom_text": "This is a custom text box" } }' 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks' |
Create a Task With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'title=Clear backlog' -F 'description=Clear backlog' -F 'type_id=456789' -X POST 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks' |
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 | { "task": { "id": 1, "title": "Clear backlog", "project_id": 1, "description": "Clear backlog", "status_id": 1, "priority_id": 4567, "reporter_id": null, "created_at": "2021-06-14T07:16:45.000Z", "updated_at": "2021-06-14T07:16:45.000Z", "display_key": "FS-1", "planned_start_date": null, "type_id": 456789, "assignee_id": null, "planned_end_date": null, "planned_effort": null, "custom_fields": {}, "attachments": [ { "id": 25634, "content_type": "application/png", "attachment_url": "https://domain.freshrelease.com/documents/25634", "size": 552562, "name": "api_attach.png", "created_at": "2024-05-14T12:04:38.000Z", "updated_at": "2024-05-14T12:04:38.000Z" } ], "version_id": null, "parent_id": null, "story_points": null, "sprint_id": null } } |
Update a Project Task
This API lets you update a project task
Attribute | Type | Description |
---|---|---|
title | string | Name of the task. |
description | string | Description of the task in plain text or HTML format. |
assignee_id | number | User ID of the person to whom the task is to be assigned. |
planned_start_date | datetime | Planned start date of the task. The acceptable format is yyyy-mm-ddThh:mm:ssZ. |
planned_end_date | datetime | Planned end date of the task. The acceptable format is yyyy-mm-ddThh:mm:ssZ. |
planned_effort | string | Planned effort of the task. The acceptable format is '1w 2d 3h 4m'. |
planned_duration | string | It is the difference between the planned end and start dates. The acceptable format is '1w 2d 3h 4m'. If only duration is updated, it will update the planned end date of the task as well. If both duration and planned end date are updated, preference will be given to the planned end date value. |
status_id | number | Status of the task. The id can be obtained from here. |
priority_id | number | Priority of the task. The id can be obtained from here. |
parent_id | number | ID of the parent task (if this field is applicable). In the case of subtasks, it is the ID of the parent task it is a part of. In the case of standard tasks, it is the ID of the Epic/Task_List it is a part of. The id can be obtained here. |
story_points | number | Story Points of the task (if this field is applicable). |
sprint_id | number | ID of the sprint this task should be a part of (if this field is applicable). It can be obtained from here. |
version_id | number | ID of the version this task is a part of (if this field is applicable). It can be obtained from here. |
custom_fields | dictionary | Key value pairs containing the names and values of custom fields. Read more here. |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X PUT -d '{ "title": "Clear backlog", "description": "Clear backlog", "status_id": 1, "priority_id": 4567, "assignee_id": 984793, "planned_start_date": "2021-06-11T07:16:45Z", "planned_end_date": "2021-06-20T07:16:45Z", , "planned_effort": null, "duration": "1w 3d", "parent_id": 34534, "story_points": 1, "sprint_id": 7892913, "version_id": 789271, "custom_fields": { "custom_text": "This is a custom text box" } }' 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/1' |
Update a Task With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'title=Clearing backlog' -X PUT 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks' |
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 | { "task": { "id": 1, "title": "Clearing backlog", "project_id": 1, "description": "Clear backlog", "status_id": 1, "priority_id": 4567, "reporter_id": null, "created_at": "2021-06-14T07:16:45.000Z", "updated_at": "2021-06-14T07:16:45.000Z", "display_key": "FS-1", "planned_start_date": null, "type_id": 456789, "assignee_id": null, "planned_end_date": null, "planned_effort": null, "custom_fields": {}, "attachments": [ { "id": 25634, "content_type": "application/png", "attachment_url": "https://domain.freshrelease.com/documents/25634", "size": 552562, "name": "api_attach.png", "created_at": "2024-05-14T12:04:38.000Z", "updated_at": "2024-05-14T12:04:38.000Z" } ], "version_id": null, "parent_id": null, "story_points": null, "sprint_id": null } } |
View a Project Task
This API lets you view the details of a project task
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/1' |
List All Project Tasks
Query Parameters | Type | Handle |
---|---|---|
filter | string | Allowed filters are ['open','unresolved']. By default all the open and completed project tasks are listed. Example: /api/v2/pm/projects/1/tasks?filter=all |
page | number | The page number to retrieve. Example: api/v2/pm/projects/1/tasks?page=1 |
per page | number | The number of entries to retrieve in each page of a paginated list. The default value is 30 and the maximum value is 100. Example: api/v2/pm/projects/1/tasks?per_page=20 |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/projects/1/tasks' |
Filter All Project Tasks
Get a list of tasks matching the specified task fields.
Note:
1. The query must be URL encoded.
2. Query can be framed using the task field name in snake case, which can be obtained from supported task fields. Task Fields are case sensitive.
3. Query string must be enclosed between a pair of double quotes and can have up to 512 characters.
4. Logical operators AND, OR along with parentheses () can be used to group conditions.
5. Relational operators greater than or equal to :> and less than or equal to :< can be used along with date fields.
6. Input for date fields should be in UTC Format.
7. The number of objects returned per page is 30 also the total count of the results will be returned along with the result.
8. To scroll through the pages add page parameter to the URL.
Query Parameters | Type | Handle |
---|---|---|
query | string | MandatoryQuery string must be enclosed between a pair of double quotes and can have up to 512 characters. Example: /api/v2/pm/projects/1/tasks/filter?query="priority_id: 1 AND status_id: 2" |
page | number | The page number to retrieve. Example: api/v2/pm/projects/1/tasks/filter?query="status_id:3%20OR%20status_id:4"&page=2 |
Supported Task Fields
Field | Type | Description |
---|---|---|
version_id | number | ID of the version this task is a part of |
sprint_id | number | ID of the sprint this task should be a part of |
priority_id | number | Priority of the task |
status_id | number | Status of the task |
type_id | number | Id of the task type |
assignee_id | number | User ID of the person to whom the task is assigned |
reporter_id | number | User ID of the person who reported the task |
created_at | date | Task creation date (YYYY-MM-DD) |
Note:
Queries can be combined using AND or OR.
https://domain.freshservice.com/api/v2/pm/projects/{id}/tasks/filter?query="priority_id: 1 AND status_id: 2"
Supported operators 1. priority_id: 1 (priority_id equal to 1)
2. created_at:> '2024-01-01' (created_at greater than or equal to '2024-01-01')
3. created_at:< '2023-01-01' (created_at less than or equal to '2023-01-01')
Formatting 1. String fields to be enclosed in single quotes ('')
2. Number fields to be given as number without quotes.
3. Date and date_time fields to be enclosed in single quotes('yyyy-mm-dd')
4. only :> and :< are supported for date and date_time fields. Both fields expect input in the same format as 'yyyy-mm-dd'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/filter?query="priority:4567"' |
1. Get the list of Urgent and High priority tasks ('priority_id:4 OR priority_id:3')
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/filter?query="priority_id:4%20OR%20priority_id:3"' |
2. Get the second page of Open and In Progress tasks ('status_id:3 OR status_id:4')
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/filter?query="status_id:3%20OR%20status_id:4"&page=2' |
3. Get the list of Urgent priority tasks created after a particular day ('priority_id:4 AND created_at:>'2021-01-01')
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/filter?query="priority_id%3A%203%20AND%20created_at%3A%3E%272020-01-01%27"' |
4. Get the list of Urgent priority tasks created after a particular day with time included ('priority_id:4 AND created_at:>'2021-01-01T09:46:02Z')
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/filter?query="priority_id%3A%203%20AND%20created_at%3A%3E%272020-01-01T09:46:02Z%27"' |
Delete a Project Task
This API helps you delete a project task. Deleted tasks cannot be restored.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/pm/projects/2/tasks/1' |
View Project Task Type Fields
Attribute | Description |
---|---|
project_id | ID of the project this task type is present in. |
label | Display name of the field (as seen by project members). |
name | Name of the field. This can be used in API requests. |
type | Indicates if the field is a text, number, date, paragraph, checkbox,or dropdown. |
choices | List of values supported by the field. |
default | Set to true if the field is a default field. |
mandatory | Set to true if the field is mandatory. |
This API lets you list the fields of a specifc task type from your project. The ID of the task type can be obtained from this API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/task-types/1/fields' |
View Project Task Types
Attribute | Description |
---|---|
project_id | ID of the project. |
id | ID of task type. |
name | Name of the task type. |
description | Description of the task type. |
This API lists all the task types that are present in a project.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/task-types' |
View Project Task Priorities
Attribute | Description |
---|---|
project_id | ID of the project. |
id | ID of the priority level. |
name | Priority level. |
description | Description of the priority level. |
This API lists all the priority levels that have been created in a project.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/task-priorities' |
View Project Task Statuses
Attribute | Description |
---|---|
project_id | ID of the project. |
id | ID of the status. |
name | Name of the status. |
description | Description of the status. |
category_id | Category of the status. 1 = Yet to start, 2 = Work in progress, 3 = Completed. |
This API lists all the task statuses that have been defined in a project.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/task-statuses' |
View Project Versions
Attribute | Description |
---|---|
project_id | ID of the project. |
id | ID of the version. |
name | Name of the version. |
description | Description of the version. |
start_date | Start date of the version. |
due_date | Due date of the version. |
status_id | Status of the version. 1 = Unreleased, 2 = Released. |
owner_id | ID of the user who owns the version. |
This API lists all the versions that have been created in a project.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/versions' |
View Project Sprints
Attribute | Description |
---|---|
project_id | ID of the project. |
id | ID of the sprint. |
title | Name of the sprint. |
goal | Goal of the sprint. |
state | State of the sprint [1 = Planned, 2 = Active, 3 = Completed, 0 = Deleted]. |
planned_start_date | Planned start date entered for the sprint. |
planned_end_date | Planned end date entered for the sprint. |
This API lists all the sprints that have been created in a project.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/sprints' |
View Project Memberships
Attribute | Description |
---|---|
id | Memebership ID of the project. |
project_id | ID of the project. |
user_id | User ID of the project member. |
access_type | Access type of the user. 1 = Project Viewer, 2 = Project Editor. |
manage_settings | Set to "true" if the user has the permission to manage project settings. |
project_manager | Set to "true" if the user is the manager of the project. |
This API lists all the members that are present in a project.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/memberships' |
Create Associations
This API allows you to associate a task with specific Tickets, Problems, Changes or Assets.
Attribute | Type | Description |
---|---|---|
ids | array of numbers | Unique ID(s) of the Ticket/Problem/Change/Asset being associatedMandatory |
module_name | string | Name of the module being associated with. This can be Tickets, Problems, Changes or Assets.Mandatory |
project_id | number | Unique ID of the projectMandatory |
task_id | number | Unique ID of the taskMandatory |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "ids":[1,2] }' -X POST 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/1/tickets' |
View Associations
This API allows you to view all associations of a project task by module.
Attribute | Type | Description |
---|---|---|
module_name | string | Name of the module for which associations need to be viewed. This can be Tickets, Problems, Changes or Assets.Mandatory |
project_id | number | Unique ID of the projectMandatory |
task_id | number | Unique ID of the taskMandatory |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/1/tickets' |
Delete Association
This API allows you to delete an association of a project task.
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the Ticket/Problem/Change/AssetMandatory |
module_name | string | Name of the module. This can be Tickets, Problems, Changes or Assets.Mandatory |
project_id | number | Unique ID of the projectMandatory |
task_id | number | Unique ID of the taskMandatory |
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/1/tickets/1' |
Create Note
This API allows you to add a note to a task.
Attribute | Type | Description |
---|---|---|
project_id | number | Unique ID of the project.Mandatory |
task_id | number | Unique ID of the task.Mandatory |
content | string | The content of the note.Mandatory | attachments | array of attachment objects | Note Attachments. The total size of these attachments cannot exceed 26 MB |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X POST -d '{ "content": "<p>Hi tom, Still Angry</p>" }' 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/12/notes' |
Create a Note With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'content=Hi tom, Still Angry' -X POST 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/12/notes' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | { "notes": [ { "id": 1, "body": "<p>Hi tom, Still Angry</p>", "task_id": 12, "user_email_id": "abc@freshworks.com", "attachments": [ { "id": 25634, "content_type": "application/png", "attachment_url": "https://domain.freshrelease.com/documents/25634", "size": 552562, "name": "api_attach.png", "created_at": "2024-05-14T12:04:38.000Z", "updated_at": "2024-05-14T12:04:38.000Z" } ], "created_at": "2024-05-14T12:04:38.000Z", "updated_at": "2024-05-14T12:04:38.000Z" } ] } |
View Notes
This API allows you to view all task notes.
Attribute | Description |
---|---|
project_id | Unique ID of the project. |
id | Unique ID of the task. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/12/notes' |
Update Note
This API allows you to update a note.
Attribute | Type | Description |
---|---|---|
project_id | number | Unique ID of the project.Mandatory |
id | number | Unique ID of the task.Mandatory |
id | number | Unique ID of the note.Mandatory |
content | string | The content of the note.Mandatory | attachments | array of attachment objects | Note Attachments. The total size of these attachments cannot exceed 26 MB |
1 2 | curl -v -u api_key:X -H "Content-Type:application/json" -X PUT -d '{ "content": "<p>Hi tom, Still Angry</p>" }' 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/12/notes/1' |
Update a Note With Attachment
Note:
1. This API request must have its Content-Type set to multipart/form-data.
1 | curl -v -u api_key:X -F 'attachments[]=@/Users/user/Desktop/api_attach.png' -F 'content=Hi tom, Still Angry' -X PUT 'https://domain.freshservice.com/api/v2/pm/projects/1/tasks/12/notes/1' |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | { "notes": [ { "id": 1, "body": "<p>Hi tom, Still Angry</p>", "task_id": 12, "user_email_id": "abc@freshworks.com", "attachments": [ { "id": 25634, "content_type": "application/png", "attachment_url": "https://domain.freshrelease.com/documents/25634", "size": 552562, "name": "api_attach.png", "created_at": "2024-05-14T12:04:38.000Z", "updated_at": "2024-05-14T12:04:38.000Z" } ], "created_at": "2024-05-14T12:04:38.000Z", "updated_at": "2024-05-14T12:04:38.000Z" } ] } |
Delete Note
This API allows you to delete a note.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/projects/1/tasks/12/notes/1' |
Delete Attachment of a Note
This API allows you to delete an attachment of a note.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/projects/1/tasks/12/notes/1/attachments/1' |
Delete Attachment of a Task
This API allows you to delete an attachment of a task.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/projects/1/tasks/12/attachments/1' |
Solution Category
The Solution APIs allow you to perform all activities related to the creation and publishing of solutions to your requesters. You can create, modify or delete solutions from anywhere you want using the Solutions API.
The API is divided into 3 categories: 1. Solution Category, 2. Solution Folder 3. Solution Article
Attribute | Type | Description |
---|---|---|
id | number | Unique id of the solution category Read-Only |
workspace_id | number | ID of the workspace to which the solution category belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
name | string | Name of the solution category Mandatory |
description | string | Description about the solution category |
position | number | The rank of the solution category in the category listing Read-Only |
default_category | boolean | Set as true if the category is a default one Read-Only |
visible_in_portals | array of numbers | List of Unique portal IDs where this category is visible. Allowed only if the account is configured with multiple portals. |
Create Solution Category
Use this API to create a new category of solutions.
Note:
The attribute 'workspace_id' is applicable only for accounts on the Employee Support Mode. The default value is the ID of the primary workspace of the account.
1 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "name":"API", "description":"API related documents", "visible_in_portals":[1], "workspace_id": 2 }' https://domain.freshservice.com/api/v2/solutions/categories |
Update Solution Category
Use this API to update solution categories. For a list of all attributes that can be updated, look here
1 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "name":"Rest API", "workspace_id": 2 }' https://domain.freshservice.com/api/v2/solutions/categories/2 |
View Solution Category
To view the category available in your service desk, use this
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET https://domain.freshservice.com/api/v2/solutions/categories/2 |
View List of Solution Categories
This API lets you view all the categories in a forum.
Note:
By default, only categories from the primary workspace will be returned for accounts on the Employee Support Mode. For categories from other workspaces, use the workspace_id filter.
Filter by | Handle |
---|---|
Workspace | /api/v2/solutions/categories?workspace_id=[id] If a workspace_id is not specified as a URL parameter, only solution categories from the primary workspace will be included in the response. If workspace_id is specified as 0, solution categories from across all workspaces will be included in the response. Applicable only to accounts on the Employee Support Mode. |
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET https://domain.freshservice.com/api/v2/solutions/categories?workspace_id=2 |
Delete Solution Category
To delete certain Categories, use this API.
1 | curl -u api_key:X -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/api/v2/solutions/categories/2 |
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 |
workspace_id | number | ID of the workspace to which the solution folder belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
name | string | Name of the solution folder Mandatory |
description | string | Description of the solution folder |
position | number | Describes the position in which the folder is listed Read-Only |
default_folder | boolean | Set as true is it is a default folder Read-Only |
category_id | number | ID of the category under which the folder is listed Mandatory |
visibility | number | Accessibility of this folder |
approval_settings | hash | Approval settings that have been associated with the folder. Key-value pair containing the approval_type, approval_ids and its values. |
department_ids | number | ID of the department to which this solution folder is visible. ( Mandatory if visibility is set to '4') |
group_ids | number | ID of the Agent Groups to which this solution folder is visible. ( Mandatory if visibility is set to '5') |
requester_group_ids | number | ID of the Contact Groups to which this solution folder is visible. ( Mandatory if visibility is set to '6') |
manage_by_group_ids | array of numbers | Unique ID of the Groups to which this solution folder is managed by. |
Solution Folder Properties
Visibility Type | Value |
---|---|
All | 1 |
Logged in Users | 2 |
Agents Only | 3 |
Departments | 4 |
Agent groups | 5 |
Contact groups | 6 |
Approval Settings | |
---|---|
Approval Type | Value |
All Approvers | 1 |
Anyone can approve / reject | 4 |
Approval Ids | List of Unique ID of the users to approve the folder |
Create Solution Folder
Use this API to create a new folder in your solutions.
1 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "name":"Folder API", "visibility":4, "description":"Folder CRUD Operations", "department_ids": [4,5], "category_id": 2 }' https://domain.freshservice.com/api/v2/solutions/folders |
Create Solution Folder with Approval
Use this API to create a new folder with approval settings in your solutions.
1 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "name":"Folder API", "visibility":4, "description":"Folder CRUD Operations", "department_ids": [4,5], "category_id": 2, "approval_settings": {"approval_type": 1, "approver_ids": [1]} }' https://domain.freshservice.com/api/v2/solutions/folders |
Update Solution Folder
To update details of your solution folder, use this API. You can change the name, description and
1 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "visibility":1, "description":"Folder API related Operations" }' https://domain.freshservice.com/api/v2/solutions/folders/2 |
View Solution Folder
To view all folders present in a category, use this API.
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET https://domain.freshservice.com/api/v2/solutions/folders/2 |
View List of Solution Folder
This API lets you view all the folders in a forum for specific category.
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET https://domain.freshservice.com/api/v2/solutions/folders?category_id=2 |
Delete Solution Folder
This API can be used to delete solution folder. Deleted solution folders cannot be restored.
1 | curl -u api_key:X -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/api/v2/solutions/folders/2 |
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 |
workspace_id | number | ID of the workspace to which the solution article belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
title | string | Title of the solution article Mandatory |
description | string | Description of the solution article |
position | number | The rank of the solution article in the article listing Read-Only |
article_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 |
category_id | number | ID of the category under which the article is belongs to |
status | number | Status of the article. ( 1 - draft, 2 - published ) |
approval_status | number | Approval status of the article. |
thumbs_up | number | Number of upvotes for the article Read-Only |
thumbs_down | number | Number of down votes for the article Read-Only |
agent_id | number | ID of the user who created the article Read-Only |
views | number | Total hit count of the user visited this article Read-Only |
tags | array of strings | Tags that have been associated with the article |
keywords | array of strings | keywords that have been associated with the article |
attachments | array of objects | Article attachments. The total size of these attachments cannot exceed 40 MB. |
url | string | Article from external url link. |
review_date | date | Date in future when this article would need to be reviewed again. |
Create Solution Article
To write a new solution article in a category, use this API.
Attribute | Type | Description |
---|---|---|
title | string | Title of the solution article Mandatory |
description | string | Description of the solution article Mandatory |
article_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 ) |
tags | array of strings | Tags that have been associated with the article |
keywords | array of strings | keywords that have been associated with the article |
review_date | date | Date in future when this article would need to be reviewed again. |
1 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "title": "Create a article", "description": "<p>Steps: Fill in the mandatory fields ...</p>", "status": 1, "article_type": 1, "folder_id": 2, "tags": ["tag1"] }' https://domain.freshservice.com/api/v2/solutions/articles |
Create Secondary Language Article
To create a secondary language article and link it to a primary language article, use this API
Attribute | Type | Description |
---|---|---|
title | string | Title of the solution article Mandatory |
description | string | Description of the solution article |
article type | number | The type of the article ( 1 -> permanent, 2 -> workaround ) |
folder_id | number | Unique ID of the solution folder Mandatory |
language | string | Language of secondary solution article, For example: French -> “fr” For other language code please refer hereMandatory |
parent_id | number | Unique ID of the primary language article Mandatory |
1 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "title": "Title of the solution article", "description": "<p> Description of the solution article </p>", "status": 1, "article_type": 1, "folder_id": 2, "language":"ar","parent_id": 1}' https://domain.freshservice.com/api/v2/solutions/articles |
Create Article With Attachment
To write a new solution article with attachments in a category, use this API.
1 | curl --request POST 'https://domain.freshservice.com/api/v2/solutions/articles' --header 'Content-Type: multipart/form-data' --header 'Authorization: Basic base64 encoding - username and password' --form 'title=Create a article' --form 'folder_id=1' --form 'description=Steps: Fill in the mandatory fields ...' --form 'status=1' --form 'article_type=1' --form 'tags[]=tag1' --form 'attachments[]=@/Users/user/article.jpg' |
Create Article from External URL
To write a new solution external article in a category, use this API.
Attribute | Type | Description |
---|---|---|
title | string | Title of the solution article Mandatory |
url | string | Article from external url link Mandatory |
folder_id | number | ID of the folder under which the article is listed Mandatory |
status | number | Status of the article. ( 1 - draft, 2 - published ) |
tags | array of strings | Tags that have been associated with the article |
keywords | array of strings | keywords that have been associated with the article |
1 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "title": "Create an article from external url", "status": 2, "url": "https://en.wikipedia.org/wiki/English_Wikipedia", "folder_id": 2, "tags": ["tag1"], "keywords": ["keyword1"] }' https://domain.freshservice.com/api/v2/solutions/articles |
Search Solution Articles
Search for articles from the knowledge base for a given search term.
Note:
1. If the user_email parameter is provided, the user of the API key provided must have the privilege of assuming the identity of the user_email provided. Otherwise the API will return a 403 error.
2. The API will only return published solution articles that the user (or user_email) has access to.
Attribute | Type | Description |
---|---|---|
search_term | string | The keywords for which the solution articles have to be searched. Example: “Vpn issue” |
user_email | By default, the API will search the articles for the user whose API key is provided. If you want to search articles for a different user, please provide their user_email. | |
page | number | If the returned results are more than per_page, you can use the page parameter to fetch subsequent pages. |
per_page | number | The number of results to return per page. By default, the value is set to 30. |
1 | curl --location --request GET 'https://domain.freshservice.com/api/v2/solutions/articles/search?search_term=printer&page=2&per_page=10&user_email=andrea@freshservice.com' --header 'Authorization: Basic <apikey>' |
Send Article to Approval
To send article approval for the review, use this API.
1 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '' https://domain.freshservice.com/api/v2/solutions/articles/1/send_for_approval |
Publish Solution Article
To publish an solution article, use this API.
1 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "status": 2 }' https://domain.freshservice.com/api/v2/solutions/articles/1 |
Update Solution Article
To update an article, use this API.
1 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "title":"Steps to create a ticket", description":"Steps: 1. Fill in the mandatory fields ..." }' https://domain.freshservice.com/api/v2/solutions/articles/1 |
View Solution Article
If there is a specific article which you wish to view, use this API. Article ID is a must though.
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET https://domain.freshservice.com/api/v2/solutions/articles/1 |
View List of Solution Article
To view all the articles, use this API.
1 | curl -u api_key:X -H "Content-Type: application/json" -X GET https://domain.freshservice.com/api/v2/solutions/articles?folder_id=2 |
Delete Solution Article
To delete an article, use this API.
1 | curl -u api_key:X -H "Content-Type: application/json" -X DELETE https://domain.freshservice.com/api/v2/solutions/articles/1 |
Service Catalog
This section lists all APIs that are related to service category and service items
Service Item
This section lists all APIs that are related to service items.
Attribute | Type | Description |
---|---|---|
id | number | Unique id of the item |
workspace_id | number | ID of the workspace to which the service item belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
created_at | datetime | The time at which the item was created |
updated_at | datetime | The time at which the item was update |
name | string | Name of the item |
delivery_time | number | Estimated delivery time of the item (in hours) |
display_id | number | Unique ID of the service item specific to your account |
category_id | number | Unique ID of the category of the service item |
product_id | number | The ID of the product mapped to the item. Returns null if no product is mapped |
quantity | number | |
deleted | boolean | Set to True if the item is deleted |
group_visibility | number | 1 denotes visibility to all requesters. 2 for restricted visibility |
item_type | number | ‘1’ indicates a normal item. ‘2’ indicates a loaner item |
ci_type_id | number | Unique id of the asset type associated with the product |
cost_visibility | boolean | Set to True if cost should be visible to the requester |
delivery_time_visibility | boolean | Set to True if delivery time of the item should be visible to the requester |
configs | string | Config indicating the template of the service request subject |
botified | boolean | Set to True if item is “bot ready” |
visibility | number | ‘1’ denotes draft and ‘2’ denotes published. |
allow_attachments | boolean | Set to True if requester is allowed to attach a file |
allow_quantity | boolean | Set as True to allow the requester to request for more than 1 quantity |
is_bundle | boolean | Boolean indicating whether the item contains child items |
create_child | boolean | Boolean indicating whether child items will be created as separate service request |
description | string | Description of the service item |
short_description | string | Short Description of the service item |
cost | number | Cost of the service item |
custom_fields | - | Custom fields associated with the service item |
child_items | - | Child Service Items attached to this item |
View a Service Item
This API allows you to view the details of a service item.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/service_catalog/items/11' |
View List of Service Items
This API lists all service items in your Freshservice service desk.
To view items belonging to a particular category, use the filter below
Note:
By default, only service items from the primary workspace will be returned for accounts on the Employee Support Mode. For service items from other workspaces, use the workspace_id filter.
Filter By | Handle |
---|---|
Category Id | /api/v2/service_catalog/items?category_id=[category_id] |
Workspace | /api/v2/service_catalog/items?workspace_id=[id] 'workspace_id' is applicable only for accounts on the Employee Support Mode. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/service_catalog/items?workspace_id=2' |
Search Service Items
Search for service items from the service catalog for a given search term.
Note:
1. If the user_email parameter is provided, the user of the API key provided must have the privilege of assuming the identity of the user_email provided. Otherwise the API will return a 403 Error.
2. The API will only return published service items that the user (or user_email) has access to.
Attribute | Type | Description |
---|---|---|
workspace_id | number | ID of the workspace to which the service item belongs. If not specified, it will be defaulted to the ID of the primary workspace. This attribute is applicable only to accounts on the Employee Support Mode. |
search_term | string | The keywords for which the solution articles have to be searched. Example: “Vpn issue” |
user_email | By default, the API will search the articles for the user whose API key is provided. If you want to search articles for a different user, please provide their user_email. | |
page | number | If the returned results are more than per_page, you can use the page parameter to fetch subsequent pages. |
per_page | number | The number of results to return per page. By default, the value is set to 30. |
1 | curl --location --request GET 'https://domain.freshservice.com/api/v2/service_catalog/items/search?workspace_id=2&search_term=adobe&page=1&per_page=3&user_email=andrea@freshservice.com' --header 'Authorization: Basic <apikey>' |
Create Service Catalog item
This operation allows you to create a new service item in Freshservice.
Attribute | Type | Description | workspace_id | number | ID of the workspace to which the service item needs to be created. 'workspace_id' is applicable only to accounts on the Employee Support Mode.The default value is the ID of the primary workspace of the account. |
---|---|---|
name * | string | Name of the Service Item. Example: “Vpn issue” |
category_id * | number | Unique ID of the category of the service item. The category ID can be obtained by using the "/api/v2/service_catalog/items" public API. |
short_description * | number | Short Description of the service item. |
description * | number | Description of the service item. |
visibility * | number | '1' denotes draft and '2' denotes published state of the service item. |
cost | number | Cost of the service item. |
cost_visibility | boolean | Set to True if the cost should be visible to the requester. |
delivery_time | number | Estimated delivery time of the item (in hours). |
delivery_time_visibility | boolean | Set to True if the delivery time of the item should be visible to the requester. |
agent_group_visibility | number | This attribute describes the collection of agents who can view this service item in the service catalog. Possible values: 1: All agents. 2: Agents in specific groups. 3: Agents in specific workspaces. |
agent_group_visibilities | hash | This attribute contains the group_id attribute, and is applicable only if agent_group_visibility is set to 2 (Agents in specific groups). |
group_id | array | This attribute contains the array of agent group identifiers which have been granted access to the service item. |
agent_workspace_visibilities | hash | This attribute contains the workspace_ids attribute, and is applicable only if agent_group_visibility is set to 3 (Agents in specific workspaces). |
workspace_ids | array | This attribute contains the array of workspace identifiers which have been granted access to the service item. |
group_visibility | number | 1 denotes visibility to all requesters. 2 for restricted visibility. |
custom_fields | array of hash | Custom fields associated with the service item. |
label | string | Name of the custom field. |
placeholder | string | Placeholder value for the custom field. |
required | boolean | Indicates whether the Field is required or not during the form submission. |
field_options | hash | Contains Options available for selection of the field. |
displayed_to_requester | boolean | Requester can view the field. This field should be set to True if we want requester_can_edit to be Set as True |
requester_can_edit | boolean | Requester can edit the field. |
choices | array of hash | Dropdown choices for a custom field. |
value | string | Contains dropdown choice values. |
field_type | string | Denotes the Custom field Type. |
Note:
1. Custom field Type that we support for creating API are custom_text (Single Line Text), custom_dropdown (Dropdown), custom_checkbox (Checkbox), custom_paragraph (Paragraph Text), custom_date_time (Date), custom_number (Number), custom_decimal (Decimal), custom_big_number (Number), custom_url (URL), custom_static_rich_text (Content), custom_multi_select_dropdown (Multi Dropdown).
2. workspace_id cannot be set to 1 (which represents global settings), as service items cannot be created under global settings.
1 2 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "service_item": { "name": "Item Name", "category_id": 10000345, "short_description": "Apple Macbook Pro 13 inch", "description": "<p>Apple Macbook Pro 13 inch - 8 GB</p>", "visibility": 2}, "workspace_id" : 3}' https://domain.freshservice.com/api/v2/service-catalog/items |
Create a Service Catalog Item With Custom Fields
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "service_item": { "name": "Employee Form", "category_id": 10000028112, "short_description": "Employee Details Form", "description": "Employee Information Form", "delivery_time": 10, "cost": "12.0", "visibility": 2, "custom_fields": [ { "label": "Employee Name", "placeholder": "Employee Name", "required": true, "field_options": { "displayed_to_requester": true, "requester_can_edit": true }, "field_type": "custom_text" }, { "label": "Employee Details", "placeholder": "Enter employee details", "required": true, "field_options": { "displayed_to_requester": true, "requester_can_edit": true }, "field_type": "custom_paragraph" }, { "label": "Employee Active", "required": false, "field_options": { "displayed_to_requester": true, "requester_can_edit": true }, "field_type": "custom_checkbox" }, { "label": "Employee Age", "placeholder": "Enter employee age", "required": false, "field_options": { "displayed_to_requester": true, "requester_can_edit": true }, "field_type": "custom_number" }, { "label": "Employee Start Date", "required": true, "field_options": { "displayed_to_requester": true, "requester_can_edit": true, "date_only": true }, "field_type": "custom_date_time" }, { "label": "Employee Department", "required": false, "field_options": { "displayed_to_requester": true, "requester_can_edit": true }, "choices": [ { "value": "HR" }, { "value": "Finance" }, { "value": "IT" }, { "value": "Operations" } ], "field_type": "custom_dropdown" }, { "label": "Employee Skills", "required": false, "field_options": { "displayed_to_requester": true, "requester_can_edit": true }, "choices": [ { "value": "ABC" } ], "field_type": "custom_multi_select_dropdown" }, { "label": "Employee Salary", "placeholder": "Enter employee salary", "required": false, "field_options": { "displayed_to_requester": true, "requester_can_edit": true }, "field_type": "custom_decimal" }, { "label": "Employee Profile Picture", "placeholder": "Upload employee profile picture", "required": false, "field_options": { "displayed_to_requester": true, "requester_can_edit": true }, "field_type": "custom_url" }, { "label": "Employee Bio", "required": false, "field_options": { "content_name": "Bio Field", "displayed_to_requester": true, "requester_can_edit": true }, "field_type": "custom_static_rich_text" } ] }, "workspace_id": 3 }' https://domain.freshservice.com/api/v2/service-catalog/items |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 | { "service_item": { "id": 42246, "created_at": "2023-06-29T09:46:58Z", "updated_at": "2023-06-29T09:46:58Z", "name": "Employee Form", "delivery_time": 10, "display_id": 25, "category_id": 10228, "product_id": null, "quantity": null, "deleted": false, "icon_name": "service-catalog-services-default", "group_visibility": 1, "agent_group_visibility": 2, "item_type": 1, "ci_type_id": null, "visibility": 2, "workspace_id": 3, "cost_visibility": false, "delivery_time_visibility": false, "botified": false, "allow_attachments": false, "allow_quantity": false, "is_bundle": false, "create_child": false, "configs": { "attachment_mandatory": false, "subject": "Request for {{requested_for}}: {{item.name}}" }, "description": "Employee Information Form", "short_description": "Employee Details Form", "desc_un_html": "Employee Information Form", "cost": "12.0", "agent_group_visibilities": {"group_id": [123]}, "agent_workspace_visibilities": { "workspace_ids": [] } "custom_fields": [ { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "d795a962-7ce3-4d0c-87c6-dce4266d7818", "label": "Employee Name", "name": "employee_name", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "Employee Name" }, "visible_in_portal": true, "field_type": "custom_text", "item_id": 42246, "position": 1, "required": true, "choices": [], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "397fac82-3725-4319-88f4-06d4ebd07a9d", "label": "Employee Details", "name": "employee_details", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "Enter employee details" }, "visible_in_portal": true, "field_type": "custom_paragraph", "item_id": 42246, "position": 2, "required": true, "choices": [], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "e70cc94f-c471-472a-a697-fc1ba5b40a60", "label": "Employee Active", "name": "employee_active", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "" }, "visible_in_portal": true, "field_type": "custom_checkbox", "item_id": 42246, "position": 3, "required": false, "choices": [], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "81ab3cbb-3906-4f57-8635-d2314cbf1d0c", "label": "Employee Age", "name": "employee_age", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "Enter employee age" }, "visible_in_portal": true, "field_type": "custom_number", "item_id": 42246, "position": 4, "required": false, "choices": [], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "2275bf2d-a823-4079-8ba9-5976e92f7472", "label": "Employee Start Date", "name": "employee_start_date", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "date_only": true, "placeholder": "" }, "visible_in_portal": true, "field_type": "custom_date", "item_id": 42246, "position": 5, "required": true, "choices": [], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "4ba5d714-ef68-4e64-b717-e089c65f5d78", "label": "Employee Department", "name": "employee_department", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "" }, "visible_in_portal": true, "field_type": "custom_dropdown", "item_id": 42246, "position": 6, "required": false, "choices": [ [ "HR", "HR" ], [ "Finance", "Finance" ], [ "IT", "IT" ], [ "Operations", "Operations" ] ], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "9feac2a8-b368-4a57-a10e-8cf3a1ed13d7", "label": "Employee Skills", "name": "employee_skills", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "" }, "visible_in_portal": true, "field_type": "custom_multi_select_dropdown", "item_id": 42246, "position": 7, "required": false, "choices": [ [ "ABC", "e0b2ff49-06a2-4b99-9d22-3e13a6ea33bf" ] ], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "21cca320-a57e-492b-87a0-5c5f571b1f5e", "label": "Employee Salary", "name": "employee_salary", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "Enter employee salary" }, "visible_in_portal": true, "field_type": "custom_decimal", "item_id": 42246, "position": 8, "required": false, "choices": [], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "9ed516fd-6d57-46ea-bd2a-6a7db5898853", "label": "Employee Profile Picture", "name": "employee_profile_picture", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "Upload employee profile picture" }, "visible_in_portal": true, "field_type": "custom_url", "item_id": 42246, "position": 9, "required": false, "choices": [], "nested_fields": [] }, { "created_at": "2023-06-29T09:46:58Z", "deleted": false, "description": null, "id": "b596c96f-29cc-4420-805f-7a4e710a47a2", "label": "Employee Bio", "name": "bio_field", "updated_at": "2023-06-29T09:46:58Z", "field_options": { "content_name": "Bio Field", "displayed_to_requester": "true", "requester_can_edit": "true", "placeholder": "" }, "visible_in_portal": true, "field_type": "custom_static_rich_text", "item_id": 42246, "position": 10, "required": false, "choices": [], "nested_fields": [] } ], "child_items": [], "icon_url": "https://domain.freshservice.com/services-default.png" } } |
Create a Service Catalog Item with agent workspace visibilities
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "service_item": { "name": "Item with workspace visibility", "category_id": 10, "short_description": "workspace visibility", "description": "<p>Apple Macbook Pro 13 inch - 8 GB</p>", "visibility": 2, "agent_group_visibility": 3, "agent_workspace_visibilities": { "workspace_ids": [ 2,4 ] } }, "workspace_id": 2 }' https://domain.freshservice.com/api/v2/service-catalog/items |
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 | { "service_item": { "id": 185, "created_at": "2024-01-04T07:44:17Z", "updated_at": "2024-01-04T07:44:17Z", "name": "Item with workspace visibility", "delivery_time": null, "display_id": 143, "category_id": 10, "product_id": null, "quantity": null, "deleted": false, "icon_name": "service-catalog-services-default", "group_visibility": 1, "agent_group_visibility": 3, "item_type": 1, "ci_type_id": null, "visibility": 2, "workspace_id": 2, "cost_visibility": false, "delivery_time_visibility": false, "botified": false, "allow_attachments": false, "allow_quantity": false, "is_bundle": false, "create_child": false, "configs": { "attachment_mandatory": false, "subject": "Request for {{requested_for}}: {{item.name}}" }, "description": "<p>Apple Macbook Pro 13 inch - 8 GB</p>", "short_description": "workspace visibility", "desc_un_html": " Apple Macbook Pro 13 inch - 8 GB ", "cost": null, "agent_group_visibilities": { "group_id": [] }, "agent_workspace_visibilities": { "workspace_ids": [ 2, 4 ] }, "custom_fields": [], "child_items": [], "icon_url": "http://domain.freshservice.com/assets/cdn-ignored/sprites/service-catalog/services-default.png" } } |
Create a Service Catalog Item with agent group visibilities
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "service_item": { "name": "Item with group visibility", "category_id": 10, "short_description": "workspace visibility", "description": "<p>Apple Macbook Pro 13 inch - 8 GB</p>", "visibility": 2, "agent_group_visibility": 2, "agent_group_visibilities": { "group_id": [ 20,21 ] } }, "workspace_id": 2 }' https://domain.freshservice.com/api/v2/service-catalog/items |
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 | { "service_item": { "id": 185, "created_at": "2024-01-04T07:44:17Z", "updated_at": "2024-01-04T07:44:17Z", "name": "Item with workspace visibility", "delivery_time": null, "display_id": 143, "category_id": 10, "product_id": null, "quantity": null, "deleted": false, "icon_name": "service-catalog-services-default", "group_visibility": 1, "agent_group_visibility": 3, "item_type": 1, "ci_type_id": null, "visibility": 2, "workspace_id": 2, "cost_visibility": false, "delivery_time_visibility": false, "botified": false, "allow_attachments": false, "allow_quantity": false, "is_bundle": false, "create_child": false, "configs": { "attachment_mandatory": false, "subject": "Request for {{requested_for}}: {{item.name}}" }, "description": "<p>Apple Macbook Pro 13 inch - 8 GB</p>", "short_description": "workspace visibility", "desc_un_html": " Apple Macbook Pro 13 inch - 8 GB ", "cost": null, "agent_group_visibilities": { "group_id": [ 20, 21 ] }, "agent_workspace_visibilities": { "workspace_ids": [] }, "custom_fields": [], "child_items": [], "icon_url": "http://domain.freshservice.com/assets/cdn-ignored/sprites/service-catalog/services-default.png" } } |
Service Category
This section list all API related to service category
Attribute | Type | Description |
---|---|---|
id | number | Unique id of the category |
workspace_id | number | ID of the workspace to which the service category belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
name | string | Name of the service category |
description | string | Description of the service category |
created_at | datetime | The time at which the category was created |
updated_at | datetime | The time at which the category was updated |
position | number | Number denoting the position of category in service catalog |
View List of Service Categories
This api lists all service categories in your Freshservice service desk
Note:
By default, only service categories from the primary workspace will be returned for accounts on the Employee Support Mode. For service categories from other workspaces, use the workspace_id filter.
Filter by | Handle |
---|---|
Workspace | /api/v2/service_catalog/categories?workspace_id=[id] 'workspace_id' is applicable only for accounts on the Employee Support Mode. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/service_catalog/categories?workspace_id=2' |
Announcements
Announcements can be used by IT Teams to share updates with Agents and End-users. It is particularly useful in sharing updates on new releases and in broadcasting down-time alerts.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the AnnouncementRead-Only |
workspace_id | number | ID of the workspace that the Announcement belongs to. If not provided, the ID of the primary workspace will be defaulted. Applicable only to accounts on the Employee Support Mode. |
created_by | number | Unique identifier of the agent to created this Announcement |
state | string | State of the Announcement - active, archived, scheduled |
title | string | Title of the Announcement |
body | string | Body of the Announcement |
body_html | string | Body of the Announcement in HTML format |
visible_from | datetime | Timestamp at which Announcement becomes active |
visible_till | datetime | Timestamp until which Announcement is active |
visibility | string | Who can see the announcement? Values - everyone, agents_only, agents_and_groups |
departments | Array of numbers | Array of Department IDs that can view this Announcement (visibility must be agents_and_groups) |
groups | Array of numbers | Array of Group IDs that can view this Announcement (visibility must be agents_and_groups) | is_read | boolean | True if the logged-in-user has read the announcement |
send_email | boolean | True if the announcement needs to be sent via email as well. False, otherwise |
additional_emails | Array of Strings | Additional email addresses to which the announcement needs to be sent | created_at | datetime | Announcement creation timestamp |
updated_at | datetime | Announcement updated timestamp |
Create an Announcement
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{"title": "Email Service Outage", "body_html": "<h2>Email Service is down</h2> <p>Service will be up and running in 2 hours</p>", "visible_from": "2020-02-26T11:19:45.994Z", "visible_till": "2020-02-27T11:19:45.994Z", "visibility": "grouped_visibility", "departments": [ 19456, 23432 ], "groups": [ 34231 ], "additional_emails": [ "abc@xyz.com" ], "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/announcements' |
View an Announcement
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/announcements/122' |
List All Announcements
Filter by | Handle |
---|---|
state | /api/v2/announcements?state=[archived | active | scheduled | unread] |
Workspace | /api/v2/announcements?workspace_id=[id] If a workspace_id is not specified as a URL parameter, only announcements from the primary workspace will be included in the response. If workspace_id is specified as 0, announcements from across all workspaces will be included in the response. Applicable only to accounts on the Employee Support Mode. |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/announcements' |
1. Get the list of all announcements from workspaces to which the user has access.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/announcements?workspace_id=0' |
2. Get the list of announcements from a specific workspace
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/announcements?workspace_id=3' |
Edit an Announcement
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{"title": "[Restored] Email Service Outage", "body_html": "<h2>Email Service is up and running now</h2> <p>Service is restored</p>", "visible_from": "2020-02-26T11:19:45.994Z", "visible_till": "2020-02-27T11:19:45.994Z", "visibility": "grouped_visibility", "departments": [ 19456, 23432 ], "groups": [ 34231 ], "additional_emails": [ "abc@xyz.com" ], "workspace_id": 2 }' 'https://domain.freshservice.com/api/v2/announcements/122' |
Delete an Announcement
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X DELETE 'https://domain.freshservice.com/api/v2/announcements/122’ |
Employee Onboarding
This section lists all APIs related to Employee Onboarding.
View Onboarding Form Fields
This API lets you view all the fields in the Initiator’s Onboarding form.
Field | Type | Description |
---|---|---|
placeholder | string | Placeholder of the field Read-Only |
label | string | Label of the fieldRead-Only |
name | string | Name of the fieldRead-Only |
position | number | Position of the field Read-Only |
required | boolean | Boolean indicating whether the field is required or not during form submissionRead-Only |
default | boolean | Boolean indicating whether the field is default or notRead-Only |
field_type | string | Indicates the type of fieldRead-Only |
data_source | number | Indicates the type of Datasource. This value will be available only for field_type: "custom_lookup_bigint". Please refer the Data source table to know moreRead-Only |
Lookup Datasources
The Onboarding form may contain Lookup fields with Datasource. Lookup Datasources are entities where we can search data from them. The numerical value for each DataSource (Department, Location etc.) is given below.
Source | Value |
---|---|
locations | 1 |
Requesters | 2 |
Agents | 3 |
Assets | 4 |
All Users | 5 |
Departments | 6 |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/onboarding_requests/form' |
Create an Onboarding Request
This API helps you to create a new Onboarding Request in your service desk.
Note:
1. Based on the field values, Mandatory service items (that do not have any Mandatory custom fields) in Onboarding kits will be selected and attached to the Onboarding Request.
2. Only user who has admin privilege can raise request behalf of other onboarding user by adding initiator_id.
3. initiator_id is the User ID of the initiator.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | { "initiator_id": 1, "fields": { "cf_employee_name": "Andrea", "cf_job_title": "HR", "cf_date_of_joining": "2020-08-20", "cf_all_users": "andrea@freshservice.com", "cf_department": "HR", "cf_assets": 1, "cf_location": 5, "cf_hierarchy": "L3", "cf_verified": true, "msf_area_of_expertise": [ "Ruby", "Java" ], "msf_preferred_locations": [53, 57] } } |
1 2 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "fields": { "cf_employee_name": "Andrea","cf_job_title": "HR", "cf_date_of_joining": "2020-08-20","cf_all_users": "andrea@freshservice.com","cf_department": "HR","cf_assets": 1,"cf_location": 5,"cf_hierarchy": "L3","cf_verified": true}}' https://domain.freshservice.com/api/v2/onboarding_requests |
View an Onboarding Request
This API lets you retrieve and view a specific Onboarding Request in your service desk.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/onboarding_requests/id' |
View all Onboarding Requests
This API lets you view all the Onboarding Requests in your service desk.
The below table lists the custom status for Onboarding Request
Status | value |
---|---|
Awaiting Information | 1 |
Request Cancelled | 2 |
Request In Progress | 3 |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/onboarding_requests' |
View Onboarding Tickets
This API lets you retrieve and view the Onboarding Tickets associated with an Onboarding Request.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/onboarding_requests/id/tickets' |
Employee Offboarding
This section lists all APIs related to Employee Offboarding.
View Offboarding Form Fields
This API lets you view all the fields in the Initiator’s Offboarding form.
Field | Type | Description |
---|---|---|
placeholder | string | Placeholder of the field Read-Only |
label | string | Label of the fieldRead-Only |
name | string | Name of the fieldRead-Only |
position | number | Position of the field Read-Only |
required | boolean | Boolean indicating whether the field is required or not during form submissionRead-Only |
default | boolean | Boolean indicating whether the field is default or notRead-Only |
field_type | string | Indicates the type of fieldRead-Only |
data_source | number | Indicates the type of Datasource. This value will be available only for field_type: "custom_lookup_bigint". Please refer the Data source table to know moreRead-Only |
Lookup Datasources
The Offboarding form may contain Lookup fields with Datasource. Lookup Datasources are entities where we can search data from them. The numerical value for each DataSource (Department, Location etc.) is given below.
Source | Value |
---|---|
locations | 1 |
Requesters | 2 |
Agents | 3 |
Assets | 4 |
All Users | 5 |
Departments | 6 |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/offboarding_requests/form' |
Create an Offboarding Request
This API helps you to create a new Offboarding Request in your service desk.
Note:
1. Only user who has admin privilege can raise request behalf of other offboarding user by adding initiator_id.
2. initiator_id is the User ID of the initiator.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | { "initiator_id": 1, "fields": { "actor_2": "sample@freshservice.com", "cf_employee_name": "Andrea", "cf_employee_email": "andrea@freshservice.com", "cf_department": "HR", "cf_separation_type": "Voluntary Separation", "cf_mobile_phone_number": "123456789", "cf_assets": 1, "cf_location": 5, "cf_hierarchy": "L3", "cf_verified": true, "msf_area_of_expertise": [ "Ruby", "Java" ], "msf_preferred_locations": [53, 57] } } |
1 2 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "fields": { "cf_employee_name": "Andrea","cf_employee_email": "andrea@freshservice.com", "cf_department": "HR","cf_separation_type": "Voluntary Separation","cf_mobile_phone_number": "123456789","cf_assets": 1,"cf_location": 5,"cf_hierarchy": "L3","cf_verified": true}}' https://domain.freshservice.com/api/v2/offboarding_requests |
View an Offboarding Request
This API lets you retrieve and view a specific Offboarding Request in your service desk.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/offboarding_requests/id' |
View all Offboarding Requests
This API lets you view all the Offboarding Requests in your service desk.
The below table lists the custom status for Offboarding Request
Status | value |
---|---|
Awaiting Information | 1 |
Request Cancelled | 2 |
Request In Progress | 3 |
Request Completed | 4 |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/offboarding_requests' |
View Offboarding Tickets
This API lets you retrieve and view the Offboarding Tickets associated with an Offboarding Request.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/offboarding_requests/id/tickets' |
Oncall management
On-Call Management helps organizations contain the impact of critical incidents by getting the right person to start working on an incident fast. It does so by automating escalation as per pre-configured calendars, rosters, communication channels, and notification rules.
Create a schedule
This operation allows you to create an on-call schedule for an agent group
Attribute | Type | Description |
---|---|---|
name | string | Name of the on-call schedule Mandatory |
description | string | Description associated with the on-call schedule |
agent_group_id | number | Unique identifier id of an agent group Mandatory |
agent_group_name | string | Name of agent group Mandatory |
Note: Only users with "Manage On-call schedules" privilege can access the following API.
1 2 3 4 5 6 | { "name": "OCS Schedule", "description": "Public OCS API", "agent_group_id": 1000208191, "agent_group_name": "1 Public API" } |
1 2 3 4 5 6 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "name": "OCS Public API Edit1", "description": "Public OCS API Edit1", "agent_group_id": 1000208191, "agent_group_name": "1 Public API" }' |
Update a schedule
This operation allows you to update an existing on-call schedule
Note: Only users with "Manage On-call schedules" privilege can access the following API.
1 2 3 4 5 6 | { "name": "OCS Public API Edit1", "description": "Public OCS API Edit1", "agent_group_id": 1000208191, "agent_group_name": "1 Public API" } |
1 2 3 4 5 6 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "name": "OCS Public API Edit1", "description": "Public OCS API Edit1", "agent_group_id": 1000208191, "agent_group_name": "1 Public API" }' |
View all schedules
This operation allows you to fetch details about all on-call schedules in your workspace
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules?page=1&per_page=30' |
Filter schedules
This operation allows you to get list of all on-call schedules in your workspace whose schedule names include the search query (scheduleName).
Note: Supports between 2 to 255 char as input. Input supports alphanumeric and following characters - " / \ - _ . + ( ) $ & ! @ # % ^ * [ ] { } | ' : < > ;?
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules?page=1&per_page=30&query=Schedule1' |
View a schedule
This operation allows you to fetch details about all on-call schedules in your workspace by ID
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules/8569' |
Delete a schedule
This operation allows you to delete n on-call schedules in your workspace by its ID
Note: Only users with "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules/8569' |
Create a shift
This operation lets you create a new shift within your on-call schedule
Attribute | Type | Description |
---|---|---|
name | string | Name of the on-call schedule Mandatory |
timezone | string | Timezone for the on-call schedule Mandatory |
start_date | datetime | Date and time from which the shift starts Mandatory |
end_date | datetime | Date and time from which the shift ends |
roster | json | Provide details about your roster part of the shift |
Note: Only users with "Manage On-call schedules" privilege can access the following API.
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 | { "name": "OCS shift", "timezone": "Eastern Time (US & Canada)", "start_date": "2024-04-18T05:00:00Z", "rosters": [ { "roster_type": "PRIMARY", "id": null, "rotation_type": "DAILY", "hand_off_day": "MON", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "user": { "name": "Staging Test Agent", "email": "john.doe@gmail.com", "product_user_id": "1001447031" }, "color_code": "#ffffff", "roster_type": "PRIMARY" } ], "shift_times": [], "shift_event_overrides": [] }, { "roster_type": "SECONDARY", "id": null, "rotation_type": "DAILY", "hand_off_day": "MON", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "user": { "name": "John Doe", "email": "john.doe@gmail.com", "product_user_id": "1000814658" }, "color_code": "#ffffff", "roster_type": "SECONDARY" } ], "shift_times": [], "shift_event_overrides": [] }, { "roster_type": "TERTIARY", "id": null, "rotation_type": "DAILY", "hand_off_day": "MON", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "user": { "name": "John Doe", "email": "john.doe@gmail.com", "product_user_id": "1000814658" }, "color_code": "#ffffff", "roster_type": "TERTIARY" } ], "shift_times": [], "shift_event_overrides": [] } ] } |
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 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "name": "OCS shift", "timezone": "Eastern Time (US & Canada)", "start_date": "2024-04-18T05:00:00Z", "rosters": [ { "roster_type": "PRIMARY", "id": null, "rotation_type": "DAILY", "hand_off_day": "MON", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "user": { "name": "Staging Test Agent", "email": "john.doe@gmail.com", "product_user_id": "1001447031" }, "color_code": "#ffffff", "roster_type": "PRIMARY" } ], "shift_times": [], "shift_event_overrides": [] }, { "roster_type": "SECONDARY", "id": null, "rotation_type": "DAILY", "hand_off_day": "MON", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "user": { "name": "John Doe", "email": "john.doe@gmail.com", "product_user_id": "1000814658" }, "color_code": "#ffffff", "roster_type": "SECONDARY" } ], "shift_times": [], "shift_event_overrides": [] }, { "roster_type": "TERTIARY", "id": null, "rotation_type": "DAILY", "hand_off_day": "MON", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "user": { "name": "John Doe", "email": "john.doe@gmail.com", "product_user_id": "1000814658" }, "color_code": "#ffffff", "roster_type": "TERTIARY" } ], "shift_times": [], "shift_event_overrides": [] } ] }' |
Update a shift
This operation lets you update an existing shift within your on-call schedule
Note: Only users with "Manage On-call schedules" privilege can access the following API.
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 | { "start_date": "2024-04-18T05:00:00Z", "name": "OCS shift", "timezone": "Eastern Time (US & Canada)", "end_date": null, "rosters": [ { "roster_type": "PRIMARY", "id": "18807", "rotation_type": "WEEKLY", "hand_off_day": "WED", "hand_off_date": "1", "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "user": { "name": "Staging Test Agent", "email": "john.doe@gmail.com", "product_user_id": "1001447031" } } ], "shift_times": [], "shift_event_overrides": [] } ] } |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "shift": { "id": 11411, "name": "OCS shift", "description": null, "timezone": "Eastern Time (US & Canada)", "status": "ACTIVE", "start_date": "2024-04-18T05:00:00Z", "end_date": null, "rosters": [ { "id": 18807, "roster_type": "PRIMARY", "rotation_type": "WEEKLY", "hand_off_day": "WED", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "id": 275302, "user": { "id": 16146, "name": "Staging Test Agent", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1001447031", "phone": null, "mobile": null, "agent": true, "group_ids": "1000207613,1000207614,1000207615,1000207616,1000207617,1000207620" }, "roster_type": "PRIMARY", "sequence_order": 1 } ], "shift_times": [], "shift_events": [ { "id": 373282018, "user": { "id": 16146, "name": "Staging Test Agent", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1001447031", "phone": null, "mobile": null, "agent": true, "group_ids": "1000207613,1000207614,1000207615,1000207616,1000207617,1000207620" }, "event_start_date_time": "2024-04-18T05:00:00Z", "event_end_date_time": "2024-04-24T05:00:00Z", "overridden": false } ], "shift_event_overrides": [], "is_only_overridden_events": false }, { "id": 18808, "roster_type": "SECONDARY", "rotation_type": "DAILY", "hand_off_day": "MON", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "id": 275300, "user": { "id": 47, "name": "John Doe", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1000814658", "phone": "+13232323232", "mobile": null, "agent": true, "group_ids": "1000186851,1000186855,1000206400,1000206869,1000207617,1000207620,1000207696,1000208087" }, "roster_type": "PRIMARY", "sequence_order": 1 } ], "shift_times": [], "shift_events": [ { "id": 373282092, "user": { "id": 47, "name": "John Doe", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1000814658", "phone": "+13232323232", "mobile": null, "agent": true, "group_ids": "1000186851,1000186855,1000206400,1000206869,1000207617,1000207620,1000207696,1000208087" }, "event_start_date_time": "2024-04-18T05:00:00Z", "event_end_date_time": "2024-04-19T05:00:00Z", "overridden": false }, { "id": 373282093, "user": { "id": 47, "name": "John Doe", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1000814658", "phone": "+13232323232", "mobile": null, "agent": true, "group_ids": "1000186851,1000186855,1000206400,1000206869,1000207617,1000207620,1000207696,1000208087" }, "event_start_date_time": "2024-04-19T05:00:00Z", "event_end_date_time": "2024-04-20T05:00:00Z", "overridden": false }, { "id": 373282094, "user": { "id": 47, "name": "John Doe", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1000814658", "phone": "+13232323232", "mobile": null, "agent": true, "group_ids": "1000186851,1000186855,1000206400,1000206869,1000207617,1000207620,1000207696,1000208087" }, "event_start_date_time": "2024-04-20T05:00:00Z", "event_end_date_time": "2024-04-21T05:00:00Z", "overridden": false } ], "shift_event_overrides": [], "is_only_overridden_events": false }, { "id": 18809, "roster_type": "TERTIARY", "rotation_type": "DAILY", "hand_off_day": "MON", "hand_off_date": 1, "custom_rotation_type": "HOURS", "custom_rotation_length": 1, "shift_restriction_type": "TWENTY4X7", "members": [ { "id": 275301, "user": { "id": 47, "name": "John Doe", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1000814658", "phone": "+13232323232", "mobile": null, "agent": true, "group_ids": "1000186851,1000186855,1000206400,1000206869,1000207617,1000207620,1000207696,1000208087" }, "roster_type": "PRIMARY", "sequence_order": 1 } ], "shift_times": [], "shift_events": [ { "id": 373282166, "user": { "id": 47, "name": "John Doe", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1000814658", "phone": "+13232323232", "mobile": null, "agent": true, "group_ids": "1000186851,1000186855,1000206400,1000206869,1000207617,1000207620,1000207696,1000208087" }, "event_start_date_time": "2024-04-18T05:00:00Z", "event_end_date_time": "2024-04-19T05:00:00Z", "overridden": false }, { "id": 373282167, "user": { "id": 47, "name": "John Doe", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1000814658", "phone": "+13232323232", "mobile": null, "agent": true, "group_ids": "1000186851,1000186855,1000206400,1000206869,1000207617,1000207620,1000207696,1000208087" }, "event_start_date_time": "2024-04-19T05:00:00Z", "event_end_date_time": "2024-04-20T05:00:00Z", "overridden": false }, { "id": 373282168, "user": { "id": 47, "name": "John Doe", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1000814658", "phone": "+13232323232", "mobile": null, "agent": true, "group_ids": "1000186851,1000186855,1000206400,1000206869,1000207617,1000207620,1000207696,1000208087" }, "event_start_date_time": "2024-04-20T05:00:00Z", "event_end_date_time": "2024-04-21T05:00:00Z", "overridden": false } ], "shift_event_overrides": [], "is_only_overridden_events": false } ], "escalation_path": null } }' |
View all shifts
This operation allows you to fetch details about all shifts in your on-call schedule
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules/8569/shifts' |
View a shift
This operation allows you to fetch details about relevant shifts in your on-call schedule by using their ids
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules/8569/shifts/201' |
Delete a shift
This operation allows you to delete shifts in your on-call schedule by using their ids
Note: Only users with "Manage On-call schedules" privilege can access the following API.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules/8569/shifts/201' |
Create/Update/Delete an override
This operation lets you create, update, delete an override as part of an existing shift so that another agent will be on-call instead of the one originally configured
Attribute | Type | Description |
---|---|---|
name | string | Name of the on-call schedule Mandatory |
roster_type | string | Indicates the roster type as primary, secondary or tertiary Mandatory |
id | number | Roster id of the shift |
override_from | datetime | Start time of the override Mandatory |
override_to | datetime | End time of the override Mandatory |
action | string | For create, the action is “CREATE” For update, the action is “UPDATE” For delete, the action is “DESTROY” Mandatory |
name | string | Name of the agent providing the coverage |
product_user_id | number | ID of the agent providing the coverage Mandatory |
Note: Only users with “Provide on-call coverage” privilege can access the API.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | { "name": "OCS shift", "rosters": [ { "roster_type": "PRIMARY", "id": "18812", "shift_event_overrides": [ { "id": 373282400, "override_from": "2024-04-18T10:30:00Z", "override_to": "2024-04-20T01:30:00Z", "action": "CREATE", "user": { "product_user_id": "1001447031", "name": "Staging Test Agent" } } ] } ] } |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "name": "OCS shift", "rosters": [ { "roster_type": "PRIMARY", "id": "18812", "shift_event_overrides": [ { "id": 373282400, "override_from": "2024-04-18T10:30:00Z", "override_to": "2024-04-20T01:30:00Z", "action": "CREATE", "user": { "product_user_id": "1001447031", "name": "Staging Test Agent" } } ] } ] }' |
View oncall calendar events for a user
This operations enables you to get information about all on-call events for a user has during a fixed duration
Attribute | Type | Description |
---|---|---|
start_time | datetime | Indicates date and time from from when the events need to be fetched Read-Only |
end_time | datetime | Indicates date and time till when the events need to be fetched Read-Only |
user_id | number | User Id of the user whose on-call calendar events should be fetched Read-Only |
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/shift-events?start_time=2024-04-18T05:00:00Z&end_time=2024-04-19T05:00:00Z&shift_id=201&schedule_id=25988&user_id=47' |
View oncall calendar events for a schedule
This operations enables you to get information about all on-call events in an on-call schedule during a fixed duration
Attribute | Type | Description |
---|---|---|
start_time | datetime | Indicates date and time from from when the events need to be fetched Read-Only |
end_time | datetime | Indicates date and time till when the events need to be fetched Read-Only |
schedule_id | number | On-call schedule id for which calendar events should be fetched Read-Only |
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/shift-events?start_time=2024-04-18T05:00:00Z&end_time=2024-04-19T05:00:00Z&schedule_id=8569' |
View oncall calendar events for a shift
This operation enables you to get information about all on-call events in an shift during a fixed duration
Attribute | Type | Description |
---|---|---|
start_time | datetime | Indicates date and time from from when the events need to be fetched Read-Only |
end_time | datetime | Indicates date and time till when the events need to be fetched Read-Only |
schedule_id | number | On-call schedule id for which calendar events should be fetched Read-Only |
shift_id | number | Shift id for the shift within the on-call schedule for which calendar events need to be fetched Read-Only |
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/shift-events?start_time=2024-04-18T05:00:00Z&end_time=2024-04-19T05:00:00Z&shift_id=201&schedule_id=25988' |
View oncall calendar events of a shift for a user
This operation enables you to get information about all on-call events in an shift for a user
Attribute | Type | Description |
---|---|---|
start_time | datetime | Indicates date and time from from when the events need to be fetched Read-Only |
end_time | datetime | Indicates date and time till when the events need to be fetched Read-Only |
schedule_id | number | On-call schedule id for which calendar events should be fetched Read-Only |
shift_id | number | Shift id for the shift within the on-call schedule for which calendar events need to be fetched Read-Only |
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/shift-events?start_time=2024-04-19T18:30:00Z&end_time=2024-04-20T18:30:00Z&shift_id=201&schedule_id=8569&user_id=25988' |
View oncall calendar events of a schedule for a user
This operation enables you to get information about all on-call events in an shift for a user
Attribute | Type | Description |
---|---|---|
start_time | datetime | Indicates date and time from from when the events need to be fetched Read-Only |
end_time | datetime | Indicates date and time till when the events need to be fetched Read-Only |
schedule_id | number | On-call schedule id for which calendar events should be fetched Read-Only |
shift_id | number | Shift id for the shift within the on-call schedule for which calendar events need to be fetched Read-Only |
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/shift-events?start_time=2024-04-19T18:30:00Z&end_time=2024-04-20T18:30:00Z&schedule_id=8569&user_id=25988' |
View who is oncall
This operation enables you to find out who’s on call right now for a given on-call schedule using its id
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
Create an escalation policy
This operation lets you create a new escalation policy within an existing on-call schedule
Attribute | Type | Description |
---|---|---|
name | string | Name of the on-call schedule Mandatory |
status | string | Indicates if the EP should be “ACTIVE” or “INACTIVE” when created |
repeat_count | number | How many times should EP be executed if no one acknowledges the notifications Mandatory |
condition_type | number | Configure the boolean logic using conditions. 0: is, 1: is not, 2: includes, 3: does not include, 4: contains, 5: does not contain, 6: is empty, 7: is not empty Mandatory |
channels | number | Controls through which channel should on-call agents should be notified 1: SMS 2: E-mail 3: Slack 5: Push notification 6: Teams 7: Whatsapp |
notifiers | json | Provide details regarding agents who need to be notified Mandatory |
escalation_policy_paths | json | Provide details regarding whom to notify, how to notify and when to notify Mandatory |
conditions | json | Define conditions to control on which incidents escalation policy should be followed Mandatory |
shift_ids | numeric | Provide shift ids for which shifts the policy should be applicable -1 selects all shifts Mandatory |
Note: Only users with "Manage On-call schedules" privilege can access the API.
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 | { "name": "OCS escalation policy", "status": "ACTIVE", "repeat_count": 2, "condition_type": 1, "stakeholders": { "notify_interval": 5, "channels": [ 0 ], "notifiers": [ { "agent": true, "product_user_id": "1001447031", "email": "john.doe@gmail.com", "groups_payload": "1000207613,1000207614,1000207615,1000207616,1000207617,1000207620", "mobile": "", "name": "Staging Test Agent", "phone": "", "second_email": "" } ] }, "escalation_policy_paths": [ { "level": 1, "position": 1, "notify_interval": 5, "channels": [ 2 ], "escalation_policy_path_notifiers": [ { "notifier": null, "notifier_type": 0, "roster_type": 0 } ] } ], "conditions": [ { "module": "ticket", "property": "priority", "operator": 0, "value": [ "2" ] } ], "shift_ids": [ "-1" ] } |
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 | curl -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "name": "OCS escalation policy", "status": "ACTIVE", "repeat_count": 2, "condition_type": 1, "stakeholders": { "notify_interval": 5, "channels": [ 0 ], "notifiers": [ { "agent": true, "product_user_id": "1001447031", "email": "john.doe@gmail.com", "groups_payload": "1000207613,1000207614,1000207615,1000207616,1000207617,1000207620", "mobile": "", "name": "Staging Test Agent", "phone": "", "second_email": "" } ] }, "escalation_policy_paths": [ { "level": 1, "position": 1, "notify_interval": 5, "channels": [ 2 ], "escalation_policy_path_notifiers": [ { "notifier": null, "notifier_type": 0, "roster_type": 0 } ] } ], "conditions": [ { "module": "ticket", "property": "priority", "operator": 0, "value": [ "2" ] } ], "shift_ids": [ "-1" ] }' |
Update an escalation policy
This operation lets you update an escalation policy within an existing on-call schedule
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
Note: To set an escalation policy as active or inactive, set status field as "ACTIVE" or "INACTIVE"
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 | { "name": "OCS escalation policy", "status": "ACTIVE", "rank": 3, "repeat_count": 2, "condition_type": 1, "stakeholders": { "notify_interval": 5, "channels": [ 0 ], "notifiers": [ { "id": 16146, "name": "Staging Test Agent", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1001447031", "phone": null, "mobile": null, "agent": true, "group_ids": "1000207613,1000207614,1000207615,1000207616,1000207617,1000207620" } ] }, "escalation_policy_paths": [ { "level": 1, "position": 1, "notify_interval": 5, "channels": [ 2, 7 ], "escalation_policy_path_notifiers": [ { "notifier": null, "notifier_type": 0, "roster_type": 0 } ], "id": "201172" } ], "conditions": [ { "module": "ticket", "property": "priority", "operator": 0, "value": [ "2" ] }, { "module": "ticket", "property": "cf_major_incident_type", "operator": 0, "value": [ "Partial outage" ] } ], "shift_ids": [ -1 ] } |
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 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d ' { "name": "OCS escalation policy", "status": "ACTIVE", "rank": 3, "repeat_count": 2, "condition_type": 1, "stakeholders": { "notify_interval": 5, "channels": [ 0 ], "notifiers": [ { "id": 16146, "name": "Staging Test Agent", "email": "john.doe@gmail.com", "second_email": null, "product_user_id": "1001447031", "phone": null, "mobile": null, "agent": true, "group_ids": "1000207613,1000207614,1000207615,1000207616,1000207617,1000207620" } ] }, "escalation_policy_paths": [ { "level": 1, "position": 1, "notify_interval": 5, "channels": [ 2, 7 ], "escalation_policy_path_notifiers": [ { "notifier": null, "notifier_type": 0, "roster_type": 0 } ], "id": "201172" } ], "conditions": [ { "module": "ticket", "property": "priority", "operator": 0, "value": [ "2" ] }, { "module": "ticket", "property": "cf_major_incident_type", "operator": 0, "value": [ "Partial outage" ] } ], "shift_ids": [ -1 ] }' |
View all escalation policies
This operation lets you get details about all the escalation policies in an on-call schedule
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules/8569/escalation-policies' |
View an escalation policy
This operation lets you get details about particular escalation policies in an on-call schedule by its id
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules/8569/escalation-policies/12415' |
Delete an escalation policy
This operation lets you delete an escalation policy
Note: Only users with "Manage On-call schedules" privilege can access the API.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/oncall/ws/2/schedules/8569/escalation-policies/12415' |
Reorder an escalation policy
This operation lets you re-order the escalation policies (EP) within an on-call schedule. In cases where ticket conditions match two or more EPs, notifications are sent from the EP which is at a higher level.
Note: Only users with "View On-call schedules" or "Manage On-call schedules" privilege can access the API.
1 2 3 4 5 6 7 | { "reorder_list":{ "31127":1, "31128":3, "31129":2 } } |
1 2 3 4 5 6 7 | curl -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "reorder_list":{ "31127":1, "31128":3, "31129":2 } }' |
Custom Objects
Custom Objects allow you to create your own custom entities and thus extend the data model in Freshservice to solve a number of use cases. More information about custom objects can be found here.
View List of Custom Objects
This API lists all the Custom objects that are present in the account.
Note:
By default, only Custom objects from the primary workspace will be returned for accounts on the Employee Support Mode. For Custom objects from other workspaces, use the workspace_id filter.
Filter by | Handle |
---|---|
Workspace | /api/v2/objects?workspace_id=[id] 'workspace_id' is applicable only for accounts on the Employee Support Mode. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/objects?workspace_id=2' |
Show a Custom Object
This API gives you the details of a given Custom object like field names, options for dropdown fields etc.
The following are the default readonly meta fields present in every Custom object
Name | Label |
---|---|
bo_display_id | Record ID |
bo_created_by | Created By |
bo_updated_by | Updated By |
bo_created_at | Created At |
bo_updated_at | Updated At |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/objects/1000040838' |
Create new Custom Object Record
This API creates a new record in a Custom object.
Note:
1. The field names to construct the request body and options for dropdowns can be obtained using the Show Custom Object API.
2. ID of the source entity (Agent, Ticket etc) should be specified as value for the lookup fields.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X POST -d '{ "data": { "agent_group": "5175566", "approver": "1232007392", "category_dd1": "Hardware", "category_dd2": "Computer", "category_dd3": "PC", "item_name": "1011125282", "vendor_information": "Apple-sales@apple.com" } }' 'https://domain.freshservice.com/api/v2/objects/1000040838/records' |
List all records of a Custom Object
This API lists all the records present in a given Custom object.
Note:
The query request parameter can be specified to filter the records. The query parameter is a list of conditions connected by the AND operator. The rules for constructing the query parameter are as follows
1. A condition should be of the format [field-name] [condition-operator] [field-value].
2. Conditions can be specified using the AND operator.
3. The field-value can be a string enclosed in single quotes, a number or null.
4. The supported condition operators are : (equal to), < (less than),> (greater than), :< (less than or equal to), :> (greater than or equal to).
5. The : (equal to) operator can be used with a comma separated list of values enclosed in square brackets to match any one of the list values. For example, [1, 2, 4].
6. Dates should be specified in the UTC format (YYYY-MM-DDTHH:MM:SS.sssZ). For example, 2020-10-11T06:00:00.000Z, 2021-09-18T15:00:00Z etc.
7. The query request parameter must be URL encoded and should not be enclosed in any quotes before encoding (See example below).
Supported request parameters
Field | Type | Description |
---|---|---|
query | string | URL encoded query string (formed using the above rules) to filter records. |
page_size | integer | The number of records to be returned in a single query. |
sort_field | string | Name of the object field to be used for sorting the records. |
sord_order | string | Order of sorting the records (ASC or DESC). |
next_page_link | string | URL encoded link for the next page of results. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/objects/1000040838/records' |
Example request with page_size and query parameters. query parameter before encoding
category_dd1 : 'Hardware' AND category_dd3 : ['PC', 'Mac'] AND bo_created_at :< '2021-09-18T15:00:00Z'
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/objects/1000040838/records?page_size=5&query=category_dd1%20%3A%20%27Hardware%27%20AND%20category_dd3%20%3A%20%5B%27PC%27%2C%20%27Mac%27%5D%20AND%20bo_created_at%20%3A%3C%20%272021-09-18T15%3A00%3A00Z%27' |
Update Custom Object Record
This API updates the value of the given fields of a record in a Custom object.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X PUT -d '{ "data": { "category_dd1": "Hardware", "category_dd2": "Computer", "category_dd3": "Mac", "item_name": "1011125282" } }' 'https://domain.freshservice.com/api/v2/objects/1000040838/records/1' |
Delete Custom Object Record
This API deletes an existing record in a Custom object.
1 | curl -v -u api_key:X -X DELETE 'https://domain.freshservice.com/api/v2/objects/1000040838/records/1’ |
SLA Policies
SLA Policies can be used by IT Teams to set Resolution and Response targets for all incoming Tickets. They are particularly useful in standardizing Service desk functions and boosting efficiency.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the SLA Policy |
workspace_id | number | ID of the workspace to which the SLA policy belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
name | string | Name of the SLA Policy |
position | number | Position / Rank of the SLA Policy among other SLA Policies |
is_default | boolean | True for Default SLA. False otherwise |
active | boolean | True if activated. False otherwise |
deleted | boolean | True if deleted. False otherwise |
description | string | Short description of the SLA Policy |
sla_targets[].priority | number | Priority for which the sla_target should be applied |
sla_targets[].escalation_enabled | boolean | True if escalation is enabled. False otherwise |
sla_targets[].business_hours | boolean | True if the target should follow business hours. False if the target should follow calendar hours |
sla_targets[].respond_within | number | First Response Target in seconds |
sla_targets[].resolve_within | number | Resolution Target in seconds |
applicable_to.ticket_type | array of strings | Specifies which Ticket types this SLA Policy should apply to |
applicable_to.service_items | array of numbers | Specifies which Service items this SLA Policy should apply to |
applicable_to.service_categories | array of numbers | Specifies which Service Categories this SLA Policy should apply to |
applicable_to.department_id | array of numbers | Specifies which Departments this SLA Policy should apply to |
applicable_to.group_id | array of numbers | Specifies which Groups this SLA Policy should apply to. |
applicable_to.source | array of numbers | Specifies which Ticket Sources this SLA Policy should apply to |
applicable_to.category | string | Specifies which Category this SLA Policy should apply to |
applicable_to.sub_category | string | Specifies which Subcategory this SLA Policy should apply to |
applicable_to.item_category | string | Specifies which Item Category this SLA Policy should apply to |
escalation.response.level escalation.resolution[].level | string | Level / hierarchy of escalation |
escalation.response.escalation_when escalation.resolution[].escalation_when | string | When to escalate - Takes “before”, “immediately”, “after” (Before the Ticket breaches, right when the Ticket breaches, After the Ticket breaches) |
escalation.response.escalation_time escalation.resolution[].escalation_time | number | How long until escalation. Takes values in seconds. Applicable for “before” and “after” escaltion_when values |
escalation.response.agent_ids escalation.resolution[].agent_ids | array of numbers | Ids of Agents to whom escalation should be triggered. For escalating to agent assigned to the Ticket, specify -1 |
escalation.response.group_ids escalation.resolution[].group_ids | array of numbers | Ids of Agent Groups to whom escalation should be triggered. |
View List of SLAs
This API helps to view all time entries of a particular ticket.
Note:
By default, only SLA policies from the primary workspace will be returned for accounts on the Employee Support Mode. For SLA Policies from other workspaces, use the workspace_id filter.
Filter by | Handle |
---|---|
Workspace | /api/v2/sla_policies?workspace_id=[id] 'workspace_id' is applicable only for accounts on the Employee Support Mode. The value 1 for workspace_id will return all global SLA policies |
1 | curl -v -u api_key:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/sla_policies?workspace_id=2' |
Canned Response Folders
This section lists all APIs related to Canned Response Folders.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the Canned Response FolderRead-Only |
workspace_id | number | ID of the workspace to which the canned response folder belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
name | string | Title of the Canned Response Folder |
type | string | Type of the Canned Response FolderRead-Only |
responses_count | string | No of Canned Responses in this folderRead-Only |
created_at | datetime | Canned Response Folder creation timestamp |
updated_at | datetime | Canned Response Folder updated timestamp |
View List of Canned Response Folders
This API lists all the canned response folders that are present in the account.
Note:
By default, only canned response folders from the primary workspace will be returned for accounts on the Employee Support Mode. For canned response folders from other workspaces, use the workspace_id filter.
Filter by | Handle |
---|---|
Workspace | /api/v2/canned_response_folders?workspace_id=[id] 'workspace_id' is applicable only for accounts on the Employee Support Mode. |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/canned_response_folders?workspace_id=2' |
Show a Canned Response Folder
This API show a specific Canned Response
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/canned_response_folders/122' |
List all Canned Responses In a Folder
This API lists all the Canned Response Folders that are present in the folder.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/canned_response_folders/122/canned_responses' |
Canned Responses
This section lists all APIs related to Canned Responses.
Attribute | Type | Description |
---|---|---|
id | number | Unique identifier of the Canned ResponseRead-Only |
workspace_id | number | ID of the workspace to which the canned response belongs. This attribute is applicable only to accounts on the Employee Support Mode. |
title | string | Title of the Canned Response FolderMandatory |
folder_id | number | ID of the Canned Response Folder in which the response is associated |
content | string | Content of the Canned Response |
content_html | string | Content of the Canned Response in HTML formatMandatory |
created_at | datetime | Canned Response Folder creation timestamp |
updated_at | datetime | Canned Response Folder updated timestamp |
View List of Canned Responses
This API lists all the canned responses that are present in the folder.
Note:
By default, only canned responses from the primary workspace will be returned for accounts on the Employee Support Mode. For canned responses from other workspaces, use the workspace_id filter.
Filter by | Handle |
---|---|
Workspace | /api/v2/canned_responses?workspace_id=[id] 'workspace_id' is applicable only for accounts on the Employee Support Mode. The value 1 for workspace_id will return all global canned responses |
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/canned_responses?workspace_id=2' |
Show a Canned Response
This API show a specific Canned Response
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/canned_responses/122' |
Audit Logs
Audit log keeps track of all the changes that take place under the Admin section of your service desk.
Note:
Only users with "Play God with Admin controls" privilege can access the following APIs.
Attribute | Type | Description |
---|---|---|
since * | datetime | Timestamp from which the logs are needed |
before * | datetime | Timestamp to which the logs are needed |
type | array of strings | Denotes the type of module (Examples workflow,sla_policy,sandbox_job..) |
actor | number | Id of the agent who performed the changes |
workflow_id | number | Id of the workflow |
sla_policy_id | number | Id of the sla policy |
change_lifecycle_id | number | Id of the change lifecycle |
group_id | number | ID of the group |
agent_id | number | Id of the agent |
Audit Log Export
This API helps to export the changes made inside your service desk.
Note:
Type should be one of the following values.
account, agent, group, change_field, change_lifecycle, sandbox_job, sla_policy, workflow, plans & billing.
If a workspace_id is not specified in the request parameter or specified as 0, logs from the workspace to which the user has access will be included in the response. If workspace_id is specified as 1, only the audit log entires that correspond to global settings will be included in the response. Applicable only to accounts on the Employee Support Mode.
1 | curl -v -u api_key:X -H "Content-Type: application/json" -d '{ "since": "2021-12-10T00:00:00Z", "before": "2022-02-23T00:00:00Z" }' -X POST 'https://domain.freshservice.com/api/v2/audit_log/export' |
1. Export the workflow module related changes
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -d '{ "since": "2021-07-23T00:00:00+5:30","before": "2021-09-27T00:00:00+5:30","filters": {"type": ["workflow"],"workflow_id": 5}}' -X POST 'https://domain.freshservice.com/api/v2/audit_log/export' |
2. Export the workflow module related changes done by a particular agent
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -d '{ "since": "2021-07-23T00:00:00+5:30","before": "2021-09-27T00:00:00+5:30","filters": {"type": ["workflow"],"workflow_id": 5, "actor": 8 }}' -X POST 'https://domain.freshservice.com/api/v2/audit_log/export' |
3. Export the change lifecycle management related changes
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -d '{ "since": "2021-07-23T00:00:00+5:30","before": "2021-09-27T00:00:00+5:30","filters": {"type": ["change_field", "change_lifecycle"],"change_lifecycle_id:": 15, "actor": 8 }}' -X POST 'https://domain.freshservice.com/api/v2/audit_log/export' |
4. Export the sandbox related changes
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -d '{ "since": "2021-07-23T00:00:00+5:30","before": "2021-09-27T00:00:00+5:30","filters": {"type": ["sandbox_job"], "actor": 8 }}' -X POST 'https://domain.freshservice.com/api/v2/audit_log/export' |
5. Export all the changes done by a particular agent in a particular workspace
1 | curl -v -u api_key:X -H 'Content-Type: application/json' -d '{ "since": "2021-07-23T00:00:00+5:30","before": "2021-09-27T00:00:00+5:30","filters": {"actor": 8, "workspace_display_id": 2 }}' -X POST 'https://domain.freshservice.com/api/v2/audit_log/export' |
Attachment
This API helps you download the attachments.
Note:
Attachment downloads are supported for the following entities - Tickets, Problems, Changes, Releases, Solution Articles, Purchase Orders, Contracts and Assets.
API users with access to the parent entity of the attachment can download it.
Download Attachment
This API helps you to download attachments of Ticket, Problem, Change, Release, Solution Article and Asset.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/attachments/1' |
Download Purchase order and Contracts Attachment
This API helps you to download attachments of Purchase order and Contract.
1 | curl -v -u api_key:X -X GET 'https://domain.freshservice.com/api/v2/itil_attachments/1' |