> For the complete documentation index, see [llms.txt](https://api-docs.roundhr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.roundhr.com/round-api/api-reference/sourcing-candidates/list.md).

# 후보자 리스트 조회

## 후보자 리스트

<mark style="color:green;">`GET`</mark> `https://api.roundhr.com/v1/sourcing/candidates`

소싱/탤런트풀 후보자 리스트를 반환합니다. 페이지네이션이 적용됩니다.

지원자로 전환된 후보자도 `sourcing_status`가 `conversion` 상태로 계속 포함됩니다.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Query Parameters**

| Name             | Type   | 필수         | Description                                                              |
| ---------------- | ------ | ---------- | ------------------------------------------------------------------------ |
| sourcing\_status | string | `optional` | 소싱 상태로 필터링 (lead, contacted, interested, nurturing, pending, conversion) |
| per              | number | `optional` | 페이지당 결과 수 (기본값: 20, 최대: 100)                                             |
| page\_token      | string | `optional` | 페이지네이션 토큰                                                                |

**응답 예제**

{% tabs %}
{% tab title="200" %}

```json
{
   "collection": [
      {
         "code": "code_abc123def456",
         "name": "박소싱",
         "email": "sourcing.park@example.com",
         "phone": "010-1234-5678",
         "duplicate": false,
         "duplicate_job": false,
         "reapply": false,
         "feedback_kind": "sourcing",
         "feedback_status": "ongoing",
         "feedback_result": null,
         "feedback_score": null,
         "feedback_score_count": 1,
         "feedback_score_total_count": 3,
         "education_final_kind": "university_4",
         "experience_total_period": 36,
         "interest": null,
         "privacy": true,
         "resume_path": "https://example.com/resume.pdf",
         "referer_type": "sourcing",
         "referral_info": null,
         "referral_reason": null,
         "fail_reason_message": null,
         "sourcing_status": "lead",
         "linkedin_url": "https://www.linkedin.com/in/sourcing-park",
         "applied_at": null,
         "created_at": "2024-09-02T18:56:37+09:00",
         "projects": [
            {
               "code": "code_project123",
               "title": "인재풀",
               "description": "기본 인재풀",
               "base": true,
               "created_at": "2024-09-02T18:56:37+09:00",
               "updated_at": "2024-09-02T18:56:37+09:00"
            }
         ]
      }
   ],
   "pagination": {
      "total": 150,
      "previous_page": null,
      "previous_page_token": null,
      "next_page": "https://api.roundhr.com/v1/sourcing/candidates?page_token=MTk=_N",
      "next_page_token": "MTk=_N"
   }
}
```

{% endtab %}
{% endtabs %}

**응답 필드 설명**

| Field                         | Type    | Description                                                         |
| ----------------------------- | ------- | ------------------------------------------------------------------- |
| code                          | string  | 후보자 고유 코드 (지원자 전환 후에도 유지)                                           |
| name                          | string  | 후보자 이름                                                              |
| email                         | string  | 후보자 이메일                                                             |
| phone                         | string  | 후보자 전화번호                                                            |
| sourcing\_status              | string  | 소싱 상태 (lead, contacted, interested, nurturing, pending, conversion) |
| linkedin\_url                 | string  | 링크드인 프로필 URL                                                        |
| feedback\_kind                | string  | 평가 종류 (sourcing 등)                                                  |
| feedback\_status              | string  | 평가 상태 (ongoing, complete, expire)                                   |
| feedback\_result              | string  | 평가 결과                                                               |
| feedback\_score               | integer | 평가 점수                                                               |
| feedback\_score\_count        | integer | 완료된 평가자 수                                                           |
| feedback\_score\_total\_count | integer | 전체 평가자 수                                                            |
| education\_final\_kind        | string  | 최종 학력                                                               |
| experience\_total\_period     | integer | 총 경력 기간 (월 단위)                                                      |
| referer\_type                 | string  | 유입 유형 (sourcing, referral 등)                                        |
| applied\_at                   | string  | 지원자 전환 일시 (전환 전에는 null)                                             |
| projects                      | array   | 소속 인재풀(프로젝트) 목록                                                     |

**sourcing\_status 값**

| Value      | Description |
| ---------- | ----------- |
| lead       | 리드          |
| contacted  | 컨택 완료       |
| interested | 후보자 응답/관심   |
| nurturing  | 관계 유지       |
| pending    | 보류          |
| conversion | 지원자로 전환됨    |

**Pagination**

| Field                 | Type    | Description           |
| --------------------- | ------- | --------------------- |
| total                 | integer | 전체 후보자 수              |
| previous\_page        | string  | 이전 페이지 URL (없으면 null) |
| previous\_page\_token | string  | 이전 페이지 토큰 (없으면 null)  |
| next\_page            | string  | 다음 페이지 URL (없으면 null) |
| next\_page\_token     | string  | 다음 페이지 토큰 (없으면 null)  |