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

# Create a candidate

This endpoint allows you create new candidates for a given job\_reference.

For example, you could create a [Chrome Extension](https://chrome.google.com/webstore/detail/welcomekitco-chrome-exten/lejhdnpgccgidknkedecghdkamgmempj) which makes it easy for recruiters to create new candidates… :)

Also, if you don’t want to give full access to all your candidates to external services, you may use the `my_candidates_rw` scope which will let them create candidates and only access to the candidates they created.

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

## candidate creation

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

#### Query Parameters

| Name                                                      | Type    | Description                                                        |
| --------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
| organization\_reference<mark style="color:red;">\*</mark> | string  | Organization reference                                             |
| job\_reference<mark style="color:red;">\*</mark>          | string  | Job reference                                                      |
| job\_stage\_id<mark style="color:red;">\*</mark>          | string  | Job stage id                                                       |
| email<mark style="color:red;">\*</mark>                   | string  | Email                                                              |
| firstname<mark style="color:red;">\*</mark>               | string  | First name                                                         |
| lastname<mark style="color:red;">\*</mark>                | string  | Last name                                                          |
| tag\_list                                                 | string  | Comma separated list of tags                                       |
| subtitle                                                  | string  | Subtitle                                                           |
| phone                                                     | string  | Phone number                                                       |
| remote\_image\_url                                        | string  | Avatar url                                                         |
| remote\_resume\_url                                       | string  | Resume url (file type: PDF, DOC, DOCX, ODT maximum file size: 5MB) |
| remote\_portfolio\_url                                    | string  | Portfolio url (file type: PDF, maximum file size: 10MB)            |
| comment                                                   | string  | A comment about this candidate                                     |
| archived                                                  | boolean | Archive user                                                       |
| media\_website                                            | string  | Candidate website url                                              |
| media\_github                                             | string  | Profile url on Github                                              |
| media\_stackoverflow                                      | string  | Profile url on Stackoverflow                                       |
| media\_dribbble                                           | string  | Profile url on Dribbble                                            |
| media\_behance                                            | string  | Profile url on Behance                                             |
| media\_linkedin                                           | string  | Profile url on Linkedin                                            |
| media\_facebook                                           | string  | Profile url on Facebook                                            |
| media\_instagram                                          | string  | Profile url on Instagram                                           |
| media\_medium                                             | string  | Profile url on Medium                                              |
| media\_tumblr                                             | string  | Profile url Tumblr                                                 |
| media\_vimeo                                              | string  | Profile url on Vimeo                                               |
| media\_twitter                                            | string  | Profile url on Twitter                                             |
| cover\_letter                                             | string  | Cover letter                                                       |
| referrer                                                  | string  | Referrer                                                           |

{% 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,
  "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 POST "https://www.welcomekit.co/api/v1/external/candidates" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer WK_API_KEY" \
    -d @- <<EOF
{
  "email": "test@example.com",
  "firstname": "Foo",
  "lastname": "Bar",
  "organization_reference": "Pg4eV6k",
  "job_reference": "WTTJ_KmqkD1Y",
  "remote_resume_url": "http://example.com/resume.pdf",
  "remote_portfolio_url": "http://example.com/portfolio.pdf"
}
EOF
```