Greenhouse

Greenhouse is an applicant tracking and hiring tool. They are a talent acquisition software company that offers its suite of tools and services to help businesses with the hiring process and features automated workflows, recruitment analytics, CRM, and onboarding.

Action required by August 31, 2026. Greenhouse is retiring Harvest API v1 and v2 on that date. Relyance connections that authenticate with the legacy Custom method (Harvest API Key + Ingestion API Key) stop working when Greenhouse turns v1 off. Set up new connections with Harvest v3 (OAuth), and move existing connections over before the cutoff — see Migrate an existing connection.

Relyance connects to Greenhouse through the Harvest API v3. To integrate it you need a Harvest v3 (OAuth) API credential from Greenhouse — a Client ID and a Client Secret — with the scopes listed below.

Permissions Relyance needs

To create the credential you must be a Greenhouse Site Admin, or a user whose permissions include Can manage ALL organization's API credentials.

Scopes. A Harvest v3 credential only reaches the endpoints whose scopes are ticked under Manage permissions. Relyance needs the list scope for each resource it classifies. Tick every scope in this table; a missing one does not fail the connection test, it fails the scan when it reaches that endpoint.

DSR only: add harvest:candidates:destroy (Delete candidate) if you enable Data Subject Requests on the connection. Erasure requests permanently delete the candidate and all of their applications, attachments, scorecards, notes and other associated records — Greenhouse cannot undo this. Leave the scope off for a discovery-only connection and the integration cannot delete anything.

Which user the credential acts as. When Greenhouse creates a Harvest v3 credential it also creates an integration service user that owns the credential, and Relyance acts as that user by default. Nothing else is needed. If your organization requires API activity to be attributed to a named person instead, you can enter that person's numeric Greenhouse User ID in Relyance; that user must be a Site Admin, and if the account is later deactivated the connection starts failing even though the Client ID and Secret are still valid.

In Greenhouse

1. Sign in to Greenhouse as a Site Admin (or a user who can manage all API credentials).
2. Click the Configure icon (the gear) in the navigation bar, then Dev Center in the left menu.
3. Click API Credential Management.
4. Click Create new API credentials.
5. Fill in the form:
   • API type: Harvest v3 (OAuth). Do not pick Harvest — that is the v1 key Greenhouse is retiring.
   • Partner: Custom (or unlisted vendor) — Relyance is not a listed Harvest v3 partner.
   • Description: something you will recognise later, e.g. Relyance AI.
6. Click Manage permissions and tick every scope in the table above. Add Delete candidate (harvest:candidates:destroy) only if you will enable DSRs. Click Save.
7. Copy the Client ID and the Client Secret and store them somewhere safe. The Client Secret is shown only once; if you lose it you have to create a new credential. The Client ID stays visible in the credential list.
8. Click I have stored the client credentials.

Optional — only if you need requests attributed to a named user: open Configure → Users, click the user, and copy the number at the end of the browser URL. That is the User ID for the Relyance form.

In the Relyance AI application

1. Login to your Relyance AI account.
2. Navigate to the Settings (bottom-left corner).
3. Select Integrations.
4. Search and locate the Greenhouse integration card and click on it.
5. Click on the Add Connection button on the top right.
6. Provide a meaningful name for the integration and click on the Add button.
7. In the Overview section, select the integration features you wish to enable for the integration, review the Scope and Permission, and Endpoint details and click on Continue. For more details, see Integration Features. If you enable Data Subject Requests, the Greenhouse credential must carry the Delete candidate scope described above.
8. In the Connection section, provide the appropriate values and click on Continue,
   • Connection Name: This property allows you to update the integration specified in Step 6. If you have multiple integrations for the same vendor, you may want to assign distinct names to each. This helps streamline filtering by Discovery Source across the Inventory, Visual Maps, Assets, and Data Flow Analysis pages.
   • Rescan Frequency: This property allows you to configure how often Relyance executes scans against this Vendor connection.
   • Business Atlas Associations (required): the business entities or products that newly discovered third parties, services and assets from this integration are attributed to. Choose at least one from the Select Associations dropdown — the wizard will not advance past this step without one. For more details, see Business Atlas.
9. In the Authentication section, choose Harvest v3 (OAuth) as the authentication method, then:
   • Harvest v3 Client ID: the Client ID from Greenhouse.
   • Harvest v3 Client Secret: the Client Secret from Greenhouse.
   • Harvest v3 User ID (optional): leave blank to act as the credential's integration service user. Fill it only if you need activity attributed to a specific Site Admin.
   • Click on Continue. Relyance exchanges the Client ID and Secret for a token and reads one page of candidates to verify the credential. If a scope is missing, the error names it (for example harvest:candidates:list) — add it under Manage permissions in Greenhouse and try again.
10. This step applies only if the Data Inspection check box was enabled in Step 7. In the Data Inspection section, provide the appropriate values and click on Continue,
    • Minimum Confidence Level: This property adjusts the sensitivity of the Data Inspection feature. Lower likelihoods (e.g., unlikely) offer more coverage but may produce false positives, while higher sensitivity (e.g., very likely) provides greater accuracy but less coverage.
11. Review the configuration summary from the Completion section and click on Finish.
12. Confirm the integration Status reflects Connected.

Migrate an existing connection

If your Greenhouse connection was set up with the Custom method (Harvest API Key, Ingestion API Key and On Behalf of Email), it uses Harvest v1 and stops working when Greenhouse retires v1 on August 31, 2026. Move it over before then:

1. In Greenhouse, create a Harvest v3 (OAuth) credential with the scopes above (the In Greenhouse steps). Keep the old Harvest and Ingestion keys active for now.
2. In Relyance, add a new Greenhouse connection with the Harvest v3 (OAuth) method (the In the Relyance AI application steps). Give it the same features (Data Inspection, DSR) and Business Atlas associations as the connection it replaces. Both connections can run side by side while you switch.
3. Wait for the new connection to show Connected and for its first scan to finish.
4. Delete the old Custom connection in Relyance, then revoke the old Harvest and Candidate Ingestion API keys in Greenhouse under API Credential Management.

Discovery sources, inventory entries and data-flow attribution follow the connection name, so give the new connection a name that makes the change obvious to anyone filtering by Discovery Source later.

What changes on v3, for anyone who audits the connection:

• Authentication is OAuth 2.0 client credentials (a short-lived token minted from your Client ID and Secret) instead of a static API key sent with every request.
• No Ingestion API key and no On Behalf of Email. Requests are attributed to the credential's integration service user (or the optional User ID), so the extra key and the live-user requirement go away.
• Per-resource scopes replace the v1 endpoint checklist. Records that v1 embedded inside a candidate — education, employment, attachments, notes — are separate v3 resources, which is why the scope list is longer than the v1 permission list was.
• Data Subject Requests run against the same v3 credential; only the Delete candidate scope is needed on top of the list scopes.

Legacy: Custom (Harvest API v1) — retiring August 31, 2026

These steps are kept for organizations that still have a Custom connection. Do not set up a new connection this way; Greenhouse will not serve v1 after the cutoff and the connection will fail. Follow Migrate an existing connection instead.

The legacy method needs two keys and a user email, and they do different jobs:

• Harvest API Key — reads candidates, applications, interviews and the demographic-question data. Its permission list must include the endpoints Relyance calls: list candidates, list applications, list interviews, and the demographics questions and answers.
• Ingestion API Key — used for the ingestion API; a Harvest key alone is not enough.
• On Behalf of Email — Greenhouse attributes API activity to a user, so this must be a live account. If that person is deactivated, calls start failing even though both keys are still valid. For DSR delete operations this account needs Site Admin permission in Greenhouse.

Generate the Harvest API Key: click the Configure gear → Dev Center → API Credential Management → Create New API Key; select Harvest as the API type; copy the key; click Manage Permissions and enable the endpoints above.

Generate the Ingestion API Key: back in API Credential Management, click Create New API Key; select Candidate Ingestion as the API type; select Relyance Inc. under Partners; copy the key.

In the Relyance connection wizard, choose Custom as the authentication method and provide the Harvest API Key, Ingestion API Key, On Behalf of Email and Maximum concurrent API calls.

Troubleshooting

• "Unable to authenticate to Greenhouse Harvest v3 - verify your credentials" — Greenhouse rejected the Client ID / Client Secret pair. Check for a copy-paste truncation; if the secret was lost, create a new credential (the secret is shown once).
• "Greenhouse Harvest v3 credential is missing required scopes: … (harvest:…:list)" — the credential authenticates but a scope is not ticked. The message names the scope. In Greenhouse open the credential → Edit → Manage permissions, tick it, Save, then retry the connection. Added scopes take effect the next time Relyance requests a token — a connection re-test does that immediately, and a running scan picks it up within the hour when its token expires. No re-authorization is needed on the Relyance side.
• Connected, but a scan finishes with nothing for one resource — the same cause: a list scope missing for that resource (Greenhouse answers 403 for it while the rest of the scan proceeds). Compare the credential's ticked scopes with the table above.
• Connection worked, then started failing — if you filled in Harvest v3 User ID, confirm that user is still active and still a Site Admin. If not, clear the field so the credential acts as its integration service user.
• Rate limits — Harvest v3 limits requests per 30-second window and token requests per 60-second window. Relyance paces its calls and backs off on 429 responses, so slow scans against a large Greenhouse tenant are expected and not an error.

Manage this integration with Terraform

Connections for this integration can be managed as code with the Relyance Terraform provider. Non-secret fields go in auth.params; secret fields go in auth.secrets_wo, which is write-only — never stored in Terraform state. Rotate secrets by bumping auth.secrets_wo_version.

API key

resource "relyance_integration_connection" "greenhouse_0" {
  vendor = "greenhouse"
  name   = "<your connection name>"

  auth = {
    method = "api-key"
    params = {
      ON_BEHALF_OF = "<ON_BEHALF_OF>"
      data_storage_location = "us"
    }
    # Secret fields are write-only: sent to Relyance, never stored in state.
    secrets_wo = {
      HARVEST_API_KEY = var.greenhouse_harvest_api_key
      INGESTION_API_KEY = var.greenhouse_ingestion_api_key
    }
    secrets_wo_version = 1
  }

  scans = { "data-inspection" = { enabled = true } }
}

Client ID & secret

resource "relyance_integration_connection" "greenhouse_1" {
  vendor = "greenhouse"
  name   = "<your connection name>"

  auth = {
    method = "client-credentials"
    params = {
      HARVEST_V3_CLIENT_ID = "<HARVEST_V3_CLIENT_ID>"
      data_storage_location = "us"
    }
    # Secret fields are write-only: sent to Relyance, never stored in state.
    secrets_wo = {
      HARVEST_V3_CLIENT_SECRET = var.greenhouse_harvest_v3_client_secret
    }
    secrets_wo_version = 1
  }

  scans = { "data-inspection" = { enabled = true } }
}