Talent Hub HRIS Integration
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 |