---
title: "Migrating Off Greenhouse: Harvest API v3 Export & ATS Migration Guide"
slug: migrating-off-greenhouse-harvest-api-v3-export-ats-migration-guide
date: 2026-11-16
author: Nachi Raman
categories: [Greenhouse, Migration Guide, ATS]
excerpt: "Greenhouse set August 31, 2026 as the removal date for Harvest API v1/v2. How to export data via Harvest v3, map it to a new ATS, and avoid the common migration pitfalls."
tldr: "Greenhouse set August 31, 2026 as the removal date for Harvest API v1/v2. Export via Harvest v3 (OAuth 2.0, cursor pagination, 30-second rate-limit windows). CSV flattens your data. Scorecard ratings need explicit mapping, because Lever and Ashby rate on 1–4 scales."
canonical: https://clonepartner.com/blog/migrating-off-greenhouse-harvest-api-v3-export-ats-migration-guide
---

# Migrating Off Greenhouse: Harvest API v3 Export & ATS Migration Guide


# Migrating Off Greenhouse: Harvest API v3 Export & ATS Migration Guide

To migrate off Greenhouse, export your data through Harvest API v3 and map it into the new ATS's data model. Greenhouse's documentation sets **August 31, 2026** as the removal date for Harvest API v1 and v2 and directs developers to Harvest v3 ([developers.greenhouse.io](https://developers.greenhouse.io/harvest.html)). After v1/v2 removal, OAuth is the only supported authentication method for the Harvest API ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/authentication)), so every extraction script, ETL pipeline, and custom integration built against v1 or v2 has to be rebuilt.

If you are planning to migrate off Greenhouse to a new Applicant Tracking System, this deadline shapes your entire extraction architecture. Any new export code must target Harvest v3 — and v3 is not a minor version bump. It changes authentication, pagination, rate limits, and the shape of the resources in ways that break existing scripts beyond a simple find-and-replace.

Migrating off Greenhouse is a data-model translation problem, not a simple export-import exercise. Greenhouse is strictly application-centric. A candidate is a flat profile, but their pipeline stages, interview schedules, scorecard ratings, and offers are tied to specific job applications. A naive report export flattens that relational structure, leaves out scorecard attribute ratings, and leaves attachments behind. To move historical recruiting data with full fidelity, you must extract it programmatically.

This guide covers the technical realities of the v3 migration, every viable method for getting data out of Greenhouse, the data-model translation problems you will hit when loading into a new ATS, and the compliance obligations that follow your candidate data out the door.

For a deep-dive on extraction methods alone, see our [Greenhouse data export guide](https://clonepartner.com/blog/blog/how-to-export-data-from-greenhouse-methods-api-limits-gaps). For target-specific guides, see [Greenhouse to Lever](https://clonepartner.com/blog/blog/greenhouse-to-lever-migration-the-ctos-technical-guide), [Greenhouse to Ashby](https://clonepartner.com/blog/blog/greenhouse-to-ashby-migration-apis-mapping-rate-limits), or [Greenhouse to Workday Recruiting](https://clonepartner.com/blog/blog/greenhouse-to-workday-recruiting-migration-the-ctos-guide).

> [!CAUTION]
> Greenhouse states that Harvest API v1 and v2 are deprecated and will be removed on **August 31, 2026**. All extraction and integration scripts must use Harvest v3 with OAuth 2.0 authentication. Do not invest engineering time in v1/v2 code. ([developers.greenhouse.io](https://developers.greenhouse.io/harvest.html))

## What changed in Harvest v3?

Four breaking changes define the v1/v2 → v3 shift, and each one alters how you build an extraction pipeline.

**Authentication.** Harvest v1/v2 used HTTP Basic Auth — your API key as the username, password blank. Harvest v3 replaces this with OAuth 2.0. For a custom integration, an admin opens **API Credentials**, creates new credentials of type "Harvest V3 (OAuth)", configures scopes, and receives a client ID and client secret. Your script sends those as HTTP Basic credentials to `https://auth.greenhouse.io/token` with `grant_type=client_credentials` and gets back a JWT bearer token ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/authentication)). Greenhouse's partner guide gives access tokens a **1-hour** lifetime ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/harvest-partner-oauth)), and the token response includes `expires_in`. The client credentials flow issues no refresh token, so you request a new token before expiry or on a `401`. For a long-running migration extraction, your script must actively manage the token lifecycle or the job will fail mid-flight with a `401 Unauthorized`.

**Pagination.** v1/v2 used page-number pagination (`?page=2&per_page=500`) with RFC 5988 Link headers that included `rel="next"`, `rel="prev"`, and `rel="last"`. v3 uses **cursor-based pagination** — you put filters and `per_page` (default 100, max 500) only on the first request, then follow the opaque cursor URL from the `Link: <...>; rel="next"` header. The cursor must be the only query parameter on subsequent requests. Appending filters alongside a cursor returns **HTTP 422 Unprocessable Content** ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/pagination)). The 422 body is ordinary JSON (`{"message": "Unprocessable Content", ...}`), so a handler that parses the body without checking the status code can mistake it for an empty last page and stop paginating early.

**Rate limits.** v1/v2 counted requests per 10-second window, with the limit returned in `X-RateLimit-Limit` ([developers.greenhouse.io](https://developers.greenhouse.io/harvest.html)). v3 counts requests in fixed 30-second windows, and token requests have a separate 60-second window. Greenhouse's v3 documentation shows `X-RateLimit-Limit: 75` only as an example ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/api-rate-limiting)). Build your rate limiter to read `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` dynamically from response headers rather than hardcoding a number.

**Resource shape.** v3 no longer embeds child resources in their parents. For example, `GET /v3/candidates` no longer includes the candidate's applications. You filter the child endpoint instead, such as applications by candidate ID ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/overview-and-philosophy)).

| Surface | Harvest v1/v2 (removal set for Aug 31, 2026) | Harvest v3 |
|---|---|---|
| Auth | Basic Auth (API key as username) | OAuth 2.0 bearer token (JWT) |
| Token expiry | N/A — API key is permanent | Access token: 1 hour; request a new one |
| Pagination | Page-number (`?page=N&per_page=500`) | Cursor-based (opaque cursor as sole parameter) |
| Rate limit | Per 10-second window; limit in `X-RateLimit-Limit` | Per 30-second fixed window; limit in `X-RateLimit-Limit` |
| Link headers | `next`, `prev`, `last` | `next` only (no `prev` or `last`) |
| Mixed cursor + filter | N/A (no cursor) | HTTP 422 Unprocessable Content |
| Child resources | Often embedded in parents | Separate endpoints, filtered by parent ID |

> [!WARNING]
> Because v3 splits child data into separate endpoints, a full extraction makes more requests than a v1/v2 script that read embedded objects. Plan your migration windows around the limit your account returns in `X-RateLimit-Limit`.

## HTTP status codes you will encounter in Harvest v3

Understanding what each error code means in context prevents misdiagnosed failures. The following table maps the most common status codes to their Greenhouse-specific causes and the correct handler response.

| Status code | Greenhouse-specific cause | Correct handler |
|---|---|---|
| `401 Unauthorized` | Access token expired (1-hour TTL) or malformed bearer header | Request a new token (client credentials) or refresh it (partner OAuth); re-queue the request |
| `403 Forbidden` | The authorizing user lacks the Greenhouse permissions, or the credential lacks a scope. All list endpoints require a Site Admin authorizing user. | Check the credential's scopes under **API Credentials** and the user passed as `sub` |
| Failed attachment download | The time-limited download URL has expired (links last seven days) | Re-fetch the attachment from `GET /v3/attachments`; download files inline during extraction |
| `422 Unprocessable Content` | Cursor present alongside other query parameters, a malformed cursor, or `per_page` out of range | Pass only the cursor URL from the `Link` header |
| `429 Too Many Requests` | Rate limit window exhausted | Read `Retry-After` header; sleep for that duration before retrying |
| `5xx` server errors | Transient server-side failure | Exponential backoff; do not retry immediately |

Sources: [harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/authentication), [harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/pagination), [harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/api-rate-limiting), [harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-attachments). The 422 during cursor pagination is the error most easily misread, because a handler that ignores the status code sees a JSON body and no records.

## The Greenhouse data model: what you are actually exporting

Before writing extraction logic, you must understand how Greenhouse relates its core objects. Get the schema wrong and you will corrupt candidate histories during the import phase.

Greenhouse organizes data in a strict hierarchy: **Candidate → Application → Job → Scorecard**.

### Candidates vs. Applications

A **Candidate** in Greenhouse is a contact record — name, email, phone number, social links. All meaningful recruiting activity happens at the **Application** level. An Application represents that candidate's attempt to get a specific job. Pipeline stages, interview schedules, rejections, and offers all hang off the Application, not the Candidate.

If a software engineer applies to your company three times over four years, they have one Candidate record and three Application records. You cannot pull a list of candidates and expect to see interview history. You must pull the Candidate, then query the Applications filtered by that Candidate ID, then pull the Jobs and Scorecards tied to each Application.

### Harvest v3 object schema reference

The following summarizes the key fields returned for core Greenhouse objects via the Harvest v3 API. This is not exhaustive — it covers the fields most critical for migration fidelity. v3 has list endpoints only for these objects. To fetch one record, pass its ID in the `ids` filter.

**Candidate object** (`GET /v3/candidates`) ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-candidates)):

| Field | Type | Nullable | Notes |
|---|---|---|---|
| `id` | integer | No | Greenhouse's internal integer ID |
| `first_name` | string | Yes | Can be null, for example after anonymization |
| `last_name` | string | Yes | Can be null, for example after anonymization |
| `email_addresses` | array of objects | No | Each has `value` and `type` (personal, work, other) |
| `phone_numbers` | array of objects | No | Each has `value`, `type` |
| `addresses` | array of objects | No | Each has `value`, `type` |
| `website_addresses` | array of objects | No | Each has `value`, `type` |
| `social_media_addresses` | array of objects | No | `value` only |
| `tags` | array of strings | No | Candidate tag names |
| `can_email` | boolean | No | Whether the candidate consented to email from your organization |
| `custom_fields` | object | Yes | Map of objects, each with `name`, `type`, `value` |

Applications are not embedded. Filter `GET /v3/applications` by `candidate_ids` instead.

**Application object** (`GET /v3/applications`) ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-applications)):

| Field | Type | Nullable | Notes |
|---|---|---|---|
| `id` | integer | No | Application-scoped integer ID |
| `candidate_id` | integer | No | Foreign key to Candidate |
| `job_id` | integer | Yes | Foreign key to Job; null for jobless prospects |
| `status` | string | No | `in_process`, `rejected`, `hired`, `converted` |
| `stage_id` / `stage_name` | integer / string | Yes | Current interview stage |
| `source_id` | integer | Yes | Null if no source is set |
| `referrer_id` | integer | Yes | Null if no referral |
| `recruiter_id` / `coordinator_id` | integer | Yes | Null when unassigned |
| `rejected_at` | datetime | Yes | ISO 8601; null if not rejected |
| `rejection_reason_id` | integer | Yes | References `/v3/rejection_reasons` |
| `prospect` | boolean | No | True for prospect applications |
| `custom_fields` | object | Yes | Application-level custom fields |

Scorecards, offers and stage history are not embedded. Pull them from `/v3/scorecards`, `/v3/offers`, and `/v3/application_stages`, filtered by application.

**Scorecard object** (`GET /v3/scorecards`) ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-scorecards)):

| Field | Type | Nullable | Notes |
|---|---|---|---|
| `id` | integer | No | Scorecard-scoped ID |
| `application_id` | integer | No | Foreign key to Application |
| `interviewer_id` | integer | No | User the scorecard is assigned to |
| `submitter_id` | integer | No | User who submitted it |
| `interview_kit_id` | integer | No | Determines questions, attributes and rating scale |
| `candidate_rating` | string | No | Overall recommendation: `strong_no` ("Definitely Not"), `no`, `yes`, `strong_yes`, `no_decision` |
| `notes`, `public_notes`, `private_notes` | string | Yes | Key takeaways and notes |
| `status` | string | No | `draft` or `complete` |
| `submitted_at` | datetime | Yes | ISO 8601; null while draft |

Per-attribute ratings live on a separate endpoint, `GET /v3/scorecard_candidate_attributes`. Each row carries a `candidate_attribute_rating` of `definitely_not`, `no`, `mixed`, `yes`, `strong_yes`, or `no_decision`, plus an optional `note` ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-scorecard-candidate-attributes)). Answers to scorecard questions come from `GET /v3/scorecard_question_answers`. This structured data is what distinguishes a Greenhouse scorecard from a generic text note.

### Scorecards and structured evaluation

Greenhouse scorecards are the most frequently mishandled objects in a migration. A scorecard is not a single text field — it is a collection of **attributes** (e.g., "System Design", "Communication") rated on a five-point categorical scale (Definitely Not, No, Mixed, Yes, Strong Yes), plus an overall recommendation and free-text notes.

Two constraints matter. First, v3 splits a scorecard across several endpoints, so extraction must join the scorecard, its attribute ratings, and its question answers. Second, target ATSs accept structured feedback only on their own scales:

- **Lever** (`POST /opportunities/:opportunity/feedback`): Accepts feedback forms built from a template. The overall rating runs from "4 - Strong Hire" to "1 - Strong No Hire", and scorecard fields rate each skill on a 1–4 scale with an optional comment ([hire.lever.co](https://hire.lever.co/developer/documentation)). Greenhouse's "Mixed" has no direct equivalent on a four-point scale, so you must decide how to convert it.
- **Ashby** (`applicationFeedback.submit`): Accepts answers to a feedback form's fields, including Score fields that take an integer from 1 to 4 with optional comments ([developers.ashbyhq.com](https://developers.ashbyhq.com/reference/applicationfeedbacksubmit-1)). The same "Mixed" mapping decision applies.
- **Workday Recruiting**: Confirm which feedback objects your Workday tenant can load before you plan the mapping.

The practical outcome: per-attribute ratings can travel as structured data only where the target's feedback form has matching fields and a rating mapping you have agreed. Anything without a home is serialized into notes or feedback text. Dropping scorecard data means losing the historical justification for every hiring decision. Serialize them — do not skip them. For anything you serialize, append the attribute names and ratings to the note body, so the rating values are human-readable even after import.

### What does not export

Several categories of Greenhouse data have no API endpoint, or no path into another ATS:

- **Reporting dashboards** — Greenhouse computes analytics server-side; there is no API endpoint to export computed metrics
- **Workflow automation rules**, stage-transition triggers, and approval chains — configuration, not data
- **Email templates** — `GET /v3/email_templates` lists them, but they must be rebuilt in your target system
- **Deleted records** — once Greenhouse deletes a candidate (via retention rules or manual deletion), the API no longer returns it; it is unrecoverable
- **Webhooks configuration** — event subscriptions are not exportable via API

Logged emails and activity entries are exportable: in v3, `GET /v3/notes` replaces the v1/v2 activity feed and returns note, email, and activity entries with their bodies ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-notes), [harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/step-by-step-migration-instructions)).

Candidate data moves at high fidelity; workflow configuration does not. Your migration plan should account for the configuration rebuild as a separate work stream from the data migration.

## How to get data out of Greenhouse: methods compared

Greenhouse offers several export paths. The right one depends on scale, fidelity requirements, and engineering resources.

### Harvest API v3 (programmatic export)

The **Harvest API** is the primary extraction mechanism for migrations. It returns structured JSON that preserves relational IDs, supports filtering by `updated_at` for incremental extraction, and provides attachment download URLs. This is the only path that gives you candidates, applications, jobs, scorecards, offers, interviews, custom fields, tags, sources, notes, and attachments (resumes, cover letters) with full relational integrity.

**Key constraint:** Attachment download URLs are time-limited and expire after seven days ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-attachments)). Your script must download the binary files inline during extraction, not in a later pass.

**Webhooks as a complement to polling:** Greenhouse webhooks POST event payloads to an endpoint you run, and can be used alongside Harvest API extraction to capture changes during a long migration. Subscribe to events such as `update_candidate`, `application_updated`, `candidate_stage_change`, and `hire_candidate` ([docs.greenhouse.io](https://docs.greenhouse.io/webhooks.html)) to maintain a delta log of changes occurring while your bulk extraction runs. This avoids a full re-extraction for the final delta sync, though it requires a receiving endpoint and a reconciliation pass.

### CSV report exports

Greenhouse's reports, such as the essential candidate report, return one row per candidate application. The report has a limit of 1,000 candidate applications; for larger lists, Greenhouse suggests filtering first or exporting, and the report can be emailed as an XLS file ([support.greenhouse.io](https://support.greenhouse.io/hc/en-us/articles/360042740232-Essential-Candidate-reports)). Report exports flatten the relational data model — the Candidate → Application → Job → Scorecard chain collapses into rows. Scorecard attribute ratings, attachments, and stage-transition history are not in the report columns, and nothing in the file tells you they are missing.

**When it works:** Quick snapshots for small teams or one-time compliance spot-checks with a few hundred records.

**When it breaks:** Any scenario requiring historical interview data, or any case where resumes need to travel with the candidate record.

Specifically, a report export:

- **Flattens the Candidate → Application relationship.** A candidate who applied to three jobs appears as three rows that you must merge yourself in the target system.
- **Leaves out scorecard attribute ratings.** Per-attribute ratings come only from the API.
- **Excludes attachments.** Resumes and cover letters are files in Greenhouse, not report columns.
- **Strips stage-transition history.** You get the current stage, not the full timeline of when a candidate moved through your pipeline.

Do not use CSVs as the basis for an ATS migration.

### Business Intelligence Connector

Greenhouse's **Business Intelligence Connector** is available on the Plus and Pro tiers. It delivers your Greenhouse data in nightly ETLs to Amazon S3 or Redshift ([support.greenhouse.io](https://support.greenhouse.io/hc/en-us/articles/360017503272-Business-Intelligence-BI-Connector-Basics-and-Overview)). Useful for warehouse pipelines and analytics, but the **nightly refresh** makes it unsuitable as a migration source when you need current data for a cutover.

### GDPR data subject request export

Greenhouse provides a per-candidate candidate packet, downloaded from a candidate's profile, which teams use for data access requests ([support.greenhouse.io](https://support.greenhouse.io/hc/en-us/articles/360035385891-Download-Candidate-Packet)). This is a single-record, one-at-a-time mechanism. Not viable for bulk migration.

| Method | Data fidelity | Attachments | Scorecards | Scale limit | Engineering effort |
|---|---|---|---|---|---|
| Report export | Low (flattened) | No | No | 1,000 applications per essential report | None |
| Harvest API v3 | High (relational JSON) | Yes (download inline) | Yes (separate endpoints) | Rate-limit bound | Medium–High |
| BI Connector | High (SQL) | Not documented | Yes | Plus and Pro tiers | Medium |
| Webhooks (complement) | Delta changes only | No | No | Real-time | Low–Medium |
| GDPR export | Per-candidate | Varies | No | 1 record at a time | None |

## How does Greenhouse data map to a new ATS?

Every ATS structures recruiting data differently. The translation from Greenhouse's application-centric model to your target is where most migration complexity lives.

### Greenhouse → Lever

Lever uses an **opportunity-centric model**: a Contact (person) has one or more Opportunities (candidacies). A Greenhouse Candidate maps 1:1 to a Lever Contact. Each Greenhouse Application maps to a Lever Opportunity. Greenhouse's integer IDs must translate to Lever's UUIDs.

If you fail to link the Opportunity to the Contact properly, your new ATS fills up with disconnected, orphaned pipeline records. As noted above, Lever's feedback forms rate on four-point scales — Greenhouse's "Mixed" rating has no direct equivalent and must be converted according to your mapping logic. See our full [Greenhouse to Lever migration guide](https://clonepartner.com/blog/blog/greenhouse-to-lever-migration-the-ctos-technical-guide).

### Greenhouse → Ashby

Ashby's data model is closer to Greenhouse's application-centric structure, which reduces some translation complexity. Ashby's feedback API accepts Score fields on a 1–4 scale, so per-attribute ratings need the same "Mixed" mapping decision as Lever. Custom fields require explicit type-matching between Greenhouse's field types and Ashby's equivalents before import. See our [Greenhouse to Ashby guide](https://clonepartner.com/blog/blog/greenhouse-to-ashby-migration-apis-mapping-rate-limits).

### Greenhouse → Workday Recruiting

Workday Recruiting lives inside Workday HCM, so candidate data must fit Workday's HR object model — a fundamentally different data structure from Greenhouse's application-centric design. This path typically requires EIB (Enterprise Interface Builder) batch loads or Workday's APIs. This is the most complex translation path. See our [Greenhouse to Workday guide](https://clonepartner.com/blog/blog/greenhouse-to-workday-recruiting-migration-the-ctos-guide).

### Custom field type compatibility

Greenhouse custom fields have a `value_type` of short text, long text, yes/no, single select, multi-select, currency, currency range, number, number range, date, URL, user, attachment, or rich text ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-custom-fields)). These fields appear in the API under a `custom_fields` object, not as top-level JSON keys. Options for select fields live on a separate endpoint, `GET /v3/custom_field_options`. Before running the import, you must recreate these fields in the target ATS with matching types, and confirm each type against the target's own field list.

Type mismatches cause target API rejections at import time. Multi-select fields need the most care: Greenhouse returns them as arrays, and each target has its own format for multi-value fields.

### Translating user IDs

Every action in Greenhouse — who created the candidate, who submitted the scorecard, who scheduled the interview — is tied to a Greenhouse User ID (integer). Extract all Greenhouse users first via `GET /v3/users` and map them to corresponding users in the new ATS before importing any activity records. If a recruiter has left the company, their user account will not exist in the new system. Map their historical actions to a designated "Legacy Data User" account to preserve the audit trail without consuming active licenses in the target ATS.

## Building an extraction pipeline against Harvest v3

If you are building the extraction yourself, here is the sequence that avoids the most common pitfalls:

1. **Create Harvest v3 OAuth credentials.** In Greenhouse, open **API Credentials**, create new credentials, select "Harvest V3 (OAuth)," and configure read scopes for all object types you need: candidates, applications, jobs, scorecards, offers, custom fields, and attachments. List endpoints require a Site Admin authorizing user ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/authentication)).

2. **Implement the OAuth token flow.** Send your client ID and client secret as HTTP Basic credentials to `https://auth.greenhouse.io/token` with `grant_type=client_credentials`. Cache the token and request a new one before the 1-hour expiry or when you get a `401`. Do not hardcode tokens.

3. **Pull custom field definitions first.** `GET /v3/custom_fields` returns the custom field IDs, names, and value types for this Greenhouse instance, and `GET /v3/custom_field_options` returns the allowed values for select fields. Run this before extracting any records — it prevents transformation failures downstream and gives you the mapping table you need for step 4.

4. **Extract in dependency order.** Jobs and departments first (`GET /v3/jobs`, `GET /v3/departments`), then candidates (`GET /v3/candidates`), applications (`GET /v3/applications`), scorecards (`GET /v3/scorecards` plus `GET /v3/scorecard_candidate_attributes`), offers (`GET /v3/offers`), and notes (`GET /v3/notes`). Extracting out of order creates orphaned references that break foreign-key constraints during import.

5. **Handle cursor pagination correctly.** On the first request, specify filters and `per_page` (max 500). On every subsequent request, use *only* the cursor URL from the `Link` header — do not append any query parameters. Harvest v3 returns HTTP 422 if the cursor is not the sole parameter. The 422 response body is JSON with no records, so an error handler that checks `len(records) == 0` without checking the status code will silently treat the truncated page as "end of results."

6. **Download attachments inline.** `GET /v3/attachments` returns time-limited download URLs for resumes and documents. Download the file bytes during extraction, following redirects. Store the binary alongside the JSON record. URLs stored for a later download pass fail once they expire after seven days ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-attachments)).

7. **Respect rate limits dynamically.** Read `X-RateLimit-Remaining` from every response. When it nears zero, pause until `X-RateLimit-Reset` ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/docs/api-rate-limiting)). Do not carry hardcoded delays over from v1/v2 scripts, which were tuned to a 10-second window.

8. **Configure webhooks for the delta window (optional but recommended).** If your extraction takes more than a few hours, configure Greenhouse webhooks for `update_candidate` and `application_updated` events pointing to a receiving endpoint. Use the webhook log as your delta set for the final sync rather than running a full re-extraction.

9. **Validate after extraction.** Compare record counts between your extract and the Greenhouse UI. Check for missing scorecards or offers (symptom of insufficient scopes or user permissions), orphaned applications (symptom of out-of-order extraction), and empty attachment downloads (symptom of expired URLs).

```python
import requests
import time

def get_token(client_id, client_secret):
    """Exchange OAuth client credentials for a bearer token."""
    resp = requests.post(
        "https://auth.greenhouse.io/token",
        auth=(client_id, client_secret),  # HTTP Basic, per Greenhouse docs
        data={"grant_type": "client_credentials"},
    )
    resp.raise_for_status()
    token_data = resp.json()
    # track expiry from expires_in and request a new token before it lapses
    return token_data["access_token"], time.time() + token_data["expires_in"] - 60

def extract_all(endpoint, token, params=None):
    """Cursor-paginated extraction for Harvest v3.
    
    Critical: params (filters) are sent ONLY on the first request.
    Subsequent requests use only the cursor URL from the Link header.
    Mixing cursor + params returns HTTP 422.
    """
    url = f"https://harvest.greenhouse.io/v3/{endpoint}"
    headers = {"Authorization": f"Bearer {token}"}
    results = []
    first_request = True

    while url:
        resp = requests.get(
            url,
            headers=headers,
            params=params if first_request else None  # cursor is self-contained
        )

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 30))
            time.sleep(retry_after)
            continue

        if resp.status_code == 422:
            # Likely cursor + filter collision. Fail loudly — do not swallow.
            raise ValueError(
                f"HTTP 422 from {url}. Check that no query params are "
                f"appended alongside a cursor token. Response: {resp.text}"
            )

        resp.raise_for_status()
        page_data = resp.json()
        if not page_data:
            break
        results.extend(page_data)

        # Parse next cursor from Link header: <url>; rel="next"
        link = resp.headers.get("Link", "")
        url = _parse_next_url(link)  # returns None if no next link
        first_request = False
        params = None  # never re-send filters after first request

    return results

def download_attachment(url):
    """Download a time-limited attachment URL inline. Do not store URLs for later."""
    # The URL may redirect to a fresh short-lived file URL; follow redirects
    resp = requests.get(url, timeout=30, allow_redirects=True)
    if resp.status_code in (403, 404, 410):
        raise RuntimeError(
            f"Attachment URL failed (HTTP {resp.status_code}). Re-fetch the "
            f"attachment from /v3/attachments before downloading."
        )
    resp.raise_for_status()
    return resp.content  # binary bytes; store to disk or object storage immediately
```

## How long does the data migration take?

The data migration itself — extracting from Greenhouse via Harvest v3 and loading into a target ATS — is typically completed within **1–5 business days**, depending on data volume, complexity, and API rate limits on both ends. These figures reflect our experience across migrations; your timeline will vary based on rate limit headroom in your Greenhouse account and the write throughput of your target ATS.

| Data volume | Typical migration time | Primary constraint |
|---|---|---|
| Under 10,000 records | Under 24 hours | Mapping and validation, not extraction speed |
| Most migrations | 1–5 business days | Custom field translation, attachment downloads, v3 and target rate limits |

**Keep two clocks separate.** These figures describe the data migration — extracting records from Greenhouse and loading them into your target ATS. They do not describe the time to select a new ATS, rebuild interview kits, configure workflow automation, re-establish integrations, retrain your team, and go live. That broader replatforming project is a separate effort measured in months.

## Common failure modes when leaving Greenhouse

These are the error patterns that appear most often in Harvest v3 migrations, with specific causes and fixes:

- **Missing scopes or permissions.** A credential without a needed scope, or a `sub` user without the needed permissions, gets `403 Forbidden`. Worse, when the token acts as a Site Admin who lacks the advanced permission for private data — offers, salary information, private notes, private fields — those list endpoints return an empty result with no error ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-candidates)). If you discover this after loading data into the target, you must re-extract and re-load the affected data separately.

- **Attachment URLs fetched but not downloaded.** Teams store the download URLs returned by the API, planning a separate download pass. The URLs expire after seven days ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-attachments)), and the later pass fails with no indication of what the original content was. Download bytes inline during extraction; store the binary immediately.

- **Anonymized candidates in the extract.** Anonymization scrubs the data categories you choose, such as names, email addresses, attachments, or notes, while hiring activity stays for reporting ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/patch_v3-candidates-id-anonymize)). Those records count against your candidate totals but carry little usable PII. Audit your retention and anonymization settings before extracting to know how many anonymized records to expect.

- **Cursor + filter → silent truncation.** Teams append query filters (e.g., `&updated_at=gte|2024-01-01T00:00:00Z`) alongside a cursor token on subsequent pagination requests. Harvest v3 returns HTTP 422. If your error handler treats 422 as "no more records" rather than raising an exception, the extraction completes silently with only the records from before the cursor was invalidated. The result is a partial extract with a record count that looks plausible but is wrong. Raise on 422 — never swallow it.

- **Rate-limit math from v1/v2 carried into v3 scripts.** Old scripts were tuned to v1/v2's 10-second window. v3 counts requests in 30-second fixed windows, so a fixed sleep interval can burn through a window early and then hit `429` responses for the rest of it. The fix is dynamic rate limiting from `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers — not a hardcoded sleep interval.

- **Out-of-order extraction creating orphaned records.** Extracting applications before jobs means application records reference job IDs that do not yet exist in your staging dataset. Import fails with foreign-key violations or silently creates applications with null job references. Always extract in dependency order: departments → jobs → candidates → applications → scorecards.

## GDPR and data compliance during the switch

Candidate databases contain Personally Identifiable Information and sometimes protected demographic data. Compliance obligations survive the migration. Three areas demand explicit attention.

**Retention rules and deletion timing.** Greenhouse lets you set your own data retention rules. If you have enabled auto-deletion rules, candidates may be purged *before* you extract them. Audit your retention configuration before starting extraction. If your retention window is 12 months and you have 2-year-old rejected candidates you need for compliance records, verify they still exist in the API — a `GET /v3/candidates?ids=...` request that returns no record means the data is gone.

**Consent status travels with the data.** Harvest v3 candidate records carry a `can_email` flag for email consent ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-candidates)), but no consent-history array. Export consent records from Greenhouse's GDPR features and keep them with the data. If a candidate denied consent or requested erasure in Greenhouse, you cannot re-import their data into a new system without a fresh legal basis. Map consent status to your target ATS's consent tracking mechanism or document it in your audit log.

**Post-migration erasure obligations.** If you export candidate data to a staging environment or target ATS and then receive a GDPR erasure request, you must delete it from every copy — source, staging, and target. Your data warehouse is not exempt. Document your data flow so your DPO can trace where records live at each stage of the migration.

For a broader compliance framework, see our [GDPR & CCPA compliance guide for candidate data migration](https://clonepartner.com/blog/blog/ats-migration-gdpr-ccpa-compliance).

> [!NOTE]
> Greenhouse's Data Processing Addendum says all personal data in your account is automatically deleted **90 days** after the services agreement expires or ends, subject to Greenhouse's standard 30-day backup schedule ([greenhouse.com](https://www.greenhouse.com/data-processing-addendum)). Do not plan to extract during that window. Finish your export while your contract is active.

## What about ongoing integrations?

The v1/v2 removal does not just affect one-time data exports. If you use Greenhouse with Zapier, Make, Workato, Fivetran, Airbyte, or any iPaaS or ETL tool, those connectors must be on v3-compatible versions.

Zapier released Greenhouse version 2.0.0 for Harvest v3 and OAuth 2.0, and set August 26, 2026 as the date version 1.5.1 stops working ([help.zapier.com](https://help.zapier.com/hc/en-us/articles/47585848967437-Action-required-Update-your-Greenhouse-Zaps-before-the-Harvest-API-deprecation)). The update is not automatic. Each affected Zap must be switched to the new version and reconnected with an OAuth connection; Zapier says you cannot reconnect with a new API key.

Audit every tool in your stack that reads from or writes to Greenhouse:

- **Zapier / Make / Workato** — update to the latest Greenhouse connector version and re-authenticate with OAuth 2.0 credentials
- **Fivetran / Airbyte** — check connector config strings for `harvest.greenhouse.io/v1` or `/v2` endpoints and re-point to v3; verify that the connector release notes confirm v3 support
- **Custom scripts** — any script using Basic Auth headers or page-number pagination needs a full rewrite; find-and-replace does not address the authentication or cursor pagination changes
- **Stored pagination state** — flush all cached page numbers or v1/v2 pagination tokens before the version switch; they are meaningless in v3 and will cause unpredictable behavior if passed to v3 endpoints

## Validating the cutover

A successful migration requires multi-stage validation. Before signing off:

1. **Record-count parity.** Does the total number of Candidates, Applications, and Jobs in the target ATS match the total extracted from Greenhouse? Reconcile against Greenhouse's UI counts, not just your extract file — your extract may be missing GDPR-anonymized records or records created during the migration window.

2. **Referential integrity.** Pick a random sample of 100+ applications. Do they link to the correct candidate? The correct job? Are the scorecards attached to the correct application and interview stage? Automated spot-check scripts that traverse the relational chain and flag nulls are more reliable than manual review.

3. **Attachment validation.** Verify that resumes open correctly in the new ATS. A common failure mode is uploading a file with the wrong MIME type declaration, causing the target ATS document viewer to reject rendering. Check both that the file exists and that it opens.

4. **Field-level spot checks.** Compare custom field values on a sample of records between source and target. Type mismatches (e.g., Greenhouse multi-select array → target ATS text field) can silently truncate or null out values without import errors. Verify multi-select fields explicitly.

5. **Scorecard content verification.** Confirm that serialized scorecard data appears in the target's notes or feedback fields. Check that the structured content (attribute names, ratings, overall recommendation) is present and readable, not just that a note record exists.

6. **Delta sync.** The bulk load runs during the working days before go-live, while recruiters keep working in Greenhouse. On the go-live Monday, freeze Greenhouse before the working day starts and run a final delta sync — extracting only records where `updated_at` is after your initial extraction timestamp. The delta takes about 30 minutes, and recruiters log in to the new ATS that morning. If you configured webhooks during extraction, reconcile the webhook log against the delta sync to catch any gaps.

## Planning your exit: a scoping checklist

Before you extract a single record, answer these questions:

- [ ] **What is your Greenhouse contract end date?** Greenhouse's DPA deletes personal data 90 days after the agreement ends. Plan to finish your export before the contract ends.
- [ ] **What GDPR retention rules are active?** Check your retention and anonymization settings. Candidates may already be anonymized; know how many before you start.
- [ ] **Which API credentials exist?** Inventory all Harvest API keys. v1/v2 keys stop working once Greenhouse removes v1/v2. Create Harvest v3 OAuth credentials with read scopes for candidates, applications, jobs, scorecards, offers, custom fields, and attachments.
- [ ] **What integrations touch Greenhouse?** List every connected tool and verify v3 compatibility and re-authentication status.
- [ ] **What is your target ATS?** The data model translation work starts here. For help choosing, see our [Greenhouse alternatives comparison](https://clonepartner.com/blog/blog/top-greenhouse-alternatives-in-2026-pricing-tco-migration).
- [ ] **What custom fields exist?** Run `GET /v3/custom_fields` and document every field ID, name, type, and allowed values before writing any transformation logic.
- [ ] **Do you need attachments?** If yes, plan for inline downloads during extraction. If not, your extract is simpler and faster.
- [ ] **Do you need scorecards?** If yes, plan the translation into your target's feedback or notes model. Decide in advance how to map the five-value attribute scale onto the target's scale, or into text. If no, skip the scorecard endpoint and save API calls.
- [ ] **Do you need historical stage-transition data?** `GET /v3/application_stages` carries it, one row per stage with entry and exit timestamps ([harvestdocs.greenhouse.io](https://harvestdocs.greenhouse.io/reference/get_v3-application-stages)), but it adds extraction volume. Decide before scoping the pipeline.
- [ ] **What is your acceptable downtime window?** With background sync and a delta pass, source systems can stay live during migration. Define the cutover window before you start.

Start scoping **at least 3–4 months before your internal deadline** — whether that is a contract renewal or a board-mandated system cutover.

## Where ClonePartner fits

ClonePartner is an engineer-led migration service specializing in ATS data extraction and cross-system loading. Our process: connect accounts, produce a migration checklist specific to your Greenhouse instance (custom fields, attachment volume, scorecard count, GDPR-anonymized record count), run sample migrations until the data mapping is validated, execute the full migration, and finish with a delta sync. **One fixed price per project, starting at $500** — no hourly billing, no per-record metering.

A dedicated migration engineer owns each project. NDAs and DPAs available on request; BAAs before any PHI is processed. SOC 2 Type II and ISO 27001 audited. Staging databases auto-purge no later than 30 days after project close; AES-256 encryption at rest and TLS 1.2+ in transit. Details at [trust.clonepartner.com](https://trust.clonepartner.com).

If your engineering team is focused on product development, building and maintaining a Harvest v3 ETL pipeline for a one-time migration is a poor use of those resources.

> Book a free 30-minute scoping call. We'll map your Greenhouse data, identify the edge cases specific to your instance, and produce a fixed-price proposal.
>
> [Talk to us](https://clonepartner.com/talk-to-us?duration=30&utm_source=blog&utm_medium=button&utm_campaign=demo_bookings&utm_content=cta_click&utm_term=demo_button_click)

## Frequently asked questions

### When are Greenhouse Harvest API v1 and v2 being removed?

Greenhouse's documentation gives August 31, 2026 as the removal date for Harvest API v1 and v2. All integrations and export scripts must use Harvest v3, which requires OAuth 2.0 authentication instead of the old Basic Auth API keys.

### Can I export scorecards from Greenhouse to another ATS?

Yes, with mapping. Harvest v3 returns scorecards, per-attribute ratings and question answers from separate endpoints. Lever and Ashby both accept structured feedback through their APIs, but they rate on 1–4 scales, so Greenhouse's five-value attribute scale (including Mixed) needs an explicit mapping. Where a target cannot hold a field, serialize it into the feedback notes.

### Will a CSV export from Greenhouse work for an ATS migration?

Only for small datasets where you don't need attachments, scorecard data, or relational integrity. Report exports flatten the Candidate → Application → Job → Scorecard hierarchy into one row per application, leave out resumes and scorecard ratings, and show the current stage rather than stage history. Use the Harvest API v3 for any real migration.

### What is the Greenhouse Harvest v3 API rate limit?

Harvest v3 counts requests in fixed 30-second windows. Greenhouse returns the limit in the X-RateLimit-Limit header on every response, and its documentation uses 75 as an example. Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset from each response instead of hardcoding a number.

### How long does it take to migrate data out of Greenhouse?

The data migration itself typically takes 1–5 business days, depending on volume, complexity, and API rate limits. Small datasets under 10,000 records can finish in under 24 hours. This covers extracting and loading data — not the broader replatforming project of configuring your new ATS, which is a separate effort.
