> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dropcv.work/llms.txt
> Use this file to discover all available pages before exploring further.

# candidate_list

> 按关键词、过滤条件、分页浏览人才库 —— 非语义结构化查询。

`candidate_list` 是人才库的**结构化查询** —— 纯数据库查询，不走向量语义。和 [`candidate_search`](/integration/skills/candidate-search) 互补：

* `candidate_search` —— 给一段 JD 或人选画像，**语义召回**相似的人
* `candidate_list` —— **翻页浏览**整库、或按**姓名 / 公司 / 职位关键词**精确找人

所有参数都可选；全不传就是按更新时间倒序翻人才库第一页。

## 参数

| 字段               | 类型        | 必填 | 说明                           |
| ---------------- | --------- | -- | ---------------------------- |
| `keyword`        | string    | 否  | 对姓名 / 当前公司 / 当前职位做大小写不敏感子串匹配 |
| `current_city`   | string    | 否  | 按当前城市过滤（精确匹配）                |
| `industries`     | string\[] | 否  | 行业标签过滤（命中任一即可）               |
| `functions`      | string\[] | 否  | 职能标签过滤（命中任一即可）               |
| `skills`         | string\[] | 否  | 技能标签过滤（命中任一即可）               |
| `profile_status` | string    | 否  | 档案状态，如 `draft` / `active`    |
| `limit`          | int       | 否  | 返回条数，默认 20，最多 200            |
| `offset`         | int       | 否  | 分页偏移，默认 0                    |

## 返回

```json theme={null}
{
  "total": 128,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "candidate_id": "uuid",
      "full_name": "张三",
      "current_title": "高级后端工程师",
      "current_company": "某科技公司",
      "current_city": "上海",
      "profile_status": "active"
    }
  ]
}
```

`total` 是该过滤条件下的总数（不受 `limit` 影响），用来做分页。

## 示例

```bash theme={null}
# 按关键词找人
curl -X POST https://api.dropcv.work/api/external/v1/skills/candidate_list/invoke \
  -H "Authorization: Bearer $DROPCV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "params": { "keyword": "腾讯", "limit": 20 } }'

# 翻页浏览 + 过滤
curl -X POST https://api.dropcv.work/api/external/v1/skills/candidate_list/invoke \
  -H "Authorization: Bearer $DROPCV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "params": { "current_city": "上海", "industries": ["互联网"], "limit": 50, "offset": 0 } }'
```

## 权限

只读 —— 任意 API Key 都能调用，不需要 write 权限。