Configure Customer Applications and ATS Integrations

Article
05/08/2023

Your Customers must authorize and enable your ATS to use specific Middleware Platform integrations like Recruiter System Connect on their behalf. To achieve this:

You will create and configure a development application for the customer.
Using the app's credentials, you will host a customer-facing configuration plugin that 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.

Steps

Create and Configure a Customer App
Display the ATS Integration Configuration Plugin
Update Customer Integrations
Sync Integration Configurations
Verify Customer Integrations Enablement

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.

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>

Important

Use the Customer's Application Client ID obtained in step 1 as a value for 'api_key' in above plugin to display the ATS Integration Configuration Plugin.

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

Some integrations require additional configuration values to be created to complete customer onboarding for Recruiter System Connect. Configurations are a set of key-value pairs which are defined for a specific integration.

Here is an example request that sets the CALLBACK_URL key for the ONE_CLICK_EXPORT configuration type:

Sample Integration Configuration Upsert Request

URL:

PUT https://api.linkedin.com/v2/atsIntegrations/integrationContext=urn:li:organization:4gX03uw&integrationType=ONE_CLICK_EXPORT&tenantType=RECRUITER&dataProvider=ATS/configurations?ids=CALLBACK_URL

Headers:

Authorization: Bearer {token}
x-restli-method: batch_update

Request Body:

{
  "entities": {
    "CALLBACK_URL": {
      "configurationValue": {
        "string": "https://customer.callback.com/goes/here"
      }
    }
  }
}

Sample Integration Configuration Upsert Response

{
    "errors": {},
    "results": {
        "CALLBACK_URL": {
            "status": 204
        }
    }
}

You can find more details on how to configure these keys, example requests, and definition of which configuration values are required for various integration types in our Integration Configuration docs.

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

A 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 support ticket with a list of integrations you would like to delete.

Share via

Configure Customer Applications and ATS Integrations

Steps

1. Create and Configure a Customer App

2. Display the ATS Integration Configuration Plugin

Integration Enums

Plugin Load

Plugin Callback

3. Update Customer Integrations

Sync Customer Integrations

Request Body Fields

Sample Request

Sample Response

Sample Response Body

4. Sync Integration Configurations

Sample Integration Configuration Upsert Request

Sample Integration Configuration Upsert Response

5. Verify Customer Integrations Enablement

Sample Notification

Sample Response

Sample Response

Feedback

Feedback

Additional resources