UTM Tracking

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.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
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.
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER
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.
  • ADMINISTRATOR
  • DIRECT_SPONSORED_CONTENT_POSTER
  • RECRUITING_POSTER/li>
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.
  • ADMINISTRATOR
  • DIRECT_SPONSORED_CONTENT_POSTER

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.

  1. Retrieve an existing share by ID.
GET https://api.linkedin.com/v2/shares/{shareURN}

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
}
  1. Extract contentEntities from the response. The entityLocation attribute contains the URL of the landing page of the share.
  2. Modify this URL by appending UTM codes such as utm_campaign=blogpost and utm_medium=social as query parameters. You may only modify the query parameters of the URL. The added query parameters must begin with utm_. The domain and path cannot be modified.
  3. Use the modified contentEntities request body and create a PARTIAL UPDATE request with the sharesUrl API. All other attributes except entityLocation in the request body for the URL update must be exactly the same as returned by the initial GET shares request. Place the modified contentEntities block within the "patch" > "content" > "$set" block. A successful request returns 204 No Content. If any of the other attributes of contentEntities besides entityLocation are modified, a 400 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 .

The first step is to retrieve an existing share by ID using GET:

GET https://api.linkedin.com/v2/ugcPosts/{share URN}

Sample Response

{
    "author": "urn:li:organization:5515715", 
    "clientApplication": "urn:li:developerApplication:1655634", 
    "contentCertificationRecord": "{\"originCountryCode\":\"us\",\"modifiedAt\":1540237202048,\"spamRestriction\":{\"classifications\":[],\"contentQualityClassifications\":[],\"systemName\":\"MACHINE_SYNC\",\"lowQuality\":false,\"contentClassificationTrackingId\":\"3CD18031B1EC5F40BE7E7FEF6A88E731\",\"contentRelevanceClassifications\":[],\"spam\":false}}", 
    "created": {
        "actor": "urn:li:person:2XjizaJNkO", 
        "time": 1540237201826
    }, 
    "firstPublishedAt": 1540237201826, 
    "id": "urn:li:share:6460223056324415488", 
    "lastModified": {
        "actor": "urn:li:csUser:7", 
        "time": 1540237204214
    }, 
    "lifecycleState": "PUBLISHED", 
    "origin": "API", 
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "media": [
                {
                    "media": "urn:li:content:PNG/IMG/d26269b2f9954159a7e26deb1aceeb58", 
                    "originalUrl": "https://image-store.slidesharecdn.com/d26269b2-f995-4159-a7e2-6deb1aceeb58-large.png", 
                    "status": "READY", 
                    "thumbnails": [
                        {
                            "url": "https://image-store.slidesharecdn.com/d26269b2-f995-4159-a7e2-6deb1aceeb58-large.png"
                        }
                    ], 
                    "title": {
                        "text": "Test Image Share with a link"
                    }
                }
            ], 
            "shareCommentary": {
                "inferredLocale": "en_US", 
                "text": "Test Image with a link https://lnkd.in/fYCTxc8"
            }, 
            "shareFeatures": {
                "hashtags": []
            }, 
            "shareMediaCategory": "IMAGE"
        }
    }, 
    "ugcOrigin": "API", 
    "versionTag": "1", 
    "visibility": {
        "com.linkedin.ugc.SponsoredContentVisibility": "DARK"
    }
}

The next step is to locate the specificContent -> ShareContent -> shareCommentary -> text field. This text 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, a 400 Bad Request error is returned.

The final step is to use the modified text to construct the shareCommentary block and create a PARTIAL 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.

The first step is to retrieve an existing share by ID using GET:

GET https://api.linkedin.com/v2/ugcPosts/{share URN}

Sample Response

{
    "author": "urn:li:organization:5614743", 
    "clientApplication": "urn:li:developerApplication:1655634", 
    "contentCertificationRecord": "{\"originCountryCode\":\"us\",\"modifiedAt\":1539369758380,\"spamRestriction\":{\"classifications\":[],\"contentQualityClassifications\":[],\"systemName\":\"MACHINE_SYNC\",\"lowQuality\":false,\"contentClassificationTrackingId\":\"923E4C049B5F4522473EA9A87C0C16CF\",\"contentRelevanceClassifications\":[],\"spam\":false}}", 
    "created": {
        "actor": "urn:li:person:2XjizaJNkO", 
        "time": 1538512502094
    }, 
    "firstPublishedAt": 1538512502094, 
    "id": "urn:li:share:6452989141541011456", 
    "lastModified": {
        "actor": "urn:li:csUser:2", 
        "time": 1539369758390
    }, 
    "lifecycleState": "PUBLISHED", 
    "origin": "API", 
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "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", 
                    "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 Share created by API !!"
            }, 
            "shareFeatures": {
                "hashtags": []
            }, 
            "shareMediaCategory": "ARTICLE"
        }
    }, 
    "ugcOrigin": "API", 
    "versionTag": "16", 
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

The next step is to locate the specificContent -> ShareContent -> media block. The originalUrl attribute within the media 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 with utm_. The domain, path, and any existing query params cannot be modified. If you modify anything other than the UTM params, a 400 Bad Request error is returned.

The final step is to use the modified media payload and create a PARTIAL 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"
                    }
                }
            }
        }
    }
}

For carousel shares, the primaryLandingPageUrl field contains the URL, which determines the landing page where members will be redirected to if the shareCommentary is clicked on mobile apps. Individual cards could have their own landing page URLs in media.landingPage. Currently, only the UTM params in primaryLandingPageUrl are allowed for update, and the update on primaryLandingPageUrl will NOT be propagated to the landing page URLs of individual cards, which is consistent with the UI behavior.

The first step is to retrieve an existing share by ID using GET:

GET https://api.linkedin.com/v2/ugcPosts/{share URN}

Sample Response

{
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "shareCommentary": {
                "inferredLocale": "en_US",
                "text": "Commentary of carousel."
            },
            "media": [
                {
                    "originalUrl": "https://media.licdn.com/dms/image/C551DAQFklUl5lBpXlA/ssu-carousel-card-shrink_627_1200/0?e=1590706800&v=beta&t=uoQoIae8oxKAzislm1joAK8TPi0yP4IlYJnu0Owj3RM",
                    "media": "urn:li:digitalmediaAsset:C551DAQFklUl5lBpXlA",
                    "title": {
                        "text": "card 1"
                    },
                    "thumbnails": [
                        {
                            "width": 627,
                            "url": "https://media.licdn.com/dms/image/C551DAQFklUl5lBpXlA/ssu-carousel-card-shrink_627_1200/0?e=1590706800&v=beta&t=uoQoIae8oxKAzislm1joAK8TPi0yP4IlYJnu0Owj3RM",
                            "height": 825
                        }
                    ],
                    "status": "READY",
                    "landingPage": {
                        "landingPageUrl": "https://www.linkedin.com"
                    }
                },
                {
                    "originalUrl": "https://media.licdn.com/dms/image/C551DAQH_ZXfKBII03A/ssu-carousel-card-shrink_1080_1080/0?e=1590706800&v=beta&t=WrRTPUuO-WApSG1gtVIroMDWjw7SHi3e-MmcNx39eLk",
                    "media": "urn:li:digitalmediaAsset:C551DAQH_ZXfKBII03A",
                    "title": {
                        "text": "card 2"
                    },
                    "thumbnails": [
                        {
                            "width": 280,
                            "url": "https://media.licdn.com/dms/image/C551DAQH_ZXfKBII03A/ssu-carousel-card-shrink_1080_1080/0?e=1590706800&v=beta&t=WrRTPUuO-WApSG1gtVIroMDWjw7SHi3e-MmcNx39eLk",
                            "height": 280
                        }
                    ],
                    "status": "READY",
                    "landingPage": {
                        "landingPageUrl": "https://www.linkedin.com"
                    }
                }
            ],
            "primaryLandingPageUrl": "https://www.linkedin.com",
            "shareFeatures": {
                "hashtags": []
            },
            "shareMediaCategory": "CAROUSEL"
        }
    },
    "visibility": {
        "com.linkedin.ugc.SponsoredContentVisibility": "DARK"
    },
    "created": {
        "actor": "urn:li:person:M3vTZD4nJg",
        "time": 1589575197844
    },
    "author": "urn:li:organization:5474280",
    "origin": "DESKTOP",
    "versionTag": "21",
    "distribution": {
        "distributedViaFollowFeed": true,
        "externalDistributionChannels": [],
        "feedDistribution": "NONE"
    },
    "contentCertificationRecord": "{\"spamRestriction\":{\"classifications\":[],\"contentQualityClassifications\":[],\"systemName\":\"MACHINE_SYNC\",\"lowQuality\":false,\"contentClassificationTrackingId\":\"272BFB8A19D20BE164247F87E86A13CD\",\"contentRelevanceClassifications\":[],\"spam\":false},\"originCountryCode\":\"us\",\"modifiedAt\":1590617669479}",
    "ugcOrigin": "DESKTOP",
    "id": "urn:li:share:6667161609720385536",
    "firstPublishedAt": 1589575197844,
    "lastModified": {
        "actor": "urn:li:csUser:1",
        "time": 1590617670603
    }
}

The next step is to locate the specificContent -> ShareContent -> primaryLandingPageUrl 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_ or hsa_. 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.

The final step is to use the modified primaryLandingPageUrl payload and create a PARTIAL UPDATE request for /ugcPosts endpoint.

Note how the modified primaryLandingPageUrl 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":{
     "primaryLandingPageUrl":"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 under primaryLandingPageUrl.