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
, orCREATIVE_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:
Create an Ad Account in https://www.linkedin.com/marketing/businessmanager/accounts/.
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
Add the Ad Account to the Advertising API product enabled on the LinkedIn app.
Using the managing LinkedIn user account, generate a long lived access token.
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
andrw_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 calledLIST_UPLOAD
.The
type
of DMP Segment determines the type of CSV file (company list or SHA256-hashed emails) to be ingested. UseCOMPANY_LIST_UPLOAD
for any company lists andUSER_LIST_UPLOAD
for email lists.
Endpoint: https://api.linkedin.com/rest/dmpSegments
Method: POST
Header:
Field | Data Type | Description |
---|---|---|
|
| (Required) Authorized access token. Example: |
|
| (Required)
|
|
| Version number in the format |
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required)
|
|
| (Required) Full URN of Ad Account. Example: |
|
| A description of the segment. |
|
| (Required) The name of the segment. |
|
| The destinations and various metadata that the content of this segment will be onboarded to. Currently, the only accepted value is |
|
| (Required)
|
|
| (Required) The type of list uploaded: Either |
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:
Endpoint: https://api.linkedin.com/media/upload
Method: POST
Header:
Field | Data Type | Description |
---|---|---|
|
| (Required) Authorized access token. Example: |
|
| (Required)
|
Parameters:
The following parameters must be included in the request body in the form-data
format.
Field | Data Type | Description |
---|---|---|
file |
| (Required) Only supports CSV. The file suffix should be exactly |
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:
Field | Data Type | Description |
---|---|---|
|
| (Required) Authorized access token. Example: |
|
| (Required)
|
|
| Version number in the format |
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required) Full URN of file location. Example: |
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.