DMP Segment CSV List Upload 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_segmentsrw_adsonly if completing optional Step 5
The rw_dmp_segments permission belongs to the Audiences program and is not granted automatically as part of the LinkedIn Marketing API Program.
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
- Upload list file
- Monitor for READY status
- 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 lists depending on whether the type field is set as USER_LIST_UPLOAD or COMPANY_LIST_UPLOAD. A single DMP Segment cannot accept both user and company lists. 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 List 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 '{
"accessPolicy": "PRIVATE",
"account": "urn:li:sponsoredAccount:516413367",
"destinations": [
{
"destination": "LINKEDIN"
}
],
"name": "User DMP segment for CSV uploads",
"sourcePlatform": "DMP_PARTNER_PLATFORM",
"type": "USER_LIST_UPLOAD"
}'
Company List 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 '{
"accessPolicy": "PRIVATE",
"account": "urn:li:sponsoredAccount:516413367",
"destinations": [
{
"destination": "LINKEDIN"
}
],
"name": "Company DMP segment for CSV uploads",
"sourcePlatform": "DMP_PARTNER_PLATFORM",
"type": "COMPANY_LIST_UPLOAD"
}'
Step 3: Upload list file
In this step, you'll upload a CSV file containing the list of companies or users that you would like to target. Template list files are available for both user and company lists. See Company and Contact Targeting List Templates for those templates or Create List File for details on creating your own.
The API sample below shows how to upload the list file. Note the media_type param must be set to ad_segments.
curl --form "fileupload=@company1.csv;type=text/csv" \
-H 'Authorization: Bearer <access token>' \
https://api.linkedin.com/media/upload?media_type=ad_segments
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 5. 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: 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
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: https://aka.ms/ContentUserFeedback.
Submit and view feedback for