Talent Hub Background Check Integration
Important
The use of this API is restricted to those developers approved by LinkedIn and subject to applicable data restrictions in their agreements.
This document can be referred for both Background Check and Reference Check partner integrations.
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 configure customer background check integrations, 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 the format of "urn:li:contract:123" | URN |
| extensionType | Enum indicating type of integration, in this case "BACKGROUND_CHECK" | Enum |
| extensionProvider | You should always supply "THIRD_PARTY" for this field. | Enum |
Request Body Fields
| Field Name | Description | Type | Required |
|---|---|---|---|
| availablePackages | Background check packages available for the customer to choose. Default is empty array. Use empty array if this is not applicable to your extension. |
Array of Background Check Packages | No |
Background Check Package Fields
| Field Name | Description | Type | Required |
|---|---|---|---|
| displayName | Multi locale string of the display name of the package. | Object | Yes |
| packageId | Unique identifier of the package within your system. | String | Yes |
Sample Request
Headers:
Authorization: Bearer {access_token}
x-restli-method: partial_update
Request Body:
{
"patch": {
"$set": {
"providerConfiguration": {
"backgroundCheckConfiguration": {
"availablePackages": [
{
"packageId": "PKG_1305",
"displayName": {
"localized": {
"en_US": "Lorem Ipsum 1"
}
}
},
{
"packageId": "PKG_1401",
"displayName": {
"localized": {
"en_US": "Lorem Ipsum 2"
}
}
}
]
}
}
}
}
}
Note
A successful request will return a 204 response code.
Receive a Push Event from LinkedIn
When a customer creates a background check request on LinkedIn with your integration, LinkedIn will send a push notification to your callback URL registered during the onboarding process, discussed in the Getting Started documentation. See Receiving Push Notifications for how to validate the request.
POST https://{your application’s registered callback URL}
| Field Name | Description | Type | Required |
|---|---|---|---|
| type | Type of the push event: CREATE_THIRD_PARTY_BACKGROUND_CHECK in this case. |
Enum | Yes |
| hiringContext | Hiring context of the customer in the format of urn:li:contract:123 |
URN | Yes |
| backgroundCheckId | Unique identifier of the third party background check created within the domain of the hiring context. | String | Yes |
| candidateEmailAddress | Email address of the candidate being checked. | String | Yes |
| packageIds | Ids of the background check package selected. Empty if no package is available. | String | Yes |
| candidateFirstName | First name of the candidate being checked. | String | Yes |
| candidateLastName | Last name of the candidate being checked. | String | Yes |
| requesterFirstName | First name of the requester. | String | Yes |
| requesterLastName | Last name of the requester. | String | Yes |
| requesterEmailAddress | Email address of the requester. | String | Yes |
Note
The requester fields (requesterFirstName, requesterLastName and requesterEmailAddress) provided by LinkedIn can be used by the provider to validate if the requester has the access rights to create background check request. These requester details can also be embedded by the provider in customer communications.
Sample Request
"Content-Type": "application/json",
"X-LI-Signature": "5a1c2fdbd16fbba7e3816fa3ac3f05835d6bef9364b5c",
"Content-Length": "186",
"Connection": "Keep-Alive",
"Accept-Encoding": "gzip,deflate"
{
"type": "CREATE_THIRD_PARTY_BACKGROUND_CHECK",
"hiringContext": "urn:li:contract:123",
"backgroundCheckId": "ODE1OGNkNzItYzUxNi00MjBkLTlhMT",
"candidateEmailAddress": "test-candidate@outlook.com",
"configuration":{"packageIds":["PKG_1305", "PKG_1401"]},
"candidateFirstName": "test",
"candidateLastName": "candidate",
"requesterEmailAddress": "test-requester@outlook.com",
"requesterFirstName": "test",
"requesterLastName": "requester"
}
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.
Update Third Party Background Check Information
After generating a background check entity in your system, use your application credentials to call the following API to update the third party background check link and status in LinkedIn:
POST https://api.linkedin.com/v2/hireThirdPartyBackgroundChecks/hiringContext={hiringContext}&backgroundCheckId={backgroundCheckId}&extensionProvider=THIRD_PARTY
Any third-party Background check 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 push event. |
URN |
| backgroundCheckId | Unique identifier of the third party background check created within the domain of the hiring context obtained from push event. | String |
| extensionProvider | You should always supply THIRD_PARTY for this field. |
Enum |
Request Body Fields
| Field Name | Description | Type | Required |
|---|---|---|---|
| backgroundCheckUrl | URL to view this background check in your system. LinkedIn customers will be able to use this link to redirect to your system to view the progress and results of this background check | Url | Yes |
| status | Enum indicating the status of the third party background check: REQUESTED PROVIDER_READ PROVIDER_EXCEPTION STARTED COMPLETED - You should supply PROVIDER_READY 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 |
| extensionProvider | You should always supply THIRD_PARTY for this field | Enum | Yes |
Request Body Fields
| Field Name | Description | Type | Required |
|---|---|---|---|
| backgroundCheckUrl | URL to view this background check in your system. LinkedIn customers will be able to use this link to redirect to your system to view the progress and results of this background check | Url | Yes |
| status | Enum indicating the status of the third party background check: REQUESTED, PROVIDER_READY, PROVIDER_EXCEPTION, STARTED, COMPLETED. You should supply PROVIDER_READY in this case. | Enum | Yes |
| providerExceptionType | Optional enum representing type of exception which happened on provider side if the provider marks the status as PROVIDER_EXCEPTION. Options are ACCOUNT_NOT_ELIGIBLE, AUTHENTICATION_FAILURE, TEMPORARILY_UNAVAILABLE, and SERVER_ERROR | Enum | No |
Headers:
Authorization: Bearer {access_token}
x-restli-method: partial_update
Request Body:
{
"patch": {
"$set": {
"backgroundCheckUrl": "https://www.provider-url.com/bgc/8204345-45dsg-4fay",
"status": "PROVIDER_READY"
}
}
}
Update Third Party Background Check Status
When a background check is started or completed, use your application credentials to call the same API above to update the third party background check data in LinkedIn.
POST https://api.linkedin.com/v2/hireThirdPartyBackgroundChecks/hiringContext={hiringContext}&backgroundCheckId={backgroundCheckId}&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 push event. |
URN |
| backgroundCheckId | Unique identifier of the third party background check created within the domain of the hiring context obtained from push event. | 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 third party background check: STARTED, COMPLETEDYou should supply STARTED 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_EXCEPTIONCan be ACCOUNT_NOT_ELIGIBLE |
Enum | No |
Headers:
Authorization: Bearer {access_token}
x-restli-method: partial_update
Request Body:
{
"patch": {
"$set": {
"status": "COMPLETED"
}
}
}
Delete a Third Party Background Check
When a customer deletes a third party background check, LinkedIn will send a push event to your registered callback URL. See Receiving Push Notifications for how to validate the request.
Note
Currently, the UI support to delete third-party background check is under development. However, LinkedIn encourages partners to support this feature so it can be consumed immediately when available.
POST https://{your application’s registered callback URL}
Payload Fields
| Field Name | Description | Type | Required |
|---|---|---|---|
| type | Type of the push notification: DELETE_THIRD_PARTY_BACKGROUND_CHECK in this case. |
Enum | Yes |
| hiringContext | Hiring context of the customer in the format of urn:li:contract:123 |
URN | Yes |
| backgroundCheckId | Unique identifier of the third party background check created within the domain of the hiring context. | String | Yes |
Sample Request
"Content-Type": "application/json",
"X-LI-Signature": "f21aba40ab485921448942827b89af30bc3e46ee440bd37",
"Content-Length": "157",
"Connection": "Keep-Alive",
"Accept-Encoding": "gzip,deflate"
{
"type": "DELETE_THIRD_PARTY_BACKGROUND_CHECK",
"hiringContext": "urn:li:contract:123",
"backgroundCheckId": "ODE1OGNkNzItYzUxNi00MjBkLTlhMT"
}
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.
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 |