Skip to main content
SmartRecruiters

Set up Microsoft Exchange Calendar integration

Requires:
  • SmartRecruit

 

In order to set up the Microsoft Exchange Calendar integration, you'll need to have:

  • an Administrator-level account in SmartRecruiters,
  • a Microsoft Exchange version 2010 or later, and

You'll also need to create a SmartRecruiters user account (service account) on the Exchange server.

The Exchange integration is flexible in terms of data access permissions. When you enable our Exchange calendar integration, you give the service account created for SmartRecruiters permissions to read and write calendar events in your organization. You can limit the access scope of the service account to specific users if you prefer.

There's also an option to allow service account to create events on behalf of other users. That is optional, but preferred by many customers, since it makes it clear to interview participants which recruiter scheduled an interview.

Create service account

Talk to your Microsoft Exchange Server Administrator to have them set up the SmartRecruiters service account, and to determine which Exchange version you're using.

When creating the Exchange service account:

  • Give the account the username of your preference, but make sure that the account's domain matches that of your employees' email address. For example, if your company's name is Acme Corp, and employees have an @acmecorp.com domain for their emails, set the service account's email to sr-calendar-integration@acmecorp.com.
  • Make sure the account has a Mailbox and Calendar.

If your company has its own Exchange server, make sure to ask your Server Administrator for the server's Service URL. 

To expedite the process, reach out to your Account Manager or SmartRecruiters Support.

Add credentials to SmartRecruiters

After you've created the SmartRecruiters service account on your Exchange server, you'll need to add this account's credentials to SmartRecruiters.

Screen Shot 2020-02-13 at 10.48.24 AM.png

  1. In the Admin / Settings page of SmartRecruiters, click App & Integrations under Administration and select Microsoft Exchange Calendar Integration
  2. Enter the service account's email and password.
  3. If your company has its own Exchange server, enter the Service URL in place of the default URL. Otherwise, leave the default URL. 
  4. Specify which Exchange version you’re using. Available options are:
    • Exchange 2010
    • Exchange 2010 SP1
    • Exchange 2010 SP2.

If you're using Exchange 2013 or later, choose Exchange 2010 SP2 from the list.

  1. Click Save, then Load Resources. 

If the setup is successful, you'll see a list of searchable rooms and resources available to reserve from your calendars. If so, contact Support to finish the integration.

Exchange API limits calendar queries to 100 resources.  If your company has more than 100 resources, you will have to organize them in room lists to display/search all.

You can find more information about room lists creation here: https://docs.microsoft.com/exchange/...te-a-room-list

  1. Click Save, then Load Resources. 

Use scheduler's name

Normally, with an active Exchange integration, SmartRecruiters will add/edit/delete calendar events using the Account Email address used to set up the integration.  When the Use scheduler's name option is activated, SmartRecruiters will use name of the actual user who makes those changes, instead of the name of the account used to set up the integration.

Here’s an example of the option in action:

With Post as Scheduler:

  • turned off, user@integration.com will be listed on the calendar event as the user who created the event.
  • turned on, scheduler@email.com will be listed on the calendar event as the user who created the event.

'Impersonation' permissions for the service account need to be configured on the Exchange side in order for the impersonation to work correctly

Troubleshooting

Common problems such as not receiving invitation responses from your hiring team or not able to view interviewers' calendars can occurred when the client Exchange service failed to send updates to SmartRecruiters. To help pinpoint the underlying connectivity issue, you can:

  • Verify your Exchange server outgoing traffic to SmartRecruiters
  • Verify the Exchange TLS version
  • Check errors on the Exchange server

Verifying outgoing traffic to SmartRecruiters

Follow the steps below to determine if your Exchange server can send updates to SmartRecruiters: 

  1. Go to your Exchange server
  2. From your Exchange server, send a GET request to https://www.smartrecruiters.com/calendar/webhooks3/{companyIdentifier}
  3. The result should have a HTTP 200 response with the following message: "You have successfully reached SmartRecruiters Calendar integration URL, company identifier is: {companyIdentifier}." Note the date and time of the request and response

If your result is not the same as the one on Step 3, your Exchange server is not permitting outgoing traffic to SmartRecruiters. 

Verify TLS version

In some cases, the connectivity issue is caused by incompatible TLS version. SmartRecruiters uses AWS which requires TLS 1.2.

To ensure your Exchange server TLS version is 1.2, you can follow the following guide provided by Microsoft:

Additional resource that help you identify the TLS version:

Check errors on the Exchange server

Reviewing error log on the Exchange server can also help you identify if there is a connectivity issue.

Search for 'smartrecruiters.com' on your log and look for errors with message such as "Unable to send notification for subscription"