If you’re building an API-driven job import integration with your HRIS, this guide is intended to help your team decide whether to create all new jobs using one existing Greenhouse Recruiting job as a template, or using multiple template jobs.
Why are existing jobs needed to create new jobs through the Harvest API?
Creating a job through the Harvest API is like using the Copy an Existing Job option when creating a new job as a user in Greenhouse.
In order to create the job through the API, you must identify the template job ID, that is, the ID of an existing Greenhouse job, that you want to use as the template for the new job. You cannot use a blank or sample template. However, the template job's status can be open, closed, or draft.
For context, Greenhouse's Template Jobs are simply regular jobs with a "template" flag.
This "template" flag is currently used to identify (or control) which jobs should be used as a base when creating a new job, and to allow users to exclude such jobs from reporting.
The selected Template Job can be used to populate parts of the job that cannot be configured via the API (denoted by *) and/or components that may be out of scope for your integration developer, such as:
- Interview Plan*
- Job Post questions*
- Hiring Team
The API will primarily be used to fill in the Job Info (including standard and custom job fields). Depending on the scope of your integration, the Job Post title and description and the Hiring Team may also be added through the API. However, be sure to check with your integration developer if you’re not sure which job data will be added through the integration.
A helpful visual to keep in mind when thinking about creating jobs via the API is the new job setup process in Greenhouse. Through the API you’ll add most Job Info seen in step 1, whereas the Template Job specified in your API request can be responsible for auto-filling most of the other parts of the job (steps 2-7):
Do all new jobs have to use the same template job?
No, your integration can create all new jobs using one template, or using different templates. We recommend working with your primary Greenhouse users and integration developer to decide which option will best fit your needs. Our recommendations and considerations are outlined below.
One Template vs. Multiple Template Jobs
|Considerations||One Template Job||Multiple Template Jobs|
|Summary||Recommended if your Interview Plans and Scorecards are relatively consistent across offices and departments, or if your team is comfortable with updating jobs in Greenhouse after they’ve been added through the integration.||Recommended if your job Interview Plans and Scorecards are highly varied across offices, departments, or other job criteria.|
Create one master template job that includes only the information that should be found on all jobs, as that information will be included on all new jobs created via the API. Any additional information that’s required can be added after the new job is imported from HRIS.
Alternatively, you can create one “Master” template which combines all information from a few different templates. After a job has been created in Greenhouse, you can go in and remove any stages/attributes that don’t apply.
|Create all necessary template jobs ahead of building the integration and share the relevant job IDs with your integration developer.|
|No integration logic is required- all new jobs will be created using the same template job.||
Option 1: Maintain custom integration mapping or integration logic which dictates how jobs should be assigned to a particular template (e.g. all jobs in Cost Center A and Location A should be created using Greenhouse Template Job A).
|Updating New Jobs in Greenhouse||Once the job is in Greenhouse, you may need to update each section of the job individually (eg. Scorecard, Interview Plan, etc.). However when editing a job, you can easily copy Interview Stages, Scorecard Attributes, and Job Post questions from other jobs.||Jobs added via the API will likely require less updates once they are in Greenhouse, but the Interview Plans, Scorecards, etc... can still be updated if needed.|
A Note on Approvals:
If there are no new job approvals configured for your organization, new jobs will automatically be added as Open. However if you have default approval flows configured in Greenhouse to open new jobs, then new jobs added through the API will be in Draft mode until they are approved. Each job will inherit the approval flows set for all new jobs, or for the Department and/or Offices the job is assigned to, if you have Department and Office specific flows configured.
If no Department and/or Offices are assigned in the API request to create the job, the new job will inherit the Department and/or Offices set on the template job and their corresponding default approval flows.