---
title: "Create a new candidate and assign to a Talent Pool"
method: POST
path: "/candidates"
tags: ["candidates"]
---

# Create a new candidate and assign to a Talent Pool

`POST /candidates`

## Request

- Base URL: `https://api.smartrecruiters.com`
- URL: `https://api.smartrecruiters.com/candidates`
- Auth: one of:
  - API key in header `x-smarttoken`
  - OAuth 2
    - Authorization code: `https://www.smartrecruiters.com/identity/oauth/allow`
    - Token URL: `https://api.smartrecruiters.com/identity/oauth/token` scopes: `candidates_create`

Create a new candidate and assign to a Talent Pool.

**Tracking candidate source**

When adding a new candidate, it's very important you track its source appropriately. In order to associate a source with your app/integration, add below object to a candidate body object for this endpoint:
```
{
  "sourceDetails": {
    "sourceTypeId": "string",
    "sourceSubTypeId": "string",
    "sourceId": "string"
  }
}
```
**sourceTypeId** - it's a Source Type - available values can be found using [get /configuration/sources](https://developers.smartrecruiters.com/reference/configurationsourcetypes-1) endpoint

**sourceSubTypeId** - it's a Source Subtype, an optional parameter - available values can be found using [get /configuration/sources](https://developers.smartrecruiters.com/reference/configurationsourcetypes-1) endpoint

**sourceId** - it's a Source Id - available values for a given sourceTypeId can be found using [get /configuration/sources/:sourceTypeId/values](https://developers.smartrecruiters.com/reference/configurationsourcevaluesall-1) endpoint

NOTE: Not defining the source will default to **API** source.

NOTE II: In case you can't find an appropriate source to track against you can:
* Create a custom source for each customer account separately on [this admin page](https://www.smartrecruiters.com/settings/configuration/custom-sources) (you need to be logged in as an admin to the customer account in order to view this page)
* Request to [partners@smartrecruiters.com](mailto:partners@smartrecruiters.com) adding a standard source that will be available for all customers if your app/integration is productised (available to all SmartRecruiters customers)

## Request body

- CandidateInput
  - `firstName` string, required
  - `lastName` string, required
  - `email` string, email, required
  - `phoneNumber` string
  - `location` CandidateLocation
    - `country` string
    - `countryCode` string
    - `regionCode` string
    - `region` string
    - `city` string
    - `lat` number, float
    - `lng` number, float
  - `web` WebProfile
    - `skype` string
    - `linkedin` string
    - `facebook` string
    - `twitter` string
    - `website` string
  - `tags` string[]
  - `education` Education[]
    - `institution` string
    - `degree` string
    - `major` string
    - `current` boolean
    - `location` string
    - `startDate` string, when: date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    - `endDate` string, when: date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    - `description` string
  - `experience` Experience[]
    - `title` string
    - `company` string
    - `current` boolean
    - `startDate` string, when: date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    - `endDate` string, when: date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    - `location` string
    - `description` string
  - `sourceDetails` CandidateSource
    - `sourceTypeId` string, required
    - `sourceSubTypeId` string
    - `sourceId` string, required
  - `internal` boolean

## Response `201`

Created candidate.

- CandidateDetails
  - `id` string
  - `internal` boolean
  - `firstName` string
  - `lastName` string
  - `email` string
  - `phoneNumber` string
  - `location` CandidateLocation
    - `country` string
    - `countryCode` string
    - `regionCode` string
    - `region` string
    - `city` string
    - `lat` number, float
    - `lng` number, float
  - `web` WebProfile
    - `skype` string
    - `linkedin` string
    - `facebook` string
    - `twitter` string
    - `website` string
  - `createdOn` string, date-time
  - `updatedOn` string, date-time
  - `tags` string[]
  - `averageRating` number
  - `education` Education[]
    - `institution` string
    - `degree` string
    - `major` string
    - `current` boolean
    - `location` string
    - `startDate` string, when: date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    - `endDate` string, when: date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    - `description` string
  - `experience` Experience[]
    - `title` string
    - `company` string
    - `current` boolean
    - `startDate` string, when: date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    - `endDate` string, when: date in YYYY, YYYY-MM or YYYY-MM-dd format, ex. "2016", "2016-11", "2016-11-29"
    - `location` string
    - `description` string
  - `primaryAssignment` object: Its latest modified application from applications in non final-state. If no applications in non-final state then one in final state with most recent modification date is returned. Inactive(final) states are Lead, Rejected, Transferred, Withdrawn, Hired
    - `job` object
      - `id` string
      - `title` string
      - `actions` object
        - `details` Action, required
          - `url` string, required
          - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
        - `positionDetails` Action
          - `url` string, required
          - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
    - `status` 'LEAD' | 'NEW' | 'IN_REVIEW' | 'INTERVIEW' | 'OFFERED' | 'HIRED' | 'REJECTED' | 'WITHDRAWN' | 'TRANSFERRED'
    - `subStatus` string
    - `startsOn` string, date-time
    - `source` string
    - `reasonOfRejection` Property
      - `id` string, required
      - `label` string
    - `reasonOfWithdrawal` Property
      - `id` string, required
      - `label` string
    - `actions` object
      - `sourceDetails` Action
        - `url` string, required
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
  - `secondaryAssignments` object[]: List of assignemnts (applications). Applications are sorted by state (non-final states first) and then by date. First one is excluded and is returned as primaryAssignment. Mentioned date is a date of last modification of an application eg: changed state, change of a source, reapply, anonymisation, unshare. Inactive(final) states are Lead, Rejected, Transferred, Withdrawn, Hired
    - `job` object
      - `id` string
      - `title` string
      - `actions` object
        - `details` Action, required
          - `url` string, required
          - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
        - `positionDetails` Action
          - `url` string, required
          - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
    - `status` 'LEAD' | 'NEW' | 'IN_REVIEW' | 'INTERVIEW' | 'OFFERED' | 'HIRED' | 'REJECTED' | 'WITHDRAWN' | 'TRANSFERRED'
    - `subStatus` string
    - `startsOn` string, date-time
    - `source` string
    - `reasonOfRejection` Property
      - `id` string, required
      - `label` string
    - `reasonOfWithdrawal` Property
      - `id` string, required
      - `label` string
    - `actions` object
      - `sourceDetails` Action
        - `url` string, required
        - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
  - `actions` object
    - `properties` Action, required
      - `url` string, required
      - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
    - `attachments` Action
      - `url` string, required
      - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
    - `consent` Action
      - `url` string, required
      - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required
    - `consents` Action
      - `url` string, required
      - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'OPTIONS' | 'DELETE' | 'HEAD' | 'CONNECT', required

## Other responses

- `400`: with codes * **SOURCE_NOT_FOUND** when provided source does not exist, * **SUBTYPE_REQUIRED** when there are more sources and subtype parameter is required, * **INVALID_PROPERTY_VALUE** when provided property value does not conform to the domain requirements
- `403`: with code **PERMISSION_DENIED** when you are not permitted to create candidate
- `404`: with code **SOURCE_TYPE_NOT_FOUND** when provided source type does not exist

---

[API](https://skmtc.dev/smartrecruiters/apis/candidates-api.md) - [All operations](https://skmtc.dev/smartrecruiters/apis/candidates-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartrecruiters/apis/candidates-api/revisions/8fde9b33d46d?raw)