> For the complete documentation index, see [llms.txt](https://developers.welcomekit.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.welcomekit.co/candidates-api/candidates/untitled.md).

# List candidates

This endpoint lets you retrieve all candidates for a given job reference.

{% hint style="info" %}
  This endpoint requires `candidates_r` or `my_candidates_r` scope.
{% endhint %}

## candidate list

<mark style="color:blue;">`GET`</mark> `https://www.welcomekit.co/api/v1/external/candidates`

#### Query Parameters

| Name                                             | Type    | Description                                                  |
| ------------------------------------------------ | ------- | ------------------------------------------------------------ |
| referrer                                         | string  | Filter by referrer                                           |
| job\_reference<mark style="color:red;">\*</mark> | string  | Job reference                                                |
| email                                            | string  | Email                                                        |
| origin                                           | string  | Filter by origin                                             |
| job\_stage\_id                                   | string  | Filter by job stage id                                       |
| job\_stage\_reference                            | string  | Filter by job stage reference                                |
| archived                                         | string  | Only returns archived candidates or not                      |
| created\_after                                   | string  | Only returns candidates created after this date (YYYY-MM-DD) |
| updated\_after                                   | string  | Only returns candidates updated after this date (YYYY-MM-DD) |
| per\_page                                        | integer | Number of jobs per page                                      |
| page                                             | integer | Page offset                                                  |
| stage                                            | boolean | Returns related job stage (i.e. refused, hire, etc.)         |
| tags                                             | boolean | Returns related tags                                         |

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

```
[
  {
    "reference": "wttj-d655345409a6097309156b05",
    "cover_letter": "",
    "created_at": "2016-08-23T12:55:27.206+02:00",
    "job_reference": "WTTJ_KmqkD1Y",
    "modal_path": "/dashboard/o/Pg4eV6k/jobs/WTTJ_KmqkD1Y/card/wttj-d655345409a6097309156b05",
    "portfolio_size": 4242,
    "portfolio_url": "http://cdn.com/porfolio.pdf",
    "resume_content_type": "application/pdf",
    "resume_size": 4242,
    "resume_url": "http://cdn.com/resume.pdf",
    "stage_id": 14600,
    "stage":{
      "id": 14600,
      "name":"Refusé",
      "reference":"refused",
      "visible":true
    },
    "updated_at": "2016-08-23T12:55:27.206+02:00",
    "profile": {
      "address": null,
      "avatar_url": "http://wk.dev/assets/default-avatar-7cbb7b9749a7cf8864001cde13e2a9a94e612bf083430d66ede0966f5bafb296.png",
      "city": null,
      "country_code": null,
      "country_name": null,
      "email": "test@example.com",
      "firstname": "Foo",
      "lastname": "Bar",
      "phone": null,
      "subtitle": null,
      "zip_code": null
    },
    "origin": "external",
    "archived": false
  },
  ...
]
```

{% endtab %}
{% endtabs %}

Request example

```
curl -X GET -G "https://www.welcomekit.co/api/v1/external/candidates" \
    -d "job_reference=WTTJ_KmqkD1Y" \
    -d "stage=true" \
    -H "Authorization: Bearer WK_API_KEY"
```