What is a custom options sync?
A Custom Options Sync is an additional component that can be built as part of an HRIS integration. This is a per-field integration which will sync the pick list of options available for a custom field in Greenhouse Recruiting with the list of available options for a corresponding field in your HRIS. It can be set up on most custom single-select and multi-select job, offer, and candidate fields in Greenhouse Recruiting.
For example, if you create a custom job field in Greenhouse Recruiting called Cost Center that includes a list of all available cost centers in your HRIS, a custom options sync should keep the list of available options for your Cost Center field in Greenhouse Recruiting up to date with the cost center options available in your HRIS.
Note: This integration only syncs the list of available options one can select on a field, it does not sync job updates to Greenhouse Recruiting. Updating Greenhouse Recruiting job or position data should be part of the Job Import portion of the integration.
Which Fields Can You Enable Options Syncing For?
You can enable options syncing for any single-select or multi-select custom field type on any application (Advanced and Expert subscriptions only), candidate, job, or offer.
Users with a Site Admin permission level can access your organization's custom fields by clicking the Configure icon in the upper right-hand corner and navigating to Custom Options on the left-hand panel.
Options syncing is not available for the following fields:
- Any standard Greenhouse Recruiting job fields:
- Internal job name
- External job name
- No. of openings
- Requisition ID
- Opening IDs
- The following Custom Field types (since none of these field types have a pre-set list of options to select from):
- Currency/Number ranges
- Short/Long textbox
- Any Company Metadata fields:
- Candidate Tags
- Close Reasons for Job Openings
- Interviewer Tags
- Rejection Reasons
Offices and Departments can be partially modified via the Greenhouse Harvest API. Please click here to learn more.
How do I decide if a field needs a custom options sync?
We generally recommend setting up custom field syncs for fields whose options change often and would require frequent editing to stay up to date with what is configured in your HRIS.
If you are building a job import integration, it is important to keep in mind that in order to import a job field value from your HRIS that maps to a single-select or multi-select field in Greenhouse Recruiting, the value that you are importing must match an existing available option in Greenhouse Recruiting. An available option cannot be created in Greenhouse Recruiting just by importing the value from your HRIS on one position.
For this reason, it is important to make sure that fields with many available options in Greenhouse Recruiting are kept up to date with what’s available in your HRIS.
How do I build a Custom Options Sync integration?
The following Harvest API methods can be used to sync the list of option values for a field from your HRIS to Greenhouse Recruiting.
- GET: List Custom Fields: to retrieve the Greenhouse Recruiting custom fields and corresponding custom field IDs (the native Greenhouse custom field ID is required for the below requests)
- GET: List Custom Field Options: to retrieve the Greenhouse Recruiting custom field’s available option values and IDs (the native Greenhouse option IDs are required for the PATCH and DELETE requests below)
- POST: Create Custom Field Options
- PATCH: Update Custom Field Options
- DELETE: Remove Custom Field Options
Note: The Harvest API Custom Field Options endpoints now allow you to host external IDs on custom field option values.
How often do changes sync to Greenhouse Recruiting?
The team building the integration will be responsible for setting the frequency of the updates.
What happens if an option is deleted in your HRIS?
Greenhouse Recruiting cannot prevent users from deleting an option, even if it is currently in use on a job in Greenhouse Recruiting. You should use caution not to remove any field options from your HRIS unless you are absolutely sure they are no longer needed.
However, if the option has been selected as the field value on jobs in Greenhouse Recruiting, the field value will be maintained on individual jobs for historical purposes, unless the value is changed at the job level in Greenhouse Recruiting.