Permissions: Job Admin and above

Product tier: Available for Advanced and Expert subscription tiers

Note: The bulk import candidates tool also is available for organizations with the legacy Prospects or CRM feature enabled, and for all organizations during their first 90 days using Greenhouse Recruiting. 

Greenhouse Recruiting's bulk import candidates feature allows your organization to add multiple active candidates into your account from an external spreadsheet, and then upload a .zip file of resumes to be attached to the newly uploaded candidates.

Bulk Import Candidates Overview

Note: If an email address is provided, candidates added to jobs configured to comply with GDPR will automatically be emailed GDPR information once imported.

To begin, click the Configure icon Configure.png in the upper right corner of the page and choose Bulk Import in the left panel. 


Click Begin Candidate Import in the Candidates panel. 


On the next page, click Download Import Template to download the pre-configured template to your computer. 


Enter the candidate information in the downloaded spreadsheet. For best performance, we recommend importing no more than 8,000 candidates at a time.

When you have finished editing the template, click Upload Spreadsheet to begin the upload and mapping workflow.

Note: The following three fields are required for every candidate:

  • First name
  • Last name
  • Job 

While the Milestone column is not required, if no information is added to this column for a candidate, the candidate will be added to the first stage on the selected job.
Every job listed in the spreadsheet must be mapped to a job in Greenhouse Recruiting during the Map Jobs step. Candidates linked to unmapped jobs will not be imported.

For a more detailed look at entering information in the import template and completing the data mapping process, please review the following sections of this article: 


After you have finished mapping the data included in the spreadsheet, you will have the opportunity to bulk upload resumes for the candidates you are importing. Drag a single .zip file (or click Choose File) of all the resumes you wish to include in the bulk import onto the Upload Resumes page.

Note: The maximum supported size for the .zip file is 5 GB. Additionally, to be correctly imported, the .zip file cannot contain any subfolders. If another folder is inside the .zip file, the candidates will not import.


Click Finish Import to upload the spreadsheet and resumes


Greenhouse Recruiting will attempt to parse each resume and associate it with the appropriate candidate. If Greenhouse cannot attach a resume from the .zip file, you will receive an email detailing the issue. Resumes can fail to attach to candidates for the following reasons: 

  • The resume cannot be parsed at all
  • The resume can be parsed, but Greenhouse could not identify an email address on it
  • The resume can be parsed and Greenhouse can identify an email address, but the email address does not match any candidates included in this bulk candidate import

Once all candidates are imported, return to the Bulk Import page and navigate to the Previous Imports panel. Click View inline with the appropriate import event to explore a list of your newly imported candidates.


Each candidate imported via the bulk import tool will be tagged with a custom candidate tag denoting the date and time they were added to Greenhouse Recruiting. 



Map Default Candidate Fields

The import template includes columns for each of the default fields listed below. Input a candidate's information in each row you wish to populate. If you do not care about a particular standard field, or do not have that information, leave the column blank.


The import template includes columns for each of the following default fields: 

  • First name*
  • Last name*
  • Job*
  • Milestone
  • Company title
  • Notes
  • Email
  • Phone
  • Social media
  • Website
  • Address
  • Source
  • Who gets credit

* indicates a required field.

Note: If data is added to the Milestone field, the candidate will be added to the first stage of the selected Milestone. If no information is added to the Milestone field, the candidate will be added to the first stage on the selected job.

Only the following values should be added to the Milestone field; no other values are supported:
Face to Face

After uploading the completed spreadsheet, you will be prompted through the data mapping process. Follow the in-app instructions to map the columns in the spreadsheet to a field in Greenhouse Recruiting. Sample data from your spreadsheet will be displayed in the right-hand column to confirm the data being mapped. 


If you wish to omit a field from the import, click the icon inline with the field under the Spreadsheet Header column. Any data entered in that spreadsheet column will not be imported.



Click Verify Spreadsheet Data at the bottom of the page when finished mapping default candidate fields. 


The next several pages of the bulk import allow you to map Sources, Who Gets Credit, and the Job for the imported candidates. When you have finished mapping data for the default fields listed above, you will have the opportunity to map Custom Fields (if applicable).

Note: If you did not provide information for one or more of these fields in the spreadsheet, the corresponding data mapping step(s) will be skipped.


Map Custom Fields

When filling out the import template, you are not limited to entering information only for the default candidate fields. Custom application and candidate fields can be added to the downloaded import template as individual columns. These columns can then be mapped to the appropriate custom fields in Greenhouse Recruiting during the final stage of the upload process.


The bulk import feature supports the following custom application and candidate field types:

  • Single select
  • Long textbox
  • Short textbox
  • Number
  • URL
  • Yes/No

Note: In order to see private custom fields, the user performing the import must have the user-specific permission Can see private notes, salary info, manage offers, and approve jobs/offers on all jobs listed in Step 4 of the bulk candidate import flow. Without this user-specific permission on all jobs included in the bulk import mapping, the user can only map to standard custom fields.

Use the provided dropdown menu inline with each spreadsheet custom field to select a corresponding custom application field or custom candidate field. Sample data from your spreadsheet will be provided in the right-hand column to confirm the data being mapped.


Each custom field must pass data validations. The following issues can result in a failed import: 

Field type Validation issue

Single select

If the Greenhouse custom field you are mapping to is a single select type, the values input in your spreadsheet for the mapped column must match the exact options available for the Greenhouse custom field.

Note: If a custom field's option values for a single select field type are decimal numbers (e.g., GPA), Greenhouse recommends you validate the data in the column for decimal numbers. By doing this, you can ensure that your spreadsheet editor does not automatically round numbers to the nearest whole number (e.g., 4.0 can be expressed as 4), which would misalign values in your spreadsheet and the available options for the Greenhouse custom field.

Number If the Greenhouse custom field you are mapping to is a Number type, the values input in the your spreadsheet for the mapped column must be expressed as a number (e.g., 3 instead of three). Greenhouse will accept symbols in the number (e.g., comma, period, $, %, etc.).
Yes/No If the Greenhouse custom field you are mapping to is a Yes/No type, the values input in the your spreadsheet for the mapped column must either be Yes or No (values such as Y or N will not be accepted).
URL If the Greenhouse custom field you are mapping to is a URL type, the values input in the your spreadsheet for the mapped column must be expressed as a URL.



When finished mapping custom fields, click Verify Data


Auto-Merge for Bulk Imported Candidates

If Auto-Merge is enabled for your organization, candidates added through bulk import will be assessed by Greenhouse Recruiting against your organization's candidate database.

If Greenhouse Recruiting finds a duplicate email address, the added candidate will be merged with the existing profile. You will see all of the candidate's job application(s) listed under the bulk candidate import tag.

Note: If the source for a candidate added through bulk import is Referral or a specific agency, the imported candidate will not be merged, even if it otherwise meets Auto-Merge conditions.

The profiles for both the imported candidate and the original candidate will display a potential duplicate alert, and your team can merge the profiles manually if appropriate.

Click here to learn more about cases where Greenhouse Recruiting will not Auto-Merge.