> 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/candidates/list.md).

# 지원자 리스트 조회

## 지원자 리스트

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

지원자 리스트를 반환합니다. 페이지네이션이 적용됩니다.

**Headers**

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

**Query Parameters**

| Name        | Type   | 필수         | Description                                                |
| ----------- | ------ | ---------- | ---------------------------------------------------------- |
| stage\_kind | string | `optional` | 채용 단계로 필터링 (applied, review, interview, offer, pass, fail) |
| per         | number | `optional` | 페이지당 결과 수 (기본값: 20, 최대: 100)                               |
| page\_token | string | `optional` | 페이지네이션 토큰                                                  |

**응답 예제**

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

```json
{
   "collection": [
      {
         "code": "code_abc123def456",
         "name": "김지원",
         "email": "jiwon.kim@example.com",
         "phone": "010-1234-5678",
         "duplicate": false,
         "duplicate_job": false,
         "reapply": false,
         "feedback_kind": "interview",
         "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,
         "birth": "1990-01-15",
         "privacy": true,
         "resume_path": "https://example.com/resume.pdf",
         "referer_type": "referral",
         "referral_info": "김철수",
         "referral_reason": "해당 직무에 적합한 인재",
         "fail_reason_message": "실무 경험이 기대에 미치지 못했습니다.",
         "fail_reason_title": "면접 불합격",
         "applied_at": "2024-09-02T18:56:37+09:00",
         "created_at": "2024-09-02T18:56:37+09:00",
         "job": {
            "code": "code_job123",
            "title": "프론트엔드 개발자 채용",
            "url": "https://company.recruit.roundhr.com/c/code_job123",
            "deleted": false,
            "created_at": "2024-09-02T18:56:37+09:00",
            "updated_at": "2024-09-02T18:56:37+09:00"
         },
         "job_stage": {
            "stage_kind": "failed",
            "title": "불합격",
            "created_at": "2024-09-02T18:56:37+09:00",
            "updated_at": "2024-09-02T18:56:37+09:00"
         },
         "fail_job_stage": {
            "stage_kind": "interview",
            "title": "1차 면접",
            "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/candidates?page_token=MTk=_N",
      "next_page_token": "MTk=_N"
   }
}
```

{% endtab %}
{% endtabs %}

**응답 필드 설명**

| Field                         | Type    | Description                             |
| ----------------------------- | ------- | --------------------------------------- |
| code                          | string  | 지원자 고유 코드                               |
| name                          | string  | 지원자 이름                                  |
| email                         | string  | 지원자 이메일                                 |
| phone                         | string  | 지원자 전화번호                                |
| duplicate                     | boolean | 중복 지원 여부                                |
| duplicate\_job                | boolean | 동일 공고 중복 지원 여부                          |
| reapply                       | boolean | 재지원 여부                                  |
| feedback\_kind                | string  | 평가 종류 (review, interview, assignment 등) |
| 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  | 추천 유형 (referral, external 등)            |
| referral\_info                | string  | 추천인 정보                                  |
| referral\_reason              | string  | 추천 사유                                   |
| fail\_reason\_title           | string  | 불합격 사유                                  |
| fail\_reason\_message         | string  | 불합격 상세 사유                               |
| applied\_at                   | string  | 지원 일시                                   |
| job                           | object  | 지원한 공고 정보                               |
| job\_stage                    | object  | 현재 채용 단계 정보                             |
| fail\_job\_stage              | object  | 불합격 직전 채용 단계 정보                         |

**stage\_kind 값**

| Value     | Description |
| --------- | ----------- |
| applied   | 지원          |
| review    | 서류 검토       |
| interview | 면접          |
| offer     | 처우 협의       |
| pass      | 합격          |
| fail      | 불합격         |

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