Known Issues

A custom field can depend on a parent field, so that it only applies when the parent has certain values. On jobs, offers and openings, if you write a value to a child field whose parent doesn't enable it, the request returns 200 or 201, but the value isn't saved. Single-select children work the same way: options that the parent's value doesn't allow are dropped without an error.

Workaround: Give the parent field a value that enables the child, either in the same request as the child's value or before it.

Planned fix: A new endpoint, GET /v3/custom_field_dependencies, will show which fields depend on others. It ships before the change below.

🚧

Upcoming breaking change

These writes will return 422 instead of 200 or 201. The error names the child field and its parent, for example Cannot set value for custom field {id: ..., name_key: ...} because its parent field {id: ..., name_key: ...} has no value that enables it. For a single-select child, the error names the options that the parent's value doesn't allow. A request that sets the parent and the child together still succeeds, and an explicit value: null still returns 200. Before this ships, check which fields have a parent and send the parent's value along with the child's.

You can restrict a job custom field to certain offices or departments. GET /v3/jobs still returns every job custom field in the organization on every job, including fields that don't apply to that job's offices or departments. These fields usually come back with value: null. If you send a value for one of them to PATCH /v3/jobs/{id}, the request fails with 422 and the error Cannot set value for custom field {id: ..., name_key: ...} as it does not apply to the job's offices or departments. Nothing in the read response tells you which fields you can write.

Workaround: To check which fields apply to a job, call GET /v3/custom_field_offices and GET /v3/custom_field_departments. Then compare each field's offices and departments with the job's. A field restricted to a parent department or office also applies to jobs in its child departments and offices. If a field has both office and department restrictions, the job must match both.

Planned fix: Job responses will leave out custom fields that don't apply to the job's offices or departments, including fields that have a stored value. Fields that apply keep today's shape, including value: null when unset. This covers GET /v3/jobs and the job returned by POST /v3/jobs and PATCH /v3/jobs/{id}.

📘

Possible impact

This affects you only if your organization restricts job custom fields by office or department and your integration expects every job custom field on every job. For example, it might map a fixed set of fields or flag a missing field as an error. After the fix, treat a missing field as one that doesn't apply to that job and can't be written.

POST /v3/interviews doesn't check whether another interview in your organization already uses the same external_event_id. You can create several interviews with the same ID, and each request returns 201. A later PATCH /v3/interviews/{id} that sends that external_event_id fails with 422 and the error External event ID already taken. Harvest V1 and V2 reject the duplicate when the interview is created.

Workaround: If you aren't changing an interview's external_event_id, leave it out of the PATCH /v3/interviews/{id} request body. The interview keeps its current ID, and the duplicate check doesn't run.

🚧

Upcoming breaking change

POST /v3/interviews will return 422 with the error External event ID already taken when another interview in your organization already uses the request's external_event_id. This matches PATCH /v3/interviews/{id}. Interviews that already share an ID won't be changed. Before this ships, make sure your integration sends a unique external_event_id for each interview in the organization, and handles a 422 on create.

When a new responsible recruiter or coordinator replaces the current one, the previous owner's responsible changes to false, but its updated_at stays the same. If you sync job owners by updated_at, you miss this change. It happens when the change comes from POST /v3/job_owners with candidate_responsibility, from the Harvest V1 hiring team endpoints, or from the hiring team page in Greenhouse.

Planned fix: The previous owner's updated_at will change when it loses responsibility on the paths above.

📘

Note

Owners that lost responsibility before the fix keep their old updated_at. If you sync by updated_at, plan a one-time full pull of GET /v3/job_owners after the fix ships.

In Greenhouse, you can clear Who gets credit? on an application. Harvest V3 has no way to do the same. Sending "referrer_id": null to PATCH /v3/applications/{id} returns 422 with the error Value at /referrer_id is not an integer, and the referrer doesn't change.

Workaround: Clear Who gets credit? on the application in Greenhouse.

Planned fix: Sending "referrer_id": null will clear the referrer and return 200 with "referrer_id": null. Leaving out referrer_id will still leave the referrer unchanged, and a valid integer referrer_id will still set it.

When you create a job post with POST /v3/job_posts and template_job_post_id, the new post gets duplicate settings for each free job board. In Greenhouse, Publish to free job boards then shows each board more than once. The duplicates add up: if you use an API-created post as the next template, its copy gets one more entry per board. The API response doesn't include these settings, so you won't see the duplicates there. Job posts duplicated in Greenhouse aren't affected.

Planned fix: A job post created from a template will get exactly one entry per free job board.

You can send a rejection email with rejection_email.email_from_user_id and an email template that sends from the user's own email address. If that user hasn't allowed others to send email from their address, or their email address isn't verified, the request fails with 403. The response doesn't say why the request failed or how to fix it.

Workaround: Ask the user in email_from_user_id to turn on Allow anyone with job or site admin permissions to send emails from my address in their Greenhouse account settings, and to verify their email address.

Planned fix: The error will explain why the request failed and which setting the user needs to turn on.

A required rejection custom field can be set to apply only to some rejections: in the offer stage or in other stages, and when you rejected the candidate or when the candidate rejected you. When you update rejection details with custom_fields, PATCH /v3/rejection_details/{id} requires every required rejection field, including ones that don't apply to this rejection. The request fails with 422 and the error Required custom field values not provided.

Planned fix: The required-field check will skip fields that don't apply to the rejection. These requests will then return 200.

If you send a POST, PUT or DELETE request to a URL that doesn't match any Harvest V3 endpoint, the API returns 412 Precondition Failed instead of 404 Not Found. For example, a URL with the base URL repeated, such as https://harvest.greenhouse.io/v3/https:/harvest.greenhouse.io/v3/jobs, returns 412. The status code doesn't tell you that the URL is wrong. GET requests to an unknown URL correctly return 404.