DMP Segment Streaming API Workflow
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 Audiences for Users and Companies can be added to LinkedIn audiences using the streaming APIs /dmpSegments/users
and /dmpSegments/companies
. In this guide, we will provide sample requests to implement each step of this workflow for both user and company DMP Segments.
Permissions
Your application must have an access token with the following permissions to follow this guide.
rw_dmp_segments
rw_ads
only if completing optional Step 6
The rw_dmp_segments
permission belongs to the Audiences program and is not granted automatically as part of the Marketing Developer Platform.
Workflow Overview
A typical Pull workflow consists of the following steps:
- Request LinkedIn to provide a sourcePlatform ENUM that your integration can use
- Create DMP Segment and Destination
- Start adding email addresses or company data to the segment using the streaming APIs
- Monitor for READY status
- Optional: Schedule periodic updates to add or remove data from the segment
- Optional: Add to Campaign
Step 1: Request sourcePlatform ENUM
Before creating DMP Segments, your integration must be assigned a sourcePlatform ENUM value. This value is passed every time your integration creates a DMP Segment to identify the source platform(your integration) the data came from.
If you haven't been provided this already, you must request this from your partner representative.
We will use DMP_PARTNER_PLATFORM
as the sourcePlatform value for this guide. Replace this with your own value in order to follow this guide.
Step 2: Create DMP Segment and Destination
DMP Segments can be created to accept either user or company data depending on whether the type
field is set as USER
or COMPANY
. A single DMP Segment cannot accept both user and company data. Once created, DMP Segments cannot change type.
The sample below also creates a DMP Segment Destination that represents the ad exchange where the audience will be built. The only valid value currently is LINKEDIN
.
A successful response returns a 201 Created HTTP status code and the DMP Segment's ID in the x-linkedin-id
response header.
After successful creation, your integration must wait at least 5 seconds before proceeding to the next step and streaming data.
User DMP Segment
curl -X POST 'https://api.linkedin.com/v2/dmpSegments' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
"name":"User DMP Segment",
"sourcePlatform":"DMP_PARTNER_PLATFORM",
"account":"urn:li:sponsoredAccount:516413367",
"accessPolicy":"PRIVATE",
"type":"USER",
"destinations":[
{
"destination":"LINKEDIN"
}
]
}'
Company DMP Segment
curl -X POST 'https://api.linkedin.com/v2/dmpSegments' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
"name":"Company DMP Segment",
"sourcePlatform":"DMP_PARTNER_PLATFORM",
"account":"urn:li:sponsoredAccount:516413367",
"accessPolicy":"PRIVATE",
"type":"COMPANY",
"destinations":[
{
"destination":"LINKEDIN"
}
]
}'
Step 3: Add data via streaming APIs
Once you've waited 5 seconds after creating a DMP Segment, you can begin streaming data. The following samples use the BATCH CREATE endpoints to add multiple entities. Data can also be added individually. See the full documentation for DMP Segment Users and DMP Segment Companies for those samples.
Adding Users
curl -X POST 'https://api.linkedin.com/v2/dmpSegments/10804/users' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'X-RestLi-Method: BATCH_CREATE' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
"elements": [
{
"action": "ADD",
"userId": {
"idType": "SHA256_EMAIL",
"idValue": "692682111bc191d915ac7009d118a78bc496cf7a2ba8c2d0134ade012ac1234"
}
},
{
"action": "ADD",
"userId": {
"idType": "SHA256_EMAIL",
"idValue": "09d118a78b692682111bc15ac70c496cf7a9e0502ba8c2d016f2f1f7a2ba8c2"
}
}
]
}'
Adding Companies
curl -X POST 'https://api.linkedin.com/v2/dmpSegments/10804/companies' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'X-RestLi-Method: BATCH_CREATE' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
"elements": [
{
"action": "ADD",
"companyName": "LinkedIn"
},
{
"action": "ADD",
"companyName": "Microsoft"
}
]
}'
Step 4: Monitor status
Now you'll need to monitor the status of the DMP Segment Destination to track when it becomes ready to be used in a campaign. At first, the status will be BUILDING
and will move to READY
when it can be added to a campaign. There are several other statuses that can be returned. Refer to the DMP Segment Destination page for that information.
If your integration supports Campaign Management, you should note the adSegment URN returned in the destinationSegmentId
field which will be used in optional Step 6. Otherwise, you can simply notify the user the segment is ready for them to use in targeting through LinkedIn Campaign Manager or any other partner campaign management tool.
curl -X GET 'https://api.linkedin.com/v2/dmpSegments/10804/destinations/LINKEDIN' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}'
Response
{
"audienceSize": 1500,
"created": 1505349172000,
"destination": "LINKEDIN",
"destinationSegmentId": "urn:li:adSegment:10001",
"dmpSegmentId": 10804,
"lastModified": 1506349172000,
"matchedCount": 1400,
"status": "READY"
}
Optional Step 5: Schedule updates
DMP Segments can be updated to add or remove data periodically using the same BATCH CREATE endpoint used in Step 3. This same endpoint is used for removal. A single call can include both additions and removals.
Removing Users
curl -X POST 'https://api.linkedin.com/v2/dmpSegments/10804/users' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'X-RestLi-Method: BATCH_CREATE' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
"elements": [
{
"action": "REMOVE",
"userId": {
"idType": "SHA256_EMAIL",
"idValue": "692682111bc191d915ac7009d118a78bc496cf7a2ba8c2d0134ade012ac1234"
}
},
{
"action": "ADD",
"userId": {
"idType": "SHA256_EMAIL",
"idValue": "342700111bk594d915ac7009d118a22bc496cf7a2ba4j2o0027ade012tc5143"
}
}
]
}'
Removing Companies
curl -X POST 'https://api.linkedin.com/v2/dmpSegments/10804/companies' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'X-RestLi-Method: BATCH_CREATE' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
"elements": [
{
"action": "REMOVE",
"companyName": "LinkedIn"
},
{
"action": "ADD",
"companyName": "GitHub"
}
]
}'
Optional Step 6: Add to Campaign
The goal of any DMP Segment is to be used in a Campaign, but your integration is not required to manage this step if your user uses LinkedIn's Campaign Manager or another partner's platform. If your integration offers both Audience creation and Campaign Management, you should implement this step.
Using the adSegment URN returned in Step 4, you can create a new Campaign or update an existing one including the adSegment in the targetingCriteria
object.
Creating New Campaign
curl -X POST 'https://api.linkedin.com/v2/adCampaignsV2' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
"targetingCriteria": {
"exclude": {
"or": {
"urn:li:adTargetingFacet:locations": [
"urn:li:geo:102095887"
]
}
},
"include": {
"and": [
{
"or": {
"urn:li:adTargetingFacet:locations": [
"urn:li:geo:103644278"
]
}
},
{
"or": {
"urn:li:adTargetingFacet:interfaceLocales": [
"urn:li:locale:en_US"
]
}
},
{
"or": {
"urn:li:adTargetingFacet:segments": [
"urn:li:adSegment:10001"
]
}
}
]
}
},
"account": "urn:li:sponsoredAccount:516413367",
"campaignGroup": "urn:li:sponsoredCampaignGroup:635137195",
"audienceExpansionEnabled": false,
"costType": "CPC",
"creativeSelection": "OPTIMIZED",
"dailyBudget": {
"amount": "18",
"currencyCode": "USD"
},
"locale": {
"country": "US",
"language": "en"
},
"name": "Campaign with Ad Segment",
"offsiteDeliveryEnabled": false,
"runSchedule": {
"end": 9876543210123,
"start": 1234567890987
},
"type": "SPONSORED_UPDATES",
"unitCost": {
"amount": "15",
"currencyCode": "USD"
},
"status": "ACTIVE"
}'
Updating Campaign
curl -X POST 'https://api.linkedin.com/v2/adCampaignsV2/{campaign ID}' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
"patch":{
"$set":{
"targetingCriteria":{
"include":{
"and":[
{
"or":{
"audienceMatchingSegments":[
"urn:li:adSegment:10001"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:locations":[
"urn:li:geo:103644278"
]
}
}
]
}
}
}
}
}'
References
See the following links for additional information on building a Streaming DMP Segment integration.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for