Partager via


Talent Hub Interview 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 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.

Types of Interviews

LinkedIn supports the following two types of interviews:

  • One-to-One Interview - Initiated by the recruiter via InMail or Email to set up a time to Interview or meet with a prospect. The prospective candidate receives a link to schedule time on the recruiter’s calendar.
  • Panel Interview - Multi-part interview scheduled by a recruiter with a candidate and the hiring panel, through the Schedule Interview feature in Talent Hub. Panel interviews contain one or more interview time slots for each interviewer.

Configure Interview Integrations

LinkedIn gives a way for you to customize your interview integration by providing a set of provider configurations. Provider configurations allow you to specify integration configurations that your integration supports. Toggling each configuration results in a slightly different user experience for customers within LinkedIn, as well as possibly different payload parameters for API interaction. Below is a list of all configurations and their default values LinkedIn currently supports for interview integrations. If you have any special requests, please contact the member from LinkedIn Business Development who you have been working with.

To customize your interview integration, use your application credentials to call the following API:

POST https://api.linkedin.com/v2/hireThirdPartyExtensionProviders/extensionType={extensionType}&extensionProvider=THIRD_PARTY

Interview integration is uniquely identified by a combination of the fields below:

Field Name Description Type
extensionType Enum indicating type of the integration: INTERVIEW in this case. Enum
extensionProvider You should always supply THIRD_PARTY for this field. Enum

Request Body Fields

Field Name Description Type Required
configuration All configurations for your interview extension. Boolean Yes

Configuration Fields

Field Name Description Type Required
codeEditorConfigurable Indicating if LinkedIn should allow customer to configure whether code editor should be enabled when creating an interview. Default is false. Boolean Yes
codeExecutionConfigurable Indicating if LinkedIn should allow customers to configure whether code execution should be enabled when creating an interview. Default is false. Boolean Yes
interviewSummaryConfigurable Indicating if LinkedIn should allow customers to configure whether interview summary should be enabled when creating an interview. Default is false. Boolean Yes

Note

Support for Talent Hub UI for the customer to configure the above fields will be released in future.

Sample Request

Note

A successful request returns a 204 response code.

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

Request Body:
{
  "patch": {
    "$set": {
      "configuration": {
        "interviewConfiguration": {
          "codeEditorConfigurable": true,
          "codeExecutionConfigurable": false,
          "interviewSummaryConfigurable": false
        }
      }
    }
  }
}

Update only one configuration setting at a time using the following syntax in the request body:

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

Request Body:
{
   "patch": {
      "configuration": {
         "interviewConfiguration": {
            "$set": {
               "interviewSummaryConfigurable": false
            }
         }
      }
   }
}

Create Third-Party Interview

Recruiters can choose to create a third-party interview when scheduling interviews in LinkedIn.

Receive a Push Event from LinkedIn

When a customer creates an interview request on LinkedIn with your integration, LinkedIn sends a push notification to your callback URL registered during the onboarding process. See Receiving Push Notifications for how to validate the request.

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

Push Notification Request Body Fields

Field Name Description Type Required
type Type of the push event: CREATE_THIRD_PARTY_INTERVIEW in this case. For reschedule, the type of push event is UPDATE_THIRD_PARTY_INTERVIEW Enum Yes
hiringContext Hiring context of the customer in the format of urn:li:contract:123 URN Yes
interviewId Unique identifier of the third-party interview created within the domain of the hiring context String Yes
interviewName Name of the third-party interview. Null if the name of the interview is not available String Yes
interviewGroupId Unique identifier of the interview group within LinkedIn to which the third-party interview belongs String Yes
startsAt Time in milliseconds since midnight, January 1, 1970 UTC. Null if the interview start time is not available Long Yes
durationInMilliseconds Duration of the interview in milliseconds. Null if the interview duration is not available Long Yes
configuration Configuration of the third-party interview creation request Object Yes
requesterFirstName First name of the requester of this interview. Null if the requester first name is not available String Yes
requesterLastName Last name of the requester of this interview. Null if the requester last name is not available String Yes
requesterEmailAddress Email address of the requester of this interview. Null if the requester emailAddress is not available 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 interview request. These requester details can also be embedded by the provider in customer communications.

Configuration Fields

Field Name Description Type Required
codeEditorEnabled Whether code editor should be enabled for this interview. This payload field will only appear if “codeEditorConfigurable” for your extension is true. Boolean No
codeExecutionEnabled Whether code execution should be enabled for this interview. This payload field will only appear if “codeExecutionConfigurable” for your extension is true. Boolean No
interviewSummaryEnabled Whether interview summary should be enabled for this interview. This payload field will only appear if “interviewSummaryConfigurable” for your extension is true. Boolean No

Sample Request

Below represents the sample push notification for creating interview:


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

{  
  "type": "CREATE_THIRD_PARTY_INTERVIEW",
  "hiringContext": "urn:li:contract:123",
  "interviewId": "YzZkYzcxNzEtYzBmNC00YzBjLWFlNTktOGZjN2U0ZDhmO",
  "interviewName": "System Design and Architecture",
  "interviewGroupdId": "urn:li:interview:(urn:li:contract:123,27)",
  "startsAt": 1527651734162,
  "durationInMilliseconds": 360000,
  "configuration": {
    "codeEditorEnabled": true,
    "codeExecutionEnabled": false,
    "interviewSummaryEnabled": true
  },
  "requesterLastName":"requester",
  "requesterFirstName":"test",
  "requesterEmailAddress": "test-requester@outlook.com"
}

If a push event sent to the registered callback URL receives an unsuccessful response (something other than “200 OK”), LinkedIn retries sending the request up to six times. After six failed attempts, LinkedIn notifies customer about the failure. The customer then has the option to create an interview again.

Note

A panel interview can contain more than one interview slots. For every interview slot present, a push notification with event type "CREATE_THIRD_PARTY_INTERVIEW" is sent.

Update Third-Party Interview

After generating an interview entity in your system, use your application credentials to call the following API to update the third-party interview link, access code, and set status as PROVIDER_READY on LinkedIn. When the interview starts, use the same API to update the status as STARTED. Similarly, update the status as COMPLETED when the interview ends. In case of any error, ensure that the status is set to PROVIDER_EXCEPTION.

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

Any third-party Interview 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
interviewId Unique identifier of the third-party interview 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
candidateInterviewUrl URL of this interview in your system for candidate to access. URL No
candidateAccessCode Access code for candidate to access the interview in your system. String No
interviewerInterviewUrl URL of this interview in your system for the interviewer to access. URL No
interviewerAccessCode Access code for interviewer to access the interview in your system. String No
interviewSummaryUrl Url of the interview summary (code snapshot, transcript, etc.) in your system for the interviewer to access. This should be provided when status is set to COMPLETED URL Yes
status Enum indicating the status of the third-party interview. Valid values are: PROVIDER_READY, PROVIDER_EXCEPTION, STARTED, COMPLETED Enum Yes
interviewUrlSecured If True, a secure meeting URL (meeting URL with embedded access code) will be sent in the meeting invite. Default is False Boolean No
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,AUTHENTICATION_FAILURE, TEMPORARILY_UNAVAILABLEand SERVER_ERROR Enum No
providerExceptionMessage Use this field to pass the custom partner error message to LinkedIn. The allowed maximum length is 180 characters String No

Sample Request

Below represents the sample request when status is PROVIDER_READY.

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

Request Body:
{
  "patch": {
    "$set": {
      "candidateInterviewUrl": "https://www.provider-url.com/interviews/7944c32c-821b-c183",
      "candidateAccessCode": "61fj2i25",
      "interviewerInterviewUrl": "https://www.provider-url.com/interviews/7944c32c-821b-c184",
      "interviewerAccessCode": "k92d2g2",
      "status": "PROVIDER_READY"
    }
  }
}

Customers can send emails to interview participants and notify them about the interview link and access code using their templates within LinkedIn. Your system does not need to contact participants about the interview.

If your system is not able to process the interview creation request for any reasons(for example, customer does not have enough credit), your system should notify us about the exception by updating the status to be PROVIDER_EXCEPTION along with exception type. LinkedIn notifies customer about the exception.

Below represents the sample request when status is PROVIDER_EXCEPTION

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

Request Body:

{
  "patch": {
    "$set": {
      "status": "PROVIDER_EXCEPTION",
      "providerExceptionType": "ACCOUNT_NOT_ELIGIBLE"
    }
  }
}

Below represents the sample request when status is STARTED.

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

Request Body:

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

Below represents the sample request when status is COMPLETED.

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

Request Body:

{
  "patch": {
    "$set": {
      "interviewSummaryUrl": "https://www.provider-url.com/interviewSummaries/7944c32c-821b-c184",
      "status": "COMPLETED"
    }
  }
}

Reschedule Third-Party Interview

Already created third-party interviews can be rescheduled, if needed.

Receive a Push Event from LinkedIn

When a customer reschedules an interview request on LinkedIn with your integration, LinkedIn sends a push notification to your callback URL registered during the onboarding process. See Receiving Push Notifications for how to validate the request.

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

Push Notification for One-to-One Interview

For One-to-One interviews that are scheduled via InMail, the candidate can reschedule an interview slot as per the calendar availability of the interviewer. LinkedIn provides a tracking URL for the candidate to find related interview details. The candidate can opt to reschedule the interview, after which LinkedIn sends a push notification of the type "UPDATE_THIRD_PARTY_INTERVIEW" to the provider.

The request body fields received for update push notification are similar to Create Third-Party Interview

Sample Request

Below represents the sample push notification for a rescheduled One-to-One interview:


"Content-Type": "application/json",
"X-LI-Signature": "5a1c2fdbd16fbba7e3816fsf23dfasc06eda80f9364b5c",
"Content-Length": "186",
"Connection": "Keep-Alive",
"Accept-Encoding": "gzip,deflate"
{
"hiringContext": "urn:li:contract:123456789",
"interviewId": "OTM3MzlkYTQtMWQ3NC00ZDI1LWI1YWQtODA1Nzg4OTg1OGQ4OjE2MTk2OTU4ODMyNTM6MTA=",
"configuration": {
    "codeEditorEnabled": true,
    "codeExecutionEnabled": false,
    "interviewSummaryEnabled": true
},
"durationInMilliseconds": 1800000,
"startsAt": 1620021600000,
"interviewGroupId": "urn:li:interview:(urn:li:contract:123456789,3046404)",
"requesterEmailAddress": "abcd@linkedin.com",
"type": "UPDATE_THIRD_PARTY_INTERVIEW"
}

Push Notification for Panel Interviews

For panel interviews, the recruiter can reschedule an interview. In this case, LinkedIn sends a push notification of the type "DELETE_THIRD_PARTY_INTERVIEW" with interviewGroupIdvalue and interviewId only for the rescheduled interview slots. This is then followed by a ‘CREATE_THIRD_PARTY_INTERVIEW’ push notification with new interviewId for the rescheduled interview slots and the interviewGroupId same as the interview panel prior to re-scheduling.

Refer to Delete Third-Party Interview and Create Third-Party Interview push notifications for request body fields.

Sample Request

Below represents the sample delete push notification for an interview slot:


"Content-Type": "application/json",
"X-LI-Signature": "5a1c2fdbd16fbba7e3816fsf23dfasc06eda80f9364b5c",
"Content-Length": "186",
"Connection": "Keep-Alive",
"Accept-Encoding": "gzip,deflate"
{
  "hiringContext": "urn:li:contract:123456789",
  "interviewId": "Zjc4ZGYzNTctOTY4MC00ZDMwLThmMTQtMDViZjI0MWZhYTM3OjE2MTk3MDE3ODk1NTE6MTI=",
  "interviewGroupId": "urn:li:interview:(urn:li:contract:251956473,2988170)",
  "type": "DELETE_THIRD_PARTY_INTERVIEW"
}

Below represents the sample create push notification for a rescheduled interview slot:


"Content-Type": "application/json",
"X-LI-Signature": "5a1c2dddd16fbba7e3816fsf23dfasc06eda80f9364b5c",
"Content-Length": "186",
"Connection": "Keep-Alive",
"Accept-Encoding": "gzip,deflate"
{
  "hiringContext": "urn:li:contract:123456789",
  "interviewId": "N2MyZDc1ZmEtYjk4Zi00NDMzLThkMGQtOTlhYTg4ZDM4YjY5OjE2MTk3MDIxNzg2Mzg6MTI=",
  "configuration": {
    "codeEditorEnabled": true,
    "codeExecutionEnabled": false,
    "interviewSummaryEnabled": true
  },
  "durationInMilliseconds": 3600000,
  "startsAt": 1619805600000,
  "interviewGroupId": "urn:li:interview:(urn:li:contract:123456789,2988178)",
  "requesterEmailAddress": "abcd@linkedin.com",
  "type": "CREATE_THIRD_PARTY_INTERVIEW"
}

Delete a Third-Party Interview

When a customer deletes a third-party interview, LinkedIn sends a push event to your registered callback URL. See Receiving Push Notifications for how to validate the request.

POST https:// {your registered unique callback URL for the customer}

Note

Deletion for One-to-One interview is not supported.

Delete Push Notification Request Body Fields

Field Name Description Type Required
type Type of the push event: DELETE_THIRD_PARTY_INTERVIEW in this case. Enum Yes
hiringContext Hiring context of the customer in the format of urn:li:contract:123 URN Yes
interviewId Unique identifier of the third-party interview created within the domain of the hiring context obtained from push event String Yes
interviewGroupId Unique identifier of the interview group within LinkedIn to which the third-party interview belongs. String Yes

Sample Request

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

{  
  "type": "DELETE_THIRD_PARTY_INTERVIEW",
  "hiringContext": "urn:li:contract:123",
  "interviewId": "YzZkYzcxNzEtYzBmNC00YzBjLWFlNTktOGZjN2U0ZDhmO",
  "interviewGroupId": "urn:li:interview:(urn:li:contract:123456789,2988178)"
}

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 document.

Throttle Limits Request Per Day (UTC) Action
Application Maximum (max requests per app) 5000 Calls will be rejected with a status code of 429