This article outlines the main steps to Integrate SmartRecruiters with Enboarder. Current Integration supports one function: 'Hire'. This event in SmartRecruiters will start a workflow in Enboarder.
Before you begin: Like anything worth doing, integrations take time. Please allow up to 4 weeks for this integration to be completed, this includes time for scoping, development and testing. You’ll also need to have a system expert and/or system administrator to assist in the completion of this integration.
Note: If your Enboarder Instance has parent and child accounts created, you'll need to set this integration up on each one. This is where the filters are useful (to prevent employees from launching in multiple systems). Speak to your Customer Success Manager for more information on this.
To perform steps in Enboarder, the user role should be 'Administrator'
To perform steps in SmartRecruiters, the role of the user must be 'Admin'
Setting Onboarding Status in SmartRecruiters
Login as 'Admin' in SmartRecruiters
Clicks on 'Settings/Admin'
Navigate to the Configuration section, and click on 'Candidate Fields'.
Click on 'Add Field', then select the field 'Onboarding Status'. Tick 'New Hire Form' to have this field appear on the New Hire Form.
Setting up connection
Login to Enboarder to create a connection with SmartRecruiters:
Login as an Admin user and go to Settings > Integration > App Center
Click on the tile (or search if you can't see it) for which you want the integration setup.
Click on 'Add Integration'.
You'll then need to configure the below options as per your business requirements:
Select if integration needs to connect to Production account or New Sandbox account. Production is default.
Select 'Only trigger with email, do not import mobile numbers' if you don’t want Enboarder to import a mobile number for the new hire or other stakeholders
Set how frequent the polling intervals are and also if any filter (optional) has to be applied.
Please tick the checkbox "I have enabled onboarding status in Smart Recruiters", once you have enabled the onboarding status in SmartRecruiters.
Click 'Add Integration'
Note: If you are wanting to use a filter based on candidate properties, then please find more detail at the end of this article on how to get propertyId and propertyValueId.
When the new tab opens up, fill in your username and password, then authorize.
Following an instance being created, it will prompt for SmartRecruiters credential login details.
Once logged in, request for information access will be asked. Once this is allowed, the instance will be setup, and the integration is completed.
It’s crucial that the identical fields are set up in Enboarder that are used in SmartRecruiters. The basic fields required to launch a workflow are: New Hire name, New Hire contact, Manager name, Manager contact and New Hire start date.
In Enboarder, clicking into the settings tab allows you to view and set up branding, locations, categories and custom fields. The mapping exercise involves ensuring whatever is created here matches what is in SmartRecruiters.
Where relevant: Custom fields for Source type, Source sub-type and Source are the same as shown on the SmartRecruiters 'Add Candidate' screen. The label for Job reference code in SmartRecruiters is REF code, with it coming as 'refNumber' in the api. Make sure to create a custom field with the same name that is coming in the API response i.e. refNumber (see below). See here how you can create custom fields in Enboarder.
You can create multiple workflows in Enboarder, and will often have criteria on these (such as location). When criteria is sent from SmartRecruiters, Enboarder will launch the new hire into a workflow that matches this criteria.
General Integration Notes
The system is picking location from the location on the Job. The location may contain address, city, country, region, region code. Enboarder will match the values in the below order. The location name in Enboarder needs to consist of all of these fields that you are sending over:
Address > City > Country > Region > RegionCode
Using Default Role
Enboarder is calling SmartRecruiter's Hiring Team API to receive the Hiring Manager's information. Enboarder is able to fetch the following managers' from SmartRecruiters:
These are defined in SmartRecruiters, and will automatically be mapped in Enboarder if these manager roles have been created. See here how to create managers' in Enboarder.
Using Custom Field - Type 'User Picker'
If you need other custom roles on top of the above roles, you can add these using the custom field type 'User Picker' in New Hire form in SmartRecruiters. Enboarder will map these user's with manger's that you have created in Enboarder.
Note: In the above two methods, mobile contacts will not be populated for these managers', as SmartRecruiters does not provide a field to enter a mobile number for these users. If there is any requirement to add mobile numbers for these managers', please see below.
Mapping Extra Managers via Custom Fields
To map extra managers' with mobile numbers or emails, custom fields should be used in SmartRecruiters. The convention to be used for 'Immutable Field Key' value of the custom field should be a lower case manager label of what is defined in Enboarder, with spaces converted to “_”. For example below, if the manager label in Enboarder is Report To Manager, the Immutable Field Key in SmartRecruiters should be report_to_manager.
To define Mobile or Email for these manager user's, the Immutable Field Key name convention should be the same as the manager label above, however suffixed with _mobile or _email. For example below, report_to_manager_mobile.
These custom fields should be defined as candidate fields in SmartRecruiters and added on new hire form.
Customisation for hires to be ignored OR launched in Enboarder
A custom field Push To Enboarder can be created as a candidate field within the hiring section of Smart Recruiters and actioned with the respective values before the candidate is hired.
Here are the steps to add this custom field to ignore candidates in Enboarder.
Go to Settings → Configuration → Candidate Fields
Create new custom field with title "Push To Enboarder" with type "yes/no" as shown below.
On hire form, select its value as No if you want Enboarder to ignore this candidate being launched.
Triggering new hires into Enboarder from SmartRecruiters
When in a job, and selecting a candidate as ‘Hired’, a workflow will launch in Enboarder, bringing with it all of the criteria that was listed in SmartRecruiters.
You can investigate mapping issues very easily, with the API response being available in Enboarder. Go to Settings -> Integration -> Audit logs to view the complete payload. There will be multiple rows. One contains the complete response message, with the other providing the rest of the candidate information for that workflow.
Click on the row with the blank employee name to view the complete payload.
How to get candidate propertyId and propertyValueId in SmartRecruiters
If you are using a SmartRecuiters Sandbox account (sandbox.smartrecruiters.com), you will need to ask SmartRecruiters to assist in providing the IDs.
If you are using a SmartRecruiters production account you will need to call some APIs. SmartRecruiters have web APIs available, which allows you to retrieve these using your SmartRecruiters apikey. Please see these articles for more detail:
SmartRecruiters - Sign-in
To get the SmartRecruiter api key, log in to your SmartRecruiters account and go to Settings/Admin → Company Settings → Apps & Integrations
On the next page select 'Credential tab' and click on 'New Credential' button
Select 'API key' and click 'Next'
Provide a name and description and click on 'Generate'. Note down the key on the next page
Please note that API credentials generated in NewSandbox accounts cannot be used in Dev Portal. Please use another external tool to run NewSandbox APIs.
Go to the Overview page and then select configuration API for Candidate Properties.
Click 'Try it!' and then 'Execute:
Copy the corresponding property id from the response
Using the id in the above response, call the Property values API to get the property values ids.
From the above response, property value ids are available. Pick the correct value id and add this to your Enboarder integration setup
When using the filters, it's possible to use multiple criteria. This will use an "OR" logic, for example:
Parent Child Mapping
If you have multiple Enboarder accounts, in order to launch workflows in any account, SmartRecruiters integrations need to be configured with every Enboarder child account. In order to make this easier for you, the data should flow from SmartRecruiters to the Enboarder parent account, and then be pushed to the Enboarder child accounts based on criteria in the payload.
Parent-child flow from SmartRecruiters integration
A custom field with name subsidiarycompanyid will need to be created in SmartRecruiters and added to the new hire form section. You will need to define some values for this field
Once you have configured this, please provide these details to your Enboarder account team so that they can have these configured for your Enboarder account
When a candidate is created in SmartRecruiters, a value will be set up in this field in the offer section
When the candidate is moved to the hired stage, the Enboarder webhook is called
Enboarder will then check the value of subsidiarycompanyid. If the ID matches with any of the child accounts:
The workflow will be launched in that account
If no match is found, it will launch in the parent account
Set up in Enboarder
We need a mapping of your child account names and the unique ID of each child account. The child account ID can be any ID that is unique per child account and available in SmartRecruiters. This ID will be used to find the child's account in Enboarder. The ID can be alphanumeric or a string. It should be passed to our system as a string.
Example: You have 3 child accounts in Enboarder and are using the office location city as child ID (assuming you have only one office per city). You will send us the below data in a CSV file:
Child Account Name
Set up in SmartRecruiters
You will need to create a custom field in SmartRecruiters with label subsidiarycompanyid. This needs to be a text field. The values of this field should be the same as that you have provided to Enboarder (e.g Sydney, Brisbane, London)
Go to Settings → Configuration → Candidate Fields and create this field.
When in the hiring section, fill the values as shown below: