Receive Applications

When LinkedIn receives a job application for your job posting, we will make a POST to the jobApplicationWebhookUrl which you have registered to the JobPosting. You must return a 200 OK status code to indicate that the application has been successfully received by your servers. LinkedIn will attempt to re-send the application 6 times if a non-200 status code is returned.

As part of the payload, you will be receiving a job application ID. You must store this ID so that it can be used in the Applicant Highlights Plugin, Apply Connect Full Profile Plugin, and as part of the Job Application Feedback API.

Important

If the first application fails to deliver, the job will be converted to an off-site apply using the companyApplyUrl provided in the payload.

Requirements

• Respond to all LinkedIn validation requests.
• Verify validity of push event requests using the x-li-signature.
• Respond with a 200 HTTP status code indicating successful delivery of the notification to your webhook.
• Create or supplement existing candidate application details from delivered application response.
• Add source attribution to application as "LinkedIn apply".
• For failed application delivery (non-200 HTTP response), provide the associated errorCode and additionalErrorDetails documented.

Validate the Request

LinkedIn will use a secret key to generate an "HMACSHA256" signature of the escaped Unicode version of the request payload prefixed by "hmacsha256=". This signature is then included as an X-LI-Signature header in the HTTP POST request sent from LinkedIn servers. Use the secret key associated with your API Key in order to validate the signature included in the request.

The computed HMAC can be tested using a free HMAC Generator. Using "hmacsha256=" and appending the request payload, the computed HMAC should match the X-LI-Signature from the request when using the associated secret key.

Webhook Endpoint Validation

Important

You will not need to register a Webhook URL in the Developer Portal, the jobApplicationWebhookUrl is provided in the job payload when creating an OnsiteApplyConfigured Job.

To ensure that webhook URLs are not compromised by malicious actors. All jobApplicationWebhookUrls must support the Webhook Endpoint Validation flow, specified here.

Receive Job Applications

Sample Request

POST https://{jobApplicationWebhookUrl}

JobApplicationWebhookUrl Payload Fields

Field	Description	Type
type	Type of push event. This will always be JOB_APPLICATION_EXPORT for Apply Connect use-cases.	Enum
externalJobId	Reference id of the external job in partner’s system to which the applicant applied.	String
jobApplicationId	Represents the unique job application id on LinkedIn. This id must be saved and passed into Applicant Highlights widget as a parameter in order to properly display Applicant Highlights for this applicant. This id is also used by the JobApplicationLifecycleActions API. Partners should save this String in its entirety as the format of the String is subject to change in the future.	String
appliedAt	When the job application was submitted. Represented in milliseconds since epoch.	Long
questionResponses	Responses to job application questions.	SimpleTalentQuestionResponses
applicantSkills[]	Array of skills that the applicant has. Currently, this list will contain explicit skills listed by the applicant on their LinkedIn profile that match the job posting's standardized skills, as well as all skills for which an applicant has completed a skill assessment, regardless of if that skill matches the job posting's standardized skills. If a partner is ineligible to receive skills due to contractual agreement , then this field will not be present in the payload. Otherwise, this field will contain an array of the applicant's skills (will be an empty array if applicant has no skills, null if LinkedIn encounters an issue retrieving applicant skills).	ApplicantSkill[]
jobApplicant	Represents the unique job applicant id on LinkedIn.	PersonUrn in format urn:li:person:{id}

SimpleTalentQuestionResponses Fields

Field	Description	Type
contactInformationQuestionResponses	Responses to Contact Information questions. This field will always be present as First Name, Last Name, and Email will always be included as part of Contact Information.	ContactInformationQuestionResponses
resumeQuestionResponses	Responses to Resume questions, null if there are no Resume questions	ResumeQuestionResponses
coverLetterQuestionResponses	Responses to Cover Letter questions, null if there are no Cover Letter questions.	CoverLetterQuestionResponses
workQuestionResponses	Responses to Work questions, null if there are no Work questions.	WorkQuestionResponses
educationQuestionResponses	Responses to Education questions, null if there are no Education questions.	EducationQuestionResponses
voluntarySelfIdentificationQuestionResponses	Responses to Voluntary Self Identification questions, null if there are no Voluntary Self Identification questions.	VoluntarySelfIdentificationQuestionResponses
additionalQuestionResponses	Responses to questions in "Additional Questions" section, null if there are no responses to CustomQuestionSets.	AdditionalQuestionResponses

ApplicantSkill Fields

Field	Description	Type
skillUrn	Unique identifier for this skill. Partners can use these urns to batch get skills data from the externalized skills endpoint, specifying their request locale.	SkillUrn
skillName	Standardized name for this skill.	String
jobMatched	Whether this skill matched the job posting’s skills.	boolean
assessmentVerified	Whether the applicant has passed a skill assessment for this skill.	boolean

ContactInformationQuestionResponses Fields

Field	Description	Type
firstNameAnswer	Applicant’s first name, this field will always be present.	TextAnswerValue
lastNameAnswer	Applicant’s last name, this field will always be present.	TextAnswerValue
emailAnswer	Applicant’s email, this field will always be present.	TextAnswerValue
middleNameAnswer	Applicant’s middle name, null if no middle name provided.	TextAnswerValue
cellphoneNumberQuestionAnswer	Applicant’s cellphone number, null if no cellphone provided.	PhoneNumberAnswerValue
customQuestionResponses	Responses to custom questions within this question section. This field will not be present in the payload if no custom questions were included. Otherwise, this field will have a list containing question responses that an applicant has provided.	SimpleTalentQuestionResponse[]

ResumeQuestionResponses Fields

Field	Description	Type
resumeQuestionAnswer	Resume question response, null if no resume provided.	DocumentAnswerValue
customQuestionResponses	Responses to custom questions within this question section. This field will not be present in the payload if no custom questions were included. Otherwise, this field will have a list containing question responses that an applicant has provided.	SimpleTalentQuestionResponse[]

CoverLetterQuestionResponses Fields

Field	Description	Type
coverLetterQuestionAnswer	Cover Letter question response, null if no cover letter provided.	DocumentAnswerValue
textCoverLetterQuestionAnswer	Text cover letter question response, null if no text cover letter inputted.	SimpleTalentQuestionResponse[]
customQuestionResponses	Responses to custom questions within this question section. This field will not be present in the payload if no custom questions were included. Otherwise, this field will have a list containing question responses that an applicant has provided.	SimpleTalentQuestionResponse[]

WorkExperienceQuestionSetResponses Fields

Field	Description	Type
city	Response to city question.	TextAnswerValue
company	Response to company question.	TextAnswerValue
description	Response to description question.	TextAnswerValue
employmentDates	Dates attended at educational institution.	DateRangeAnswerValue
title	Response to title question.	TextAnswerValue
customQuestionResponses	Responses to custom questions within this question section. This field will not be present in the payload if no custom questions were included. Otherwise, this field will have a list containing question responses that an applicant has provided.	SimpleTalentQuestionResponse[]

EducationQuestionResponses Fields

Field	Description	Type
educationExperienceQuestionSetResponses	Array of responses to repeating EducationExperienceQuestionSets.	EducationExperienceQuestionSetResponse[]
customQuestionResponses	Responses to custom questions within this question section. This field will not be present in the payload if no custom questions were included. Otherwise, this field will have a list containing question responses that an applicant has provided.	SimpleTalentQuestionResponse[]

EducationExperienceQuestionSetResponses Fields

Field	Description	Type
city	Response to city question.	TextAnswerValue
degree	Response to degree question.	TextAnswerValue
datesAttended	Dates attended at educational institution.	DateRangeAnswerValue
fieldOfStudy	Response to Field of Study question.	TextAnswerValue
school	Response to school question.	TextAnswerValue
customQuestionResponses	Responses to custom questions within this question section. This field will not be present in the payload if no custom questions were included. Otherwise, this field will have a list containing question responses that an applicant has provided.	SimpleTalentQuestionResponse[]

VoluntarySelfIdentificationQuestionResponses Fields

Field	Description	Type
disabilityAnswer	Answer to disability question.	DisabilityAnswer Enum
genderAnswer	Answer to gender question.	GenderAnswer Enum
raceAnswer	Answer to race question.	RaceAnswer Enum
veteranStatusAnswer	Answer to veteran status question.	VeteranStatus Enum
customQuestionResponses	Responses to custom questions within this question section. This field will not be present in the payload if no custom questions were included. Otherwise, this field will have a list containing question responses that an applicant has provided.	SimpleTalentQuestionResponse[]

DisabilityAnswer Enum Values

Value	Description
YES	Applicant answered "Yes, I Have A Disability, Or Have A History/Record Of Having A Disability".
NO	Applicant answered "No, I Don't Have A Disability, Or A History/Record Of Having A Disability".
OPT_OUT	Applicant answered "I don't wish to answer".

GenderAnswer Enum Values

Value	Description
MALE	Applicant answered "Male".
FEMALE	Applicant answered “Female”.
OPT_OUT	Applicant answered "I prefer not to specify".

RaceAnswer Enum Values

Value	Description
HISPANIC_OR_LATINO	Applicant answered "Hispanic or Latino".
AMERICAN_INDIAN_OR_ALASKA_NATIVE	Applicant answered “American Indian or Alaska Native (Not Hispanic or Latino)”.
ASIAN	Applicant answered "Asian (Not Hispanic or Latino)".
BLACK_OR_AFRICAN_AMERICAN	Applicant answered “Black or African American (Not Hispanic or Latino)”.
NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLANDER	Applicant answered “Native Hawaiian or Other Pacific Islander (Not Hispanic or Latino)”.
TWO_OR_MORE_RACES	Applicant answered “Two or More Races (Not Hispanic or Latino)”.
WHITE	Applicant answered “White (Not Hispanic or Latino)”.
OPT_OUT	Applicant answered “I prefer not to specify”.

VeteranStatusAnswer Enum Values

Value	Description
PROTECTED_VETERAN	Applicant answered "I identify as one or more of the classifications of protected veteran listed above".
NOT_PROTECTED_VETERAN	Applicant answered "I am not a protected veteran".
OPT_OUT	Applicant answered "I prefer not to specify".

AdditionalQuestionResponses Fields

Field	Description	Type
customQuestionSetResponses	A list of responses to custom question sets.	CustomQuestionResponses[]

CustomQuestionResponses Fields

Field	Description	Type
customQuestionSetResponses	Responses to custom questions within this question set.	SimpleTalentQuestionResponse[]

SimpleTalentQuestionResponse Fields

Field	Description	Type
questionIdentifier	The questionIdentifier used in the SimpleTalentQuestion. This should be used by external systems to map the response to the corresponding question. This field is provided by external systems (e.g., ATS partners') and LinkedIn system does not use this field as identifier.	String
answer	Answer to the question.	SimpleAnswerValue

SimpleAnswerValue Fields

Field	Description	Type
DocumentAnswerValue	If this field is present, then all other fields will be null. An answer to a document question.	DocumentAnswerValue
multipleChoiceAnswerValue	If this field is present, then all other fields will be null. An answer to a multiple choice question.	MultipleChoiceAnswerValue
numericAnswerValue	If this field is present, then all other fields will be null. An answer to a numeric question.	NumericAnswerValue
phoneNumberAnswerValue	If this field is present, then all other fields will be null. An answer to a phone number question.	PhoneNumberAnswerValue
TextAnswerValue	If this field is present, then all other fields will be null. An answer to a text question.	TextAnswerValue

BooleanAnswerValue Fields

Field	Description	Type
value	Applicant’s answer for this question.	boolean

DateRangeAnswerValue Fields

Field	Description	Type
dateRange	Applicant’s answer for this question.	DateRange

DateRange Fields

Field	Description	Type
start	Represents the inclusive (greater than or equal to) value in which to start the range. This value is optional. An unset field indicates an open range; for example if start is not set, and end is 01/01/2016, it indicates values before 01/01/2016.	Date
end	Represents the exclusive (strictly less than) value in which to end the range. This value is optional. An unset field indicates an open range, for example if end is not set, and start is 01/01/2016, it indicates values on or after 01/01/2016.	Date

Date Fields

Field	Description	Type
day	Day of date.	integer
month	Month of date.	integer
year	Year of date	integer

DocumentAnswerValue Fields

Field	Description	Type
mediaUrn	MediaUrn that represents the document.	MediaUrn
mediaUrl	MediaUrl that represents the location of the document.	MediaUrl

MultipleChoiceAnswerValue Fields

Field	Description	Type
symbolicNames	An array of symbolic names for the answer value from the array of choices. The array may only have more than one item if the multiple choice question accepts multiple answers.	String[]

NumericAnswerValue Fields

Field	Description	Type
integerValue	This field is present if the member's answer is an integer. DecimalValue will be null if this field is present	integer
decimalValue	This field is present if the member’s answer is a decimal. IntegerValue will be null if this field is present.	float

PhoneNumberAnswerValue Fields

Field	Description	Type
countryCode	Country code for the phone number. It's an integer in string format. Also called IDD (International Direct Dialing) or ISD (International Subscriber Dialing) codes. For example, the country code for Switzerland is '41'.	String
nationalNumber	The phone number you would dial if you were in the same country/region.	String
extension	The extension number for this phone number, null if no extension.	String

TextAnswerValue Fields

Field	Description	Type
value	Applicant’s answer for this text question.	String

Sample Payload

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

{
  "type": "JOB_APPLICATION_EXPORT",
  "externalJobId": "jobIdOnAtsPartner",
  "jobApplicationId": "urn:li:jobApplication:12345678",
  "jobApplicant": "urn:li:person:abc123",
  "appliedAt": 1602137400011,
  "applicantSkills": [
    {
      "skillUrn": "urn:li:skill:12345",
      "skillName": "Java",
      "jobMatched": true,
      "assessmentVerified": true
    }
  ],
  "questionResponses": {
    "resumeQuestionResponses":
        {"resumeQuestionAnswer":
            {"mediaUrl":"https://www.linkedin.com/ambry/?x-li-ambry-ep=AQFBV...",
            "mediaUrn":"urn:li:media:AgAAA..."}​
      },
    "contactInformationQuestionResponses": {
      "firstNameAnswer": {
        "value": "First"
      },
      "lastNameAnswer": {
        "value": "Last"
      },
      "emailAnswer": {
        "value": "applicant@linkedin.com"
      }
    },
    "voluntarySelfIdentificationQuestionResponses": {
      "disabilityAnswer": "NO",
      "genderAnswer": "MALE",
      "raceAnswer": "ASIAN",
      "veteranStatusAnswer": "NOT_PROTECTED_VETERAN"
    },
    "educationQuestionResponses": {
      "educationExperienceQuestionSetResponses": [
        {
          "school": {
            "value": "UC Berkeley"
          }
        }
      ]
    },
    "workQuestionResponses": {
      "workExperienceQuestionSetResponses": [
        {
          "company": {
            "value": "LinkedIn"
          },
          "title": {
            "value": "Software Engineer"
          }
        }
      ]
    },
    "additionalQuestionResponses": {
      "customQuestionSetResponses": [
        {
          "customQuestionResponses": [
            {
              "questionIdentifier": "question1",
              "answer": {
                "multipleChoiceAnswerValue": {
                  "symbolicNames": [
                    "right"
                  ]
                }
              }
            }
          ]
        }
      ]
    }
  }
}

Retrieve Applicant Media Files

The mediaUrl will be returned when the applicant uploads a resume, cover letter, or additional files with their job application. This media is short-lived and will be available for 30 days. This url can be accessed and the media file stored for use within your application.

Sample Request

GET https://www.linkedin.com/ambry/?x-li-ambry-ep=AQFBV...

Sample Headers

Authorization: Bearer {access_token}

Note

Use the content-type header in the response to indicate how the media data should be interpreted.

Troubleshooting

In a browser you can paste the mediaUrl and an active access token using the oauth2_access_token field to download the resume media.

https://www.linkedin.com/ambry/?x-li-ambry-ep=AQFBV...&oauth2_access_token=AQXsov...

Query Parameters

Field	Description	Required
oauth2_access_token	Access token of the application which received the mediaUrl.	Yes

Error Handling

If an application delivery is attempted and your system is unable to process, return the HTTP response and the associated errorCode and additionalErrorDetails in the response body to LinkedIn.

The following error codes can be returned:

Error Code	Description	Job Posting Behavior	Impact to Applicant
MISSING_REQUIRED_RESPONSE	Responses missing for the required questions	No change	Will receive application delivery failure email
INPUT_VALIDATION_FAILED	Failed Input validation For example - Phone number is entered in such a way ATS doesn’t accept or incorrect formatting or file type for the attachments or size of the attachment exceeded	No change	Will receive application delivery failure email
DUPLICATE_APPLICATION_RECEIVED	Duplicate job application is received. Only if the applicationId of the incoming application matches that of the application that was already received	No change	Will Receive Successful Delivery Email
JOB_POSTING_CLOSED	Job Posting is closed and cannot receive any more applications	Disable onsite apply (LinkedIn apply) and redirect to apply url	Will receive application delivery failure email
TOO_MANY_REQUESTS	Too many application submissions at the same time	No change	Will retry to deliver application, once retries have been exhausted applicant will receive application delivery failure email
SIGNATURE_MISMATCH	The signature from the job application failed to match with the partner's signature	No change	Will not retry to deliver as this will be considered as a fatal error
TRANSIENT_ERROR	Unknown Error on ATS end. Only use this when confident that the application should be retried after a short-delay	No change	Will retry to deliver application, once retries have been exhausted applicant will receive application delivery failure email
OTHER	Error caused by other unknown issues. To be sent by the partner when the error doesn't fall into the above categories	No	Will retry to deliver application, once retries have been exhausted applicant will receive application delivery failure email

Error Response Schema

The error response schemas as listed below:

ApplicationDeliveryErrorDetails Schema

Field	Required	Type	Description
errors	Optional	Array(ApplicationDeliveryError)	Error details include error code and the corresponding error details sent by the partner

ApplicationDeliveryError Schema

Field	Required	Type	Description
errorCode	Yes	enum	The error code to represent the error, if any, that may have occurred during application delivery failure
additionalErrorDetails	Optional	record	Additional information on the delivery failure

AdditionalErrorDetails Schema

Field	Required	Type
missingQuestionResponseErrorDetails	Optional	record
inputValidationErrorDetails	Optional	record
otherErrorDetails	Optional	String
duplicateApplicationErrorDetails	Optional	record

MissingQuestionResponseErrorDetails Schema

Field	Required	Type
partnerQuestionIdentifiers	Yes	Array(string)

InputValidationErrorDetails Schema

Field	Required	Type
invalidInputQuestionIdentifierDetails	Yes	Array invalidInputQuestionIdentifierDetails

InvalidInputQuestionIdentifierDetails Schema

Field	Required	Type
partnerQuestionIdentifier	Yes	String
validationHint	Optional	String

DuplicateApplicationErrorDetails Schema

Field	Required	Type
duplicateApplicationId	Optional	String

Sample Application Delivery Response

Sample Missing Required Response

{
"errors": [{
"errorCode":"MISSING_REQUIRED_RESPONSE",
"additionalErrorDetails": {
    "missingQuestionResponseErrorDetails": {
        "partnerQuestionIdentifiers":["93940492"]
      }
     }
   }]
}

Sample Input Validation Response

{
    "errors": [
      {
        "errorCode": "INPUT_VALIDATION_FAILED",
        "additionalErrorDetails": {
          "inputValidationErrorDetails": {
            "invalidInputQuestionIdentifierDetails": [
              {
                "partnerQuestionIdentifier": "12345",
                "validationHint": "Invalid Zip Code"
              }
            ]
          }
        }
      }
    ]
  }

Sample Duplicate Application Response

{
"errors": [{
"errorCode":"DUPLICATE_APPLICATION_RECEIVED",
"additionalErrorDetails": {
    "duplicateApplicationErrorDetails": {
        "duplicateApplicationId":"93940492"
         }
       }
    }]
}