Skip to main content

User Sync Integration


SmartRecruiters' User Sync connector allows customers to maintain their employee population in synchronization with SmartRecruiters in Real-time. This integration enables customers to create, update, activate/deactivate, and provision/deprovision employees.  Please contact your CSM for additional information.

User Sync Integration

  • SmartRecruit

This is a paid offering. Please contact your CSM for additional information

NOTE: SmartConnect solutions are no longer being offered, though these pages will remain active until all contracts for legacy customers have expired. Please contact your CSM for alternative integration offerings. 

SmartRecruiters is pleased to offer a connector that will allow customers to maintain their employee population in synchronization with SmartRecruiters in Real-time. This integration enables customers to create, update, activate/deactivate and provision/deprovision employees using the User Sync connector.

SmartRecruiters API Token: This integration requires an API Token. Navigate through the following links in order to generate a key:

 Settings / Admin → Apps & Integrations → CREDENTIALS

Screen Shot 2021-07-21 at 11.21.35 AM.png

Data Transfer Protocols
FTP or API Endpoints supported. Choose from the following options:

  • Customer’s FTP or SFTP (SSH encryption available)
  • Customer’s API Endpoint
  • SmartRecruiters API Endpoint
  • SmartRecruiters SFTP (see the end of this page for setup)

SFTP & FTP Method

  • File consumption (the customer will upload the file into the FTP or SFTP and the integration will consume the file based on a scheduled frequency)

Endpoint HTTP Methods 

  • GET (Fetch): The integration will pull data from an Endpoint (in real time or on a schedule)
  • POST: The customer will push data to SR’s Endpoint (in real time)

Data Payload

The are two file formats supported: CSV or JSON
In order to create a User in SmartRecruiters the following fields would be needed:

  • First name (*required by SmartRecruiters)
  • Last name (*required by SmartRecruiters)
  • Email (*required by SmartRecruiters)
  • Role (*required by SmartRecruiters)
    *SR standard or custom roles. For custom roles, please use the System Role ID code, found through the User API. 
    *Mapping done by label matching
    *If customer doesn’t have System Roles they can choose a default in SmartConnect in order to create a user
  • Employee ID (optional)
    *Recommended as unique identifier between platforms. Find more details regarding the unique identifier below
  • SSO (optional)
    *SAML 2.0 Protocol. SSO must match exactly the identity provider
  • Access Group (optional)
    * Label must match SR’s access group
  • Status (optional)
    * Activation/Deactivation can happen upon removing users from the file. This option must not be checked on the “User list will only contain active users” checkbox on the Project Configuration section
    * Activation/Deactivation can be set to automatic or manual from Project Configuration section. If manual, manage user population status  from User Management in SmartRecruiters. If automatic, status can change either by file drop off (file will contain only active users) or with a status flag. The following status flags are supported:
    -True or false
    -Active or Inactive
    -A or I
    -1 (true) or 0 (false)
    -Date ( when matches today’s date deactivate user). Must be expressed in ISO 8601 format
    Example: Maternity is Feb 26, 2021, Today Feb 15th, 2021, not deactivate
  • Language (optional)
    *Language code must be expressed in ISO 639-1 format (2 letters)
  • City (optional)
  • Country (optional)
    *If used, City and Country must be specified. Country uses 2 digit ISO Code

Screen Shot 2021-07-21 at 11.23.15 AM.png

NOTE: If any field is blank on the payload, the integration will not perform updates and remain Smartrecruiters data as is. This feature would fit customers that would like to maintain the User statuses or roles manually from SR

NOTE: Delta Files (files containing only recent users that need to be created or updated) are supported. If using deltas, the “Only Active Users” option must not be checked. 

Unique identifier: As best practice using the employee ID is recommended (or similar unique ID on your HRIS), mapped to the externalData field. If your HRIS does not hold any IDs then the email could be used as well (in this case emails wouldn’t be able to be updated as they must stay unique)

employeeID → externalData

Special Characters:
(', ')', '[', ']', ''','\"', '.', '/', '-', '.', ',', '&', '@', '_', '#, '$, '*'', and accented characters) these special characters are not supported by SmartRecruiters.

Supported Special Characters will be included in syncs, processed as strings. For example, John "Doe Jr." would be added to SmartRecruiters as John "Doe Jr.", not John Doe Jr. 

File path: Indicate the directory path where the file will be located (ex: /integrations/user/)

NOTE: SmartRecruiters recommends that a project folder is created for each integration. Example: /user

File naming convention: There is no need to name your file, it should be placed inside the directory that has been specified on the “File path”. Once the integration processes the file it will rename it to: [DONE]_Users_date.csv

Updating data: The integration allows customers to update every data point being sent except the Unique Identifier. As best practice, the source of truth should always be the data belonging to the HRIS. There are some exceptions:

  • If the System Role column is empty then the customer will be able to change a user role from SmartRecruiters without the integration overwriting the value

NOTE: This integration, once activated, will create or update users in SmartRecruiters. In case of existing users it will cause updates if  there are data differences between platforms. The customer’s HRIS should always be the source of truth. If users have been previously created manually most likely they will not have a unique identifier, in this case the customer should work with the Support Team to insert the employee ID into the users for the sync to recognize them. 

User Integration Configuration in SmartConnect

1. Click on “Create Sync” in order to start the process of configuring the connector
Screen Shot 2021-07-21 at 11.24.01 AM.png

2.Selecting Transfer Protocol Methods. See below for the FTP & SFTP or the API Endpoint option

  • Protocol Method: Choose the Transfer Protocol Method
    Screen Shot 2021-07-21 at 11.24.35 AM.png
    - Endpoint (API Method)
    - Customer’s FTP o SFTP (SSH encryption available)
    - SmartRecruiters SFTP (SSH encryption available)

  • Format: Choose a file format (CSV is recommended if using an FTP or SFTP)
    Screen Shot 2021-07-21 at 11.25.19 AM.png

  • Project Name: Choose the desired name of the project
    Screen Shot 2021-07-21 at 11.25.55 AM.png

  • Insert SmartRecruiters API Token
    Screen Shot 2021-07-21 at 11.26.34 AM.png

  • FTP & SFTP Option: (For customers using their own FTP or SFTP)
    Screen Shot 2021-07-21 at 11.27.11 AM.png

  • Connectivity Variables: Insert the host URL, Username, Password and Path where the file will be located
    Screen Shot 2021-07-21 at 11.27.50 AM.png
    NOTE: The SSH Key is Optional on SFTP
    Screen Shot 2021-07-21 at 11.29.06 AM.png

SmartRecruiters  SFTP Option: (For customers using SmartRecruiters SFTP)

  • Connectivity Variables: Insert the host URL, Username, Password, Path IN (where the file will be located) and Path OUT (where processed files and logs will be sent)
    Screen Shot 2021-07-21 at 11.30.08 AM.png
    NOTE: The SSH Key is Optional if needed
    Screen Shot 2021-07-21 at 11.29.06 AM.png

Endpoint Option:
Screen Shot 2021-07-21 at 11.32.18 AM.png

3. Integration & File Configuration
Screen Shot 2021-07-21 at 11.33.21 AM.png

  • Choosing Unique Identifier
    Screen Shot 2021-07-21 at 11.34.13 AM.png
    NOTE: EmployeeID is recommended. In case of not having an EmployeeID then Email would have to be the unique ID. Note that if the Email is selected, then updates will not be possible in this field as they must remain unique

  • User list will contain only active users
    Screen Shot 2021-07-21 at 11.35.27 AM.png
    If this selected, the integration will deactivate users that have been removed from the file and that exist in SmartRecruiters

  • Handling System Roles manually from SmartRecruiters
    Screen Shot 2021-07-21 at 11.36.30 AM.png
    If selected, the integration will not update System Roles. SmartRecruiters will be the source of truth when it comes to user roles.
    NOTE: the customer would want to select this option only if they don’t have System Roles on their HRIS or if they can’t have them shown on the file payload
    If Handle System Roles manually is selected, the following options will be enabled. Choose a default System Role when users are created in SmartRecruiters: 
    Screen Shot 2021-07-21 at 11.37.16 AM.png

  • Handle Users statuses manually from SmartRecruiters
    Screen Shot 2021-07-21 at 11.38.26 AM.png
    If selected, the integration will not update statuses of users. SmartRecruiters will be the source of truth when it comes to activating and deactivating users

  • The customer can choose to receive the integration run logs via email or through the FTP/SFTP
    Screen Shot 2021-07-21 at 11.39.09 AM.png
    Email Log: will allow customers to specify multiple email addresses 
    Screen Shot 2021-07-21 at 11.40.01 AM.png
    File Log: will allow customers to receive the integration logs via FTP or SFTP

4. The User has to map the data points from the file to match the fields in SmartRecruiters

  • Select on “Edit Mappings” in order to open the field mapping section
    Screen Shot 2021-07-21 at 11.40.52 AM.png

  • Click on “ + SELECT A NEW SAMPLE FILE” to use a sample file that contains the schema you will use OR you can also map the fields manually by dragging and dropping the fields from  the left to the right or clicking on the select circle from the left then selecting the matching field on the rigScreen Shot 2021-07-21 at 11.41.34 AM.png

  • Upload your CSV or JSON file
    Screen Shot 2021-07-21 at 11.42.30 AM.png

  • Check the box “First line as header” if the Row 1 of your file contains the field names otherwise leave it uncheckedScreen Shot 2021-07-21 at 11.43.18 AM.pngScreen Shot 2021-07-21 at 11.44.18 AM.png

  • Review and click on “SAVE”:
    Screen Shot 2021-07-21 at 11.45.29 AM.png

  • Mapping the fields from the source (customers fields specified on the file) and the target (SmartRecruiters fields):
    Option 1: Drag fields from the left column to match the fields on the right column
    Option 2: Click on a field from the left column, then click on the desired field from the right column and click “MAP SELECTED FIELDS”Screen Shot 2021-07-21 at 11.46.50 AM.png 
    NOTE: SmartRecruiters recommends using the employeeID as the unique identifier and have this mapped to externalData. If the customer does not have employeeID or similar, then select the email address as unique ID.

  • Verify the selected mappings and click on “SAVE”:
    Screen Shot 2021-07-21 at 11.48.02 AM.png

  • Click on “→NEXT STEP” to continue to the Scheduling section:
    Screen Shot 2021-07-21 at 11.48.42 AM.png

5. The user has to create a schedule for the integration to start running

  • Click on “+ ADD SCHEDULE” 
    Screen Shot 2021-07-21 at 11.49.23 AM.png

  • Select a schedule name (optional, there will be a defaulted one)
    Screen Shot 2021-07-21 at 11.49.55 AM.png

  • Select a Start Date for the Integration to start working:
    Screen Shot 2021-07-21 at 11.50.49 AM.png

  • Add the Frequency in which the integration will run. You can also enter your own Cron expression for scheduling. 
    Screen Shot 2021-07-21 at 11.51.41 AM.png

  • Verify the schedule and click on “SAVE”
    NOTE: Times are displayed in the user's local time, but when entering times, please use UTC (Coordinated Universal Time)
    Screen Shot 2021-07-21 at 11.52.27 AM.png

  • Click on “FINISH SYNC” to complete the setup process
    Screen Shot 2021-07-21 at 11.53.20 AM.png

  • Users are able to run the integration manually by clicking on “MANUAL START SYNC” after setting up the schedule

    Screen Shot 2021-07-21 at 12.39.11 PM.png


Using SmartRecruiters SFTP

SmartRecruiters offers customers an SFTP (paid offering) in case they do not have one on their end. The following steps are required in order to request access to it:

NOTE: If you already have a SmartRecruiters SFTP that is being used on a different connector then move on to Step 4.

  1. Contact your CSM or Implementation Manager and request the SFTP service

  2. Provide them with a password that will allow to access the SFTP
    NOTE: The username will be automatically created for the customer
    NOTE: The password will be used for SmartRecruiters to login and access the file as well

  3. Provide them with the IP address/addresses that will be used to connect. These IP addresses will get whitelisted  in order to access granted.
    *CSM or Implementation Manager will submit a request for an SFTP using the provided information. Once it has been approved, the customer will receive the following details:
    -- SFTP host URL
    -- Username

  4. Log in to the SFTP and you will find two folders /in and /out

  5. Inside /in create a new folder and name it after the connector 
    NOTE:  We recommended that the folder name is user_sync. 

*The SFTP’s data centers are currently hosted in Europe. Please let know your CSM or Implementation Manager in case that it is a requirement on your end for the data center to be located in the USA



FTP: file transfer protocol

SFTP: secure file transfer protocol

SSH Key: Secure Socket Shell (SSH) Key Management, also called Secure Shell Management, is a special network protocol leveraging public-key cryptography to enable authorized users to remotely access a computer or other device via access credentials called SSH keys

API: application programming interface

Endpoint: a URL that enables the API to gain access to data on a server

Unique Identifier: an id that is shared between systems in order to identify a user