This document provides comprehensive information about the REST APIs available for:

• Freshservice (for IT & Business Teams) – A cloud-based IT Service Management (ITSM) solution that helps IT and Business teams to streamline service delivery within their own organization, with focus on user experience and employee satisfaction. The applicable APIs are tagged with “Freshservice”.
• Freshservice for MSPs – A purpose-built offering of Freshservice designed specifically for Managed Service Providers (MSPs) to manage service delivery across multiple external clients. The applicable APIs are tagged with “Freshservice for MSPs”.

These APIs follow the Representational State Transfer (REST) architecture and support standard CRUD (Create, Read, Update, Delete) operations. They enable seamless integration with your service desk and support Cross-Origin Resource Sharing (CORS), making them suitable for modern web-based applications.

For Freshservice for MSPs use slightly different terminology to represent similar concepts. The table below outlines these distinctions.

Some APIs differ between Freshservice and Freshservice for MSPs, both at the module and endpoint levels. Be sure to reference the specific API sections relevant to your use case.

Note: We recommend reviewing the callouts and notes throughout the documentation. These highlight key differences and important considerations when working with Freshservice and Freshservice for MSP APIs.

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 and Freshservice for MSPs?

Freshservice and Freshservice for MSPs APIs are plain JSON over HTTP and use the following HTTP verbs:

Note: Note: All API requests should hit the secured endpoint i.e. only HTTPS

Version 2 of the API brings several new features as well as changes to the previous APIs. This section highlights some of the new features introduced in v2.

1. Higher rate limits as a result of significant performance enhancements
2. Improved error handling - errors will return appropriate HTTP status codes and an error body
3. New APIs that enable you to Reply to a ticket and enhancements to existing APIs that enable you to Update a ticket's description, Update a ticket's notes, and Retrieve a list of tickets that have been recently modified
4. Only JSON is supported in V2
5. Only SSL calls (HTTPS) will be allowed
6. Works only via Freshservice domains and not via custom CNAMEs
7. Support for page sizes up to 100 has been added

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.

Note:
Freshservice for MSPs: For accounts on the Core plan, the rate limits for the Overall, Ticket, Agent, and Requester APIs are identical to those defined for the Growth plan above.

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

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

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.

• Introduced the Freshservice for MSPs product along with a set of APIs specific to its features.
• Introduced contextual notes and callouts to highlight key behavioral differences between Freshservice for MSPs and the existing Freshservice product.
• Introduced a Client module for Freshservice for MSPs. This module includes enhancements built on top of the existing workspace module available in Freshservice, with additional functionality exclusive to the MSP offering.
• Added a product selector dropdown to help developers identify which modules and corresponding APIs apply to Freshservice and Freshservice for MSPs. When building for both products, ensure that the APIs being used are supported by both, as not all APIs are universally applicable.
• API has been introduced to fetch all custom incident and maintenance statuses from the Status Page.
• The Status IDs from custom statuses can be used in incident and maintenance update APIs.

• Tickets and Changes API have been updated to introduce Groups and Chains in Approvals. This is to help create, edit, and manage Service Request and Change Approvals

• Users (Requesters) API has been updated with External ID. This represents the unique user identifier from identity providers like Okta and Azure AD and is used for identity mapping during SCIM sync.
• Locations API has been updated with email, phone and contact_name. This is to help viewing the contact attributes for locations.

• New API for OnCall Management has been introduced. This is to help export oncall calendar events by user, schedule, shift, and their combinations.

• New API for Status Page has been introduced. This is to help managing status pages, service components, incidents, scheduled maintenance, and associated updates.

• New APIs for Create a Component and Update a Component have been introduced to the Asset API.
• New API for Alert Management has been introduced. This is to help viewing, acknowledging, resolving, suppressing, and deleting alerts.

• Changes API has been updated with advanced filtering (query), predefined views (view), improved pagination, and sorting.
• user_field_groups has been introduced to List all Agent Fields and List all Requester Fields API responses.

• include has been introduced as query param in Purchase Orders list API response to show purchase_items and custom_fields.

• New APIs for Change Advisory Board have been introduced.
• custom_fields object has been introduced to View List of Changes API response.

• initiator_id has been added to Create an Onboarding Request and Create an Onboarding Request API to help admins raise offboarding requests on behalf of other users using initiator_id.
• Add Members API has been introduced to new-gen project management to enable bulk addition of members.
• New APIs for managing projects and tasks associations have been introduced.
• New APIs for notes and attachments associated with projects and tasks have been introduced.

• 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.
• On-Call Management APIs have been introduced for managing schedules and shifts, including creation, editing, deletion, and retrieval.

• Search Assets API response now includes sources that contributed to asset creation and updates. This helps track multiple sources.
• Employee Offboarding APIs have been introduced to streamline and automate the offboarding process.

• resolution_notes and resolution_notes_html have been included in the Create and Update API responses of tickets.
• Search Assets API response now includes source and user IDs to help track modifications. Following fields have been added: created_by_source, last_updated_by_source, created_by_user, last_updated_by_user.

• agent_workspace_visibilities has been added to Create Service Catalog item API response.

• 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

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

Before you can set the priority of a ticket or change a customer's name or use any of the APIs listed above, you need to "authenticate your ID" or "log in" in the same way you log in to your helpdesk's web portal.

You can use your personal API key to authenticate the request. If you use the API key, there is no need for a password. You can use any set of characters as a dummy password.

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

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

curl -v -u abcdefghij1234567890:X -H "Content-Type: application/json" -X GET 'https://domain.freshservice.com/api/v2/tickets'

Where can I find my API key?

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

Freshservice 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'

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.

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

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

Attachments are supported for the following endpoints

• Create a Ticket
• Update a Ticket
• Reply to a Ticket

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.