The Freshservice API is a robust RESTful interface that enables IT teams to automate tasks, streamline service management, and integrate with critical business systems. Communicating via JSON over standard HTTP methods (GET, POST, PUT, DELETE), it allows for seamless data exchange across departments like HR, finance, and IT.
With access to tickets, users, assets, and departments, the API reduces manual workload and human error while ensuring secure interactions via HTTPS and role-based access controls. CORS support simplifies building web apps that directly interface with Freshservice, and the v2 API version delivers improved performance for enterprise-scale automation.
By mastering the Freshservice API, teams can build scalable, ITIL-aligned integrations that adapt to unique business needs. In this article, we’ll walk through everything from setup and core functionality to advanced techniques, error handling, and best practices for optimizing your Freshservice API experience.
Getting Started with Freshservice API#
The Freshservice API documentation serves as your comprehensive guide, detailing all available endpoints, authentication methods, and data formats. Before diving into development, take time to review the documentation, paying particular attention to rate limits and error handling practices.
Setting Up Your Development Environment#
To begin working with the Freshservice API, follow these essential steps:
- Obtain API Credentials: Access your Freshservice profile settings to generate an API key.
- Choose a Development Tool: Select appropriate tools for API interaction:
- cURL for command-line testing
- Postman for interactive exploration
- Language-specific libraries (Python Requests, JavaScript Axios)
- Use an API mocking tool to simulate API responses during development
- Configure Authentication: Your first API request requires proper authentication headers. Here's how to set up a basic authentication header with your API key:
const apiKey = 'your_api_key_here';
const encodedKey = Buffer.from(apiKey + ':X').toString('base64');
fetch('https://yourdomain.freshservice.com/api/v2/tickets', {
method: 'GET',
headers: {
'Authorization': `Basic ${encodedKey}`,
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data));- Implement Rate Limit Handling: Freshservice imposes API call limits to ensure service stability. The following code demonstrates how to handle rate limiting with exponential backoff:
async function makeRequestWithRetry(url, options, maxRetries = 3) {
let retries = 0;
while (retries < maxRetries) {
try {
const response = await fetch(url, options);
if (response.status !== 429) {
return response.json();
}
// Calculate exponential backoff delay
const delay = Math.pow(2, retries) * 1000;
console.log(`Rate limited. Retrying in ${delay}ms...`);
await new Promise(resolve => setTimeout(resolve, delay));
retries++;
} catch (error) {
console.error('API request failed:', error);
throw error;
}
}
throw new Error('Maximum retries reached');
}- This retry mechanism dynamically adjusts wait times between attempts, preventing your application from overwhelming the API during high-traffic periods.
For a detailed tutorial on rate limiting APIs in Node.js, refer to this API rate limiting tutorial.
Core Functionality and Commands of Freshservice API#
The Freshservice API follows standard REST principles, providing a consistent interface for interacting with service desk data.
HTTP Verbs and Endpoints#
The API supports four primary HTTP methods, each corresponding to specific operations:
- GET: Retrieve data from endpoints
- POST: Create new resources
- PUT: Update existing resources
- DELETE: Remove resources
These methods combine with endpoints to perform specific operations. Here's how to retrieve all tickets using the tickets endpoint:
// Fetch all tickets
fetch('https://yourdomain.freshservice.com/api/v2/tickets', {
method: 'GET',
headers: {
'Authorization': 'Basic ' + btoa('your_api_key:X'),
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data.tickets));To create a new ticket, you would use the same endpoint with the POST method and include ticket details in the request body:
// Create a new ticket
fetch('https://yourdomain.freshservice.com/api/v2/tickets', {
method: 'POST',
headers: {
'Authorization': 'Basic ' + btoa('your_api_key:X'),
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'requester@example.com',
subject: 'New laptop request',
description: 'I need a new laptop for the upcoming project',
priority: 2,
status: 2
})
})
.then(response => response.json())
.then(data => console.log(data));Commonly Used Endpoints#
The Freshservice API offers numerous endpoints for different service management functions:
/tickets: Manage support tickets and their various properties/users: Handle user accounts, groups, and requester data/assets: Track and manage IT assets throughout their lifecycle/departments: Organize company structure and manage departmental assignments/changes: Control change management processes and approval workflows
Each endpoint supports different operations depending on the HTTP verb used, allowing for flexible interaction with your service desk data. Utilizing an API gateway can simplify and enhance API management; learn about the advantages of a hosted API gateway.
Authentication and Security in Freshservice API#
Secure integration with Freshservice API requires implementing robust authentication and following security best practices. As of May 2023, API authentication options have evolved, with newer methods replacing legacy approaches.
Authentication Methods#
The primary authentication method is API Key authentication. Here's how to implement it correctly:
// API Key Authentication Example
const apiKey = 'your_api_key_here';
const encodedCredentials = Buffer.from(apiKey + ':X').toString('base64');
fetch('https://yourdomain.freshservice.com/api/v2/tickets', {
method: 'GET',
headers: {
'Authorization': `Basic ${encodedCredentials}`,
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));To understand different authentication options, you can compare API authentication methods.
For applications requiring user context, OAuth 2.0 authentication is available. This approach is particularly valuable for marketplace applications that need to act on behalf of specific users without handling their credentials directly.
For more tips and best practices, see API authentication methods.
Freshservice API Security Best Practices#
When working with the Freshservice API, follow these essential security practices:
- Protect API Keys: Store keys in environment variables or secure vaults rather than hardcoding them in application code.
- Implement TLS/HTTPS: Ensure all API communications use encrypted connections - the API only accepts HTTPS requests.
- Apply Least Privilege: Restrict API key permissions to only what's necessary for your specific integration requirements.
- Rotate Keys Regularly: Establish a schedule for changing API keys to limit exposure in case of compromise.
- Validate Input Data: Before sending data to the API, implement thorough validation to prevent injection attacks:
// Simple input validation example
function validateTicketData(ticketData) {
const requiredFields = ['subject', 'description', 'email'];
for (const field of requiredFields) {
if (!ticketData[field]) {
throw new Error(`Missing required field: ${field}`);
}
}
// Validate email format
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(ticketData.email)) {
throw new Error('Invalid email format');
}
return true;
}Implementing these security measures helps protect sensitive service desk data while ensuring your integrations remain reliable and compliant with organizational security policies.
Advanced Integration Techniques with Freshservice API#
For complex IT environments, optimizing API performance becomes critical. Two powerful techniques – resource embedding and batch processing – can significantly enhance integration efficiency.
Resource Embedding#
Resource embedding allows retrieving related data in a single API call, reducing network overhead and simplifying code. Here's how to implement embedding to retrieve tickets along with requester details:
// Fetch tickets with embedded requester data
fetch('https://yourdomain.freshservice.com/api/v2/tickets?include=requester', {
method: 'GET',
headers: {
'Authorization': 'Basic ' + btoa('your_api_key:X'),
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(data => {
// Access ticket and requester data from a single request
data.tickets.forEach(ticket => {
console.log(`Ticket #${ticket.id}: ${ticket.subject}`);
console.log(`Requester: ${ticket.requester.name} (${ticket.requester.email})`);
});
});This approach eliminates the need for separate requester lookups, improving performance and reducing API call volume.
Error Handling and Troubleshooting in Freshservice API#
Effective error handling is essential for building robust Freshservice API integrations. Understanding common error codes and implementing proper error management ensures your applications remain resilient during API interactions.
Common Freshservice API Error Codes#
When working with the Freshservice API, you'll encounter these standard HTTP status codes:
- 401 Unauthorized: Authentication failed due to invalid or missing credentials
- 400 Bad Request: Request contains invalid parameters or malformed data
- 403 Forbidden: Authentication succeeded but permissions are insufficient
- 404 Not Found: Requested resource doesn't exist
- 429 Too Many Requests: Rate limit exceeded
If you encounter rate limit exceeded errors, here's how to fix rate limit exceeded errors.
Here's a comprehensive error handling implementation that addresses these scenarios:
async function callFreshserviceAPI(endpoint, method = 'GET', body = null) {
const apiKey = process.env.FRESHSERVICE_API_KEY;
const domain = process.env.FRESHSERVICE_DOMAIN;
const url = `https://${domain}.freshservice.com/api/v2/${endpoint}`;
const options = {
method,
headers: {
'Authorization': 'Basic ' + Buffer.from(apiKey + ':X').toString('base64'),
'Content-Type': 'application/json'
}
};
if (body && (method === 'POST' || method === 'PUT')) {
options.body = JSON.stringify(body);
}
try {
const response = await fetch(url, options);
// Handle different status codes
switch (response.status) {
case 200:
case 201:
return await response.json();
case 401:
throw new Error('Authentication failed. Check API key.');
case 403:
throw new Error('Permission denied. Insufficient access rights.');
case 404:
throw new Error(`Resource not found: ${endpoint}`);
case 429:
// Implement retry with exponential backoff
console.log('Rate limit exceeded. Implementing backoff...');
const retryAfter = response.headers.get('Retry-After') || 60;
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
return callFreshserviceAPI(endpoint, method, body); // Recursive retry
default:
const errorData = await response.json();
throw new Error(`API Error: ${errorData.message || response.statusText}`);
}
} catch (error) {
console.error('Freshservice API Error:', error.message);
throw error;
}
}This function provides comprehensive error handling with automatic retry logic for rate limiting, making your integrations more resilient to transient issues.
Freshservice Pricing#
Freshservice offers multiple pricing tiers designed to accommodate organizations of various sizes and complexity requirements. Each tier provides progressively more advanced features and capabilities.
Starter#
Ideal for small teams beginning their ITSM journey:
- Basic incident management
- Knowledge base functionality
- Self-service portal
- Asset discovery and management
- Limited automation capabilities
Growth#
Designed for growing organizations with more complex IT needs:
- Advanced incident management
- Problem management
- Change management
- Release management
- Basic SLA management
- Expanded automation options
- Customizable self-service portal
Pro#
Built for larger organizations requiring comprehensive ITSM solutions:
- All Growth tier features
- Advanced SLA management
- Project management
- Advanced analytics and reporting
- Customizable dashboards
- Contract management
- Software license management
- Vendor management
Enterprise#
The most robust option for large-scale organizations:
- All Pro tier features
- Multi-site support
- Custom objects
- Audit logs
- IP whitelisting
- Advanced security features
- Dedicated account manager
- Custom API limits
API Access Across Tiers#
API access varies by pricing tier:
- Starter and Growth tiers have more restricted API call limits
- Pro and Enterprise tiers offer higher API call limits
- Enterprise tier provides custom API limits for specific organizational needs
When selecting a tier, consider your current API usage requirements and anticipated future needs, particularly if you plan to implement extensive automation or integration workflows. For full details on features, limitations, and API call limits by tier, refer to the official Freshservice pricing page or consult your Freshworks account representative.
Maximize Your Freshservice API Potential with Smarter Management#
The Freshservice API empowers IT teams to automate service workflows and integrate seamlessly with other business systems. By using features like resource embedding and batch processing, organizations can boost efficiency while meeting security and compliance standards.
A strong grasp of authentication, error handling, and data management is key to building resilient, scalable integrations. Developers should also understand API definitions to streamline development—check out our API definitions guide for more.
As Freshservice expands with AI, IoT, and deeper analytics support, staying up to date with API documentation is essential to maximizing its value.
To go beyond the basics, consider Zuplo for advanced API management. With features like request validation, intelligent rate limiting, and real-time monitoring, Zuplo helps teams secure and optimize Freshservice APIs—making them enterprise-ready and future-proof. Try Zuplo for free today!
