DMP Segment List Uploads
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 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.
Advertisers can upload their first party data as a CSV list of companies or contacts to match with companies or members to create new audience (DMP) segments for targeting specific accounts within LinkedIn advertising campaigns.
DMP Segments act as staging entities, which can take in user information such as SHA256-hashed email addresses or company names from a third-party provider, map them to LinkedIn member profiles or company pages, and output adSegments
, which can then be used with other LinkedIn ads APIs. The list may take up to 48 hours to process.
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 | Endpoints |
---|---|---|
rw_ads | Manage and read an authenticated member's ad accounts data. |
|
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. |
|
Steps
- Create List File
- Upload List File
- Create List Upload DMP Segment
- Attach the Uploaded List to a DMP Segment
- Monitor Status of DMP Segment
- Update Campaign Targeting with a Created adSegment
Create List File
The list file must be in CSV format. It is recommended the file has UTF-8 encoding. See Account and Contact Targeting List Templates to download a sample CSV file.
Account Lists
Supported Header List
Header Name | Header Alias | Description |
---|---|---|
companyname | Company name, for example, Microsoft | |
companydomain | companyemaildomain,emaildomain,domain | Company email domain with a maximum length of 100 characters, for example, microsoft.com |
companywebsite | website | Company website with a maximum length of 100 characters, for example, microsoft.com |
linkedincompanypageurl | Linkedin company page url, for example, www.linkedin.com/company/microsoft | |
stocksymbol | stockticker,ticker | Stock symbol with a maximum length of 5 characters, for example, MSFT |
city | ct | City name with a maximum length of 50 characters, for example, Seattle |
state | st,province,pr | State/Province name with a maximum length of 50 characters for example, Washington |
companycountry | ISO standardized two letter country code, for example, US | |
zipcode | zip,pincode | Zip code with a maximum length of 20 characters, for example, 94103-1234 |
industry | Industry name with a maximum length of 50 characters, for example, Technology | |
industrytwo | Indutry name with a maximumm length of 50 characters, for example, Technology | |
industrythree | Industry name with a maximum length of 50 characters, for example, Technology |
Header requirements
- The header row must be included for proper parsing and it should always be the first now
- You can include header names and header aliases defined in the supported header list above.
- You can provide multiple headers in a header row, and multiple headers must be comma separated
- Duplicate headers are not allowed. Note that different header names of the same type are also considered duplicates, for example,
companywebsite
andwebsite
are duplicate headers because they all refer to a company website. - A header row must contain at least one of the header names:
- companyname
- companydomain
- companywebsite
- linkedincompanypageurl
Content requirements
- Include one instance of data per row.
- If a company name does contain a comma, the whole company name must be enclosed in double quotes. For example,
test,company,name
should be converted to"test,company,name"
in a CSV file. - LinkedIn recommends at least 1,000 companies, with a maximum list size of 300,000.
- The file must be in CSV format.
Sample Data
See the following example to upload an account list. Each list must be a separate CSV file.
Companies
companyname |
---|
Microsoft |
LinkedIn Corp |
"Company,name,test" |
Companies and Company Domains
companyname | companydomain |
---|---|
linkedin.com |
Company Websites
companywebsite |
---|
linkedin.com |
Linkedin Company Page Url
linkedincompanypageurl |
---|
www.linkedin.com/company/microsoft |
Stock Symbol
stocksymbol |
---|
MSFT |
Companies, Location and Industry
companyname | city | state | companycountry | industry |
---|---|---|---|---|
Mountain view | CA | US | Software |
Note
Matched company lists cannot be shared with advertisers.
Contact Lists
Supported Header List
Header Name | Header Alias | Description | Data Format |
---|---|---|---|
Email address | SHA256 hashed | ||
googleaid | Google Android mobile advertiser id | Plain text | |
googleuid | Google user id | Plain text | |
firstname | fn,first | First name with a maximum length of 35 characters, for example, Mike |
Plain text |
lastname | ln,last | Last name with a maximum length of 35 characters, for example, Smith |
Plain text |
employeecompany | Company name with a maximum length of 50 characters, for example, Microsoft |
Plain text | |
title | jobtitle | Job title name with a maximum length of 50 characters, for example, Software Engineer |
Plain text |
country | ISO standardized two letter country code, for example, US |
Plain text |
Header requirements
- Include the header row for proper parsing. The header row should always be the first now
- You can only use header names and header aliases defined in the supported header list above.
- You can provide multiple headers in a header row, and multiple headers must be comma separated.
- Duplicate headers are not allowed. Note that different header names of the same type are also considered duplicates, for example,
firstname
andfn
are duplicate headers because they all refer to a first name. - A header row must contain at least one of the following header names:
- Google Aid
- Google Uid
- First name and Last name
Content requirements
- Include one contact per row.
- LinkedIn recommends at least 10,000 rows with a maximum list size of 300,000.
- A minimum audience count of 300 must be satisfied.
- Must be in CSV format.
Email Hashing Guideline
Email addresses must be SHA256 hashed before you upload the list. If you use Campaign Manager, the UI hashes them for you. For parity in results (match rates) with the API, it is important that you follow these guidelines.
- Convert email addresses to all lowercase
- Remove all whitespaces
- Generate SHA256 hex hash
- abc@test.com should be converted to FA922CB41FF930664D4C9CED3C472CE7ECF29A0F8248B7018456E990177FFF75 (NOT case-sensitive)
Sample Data
See the following example to upload a contact list. Each list must be a separate CSV file.
Email only
7e27ef2718f1aaddb03936077715a60244e380ef09e27504fcb3184a2af7b6ea |
cb39d1f4b7f209e5bb36f71c20aa4c0d0b2ecf7b21d99d5d6cfc4b4c81898b24 |
Multiple IDs
googleaid | |
---|---|
7e27ef2718f1aaddb03936087714a60244e380ef09e27504fcb3184a2af7b6ea | 30F8fc7b-a9ef-4830-a636-1f0deb4f189e |
cb39d1f4b7f209e5bb36f72c60aa4c0d0b2ecf7b21d99d5d6cfc4b4c81898b24 | d0901f0e-7d98-4804-af54-751ff829520a |
People match
firstname | lastname | country | employeecompany | title |
---|---|---|---|---|
mike | smith | US | Engineer | |
mark | wang | US | microsoft | Accountant |
Upload List File
To upload rich media to LinkedIn, you must use the Media Upload API. The files must be in CSV format and should contain either company lists or contact list. The CSV files should be UTF-8 encoded for best results.
POST https://api.linkedin.com/media/upload
Schema
Field Name | Type | Description |
---|---|---|
media_type | string | Value must be ad_segments for this use case |
Sample Request
The following example uses curl to upload company1.csv
.
Note that the curl file upload command may not work with file paths containing “~”, so you may need to cd
to the location of the file first.
curl --form "fileupload=@company1.csv;type=text/csv" -H 'Authorization: Bearer <access token>' https://api.linkedin.com/media/upload?media_type=ad_segments
Sample Response
A successful response will include a body containing a media URN. Save this to be used in the step where the list upload is associated with a DMP segment.
{
"location": "urn:li:media:AgAAAIYBAWwKRuEn90X3AAABVgQvQ_s8LHBFD6JxLRzVNfswdLbLp6wr4qC786kT5XGjM-lKbiGaKYFz_-ltnibEpR3fvjJghc3W3zptQPqUIrVU1MyYxNWgXT20x-PJnrbfp44ATHKX3OmkBnMRqyq13lOBX_lRTzeFHIZE4SgGC_QW6x7yQD_C_QAAAQpcAQAAAVYEL0P7ALZgJEteCioOnhzaQ14NlbHQqKDmP50zUalsye5sUJs38xQC3bsQArS-f0JytYHaVQaNUNW2vO7OcqL3d6YS9C_HVepoHlP-axBl1KX_atcdD4dA6Oxn93n2Ymu52hxbdYo5fphIE6Ap5_Dm21X-wmeM9Nw0A4JrGn_lerqBG_UqxpRUazxsJG2UrjEUj-HOusQyAzh-F8GZdlD8OsQcWLIZ3r7RpODnVWvRtKtjie_vEE7IKEsh6RLcbVSwEWUITUmAev1NGlwxKOL-ZhWPulofwKfqKIMXXqrNX8LewndmdQJZVDufxrYlnu94sJIIwBUrKzgG-1m5FrCOvjxR4wAB"
}
Create List Upload DMP Segment
In order to accept media URNs of the uploaded CSV files as input, a DMP Segment has to be created with a specific sourcePlatform
field called LIST_UPLOAD
.
The type
of DMP Segment determines the type of CSV file (company list or SHA256-hashed emails) to be ingested. Use COMPANY_LIST_UPLOAD
for any company lists and USER_LIST_UPLOAD
for email lists.
A LIST_UPLOAD
segment cannot be used to add or remove users dynamically.
Schema
Usecase | sourcePlatform | type |
---|---|---|
Uploading account lists (Company list) | LIST_UPLOAD | COMPANY_LIST_UPLOAD |
Uploading contact lists | LIST_UPLOAD | USER_LIST_UPLOAD |
Sample Request
See create DMP segments for more information.
Note
After you create a DMP segment, you must wait 5 seconds for the segment to be available to attach lists.
Attach List to DMP Segment
Once you have the DMP segment, associate a list upload to the segment. The body of this call should include an inputFile
field containing the media URN returned in the upload response.
Note that a DMP Segment can only have one list upload attached to it.
Sample Request
POST https://api.linkedin.com/rest/dmpSegments/{dmpSegment id}/listUploads
{
"inputFile": "urn:li:media:AgAAAIYBAWwKRuEn90X3AAABVgQvQ_s8LHBFD6JxLRzVNfswdLbLp6wr4qC786kT5XGjM-lKbiGaKYFz_-ltnibEpR3fvjJghc3W3zptQPqUIrVU1MyYxNWgXT20x-PJnrbfp44ATHKX3OmkBnMRqyq13lOBX_lRTzeFHIZE4SgGC_QW6x7yQD_C_QAAAQpcAQAAAVYEL0P7ALZgJEteCioOnhzaQ14NlbHQqKDmP50zUalsye5sUJs38xQC3bsQArS-f0JytYHaVQaNUNW2vO7OcqL3d6YS9C_HVepoHlP-axBl1KX_atcdD4dA6Oxn93n2Ymu52hxbdYo5fphIE6Ap5_Dm21X-wmeM9Nw0A4JrGn_lerqBG_UqxpRUazxsJG2UrjEUj-HOusQyAzh-F8GZdlD8OsQcWLIZ3r7RpODnVWvRtKtjie_vEE7IKEsh6RLcbVSwEWUITUmAev1NGlwxKOL-ZhWPulofwKfqKIMXXqrNX8LewndmdQJZVDufxrYlnu94sJIIwBUrKzgG-1m5FrCOvjxR4wAB"
}
POST https://api.linkedin.com/v2/dmpSegments/{dmpSegment id}/listUploads
{
"inputFile": "urn:li:media:AgAAAIYBAWwKRuEn90X3AAABVgQvQ_s8LHBFD6JxLRzVNfswdLbLp6wr4qC786kT5XGjM-lKbiGaKYFz_-ltnibEpR3fvjJghc3W3zptQPqUIrVU1MyYxNWgXT20x-PJnrbfp44ATHKX3OmkBnMRqyq13lOBX_lRTzeFHIZE4SgGC_QW6x7yQD_C_QAAAQpcAQAAAVYEL0P7ALZgJEteCioOnhzaQ14NlbHQqKDmP50zUalsye5sUJs38xQC3bsQArS-f0JytYHaVQaNUNW2vO7OcqL3d6YS9C_HVepoHlP-axBl1KX_atcdD4dA6Oxn93n2Ymu52hxbdYo5fphIE6Ap5_Dm21X-wmeM9Nw0A4JrGn_lerqBG_UqxpRUazxsJG2UrjEUj-HOusQyAzh-F8GZdlD8OsQcWLIZ3r7RpODnVWvRtKtjie_vEE7IKEsh6RLcbVSwEWUITUmAev1NGlwxKOL-ZhWPulofwKfqKIMXXqrNX8LewndmdQJZVDufxrYlnu94sJIIwBUrKzgG-1m5FrCOvjxR4wAB"
}
A successful response returns a 201 Created
HTTP status code, the created list upload ID in the x-linkedin-id
response header, and the complete path in the Location
header.
Monitor Status of DMP Segment
It takes up to 48 hours for a DMP segment to move from PROCESSING to READY state. Use GET /dmpSegments
to check its status. When the DMP Segment status is READY
, the destinationSegmentId
under destinations
contains the target adSegment
URN.
Sample Request
Sample Response
{
"accessPolicy": "PRIVATE",
"account": "urn:li:sponsoredAccount:518513895",
"created": 1536351127000,
"destinations": [
{
"audienceSize": 5900,
"created": 1536351127000,
"destination": "LINKEDIN",
"destinationSegmentId": "urn:li:adSegment:164005",
"lastModified": 1536976381000,
"matchedCount": 5800,
"status": "READY"
}
],
"id": 22685,
"inputCount": 6095,
"lastModified": 1536976381000,
"name": "DMP segment for CSV uploads",
"sourcePlatform": "LIST_UPLOAD",
"type": "COMPANY_LIST_UPLOAD"
}
Update Campaign Targeting with a Created adSegment
When a DMP segment is in READY
state, the adSegment
URN is available for targeting. The advertiser can now use the segment in addition to other targeting criteria to run their campaign.
The following request updates an existing campaign with the new ad segment.
POST https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns/{campaign ID}
{
"patch":{
"$set":{
"targetingCriteria":{
"include":{
"and":[
{
"or":{
"urn:li:adTargetingFacet:audienceMatchingSegments":[
"urn:li:adSegment:30000"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:locations":[
"urn:li:geo:103644278"
]
}
}
]
}
}
}
}
}
POST https://api.linkedin.com/v2/adCampaignsV2/{campaign ID}
{
"patch":{
"$set":{
"targetingCriteria":{
"include":{
"and":[
{
"or":{
"urn:li:adTargetingFacet:audienceMatchingSegments":[
"urn:li:adSegment:30000"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:locations":[
"urn:li:geo:103644278"
]
}
}
]
}
}
}
}
}
Get DMP Segment's List Upload
Get list uploads associated with a DMP Segment. Note that only one list upload will be returned even though the response returns an array.
Sample Request
Sample Response
{
"elements": [
{
"created": 1535418156000,
"dmpSegmentId": 55484,
"id": 52105,
"inputFile": "urn:li:media:<REDACTED>",
"lastModified": 1535418156000
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
You can also get a specific list upload by ID.
Sample Request
Sample Response
{
"created": 1535417362000,
"dmpSegmentId": 55484,
"id": 52095,
"inputFile": "urn:li:media:<REDACTED>",
"lastModified": 1535417362000
}
Delete a List From a DMP Segment
Delete a list upload from a DMP Segment, identified by its unique ID.
A successful response returns a 204 No Content
HTTP status code.