Talent Hub HRIS Integration

Article
05/08/2023

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.

Configure Customer Integration

To export candidate profile to your Human Resource Information System (HRIS), follow the steps mentioned in the Getting Started documentation to register and enable your integration. Once the integration is successfully enabled, users can export the profile to your HRIS.

Create a Third Party HRIS Export Request

Users can create a third party HRIS export request for a hired candidate in LinkedIn Talent Hub.

Receive a Push Event from LinkedIn

When a customer creates an HRIS export request on LinkedIn with your integration, LinkedIn will send a push notification to your callback URL registered during the onboarding process, discussed in the partner onboarding document. See Receiving Push Notifications for how to validate the request.

POST https://{your application’s registered callback URL}

Payload Fields

Field Name	Description	Type	Required
hrisRequestId	Unique id representing the HRIS export request for a candidate	String	Yes
hiringContext	Hiring context of the customer in the format of `urn:li:contract:123`.	URN	Yes
type	Type of the push event: `CREATE_THIRD_PARTY_HRIS_EXPORT_PROFILE_REQUEST` in this case.	Enum	Yes
expiresAt	Time when this request will expire. If not provided, the request will never expire.	Time (Epoch)	Yes

"Content-Type": "application/json",
"X-LI-Signature": "d3756e445a8065c0f38c2182c502f822981fdf152af867e6f",
"Content-Length": "107",
"Connection": "Keep-Alive",
"Accept-Encoding": "gzip,deflate"

{  
   "hrisRequestId": "ODE1OGNkNzItYzUxNi00MjBkLTlhMT",
   "hiringContext": "urn:li:contract:123",
   "type": "CREATE_THIRD_PARTY_HRIS_EXPORT_PROFILE_REQUEST",
   "expiresAt": 1481402799192
}

Note

If a push event sent to the registered callback URL receives an unsuccessful response (something other than “200 OK”), LinkedIn will retry sending the request up to six times.

Retrieve HRIS Candidate Profile Information

When the callback URL has received a notification event of CREATE_THIRD_PARTY_HRIS_EXPORT_PROFILE_REQUEST type, you should then make an API call to retrieve the profile information of the candidate.

GET https://api.linkedin.com/v2/hireThirdPartyHrisProfiles/hiringContext={hiringContext}&hrisRequestId={hrisRequestId}&extensionProvider=THIRD_PARTY

Any third-party HRIS request is uniquely identified by a combination of the fields below:

Field Name	Description	Type
hiringContext	Hiring context of the customer in the format of `urn:li:contract:123` obtained from HRIS export request	URN
hrisRequestId	Unique identifier of the third party HRIS request created within the domain of the hiring context obtained from HRIS export request	String
extensionProvider	You should always supply “THIRD_PARTY” for this field.	Enum

Response Fields

Field Name	Description	Type	Required
candidateProfile	HRIS candidate export profile.	Object	Yes
requesterProfile	Profile of the user who requested to export the candidate profile. This field is decorated internally using enterprise profile and published to the partners.	Object	No
requestedAt	Time when the candidate was exported.	Long (Number of milliseconds since midnight, January 1, 1970 UTC. It must be a positive number)	Yes
jobTitle	Title of the job requisition. For example, Software Engineer.	String	No
jobLocation	Location of the job requisition.	String	No
startDate	Date when the candidate is expected to start work. If no start date is specified then the project start date for this requisition is considered as the candidate start date.	Date	Yes

Candidate Profile Fields

Field Name	Description	Type	Required
firstName	The candidate’s first name.	String	Yes
lastName	The candidate’s last name.	String	Yes
phoneNumbers	List of phone number provided by the member. An empty array if not available.	Array of phoneNumber	Yes
emailAddresses	Email address of candidate who is exported to Human Resource Information Systems. An empty array if not available.	Array of emailAddress	Yes

Requester Profile Fields

Field Name	Description	Type	Required
firstName	First name of the requester.	String	No
lastName	Last name of the requester.	String	No

Phone Number Fields

Field Name	Description	Type	Required
number	The member's phone number. The maximum allowed length is 25.	String	Yes
extension	The member's extension.	String	No

Date Fields

Field Name	Description	Type	Required
day	Day in the format ##.	Integer	No
month	Month in the format ##.	Integer	No
year	Year in the format ####.	Integer	No

Sample Response

Headers:
Authorization: Bearer {access_token}

"Content-Type": "application/json",
"Content-Length": "107",
"Connection": "Keep-Alive",
"Accept-Encoding": "gzip,deflate"

{
   "candidateProfile": {
    "firstName": "John",
    "lastName": "Candidate", 
    "phoneNumbers": [
      {
        "number": "555-555-5555",
        "extension": "1234"
      }
    ],
    "emailAddresses": [
      "candidate@outlook.com"
    ]
   },
   "requesterProfile": {
      "firstName": "Ed",
      "lastName": "Requester"
   },
   "requestedAt": 1481402799192,
   "jobTitle": "Software Engineer",
   "jobLocation": "San Francisco Bay Area",
   "startDate": {
      "day": 12,
      "month": 12,
      "year": 2012
   }
}

Update Record Generation Status

After retrieving the candidate profile information, use the following API to update the status of the record generation with the exported member in your system.

POST https://api.linkedin.com/v2/hireThirdPartyHrisProfiles/hiringContext={hiringContext}&hrisRequestId={hrisRequestId}&extensionProvider=THIRD_PARTY

A third-party hire assessment is uniquely identified by a combination of the fields below:

Field Name	Description	Type
hiringContext	Hiring context of the customer in the format of `urn:li:contract:123` obtained from HRIS export request	URN
hrisRequestId	Unique identifier of the third party HRIS request created within the domain of the hiring context obtained from HRIS export request	String
extensionProvider	You should always supply `THIRD_PARTY` for this field.	Enum

Request Body Fields

Field Name	Description	Type	Required
status	Enum indicating the status of the HRIS record creation. You should supply `PROVIDER_EXCEPTION` or `COMPLETED` in this case.	Enum	Yes
providerExceptionType	Optional enum representing type of exception happened on provider side if the provide marks the status as `PROVIDER_EXCEPTION`. Can be `ACCOUNT_NOT_ELIGIBLE`.	Enum	No

Sample Request Body

Headers:
Authorization: Bearer {access_token}
x-restli-method: partial_update

Request Body:

{
  "patch": {
    "$set": {
      "status": "COMPLETED"
    }
  }
}

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`