> 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/retrieve-a-candidate.md).

# Retrieve a candidate

This endpoint allows you to retrieve candidate info by his reference.

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

## a candidate

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

#### Path Parameters

| Name                                        | Type   | Description         |
| ------------------------------------------- | ------ | ------------------- |
| reference<mark style="color:red;">\*</mark> | string | Candidate reference |

#### Query Parameters

| Name  | Type    | Description                                          |
| ----- | ------- | ---------------------------------------------------- |
| stage | boolean | Returns related job stage (ie. refused, hired, 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
  },
  "tags": ["ruby","react","go","elixir","react native"],
  "origin": "external",
  "archived": false
}
```

{% endtab %}
{% endtabs %}

Request example

```
curl -X GET -G "https://www.welcomekit.co/api/v1/external/candidates/:reference" \
    -d "stage=true" \
    -d "tags=true" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY"
```