Talent Hub Background Check Integration

  • Articolo

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, COMPLETED
You 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_EXCEPTION
Can 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