--- title: "Bulk create candidates" method: POST path: "/v3/candidates/bulk" tags: ["Candidates"] --- # Bulk create candidates `POST /v3/candidates/bulk` ## Request - Base URL: `https://harvest.greenhouse.io` - URL: `https://harvest.greenhouse.io/v3/candidates/bulk` - Auth: OAuth 2 - Authorization code: `https://auth.greenhouse.io/authorize` - Client credentials - Token URL: `https://auth.greenhouse.io/token` scopes: `harvest:candidates:create` Asynchronously create many candidate profiles in a single call, typically for HRIS sync workflows that create a batch of candidates at once. Each item follows the same shape as `POST /v3/candidates`, with `first_name` and `last_name` required; all other profile fields are optional. Pass a nested `application` object to 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. A `bulk_action_uuid` is returned immediately. Per-item success or failure is reported through `GET /v3/bulk_requests/{bulk_action_uuid}`. ## Request body - object - `callback_url` string: Optional HTTPS URL Greenhouse will POST to when every row in `data` has finished. Omit to poll `GET /v3/bulk_requests/{bulk_action_uuid}` instead. - `data` object[], required: Array of single-resource create payloads to process. Each item must match the schema of the matching non-bulk POST endpoint. - `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 - … - union - … - number - object - … - object - … - object - … - 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 - … - union - … - number - object - … - object - … - object - … - `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 - … - object - … - `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 - … - object - … - `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 `202` Accepted - object - `bulk_action_uuid` string: UUID assigned to the new bulk request. Use this with `GET /v3/bulk_requests/{bulk_action_uuid}` to monitor progress and retrieve per-row results. - `status` string: Initial lifecycle state of the new bulk request, typically `building` immediately after creation. See the bulk request response schema for the full set of values. - `status_url` string: Relative path that returns the current status of the bulk request. Append this to your Harvest base URL to fetch the latest state. ## Other responses - `401`: Unauthorized - `413`: Payload is larger than 10MB - `422`: Validation Error - `429`: Client has more than 5 active jobs --- [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)