Skip to main content
Skip table of contents

LinkedIn API

Overview

This document outlines how you can integrate between Redpoint Data Management (DM) and LinkedIn APIs for creating DMP Segments as well as adding audience files to those segments. This documentation contains instructions for creating a DMP Segment, uploading audience documents, and attaching audience documents to DMP Segments.

Basic requirements

Each task contained in this documentation has the following requirements:

  • A LinkedIn app with the Advertising API product added.

  • A corresponding App ID and Secret.

  • A LinkedIn Campaign Manager Account (the user authenticating with LinkedIn must have one of the following LinkedIn ad account roles: ACCOUNT_BILLING_ADMIN, ACCOUNT_MANAGER, CAMPAIGN_MANAGER, or CREATIVE_MANAGER).

  • An Advertiser ID.

  • LinkedIn API Version.

  • An audience file for upload. Refer to Cloud storage providers and Define file exports for details.

Basic authentication flow

The basic flow for authentication with LinkedIn APIs is as follows:

  1. Create an Ad Account in https://www.linkedin.com/marketing/businessmanager/accounts/.

  2. Add a LinkedIn user to the Ad Account to manage API authentication. The LinkedIn user must be given one of the following roles:

    • ACCOUNT_BILLING_ADMIN

    • ACCOUNT_MANAGER

    • CAMPAIGN_MANAGER

    • CREATIVE_MANAGER

  3. Add the Ad Account to the Advertising API product enabled on the LinkedIn app.

  4. Using the managing LinkedIn user account, generate a long lived access token.

  5. Store the token for API calls, and refresh when necessary.

Create a long lived access token

All requests to the LinkedIn API must include an access token for authentication. The access token is generated via one of two OAuth flows: member authorization code and client credential.

Create a DMP segment

The LinkedIn Advertising API requires an existing DMP Segment when adding an audience list document. DMP Segments can be created either via an online GUI located at https://www.linkedin.com/campaignmanager/accounts or via API.

Create Segment Via API

The DMP Segment creation request must adhere to the guidelines listed at https://learn.microsoft.com/en-us/linkedin/marketing/integrations/matched-audiences/create-and-manage-list-uploads?view=li-lms-2023-09&tabs=curl#create-list-file

  • 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.

Endpoint: https://api.linkedin.com/rest/dmpSegments

Method: POST

Header:

Field

Data Type

Description

Authorization

string

(Required)

Authorized access token. Example: "Bearer ACCESS_TOKEN".

Content-Type

string

(Required)

"application/json".

LinkedIn-Version

string

Version number in the format YYYYMM.

Parameters:

Field

Data Type

Description

accessPolicy

string

(Required)

"PRIVATE".

account

urn

(Required)

Full URN of Ad Account. Example: "urn:li:sponsoredAccount:511602428".

description

string

A description of the segment.

name

string

(Required)

The name of the segment.

destinations

array

The destinations and various metadata that the content of this segment will be onboarded to. Currently, the only accepted value is LINKEDIN.

sourcePlatform

enum

(Required)

LIST_UPLOAD.

type

enum

(Required)

The type of list uploaded:

Either COMPANY_LIST_UPLOAD or USER_LIST_UPLOAD.

Request:

JSON
curl -X POST 'https://api.linkedin.com/rest/dmpSegments' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'LinkedIn-Version: 202304' \
--data '{
    "accessPolicy": "PRIVATE",
    "account": "urn:li:sponsoredAccount:506303764",
    "destinations": [
        {
            "destination": "LINKEDIN"
        }
    ],
    "name": "DMP segment for CSV uploads",
    "sourcePlatform": "LIST_UPLOAD",
    "type": "COMPANY_LIST_UPLOAD"
}'

A successful response returns a 201 Created HTTP status code and the segment ID in the x-restli-id response header.

Upload audience list file to DMP segment

Adding an audience file to a DMP Segment is broken up into two separate webservice calls. The first call uploads an audience file to LinkedIn and returns the location of the file within LinkedIn. The second call then assigns that file by location to the DMP Segment.

Upload audience list file via API

The file must either contain a list of company targets or contact targets. Additionally, it must be in CSV format. Emails must be converted to lowercase, have any white space removed and SHA256 hashed. A full list of file requirements can be found at the following links:

Endpoint: https://api.linkedin.com/media/upload

Method: POST

Header:

Field

Data Type

Description

Authorization

string

(Required)

Authorized access token. Example: "Bearer ACCESS_TOKEN".

Content-Type

string

(Required)

"multipart/form-data".

Parameters:

The following parameters must be included in the request body in the form-data format.

Field

Data Type

Description

file

file

(Required)

Only supports CSV. The file suffix should be exactly .csv.

DM Caveat

The requirement for multipart/form-data and a file upload presents a difficulty for DM. The request must be created manually using a Calculate function after consuming the customer file. We must define a form-data boundary, the request content type, including the boundary, and the request itself.

Examples:

  • Field: boundary
    Expression: "0ebd3"

  • Field: contentType
    Expression: "multipart/form-data; boundary=" + boundary

  • Field: request
    Expression:

CODE
"--" + boundary + "
Content-Disposition: form-data; name=\"file\"; filename=\"file:///C:/Users/AlexLada/OneDrive - Red Point Global Inc/Documents/dev/linked in/LinkedIn_Ads_Contact_Match_Template.csv\"
Content-Type: text/csv

"+ DecodeTextBytes(contents,"UTF8") +"
--" + boundary + "--"

When run through a DM web service with the request field assigned to the Body field, this produces a payload that contains contents of the file located at filename.

A successful response includes a body containing a media URN. Save this to be used in the step where the list upload is associated with a DMP segment.

Response:

CODE
{
    "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"
}

Attach audience list to DMP segment

Once the Audience List is uploaded to LinkedIn, we can use its contents to assign to a DMP Segment via the file's URN.

Endpoint: https://api.linkedin.com/rest/dmpSegments/{dmpSegment_id}/listUploads

Method: POST

Header:

Field

Data Type

Description

Authorization

string

(Required)

Authorized access token. Example: "Bearer ACCESS_TOKEN"

Content-Type

string

(Required)

"application/json".

LinkedIn-Version

string

Version number in the format YYYYMM.

Parameters:

Field

Data Type

Description

inputFile

urn

(Required)

Full URN of file location.

Example: "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"

Request:

JSON
curl -X POST 'https://api.linkedin.com/rest/dmpSegments/{dmpSegment id}/listUploads' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
    "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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.