Talent Hub Integrations Onboarding
Note
The use of this API is restricted to those developers approved by LinkedIn and subject to applicable data restrictions in their agreements.
This integration requires a partnership; please reach out to your LinkedIn Relationship Manager or Business Development contact as you will need to meet certain criteria and sign an API agreement to use this integration.
If you are not yet a LinkedIn Talent Solutions Partner, please complete the LinkedIn Talent Solutions Partner Request Form.
Obtain a LinkedIn Developer Account
Before beginning development you will need to be provisioned access. You can request access by completing the following steps:
- Create an API application for your integration. This will be your developer application. You can choose to create two separate applications i.e. one for your test/stage environment and one for your production environment.
Note
TalentHub product assignment is not supported in LinkedIn's developer platform. Sharing the developer application ID with your Business Development point of contact is sufficient for provisioning.
Once your app is configured and provisioned, you may begin making API requests and testing the integration. All API requests require OAuth 2.0 Client Credentials Flow (2-Legged) Authorization. Also, API requests return paged results; details on paging through results can be found here.
Register Your Talent Hub Integration
You need to finish configuring your integration before it can be added to LinkedIn Talent Solutions Third Party Integration Registry. Use your application credentials to call the following API:
POST https://api.linkedin.com/v2/hireThirdPartyExtensionProviders/extensionType={extensionType}&extensionProvider=THIRD_PARTY
Talent hub Integration service is uniquely identified by a combination of the fields below:
| Field Name | Description | Type |
|---|---|---|
| extensionType | Indicates the type of the extension. Types include INTERVIEW, BACKGROUND_CHECK, HRIS, JOB_DISTRIBUTION, DOCUMENT_SIGNATURE, THIRD_PARTY_ASSESSMENT |
Enum |
| extensionProvider | You should always supply THIRD_PARTY for this field. |
String |
Request Body Schema
| Field Name | Description | Type | Required |
|---|---|---|---|
| displayName | Multi locale string of the display name of your integration. | String | Yes |
| description | Multi locale string of the description of your integration. Maximum character limit 70. | String | Yes |
| onboardingUrl | A URL where you will receive the customer's LinkedIn Information via a GET request. As a response you will display a login screen where users will sign in to your system. This will complete the association of accounts and the onboarding process for the integration. This needs to be an HTTPS endpoint. |
String | Yes |
| callbackUrl | A URL for LinkedIn to send push notifications to your system regarding the integration. Different extension types might have different kinds of push notifications that you’re required to subscribe to and respond. This needs to be an HTTPS endpoint. Please do not use any query parameters. | String | Yes |
Sample Request Headers
Authorization: Bearer {access_token}
x-restli-method: partial_update
Sample Request Body
{
"patch": {
"$set": {
"displayName": {
"localized": {
"en_US": "Lorem Ipsum 1"
}
},
"description": {
"localized": {
"en_US": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
}
},
"onboardingUrl": "https://www.provider-url.com/liOnboarding",
"callbackUrl": "https://www.provider-url.com/liCallback"
}
}
}
A successful request will return a 204 response code.
After your integration is certified by LinkedIn, it will appear in our integration registry under the associated category for customers to select and onboard.
Enable a Customer
This section assumes that the customer has an account with both LinkedIn and your system and hence they’re our mutual customers.
Receive Customer Onboarding Request
When a customer starts to enable an integration in LinkedIn, they will be directed to your onboardingUrl. You will receive a GET request from LinkedIn on the onboardingUrl you provided. The GET request contains the customer’s LinkedIn information (hiring context) necessary for the integration and a signature for you to verify the request comes from LinkedIn in the query parameters.
As a response to this GET request you will display a login screen for your system. You will need to pass through the hiring context to any other flows that can originate here such as “user sign up”, “forgot password”, etc. Once your user logs in, you will use the information (hiring context) from the GET request to associate the LinkedIn user to your user's account. Any future request sent to you by LinkedIn will include the user information (hiring context) so you can correspond each request to the user’s account in your system. After onboarding process is done, you should redirect the customer back to LinkedIn to the redirectUrl provided in the GET request.
GET https://{your application’s registered onboarding URL}?hiringContext={hiringContext}&extensionType={extensionType}&redirectUrl={redirectUrl}&signature={signature}
| Field Name | Description | Type |
|---|---|---|
| hiringContext | Hiring context of the customer requesting the integration in the format of “urn:li:contract:123” | URN |
| extensionType | Integration type the customer requested. | String |
| redirectUrl | A URL where you should redirect customers back to LinkedIn when they have finished the extension onboarding process in your system | String |
| signature | This will be "HMACSHA256" signature. LinkedIn uses your developer application's secret as the encryption key. For encryption payload, LinkedIn prefixes "hmacsha256=" to the request payload. UTF-8 encoding is used here. For example, encryption payload for this use case is: hmacsha256={"hiringContext":"urn:li:contract:12345678","extensionType":"THIRD_PARTY_ASSESSMENT","redirectUrl":"https://www.linkedin.com/talent/account/v2/integrations"} | String |
Note
In order to authenticate the incoming request, the same HMAC signature can be computed by the partner and matched with the value present in the signature field present in the incoming request.
Sample Request
GET https://www.provider-url.com/liOnboarding?hiringContext=urn%3Ali%3Acontract%3A123&extensionType=BACKGROUND_CHECK&redirectUrl=https%3A%2F%2Fwww%2Elinkedin%2Ecom%2Ftalent%2Faccount%2Fv2%2Fintegrations&signature=aea468cc5941e8a7d50cb16aec9ee39b7ab4ce692a3cfb1d303737d663fe5100
Customers must log in to your system to authenticate their identity (unless they are already logged in).
Update Customer Integrations
To let LinkedIn know your system is ready for customer to consume the integration, use your application credentials to call the following API:
POST https://api.linkedin.com/v2/hireThirdPartyExtensions/hiringContext={hiringContext}&extensionType={extensionType}&extensionProvider=THIRD_PARTY
Talent hub customer Integration is uniquely identified by a combination of the fields below:
| Field Name | Description | Type |
|---|---|---|
| hiringContext | Hiring context of the customer in LinkedIn obtained in the format of urn:li:contract:123 |
URN |
| extensionType | Integration type the customer requested. | String |
| extensionProvider | You should always supply THIRD_PARTY for this field. |
String |
Request Body Fields
| Field Name | Description | Type | Required |
|---|---|---|---|
| status | Status of the extension. Statuses include ENABLED or PROVIDER_EXCEPTION. |
Enum | Yes |
| providerExceptionType | Represents the type of exception which happened on provider side if the provider marks the status as PROVIDER_EXCEPTION. Statuses include ACCOUNT_NOT_ELIGIBLE, AUTHENTICATION_FAILURE, TEMPORARILY_UNAVAILABLE, and SERVER_ERROR |
Enum | No |
Note
You may expire the extension if not used over a period of time. In this case ensure that you update the providerExceptionType to AUTHENTICATION_FAILURE
Sample Request Headers
Authorization: Bearer {access_token}
x-restli-method: partial_update
Sample Request Body
{
"patch": {
"$set": {
"providerConfiguration": {
//Provide below field only if your integration is for Background Check
"backgroundCheckConfiguration": {},
//Provide below field only if your integration is for Assessment
"assessmentConfiguration": {}
},
//Provide below field only if your integration is of type Interview
"configuration": {
"interviewConfiguration": {}
},
//Provide below field for All integration types
"status": "ENABLED"
}
}
}
A successful request will return a 204 response code. The customer’s extension will be in ENABLED status after this step.
Redirect the customer back to the redirectUrl when everything is done. Customers will see latest status in the integration registry page.
Note
Refer to Background Check, Assessments and Interviews for integration specific configurations
Disable Customer Integration
In the event a customer should disable an integration, a push event will be sent to your application's callbackUrl notifying you of this change. If you should receive this type of push event, please update your customer mapping that the integration has been disabled and to no longer make requests for this integration.
Request Body Fields
| Field | Description | Format | Required |
|---|---|---|---|
| type | Type of notification | String | Yes |
| hiringContext | Hiring context of the customer in the format of urn:li:contract:123. |
URN | Yes |
Sample Request
"Content-Type":"application/json",
"X-LI-Signature":"d3756e445a8065c0f38c2182c502f8229800eb2c6a9f3b4a1fdf152af867e6fc",
"Content-Length":"107",
"Connection":"Keep-Alive",
"Accept-Encoding":"gzip,deflate"
{
"type":"DELETE_THIRD_PARTY_EXTENSION",
"hiringContext": "urn:li:contract:123"
}
Rate Limits and Throttling
All of LinkedIn’s API are subject to rate limiting and throttling based on the number of requests made per unit time. The below limits apply to all API endpoints listed in this doc.
| Throttle Limits | Request Per Day (UTC) | Action |
|---|---|---|
| Application Maximum (max requests per app) | 5000 | Calls will be rejected with a status code of 429 |