Talent Hub Assessments 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 configure customer assessment 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 with format `urn:li:contract:123`	URN
extensionType	Enum indicating integration type `THIRD_PARTY_ASSESSMENT`	Enum
extensionProvider	You should always supply `THIRD_PARTY` for this field.	Enum

Request Body Fields

Field Name	Description	Type	Required
availableThirdPartyAssessmentTests	Assessment tests available for the customer to choose. Default is empty array. Use empty array if this is not applicable to your extension.	Array of AvailableThirdPartyAssessmentsTest	No

AvailableThirdPartyAssessmentsTest

Field Name	Description	Type	Required
id	Unique identifier of the test within your system.	String	Yes
displayName	Multi-locale string of the name of the assessment test.	Object	Yes
categories	Categories the assessment test is associated with.	String	No

Sample Request

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

{
  "patch": {
    "$set": {
      "providerConfiguration": {
        "assessmentConfiguration": {
          "availableThirdPartyAssessmentTests": [{
            "id": "TEST_1305",
            "displayName": {
              "localized": {
                "en_US": "Lorem Ipsum 1"
              }
            },
            "categories": [{
              "localized": {
                "en_US": "Backend Engineer"
              }
              },
              {
              "localized": {
                "en_US": "Fullstack Engineer"
              }
            }]
          },{
            "id": "TEST_1401",
            "displayName": {
              "localized": {
                "en_US": "Lorem Ipsum 2"
              }
            },
            "categories": [{
              "localized": {
                "en_US": "Frontend Engineer"
              }
              },
              {
              "localized": {
                "en_US": "Fullstack Engineer"
              }
            }]
          }]
        }
      }
    }
  }
}

Note

A successful request will return a 204 response code.

Receive a Push Event from LinkedIn

When a customer creates an assessment 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}

Request Body Fields

Field Name	Description	Type	Required
assessmentId	Unique id representing the assessment request for a candidate.	String	Yes
candidate.emailAddress	Email address of the candidate being assessed.	String	Yes
candidate.firstName	First name of the candidate being assessed.	String	Yes
candidate.lastName	Last name of the candidate being assessed.	String	Yes
hiringContext	Hiring context of the customer in the format of `urn:li:contract:123`	URN	Yes
requester.emailAddress	Email address of the requester.	String	Yes
thirdPartyAssessmentTestId	Unique id representing the test selected by customer.	String	Yes
type	Type of the push event: `CREATE_THIRD_PARTY_ASSESSMENT` in this case.	Enum	Yes

Sample Request

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

{
   "assessmentId":"ABcdEF123456ABcdEF123456ABcdEF123456ABcdEF123456ABcdEF123456ABcdEF12345=",
   "hiringContext":"urn:li:contract:123",
   "type":"CREATE_THIRD_PARTY_ASSESSMENT",
   "thirdPartyAssessmentTestId":"TEST_123",
   "candidate":{
      "firstName":"test",
      "lastName":"candidate",
      "emailAddress":"test-candidate@outlook.com"
   },
   "requester":{
      "emailAddress":"test-requester@outlook.com"
   }
}

Note

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

Update Third-Party Assessment Information

Use the following API under given circumstances:

After generating an assessment entity in your system, use your application credentials to call the API to update the third-party assessment link and status as INITIATED
When the candidate starts assessment test, use the API to update start time and status to IN_PROGRESS
When the assessment is expired at provider's end, update the status to EXPIRED
When the assessment is completed by the candidate, update the third-party assessment end time, score, result, and status as COMPLETED

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

Any third-party assessment 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
extensionProvider	You should always supply `THIRD_PARTY` for this field.	Enum
id	Unique identifier of the third-party assessment test created within the domain of the contract obtained from push event.	String

Request Body Fields

Field Name	Description	Type	Required
assessmentTestUrl	URL to view this assessment 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 assessment.	Url	Yes
status	Enum indicating the status of the third-party assessment: `INITIATED`,`IN_PROGRESS`, `COMPLETED`, `EXPIRED`, `NEEDS_MANUAL_REVIEW`, `PROVIDER_EXCEPTION`	Enum	Yes
thirdPartyProviderExceptionType	Optional enum that represents the type of exception on provider side. This should be provided only when the status is `PROVIDER_EXCEPTION` Valid values are `CANDIDATE_INVITATION_FAILED`, `USER_NOT_ELIGIBLE`, `INVITE_ALREADY_SENT`, `ACCOUNT_NOT_ELIGIBLE`, `AUTHENTICATION_FAILURE`, `TEMPORARILY_UNAVAILABLE`, `SERVER_ERROR`	Enum	No
thirdPartyAssessmentScore	Assessment test score. You can supply “84/100”, “3/10” or any free text within the length limit, not exceeding 100 characters. This should be provided for status `COMPLETED`	String	No
thirdPartyAssessmentTestRating	Optional enum of assessment test results. Values are `IN_RANGE` or `OUT_OF_RANGE`. This should be provided for status `COMPLETED` and only if the customer has set up a clear cutoff on partner platform. If cutoff is not defined or is set to default value of zero, do not provide this field.	Enum	No
thirdPartyAssessmentTestDuration	Object including assessment test start and end time. This should be provided for status `IN_PROGRESS` or `COMPLETED`	Object	No
assessmentExpiredAt	Unix epoch time in milliseconds when assessment expired. This should be provided only when status is EXPIRED. This should be provided only when the status is `EXPIRED`	Epoch in Milliseconds (UTC)	No

Status

Enum Value	Description
INITIATED	Use this enum after generating the assessment in your system.
IN_PROGRESS	Use this enum when the candidate starts the assessment.
COMPLETED	Use this enum when the candidate completes the assessment.
EXPIRED	Use this enum when the candidate’s assessment expired. When providing this status, it is also mandatory to provide the value to the ‘assessmentExpiredAt’ field
NEEDS_MANUAL_REVIEW	Use this enum when the customer has opted for manual review before finalizing the assessment results. When providing this status, provide the correct 'assessmentTestUrl' field where the customer can review the report and take action.
PROVIDER_EXCEPTION	Use this enum when an error occurs while processing the assessment. When providing this status, ensure that you provide the correct value for thirdPartyProviderExceptionType field.

thirdPartyProviderExceptionType

Enum Value	Description
CANDIDATE_INVITATION_FAILED	Use this enum if the candidate invitation for taking assessment failed. For example, if the candidate's email address is invalid.
USER_NOT_ELIGIBLE	Use this enum if the user who is requesting to send the assessment is not authorized to send assessments.
INVITE_ALREADY_SENT	Use this enum if you detect that this user has already made a request to send out the specific assessment to the same candidate. We prefer if users can submit multiple requests if needed, but if your system does not allow that, this enum may be used.
ACCOUNT_NOT_ELIGIBLE	Use this enum if the customer account is not eligible to send assessments. For example, if the customer does not have enough credits to send assessments.
AUTHENTICATION_FAILURE	Use this enum if the customer credentials provided to access their account are invalid.
TEMPORARILY_UNAVAILABLE	Use this enum if the service is under maintenance or temporarily unavailable.
SERVER_ERROR	Use this enum if the server is not able to handle the request.

ThirdPartyAssessmentTestDuration

Field Name	Description	Type	Required
assessmentStartedAt	Unix epoch time in seconds when candidate started the assessment test.	Epoch in seconds (UTC)	No
assessmentEndedAt	Unix epoch time in seconds when candidate completed the assessment test.	Epoch in seconds (UTC)	No

Sample Request for Status Initiated

When the assessment is initiated at provider's side, update the status to INITIATED. In this case, the sample request will be as below:

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

Request Body:

{
  "patch": {
    "$set": {
      "assessmentTestUrl": "https://www.provider-url.com/assessment/8204345-45dsg-4fay",
      "status": "INITIATED"
    }    
  }
}

Sample Request for Status In Progress

When the assessment is in progress at provider's side, update the status to IN_PROGRESS. In this case, the sample request will be as below:

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

Request Body:
{
  "patch": {
    "$set": {
      "status": "IN_PROGRESS"
        }
    }
}

Sample Request for Status Completed

When the assessment is completed at provider's side, update the status to COMPLETED. In this case, the sample request will be as below:

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

Request Body:

{
  "patch": {
    "$set": {
      "status": "COMPLETED",
      "thirdPartyAssessmentScore": {
        "localized": {
          "en_US": "8/10"
        }
      },
      "thirdPartyAssessmentTestRating": "IN_RANGE",
      "thirdPartyAssessmentTestDuration": {
        "assessmentStartedAt": 1576184642343,
        "assessmentEndedAt": 1577855383543
      }
    }
  }
}

Sample Request for Status Expired

When the assessment is expired at provider's side, update the status to EXPIRED. In this case, the sample request will be as below:

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

Request Body:

{
  "patch": {
    "$set": {
      "assessmentTestUrl": "https://www.provider-url.com/assessment/8204345-45dsg-4fay",
      "assessmentExpiredAt":1576184642343,
      "status": "EXPIRED"
    }    
  }
}

Rate Limits and Throttling

All of LinkedIn’s APIs 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`

Talent Hub Assessments Integration

Configure Customer Integration

Request Body Fields

AvailableThirdPartyAssessmentsTest

Sample Request

Receive a Push Event from LinkedIn

Request Body Fields

Sample Request

Update Third-Party Assessment Information

Request Body Fields

Status

thirdPartyProviderExceptionType

ThirdPartyAssessmentTestDuration

Sample Request for Status Initiated

Sample Request for Status In Progress

Sample Request for Status Completed

Sample Request for Status Expired

Rate Limits and Throttling

Feedback

Feedback

Additional resources