Greenhouse Okta Workflow Connector Migration Guide
Last Updated:
Overview
Greenhouse has updated their Application Programming Interface (API) to v3, bringing enhanced security, better filtering, and more robust data structures. To support these improvements, a new connector will be deployed. The Connector Listing in Workflows will display both Greenhouse Old (the legacy connector) and Greenhouse (the new connector), starting 21st July 2026. Because the underlying API, authentication methods, and data schemas will change, existing workflows must be manually updated to use the new connector cards.
Applies To
- Okta Workflows
- Greenhouse Old Connector
- Greenhouse Connector (New)
- Okta Classic Engine
- Okta Identity Engine (OIE)
Cause
Greenhouse upgraded their Harvest API from v1/v2 to v3. The new API requires OAuth authentication (replacing the standard API key) and introduces strict formatting and structural changes to payloads. Therefore, the old connector cards cannot be seamlessly updated in place and must be replaced.
Solution
How are existing workflows migrated to the new Greenhouse connector?
Migrate the integration by generating new authentication credentials, swapping the workflow cards, and reconfiguring the data mappings.
Step 1: Generate New Authentication Credentials
The new Greenhouse connector uses a more secure OAuth method. Generate new credentials in Greenhouse before updating the workflow.
- Log in to the Greenhouse UI and click the Configure icon on the navigation bar.
- Click Dev Center on the left panel, then select API Credential Management.
- Create a new credential and choose Harvest v3 (OAuth) as the API type.
- Select the appropriate Partner (or "custom" / "unlisted vendor" if applicable) and add a descriptive name.
- Click Manage permissions or View and store credentials.
- Copy the newly generated Client ID and Client Secret and store them securely to use when setting up the new Okta connection.
Step 2: Swap Connector Cards
- Locate the existing workflow containing Greenhouse Old connector cards.
- Create a duplicate of this workflow to safely test the migration.
- In the duplicated workflow, replace all Greenhouse Old cards with the new Greenhouse cards.
- Authenticate the new cards using the Client ID and Client Secret generated in Step 1.
Step 3: Reconfigure Data Mappings
Because the API changed, administrators must remap the fields based on the new connector behavior. Keep the following global changes in mind:
- Custom Fields Schema: Custom fields are now returned as highly structured JSON objects containing name, type, and value instead of raw flat payloads.
- Strict Timestamp Formatting: All Date/Time inputs (for example, Created Before, Updated After) strictly require the full ISO-8601 format, including date and time.
- Empty Field Handling: For List/ Search cards, Schema responses will automatically clear or omit fields that are empty, rather than passing null values.
- Error Handling: Error codes now align with standard REST practices. For example, duplicate emails throw a 409 Conflict, and invalid IDs in payloads throw a 422 Unprocessable Entity. Workflows must be updated to handle these new codes.
Step 4: Review Card-by-Card Changes
Update the inputs and outputs based on the specific changes made to each card below:
User Management Cards
|
Card Name |
Removed / Limited |
Added / Extended |
Changed Behavior |
|
Read User |
Removed standard "Email" lookup (must use Primary Email). Removed "Emails" array from output. |
Added Job Title, Agency Id, and Interviewer Tags to outputs. |
Disabled output renamed to Deactivated. Offices and Departments now output as lists of IDs instead of objects. |
|
Update User |
Option: Input:
|
Added Job Title and Interview Tag IDs to inputs and outputs. |
First Name and Last Name can now be left blank to clear data. External Office IDs changed from Number to Text format. User can only update details via ID |
|
List Users |
Output: Include Custom Fields and Output Emails removed |
Added input filters for Office Ids, Department Ids, Linked Candidate Ids, Interviewer Tag Ids, Is Deactivated, and custom filters. |
The streaming record limit is strictly capped at 500,000. Disabled output renamed to Deactivated. |
|
Add User Email |
Input: On behalf of User ID removed
|
N/A |
Re-adding an unverified email when Send verification is selected to No now throws a 409 Conflict. Reassigning same email to another user now throws a 409 Conflict. Passing an invalid User ID throws a 422 Unprocessable Content. |
Candidate Management Cards
|
Card Name |
Removed / Limited |
Added / Extended |
Changed Behavior |
|
Update Candidate |
Input: User ID, Recruiter and Coordinator removed from input Output: Removed "Status Code" output. |
Added Preferred Name, Timezone, Can Be Emailed and Linked User IDs to inputs and outputs. |
Outputs the full Candidate basic information profile upon successful update. Can Email renamed to Can Be Emailed. The Timezone output cannot be mapped directly to the input of another candidate card.
|
|
Read Candidate |
Removed the following from Output:
|
Added Preferred Name and Timezone to outputs. |
Can Email renamed to Can Be Emailed. The Timezone output cannot be mapped directly to the input of another candidate card. |
|
List Candidates |
Removed “Job ID” from Input Removed the following from Output:
|
Added input filters for Last Activity At, Tag, Is Private, and custom filters. Outputs include Preferred Name and Timezone. |
Inputting dates requires strict ISO-8601 formatting. Streaming limit strictly capped at 500,000. Can Email renamed to Can Be Emailed. The Timezone output cannot be mapped directly to the input of another candidate card.
|
Other Resources
- New Action Cards: To further support use cases, the new Greenhouse connector introduces two new cards: Search Applications and Search Attachments. These can be used to query specific candidate applications and documentation.
- Greenhouse Documentation: Refer to the Greenhouse Dev Center for further details on Managing Harvest API credentials permissions.
