Share via

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 EXPORT_JOB_APPLICATION 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. 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
locationAnswer Applicant’s location answer, this field will not be present if no answer is provided. LocationAnswer
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
DateAnswerValue If this field is present, then all other fields will be null. An answer to the date question. DateAnswerValue

TextAnswerValue Fields

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

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

DateAnswerValue Fields

Field Description Type
date Applicant’s answer for the question. Date

LocationAnswer Fields

Field Description Type
locationCityAnswer Applicant’s city answer, null if no city location is provided. locationCityAnswer
locationCountryAnswer Applicant’s country answer, null if no Country location is provided. LocationCountryAnswer
locationLatLong Answer to geo location question, null if no geo location is provided. LocationLatLong
locationStateAnswer Applicant’s state answer, null if no State location is provided. locationStateAnswer

Note

  • If an applicant selects a location with only state and country (no city):

    • locationCityAnswer will be null since no city is provided.
    • locationStateAnswer and locationCountryAnswer will contain the values for the selected state and country.
    • locationLatLong will still provide valid geo-location data.

  • If an applicant selects a region (rather than a specific location):

    • All location-related fields (locationCityAnswer, locationStateAnswer, locationCountryAnswer, locationLatLong) will be null.

LocationStateAnswer Fields

Field Description Type
value Applicant’s answer for this question, comma separated. String

LocationCityAnswer Fields

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

LocationCountryAnswer Fields

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

LocationLatLong Fields

Field Description Type
longitude Longitude of the answered location. float
latitude Latitude of the answered location. float

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"
          }
        }
      ]
    },
    "locationAnswer": {
      "locationStateAnswer": "San Francisco, California, United States",
      "locationLatLong": {
        "longitude": -122.42016,
        "latitude": 37.78008
      },
      "locationCityAnswer": "San Francisco",
      "locationCountryAnswer": "US"
    },
    "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

Application Delivery Failure Email

The applicants receive the following email notification when their application fails to deliver. Selecting Apply on company website redirects them to apply directly on the company's website.
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"
         }
       }
    }]
}