介绍
# Zoho Recruit
通过托管的 OAuth 身份验证访问 Zoho Recruit API。利用完整的 CRUD 操作管理候选人、职位空缺、面试、申请和招聘工作流程。
## 快速开始
```bash # List all candidates python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates?per_page=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/zoho-recruit/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Zoho Recruit API 端点路径。网关将请求代理到 `recruit.zoho.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 标头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取您的 API 密钥
1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Zoho Recruit OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-recruit&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'zoho-recruit'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "0c9fa9b1-80b6-4caa-afc2-8629fe4d9661", "status": "ACTIVE", "creation_time": "2026-02-06T07:48:59.474215Z", "last_updated_time": "2026-02-06T07:57:52.950167Z", "url": "https://connect.maton.ai/?session_token=...", "app": "zoho-recruit", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Zoho Recruit 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '0c9fa9b1-80b6-4caa-afc2-8629fe4d9661') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最早）的活动连接。
## API 参考
### 模块
#### 列出所有模块
获取您的 Zoho Recruit 账户中所有可用模块的列表。
```bash GET /zoho-recruit/recruit/v2/settings/modules ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/settings/modules') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 候选人
#### 列出候选人
```bash GET /zoho-recruit/recruit/v2/Candidates ```
**查询参数：**
| 参数 | 类型 | 默认值 | 描述 | |-----------|------|---------|-------------| | `fields` | string | - | 逗号分隔的字段 API 名称 | | `sort_order` | string | - | `asc` 或 `desc` | | `sort_by` | string | - | 用于排序的字段 API 名称 | | `converted` | string | - | `true`、`false` 或 `both` | | `approved` | string | - | `true`、`false` 或 `both` | | `page` | integer | 1 | 页码 | | `per_page` | integer | 200 | 每页记录数（最多 200） |
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates?per_page=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "id": "846336000000552208", "First_Name": "Christina", "Last_Name": "Palaskas", "Email": "[email protected]", "Candidate_Status": "Converted - Employee", "Current_Employer": "Chandlers", "Current_Job_Title": "Technical Consultant", "Experience_in_Years": 3, "Skill_Set": "Communication, Presentation, Customer service", "Candidate_Owner": { "name": "Byungkyu Park", "id": "846336000000549541" } } ], "info": { "per_page": 10, "count": 1, "page": 1, "more_records": false } } ```
#### 根据 ID 获取候选人
```bash GET /zoho-recruit/recruit/v2/Candidates/{record_id} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates/846336000000552208') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 搜索候选人
```bash GET /zoho-recruit/recruit/v2/Candidates/search?criteria={criteria} ```
**查询参数：**
| 参数 | 类型 | 描述 | |-----------|------|-------------| | `criteria` | string | 搜索条件（例如 `(Last_Name:contains:Smith)`）| | `email` | string | 按电子邮件搜索 | | `phone` | string | 按电话搜索 | | `word` | string | 全局字词搜索 | | `page` | integer | 页码 | | `per_page` | integer | 每页记录数 |
**搜索运算符：** - 文本：`equals`、`not_equal`、`starts_with`、`ends_with`、`contains`、`not_contains`、`in` - 日期/数字：`equals`、`not_equal`、`greater_than`、`less_than`、`greater_equal`、`less_equal`、`between`
**示例：**
```bash python <<'EOF' import urllib.request, os, json import urllib.parse criteria = urllib.parse.quote('(Candidate_Status:equals:Active)') req = urllib.request.Request(f'https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates/search?criteria={criteria}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 创建候选人
```bash POST /zoho-recruit/recruit/v2/Candidates Content-Type: application/json
{ "data": [ { "First_Name": "John", "Last_Name": "Doe", "Email": "[email protected]", "Phone": "555-123-4567", "Current_Job_Title": "Software Engineer" } ] } ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "data": [{ "First_Name": "John", "Last_Name": "Doe", "Email": "[email protected]", "Phone": "555-123-4567" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "code": "SUCCESS", "status": "success", "message": "record added", "details": { "id": "846336000000600001", "Created_Time": "2026-02-06T10:00:00-08:00", "Created_By": { "name": "User Name", "id": "846336000000549541" } } } ] } ```
#### 更新候选人
```bash PUT /zoho-recruit/recruit/v2/Candidates/{record_id} Content-Type: application/json
{ "data": [ { "Current_Job_Title": "Senior Software Engineer" } ] } ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "data": [{ "Current_Job_Title": "Senior Software Engineer" }] }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates/846336000000552208', data=data, method='PUT') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 删除候选人
```bash DELETE /zoho-recruit/recruit/v2/Candidates?ids={record_id1},{record_id2} ```
### 职位空缺
#### 列出职位空缺
```bash GET /zoho-recruit/recruit/v2/Job_Openings ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Job_Openings?per_page=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "data": [ { "id": "846336000000552093", "Posting_Title": "Senior Accountant (Sample)", "Job_Opening_Status": "Waiting for approval", "Date_Opened": "2026-01-21", "Target_Date": "2026-02-20", "Industry": "Accounting", "City": "Tallahassee", "No_of_Candidates_Hired": 0, "No_of_Candidates_Associated": 0 } ], "info": { "per_page": 10, "count": 1, "page": 1, "more_records": false } } ```
#### 根据 ID 获取职位空缺
```bash GET /zoho-recruit/recruit/v2/Job_Openings/{record_id} ```
#### 创建职位空缺
```bash POST /zoho-recruit/recruit/v2/Job_Openings Content-Type: application/json
{ "data": [ { "Posting_Title": "Software Engineer", "Job_Opening_Status": "In-progress", "Date_Opened": "2026-02-01", "Target_Date": "2026-03-01" } ] } ```
#### 更新职位空缺
```bash PUT /zoho-recruit/recruit/v2/Job_Openings/{record_id} Content-Type: application/json ```
#### 删除职位空缺
```bash DELETE /zoho-recruit/recruit/v2/Job_Openings?ids={record_id1},{record_id2} ```
### 面试
#### 列出面试
```bash GET /zoho-recruit/recruit/v2/Interviews ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Interviews?per_page=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 根据 ID 获取面试
```bash GET /zoho-recruit/recruit/v2/Interviews/{record_id} ```
#### 创建面试
```bash POST /zoho-recruit/recruit/v2/Interviews Content-Type: application/json
{ "data": [ { "Interview_Name": "Technical Interview", "Candidate_Name": {"id": "846336000000552208"}, "Posting_Title": {"id": "846336000000552093"}, "Start_DateTime": "2026-02-10T10:00:00-08:00", "End_DateTime": "2026-02-10T11:00:00-08:00" } ] } ```
### 部门
#### 列出部门
```bash GET /zoho-recruit/recruit/v2/Departments ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-recruit/recruit/v2/Departments?per_page=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 申请
#### 列出申请
```bash GET /zoho-recruit/recruit/v2/Applications ```
### 通用记录操作
所有模块都支持相同的 CRUD 操作：
```bash # List records GET /zoho-recruit/recruit/v2/{module_api_name}
# Get record by ID GET /zoho-recruit/recruit/v2/{module_api_name}/{record_id}
# Create records POST /zoho-recruit/recruit/v2/{module_api_name}
# Update records PUT /zoho-recruit/recruit/v2/{module_api_name}/{record_id}
# Delete records DELETE /zoho-recruit/recruit/v2/{module_api_name}?ids={id1},{id2}
# Search records GET /zoho-recruit/recruit/v2/{module_api_name}/search?criteria={criteria} ```
## 可用模块
| 模块 | API 名称 | 描述 | |--------|----------|-------------| | Candidates | `Candidates` | 职位候选人 | | Job Openings | `Job_Openings` | 开放职位 | | Applications | `Applications` | 职位申请 | | Interviews | `Interviews` | 安排的面试 | | Departments | `Departments` | 公司部门 | | Clients | `Clients` | 客户公司 | | Contacts | `Contacts` | 联系人 | | Campaigns | `Campaigns` | 招聘活动 | | Referrals | `Referrals` | 员工推荐 | | Tasks | `Tasks` | 待办事项 | | Events | `Events` | 日历事件 | | Vendors | `Vendors` | 外部供应商 |
## 分页
Zoho Recruit 使用基于页面的分页：
```bash GET /zoho-recruit/recruit/v2/{module_api_name}?page=1&per_page=200 ```
- `page`：页码（默认：1） - `per_page`：每页记录数（默认：200，最多：200）
响应包含分页信息： ```json { "data": [...], "info": { "per_page": 200, "count": 50, "page": 1, "more_records": false } } ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates?per_page=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'per_page': 10} ) data = response.json() ```
## 注意事项
- 记录 ID 是数字字符串（例如 `846336000000552208`） - 每个 GET 请求最多 200 条记录 - 每个 POST/PUT 请求最多 100 条记录 - 每个 DELETE 请求最多 100 条记录 - 模块 API 名称区分大小写（例如 `Job_Openings`，而不是 `job_openings`） - `Last_Name` 是候选人必填项 - 日期格式：`yyyy-MM-dd` - 日期时间格式：`yyyy-MM-ddTHH:mm:ss±HH:mm` (ISO 8601) - 查找字段使用包含 `id` 和可选 `name` 的 JSON 对象 - 重要：使用 curl 命令时，如果 URL 包含特殊字符，请使用 `curl -g` - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，像 `$MATON_API_KEY` 这样的环境变量可能无法在某些 shell 环境中正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Zoho Recruit 连接或请求无效 | | 401 | Maton API 密钥无效或缺失 | | 429 | 速率限制 | | 4xx/5xx | 来自 Zoho Recruit API 的透传错误 |
### 常见错误代码
| 代码 | 描述 | |------|-------------| | INVALID_DATA | 无效的字段值 | | MANDATORY_NOT_FOUND | 缺少必填字段 | | DUPLICATE_DATA | 检测到重复记录 | | INVALID_MODULE | 无效的模块 API 名称 | | NO_PERMISSION | 权限不足 |
### 故障排除：API 密钥问题
1. 检查 `MATON_API_KEY` 环境变量是否已设置：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：无效的应用名称
1. 确保您的 URL 路径以 `zoho-recruit` 开头。例如：
- 正确：`https://gateway.maton.ai/zoho-recruit/recruit/v2/Candidates` - 错误：`https://gateway.maton.ai/recruit/v2/Candidates`
## 资源
- [Zoho Recruit API v2 概述](https://www.zoho.com/recruit/developer-guide/apiv2/) - [获取记录 API](https://www.zoho.com/recruit/developer-guide/apiv2/get-records.html) - [插入记录 API](https://www.zoho.com/recruit/developer-guide/apiv2/insert-records.html) - [更新记录 API](https://www.zoho.com/recruit/developer-guide/apiv2/update-records.html) - [删除记录 API](https://www.zoho.com/recruit/developer-guide/apiv2/delete-records.html) - [搜索记录 API](https://www.zoho.com/recruit/developer-guide/apiv2/search-records.html) - [模块 API](https://www.zoho.com/recruit/developer-guide/apiv2/modules-api.html) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])