Sync Candidate Notes

Candidate notes should be sent via the Middleware Platform whenever they are created or updated in your ATS. Use both your candidate identifier and note identifier when syncing candidate notes via API.

Note

The latest API version is 202603. Use this version in the LinkedIn-Version header for all API requests to access the most recent features and improvements.

Throttle Limits

Endpoint	Requests Per Day (UTC)	Records Per Minute
rest/candidateNote	1,000,000	N/A

Note

Please submit batch calls grouped with no more than 100 records in sequential order.

Create and Update Candidate Notes

Use the following endpoint to create and update candidate notes:

PUT https://api.linkedin.com/rest/candidateNotes

Include the LinkedIn-Version header when calling this endpoint.

API Request Parameter

Parameter	Description	Format	Required
integrationContext	The integration context specifies who owns the note and identifies the customer who owns the data. The value must be in the format urn:li:organization.	String	Yes
externalCandidateId	The unique identifier of the candidate to which the note belongs within the partner system.	String	Yes
externalNoteId	The unique identifier of the note within the partner system.	String	Yes

Request Body Fields

Field	Description	Format	Required
author	The person who wrote the note.	Actor	No
note	A note about the application.	String	Yes
externalCreatedAt	The time when the note was created in the partner system, represented as an epoch timestamp in milliseconds (UTC). The value must be positive and cannot be a future time.	Epoch in Milliseconds (UTC)	Yes
externalLastModifiedAt	The time when the note was last modified in the partner system, represented as an epoch timestamp in milliseconds (UTC). The value must be positive and cannot be a future time.	Epoch in Milliseconds (UTC)	Yes

Actor Schema

Field	Description	Format	Required
firstName	The first name of the actor.	String	Required
lastName	The last name of the actor.	String	Required

Sample Request (with query tunneling)

curl --location --request POST 'https://api.linkedin.com/rest/candidateNotes' \
--header 'Content-Type: multipart/mixed; boundary=xyz' \
--header 'x-restli-method: batch_update' \
--header 'LinkedIn-Version: 202603' \
--header 'X-HTTP-Method-Override: PUT' \
--header 'Authorization: Bearer {token}' \
--data '--xyz
Content-Type: application/x-www-form-urlencoded

ids[0].externalCandidateId=candidate_20251219_001&ids[0].integrationContext=urn:li:organization:12345&ids[0].externalNoteId=note_20251219_0002
--xyz
Content-Type: application/json

{
  "entities": {
    "externalCandidateId=candidate_20251219_001&integrationContext=urn:li:organization:12345&externalNoteId=note_20251219_0002": 
    {
            "author": {
                "firstName": "Angela",
                "lastName": "Smith"
            },
            "note": "interview",           
            "externalLastModifiedAt": 1767735901000,
            "externalCreatedAt":1767735901000
    }
  }
}
--xyz--'

Sample Request (without query tunneling)

curl --location --globoff --request PUT 'https://api.linkedin.com/rest/candidateNotes?ids[0].externalCandidateId=candidate_20251219_001&ids[0].integrationContext=urn%3Ali%3Aorganization%3A12345&ids[0].externalNoteId=note_20251219_0002' \
--header 'Content-Type: application/json' \
--header 'x-restli-method: batch_update' \
--header 'LinkedIn-Version: 202603' \
--header 'Authorization: Bearer {token}' \
--data '{
  "entities": {
    "externalCandidateId=candidate_20251219_001&integrationContext=urn:li:organization:12345&externalNoteId=note_20251219_0002": 
     {
            "author": {
                "firstName": "Angela",
                "lastName": "Smith"
            },
            "note": "interview",           
            "externalLastModifiedAt": 1767735718000,
            "externalCreatedAt":1767735718000

    }
  }
}'

Sample Response

{
    "results": {
        "externalCandidateId=candidate_20251219_001&externalNoteId=note_20251219_0002&integrationContext=urn%3Ali%3Aorganization%3A12345": {
            "status": 204
        }
    },
    "errors": {}
}

Delete Candidate Notes

Sample Request (with query tunneling)

curl --location --request POST 'https://api.linkedin.com/rest/candidateNotes' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'LinkedIn-Version: 202603' \
--header 'X-HTTP-Method-Override: DELETE' \
--header 'Authorization: Bearer {token}' \
--data 'ids[0].externalCandidateId=candidate_20251219_001&ids[0].integrationContext=urn%3Ali%3Aorganization%3A12345&ids[0].externalNoteId=note_20251219_0002'

Sample Request (without query tunneling)

curl --location --globoff --request DELETE 'https://api.linkedin.com/rest/candidateNotes?ids[0].externalCandidateId=candidate_20251219_001&ids[0].integrationContext=urn%3Ali%3Aorganization%3A12345&ids[0].externalNoteId=note_20251219_0002' \
--header 'LinkedIn-Version: 202603' \
--header 'Authorization: Bearer {token}' 

Sample Response

{
    "results": {
        "externalCandidateId=candidate_20251219_001&externalNoteId=note_20251219_0002&integrationContext=urn%3Ali%3Aorganization%3A12345": {
            "status": 204
        }
    },
    "errors": {}
}