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