Retrieve Exported Candidates Overview
LinkedIn allows the ability for customers to export limited LinkedIn profile information from LinkedIn Recruiter into their ATS with a single click. This integration between LinkedIn Recruiter and the partner ATS will improve workflow improvements for our customers. This integration offers an additional feature called InMail Stub Profile sync, which will allow LinkedIn member contact information to be synced to the ATS when shared by the member. With this feature enabled, LinkedIn Members will be prompted to share their contact information when they are InMailed by a recruiter. If the member consents to share, their contact information will be synced to their ATS via an InMail Stub Profile. Learn more here.
Note
The call volume limit for the Recruiter One-Click Export API is 300 per Recruiter seat per month
Before you get started...
Authentication
All API requests should be authorized with a OAuth 2.0 Client Credentials token.
Syncing all jobs
For the Recruiter to associate a candidate with an appropriate job, you must sync all of your customer's jobs with LinkedIn. Learn more about syncing jobs here .
Push Notification Platform
For customer export requests to be in real-time from LinkedIn, LinkedIn will be pushing notifications of export events to our partners. Read more about LinkedIn’s push notification platform.
Retrieving Exported Candidates
Receiving Push Notifications
When an export event occurs within LinkedIn, a push notification will be sent to the registered callback URL for your customer. Each event will have an event-type of “EXPORT_CANDIDATE_PROFILE”.
Retrieving Exported Candidate Information
When the callback URL has received a notification event of “EXPORT_CANDIDATE_PROFILE” type, you should then make an API call to retrieve the limited profile information of the exported candidate.
Included in the response will be the integrationContext field. This field will contain an identifier unique to the customer for which this candidate was exported on behalf of. Since all callback URLs are unique per customer, you should verify that this identifier correlates to the callback URL the request was sent to.
GET https://api.linkedin.com/v2/exportedCandidates?q=request&requestId=123456789
Note
The requestId sent by push notification will expire in 24 hours.
Response Body Fields
Field | Description | Type | Required |
---|---|---|---|
candidate | LinkedIn stub profile of the candidate being exported. | StubProfile | Yes |
notes | Notes entered by the user during one click export. | String | Yes |
externalJobPostingId | Unique id for the job within the applicant tracking system | String | Yes |
integrationContext | The identifier of the customer who the candidate was exported on behalf of. | urn:li:organization:{ID} | Yes |
requestedAt | Time when the candidate was exported | Long (Number of milliseconds since midnight, January 1, 1970 UTC. It must be a positive number) | Yes |
requester | Requester who initiated the request to export the candidate. | Requester | Yes |
Retrieving Closed Candidate Profiles
After an export event occurs on behalf of a particular candidate, that candidate may choose to close their LinkedIn member account. To enable customers to be notified of such action, you should make an API call to retrieve those candidates that have recently closed their LinkedIn member accounts and update your ATS records as necessary.
If a candidate deletes their LinkedIn account, they can reactivate it within 21 days. After 21 days, we purge the deleted accounts and populate that information within the Closed Candidates Endpoint. Our ATS partners must query this endpoint periodically (at least once in 30 days) and notify end customers that they may need to delete the data that appear within this endpoint from their records if they do not have a legal basis to continue processing it.
GET https://api.linkedin.com/v2/atsPurgedExportedCandidates?q=criteria
Query Parameters
Field | Description | Type | Required | Notes |
---|---|---|---|---|
exportType | Represents the feature that exports the candidate to an external Applicant Tracking System (ATS). You should always provide ONE_CLICK_EXPORT . |
Enum | No | |
timeRange.start | Inclusive lower date boundary | Epoch in milliseconds (UTC) | Yes | Find candidates who have closed their profiles on or after a specific date. |
timeRange.end | Inclusive upper date boundary | Epoch in milliseconds (UTC) | Yes | Find candidates who have closed their profiles before a specific date. |
Response Body Fields
Field | Description | Type | Required |
---|---|---|---|
candidate | Candidate that was exported and profile is now closed. | PersonUrn in format urn:li:person:{id} |
Yes |
Sample Request
GET https://api.linkedin.com/v2/atsPurgedExportedCandidates?timeRange.start=1589747047000&timeRange.end=1592425447000&q=criteria
Sample Response
{
"elements": [
{
"candidate": "urn:li:person:a1b2c3d4e5"
},
{
"candidate": "urn:li:person:f6g7h8i9j0"
}
],
"paging": {
"count": 2,
"start": 0,
"links": []
}
}