Getting Started with LinkedIn's Marketing APIs
Before You Start
You’ll need to do the following to get started with LinkedIn Marketing APIs:
- Create a LinkedIn Page
- Create a developer application
- Review our API and data restrictions
- Apply to the Marketing Developer Platform
- Application review may take a few days
Once you’ve gained access to the Marketing Developer Platform:
- Generate an access token
- Ensure you have the right permissions based on your use case
- Validate which LinkedIn Pages a user has access to
- Validate which ad accounts a user has access to
- Map the Ad Account ID to your application
- Review Tips to Get Started
- Check out the Use Case guides to build your solution
Manage your app through the Developer Portal
The Developer Portal provides tools and resources to support your integration:
- Token generator: generate a new token using the Developer Portal.
- Token inspector: check the Time to Live (TTL) and status (active/expired) for all tokens
- API endpoint catalog: get a holistic view of the endpoints and permissions your application has access to
- App analytics: assess app performance to understand product health, diagnose issues, and stay informed on usage trends in order to better serve your users
- Webhooks: register your webhook to receive real-time HTTP notifications for subscribed events
- Add team members: enable your team to manage your app and receive the API newsletter.
Validating Company Page/Organization Roles
/organizationAcls endpoint has the following methods to determine which members have access to which Company Page/Organization. Follow the links below for specific examples.
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
/adAccountUsersV2 endpoint has the following methods to determine which members have access to which Ad Accounts. Follow the links below for specific examples.
/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.
- What is a Company Page/Organization?
- What is an Ad Account?
- Managing Your Ad Accounts List
- How do Company Pages and Ad Accounts relate to each other?
- How do I make API calls on behalf of a LinkedIn member?
- 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.
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.
|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|
|ANALYST||Access to view an organization's private administrative data that relates to its social presence on LinkedIn, access limited to analytics tab to monitor the Page’s performance to help drive goals. Can edit the competitors of a page.|
|CURATOR||Access to broadcast content to employees of the organization, view Content Suggestions, create recommended content, and view and export Page analytics. Can edit the competitors of a page.|
|CONTENT_ADMINISTRATOR||Access to create and manage Page content, including updates, pinned posts, boosting updates, events, jobs etc.|
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.
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 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.
|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
- There should be only one ACCOUNT_BILLING_ADMIN user role for an account.
- The creator of the Ad Account is assigned Account Billing Administrator by default.
- Other roles can be added and given roles through the UI.
- Click the gear icon in the upper right corner of Campaign Manager and then select "Manage Access".
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.
- Select your application from the list of apps.
- Click the "Products" tab in the navigation
- Click the "View settings" link next to "Marketing Developer Platform"
- Add or remove Ad Accounts from this page
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
/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.
|rw_organization_admin||Manage an authenticated member’s company pages and retrieve reporting data.|
|r_organization_admin||Retrieve your organization's pages and their reporting data (including follower, visitor and content analytics).|
|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:
|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:
|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:
|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.
Depending on what type of integration you are building, proceed to one of the following integration specific getting started guides.