Legacy Static UTM Tracking
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
Seamless tracking across multiple campaigns and platforms is a core part of enabling advertisers to prove ROI. UTM codes are parameters added to the end of a URL to help track the success of marketing efforts at driving traffic to a web page.
This feature provides a way to retroactively add tracking parameters to the URLs of existing shares.
- No other attributes of the share will be modified.
- The ad will not require review again.
- The performance of a campaigns using the share will not be impacted by UTM edits.
Updates are restricted to adding or modifying query parameters beginning with utm_
. The domain, path and all query parameters not beginning with utm_
cannot be modified.
Permissions
Permission | Description |
---|---|
rw_ads | Manage and read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
|
r_ads | Read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
|
w_organization_social | Post, comment and like posts on behalf of an organization. Restricted to organizations in which the authenticated member has one of the following company page roles.
|
r_organization_social | Retrieve organizations' posts, comments, and likes. Restricted to organizations in which the authenticated member has one of the following company page roles.
|
See Account Access Controls for more information on ad account roles.
See Organization Access Control for more information on company page roles.
Updating UTM Params Using Shares API
Note
While you can update UTM params using the Shares API. The sharesUrl
method only works for Article Shares. If you are already using this API, you should consider using the UGC Posts API for UTM tracking (described in next section) as that method works for all types of Shares.
Setting UTM params on an existing Share can be done with the following steps.
- Retrieve an existing share by ID.
Sample Response
{
"activity": "urn:li:activity:6280900289327431680",
"content": {
"contentEntities": [
{
"description": "News, email and search are just the beginning. Discover more every day. Find your yodel.",
"entity": "urn:li:article:8302773461016502828",
"entityLocation": "https://www.yahoo.com",
"thumbnails": [
{
"imageSpecificContent": {
"height": 200,
"size": 5992,
"width": 200
},
"resolvedUrl": "https://s.yimg.com/dh/ap/default/130909/y_200_a.png"
}
],
"title": "Test Share with Content"
}
],
"description": "News, email and search are just the beginning. Discover more every day. Find your yodel.",
"shareMediaCategory": "ARTICLE",
"title": "Test Share with Content"
},
"created": {
"actor": "urn:li:person:pE3vIqqeK6",
"time": 1497483322000
},
// Sample truncated
}
- Extract
contentEntities
from the response. TheentityLocation
attribute contains the URL of the landing page of the share. - Modify this URL by appending UTM codes such as
utm_campaign=blogpost
andutm_medium=social
as query parameters. You may only modify the query parameters of the URL. The added query parameters must begin withutm_
. The domain and path cannot be modified. - Use the modified
contentEntities
request body and create aPARTIAL UPDATE
request with thesharesUrl
API. All other attributes exceptentityLocation
in the request body for the URL update must be exactly the same as returned by the initial GET shares request. Place the modifiedcontentEntities
block within the"patch"
>"content"
>"$set"
block. A successful request returns204 No Content
. If any of the other attributes ofcontentEntities
besidesentityLocation
are modified, a400 Bad Request
status code is returned.
POST https://api.linkedin.com/v2/sharesUrl/{shareURN}
{
"patch": {
"content": {
"$set": {
"contentEntities": [
{
"description": "News, email and search are just the beginning. Discover more every day. Find your yodel.",
"entity": "urn:li:article:8302773461016502828",
"entityLocation": "https://www.yahoo.com?utm_campaign=blogpost&utm_medium=social&utm_source=facebook",
"thumbnails": [
{
"imageSpecificContent": {
"height": 200,
"size": 5992,
"width": 200
},
"resolvedUrl": "https://s.yimg.com/dh/ap/default/130909/y_200_a.png"
}
],
"title": "Test Share with Content !!"
}
]
}
}
}
}
Updating UTM Params Using UGC Posts API
The UGC Posts API provides a PARTIAL UPDATE method where UTM params can be added to the Sponsored Content entities.
You will need the permission w_organization_social
to perform this action. To read an organization's posts before and after modifying UTM params, you should also include the r_organization_social
permission.
The UGC Posts API for UTM tracking works for updating the following types of entities:
The following table lists the type of entities and a list of editable fields (for UTM tracking), which (if edited) will not trigger reviews or affect campaign performance:
Entity Type | Editable Fields (for UTM updates only) |
---|---|
Image Share | specificContent.ShareContent.shareCommentary |
Article Share | specificContent.ShareContent.media specificContent.ShareContent.shareCommentary (if required) |
Carousel Share | specificContent.ShareContent.primaryLandingPageUrl |
Updating Image/Rich Shares
For image/rich shares, the shareCommentary
field contains both the URL as well as the descriptive text entered by the creator. The URL can be a regular link or a short link.
The goal is to only update the URL (or shortlink) with a new URL with UTM params appended, without changing the rest of the text in the shareCommentary
.
Retrieve an existing share by ID using GET:
Locate the
specificContent
->ShareContent
->shareCommentary
->text
field. Thistext
field should then be parsed to look for HTTPS links (URLs). This link should be replaced in-place with a new (full) URL appended with UTM query parameters.If the text contains shortlinks (starting with
https://lnkd.in/
), then the actual long link must be resolved programmatically. The shortlink should be replaced in-place with a new (full) URL assembled using the resolved URL location and the required UTM params.Note
You may only append UTM query parameters to the links. The added query parameters must begin with
utm_
. The domain, path, and any existing query params cannot be modified. If you modify anything other than the UTM params, a400 Bad Request
error is returned.Use the modified
text
to construct theshareCommentary
block and create aPARTIAL UPDATE
request for/ugcPosts
endpoint.Note how the modified
shareCommentary
block is placed within the "patch" -> "specificContent" -> "com.linkedin.ugc.ShareContent" -> "$set" block.POST https://api.linkedin.com/v2/ugcPosts/{shareURN}
{ "patch": { "specificContent": { "com.linkedin.ugc.ShareContent": { "$set": { "shareCommentary": { "inferredLocale": "en_US", "text": "Test Image with a link https://developer.linkedin.com/docs/guide/v2/ads/matched-audiences?utm_1=111&hsa_2=222" } } } } } }
Note
The updated text
contains the new long URL with UTM tracking params which will be auto shorted by the service if required.
Response
Returns 204 No Content
on success. Upon success, a subsequent GET on the share will show the updated URL or newly created shortlink under shareCommentary
-> text
field.
Updating Article Shares
For article shares, the media.originalUrl
field contains the URL. Additionally, the shareCommentary
may also contain the same URL (or its shortlink equivalent).
The goal is to only update the originalUrl
with a new URL with UTM params appended and updating that same URL (or shortlink) in shareCommentary
without changing any other text.
Retrieve an existing share by ID using GET:
Locate the
specificContent
->ShareContent
->media
block. TheoriginalUrl
attribute within themedia
block contains the URL of the landing page of the share. This URL should be modified by appending UTM codes as query parameters.Note
You may only append UTM query parameters to the
originalUrl
. The added query parameters must begin withutm_
. The domain, path, and any existing query params cannot be modified. If you modify anything other than the UTM params, a400 Bad Request
error is returned.Use the modified
media
payload and create aPARTIAL UPDATE
request for/ugcPosts
endpoint.Note how the modified
media
block is placed within the "patch" -> "specificContent" -> "com.linkedin.ugc.ShareContent" -> "$set" block.POST https://api.linkedin.com/v2/ugcPosts/{share URN}
{ "patch": { "specificContent": { "com.linkedin.ugc.ShareContent": { "$set": { "media": [ { "description": { "text": "News, email and search are just the beginning. Discover more every day. Find your yodel." }, "media": "urn:li:article:7128585698325486338", "originalUrl": "https://www.yahoo.com?utm_1=11&hsa_2=22", "status": "READY", "thumbnails": [ { "height": 200, "size": 5992, "url": "https://s.yimg.com/dh/ap/default/130909/y_200_a.png", "width": 200 } ], "title": { "text": "Test Share created by API !!" } } ] } } } } }
Response
Returns 204 No Content
on success. Upon success, a subsequent GET on the share will show the updated URL under originalUrl
.
Updating shareCommentary and originalUrl Together
Article shares may contain the same URL within the text section as well. For such shares, the shareCommentary
block also needs to be updated along with the media
block.
For such shares, specificContent
-> ShareContent
-> shareCommentary
-> text
field should be located and parsed to look for HTTPS links (URLs).
If the text
contains shortlinks (starting with https://lnkd.in/
), then the actual long link must be resolved programmatically.
If either a direct link or a resolved shortlink within shareCommentary
-> text
matches the media
-> originalUrl
that we are already appending with UTM codes, then that link should be replaced in-place with a new (full) URL assembled using the URL location and the UTM codes.
A sample patch
request which updates both media
and shareCommentary
blocks is as follows:
Sample: Updating shareCommentary and Media
POST https://api.linkedin.com/v2/ugcPosts/{share URN}
{
"patch": {
"specificContent": {
"com.linkedin.ugc.ShareContent": {
"$set": {
"media": [
{
"description": {
"text": "News, email and search are just the beginning. Discover more every day. Find your yodel."
},
"media": "urn:li:article:7128585698325486338",
"originalUrl": "https://www.yahoo.com?utm_1=11&hsa_2=22",
"status": "READY",
"thumbnails": [
{
"height": 200,
"size": 5992,
"url": "https://s.yimg.com/dh/ap/default/130909/y_200_a.png",
"width": 200
}
],
"title": {
"text": "Test Share created by API !!"
}
}
],
"shareCommentary": {
"inferredLocale": "en_US",
"text": "Test article share with a link https://www.yahoo.com?utm_1=11&hsa_2=22"
}
}
}
}
}
}
Updating UTM Params Using Posts API
The Posts API provides a PARTIAL UPDATE method where UTM params can be added to the Sponsored Content entities.
You will need the permission w_organization_social
to perform this action. To read an organization's posts before and after modifying UTM params, you should also include the r_organization_social
permission.
The Posts API for UTM tracking works for updating the following types of entities:
The following table lists the type of entities and a list of editable fields (for UTM tracking), which (if edited) will not trigger reviews or affect campaign performance:
Entity Type | Editable Fields (for UTM updates only) |
---|---|
Image Share | contentLandingPage |
Article Share | contentLandingPage commentary (if required) |
Carousel Share | contentLandingPage |
Updating Image/Rich Shares - Posts API
For image/rich shares, the contentLandingPage
field contains the URL. The URL can be a regular link or a short link. The goal is to update the URL with a new URL with UTM params appended.
Retrieve an existing share by ID using GET:
Sample Response
{ "lifecycleState": "PUBLISHED", "lastModifiedAt": 1666206861469, "visibility": "PUBLIC", "publishedAt": 1666202504237, "author": "urn:li:organization:2414183", "contentCallToActionLabel": "LEARN_MORE", "distribution": { "feedDistribution": "NONE", "thirdPartyDistributionChannels": [] }, "content": { "media": { "taggedEntities": [], "id": "urn:li:image:D4E18AQGw3P4mVWBrpg" } }, "lifecycleStateInfo": { "isEditedByAuthor": true }, "contentLandingPage": "http://www.google.com/123", "isReshareDisabledByAuthor": false, "createdAt": 1666202504237, "id": "urn:li:share:6988559827463454720", "commentary": "Introductory text with http://www.linkedin.com", "adContext": { "dscStatus": "ACTIVE", "dscName": "Single Image Ad", "dscAdType": "STANDARD", "isDsc": true, "dscAdAccount": "urn:li:sponsoredAccount:508915158" } }
Locate the
contentLandingPage
field to replace the link in the field in-place with a new (full) URL appended with UTM query parameters.Note
You may only append UTM query parameters to the links. The added query parameters must begin with
utm_
. The domain, path, and any existing query params cannot be modified. If you modify anything other than the UTM params, a400 Bad Request
error is returned.Use the modified
contentLandingPage
payload and create aPARTIAL UPDATE
request for/Posts
endpoint.
Response
Returns 204 No Content
on success. Upon success, a subsequent GET on the share will show the updated URL in the contentLandingPage
field.
Updating Article Shares - Posts API
For article shares, the contentLandingPage
field contains the URL. Additionally, the commentary
may also contain the same URL (or its shortlink equivalent).
The goal is to only update the contentLandingPage
with a new URL with UTM params appended and updating that same URL (or shortlink) in commentary
without changing any other text.
Retrieve an existing share by ID using GET:
Sample Response
{ "lifecycleState": "PUBLISHED", "lastModifiedAt": 1666206861469, "visibility": "PUBLIC", "publishedAt": 1666202504237, "author": "urn:li:organization:2414183", "contentCallToActionLabel": "LEARN_MORE", "distribution": { "feedDistribution": "NONE", "thirdPartyDistributionChannels": [] }, "content": { "article": { "description": "Description of the Ad", "thumbnail": "urn:li:image:D4E18AQGw3P4mVWBrpg", "source": "http://www.google.com/123", "title": "Headline fo the Ad" } }, "lifecycleStateInfo": { "isEditedByAuthor": true }, "contentLandingPage": "http://www.google.com/123", "isReshareDisabledByAuthor": false, "createdAt": 1666202504237, "id": "urn:li:share:6988559827463454720", "commentary": "Introductory text with http://www.linkedin.com", "adContext": { "dscStatus": "ACTIVE", "dscName": "Single Image Ad", "dscAdType": "STANDARD", "isDsc": true, "dscAdAccount": "urn:li:sponsoredAccount:508915158" } }
Locate the
contentLandingPage
field. This contains the URL of the landing page of the share. This URL should be modified by appending UTM codes as query parameters. In addition to this, thecommentary
field can also have a URL. If this needs to be updated, locate thecommentary
field as well.Note
You may only append UTM query parameters to the
contentLandingPage
orcommentary
field URL. The added query parameters must begin withutm_
. The domain, path, and any existing query params cannot be modified. If you modify anything other than the UTM params, a400 Bad Request
error is returned.Use the modified
contentLandingPage
andcommentary
payload and create aPARTIAL UPDATE
request for/Posts
endpoint.POST 'https://api.linkedin.com/rest/posts/{shared ID}/{ugcPosts ID}'
{ "patch": { "$set": { "commentary": ""Introductory text with https://www.linkedin.com?utm_1=11&hsa_2=22&utm_3=33&hsa_4=44", "contentLandingPage": "https://www.linkedin.com?utm_1=11&hsa_2=22&utm_3=33&hsa_4=44" } } }
Response
Returns
204 No Content
on success. Upon success, a subsequent GET on the share will show the updated URL undercontentLandingPage
andcommentary
fields.
Updating Carousel Shares - Posts API
For carousel shares, the contentLandingPage
field contains the URL, which determines the landing page where members will be redirected to if the commentary
is clicked on mobile apps. Individual cards could have their own landing page URLs in content.carousel.cards.landingPage
. Currently, only the UTM params in contentLandingPage
are allowed for update, and the update on contentLandingPage
will NOT be propagated to the landing page URLs of individual cards, which is consistent with the UI behavior.
Retrieve an existing share by ID using GET:
Sample Response
{ "lifecycleState": "PUBLISHED", "lastModifiedAt": 1666173167715, "visibility": "PUBLIC", "publishedAt": 1656026022523, "author": "urn:li:organization:18799005", "distribution": { "feedDistribution": "NONE", "thirdPartyDistributionChannels": [] }, "content": { "carousel": { "cards": [ { "landingPage": "http://www.linkedin.com", "media": { "title": "Linkedin", "id": "urn:li:image:D4E1DAQFP3SqPwiOaZA" } }, { "landingPage": "http://www.linkedin.com", "media": { "title": "Linkedin", "id": "urn:li:image:D4E1DAQHslRn2pVZGSQ" } } ] } }, "lifecycleStateInfo": { "isEditedByAuthor": false }, "contentLandingPage": "http://www.linkedin.com", "isReshareDisabledByAuthor": false, "createdAt": 1656026022523, "id": "urn:li:share:6945876569575854081", "commentary": "Ads Preview", "adContext": { "dscStatus": "ACTIVE", "dscName": "Ads Preview", "dscAdType": "CAROUSEL", "isDsc": true, "dscAdAccount": "urn:li:sponsoredAccount:509639419" } }
Locate the
contentLandingPage
field to get the URL. This URL should be modified by appending UTM codes as query parameters.Note
You may only append UTM query parameters to the links. The added query parameters must begin with
utm_
orhsa_
. The domain, path, and any existing query params should not be modified. If you modify anything other than the UTM params, the ad review will be triggered, and the ads serving for this specific carousel ad could be paused.Use the modified
contentLandingPage
payload and create aPARTIAL UPDATE
request for/Posts
endpoint.POST 'https://api.linkedin.com/rest/posts/{shared ID}/{ugcPosts ID}'
{ "patch": { "$set": { "contentLandingPage": "https://www.linkedin.com?utm_1=11&hsa_2=22&utm_3=33&hsa_4=44" } } }
Response
Returns
204 No Content
upon success. Upon success, a subsequent GET on the share will show the updated URL undercontentLandingPage
.