---
title: "Agent Match Candidates"
method: POST
path: "/api/v1/agent/match-candidates"
tags: ["Agent 专用"]
---

# Agent Match Candidates

`POST /api/v1/agent/match-candidates`

## Request

- Base URL: `https://api.hipowork.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.hipowork.com/api/v1/agent/match-candidates`
- Auth: OAuth 2 (password, token URL `/api/v1/auth/oauth/token`)

一步到位：直接给定结构化/自然语言条件，返回 Top-N 匹配候选人 + 评分明细。

比 /search/structured 更方便：内部完成硬性过滤 + 语义匹配 + 评分排序。

## Request body

- MatchCandidatesRequest: 结构化条件直接匹配（Agent 一步到位）
  - `query_text` string, nullable
  - `required` RequiredRule[], nullable
    - `field` string, required
    - `operator` string, required
    - `value` unknown, required
    - `label` string, nullable
  - `preferred` PreferredConditions
    - `semantic_query` string, nullable
    - `skills` PreferredSkill[], nullable
      - `name` string, required
      - `min_level` integer, nullable
      - `min_years` number, nullable
      - `weight` number
      - `label` string, nullable
    - `keywords` PreferredKeyword[], nullable
      - `text` string, required
      - `weight` number
      - `label` string, nullable
    - `industry_extensions` object, nullable
  - `max_results` integer

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/hipowork/apis/hipo-work-ai-recruitment-platform.md) · [All operations](https://skmtc.dev/hipowork/apis/hipo-work-ai-recruitment-platform/llms.txt) · [OpenAPI document](https://skmtc.dev/hipowork/apis/hipo-work-ai-recruitment-platform/revisions/de21a6c57062?raw)