freshdesk-api

Freshdesk API

Overview

Build integrations with Freshdesk's helpdesk platform using their REST API v2. Manage support tickets, contacts, companies, agents, and automate workflows. The API supports full CRUD operations on all major resources with filtering, pagination, and embedded data.

When to Use

• Building helpdesk integrations or support dashboards
• Extracting and analyzing support ticket data
• Automating ticket routing, assignment, or updates
• Syncing contacts/companies with CRM systems
• Creating custom reporting on support metrics
• Implementing chatbots or AI-powered support tools
• Migrating data to/from Freshdesk

Prerequisites

API Key Setup

1. Log into Freshdesk as an Admin
2. Click your profile picture → Profile Settings
3. Find your API Key on the right sidebar
4. Store securely (never commit to version control)

# Set environment variable
export FRESHDESK_API_KEY="your-api-key-here"
export FRESHDESK_DOMAIN="yourcompany"  # From yourcompany.freshdesk.com

Required Tools

• curl for HTTP requests
• jq for JSON parsing (brew install jq on macOS)
• For SDKs: Python 3.6+, Node.js 14+, or Ruby 2.7+

API Base URL

https://{domain}.freshdesk.com/api/v2/

Replace {domain} with your Freshdesk subdomain (e.g., acme for acme.freshdesk.com).

Authentication

Freshdesk uses HTTP Basic Authentication with your API key as the username and X as the password.

curl Example

# Using -u flag (username:password)
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

# Using Authorization header
curl -H "Authorization: Basic $(echo -n "$FRESHDESK_API_KEY:X" | base64)" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

Headers

Always include:

Content-Type: application/json

Quick Start

Get All Tickets

curl -u "$FRESHDESK_API_KEY:X" \
  -H "Content-Type: application/json" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

Create a Ticket

curl -u "$FRESHDESK_API_KEY:X" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "subject": "Support needed",
    "description": "Details of the issue...",
    "email": "[email protected]",
    "priority": 2,
    "status": 2
  }' \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets"

Get a Contact

curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/contacts/12345"

Search Tickets

# Search by status and priority
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"status:2 AND priority:3\""

Core Endpoints

Endpoint	Description
/tickets	Create, list, update, delete tickets
/contacts	Manage customer contacts
/companies	Manage company/organization records
/agents	View and manage support agents
/groups	Manage agent groups
/conversations	Ticket replies, notes, forwards
/time_entries	Time tracking on tickets
/surveys/satisfaction_ratings	Customer satisfaction data
/products	Product catalog management
/business_hours	Business hours configuration
/email_configs	Email settings
/sla_policies	SLA policy management
/canned_responses	Pre-defined response templates
/ticket_fields	Custom ticket fields

See references/tickets-api.md for detailed ticket operations. See references/contacts-companies.md for contact/company management.

Rate Limits

Limits by API Version

Version	Limit
API v1	1000 calls/hour
API v2	Per-minute, plan-based
Trial Plans	50 calls/minute

Rate Limit Headers

Every response includes:

Header	Description
X-Ratelimit-Total	Total calls allowed per minute
X-Ratelimit-Remaining	Calls remaining this minute
X-Ratelimit-Used-CurrentRequest	Credits used by this request

Handling Rate Limits

#!/usr/bin/env bash
# Retry with exponential backoff for 429 errors

max_retries=3
retry_count=0

while [ "$retry_count" -lt "$max_retries" ]; do
  response=$(curl -s -w "\n%{http_code}" -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets")

  http_code=$(echo "$response" | tail -1)
  body=$(echo "$response" | sed '$d')

  if [ "$http_code" = "200" ]; then
    echo "$body"
    exit 0
  elif [ "$http_code" = "429" ]; then
    delay=$((2 ** retry_count))
    echo "Rate limited. Retrying in ${delay}s..." >&2
    sleep "$delay"
    retry_count=$((retry_count + 1))
  else
    echo "Error: HTTP $http_code" >&2
    echo "$body" >&2
    exit 1
  fi
done

echo "Max retries exceeded" >&2
exit 1

Credit System

Some operations consume multiple API credits:

• Basic request: 1 credit
• Including embedded data (include= parameter): +1 credit per include
• Example: ?include=requester,company costs 3 credits total

Pagination

Query Parameters

Parameter	Default	Max	Description
page	1	-	Page number (1-indexed)
per_page	30	100	Results per page

Example: Paginate Through All Tickets

page=1
while true; do
  response=$(curl -s -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?page=$page&per_page=100")

  count=$(echo "$response" | jq length)

  if [ "$count" -eq 0 ]; then
    break
  fi

  echo "$response" | jq '.[] | {id, subject, status}'
  page=$((page + 1))
done

Link Header

Responses include a Link header for navigation:

Link: <https://domain.freshdesk.com/api/v2/tickets?page=2>; rel="next"

Filtering and Embedding

Filter Parameters

Common filters available on list endpoints:

Parameter	Example	Description
filter	new_and_my_open	Pre-defined filter
requester_id	12345	Filter by requester
company_id	67890	Filter by company
updated_since	2024-01-01T00:00:00Z	Modified after date

Pre-defined Ticket Filters

# New and open tickets assigned to me
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?filter=new_and_my_open"

# All unresolved tickets
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?filter=all_unresolved"

# Tickets updated in last 30 days
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?updated_since=2024-11-01T00:00:00Z"

Include (Embedding Related Data)

Embed related objects to reduce API calls:

# Include requester and company with ticket
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets/123?include=requester,company"

# Include stats with ticket list
curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?include=stats"

Available includes for tickets: requester, company, stats, conversations, description

Search API

The Search API enables complex queries across tickets, contacts, and companies.

Syntax

curl -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"<query>\""

Query Examples

# Tickets with specific status and priority
"status:2 AND priority:3"

# Tickets from a specific requester
"requester_email:'[email protected]'"

# Tickets created in date range
"created_at:>'2024-01-01' AND created_at:<'2024-02-01'"

# Tickets with specific tag
"tag:'urgent'"

# Tickets assigned to specific agent
"agent_id:12345"

# Full-text search in subject and description
"~'password reset'"

Search Operators

Operator	Description
AND	Both conditions must match
OR	Either condition matches
:	Equals
:>	Greater than
:<	Less than
~	Full-text search

Ticket Status and Priority Values

Status

Value	Status
2	Open
3	Pending
4	Resolved
5	Closed

Priority

Value	Priority
1	Low
2	Medium
3	High
4	Urgent

Source

Value	Source
1	Email
2	Portal
3	Phone
7	Chat
8	Mobihelp
9	Feedback Widget
10	Outbound Email

Error Handling

HTTP Status Codes

Code	Meaning	Action
200	Success	Process response
201	Created	Resource created successfully
204	No Content	Delete successful
400	Bad Request	Check request body/params
401	Unauthorized	Verify API key
403	Forbidden	Check permissions
404	Not Found	Verify resource ID
409	Conflict	Resource already exists
429	Rate Limited	Wait and retry
500	Server Error	Retry with backoff

Error Response Format

{
  "description": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "It should be a valid email address.",
      "code": "invalid_value"
    }
  ]
}

Webhooks

Freshdesk can send webhook notifications on ticket events. Configure webhooks in Admin → Automations → Webhooks.

Event Types

• Ticket created
• Ticket updated
• Agent reply
• Customer reply
• Note added
• Ticket resolved/closed

Webhook Payload Example

{
  "freshdesk_webhook": {
    "ticket_id": 12345,
    "ticket_subject": "Support needed",
    "ticket_status": "Open",
    "ticket_priority": "Medium",
    "ticket_requester_email": "[email protected]",
    "triggered_event": "ticket_created"
  }
}

See references/webhooks-automation.md for detailed webhook setup.

Best Practices

Performance

1. Use webhooks instead of polling - React to events in real-time
2. Batch operations - Use bulk endpoints when available
3. Cache static data - Agent lists, ticket fields rarely change
4. Use include parameter - Reduce API calls by embedding data
5. Paginate efficiently - Use max per_page=100 for bulk operations

Security

1. Store API keys in environment variables - Never hardcode
2. Use HTTPS only - All API calls must use HTTPS
3. Rotate keys periodically - Regenerate API keys every 90 days
4. Limit API key scope - Use agent accounts with minimal permissions

Reliability

1. Implement retry with backoff - Handle 429 and 5xx errors
2. Check rate limit headers - Pause before hitting limits
3. Validate responses - Check for error objects
4. Log API calls - Track usage and debug issues

Data Handling

1. Handle null fields - API returns nulls, not omitted fields
2. Parse timestamps as UTC - Format: YYYY-MM-DDTHH:MM:SSZ
3. Validate custom fields - Check field types before submission
4. Sanitize user input - Prevent injection in descriptions

SDKs and Libraries

Official/Community SDKs

Language	Package	Install
Python	python-freshdesk	pip install python-freshdesk
Node.js	node-freshdesk-api	npm install node-freshdesk-api
Ruby	freshdesk-ruby	gem install freshdesk
PHP	Official samples	See Freshdesk docs
Java	Official samples	See Freshdesk docs

See references/sdk-examples.md for detailed code examples.

Common Workflows

Export All Tickets to JSON

#!/usr/bin/env bash
# Export all tickets to tickets.json

page=1
echo "[" > tickets.json
first=true

while true; do
  response=$(curl -s -u "$FRESHDESK_API_KEY:X" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?page=$page&per_page=100&include=description")

  count=$(echo "$response" | jq length)
  [ "$count" -eq 0 ] && break

  if [ "$first" = true ]; then
    first=false
  else
    echo "," >> tickets.json
  fi

  echo "$response" | jq '.[]' | paste -sd ',' - >> tickets.json
  page=$((page + 1))
  sleep 0.5  # Respect rate limits
done

echo "]" >> tickets.json
echo "Exported $((page - 1)) pages of tickets"

Sync Contacts from CSV

#!/usr/bin/env bash
# Import contacts from contacts.csv (name,email,company_id)

while IFS=, read -r name email company_id; do
  curl -s -u "$FRESHDESK_API_KEY:X" \
    -H "Content-Type: application/json" \
    -X POST \
    -d "{\"name\":\"$name\",\"email\":\"$email\",\"company_id\":$company_id}" \
    "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/contacts"
  sleep 0.5
done < contacts.csv

Get Ticket Metrics

# Get resolution time stats for closed tickets this month
curl -s -u "$FRESHDESK_API_KEY:X" \
  "https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/search/tickets?query=\"status:5 AND created_at:>'2024-12-01'\"" \
  | jq '[.results[] | .stats.resolved_at as $r | .created_at as $c |
    (($r | fromdateiso8601) - ($c | fromdateiso8601)) / 3600] |
    {count: length, avg_hours: (add / length)}'

Resources

• Freshdesk API Documentation
• API v2 Reference
• Webhooks Guide
• Rate Limits FAQ
• Python SDK
• Node.js SDK
• Ruby SDK

Reference Files

For detailed endpoint documentation:

• Tickets API Reference - Full ticket CRUD, conversations, time entries
• Contacts & Companies - Contact/company management
• Webhooks & Automation - Webhook setup and automation rules
• SDK Code Examples - Python, Node.js, Ruby examples