Module 1 - Configure Customer Applications & ATS Integrations

Статья
05/08/2023

Customers must authorize and enable your ATS to use specific Middleware Platform integrations, such as Apply With LinkedIn, on their behalf. To achieve this:

Create and configure a developer application for the customer
Using the application’s credential, 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, update integrations on their behalf with a user-facing integration name

Details for each step are given below:

Create and Configure a Customer App
Display the ATS Integration Configuration Plugin
Enable Customer Integrations
Verify the Customer Configuration is Enabled

Note

Please refer to Development Tools section to download postman collection of the APIs mentioned in this document.

Step 1. Create and Configure a Customer App

The Provisioning API allows you to create API keys for each of your customers. Ensure that you use proper customer names while provisioning as it will display on the consent screen (during OAuth flow). Please note that you 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.

Step 2. Display the ATS Integration Configuration Plugin

Use the ATS Integration Configuration Plugin to allow your customers to request for different integration types. Embed the Javascript code below to display the ATS Integration Configuration plugin.

The plugin loads based on the data-width and data-supported-bundled-integration-types attributes you specify
Use the data-supported-bundled-integration-types attribute to declare which integrations you support, a list of different integration types are displayed on the plugin as mentioned in data-supported-bundled-integration-types attribute
data-onintegrate attribute holds a callback function name that is invoked when the customer requests for an integration type within the plugin
When the customer requests for an integration, Linkedin invokes this function in response and a response data is passed to the function parameter
The response data contains integrationContext, integrationType, and tenantType
Ensure that you store the values of integrationContext, integrationType, and tenantType as they will be used in the next step

<script type="text/javascript" src="http://www.linkedin.com/uas/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>

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	Yes
RECRUITER_SYSTEM_CONNECT_COMPANY, RECRUITER_SYSTEM_CONNECT_CONTRACT	Used for the RSC integrations only	No

Note

Details on the customer's workflow within the plugin can be found here.
To reload the plugin on a single page application, use in.parse()

Tip

All error tables in this page are in show/hide collapsible text. Please click the text view error details.

Plugin Error Details

Click to view Plugin Errors

Use In-browser developer tools console to find out errors while rendering the plugin.

ERROR MESSAGE	DESCRIPTION	RESOLUTION
Domain validation failed for the api key. Please contact your ATS for further assistance. One should be seeing error.origin.not.in.api.domains in the In-browser developer-tool console	The Partner Domain URL is not allowlisted for the child application	1.Update `validJsSdkDomains` for child application 2. Ensure `validJsSdkDomains` should not contain trailing slash (/) 3. Ensure `validJsSdkDomains` should contain complete URL and should start with http and https
There seems to be a problem you do not have permissions	Logged in customer does not have Admin permissions for the selected contract	1. Ensure that the customer Admin has an active seat on the Recruiter contract. 2. Ensure the customer seat has been granted Admin privileges. 3. Ensure that the customer is logged in using the same email as mentioned in the contract seat 4. After the above corrections please ask the customer to re-login.

Step 3. Enable Customer Integrations

After your customer has requested enablement of Apply with LinkedIn as part of Step 2, please complete the request using the Enable Customer Integrations API. After successful execution of this API, your customers are enabled to use Apply with LinkedIn.

API Details
The details for Enable Customer Integrations API are given below:

API Endpoint

POST https://api.linkedin.com/v2/atsIntegrations?ids[0].integrationContext={integrationContext}&ids[0].integrationType={integrationType}&ids[0].tenantType={tenantType}&ids[0].dataProvider=ATS

API Authorization

This API is governed by OAuth 2 authorization and you must pass a bearer access token in your request as Authorization header. The access tokens are obtained via OAuth 2 Client Credentials flow. You must use your customer's application client id and client secret to obtain the access token.

API Headers

Name	Value
x-restli-method	batch_partial_update
Authorization	Bearer {accessToken}

API Request Parameters

Parameters	Description	Format	Required
ids[i].integrationContext	Use the customer's integration context obtained in step 2. The format will be `urn:li:organization:{id}`	string	Yes
ids[i].integrationType	Use the customer's integration type obtained in step 2	string	Yes
ids[i].tenantType	Use the customer's tenant type obtained in step 2	string	Yes
ids[i].dataProvider	Use `ATS` as the value for data provider	string	Yes

Sample Request Body

{
  "entities": {
    "integrationContext=urn:li:organization:4gX03uw&integrationType=APPLY_WITH_LINKEDIN&tenantType=JOBS&dataProvider=ATS": {
      "patch": {
        "$set": {
          "integrationName": "My Customer's Apply with LinkedIn Integration"
        }
      }
    }
  }
}

API Request Body Fields

Field	Description	Format	Required
integrationName	Customer-facing name for the integration.	string	Yes
integrationContext	Use the customer's integration context obtained in step 2. The format will be `urn:li:organization:{id}`	string	Yes
integrationType	Use the customer's integration type obtained in step 2	string	Yes
tenantType	Use the customer's tenant type obtained in step 2	string	Yes
dataProvider	Use "ATS" as the value for data provider	string	Yes

Sample Response Body

Successful execution of this API will return a 200 OK HTTP response code.

{
    "errors": {},
    "results": {
        "integrationType=APPLY_WITH_LINKEDIN&tenantType=JOBS&dataProvider=ATS&integrationContext=urn%3Ali%3Aorganization%3A4gX03uw": {
            "status": 204
        }
    }
}

Caution

Access token should be generated using customer application client id and client secret while making this api calls. Creating integrations must be done server-side and in real-time. Enable Customer Integration API must not be called from the client using java script, it must be initiated from server side. Once an Integration is Enabled for a customer, it cannot be disabled.

API Error Details

Click to view Enable Customer Integrations API errors

One of the following responses will be returned, containing a JSON object with a status and a message about the error.

HTTP CODE	RESPONSE STATUS	ERROR MESSAGE	DESCRIPTION	RESOLUTION
400	400	One or more of your update keys are violating update rule : modifying onboarding status for already enabled integration is not allowed	The status for the requested `integrationType` (i.e APPLY_WITH_LINKEDIN) for the customer is already `ENABLED`	Verify the status of the Integration request and check for `onBoardingStatus`. Use Verify the Customer Configuration is Enabled API to verify the status
400	400	Batch request mismatch. Entity key `dataProvider=urn:li` `:developerApplication:<application_id>` `&integrationContext=urn:` `li:company:<company_id>` `&integrationType=APPLY_WITH_LINKEDIN` `&tenantType=JOBS` not found in the query parameter	The value of following fields in request body and request parameters are not matching 1. `integrationContext` 2. `integrationType` 3. `dataProvider` 4. `tenantType`	Ensure that values for following fields should match in request body and request parameters 1.`integrationContext` 2.`integrationType` 3.`dataProvider` 4.`tenantType`
400	400	Integration key parts are incomplete	One or more of the mandatory keys is missing from request body or request parameters. Following are mandatory keys 1.`integrationContext` 2.`integrationType` 3.`dataProvider` 4.`tenantType`	1. Ensure that all the required keys are present in request body and request parameter 2. Ensure that values of following keys should match in request body and request parameters a. `integrationContext` b. `integrationType` c. `dataProvider` d. `tenantType`
403	403	Not enough permissions to access: POST /atsIntegrations	Application does not have required permissions	Ensure that correct child application credentials are used for fetching access token which is used as Authorization header in this api call
401	401	The token used in the request has expired	The access token used in Authorization header has expired	Regenerate a new access token Use API Authorization section for more details
401	401	Invalid access Token	The access token used is either tempered or not correct	Regenerate a new access token. Use API Authorization section for more details
200	404	No record found to partial update	Not able to find out any ATSIntegration Request which is initiated by the given customer application	Make sure the customer has initiated Apply with LinkedIn integration request using Step 2

Step 4. Verify Customer Integrations

Verify Customer Integrations API is used to find out the onboarding status of the integrations requested by customers using Step 2. When a customer enables Apply with LinkedIn integration using Step 3, the onboarding status of that integration changes from Requested to Enabled.
Customer integrations can have following three onboarding statuses:

Requested - the customer requested the integration. This is the status when customers have successfully completed Step 2
Partner Ready - the integration is ready to be enabled by the customer. It is not applicable for Apply with LinkedIn Integration type.
Enabled - the integration is set up and ready to use. This is the status when Step 3 is completed successfully

API Details
The details for Verify Customer Integrations API are given below:

API Endpoint

GET https://api.linkedin.com/v2/atsIntegrations?ids[0].integrationContext={integrationContext}&ids[0].integrationType={integrationType}&ids[0].tenantType={tenantType}&ids[0].dataProvider=ATS

API Authorization

API Headers

Name	Value
Authorization	Bearer {accessToken}

API Request Parameters

Parameters	Description	Format	Required
ids[i].integrationContext	Use the customer's integration context obtained in step 2. The format will be `urn:li:organization:{id}`	string	Yes
ids[i].integrationType	Use the customer's integration type obtained in step 2	string	Yes
ids[i].tenantType	Use the customer's tenant type obtained in step 2	string	Yes
ids[i].dataProvider	Use `ATS` as the value for data provider	string	Yes

Sample Response Body

{
    "errors": {},
    "results": {
        "integrationContext=urn:li:organization:4gX03uw&integrationType=APPLY_WITH_LINKEDIN&tenantType=JOBS&dataProvider=ATS": {
            "integrationName": "My Customer's Apply with LinkedIn Integration",
            "onboardingStatus": "ENABLED"
        }
    },
    "statuses": {}
}

Note

Access token should be generated using customer application client id and client secret while making this api calls.
PARTNER_READY value of onboardingStatus is not applicable for APPLY_WITH_LINKEDIN integration type.

API Error Details

Click to view Verify Customer Integrations API errors

One of the following responses will be returned, containing a JSON object with a status and a message about the error.

HTTP CODE	RESPONSE STATUS	ERROR MESSAGE	DESCRIPTION	RESOLUTION
200	NA	No data in statuses, results and errors field of the response body	No ATSIntegration is requested using customer application	Ensure that the customer has initiated Apply with LinkedIn integration request using Step 2
400	400	Invalid integration context urn	The value passed in `integrationContext` request parameter is not valid	Ensure that you pass the correct `integrationContext` value in the request parameter. The `integrationContext` value is obtained in Step 2 .
400	400	Integration key parts are incomplete	One or more of the required fields are missing in request parameters or contains wrong values Following are mandatory fields 1.`integrationContext` 2.`integrationType` 3.`dataProvider` 4.`tenantType`	1.Ensure that you provide all the mandatory fields in the request parameter and provide correct values to the fields 2. Refer to API Request Parameter section for more details
401	401	The token used in the request has expired	The access token used in Authorization header has expired	Regenerate a new access token. Use API Authorization section for more details
401	401	Invalid access token	The access token used is either tempered or not correct	Regenerate a new access token. Use API Authorization section for more details

Поделиться через

Module 1 - Configure Customer Applications & ATS Integrations

Step 1. Create and Configure a Customer App

Step 2. Display the ATS Integration Configuration Plugin

Plugin Error Details

Step 3. Enable Customer Integrations

API Endpoint

API Authorization

API Headers

API Request Parameters

Sample Request Body

API Request Body Fields

Sample Response Body

API Error Details

Step 4. Verify Customer Integrations

API Endpoint

API Authorization

API Headers

API Request Parameters

Sample Response Body

API Error Details

Обратная связь

Дополнительные ресурсы