Module 1 - Configure Customer Applications & ATS Integrations
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-widthanddata-supported-bundled-integration-typesattributes you specify - Use the
data-supported-bundled-integration-typesattribute to declare which integrations you support, a list of different integration types are displayed on the plugin as mentioned indata-supported-bundled-integration-typesattribute data-onintegrateattribute 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, andtenantType - Ensure that you store the values of
integrationContext,integrationType, andtenantTypeas 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. dataProvider4. 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. dataProvider4. 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. integrationContextb. integrationTypec. dataProviderd. 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
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 |
|---|---|
| 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 |
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