Ad Segments
Warning
Deprecation Notice
The Marketing Version 202308 (Marketing August 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will 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 withrw_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.
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
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
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
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.