Connecting to SmartRecruiters

The SmartRecruiters – General Partner Integration follows the OAuth 2.0 protocol and utilizes the Client Credential flow to exchange data with integrating systems. We expect your team to be familiar with the OAuth 2.0 protocol. OAuth 2.0 Client Credentials Grant document provides more information on OAuth 2.0 Client Credential flow.

Before customers can utilize your services within the SmartRecruiters platform, SmartRecruiters and your application will need to exchange credentials on two levels:

• Partner Level (Master Credentials) - credentials at this level are used to facilitate the customer-level credentials exchange during the integration setup process.
• Customer Level - credentials at this level are used:
  • By your application to access SmartRecruiters API on behalf of the customer
  • By SmartRecruiters to send requests to your application (in case of bi-directional integrations)

📘

Customer Level Credentials

The term Customer-Level Credentials refers to credentials either generated by SmartRecruiters to access customer data or generated by your application.

---

1. Obtain Partner-Level (Master) Credentials

Initial application setup is handled by the SmartRecruiters Partner & API Team. To issue a set of Master Credentials for your application, they will need the following information:

• scopes - access scopes that are required for your application. See developer documentation for the list of available scopes.
• consentUrl: The URL that SmartRecruiters will redirect the user to during the integration setup process. The user should authenticate and give their consent for the integration at the designated URL. SmartRecruiters will add companyId and redirect query parameters when redirecting user to this page.
• consentDisplayMode: This field determines the end-user experience during the integration activation step. There are two possible options:
  • REDIRECT: User will leave the SmartRecruiters integration setup page and will be redirected to the URL configured by the consentUrl field. SmartRecruiters will add the redirect query parameter in addition to companyId. The redirect parameter contains URL to redirect the user back to the SmartRecruiters when the credentials exchange process is complete.
  • POPUP: The user will stay on the SmartRecruiters integration setup page. The URL configured in the consentUrl will be used to display the pop-up iFrame widget.
• oauthTokenUrl (optional): An endpoint defined by your application. SmartRecruiters will call this endpoint to get an OAuth 2.0 Bearer token. SmartRecruiters will use the customer-level credentials received from your application during the integration setup process. This token will be used by SmartRecuiters to access your API on behalf of the customer.
• callbackUrl (optional): An endpoint for your application to receive POST requests with notifications on disabled integrations for a specific customer. Request will be signed with a Bearer token, exchanged from customer-level credentials at oauthTokenUrl. You can use the clientId associated with the token to identify the customer. POST body will contain the following object:

{
  "eventType": "INTEGRATION_DISABLED"
}

🚧

Notifications to callbackUrl will not be send if oauthTokenUrl has not been defined.

• logo: The logo of your application, displayed on the Apps & Integrations page of the SmartRecruiters platform.
• description: A description of your application, displayed on the Apps & Integrations page of the SmartRecruiters platform.

📘

Application's visibility

If you use the General Partner Integration, your application will be displayed on the Apps & Integrations page of the SmartRecruiters platform. It can be made available to all customers or, if you're building a private integration, only to selected ones. You should confirm your application's visibility with the SmartRecruiters Partner & API Team.

After you have provided SmartRecruiters with the required data, our Partner & API Team will review the requested access scopes of your application. Once the review is completed, they will:

1. Approve your application’s access scopes, OR
2. Ask you to adjust requested access scopes based on the Principle of Least Privilege

When the requested access scopes are approved, the Partner & API Team will also provide you with an Application ID and a set of Partner Level Credentials (Master Credentials). The Master Credentials is a unique clientId and clientSecret pair for you to be able to access SmartRecruiters public API and setup integrations as requested by customers.

The SmartRecruiters Partner & API Team will share the Master Credentials with your team in an encrypted way.

2. Exchange Master Credentials for a Bearer Token

After you receive the master credentials, you can use them to obtain an OAuth 2.0 Bearer token, and use the token to finish setting up the integration requests from SmartRecruiters customers.

You can exchange your Master Credentials for an access token using the following endpoint:

https://api.smartrecruiters.com/identity/oauth/token

The token endpoint accepts the POST method. Below is an example request for exchanging the access token:

curl --request POST \
  --url 'https://api.smartrecruiters.com/identity/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET

3. Exchange Customer Level Credentials

When the customer initiates a connection from SmartRecruiters to your application, your predefined access scopes will be displayed on the integration setup page. Once the customer grants their permission, they are redirected to your platform. SmartRecuiters will use the consentURL you have provided in the previous step.

There are two front-end implementation options:

• SmartRecruiters provides a pop-up iFrame widget on the integration setup page to load your service sign-in page.
• SmartRecruiters redirect users to your sign-in page.

SmartRecruiters will add the following URL query parameters when making a GET request to the consentUrl page:

• companyId - a unique company identifier in SmartRecruiters
• redirect - URL to redirect user back to SmartRecruiters. Added only if you are using consentDisplayMode=REDIRECT. Your application should redirect users to the provided URL after the credentials exchange is completed.

Once the customer authenticates on your platform, your application must send a POST request to the following endpoint to confirm the integration:

https://api.smartrecruiters.com/apps-integrations/partner-api/integrations

Additionally, if the integration is bi-directional, the access scopes granted to SmartRecruiters should be displayed to the customer before their approval.

Request must contain your application ID and company ID. Furthermore, for bi-directional integration, you need to generate customer-level credentials to your API and send them to SmartRecruiters.

📘

Should you generate Customer Level Credentials for SmartRecruiters?

Your application should generate Customer Level Credentials for SmartRecruiters and send them at this step if:

• your integration is bi-directional, meaning you expect to receive API calls from SmartRecruiters while the integration is enabled
• you want to be notified via a call to callbackUrl when a customer disables the integration on the SmartRecruiters side (in this case, you must also define oauthTokenUrl)

Request body example:

{
  "appId": "your-app-id",
  "companyId": "company-id-which-enables-integration",
  "clientId": "optional-client-id-to-your-api",
  "clientSecret": "optional-client-secret-to-your-api"
}

• appId - application ID provided to you by SmartRecruiters Partner & API Team in the previous step.
• companyId - a unique company identifier in SmartRecruiters, provided in the query parameter when redirecting user to the consentUrl page.
• clientId and clientSecret (required for bi-directional integrations) a set of customer-level credentials, generated by your application. SmartRecruiters will use it to sign requests to your API, e.g. to send you a notification about disabled integration or access the customer’s data.

🚧

ClientId uniqness

Generated clientId you send in this step must be unique among all of your integrations.

When you make calls to the /integrations endpoint, you must include the master credentials Bearer token you obtained in the previous step in the Authorization header:

Authorization: Bearer cd251a04-4a00-4e7d-99e2-1b2e5431adb1

SmartRecruiters will return a 200 OK response with customer-level credentials that you can use to access SmartRecruiters API and access customer data on behalf of the company.

Response example:

{
  "clientId": "string",
  "clientSecret": "string",
  "integrationId": "7cbc0f64-4d1c-4d70-9f19-dbd8f3656020"
}

📘

Not to be confused with the Master Credentials from the above sections

This set of credentials is to access the given customer’s data via SmartRecruiters public API.

SmartRecruiters will generate a unique set of credentials for every company integration.

4. Finish the Integration Setup Process

Based on the value configured in consentDisplayMode, end-user experience at the last step may differ:

• REDIRECT: your application needs to handle the user frontend transition by sending users back to SmartRecruiters using the URL provided to you in the redirect parameter.
• POPUP: SmartRecruiters will handle the frontend user transition, closing the pop-up widget and refreshing the page.

At this point, the connection between SmartRecruiters and your application is set up for the specific customer. You can exchange credentials you received for the access token and use this token to access SmartRecruiters public APIs on behalf of the company you’re now integrated with.