Middleware Platform Customer Configuration
Customers must authorize and enable your ATS to use specific Middleware Platform integrations on their behalf. To achieve this:
- You will create and configure a developer application for the customer.
- Using the app's credentials, you will host a customer-facing configuration plugin which allows customers to manage their integrations with your ATS.
- After the customer pre-authorizes integrations in the plugin, you will update integrations on behalf of the customer with a user-facing integration name.
- Depending on the type of integration, you may need to send customer-specific configuration values.
- Finally, the customer will log into the relevant LinkedIn product and enable the integration. Once enabled, you will be authorized to begin sending customer data to the Middleware Platform.
Details for each step are below.
1. Create and Configure a Customer App
The Provisioning API allows you to create API keys for each of your customers. Please note that you will need to store a unique API key for each of your customers.
Once your app is configured, you may begin making API requests and testing the integration. All API requests require authorization .
If you are implementing Apply with LinkedIn, please contact the member from LinkedIn Business Development who you have been working with and request to fill out the Partner Onboarding Form.
Note
Note: For existing CSA customers, you will be using their existing API keys. Please contact your Partner Engineering representative to coordinate migrating these API keys.
2. Display the ATS Integration Configuration Plugin
Using the customer's app credentials obtained in step 1, display the ATS Integration Configuration Plugin:
<script type="text/javascript" src="https://platform.linkedin.com/xdoor/scripts/in.js">
api_key: {customer app API key goes here}
extensions: ATSIntegrationWidget@https://platform.linkedin.com/rsc/extensions/onboarding-widget
</script>
<script type="IN/ATSIntegrationWidget"
data-supported-bundled-integration-types="RECRUITER_SYSTEM_CONNECT_COMPANY,RECRUITER_SYSTEM_CONNECT_CONTRACT,APPLY_WITH_LINKEDIN"
data-onintegrate="handleIntegrations"
data-width="{width}" >
</script>
<script>
/**
* This callback should:
* 1) Store the customer's integration in your ATS. These values are used to throughout the Middleware Platform's API.
* 2) Tell your server to create and configure customer integrations via the Middleware Platform using this data.
* @param {Object[]} integrations
* @param {string} integrations[].integrationContext
* @param {string} integrations[].integrationType
* @param {string} integrations[].tenantType
*/
function handleIntegrations (integrations) {
//Your code here
}
</script>
Integration Enums
The value for data-supported-bundled-integration-types should be based on the integrations as indicated below:
| Enum | Description | Required |
|---|---|---|
| APPLY_CONNECT | Used for the Apply Connect integrations only | No |
| APPLY_WITH_LINKEDIN | Used for the Apply with LinkedIn integrations only | No |
| RECRUITER_SYSTEM_CONNECT_COMPANY, RECRUITER_SYSTEM_CONNECT_CONTRACT | Used for the RSC integrations only | Yes |
Plugin Load
The plugin will load based on the data-width and data-supported-bundled-integration-types attributes you specify. Use the latter attribute to declare which integrations you support.
Plugin Callback
The callback specified for the data-onintegrate script attribute will be fired when the customer enables an integration within the plugin. You will need to store the values you retrieve per customer for: integrationContext , integrationType , and tenantType as they will be used in the next step.
Note
- Details on the customer's workflow within the plugin can be found here.
- In order to reload the widget on a single page application, use in.parse()
- Verify Content Security Policy includes "platform.linkedin.com" and "www.linkedin.com"
3. Update Customer Integrations
Sync Customer Integrations
POST https://api.linkedin.com/v2/atsIntegrations?ids[0].integrationContext={integrationContext}&ids[0].integrationType={integrationType}&ids[0].tenantType={tenantType}&ids[0].dataProvider=ATS
Note
Creating integrations must be done server-side and in real-time.
Please submit batch calls grouped with no more than 100 records and a minimum delay of one-second between calls.
For each id part specified in the request:
- Use the customer's integration context obtained in step 2 as the value of
id[i].integrationContext. The format will be either "urn:li:organization:{id}" or "urn:li:contract:{id}". - Use the integration type obtained in step 2 as the value of
id[i].integrationType. - Use the tenant type obtained in step 2 as the value of
id[i].tenantType. - Use "ATS" as the value of
id[i].dataProvider.
Request Body Fields
| Field | Description | Format | Required |
|---|---|---|---|
| integrationName | Customer-facing name for the integration. | string | Yes |
Sample Request
Headers:
Authorization: Bearer {token}
x-restli-method: batch_partial_update
Request Body:
{
"entities": {
"integrationContext=urn:li:organization:4gX03uw&integrationType=ONE_CLICK_EXPORT&tenantType=RECRUITER&dataProvider=ATS": {
"patch": {
"$set": {
"integrationName": "My Customer's LinkedIn Recruiter One-Click Export Integration"
}
}
}
}
}
Sample Response
A successful request will return a 200 OK response code, and you will find the status of each entity in the response body.
Sample Response Body
{
"errors": {},
"results": {
"integrationType=ONE_CLICK_EXPORT&tenantType=RECRUITER&dataProvider=ATS&integrationContext=urn%3Ali%3Aorganization%3A4gX03uw": {
"status": 204
}
}
}
Note
Be sure to check the response for error statuses corresponding to individual entities you submit.
4. Sync Integration Configurations
Configurations are a set of key-value pairs which belong to a specific integration. Depending on the type of integration and product ( tenantType ), additional configuration may be required.
See Middleware Platform Integration Types to understand which configuration values are required for various integration types.
Note
If a customer opts-out of restricting user-based entity visibility or your ATS doesn't offer this security functionality, you should configure customer entity visibility defaults so that entities without ACLs are shown in LinkedIn products.
5. Verify Customer Integrations Enablement
Customer integrations have three onboarding statuses:
- Requested - the customer requested the integration.
- Partner Ready - the integration is ready to be enabled by the customer.
- Enabled - the integration is set up and ready to use.
When a customer enables an integration, the onboarding status of that integration changes from Partner Ready to Enabled. When that happens, LinkedIn will send you a push notification (see Receive Push Events ) with a unique ID. You can use this ID to retrieve information about the customer and the enabled integration.
In order for push notifications to work, you must first submit a callback URL as a integration configuration for each integration the customer requested. Refer to Sync Integration Configurations for more details.
Once callback URLs are submitted, LinkedIn will generate and send a push notification automatically when a customer enables an integration. A notification will be sent for every integration enabled.
Notifications will follow the syntax below:
Sample Notification
"Content-Type":"application/json",
"X-LI-Signature":"d3756e445a8065c0f38c2182c502f8229800eb2c6a9f3b4a1fdf152af867e6fc"
{
"id":"{Unique Notification ID}",
"type":"INTEGRATION_STATUS_CHANGE",
"expiresAt":0
}
Note
Onboarding status change notifications will be denoted by the value INTEGRATION_STATUS_CHANGE (enum) in the type field.
Upon receiving the notification and verifying that type = INTEGRATION_STATUS_CHANGE , use the endpoint below with the unique notification ID to retrieve more information about the enabled integration:
GET https://api.linkedin.com/v2/atsIntegrations?q=request&requestId={Unique Notification ID}
Successful response will look like the following:
Sample Response
{
"elements": [
{
"dataProvider": "ATS",
"integrationContext": "urn:li:organization:2414183",
"integrationName": "My Customer's LinkedIn Recruiter One-Click Export Integration",
"integrationType": "ONE_CLICK_EXPORT",
"onboardingStatus": "ENABLED",
"tenantType": "RECRUITER"
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
For partners who implemented RSC prior to December 2017 and AWLI please reference the section below:
To manually retrieve the onboarding status of customer integrations, use the endpoint below:
GET https://api.linkedin.com/v2/atsIntegrations?ids[0].integrationContext={integrationContext}&ids[0].integrationType={integrationType}&ids[0].tenantType={tenantType}&ids[0].dataProvider=ATS
Successful response will look like the following:
Sample Response
{
"errors": {},
"results": {
"integrationContext=urn:li:organization:4gX03uw&integrationType=ONE_CLICK_EXPORT&tenantType=RECRUITER&dataProvider=ATS": {
"integrationName": "My Customer's LinkedIn Recruiter One-Click Export Integration",
"onboardingStatus": "ENABLED"
}
},
"statuses": {}
}
The response body will include the fields you supplied as well as the following fields:
| Field | Description | Format |
|---|---|---|
| integrationName | The customer-facing integration name you supplied | string |
| onboardingStatus | One of the three onboarding statuses for a given integration: REQUESTED, PARTNER_READY or ENABLED | enum |
Tip
During development, we recommend not having more than 10-15 integrations on your development contract as this may cause issues with our APIs. This will not be an issue in production as most customers generally have between 1-2 enabled integrations. If you should have more than 10-15 integrations please file a Zendesk ticket with a list of integrations you would like to delete.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for