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.

Try in Postman

Try in Postman

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.
  • adCampaignsV2
  • dmpSegments/listUploads
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.
  • dmpSegments
  • dmpSegments/listUploads

Steps

  1. Create List File
  2. Upload List File
  3. Create List Upload DMP Segment
  4. Attach the Uploaded List to a DMP Segment
  5. Monitor Status of DMP Segment
  6. 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 and website 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 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
LinkedIn 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 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 and fn are duplicate headers because they all refer to a first name.
  • A header row must contain at least one of the following header names:
    • Email
    • 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.

  1. Convert email addresses to all lowercase
  2. Remove all whitespaces
  3. 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
email
7e27ef2718f1aaddb03936077715a60244e380ef09e27504fcb3184a2af7b6ea
cb39d1f4b7f209e5bb36f71c20aa4c0d0b2ecf7b21d99d5d6cfc4b4c81898b24
Multiple IDs
email googleaid
7e27ef2718f1aaddb03936087714a60244e380ef09e27504fcb3184a2af7b6ea 30F8fc7b-a9ef-4830-a636-1f0deb4f189e
cb39d1f4b7f209e5bb36f72c60aa4c0d0b2ecf7b21d99d5d6cfc4b4c81898b24 d0901f0e-7d98-4804-af54-751ff829520a
People match
firstname lastname country employeecompany title
mike smith US linkedin 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

POST https://api.linkedin.com/rest/dmpSegments
{
    "accessPolicy": "PRIVATE",
    "account": "urn:li:sponsoredAccount:506303764",
    "destinations": [
        {
            "destination": "LINKEDIN"
        }
    ],
    "name": "DMP segment for CSV uploads",
    "sourcePlatform": "LIST_UPLOAD",
    "type": "COMPANY_LIST_UPLOAD"
}
POST https://api.linkedin.com/v2/dmpSegments
{
    "accessPolicy": "PRIVATE",
    "account": "urn:li:sponsoredAccount:506303764",
    "destinations": [
        {
            "destination": "LINKEDIN"
        }
    ],
    "name": "DMP segment for CSV uploads",
    "sourcePlatform": "LIST_UPLOAD",
    "type": "COMPANY_LIST_UPLOAD"
}

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

GET https://api.linkedin.com/rest/dmpSegments/22685
GET https://api.linkedin.com/v2/dmpSegments/22685

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

GET https://api.linkedin.com/rest/dmpSegments/{dmpSegment id}/listUploads
GET https://api.linkedin.com/v2/dmpSegments/{dmpSegment id}/listUploads

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

GET https://api.linkedin.com/rest/dmpSegments/{dmpSegment id}/listUploads/{list id}
GET https://api.linkedin.com/v2/dmpSegments/{dmpSegment id}/listUploads/{list id}

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.

DELETE https://api.linkedin.com/v2/dmpSegments/{dmpSegment id}/listUploads/{list id}

A successful response returns a 204 No Content HTTP status code.