DMP Segment Destinations

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

DMP Segment Destinations is a sub-resource of DMP segments and lets you add destinations (ad exchanges) to a DMP Segment.

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

Create DMP Segment Destination

A destination can be defined either while creating the segment or added to an existing segment later.

Schema

Field Name Type Description
destination String The ad exchange or platform where the content of this segment will be on-boarded. Possible values are LINKEDIN.

Sample Request

POST https://api.linkedin.com/rest/dmpSegments/11134/destinations

{
    "destination": "LINKEDIN"
}

POST https://api.linkedin.com/v2/dmpSegments/11134/destinations

{
    "destination": "LINKEDIN"
}

A successful response returns a 201 Created HTTP status code and the type of destination created in the x-linkedin-id header.

Fetch DMP Segment Destination

Fetch status and other metadata about the destination. Note that matchedCount only returns matches for the last seven days. audienceSize should be used for available audience for targeting.

Sample Request

GET https://api.linkedin.com/rest/dmpSegments/11134/destinations/LINKEDIN

GET https://api.linkedin.com/v2/dmpSegments/11134/destinations/LINKEDIN

Sample Response

{
    "created": 1505349172000,
    "destination": "LINKEDIN",
    "destinationSegmentId": "urn:li:adSegment:10001",
    "dmpSegmentId": 11134,
    "lastModified": 1505349172000,
    "status": "BUILDING"
}

Note

It is important to track whether the status field is BUILDING or READY. When the destination status is READY, audienceSize and matchedCount are also returned. Note that for member privacy protection, these metrics are approximate.

AdSegmentStatus

We are planning to launch new Audience segment statuses starting from October 30, 2019. Some of the old segment statuses are deprecated or replaced as described below.

DMP Segment Statuses

Enum Description Status
BUILDING A status representing that this segment is being built by the Audience pipeline and not ready to be used yet. Replacement for PROCESSSING
UPDATING A status representing that a segment is being updated and is being built by the backend again to pick up the updates. New
READY A status representing that all information about this segment is ready and that campaigns using this segment can start to serve. No change
FAILED A status representing that some failure happened during the backend processing of this segment. No change
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. No change
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. New

Changes to existing DMP Segment Statuses

Enum Description Status
PROCESSING A status representing that this segment has various statistics still being calculated and not ready to be used yet. Removed
READY A status representing that all information about this segment is ready and that this segment can now be used for targeting. No change
FAILED A status representing that some failure happened during the backend processing of this segment. Failure specifics can be found in the 'failure' field under DMPDestinationSegmentInfo. No change
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. No change

Schema

Field Name Type Description
audienceSize long The approximate number of output entities that will be sent to this destination.
matchedCount long The approximate number of input entities that were successfully mapped to this destination segment.

The following response is returned when status is READY:

{
    "audienceSize": 1500,
    "created": 1505349172000,
    "destination": "LINKEDIN",
    "destinationSegmentId": "urn:li:adSegment:10001",
    "dmpSegmentId": 11134,
    "lastModified": 1506349172000,
    "matchedCount": 1400,
    "status": "READY"
}

Differences Between Audience Size and Matched Count Fields

It is important to understand the subtle difference between audienceSize and matchedCount values. If any change occurs on the segment, matched count and input count are calculated based on data collected from the past seven days (rolling seven-day window). Audience size is based on all input data.

In addition audience count takes opt-out instances into account whereas match count doesn't. The relationships between matched input and actual audience can be one-to-many in either direction (one source profile can either match to one, many, or no profiles in the destination ad exchange).

For example, in an instance where a segment contains 2,000 user profiles from the source platform, 1,400 profiles were successfully matched to the destination ad-exchange. This value corresponds to matchedCount.

Out of these 1,400 matches, some profiles were matched to more than one profile in the destination, for example, 100, bringing the total audience size to 1,500. It is also possible that some profiles were matched to the same profile in the destination, for example, 200, bringing the total audience size to 1300.

In summary, match count and input count indicate how well matching occurs for the past seven days. The match count does not necessarily have a correlation with the audience size.

Fetch All DMP Segment Destinations

Retrieve information on all destinations configured for a segment.

Sample Request

GET https://api.linkedin.com/rest/dmpSegments/11134/destinations

GET https://api.linkedin.com/v2/dmpSegments/11134/destinations

Sample Response

{
    "elements": [
        {
            "audienceSize": 152,
            "created": 1505349172000,
            "destination": "LINKEDIN",
            "destinationSegmentId": "urn:li:adSegment:10002",
            "dmpSegmentId": 11134,
            "lastModified": 1506349172000,
            "matchedCount": 135,
            "status": "READY"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}