Share via

Legacy Static UTM Tracking

Warning

Deprecation Notice
The Marketing Version 202406 (Marketing June 2024) has been sunset. We recommend that you migrate to the latest versioned 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 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.