--- title: "Create candidate" method: POST path: "/v3/candidates" tags: ["Candidates"] --- # Create candidate `POST /v3/candidates` ## Request - Base URL: `https://harvest.greenhouse.io` - URL: `https://harvest.greenhouse.io/v3/candidates` - Auth: one of: - OAuth 2 - Authorization code: `https://auth.greenhouse.io/authorize` - Client credentials - Token URL: `https://auth.greenhouse.io/token` scopes: `harvest:candidates:create` - HTTP bearer Create a new candidate profile in your organization. `first_name` and `last_name` are required; all other profile fields are optional. A candidate is always created with one application. Pass a nested `application` object to control it: supply a `job_id` to create an applicant, or a `prospect_pool_id` (and omit `job_id`) to create a prospect. When `application` is omitted, the candidate is created as a prospect with an application attached to no job, placed in the organization's default prospect pool when one is configured and in no pool otherwise. 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 - number - string - 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 - number - string - 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.dev/greenhouse/apis/harvest-api.md) - [All operations](https://skmtc.dev/greenhouse/apis/harvest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/greenhouse/apis/harvest-api/revisions/822822e3f771?raw)