WRITE Endpoint Migration Guide
This guide includes updated write endpoints, recommendations for custom integrations, and a clear mapping of v1/v2 resources to their v3 equivalents. It’s designed to help you transition endpoints smoothly and efficiently.
Each table in this article is organized alphabetically and maps specific resources to their v1/v2 routes, the corresponding v3 equivalent, and any additional comments or considerations for those endpoints.
It is recommended to read through the READ Endpoint Migration to gather all the aliasing changes which may impact some of the attributes in the Harvest v3 WRITE endpoints.
Recommendations for custom integrations
We encourage users of custom integrations to adopt the Client Credentials Flow to familiarize themselves with the new authentication process in Harvest V3.
Note: The Client Credentials Flow is not available for Greenhouse partners. Partners must use the Authorization Code Grant Type.
Applications
Applications | V1 - DELETE: Delete Applications |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/applications/{id} |
V3 route | DELETE https://harvest.greenhouse.io/v3/applications/{id} |
Comments |
Applications | V1 - POST: Add Application to Candidate / Prospect |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/candidates/{id}/applications |
V3 route | POST https://harvest.greenhouse.io/v3/applications |
Comments |
Applications | V1 - PATCH: Update Application |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/applications/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/applications/{id} PATCH https://harvest.greenhouse.io/v3/rejection_details/{id} |
Comments | Notes: Rejection details in Harvest v3 are updated in their own resource. |
Applications | V1 - POST: Advance Application |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/applications/{id}/advance |
V3 route | POST https://harvest.greenhouse.io/v3/applications/{id}/move |
Comments | Leave to_stage_id and to_job_id blank if wanting to advance the application. |
Applications | V1 - POST: Move Application (Different Job) |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/applications/{id}/transfer_to_job |
V3 route | POST https://harvest.greenhouse.io/v3/applications/{id}/move |
Comments | Add to_stage_id and to_job_id if wanting to move the application to a different job. |
Applications | V1 - POST: Move Application (Same Job) |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/applications/{id}/move |
V3 route | POST https://harvest.greenhouse.io/v3/applications/{id}/move |
Comments | Add to_stage_id if wanting to move the application to a different stage within the same job. |
Applications | V1 - PATCH: Convert Prospect To Candidate |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/applications/{id}/convert_prospect |
V3 route | POST https://harvest.greenhouse.io/v3/applications/{id}/convert_to_candidate |
Comments | If the to_job_interview_stage_id is omitted, we will defer to the initial stage. |
Applications | V1 - POST: Add Attachment to Application |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/applications/{id}/attachments |
V3 route | POST https://harvest.greenhouse.io/v3/attachments |
Comments |
Applications | V1 - POST: Hire Application |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/applications/{id}/hire |
V3 route | POST https://harvest.greenhouse.io/v3/applications/{id}/hire |
Comments |
Applications | V1 - POST: Reject Application |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/applications/{id}/reject |
V3 route | POST https://harvestdocs.greenhouse.io/reference/get_v3-applications |
Comments |
Applications | V1 - PATCH: Update Rejection Reason |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/applications/{id}/reject |
V3 route | PATCH https://harvest.greenhouse.io/v3/rejection_details/{id} |
Comments |
Applications | V1 - POST: Unreject Application |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/applications/{id}/unreject |
V3 route | POST https://harvest.greenhouse.io/v3/applications/{id}/unreject |
Comments |
Approvals
Approvals | V1 - POST: Request Approvals |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/approval_flows/{id}/request_approvals |
V3 route | POST https://harvest.greenhouse.io/v3/approval_flows/{id}/request_approvals |
Comments |
Approvals | V1 - PUT: Replace an approver in an approver group |
---|---|
V1/V2 route | PUT https://harvest.greenhouse.io/v1/approver_groups/{approver_group_id}/replace_approvers |
V3 route | PUT https://harvest.greenhouse.io/v3/approver_groups/{id}/replace_approver |
Comments |
Approvals | V1 - PUT: Create or replace an approval flow |
---|---|
V1/V2 route | PUT https://harvest.greenhouse.io/v1/jobs/{job_id}/approval_flows |
V3 route | POST https://harvest.greenhouse.io/v3/approval_flows |
Comments |
Candidates
Candidates | V1 - DELETE: Delete Candidate |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/candidates/{id} |
V3 route | DELETE https://harvest.greenhouse.io/v3/candidates/{id} |
Comments |
Candidates | V1 - PATCH: Edit Candidate |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/candidates/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/candidates/{id} |
Comments | Recruiter and Coordinator information has been removed from the Candidate object and is now on the Application object. |
Candidates | V1 - POST: Add Attachment |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/candidates/{id}/attachments |
V3 route | POST https://harvest.greenhouse.io/v3/attachments |
Comments | Attachments should be attached to applications, instead of candidates, which can be done through the new endpoint. |
Candidates | V1 - POST: Add Candidate |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/candidates |
V3 route | POST https://harvest.greenhouse.io/v3/candidates |
Comments | The v3 endpoint is also used to create Prospects which is done in the nested application object. |
Candidates | V1 - POST: Add Note |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/candidates/{id}/activity_feed/notes |
V3 route | POST https://harvest.greenhouse.io/v3/notes |
Comments | The v3 endpoint has merged both Add Note and Add E-mail Note into the same endpoint and differentiates the two with the note_type attribute. |
Candidates | V1 - POST: Add E-mail Note |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/candidates/{id}/activity_feed/emails |
V3 route | POST https://harvest.greenhouse.io/v3/notes |
Comments | The v3 endpoint has merged both Add Note and Add E-mail Note into the same endpoint and differentiates the two with the note_type attribute. |
Candidates | V1 - POST: Add Education |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/candidates/{id}/educations |
V3 route | POST https://harvest.greenhouse.io/v3/candidate_educations |
Comments | Candidate education is created and deleted in its own endpoint in Harvest v3. The custom_field_option_id is now retrieved from candidate custom fields, as opposed to their own endpoints. |
Candidates | V1 - DELETE: Remove Education From Candidate |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/candidates/{candidate_id}/educations/{education_id} |
V3 route | DELETE https://harvest.greenhouse.io/v3/candidate_educations/{id} |
Comments |
Candidates | V1 - POST: Add Employment |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/candidates/{id}/employments |
V3 route | POST https://harvest.greenhouse.io/v3/candidate_employments |
Comments |
Candidates | V1 - DELETE: Remove Employment From Candidate |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/candidates/{candidate_id}/employments/{employment_id} |
V3 route | DELETE https://harvest.greenhouse.io/v3/candidate_employments/{id} |
Comments |
Candidates | V1 - POST: Add Prospect |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/prospect |
V3 route | POST https://harvest.greenhouse.io/v3/candidates |
Comments | The v3 endpoint is also used to create Candidates which is done in the nested application object. |
Candidates | V1 - PUT: Anonymize Candidate |
---|---|
V1/V2 route | PUT https://harvest.greenhouse.io/v1/candidates/{id}/anonymize?fields={field_names} |
V3 route | PATCH https://harvest.greenhouse.io/v3/candidates/{id}/anonymize |
Comments |
Candidates | V1 - PUT: Merge Candidates |
---|---|
V1/V2 route | PUT https://harvest.greenhouse.io/v1/candidates/merge |
V3 route | POST https://harvest.greenhouse.io/v3/candidates/{id}/merge |
Comments |
Custom Fields
Custom Fields | V1 - POST: Create Custom Field |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/custom_fields |
V3 route | POST https://harvest.greenhouse.io/v3/custom_fields POST https://harvest.greenhouse.io/v3/custom_field_departments POST https://harvest.greenhouse.io/v3/custom_field_offices |
Comments | Harvest v3 has separated departments and offices from custom fields. |
Custom Fields | V1 - PATCH: Update Custom Field |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/custom_fields/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/custom_fields/{id} |
Comments | The v1 endpoint for Update Custom Field had limited body parameters accessible. In v3, you can modify additional fields. |
Custom Fields | V1 - DELETE: Delete Custom Field |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/custom_fields/{id} |
V3 route | DELETE https://harvest.greenhouse.io/v3/custom_fields/{id} |
Comments |
Custom Fields | V1 - POST: Create Custom Field Options |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options |
V3 route | POST https://harvest.greenhouse.io/v3/custom_field_options |
Comments | This endpoint creates custom field options individually. There is a separate bulk endpoint to handle asynchronous bulk creation. |
Custom Fields | V1 - PATCH: Update Custom Field Options |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options |
V3 route | PATCH https://harvest.greenhouse.io/v3/custom_field_options/{id} |
Comments | This endpoint updates custom field options individually. There is a separate bulk endpoint to handle asynchronous bulk updates. |
Custom Fields | V1 - DELETE: Remove Custom Field Options |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/custom_field/{id}/custom_field_options |
V3 route | DELETE https://harvest.greenhouse.io/v3/custom_field_options/{id} |
Comments | This endpoint permanently deletes custom field options individually. There is a separate bulk endpoint to handle asynchronous bulk deletes. |
Departments
Departments | V1 - PATCH: Edit Department |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/departments/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/departments/{id} |
Comments |
Departments | V1 - POST: Add Department |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/departments |
V3 route | POST https://harvest.greenhouse.io/v3/departments |
Comments |
Job Openings
Job Openings | V2 - DELETE: Destroy Openings |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v2/jobs/{job_id}/openings |
V3 route | DELETE https://harvest.greenhouse.io/v3/openings/{id} |
Comments | This endpoint permanently deletes openings individually. There is a separate bulk endpoint to handle asynchronous bulk deletes. |
Job Openings | V1 - PATCH: Edit Openings |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/jobs/{job_id}/openings/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/openings/{id} |
Comments |
Job Openings | V1 - POST: Create New Openings |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/jobs/{job_id}/openings |
V3 route | POST https://harvest.greenhouse.io/v3/openings |
Comments | This endpoint creates openings individually. There is a separate bulk endpoint to handle asynchronous bulk creates. |
Job Posts
Job Posts | V1 - PATCH: Update Job Post |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v2/job_posts/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/job_posts/{id} POST https://harvest.greenhouse.io/v3/job_post_locations DELETE https://harvest.greenhouse.io/v3/job_post_locations/{id} |
Comments | Job post locations are modified via their own Harvest v3 endpoint. |
Job Posts | V1 - PATCH: Update Job Post Status |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v2/job_posts/{id}/status |
V3 route | PATCH https://harvest.greenhouse.io/v3/job_posts/{id} |
Comments | The v2 endpoints for job post have been combined back to a singular endpoint and the service will accept/reject the action based off of the user’s permissions. |
Jobs
Jobs | V1 - PATCH: Update Job |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/jobs/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/jobs/{id} |
Comments |
Jobs | V1 - POST: Create Job |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/jobs |
V3 route | POST https://harvest.greenhouse.io/v3/jobs |
Comments |
Jobs | V1 - PUT: Replace Hiring Team |
---|---|
V1/V2 route | PUT https://harvest.greenhouse.io/v1/jobs/{id}/hiring_team |
V3 route | POST https://harvest.greenhouse.io/v3/job_hiring_managers DELETE https://harvest.greenhouse.io/v3/job_hiring_managers/{id} POST https://harvest.greenhouse.io/v3/job_owners DELETE https://harvest.greenhouse.io/v3/job_owners/{id} |
Comments | We modified the combined functionality to pursue individual creates and deletes instead of overwriting. |
Jobs | V1 - POST: Add Hiring Team Members |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/jobs/{id}/hiring_team |
V3 route | POST https://harvest.greenhouse.io/v3/job_hiring_managers POST https://harvest.greenhouse.io/v3/job_owners |
Comments |
Jobs | V1 - DELETE: Remove Hiring Team Member |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/jobs/{id}/hiring_team |
V3 route | DELETE https://harvest.greenhouse.io/v3/job_hiring_managers/{id} DELETE https://harvest.greenhouse.io/v3/job_owners/{id} |
Comments |
Offers
Offers | V1 - PATCH: Update Current Offer |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/applications/{id}/offers/current_offer |
V3 route | PATCH https://harvest.greenhouse.io/v3/offers/{id} |
Comments |
Offices
Offices | V1 - PATCH: Edit Office |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/offices/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/offices/{id} |
Comments |
Offices | V1 - POST: Add Office |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/offices |
V3 route | POST https://harvest.greenhouse.io/v3/offices |
Comments |
Scheduled Interviews
Scheduled Interviews | V2 POST: Create Scheduled Interview |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v2/scheduled_interviews |
V3 route | POST https://harvest.greenhouse.io/v3/interviews |
Comments |
Scheduled Interviews | V2 PATCH: Update Scheduled Interview |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v2/scheduled_interviews/{id} |
V3 route | PATCH https://harvest.greenhouse.io/v3/interviews/{id} |
Comments |
Scheduled Interviews | V1 - Delete: Remove Scheduled Interview |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/scheduled_interviews/{id} |
V3 route | DELETE https://harvest.greenhouse.io/v3/interviews/{id} |
Comments |
Tags
Tags | V1 - POST: Add New Candidate Tag |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/tags/candidate |
V3 route | POST https://harvest.greenhouse.io/v3/candidate_tags |
Comments |
Tags | V1 - DELETE: Destroy a candidate tag |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/tags/candidate/{tag_id} |
V3 route | DELETE https://harvest.greenhouse.io/v3/candidate_tags/{id} |
Comments |
Tags | V1 - DELETE: Remove tag from candidate |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/candidates/{candidate_id}/tags/{tag_id} |
V3 route | DELETE https://harvest.greenhouse.io/v3/applied_candidate_tags/{id} |
Comments |
Tags | V1 - PUT: Add a candidate tag |
---|---|
V1/V2 route | PUT https://harvest.greenhouse.io/v1/candidates/{candidate_id}/tags/{tag_id} |
V3 route | POST https://harvest.greenhouse.io/v3/applied_candidate_tags |
Comments |
Users
Users | V2 - PATCH: Edit User |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v2/users/ |
V3 route | PATCH https://harvest.greenhouse.io/v3/users/{id} |
Comments |
Users | V2 - PATCH: Disable User |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v2/users/disable |
V3 route | POST https://harvest.greenhouse.io/v3/users/{id}/deactivate |
Comments |
Users | V2 - PATCH: Enable User |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v2/users/enable |
V3 route | POST https://harvest.greenhouse.io/v3/users/{id}/activate |
Comments |
Users | V1 - PATCH: Change user permission level |
---|---|
V1/V2 route | PATCH https://harvest.greenhouse.io/v1/users/permission_level |
V3 route | POST https://harvest.greenhouse.io/v3/users/{id}/revoke_permissions |
Comments |
Users | V1 - POST: Add User |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/users |
V3 route | POST https://harvest.greenhouse.io/v3/users |
Comments |
Users | V1 - POST: Add E-mail Address To User |
---|---|
V1/V2 route | POST https://harvest.greenhouse.io/v1/users/{id}/email_addresses |
V3 route | POST https://harvest.greenhouse.io/v3/user_emails |
Comments |
User Permissions
User Permissions | V1 - DELETE: Remove a Job Permission |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/users/{id}/permissions/jobs |
V3 route | DELETE https://harvest.greenhouse.io/v3/user_job_permissions/{id} |
Comments |
User Permissions | V1 - PUT: Add a Job Permission |
---|---|
V1/V2 route | PUT https://harvest.greenhouse.io/v1/users/{id}/permissions/jobs |
V3 route | POST https://harvest.greenhouse.io/v3/user_job_permissions |
Comments |
User Permissions | V1 - DELETE: Remove a Future Job Permission |
---|---|
V1/V2 route | DELETE https://harvest.greenhouse.io/v1/users/{id}/permissions/future_jobs |
V3 route | DELETE https://harvest.greenhouse.io/v3/future_job_permissions/{id} |
Comments |
User Permissions | V1 - PUT: Add a Future Job Permission |
---|---|
V1/V2 route | PUT https://harvest.greenhouse.io/v1/users/{id}/permissions/future_jobs |
V3 route | POST https://harvest.greenhouse.io/v3/future_job_permissions |
Comments |
Updated 2 days ago