--- title: "Update candidate" method: PATCH path: "/v3/candidates/{id}" tags: ["Candidates"] --- # Update candidate `PATCH /v3/candidates/{id}` ## Request - Base URL: `https://harvest.greenhouse.io` - URL: `https://harvest.greenhouse.io/v3/candidates/{id}` - Auth: one of: - OAuth 2 - Authorization code: `https://auth.greenhouse.io/authorize` - Client credentials - Token URL: `https://auth.greenhouse.io/token` scopes: `harvest:candidates:update` - HTTP bearer Patch an existing candidate's profile fields. Only the keys included in the request body are modified; omitted keys are left untouched. Array fields (`phone_numbers`, `addresses`, `email_addresses`, `website_addresses`, `social_media_addresses`, `tags`, `linked_user_ids`, `custom_fields`) replace the existing collection wholesale — send the full desired list, not a delta. Setting `is_private` to `true` restricts the candidate to users with `View Private Candidates` access. ## Path parameters - `id` integer, required ## Request body - object - `first_name` string - `last_name` string - `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 - `is_private` boolean - `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 ## Response `200` Successful - object - `id` integer - `created_at` string, date-time - `updated_at` string, date-time - `first_name` string, nullable - `last_name` string, nullable - `preferred_name` string, nullable: Preferred or chosen name the candidate goes by, when different from their legal first name. - `company` string, nullable: Candidate's current company, as entered on their profile. - `title` string, nullable: Candidate's current job title, as entered on their profile. - `last_activity_at` string, date-time, nullable: Timestamp of the most recent activity on any of the candidate's applications (notes, emails, stage changes, etc.), in ISO 8601. - `private` boolean, nullable: If true, the candidate is restricted to users with `View Private Candidates` access. Defaults to `false`. - `can_email` boolean: Whether this candidate has consented to receive email communication from your organization. - `time_zone` string, nullable: Candidate's time zone as a Rails-style identifier (for example `Eastern Time (US & Canada)`). - `tags` string[]: Candidate tag names applied to this candidate within your organization. - `linked_user_ids` integer[]: Ids of Greenhouse users linked to this candidate (employees represented by both a user record and a candidate record). - `phone_numbers` object[]: Phone numbers on the candidate's profile. Each entry pairs the `value` with a `type` such as `mobile`, `home`, `work`, `skype`, or `other`. Ordered by type — `home`, `work`, `mobile`, `skype`, then `other` — and oldest first within a type. - `value` string - `type` string - `addresses` object[]: Postal addresses on the candidate's profile. Each entry pairs the `value` with a `type` such as `home`, `work`, or `other`. Ordered oldest first. - `value` string - `type` string - `email_addresses` object[]: Email addresses on the candidate's profile. Each entry pairs the `value` with a `type` such as `personal`, `work`, or `other`. Ordered by most recently updated, and oldest first among entries last updated at the same time. - `value` string - `type` string - `website_addresses` object[]: Personal websites or portfolio URLs on the candidate's profile. Each entry pairs the `value` with a `type` such as `personal`, `company`, `portfolio`, `blog`, or `other`. Ordered oldest first. - `value` string - `type` string - `social_media_addresses` object[]: Social media handles or URLs on the candidate's profile. Social entries are untyped — only the `value` is returned. Ordered oldest first. - `value` string - `custom_fields` object, nullable ## 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)