Permissions: Job Admin and above

Product tier: Available for Advanced and Expert subscription tiers

Note: The candidate bulk import tool is also 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 feature allows your organization to add multiple active candidates to your account from an external spreadsheet, then upload a .zip file of resumes that attach to the newly uploaded candidates.

Download import template

To download a bulk import template, click the Configure icon on your navigation bar and choose Bulk Import on the left.

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.

Complete candidate import template 

The pre-configured import template includes columns for each of the default fields listed below. Input a candidate's information in each field 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 First name, Last name, and Job fields are required. 

While the Email column is not required, if candidate resumes are uploaded as part of the import, an email must be provided to map the resumes to the candidate. Additionally, candidates added to jobs configured to comply with GDPR will automatically be emailed GDPR information once imported.

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.

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 of the selected job.

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

  • Application
  • Assessment
  • Face to Face
  • Offer

Note: You are not limited to entering information for the default candidate fields only. Custom application and candidate fields can be added to the downloaded import template as individual columns. For more information on this step, please visit the Map custom fields section of this article. 

After editing and saving the template to your computer, click Upload Spreadsheet to begin the mapping workflow. 

Map default fields

After uploading the completed spreadsheet, you'll be guided 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 X 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.

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. Furthermore, if you need to save your progress click the X icon in the top-right corner of the Import page. The import will display as Incomplete on the Previous Imports table. You can finish your import by clicking Finish Import inline with your upload.

The next stages of the mapping workflow allow you to map Sources, Who Gets Credit, and the Job for the imported candidates. 

Map custom 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.

Please keep in mind, the custom fields you add to your import template must match the custom fields in your Greenhouse Recruiting. Visit our support articles to learn how to create new custom application fields and add custom candidate fields in Greenhouse Recruiting. 

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

  • Short textbox
  • Long textbox
  • Number
  • Single select
  • 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 the Map Jobs step 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.

As you fill out your custom fields, please keep in mind that each custom field must pass data validation during the mapping workflow. The following issues can result in a failed import:

Field type

Validation issue

Single select

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

Example: If the option for a single select custom field is a decimal number (for example, GPA), Greenhouse recommends you format the data in the column as a decimal number. By doing this, you can ensure that your spreadsheet editor does not automatically round numbers to the nearest whole number (for example, 4.0 instead of 4), which would misalign values in your spreadsheet with the available options for the Greenhouse custom field.


If the Greenhouse custom field you are mapping to is a Number type, the values you input into your spreadsheet must be expressed as a number (for example, 3 instead of three). Greenhouse will accept symbols in the number (for example, comma, period, $, %, et cetera).

Yes/No If the Greenhouse custom field you are mapping to is a Yes/No type, the values input into 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 you input into your spreadsheet for the mapped column must be expressed as a URL.

Once you are on the Map Custom Fields stage of the mapping workflow, use the provided dropdown menu inline with each field and 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.

Click Verify Data to finish the custom mapping process. 

Upload resumes

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. The bulk import feature supports subfolders in the .zip file for nesting resumes in different folders.

Finish Import to upload the spreadsheet and resumes.

Note: 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

Upload statuses

Once all candidates are imported, return to the Bulk Import page and navigate to the Previous Imports panel. This panel will show all your recent and historical uploads including their upload status. 

The following is a list of the upload statuses and their meanings:

Status What does it mean?
Complete The spreadsheet import, mapping workflow, and resume uploads are complete. 


The spreadsheet is uploaded, but the initial Map and Verify stage of the spreadsheet data is required. Click Finish Import to complete the process. 
Incomplete The uploaded spreadsheet data is verified in the initial Map and Verify stage, but the subsequent stages in the mapping workflow are required. Click Finish Import to complete the process. 
Enqueued The mapping workflow is complete and system processing will begin momentarily. No action is required.
Running Greenhouse Recruiting is processing the import, including resume matching to candidate profiles if provided during the Upload Resumes stage. No action is required.

View imported candidates

Click View inline with the appropriate import to explore a list of your newly imported candidates.

Each candidate imported via the bulk import tool will be assigned a custom candidate tag with the date and time they were added to Greenhouse Recruiting. You can modify this tag to match your preferred description by following the steps outlined in our Create candidate tag support article.

Reattach resumes

In the event that candidate resumes were missed or malformed, or if you uploaded the wrong .zip file, you can attach resumes again by clicking Reattach Resumes.

Auto-merge 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 when Greenhouse Recruiting will not Auto-Merge.

Additional resources