Sync Interactions

2024-10-09

Interactions include any means by which a candidate has interacted with a recruiter, a candidate has interacted with a company, or a recruiter has updated a candidate’s profile within the Talent CRM system (e.g., recruiter tags and notes). All of the interactions that fall into these categories should be sent via the Middleware Platform whenever they are created or updated in your CRM system. When a customer activates CRM Connect for the first time, you must sync all of their historical data to LinkedIn to power the integration.

Prerequisites and Requirements

Query Tunneling -- Requests require query tunneling if the request URL is larger than LinkedIn's maximum URL length. See Query Tunneling and Migration Guide - Updated API Request Maximum Length for more details.
Compliance with LinkedIn API Breaking Change Policy
Usage of the Client Credential Flow (2-legged OAuth) for authentication.
Usage of the Versioning request format for endpoints and methods that require it as defined in this document.

Throttle Limits

Throttle Limits	Requests Per Day (UTC)	Records Per Minute
Interactions maximum	100,000	10,000

Note

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

API Endpoint

https://api.linkedin.com/rest/tcrmInteractions

Sync Interactions API Query String Parameters

Parameter	Description	Type	Required
tcrmInteractionId	Interaction identifier within external Talent CRM	String	Required
integrationContext	LinkedIn company URN provided during customer onboarding, e.g. `urn:li:organization:1`	String	Required
dataProvider	Hardcoded, this value is always `PARTNER`	String	Required

Sync Interactions via Batch Update

Perform HTTP PUT on the /tcrmInteractions endpoint to send talent CRM interactions to LinkedIn. Batch requests require the x-restli-method: batch_update header. Multiple records can be sent in a single API request as indicated in the example below.

Sync Interactions API Request Body Fields

Field	Description	Type	Required
tcrmCandidateId	The unique identifier for the candidate associated with this interaction.	string	Required
tcrmPipelineId	The unique identifier for the pipeline associated with this interaction.	string	Optional
accessRestricted	Flag indicating whether the interaction is restricted by ACL. If true, the pipeline is only accessible to a set of Recruiter users specified via ACLs. If false, the interaction is accessible to all Recruiter users. (Default value: `false`)	boolean	Optional
interactionDirection	Indicates the direction of the interaction: whether the recruiter initiated contact with the candidate ("To") or the candidate initiated contact with the recruiter ("From"). Possible values: FROM TO	Enum	Optional
interactionTypeCategory	The type of interaction. Must be one of these interaction type categories: EMAIL INMAIL PHONE ATTENDED_IN_PERSON_EVENT ATTENDED_ONLINE_EVENT EVENT_SIGN_UP ENGAGED_WITH_ADVERTISEMENT ENGAGED_ON_SOCIAL_MEDIA ENGAGED_WITH_COMPANY_WEBSITE SMS	Enum	Optional
interactionTypeDescription	Describes the interaction - this is used to provide a more specific interaction type and description if type enum not included	string	Required
notes	The contents of the interaction, including but not limited to: email message content, recruiter notes, tags, etc.	string	Optional
recruiterEmailAddress	Email address of the recruiter associated with this interaction.	EmailAddress	Optional
recruiterFirstName	First name of the recruiter associated with this interaction.	string	Optional
recruiterLastName	Last name of the recruiter associated with this interaction.	string	Optional
tcrmCreatedAt	Time when this interaction was created within external CRM.	Time	Required

Sample Sync Interactions API Request

curl -i -X PUT 'https://api.linkedin.com/rest/tcrmInteractions?ids%5B0%5D.tcrmInteractionId=tcrmInteractionId123&ids%5B0%5D.integrationContext=urn:li:organization:1234567890&ids%5B0%5D.dataProvider=PARTNER&ids%5B1%5D.tcrmInteractionId=tcrmInteractionId456&ids%5B1%5D.integrationContext=urn:li:organization:1234567890&ids%5B1%5D.dataProvider=PARTNER' \
--header 'x-restli-method: batch_update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--header 'LinkedIn-Version: 202409' \
--data-raw '{
    "entities": {
        "tcrmInteractionId=tcrmInteractionId123&dataProvider=PARTNER&integrationContext=urn:li:organization:1234567890": {
        "tcrmCandidateId":"candidate123",
        "tcrmPipelineId":"pipeline123",
        "accessRestricted":true,
        "interactionDirection":"TO",
        "interactionTypeCategory":"EMAIL",
        "interactionTypeDescription":"Email correspondence",
        "notes":"Notes about email interaction with Karren",
        "recruiterEmailAddress":"karrenlui@example.com",
        "recruiterFirstName":"karren",
        "recruiterLastName":"lui",
        "tcrmCreatedAt":1640995200000
        },
        "tcrmInteractionId=tcrmInteractionId456&dataProvider=PARTNER&integrationContext=urn:li:organization:1234567890": {
        "tcrmCandidateId":"candidate345",
        "tcrmPipelineId":"pipeline345",
        "accessRestricted":true,
        "interactionDirection":"TO",
        "interactionTypeCategory":"INMAIL",
        "interactionTypeDescription":"LinkedIn inMail",
        "notes":"Notes for itneraction with Eileen ",
        "recruiterEmailAddress":"eileenScott@example.com",
        "recruiterFirstName":"eileen",
        "recruiterLastName":"scott",
        "tcrmCreatedAt":1640995200000
        }
    }
}'

Sample API Response

{
    "results": {
        "dataProvider=PARTNER&integrationContext=urn%3Ali%3Aorganization%3A1000&tcrmInteractionId=tcrmInteractionId456": {
            "status": 204
        },
        "dataProvider=PARTNER&integrationContext=urn%3Ali%3Aorganization%3A1000&tcrmInteractionId=tcrmInteractionId123": {
            "status": 204
        }
    },
    "errors": {}
}

Delete Interactions

Perform HTTP DELETE on the /tcrmInteractions endpoint when a customer deletes candidate interaction records.

Sample Delete Interactions Request

curl -i -X DELETE 'https://api.linkedin.com/rest/tcrmInteractions?ids%5B0%5D.tcrmInteractionId=tcrmInteractionId123&ids%5B0%5D.integrationContext=urn:li:organization:1234567890&ids%5B0%5D.dataProvider=PARTNER&ids%5B1%5D.tcrmInteractionId=tcrmInteractionId456&ids%5B1%5D.integrationContext=urn:li:organization:1234567890&ids%5B1%5D.dataProvider=PARTNER' \
-H 'Authorization: Bearer {access_token}' \
-H 'X-RestLi-Protocol-Version:1.0.0' \
-H 'Accept:application/json'\
-H 'LinkedIn-Version: 202409' \

Sample DELETE Interactions Response Body

A successful request will return a 200 OK response code, and you will find the status of each entity in the response body.

{
    "results": {
        "dataProvider=PARTNER&integrationContext=urn%3Ali%3Aorganization%3A1000&tcrmInteractionId=tcrmInteractionId456": {
            "status": 204
        },
        "dataProvider=PARTNER&integrationContext=urn%3Ali%3Aorganization%3A1000&tcrmInteractionId=tcrmInteractionId123": {
            "status": 204
        }
    },
    "errors": {}
}