Getting Started with LinkedIn's Marketing APIs

Start Here

Before you begin an advertising campaign on LinkedIn, you will need the following:

  1. LinkedIn Company Page: This is your organization
  2. Developer App: Create your application
  3. Approved Marketing Access: Apply for access on the products tab when you create your app:
    1. This process is not instantaneous, and may take one or more days for approval.
  4. OAuth 2.0 access token with rw_ads Permission Scope.

LinkedIn Developer Portal

The LinkedIn Developer Portal has app tools, product, and resources to support your integration":

  • App builder: An application builder to start advertising on LinkedIn.
    • Settings: Adjust your application settings.
    • Auth: Generate app credentials, set duration, and permission scopes (access levels.)
    • Products: Select from our open or proprietary marketing products.
    • Webhooks: Receive real-time HTTP notifications for subscribed events.
    • Analytics: View app quotas, usage, and errors.
    • Team members: Manage Ad Account users and Admins.

Products Tab

Ad Account Requirements

  1. An Ad Account is required before you create an Ad Campaign.
  2. You must map the Ad Account ID to your application.
  3. The Marketing Developer Platform requires internal approval and is limited by Access Tiers.

If you already have approval: Build an Ad Campaign.

FAQ

  1. What is a Company Page/Organization?
  2. What is an Ad Account?
  3. Managing Your Ad Accounts List
  4. How do Company Pages and Ad Accounts relate to each other?
  5. How do I make API calls on behalf of a LinkedIn member?=
  6. How do I generate an OAuth 2.0 token?
  7. How do I know what roles a member has?

If these topics are already familiar to you, jump to Build an Ad Campaign.

What is a Company Page/Organization?

A Company Page is an entity that represents an organization on LinkedIn. The Company Page is where a company can post organic content and interact with members on LinkedIn. In addition to the Ad Account, the Company Page is one of the key entities that is used across marketing APIs for both sponsored and organic use cases.

See Creating a LinkedIn Page guide for instructions on creating a company page.

Note

Company Pages are also referred to as "Organizations", and these terms are used interchangeably in the documentation.

Company Page Roles

Company Pages can be managed by members who have been granted one of the following roles within that Company Page.

Role Description
ADMINISTRATOR Administer an organizational entity; Post updates; Edit the organization page; Manage administrators; View analytics and notifications
DIRECT_SPONSORED_CONTENT_POSTER Create/View direct sponsored content (DSC) for an organizational entity
RECRUITING_POSTER Post to an organizational entity
LEAD_CAPTURE_ADMINISTRATOR View/Manage landing pages for the company; Create/Edit landing pages
LEAD_GEN_FORMS_MANAGER Access leads that belong to a specific account which is associated with a company page

The creator of the Company Page is the Administrator by default. All others can be added and given roles through the UI. Click "Admin tools" on the right side of the admin view of the Company Page and then select "Manage Admins". To add a member to a company page you must be connected on LinkedIn.

Company Page Admin Tools

What is an Ad Account?

An Ad Account (a.k.a. Sponsored Account) is an umbrella entity for advertising management on LinkedIn, e.g., billing, campaigns, ad creatives, tracking tags, and more.

Ad Accounts can be managed through the UI using the Campaign Manager tool. Learn how to access Campaign Manager from the LinkedIn homepage, or for more information see Campaign Manager Overview

Ad Account Roles

Ad Accounts can be managed by members who have been granted one of the following roles within that Ad Account. Please note that you must be connected to a LinkedIn member to add them to a Company Page.

Role Description
VIEWER View campaign data and reports (cannot Create/Edit campaigns or ads)
CREATIVE_MANAGER Create/Edit/View campaign data and reports; Create/Edit ads
CAMPAIGN_MANAGER View campaign data and reports; Create/Edit campaigns and ads
ACCOUNT_MANAGER View campaign data and reports. Create/Edit campaigns and ads; Edit account data and manage user access
ACCOUNT_BILLING_ADMIN View campaign data and reports; Create/Edit campaigns and ads. Edit account data and manage user access. Can also access billing data and will be billed for this account. (See next paragraph for more details on this role

Account Billing Admin role

  1. There should be only one ACCOUNT_BILLING_ADMIN user role for an account.
  2. The creator of the Ad Account is assigned Account Billing Administrator by default.
  3. Other roles can be added and given roles through the UI.
  4. Click the gear icon in the upper right corner of Campaign Manager and then select "Manage Access".

Ad Account Gear

Managing Your Ad Accounts List

Once your application has been accepted into the Development Tier, you can manage and view your Ad Accounts from the developer portal. You can add up to 5 accounts to manage in the Development Tier.

  1. Select your application from the list of apps.
  2. Click the "Products" tab in the navigation
  3. Click the "View settings" link next to "Marketing Developer Platform"
  4. Add or remove Ad Accounts from this page Managing Your Ad Accounts List.

Only accounts that have been configured for access in the Ad Accounts tab of your application can be managed through the API.

You cannot create new accounts through the API in the Development Tier.

How do Company Pages and Ad Accounts relate to each other?

Company Pages can be associated with Ad Accounts to advertise on behalf of that organization. For example, if an organization wanted to boost exposure to their Company Page's content by sponsoring it, they would need to associate their Company Page with an Ad Account.

While not required, we recommended that you always associate a Company Page with an Ad Account to get the full benefits of LinkedIn's marketing capabilities. Some campaign objectives and ad creative types require a Company Page to be associated with the Ad Account.

  • A Company Page can be associated with multiple Ad Accounts.
  • An Ad Account can only be associated with a single Company Page.
  • Once an Ad Account is linked to a particular Company Page, it cannot be changed.

How do I make API calls on behalf of a LinkedIn member?

Once you have a developer application that has been given access to the Marketing Developer Platform, you are ready to start generating OAuth access tokens to make API calls on behalf of authenticated members.

Before an API call can be made, any required permission scopes must first be granted by the LinkedIn member. This ensures that members are made aware of what an application could potentially access or do on their behalf.

If your application requires multiple permissions to access all the data it requires, members who use your application are required to accept all of them. They cannot accept only a subset of the requested application permissions. To provide the best experience for the member, ensure that your application requests the fewest necessary permissions.

How do I know what roles a member has?

One of the common errors developers encounter is attempting to make API calls to Company Pages, Ad Accounts, and their associated objects using a token belonging to a member who does not have a role defined under a given Company Page or Ad Account. You can use the /adAccountUsersV2 and /organizationAcls API to validate what roles a member has.

The Marketing Developer Platform(MDP) gives access to the following permissions. All these permission scopes are 3-legged permissions requiring explicit approval by a LinkedIn member. The 2-legged client credentials flow is not available for any marketing use cases.

Permission Description
rw_organization_admin Manage an authenticated member’s company pages and retrieve reporting data.
w_organization_social Post, comment and like posts on behalf of an organization. Restricted to organizations in which the authenticated member has one of the following company page roles:
  • ADMINISTRATOR
  • DIRECT_SPONSORED_CONTENT_POSTER
  • LEAD_GEN_FORMS_MANAGER
r_organization_social Retrieve organizations' posts, comments, and likes.
w_member_social Post, comment and like posts on behalf of an authenticated member.
rw_ads Manage and read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles:
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER
r_ads Read an authenticated member's Ad Accounts. Restricted to ad accounts in which the authenticated member has one of the following Ad Account roles:
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER
r_ads_reporting Retrieve reporting for advertising accounts.
r_1st_connections_size Retrieve the count of an authenticated member's 1st-degree connections.
r_basicprofile Read an authenticated member's basic profile including name, photo, headline, and public profile URL.

In addition to these permissions, members must have the appropriate roles as defined in Company Page Roles and Ad Account Roles to act on or read data from a given Company Page or Ad Account. See How Do I Know What Roles a Member Has to determine which roles an authenticated member has through the API.

One of the common errors developers encounter is attempting to make API calls to Company Pages, Ad Accounts, and their associated objects using a token belonging to a member who does not have a role defined under a given Company Page or Ad Account. You can use the API to validate what roles a member has.

Generate an Access Token

The full process your application will need to implement for 3-legged tokens is described in Authorization Code Flow. The steps outlined below describe the process for using Postman to generate OAuth tokens for testing.

Step 1

Go to the LinkedIn Developer Portal, select the app you'll be using, click the "Auth" tab, and locate your Client ID and Client Secret. Please note these values for use later during this process.

LinkedIn Auth Tab

Step 2

From the same "Auth" tab, scroll to the bottom of the page. Under "OAuth 2.0 Settings", add the Postman callback URL https://oauth.pstmn.io/v1/callback as your Redirect URL.

Note

Postman uses the term "Callback URL"
LinkedIn uses the term "Redirect URL"

Postman Callback URL

Step 3

Open a new tab in Postman, click the "Authorization" tab and select "OAuth 2.0":

Authorization Type

Step 4

Scroll down the authorization page and click "Get New Access Token".

Get New Access Token

Step 5

Enter the Authorization parameters, then click "Get new access token":

  • Grant Type: Authorization Code
  • Callback (Redirect) URL: https://oauth.pstmn.io/v1/callback
    • Select "Authorize using browser" to have Postman generate a callback from the users browser
  • Auth URL: https://www.linkedin.com/oauth/v2/authorization
  • Access Token URL: https://www.linkedin.com/oauth/v2/accessToken
  • Client ID: {Copy this from the "Auth" tab in the developer portal}
  • Client Secret: {Copy this from the "Auth" tab in the developer portal}
  • Scope: r_organization_social,w_organization_social,rw_organization_admin,rw_ads,r_ads_reporting,r_liteprofile
  • Client Authentication: Send client credentials in body

Set Authorization Parameters

Step 6

Postman will take you to the LinkedIn authorization page, where you may be prompted to log into LinkedIn. Click "Allow" to authorize the request.

Authorize Scopes

Step 7

Postman will then display your access token. Use this for testing. For convenience, it's advisable to configure the token in a Postman environment variable to use in all your requests to the LinkedIn API. You can read about configuring this in Postman's documentation on variables

Access Token

Step 8

Finally, create a new tab in Postman to test your token. Fill out the following fields:

  • Set the request URL as https://api.linkedin.com/v2/me
  • Under the request "Headers" tab, add the header key Authorization with value Bearer{paste your token}. If you set your token in a Postman environment variable, the value should be Bearer {{TOKEN_ENV_VAR}} where TOKEN_ENV_VAR would be replaced by the name you set for your variable. In the example below, the variable is named TOKEN
    • Optional: Many LinkedIn API calls will require a request header with X-Restli-Protocol-Version: 2.0.0

Make First API Call

Assuming your token was authorized for the product scopes listed in Step 6, your call should be successful and return some basic profile fields from your LinkedIn profile.

Validating Company Page/Organization Roles

The /organizationAcls endpoint has the following methods to determine which members have access to which Company Page/Organization. Follow the links below for specific examples.

  1. Find an Organization's Members
  2. Find a Member's Organizations

Access to a Company Page/Organization cannot be granted or updated through the API. Please use the UI tool to grant, update, or remove access.

Validating Ad Account Roles

The /adAccountUsersV2 endpoint has the following methods to determine which members have access to which Ad Accounts. Follow the links below for specific examples.

  1. Find Ad Account Users by Ad Accounts
  2. Find Ad Accounts by Authenticated User
  3. Get Ad Account User

Additionally, /adAccountUsersV2 can be used to grant, update, or revoke access to an Ad Account. This action must be performed using the token of a member who has either an ACCOUNT_BILLING_ADMIN or ACCOUNT_MANAGER role.

  1. Grant Access
  2. Update Access
  3. Revoke Access

Next Steps

Depending on what type of integration you are building, proceed to one of the following integration specific getting started guides.