Legacy Static UTM Tracking

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to 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.
  • 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 .

  1. Retrieve an existing share by ID using GET:

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

  2. 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.

  3. 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.

  1. Retrieve an existing share by ID using GET:

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

  2. 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.

  3. 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"
                    }
                }
            }
        }
    }
}

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.

  1. Retrieve an existing share by ID using GET:

    GET https://api.linkedin.com/rest/posts/{encoded ugcPostUrn|shareUrn}

    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"
    }
}

  2. 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, a 400 Bad Request error is returned.

  3. Use the modified contentLandingPage payload and create a PARTIAL 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 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.

  1. Retrieve an existing share by ID using GET:

    GET https://api.linkedin.com/rest/posts/{encoded ugcPostUrn|shareUrn}

    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"
    }
}

  2. 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, the commentary field can also have a URL. If this needs to be updated, locate the commentary field as well.

    Note

    You may only append UTM query parameters to the contentLandingPage or commentary field URL. 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.

  3. Use the modified contentLandingPage and commentary payload and create a PARTIAL 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 under contentLandingPage and commentary 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.

  1. Retrieve an existing share by ID using GET:

    GET https://api.linkedin.com/rest/posts/{encoded ugcPostUrn|shareUrn}

    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"
    }
}

  2. 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_ 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.

  3. Use the modified contentLandingPage payload and create a PARTIAL 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 under contentLandingPage.