freshdesk-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

使用Freshdesk的REST API v2与他们的帮助台平台构建集成。管理支持工单、联系人、公司、坐席，并自动化工作流。该API支持对所有主要资源进行完整的CRUD操作，同时提供过滤、分页和嵌入数据功能。

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

构建帮助台集成或支持仪表板
提取和分析支持工单数据
自动化工单路由、分配或更新
将联系人/公司与CRM系统同步
创建支持指标的自定义报表
实现聊天机器人或AI驱动的支持工具
在Freshdesk之间迁移数据

Prerequisites

前提条件

API Key Setup

API密钥设置

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

bash

undefined

以管理员身份登录Freshdesk
点击您的头像 → 个人资料设置
在右侧边栏找到您的API密钥
安全存储（绝不要提交到版本控制系统）

bash

undefined

Set environment variable

设置环境变量

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

undefined

export FRESHDESK_API_KEY="your-api-key-here" export FRESHDESK_DOMAIN="yourcompany" # 来自yourcompany.freshdesk.com

undefined

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+

```
curl
```
用于HTTP请求
```
jq
```
用于JSON解析（macOS上使用
```
brew install jq
```
安装）
对于SDK：Python 3.6+、Node.js 14+ 或 Ruby 2.7+

API Base URL

API基础URL

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

Replace

{domain}

with your Freshdesk subdomain (e.g.,

acme

for

acme.freshdesk.com

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

将

{domain}

替换为您的Freshdesk子域名（例如，

acme

对应

acme.freshdesk.com

）。

Authentication

身份验证

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

as the password.

Freshdesk使用HTTP基本身份验证，您的API密钥作为用户名，

作为密码。

curl Example

curl示例

bash

undefined

bash

undefined

Using -u flag (username:password)

使用-u标志（用户名:密码）

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

Using Authorization header

使用Authorization头

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

undefined

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

undefined

Headers

请求头

Always include:

Content-Type: application/json

始终包含：

Content-Type: application/json

Quick Start

快速开始

Get All Tickets

获取所有工单

bash

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

bash

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

Create a Ticket

创建工单

bash

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

bash

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

Get a Contact

获取联系人

bash

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

bash

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

Search Tickets

搜索工单

bash

undefined

bash

undefined

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""

undefined

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

undefined

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.

端点	描述
`/tickets`	创建、列出、更新、删除工单
`/contacts`	管理客户联系人
`/companies`	管理公司/组织记录
`/agents`	查看和管理支持坐席
`/groups`	管理坐席组
`/conversations`	工单回复、备注、转发
`/time_entries`	工单时间跟踪
`/surveys/satisfaction_ratings`	客户满意度数据
`/products`	产品目录管理
`/business_hours`	营业时间配置
`/email_configs`	邮件设置
`/sla_policies`	SLA策略管理
`/canned_responses`	预定义回复模板
`/ticket_fields`	自定义工单字段

查看references/tickets-api.md获取详细的工单操作说明。查看references/contacts-companies.md获取联系人/公司管理说明。

Rate Limits

速率限制

Limits by API Version

按API版本划分的限制

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

版本	限制
API v1	1000次调用/小时
API v2	基于套餐的每分钟限制
试用套餐	50次调用/分钟

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

每个响应都包含以下头信息：

头信息	描述
`X-Ratelimit-Total`	每分钟允许的总调用次数
`X-Ratelimit-Remaining`	本分钟剩余的调用次数
`X-Ratelimit-Used-CurrentRequest`	当前请求消耗的额度

Handling Rate Limits

处理速率限制

bash

#!/usr/bin/env bash

bash

#!/usr/bin/env bash

Retry with exponential backoff for 429 errors

遇到429错误时使用指数退避重试

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

undefined

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

echo "Max retries exceeded" >&2 exit 1

undefined

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

某些操作会消耗多个API额度：

基础请求：1个额度
包含嵌入数据（
```
include=
```
参数）：每个嵌入额外消耗1个额度
示例：
```
?include=requester,company
```
总共消耗3个额度

Pagination

分页

Query Parameters

查询参数

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

参数	默认值	最大值	描述
`page`	1	-	页码（从1开始）
`per_page`	30	100	每页结果数

Example: Paginate Through All Tickets

示例：遍历所有工单

bash

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

bash

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

Link响应头

Responses include a

Link

header for navigation:

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

响应包含

Link

头用于导航：

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

列表端点支持的常用过滤器：

参数	示例	描述
`filter`	`new_and_my_open`	预定义过滤器
`requester_id`	`12345`	按请求者过滤
`company_id`	`67890`	按公司过滤
`updated_since`	`2024-01-01T00:00:00Z`	按修改日期过滤（仅包含指定日期之后的记录）

Pre-defined Ticket Filters

预定义工单过滤器

bash

undefined

bash

undefined

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

过去30天内更新的工单

curl -u "$FRESHDESK_API_KEY:X"
"https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?updated_since=2024-11-01T00:00:00Z"

undefined

curl -u "$FRESHDESK_API_KEY:X"
"https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?updated_since=2024-11-01T00:00:00Z"

undefined

Include (Embedding Related Data)

包含（嵌入相关数据）

Embed related objects to reduce API calls:

bash

undefined

嵌入相关对象以减少API调用次数：

bash

undefined

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`

curl -u "$FRESHDESK_API_KEY:X"
"https://$FRESHDESK_DOMAIN.freshdesk.com/api/v2/tickets?include=stats"


**工单支持的嵌入项**：`requester`、`company`、`stats`、`conversations`、`description`

Search API

搜索API

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

搜索API允许对工单、联系人、公司进行复杂查询。

Syntax

语法

bash

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

bash

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

Query Examples

查询示例

bash

undefined

bash

undefined

Tickets with specific status and priority

按特定状态和优先级搜索工单

"status:2 AND priority:3"

Tickets from a specific requester

按特定请求者搜索工单

"requester_email:'customer@example.com'"

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

undefined

"~'password reset'"

undefined

Search Operators

搜索运算符

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

运算符	描述
`AND`	两个条件必须同时满足
`OR`	满足任一条件即可
`:`	等于
`:>`	大于
`:<`	小于
`~`	全文搜索

Ticket Status and Priority Values

工单状态与优先级值

Status

状态

Value	Status
2	Open
3	Pending
4	Resolved
5	Closed

值	状态
2	已打开
3	待处理
4	已解决
5	已关闭

Priority

优先级

Value	Priority
1	Low
2	Medium
3	High
4	Urgent

值	优先级
1	低
2	中
3	高
4	紧急

Source

来源

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

值	来源
1	邮件
2	门户
3	电话
7	聊天
8	Mobihelp
9	反馈小部件
10	外发邮件

Error Handling

错误处理

HTTP Status Codes

HTTP状态码

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

状态码	含义	操作
200	成功	处理响应
201	创建成功	资源已成功创建
204	无内容	删除操作成功
400	错误请求	检查请求体/参数
401	未授权	验证API密钥
403	禁止访问	检查权限
404	未找到	验证资源ID
409	冲突	资源已存在
429	速率限制	等待并重试
500	服务器错误	使用退避策略重试

Error Response Format

错误响应格式

json

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

json

{
  "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.

Freshdesk可以在工单事件发生时发送Webhook通知。在管理员→自动化→Webhooks中配置Webhooks。

Event Types

事件类型

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

工单创建
工单更新
坐席回复
客户回复
添加备注
工单解决/关闭

Webhook Payload Example

Webhook负载示例

json

{
  "freshdesk_webhook": {
    "ticket_id": 12345,
    "ticket_subject": "Support needed",
    "ticket_status": "Open",
    "ticket_priority": "Medium",
    "ticket_requester_email": "customer@example.com",
    "triggered_event": "ticket_created"
  }
}

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

json

{
  "freshdesk_webhook": {
    "ticket_id": 12345,
    "ticket_subject": "Support needed",
    "ticket_status": "Open",
    "ticket_priority": "Medium",
    "ticket_requester_email": "customer@example.com",
    "triggered_event": "ticket_created"
  }
}

查看references/webhooks-automation.md获取详细的Webhook设置说明。

Best Practices

最佳实践

Performance

性能

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

使用Webhooks替代轮询 - 实时响应事件
批量操作 - 尽可能使用批量端点
缓存静态数据 - 坐席列表、工单字段很少更改
使用
include
参数 - 通过嵌入数据减少API调用次数
高效分页 - 批量操作时使用最大
```
per_page=100
```

Security

安全性

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

将API密钥存储在环境变量中 - 绝不硬编码
仅使用HTTPS - 所有API调用必须使用HTTPS
定期轮换密钥 - 每90天重新生成API密钥
限制API密钥权限 - 使用权限最小的坐席账户

Reliability

可靠性

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

实现退避重试机制 - 处理429和5xx错误
检查速率限制头 - 在达到限制前暂停
验证响应 - 检查错误对象
记录API调用 - 跟踪使用情况并调试问题

Data Handling

数据处理

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

处理空字段 - API返回null而非省略字段
将时间戳解析为UTC - 格式：
```
YYYY-MM-DDTHH:MM:SSZ
```
验证自定义字段 - 提交前检查字段类型
清理用户输入 - 防止描述中的注入攻击

SDKs and Libraries

SDK与库

Official/Community SDKs

官方/社区SDK

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.

语言	包	安装命令
Python	`python-freshdesk`	`pip install python-freshdesk`
Node.js	`node-freshdesk-api`	`npm install node-freshdesk-api`
Ruby	`freshdesk-ruby`	`gem install freshdesk`
PHP	官方示例	查看Freshdesk文档
Java	官方示例	查看Freshdesk文档

查看references/sdk-examples.md获取详细代码示例。

Common Workflows

常见工作流

Export All Tickets to JSON

将所有工单导出为JSON

bash

#!/usr/bin/env bash

bash

#!/usr/bin/env bash

Export all tickets to tickets.json

将所有工单导出到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"

undefined

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 # 遵守速率限制 done

echo "]" >> tickets.json echo "已导出$((page - 1))页工单"

undefined

Sync Contacts from CSV

从CSV同步联系人

bash

#!/usr/bin/env bash

bash

#!/usr/bin/env bash

Import contacts from contacts.csv (name,email,company_id)

从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

undefined

undefined

Get Ticket Metrics

获取工单指标

bash

undefined

bash

undefined

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)}'

undefined

undefined

Resources

资源

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

如需详细的端点文档：

工单API参考 - 完整的工单CRUD、对话、时间条目
联系人与公司 - 联系人/公司管理
Webhooks与自动化 - Webhook设置和自动化规则
SDK代码示例 - Python、Node.js、Ruby示例