Job Status Change Notifications
After jobs have successfully posted on LinkedIn a jobs' status can change at a later time. Some examples are jobs converting from an on-site to off-site application flow, jobs being reported by members resulting in that job being closed, or the promotion status changed by LinkedIn or the customer. With those changes partners do not have visibility into these changes as they happen, and have no way to retrieve the current status of a job posting on LinkedIn. This limitation also prevents ATS partners from having a way to display accurate job status information to customers in their UI.
With the Job Status Change Notifications API this allows partners to be notified by LinkedIn in near real-time of up-to-date statuses of their customer posted jobs.
Note
Ensure to register and enable only one webhook for each event type per parent application in the developer portal's webhooks tab.
Requirements
- Configure a webhook url which is publicly acccesible.
- Register and validate the webhook url in the LinkedIn Developer Portal
Webhook Registration and Validation
To receive notifications at your webhook, your webhook must be registered and validated. Please review and complete the steps in the documentation for Webhooks.
Receive Job Status Change Notification
Registered webhook URLs will receive notifications from LinkedIn for job status change events. This request will contain the developerApplicationUrn associated to the customer and the externalJobPostingId of the updated job.
Sample Request
POST https://{webhookUrl}
| Field | Description | Format | Required |
|---|---|---|---|
| externalJobPostingId | Unique job posting id within the partner's system. | string | Yes |
| developerApplicationUrn | Developer Application urn for a child app. | String | Yes |
| type | Type of the callback request, current supported type JOB_POSTING_STATUS. |
Enum | Yes |
| jobPostingInfo | Unique job posting id within the partner's system. | JobPostingInfo | Optional |
| jobPostingUrl | Link to the job posting on LinkedIn. Will only be present if job is listed on LinkedIn. | string | Optional |
| linkedInApplyStatus | LinkedIn Apply status of the job posting. Will be one of ENABLED, NOT_ENABLED, IN_PROGRESS. |
enum | Optional |
| linkedInApplyStatusDetail | JobPostingStatusDetail | Optional | |
| listingStatus | Listing state of the job posting. Will be one of LISTED, NOT_LISTED. |
enum | Yes |
| listingStatusDetail | Error description for the job, if not listed successfully. | JobPostingStatusDetail | Optional |
| promotionStatus | Promoted status of the job listing. Will be one of PROMOTED, NOT_PROMOTED. |
enum | Optional |
| promotionStatusDetail | Instruction message to manage job promotion. | JobPostingStatusDetail | Optional |
JobPostingInfo Field Schema
| Field | Description | Format | Required |
|---|---|---|---|
| alternateLocations | Alternate locations for the job, which can have multiple locations. This field is used to reflect the locations other than the one set in location field. It's empty if the job only has one location. | String[] | Yes |
| companyDetails | Job company details, contains company name and page url. | CompanyDetails | Optional |
| expireAt | Represents the date the job posting will expire on LinkedIn. Null if the job posting is not listed yet. The date is epoch timestamp in milliseconds (UTC). | Long | Optional |
| listedAt | Represents initial date the job posting was listed on Linkedin. The date is epoch timestamp in milliseconds (UTC). | Long | Yes |
| location | Standardized location for the job listing. | String | Yes |
CompanyDetails Field Schema
| Field | Description | Format | Required |
|---|---|---|---|
| companyName | The name of a company. | string | Yes |
| companyPage | The company page on LinkedIn. | string | Yes |
JobPostingStatusDetail Field Schema
| Field | Description | Format | Required |
|---|---|---|---|
| errorCode | Error code identifier. | int | optional |
| errorType | Error desciption. Will be one of
|
enum | Optional |
| statusMessage | Description of the status. | string | Yes |
ListingStatusDetails Error Codes
| ListedStatus | Error Code | Error Type | Error Message | Description |
|---|---|---|---|---|
| NOT_LISTED | 10XX | CUSTOMER_ERROR | INVALID_LOCATION: The job location cannot be standardized. Please update the location in your ATS according to the API schema location field best practices. | The location cannot be recognized, most likely because it is missing information such as a Country or Postal code. |
| NOT_LISTED | 10XX | CUSTOMER_ERROR | MISSING_LOCATION: The job is missing location data. Please add the location in your ATS to post. | The job is missing a location. |
| NOT_LISTED | 10XX | CUSTOMER_ERROR | BLOCKED_COUNTRY: The job’s location is a country blocked by LinkedIn to comply with US government sanctions. Please refer to LinkedIn Help to ensure the job location is not in a sanctioned country. | The job location cannot be in a country sanctioned by the US. |
| NOT_LISTED | 10XX | CUSTOMER_ERROR | MEMBER_REPORTED: The job was closed because it was reported by multiple LinkedIn members as no longer accepting applications. Please ensure the job was not incorrectly closed in your ATS. | LinkedIn auto-closes jobs that have been reported multiple times by jobseekers as no longer accepting applicants. |
| NOT_LISTED | 10XX | CUSTOMER_ERROR | CUSTOMER_EXCLUDED: The job was deliberately not posted due to a customer-requested rule. Please reach out to LinkedIn Support to modify or remove the rule. | Customers may exclude certain jobs from being posted by requesting rules through LinkedIn Support. |
| NOT_LISTED | 10XX | PARTNER_ERROR | PENDING_CUSTOMER_MIGRATION:This job is not yet eligible to be posted automatically via the API. LinkedIn Support has been notified to ensure customer’s readiness to migrate to real time API posting within 1-2 weeks. |
LinkedinApplyStatus Error Codes
| linkedInApplyStatus | Error Code | Error Type | Error Message | Description | Resolution |
|---|---|---|---|---|---|
| IN_PROGRESS | 1156 | CUSTOMER_ERROR | IN_PROGRESS: LinkedIn Apply is being processed. Please check back in 5 minutes. | LinkedIn Apply enablement has been requested and is being processed by the system. | No action needed. |
| NOT_ENABLED | 1100 | PARTNER_ERROR | ENABLING_APPLY_CONNECT_BY_PARTNER_FAILED: Required one non-null optional field in /questionDetails | questionDetails in SimpleTalentQuestionDefinition should have exactly one field. For example, if dateQuestionDetails is present then other fields should not be present. | Address error and update job. |
| NOT_ENABLED | 1101 | PARTNER_ERROR | ENABLING_APPLY_CONNECT_BY_PARTNER_FAILED: PrerequisiteQuestion cannot depend on the response of another PrerequisiteQuestion | Prerequisite question in prerequisiteQuestionResponse can not be a dependent question. For example, with two questions, Q1 and Q2, if Q2 has Q1 as its prerequisiteQuestionResponse then Q1 should have a null prerequisiteQuestionResponse | Address error and update job. |
| NOT_ENABLED | 1102 | PARTNER_ERROR | ENABLING_APPLY_CONNECT_BY_PARTNER_FAILED: PrerequisiteQuestion must be present within the same customQuestions set/array | Prerequisite question in prerequisiteQuestionResponse should be defined within the same customQuestions array | Address error and update job. |
| NOT_ENABLED | 1103 | PARTNER_ERROR | ENABLING_APPLY_CONNECT_BY_PARTNER_FAILED: Repeatable questions cannot have PrerequisiteQuestion | If any of the question types in SimpleTalentQuestions has repeatLimit > 1 then all of the questions in it must have a null prerequisiteQuestionResponse | Address error and update job. |
| NOT_ENABLED | 1150 | PARTNER_ERROR | ENABLING_APPLY_CONNECT_BY_PARTNER_FAILED: LinkedIn Apply update failed | This error occurs due to some issue on LinkedIn and no action is required from the customer side. | No action required. LinkedIn will retry processing. |
| NOT_ENABLED | 1151 | PARTNER_ERROR | ENABLING_APPLY_CONNECT_BY_PARTNER_FAILED: Unable to process questions | This error occurs due to issues with question transformation/validation or due to duplicate question identifiers. | Partners are advised to re-validate the question payload and format. |
| NOT_ENABLED | 1153 | PARTNER_ERROR | ENABLING_APPLY_CONNECT_BY_PARTNER_FAILED: Unable to register jobApplicationWebhookUrl |
This error occurs when the job application webhook url is not successfully registered to receive job applications. | Ensure webhook is valid and update job. |
| NOT_ENABLED | 1154 | PARTNER_ERROR | BLOCKED_WEBHOOK: The application delivery webhook wasn’t reachable. Please ensure webhook is reachable and able to accept applications and then resync the job. | Webhook validation failed. Usually means challengeResponse != Hex-encoded(HMACSHA256(challengeCode, clientSecret)). Webhook Validation |
Ensure webhook is valid and update job. |
| NOT_ENABLED | 1155 | PARTNER_ERROR | LOW_APPLICATION_DELIVERY: LinkedIn Apply has been disabled due to application delivery failures. Please verify the webhook url, ensure you are able to process applications successfully for this job and then resync the job. | Linked Apply has been disabled due to application delivery failures. | Please verify the webhook url, ensure you are able to process applications successfully for this job and then resync the job. |
PromotionStatus Error Codes
| PromotionStatus | Error Code | Error Type | Error Message | Description | Resolution |
|---|---|---|---|---|---|
| PROMOTED | 10XX | CUSTOMER_ERROR | LI_CUSTOMER_PROMOTED: Visit Recruiter to manage. | The LinkedIn customer’s job was promoted successfully through their LinkedIn Recruiter contract. | No action required from partner or customer in the ATS. |
| NOT_PROMOTED | 10XX | CUSTOMER_ERROR | LI_CUSTOMER_BASIC: Promote your job in Recruiter or ask your Job Posting Admin to manage. | The LinkedIn customer’s job was posted as a basic job. | No action required from partner or customer in the ATS. |
| NOT_PROMOTED | 10XX | CUSTOMER_ERROR | ATS_CUSTOMER_BASIC: Reach out to LinkedIn Sales to learn more. | The ATS customer’s job was posted as a basic job since they do not have a LinkedIn contract. | No action required from partner or customer in the ATS. |
Sample Payload
"Content-Type":"application/json",
"X-LI-Signature":"d3756e445a8065c0f38c2182c502f8229800eb2c6a9f3b4a1fdf152af867e6fc",
"Content-Length":"107",
"Connection":"Keep-Alive",
"Accept-Encoding":"gzip,deflate"
{
"developerApplicationUrn": "urn:li:developerApplication:12345",
"externalJobPostingIds": "{external_job_posting_id_1}",
"type": "JOB_POSTING_STATUS",
"listedAt": 1602137400011,
"externalJobPostingId": "{external_job_posting_id_1}",
"location": "Sunnyvale, California",
"listingStatus": "LISTED",
"linkedInApplyStatus": "ENABLED",
"jobPostingUrl": "https://www.linkedin.com/jobs/view/123",
"companyDetails": {
"companyName": "abc",
"companyPage": "https://www.linkedin.com/company/abc"
},
"promotionStatus": "PROMOTED",
"promotionStatusDetail": {
"errorCode": 1012,
"errorType": "CUSTOMER_ERROR",
"errorMessage": "LI_CUSTOMER_PROMOTED: Visit Recruiter to manage."
}
}
Push Event Responses
Upon receiving notifications from LinkedIn, your webhook must respond with an HTTP response. For each notification delivered to your webhook, it must return an HTTP status code to indicate delivery of the notification to your webhook. Valid HTTP response codes listed below.
| HTTP Code | Result | HTTP Payload Response |
|---|---|---|
| 200 | Callback was successfully received | None |
| 400 | Callback was received, but payload was not understood by the ATS | Respond with the field errorMessage. This string field should be the reason the request payload was not understood. Example: {"errorMessage": "Failed to get id from request payload."} |
| 500 | System encountered an error while processing the request | None |
Error Handling
If a push notification request sent to the registered webhook URL receives an unsuccessful response (not 200 OK), then LinkedIn will retry sending the request.