Dynamic 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 track the success of marketing efforts in driving traffic to a web page.

This feature provides a way to add dynamic tracking parameters to the landing page URLs of ad creatives.

Note

  • Tracking parameters can be set on the Campaign level.
  • Tracking parameters set on Campaign will affect the landing page URLs of ad creatives under that Campaign.
  • Existing tracking parameters of a Campaign will be applied to all new creatives created under it.
  • An update to the tracking parameters of a Campaign with running ads will have the updated tracking parameters applied to all creatives under the Campaign.
  • A Creative can be tracked across multiple campaigns if dynamic tracking parameters are configured on these campaigns.
  • If static UTM Tracking was configured on the creative, for example utm_abc=123 and dynamic UTM parameters were configured at the CAMPAIGN level as campaign=CAMPAIGN_ID, then the effective served URL will have the assignment: utm_abc=123&campaign=1234567. You must ensure uniqueness of the dynamic UTM parameters, and if a static UTM key was already present using the UTM Parameters (legacy) api, you should change from the UGC Posts and Shares API. Additionally, remove that static assignment to avoid multiple duplicate UTM parameters in the URL.
  • The ad will not require review again.
  • Existing shortened URLs will be appended with dynamic tracking parameters before the ad is rendered. If the shortened URL has existing static UTM parameters, those will be appended with dynamic tracking parameters too.
  • The following creative formats are currently unsupported:
    • Conversation Ads
    • Lead Generation Form Ads
    • Message Ads

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
    		•

    See Account Access Controls for more information on ad account roles.

    Create Tracking Parameters For a Campaign

    Note

    • X-Restli-Protocol-Version: 2.0.0 must be passed as the header in your API requests.
    • LinkedIn-Version: {yyyymm} must be passed as the header in your API requests as this API is released with Versioning.

    Creating Tracking parameters on an existing Campaign can be done by calling the /adTrackingParameters API as below:

    • Two types of tracking parameters can be set: dynamicTrackingParameters and customTrackingParameters.
    • dynamicTrackingParameters are of the format: any_string_key -> AdDynamicTrackingParameterValue. The value of dynamicTrackingParameters needs to be of type AdDynamicTrackingParameterValue. These values are resolved and the actual values will be substituted before appending the parameters to the landing page URL.
    • customTrackingParameters are of the format: any_string_key -> any_string_value. These parameters are appended as it is to the landing page URL.
    • AdDynamicTrackingParameterValue currently supports the following enum:
      • ACCOUNT_ID
      • ACCOUNT_NAME
      • CAMPAIGN_GROUP_ID
      • CAMPAIGN_GROUP_NAME
      • CAMPAIGN_ID
      • CAMPAIGN_NAME
      • CREATIVE_ID
    PUT https://api.linkedin.com/rest/adTrackingParameters/(adEntity:(sponsoredCampaign:{sponsoredCampaignURN}))

    {
    "dynamicValueParameters": {
        "accountId":"ACCOUNT_ID", 
        "campaign_name": "CAMPAIGN_NAME", 
        "cg_id": "CAMPAIGN_GROUP_ID"
    },
    "customValueParameters": {
        "any_custom":"any_value", 
        "source":"LinkedIn"
    }
}

    A successful request returns 201 CREATED. If sponsoredCampaignUrn is malformed, then a error 400 Bad Request status code is returned.

    Sample Request

    PUT https://api.linkedin.com/rest/adTrackingParameters/(adEntity:(sponsoredCampaign:urn%3Ali%3AsponsoredCampaign%3A12345))

    {
    "dynamicValueParameters": {
        "utm_campaign": "CAMPAIGN_NAME", 
        "utm_campaign_id": "CAMPAIGN_ID",
        "utm_campaign_group_id": "CAMPAIGN_GROUP_ID",
        "utm_creative_id": "CREATIVE_ID"
    },
    "customValueParameters": {
        "utm_source":"linkedin",
        "utm_medium":"social"
    }
}

    Get Tracking Parameters of a Campaign

    To retrieve existing tracking parameters of a campaign:

    GET https://api.linkedin.com/rest/adTrackingParameters/(adEntity:(sponsoredCampaign:{sponsoredCampaignURN}))

    Sample Response

    { 
    "dynamicValueParameters": { 
        "campaign_name": "CAMPAIGN_NAME", 
        "cg_id": "CAMPAIGN_GROUP_ID", 
        "account_id": "ACCOUNT_ID" 
    }, 
    "idempotencyToken": "1653526665978", 
    "changeTimeStamps": { 
        "created": 1653526665978, 
        "lastModified": 1653526665978 
    }, 
    "customValueParameters": { 
        "any_custom": "value_1", 
        "source": "LinkedIn"
    }, 
    "adEntity": { 
        "sponsoredCampaign": "urn:li:sponsoredCampaign:366948955"
    }
}

    Update Tracking Parameters For a Campaign

    You can update the Tracking parameters on a Campaign with existing parameters by performing the following steps:

    1. Retrieve an existing tracking parameters by Campaign URN.
    GET https://api.linkedin.com/rest/adTrackingParameters/(adEntity:(sponsoredCampaign:{sponsoredCampaignURN}))

    Sample Response

    { 
    "dynamicValueParameters": { 
        "campaign_name": "CAMPAIGN_NAME", 
        "cg_id": "CAMPAIGN_GROUP_ID", 
        "account_id": "ACCOUNT_ID" 
    }, 
    "idempotencyToken": "1653526665978", 
    "changeTimeStamps": { 
        "created": 1653526665978, 
        "lastModified": 1653526665978 
    }, 
    "customValueParameters": { 
        "any_custom": "value_1", 
        "source": "LinkedIn"
    }, 
    "adEntity": { 
        "sponsoredCampaign": "urn:li:sponsoredCampaign:366948955"
    }
}
    1. Extract idempotencyToken from the response. This must be passed in a query parameter for update.
    2. Use the new parameter mapping to be set on the Campaign and call the Update API as below.

    Note

    A successful request returns 200 OK. If the idempotencyToken does not match, a 409 CONFLICT error is returned. This means the tracking parameter mapping has been updated after your GET call. Perform the GET operation again and use the new idempotencyToken.

    PUT https://api.linkedin.com/rest/adTrackingParameters/(adEntity:(sponsoredCampaign:{sponsoredCampaignURN}))?idempotencyToken=1653526665978

    {
    "dynamicValueParameters": {
        "accountId":"ACCOUNT_ID", 
        "cg": "CAMPAIGN_ID", 
        "cg_id": "CAMPAIGN_GROUP_ID"
    },
    "customValueParameters": {
        "any_custom_new":"any_value_new"
    }
}

    Delete Tracking Parameters of a Campaign

    To delete existing tracking parameters of a campaign:

    DELETE https://api.linkedin.com/rest/adTrackingParameters/(adEntity:(sponsoredCampaign:{sponsoredCampaignURN}))

    Sample Response

    A successful request returns 204 NO CONTENT.