Ad Segments

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

An Ad segment is a collection of entities (such as members or companies) to which ads can be targeted. Ad Segments are created automatically after DMP Segments are matched with LinkedIn members.

Permissions

There are two conditions for successful requests:

  • Scope permission accessibility for:

    • rw_ads (read/write)
    • r_ads (read-only)

  • The authenticated Ad Account user that provides consent has one of the following roles on the Ad Account:

    • ACCOUNT_BILLING_ADMIN
    • ACCOUNT_MANAGER
    • CAMPAIGN_MANAGER
    • CREATIVE_MANAGER
    • VIEWER (read-only, even with rw_ads scope)

For more information on Ad Account roles and permissions:

Supported Methods

Update Ad Segment | Find Ad Segments by Ad Account | Get Ad Segment

Schema

Field Name Type Description
account optional SponsoredAccountUrn URN identifying the advertising account associated with the segment. This field is immutable.
approximateMemberCount optional long Approximate number of members in the segment. Please note that because of member privacy protection mechanisms we have in place, this metric is approximate. (Read only)
changeAuditStamps ChangeAuditStamps Audit change stamps including creator, creation timestamp and last updated timestamp. (Read only)
description optional string The detailed description of the ad segment.
id long The ad segment's ID. (Read only)
name string The display name of the ad segment.
status AdSegmentStatus Status on readiness of use
type AdSegmentType Type of the ad segment.

Note

The audience size of an ad campaign could be very different from the field approximateMemberCount of the segment due to other targeting facets applied. To get audience size of an ad campaign, please use audienceCounts API instead.

DMP Segment State Transition

AdSegmentStatus

Enum Description
BUILDING A status representing that this segment is being built by the Audience pipeline and not ready to be used yet.
UPDATING A status representing that a segment is being updated and is being built by the backend again to pick up the updates.
READY A status representing that all information about this segment is ready and that campaigns using this segment can start to serve.
FAILED A status representing that some failure happened during the backend processing of this segment. For DMPSegments, failure specifics can be found in the 'failure' field under DMPDestinationSegmentInfo.
ARCHIVED A status representing that the segment has not been used in any active campaign for more than 30 days. The segment can still be used in a campaign before it gets expired in 90 days.
EXPIRED A status representing that a segment audience has been purged from our system due to data retention policy. Segments that have not been used in any campaign for 90 days will become expired.

AdSegmentType

Enum Description
BULK A segment defined by advertiser by uploading a file containing companies or members to be targeted. This type of segment can be used in 'audience matching' target facet in ad campaign
RETARGETING A 'retargeting' segment is used to target the visitors to all or part of an advertiser's website. This type of segment is populated based on the rules defined in an adPageSet. It can be used in the 'dynamic' targeting facet of an ad campaign.
MARKET_AUTOMATION Marketing automation segments are created and managed by selected third party vendors.

Get Ad Segment

Fetch an existing ad segment by its ID.

Parameters

Field Name Type Description
id long The ad segment's ID

Sample Request

GET https://api.linkedin.com/rest/adSegments/{id}

GET https://api.linkedin.com/v2/adSegmentsV2/{id}

Sample Response

{
   "created": {
       "actor": "urn:li:unknown:0",
       "time": 1678259032000
   },
   "name": "Bulk AdSegment created by self service, and go through state transitions",
   "description": "description for AdSegment Bulk",
   "versionTag": "108105253952",
   "lastModified": {
       "actor": "urn:li:unknown:0",
       "time": 1678259032000
   },
   "id": 16182906,
   "type": "RETARGETING",
   "account": "urn:li:sponsoredAccount:509090297",
   "status": "READY"
}

Update Ad Segment

Partial update fields such as name on the existing ad segment by its ID.

Parameters

Field Name Type Description
id long The ad segment's ID
name string The display name of the ad segment.
status AdSegmentStatus, default="ACTIVE" Status of the segment.

Sample Request

POST https://api.linkedin.com/rest/adSegments/{id}

{
   "patch": {
       "$set": {
           "name": "Retargeting AdSegment",
           "status": "ARCHIVED"
       }
   }
}

POST https://api.linkedin.com/v2/adSegmentsV2/{id}

{
   "patch": {
       "$set": {
           "name": "Retargeting AdSegment",
           "status": "ARCHIVED"
       }
   }
}

Sample Response

A successful response returns a 204 No Content HTTP status.

Find Ad Segments by Ad Account

Query ad segments by advertiser account:

Parameters

Field Name Type Description
accounts SponsoredAccountUrn[] Filter result by 'accounts' field of the object
statuses optional AdSegmentStatusArrayRecord Filter result by 'status' field of the object
types optional AdSegmentTypeArrayRecord filter result by 'type' field of the object
Field Name Type Description
accounts SponsoredAccountUrn[] Filter result by 'accounts' field of the object
statuses optional AdSegmentStatus[] Filter result by 'status' field of the object
types optional AdSegmentType[] filter result by 'type' field of the object

Sample Request

https://api.linkedin.com/rest/adSegments?q=accounts&accounts=List(urn%3Ali%3AsponsoredAccount%3A{{sponsoredaccount_id}})&start=0&count=5

GET https://api.linkedin.com/v2/adSegmentsV2?q=accounts&accounts=urn:li:sponsoredAccount:511910281&start=0&count=5

Sample Response

{
   "elements": [
       {
           "approximateMemberCount": 230000,
           "created": {
               "actor": "urn:li:unknown:0",
               "time": 1651129031000
           },
           "name": "DMP Segment 1",
           "versionTag": "81433811311",
           "id": 11422166,
           "lastModified": {
               "actor": "urn:li:unknown:0",
               "time": 1654271097000
           },
           "type": "MARKET_AUTOMATION",
           "account": "urn:li:sponsoredAccount:509090297",
           "status": "ARCHIVED"
       },
       {
           "approximateMemberCount": 0,
           "created": {
               "actor": "urn:li:unknown:0",
               "time": 1651486505000
           },
           "name": "DMP segment for CSV uploads",
           "versionTag": "78913777069",
           "id": 11462646,
           "lastModified": {
               "actor": "urn:li:unknown:0",
               "time": 1651972148000
           },
           "type": "BULK",
           "account": "urn:li:sponsoredAccount:509090297",
           "status": "READY"
       },
       {
           "approximateMemberCount": 0,
           "created": {
               "actor": "urn:li:unknown:0",
               "time": 1657199237000
           },
           "name": "Bulk AdSegment created by self service, and go through state transitions",
           "description": "description for AdSegment Bulk",
           "versionTag": "84646462865",
           "id": 12554466,
           "lastModified": {
               "actor": "urn:li:unknown:0",
               "time": 1657238293000
           },
           "type": "RETARGETING",
           "account": "urn:li:sponsoredAccount:509090297",
           "status": "READY"
       }
   ]
}

When start or count parameters are provided in the request, pagination for multiple records returned follows the standard API pagination. When no start or count parameters are provided in the request, all the segments for an account will be returned in the response.