Website Visitors Retargeting

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

The LinkedIn Ads platform offers advertisers the ability to retarget visitors of their website with ad content on LinkedIn. By adding the LinkedIn Insight Tag to their website, advertisers can match website visitors to members on LinkedIn to enable further engagement. Advertisers can also use website retargeting with LinkedIn demographic segments for more refined targeting.

A retargeting segment is a private user segment that is populated using tracking data sent from an advertiser’s website. A segment must have a minimum audience count of 300 before it can be used in a campaign. Unless this requirement is met, campaigns using the segment will not start serving right away.

For more information on campaign targeting options, see Ads Targeting, and for information on using retargeting in Campaign Manager, see Website Retargeting.

The use of this API is restricted to those developers approved by LinkedIn and subject to applicable data restrictions in their agreements.

Permissions

Permission Description
rw_ads Manage and read an authenticated member's ad accounts data.
rw_dmp_segments Access an authenticated member's DMP Segments. Can manage and read audience DMP segments. This permission belongs to the Audiences program and is not granted automatically as part of the LinkedIn Marketing API Program.

Conversion Tracking

The advertiser you are working with must have deployed a working and live Insight Tag on their website. For more information, see Conversion Tracking.

Segment State Transition

Website retargeting segments follow the same state transitions as DMP segments however, they will never be expired.

Steps

  1. Create Ad Page Set
  2. Create Ad Segment
  3. Update Ad Segment Source
  4. Apply Targeting to Campaign

Create Ad Page Set

Create an ad page set using the adPageSets API. A page set is a set of pages on the advertiser's website that are configured to be tracked. Every page set is owned by a Sponsored Account (advertiser). LinkedIn members who visit a page in a page set can be added to a retargeting segment.

POST https://api.linkedin.com/rest/adPageSets

{
    "account": "urn:li:sponsoredAccount:$accountId",
    "matchRules": [
        {
            "matchType": "EXACT",
            "matchValue": "foo.com"
        }
    ],
    "name": "TestPageSet"
}

POST https://api.linkedin.com/v2/adPageSets

{
    "account": "urn:li:sponsoredAccount:$accountId",
    "matchRules": [
        {
            "matchType": "EXACT",
            "matchValue": "foo.com"
        }
    ],
    "name": "TestPageSet"
}

A successful response returns a 201 Created HTTP status code and the page set ID in the x-linkedin-id response header.

Create Ad Segment

Create an empty ad segment for the page set using the adSegmentsV2 API. You will add entities to be retargeted, such as members or companies, to the segment after this step.

POST https://api.linkedin.com/rest/adSegments

{
    "account": "urn:li:sponsoredAccount:511910281",
    "description": "description for retargeting AdSegment",
    "name": "name for retargeting AdSegment",
    "status": "READY",
    "type": "RETARGETING"
}

POST https://api.linkedin.com/v2/adSegmentsV2

{
    "account": "urn:li:sponsoredAccount:511910281",
    "description": "description for retargeting AdSegment",
    "name": "name for retargeting AdSegment",
    "status": "READY",
    "type": "RETARGETING"
}

A successful response returns a 201 Created HTTP status code and the ad segment ID in the x-linkedin-id response header.

Update Ad Segment Source

Create an association between the new page set and the new segment using the adSegmentSources API. The API stores associations between an ad page set URN, a segment URN, and a sponsored account URN. This association determines which segment a user should be associated with based on existing page set criteria.

PUT https://api.linkedin.com/rest/adSegmentSources/source=urn:li:adPageSet:{id}&segment=urn:li:adSegment:{id}

{
    "account": "urn:li:sponsoredAccount:511910281",
    "segment": "urn:li:adSegment:10001",
    "source": "urn:li:adPageSet:10001"
}

PUT https://api.linkedin.com/v2/adSegmentSources/source=urn:li:adPageSet:{id}&segment=urn:li:adSegment:{id}

{
    "account": "urn:li:sponsoredAccount:511910281",
    "segment": "urn:li:adSegment:10001",
    "source": "urn:li:adPageSet:10001"
}

A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header.

Apply Targeting to Campaign

Add the segment to a campaign using the adCampaignsV2 API. The segment ID can be used with other targeting criteria to run a campaign. The campaign is created, but not served until the segment is in READY status and has a minimum audience count of 300.

Targeting facets must have locations and interfaceLocales defined.

POST https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns/{campaign ID}

{
 "patch": {
  "$set": {
   "targetingCriteria": {
    "include": {
     "and": [
      {
       "or": {
        "urn:li:adTargetingFacet:dynamicSegments": [
         "urn:li:adSegment:208133"
        ]
       }
      },
      {
       "or": {
        "urn:li:adTargetingFacet:locations": [
         "urn:li:geo:103644278"
        ]
       }
      },
      {
       "or": {
        "urn:li:adTargetingFacet:interfaceLocales": [
         "urn:li:locale:en_US"
        ]
       }
      }
     ]
    }
   }
  }
 }
}

POST https://api.linkedin.com/rest/adCampaigns/{campaign ID}

{
 "patch": {
  "$set": {
   "targetingCriteria": {
    "include": {
     "and": [
      {
       "or": {
        "urn:li:adTargetingFacet:dynamicSegments": [
         "urn:li:adSegment:208133"
        ]
       }
      },
      {
       "or": {
        "urn:li:adTargetingFacet:locations": [
         "urn:li:geo:103644278"
        ]
       }
      },
      {
       "or": {
        "urn:li:adTargetingFacet:interfaceLocales": [
         "urn:li:locale:en_US"
        ]
       }
      }
     ]
    }
   }
  }
 }
}

POST https://api.linkedin.com/v2/adCampaignsV2/{campaign ID}

{
 "patch": {
  "$set": {
   "targetingCriteria": {
    "include": {
     "and": [
      {
       "or": {
        "urn:li:adTargetingFacet:dynamicSegments": [
         "urn:li:adSegment:208133"
        ]
       }
      },
      {
       "or": {
        "urn:li:adTargetingFacet:locations": [
         "urn:li:geo:103644278"
        ]
       }
      },
      {
       "or": {
        "urn:li:adTargetingFacet:interfaceLocales": [
         "urn:li:locale:en_US"
        ]
       }
      }
     ]
    }
   }
  }
 }
}

For more information, see Ads Targeting.

Delete a Segment Source

Remove an existing association between an ad page set and a segment.

DELETE https://api.linkedin.com/rest/adSegmentSources/source=urn:li:adPageSet:{id}&segment=urn:li:adSegment:{id}

DELETE https://api.linkedin.com/v2/adSegmentSources/source=urn:li:adPageSet:{id}&segment=urn:li:adSegment:{id}