DMP Segment List Uploads
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.
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,
companywebsiteandwebsiteare 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,nameshould 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,
firstnameandfnare 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/rest/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.
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