Talent Hub Interview 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 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_UNAVAILABLE`and `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`

Partager via

Talent Hub Interview Integration

Types of Interviews

Configure Interview Integrations

Request Body Fields

Configuration Fields

Sample Request

Create Third-Party Interview

Receive a Push Event from LinkedIn

Push Notification Request Body Fields

Configuration Fields

Sample Request

Update Third-Party Interview

Request Body Fields

Sample Request

Reschedule Third-Party Interview

Receive a Push Event from LinkedIn

Push Notification for One-to-One Interview

Sample Request

Push Notification for Panel Interviews

Sample Request

Delete a Third-Party Interview

Delete Push Notification Request Body Fields

Sample Request

Rate Limits and Throttling

Commentaires

Ressources supplémentaires