---
title: "Create candidate"
method: POST
path: "/v3/candidates"
tags: ["Candidates"]
---

# Create candidate

`POST /v3/candidates`

Create a new candidate profile in your organization. `first_name` and `last_name` are required; all other profile fields are optional. Pass a nested `application` object to simultaneously create the candidate's first application — supply a `job_id` to create an applicant, or a `prospect_pool_id` (and omit `job_id`) to create a prospect. Tag names that don't yet exist on the organization are created on the fly.

## Request body

- object
  - `first_name` string, required
  - `last_name` string, required
  - `preferred_name` string
  - `time_zone` 'international date line west' | 'midway island' | 'american samoa' | 'hawaii' | 'alaska' | 'pacific time (us & canada)' | 'tijuana' | 'mountain time (us & canada)' | 'arizona' | 'chihuahua' | 'mazatlan' | 'central time (us & canada)' | 'saskatchewan' | 'guadalajara' | 'mexico city' | 'monterrey' | 'central america' | 'eastern time (us & canada)' | 'indiana (east)' | 'bogota' | 'lima' | 'quito' | 'atlantic time (canada)' | 'caracas' | 'la paz' | 'santiago' | 'asuncion' | 'newfoundland' | 'brasilia' | 'buenos aires' | 'montevideo' | 'georgetown' | 'puerto rico' | 'greenland' | 'mid-atlantic' | 'azores' | 'cape verde is.' | 'dublin' | 'edinburgh' | 'lisbon' | 'london' | 'casablanca' | 'monrovia' | 'utc' | 'belgrade' | 'bratislava' | 'budapest' | 'ljubljana' | 'prague' | 'sarajevo' | 'skopje' | 'warsaw' | 'zagreb' | 'brussels' | 'copenhagen' | 'madrid' | 'paris' | 'amsterdam' | 'berlin' | 'bern' | 'zurich' | 'rome' | 'stockholm' | 'vienna' | 'west central africa' | 'bucharest' | 'cairo' | 'helsinki' | 'kyiv' | 'riga' | 'sofia' | 'tallinn' | 'vilnius' | 'athens' | 'istanbul' | 'minsk' | 'jerusalem' | 'harare' | 'pretoria' | 'kaliningrad' | 'moscow' | 'st. petersburg' | 'volgograd' | 'samara' | 'kuwait' | 'riyadh' | 'nairobi' | 'baghdad' | 'tehran' | 'abu dhabi' | 'muscat' | 'baku' | 'tbilisi' | 'yerevan' | 'kabul' | 'ekaterinburg' | 'islamabad' | 'karachi' | 'tashkent' | 'chennai' | 'kolkata' | 'mumbai' | 'new delhi' | 'kathmandu' | 'dhaka' | 'sri jayawardenepura' | 'almaty' | 'astana' | 'novosibirsk' | 'rangoon' | 'bangkok' | 'hanoi' | 'jakarta' | 'krasnoyarsk' | 'beijing' | 'chongqing' | 'hong kong' | 'urumqi' | 'kuala lumpur' | 'singapore' | 'taipei' | 'perth' | 'irkutsk' | 'ulaanbaatar' | 'seoul' | 'osaka' | 'sapporo' | 'tokyo' | 'yakutsk' | 'darwin' | 'adelaide' | 'canberra' | 'melbourne' | 'sydney' | 'brisbane' | 'hobart' | 'vladivostok' | 'guam' | 'port moresby' | 'magadan' | 'srednekolymsk' | 'solomon is.' | 'new caledonia' | 'fiji' | 'kamchatka' | 'marshall is.' | 'auckland' | 'wellington' | 'nuku'alofa' | 'tokelau is.' | 'chatham is.' | 'samoa'
  - `company` string
  - `title` string
  - `can_email` boolean
  - `phone_numbers` object[]
    - `value` string, required
    - `type` 'home' | 'work' | 'mobile' | 'skype' | 'other', required
  - `addresses` object[]
    - `value` string, required
    - `type` 'home' | 'work' | 'other', required
  - `email_addresses` object[]
    - `value` string, required
    - `type` 'personal' | 'work' | 'other', required
  - `website_addresses` object[]
    - `value` string, required
    - `type` 'personal' | 'company' | 'portfolio' | 'blog' | 'other', required
  - `social_media_addresses` object[]
    - `value` string, required
  - `tags` string[]
  - `linked_user_ids` integer[]
  - `custom_fields` union[]
    - union
      - object
        - `name_key` string, required — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified.
        - `custom_field_id` integer — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified.
        - `value` union
          - string
          - string
          - string
          - string
          - string
          - boolean
          - number — User ID
          - union
            - string[]
            - number[]
          - number
          - object
            - `amount` number, required
            - `currency_code` string, required
          - object
            - `min_amount` number, required
            - `max_amount` number, required
            - `currency_code` string, required
          - object
            - `min_value` number, required
            - `max_value` number, required
      - object
        - `name_key` string — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified.
        - `custom_field_id` integer, required — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified.
        - `value` union
          - string
          - string
          - string
          - string
          - string
          - boolean
          - number — User ID
          - union
            - string[]
            - number[]
          - number
          - object
            - `amount` number, required
            - `currency_code` string, required
          - object
            - `min_amount` number, required
            - `max_amount` number, required
            - `currency_code` string, required
          - object
            - `min_value` number, required
            - `max_value` number, required
  - `application` union
    - object
      - `source_id` integer
      - `recruiter_id` integer
      - `coordinator_id` integer
      - `referrer_id` integer
      - `created_at` string, date-time
      - `custom_fields` union[]
        - union
          - object
            - `name_key` string, required — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified.
            - `custom_field_id` integer — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified.
            - `value` union
              - …
          - object
            - `name_key` string — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified.
            - `custom_field_id` integer, required — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified.
            - `value` union
              - …
      - `job_id` integer, required
      - `initial_stage_id` integer
    - object
      - `source_id` integer
      - `recruiter_id` integer
      - `coordinator_id` integer
      - `referrer_id` integer
      - `created_at` string, date-time
      - `custom_fields` union[]
        - union
          - object
            - `name_key` string, required — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified.
            - `custom_field_id` integer — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified.
            - `value` union
              - …
          - object
            - `name_key` string — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified.
            - `custom_field_id` integer, required — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified.
            - `value` union
              - …
      - `prospect` boolean, required
      - `job_ids` integer[]
      - `prospect_pool_id` integer
      - `prospect_pool_stage_id` integer
      - `prospect_owner_id` integer
      - `prospective_department_id` integer
      - `prospective_office_id` integer

## Response `201`

Successful

- object
  - `candidate` unknown
  - `application` unknown

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `422` — Unprocessable Content

---

[API](https://skmtc.net/greenhouse/apis/auth-api.md) · [All operations](https://skmtc.net/greenhouse/apis/auth-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greenhouse/auth-api/versions/9517a2e54640/schema)