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 Recruiting.

In order to create the job through the API, you must identify the job ID of an existing Greenhouse Recruiting 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.

Greenhouse Recruiting's template jobs are simply regular jobs that have been marked as template jobs. Read more here: Best practices: Template jobs.

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:

  • Scorecard*
  • Interview plan*
  • Job post questions*
  • Hiring team
  • Notifications*

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 poost 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.

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 Recruiting 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 Recruiting 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 primary 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 primary template which combines all information from a few different templates. After a job has been created in Greenhouse Recruiting, 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.

Integration Development<

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 that dictates how jobs should be assigned to a particular template (for instance, all jobs in Cost Center A and Location A should be created using Greenhouse Recruiting template job A). 

Option 2: Create a single select custom object / field in HRIS which will pull in a list of all Greenhouse Recruiting template jobs using the Harvest API (template jobs should be categorized under a "Template" office or department so you can use the office/department parameter to filter the GET List Jobs response). When creating a job in your HRIS, a user should select the appropriate Greenhouse Recruiting job template from this dropdown.

Updating New Jobs in Greenhouse Recruiting Once the job is in Greenhouse Recruiting, you may need to update each section of the job individually (like 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 Recruiting, but the interview plans, scorecards, etc. can still be updated if needed.

Job 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 Recruiting 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.