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.

• LinkedIn provides an online graphical user interface (GUI) for creating each access token: https://www.linkedin.com/developers/tools/oauth/token-generator. At a minimum, the scope must include r_ads and rw_ads.

• Tokens have a 2 month life before needing to be refreshed. They can be inspected via the online GUI: https://www.linkedin.com/developers/tools/oauth/token-inspector.

• A full guide to creating a LinkedIn app, setting it up for OAuth, and managing tokens is beyond the scope of this document and can be found at https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?toc=%2Flinkedin%2Fmarketing%2Ftoc.json&bc=%2Flinkedin%2Fbreadcrumb%2Ftoc.json&view=li-lms-2023-09&tabs=HTTPS1.

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:

Parameters:

Request:

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:

• Requirements for company targeting lists

• Requirements for contact targeting lists

• Further requirements

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

Method: POST

Header:

Parameters:

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

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:

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

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

Parameters:

Request:

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.