Build an Ad Campaign
Warning
Deprecation Notice
The Marketing Version 202308 (Marketing August 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
OAuth 2.0 and Permission Scopes
All LinkedIn API endpoints have access limitations called permission "Scopes", which define what your app can do on a user's behalf.
OAuth 2.0 Scopes are a part of the authentication process and define USER ACCESS (r_basicprofile, r_ads, rw_ads) to LinkedIn PRODUCTS (Consumer, Marketing, Learning) and SERVICES (Posts, Ad Accounts, Campaign management.)
Marketing APIs require the rw_ads
scope. Other APIs require additional permission scopes which are documented in topic-specific pages. To learn more, see Marketing-Frequently Asked Questions.
Map Campaign Ad Account ID to Application
- From Campaign Manager, copy the nine-digit Ad "Account ID".
- Open the Developer Portal and select your application.
- From the "Products" tab click "View Ad Accounts".
- Click "Add Ad Account" and paste the Ad Account ID, then save.
This particular Ad Account is now mapped to the selected application. Repeat for any other Ad Accounts you need to add for this or any other applications.
Create an Ad Account
Ad Account
Sample Request
POST https://api.linkedin.com/rest/adAccounts
POST http://api.linkedin.com/v2/adAccountsV2
Sample Request Body
{
"currency": "USD",
"name": "Company ABC",
"notifiedOnCampaignOptimization": true,
"notifiedOnCreativeApproval": true,
"notifiedOnCreativeRejection": true,
"notifiedOnEndOfCampaign": true,
"reference": "urn:li:organization:101202303",
"type": "BUSINESS"
}
A successful response returns a 201 Created
HTTP status code and the ID of the account in the x-linkedin-id
response header. You can also retrieve the Ad Account ID later through the API or UI. To learn more about working with Ad Accounts, see Accounts.
Create a Campaign Group
Campaign Groups give advertisers a way to manage status, budget, and performance across multiple related campaigns. Creating Campaign Groups is optional. Campaigns can still be created on their own without an associated Campaign Group.
Use the following API to create a Campaign Group:
Ad Campaign Groups
Sample request
Note
This API does not support ENTERPRISE
accounts.
POST https://api.linkedin.com/rest/adAccounts/{adAccountID}/adCampaignGroups
Note
This API does not support ENTERPRISE
accounts.
POST https://api.linkedin.com/v2/adCampaignGroupsV2
Sample Response
{
"account": "urn:li:sponsoredAccount:502616245",
"name": "CampaignGroup1",
"runSchedule": {
"end": 9876543210123,
"start": 1234567890987
},
"status": "ACTIVE",
"totalBudget": {
"amount": "60000.00",
"currencyCode": "USD"
}
}
Find Target Audience
Before creating a campaign, you must define the right audience by specifying targeting criteria. The targeting criteria can also be updated after the campaign is created.
LinkedIn offers a collection of APIs to discover audiences for your campaign. For a campaign to run, the target audience must have at least 300 members. This ensures that there is enough impression data for the system to properly assess its effectiveness. To learn more, see Audience Counts API and Ads Targeting.
First, explore the targeting criteria that is available on the LinkedIn Campaign Management platform. The following example uses the adTargetingFacets
API to discover the available ad targeting facets. Facets are targeting types such as industries, locations, or seniority level. Each facet contains entities that reflect the individual values which can be fetched through the adTargetingEntities
API.
For example, the locations
facet includes entities such as Canada and the United States.
Ad Targeting Facets
Sample Request
GET https://api.linkedin.com/rest/adTargetingFacets
GET http://api.linkedin.com/v2/adTargetingFacets
Response
The API response shows the available targeting facets. Each facet record contains the name of the facet, the type, and the Finder methods available to query for more information and discover the facet's entities.
{
"elements": [
{
"facetName": "seniorities",
"availableEntityFinders": [
"AD_TARGETING_FACET"
],
"entityTypes": [
"SENIORITY"
],
"$URN": "urn:li:adTargetingFacet:seniorities"
},
{
"facetName": "locations",
"availableEntityFinders": [
"AD_TARGETING_FACET"
],
"entityTypes": [
"GEO"
],
"$URN": "urn:li:adTargetingFacet:locations"
},
{
"facetName": "industries",
"availableEntityFinders": [
"AD_TARGETING_FACET",
"TYPEAHEAD",
"SIMILAR_ENTITIES"
],
"entityTypes": [
"INDUSTRY"
],
"$URN": "urn:li:adTargetingFacet:industries"
},
...
]
}
Next, drill down into a facet to discover its entities. Entities can be included or excluded from your targeting.
Use the following API to discover the entities within a facet. The example below fetches possible seniority levels.
Ad Targeting Entities
Sample request
GET http://api.linkedin.com/rest/adTargetingEntities?q=adTargetingFacet&queryVersion=QUERY_USES_URNS&facet=urn:li:adTargetingFacet:seniorities
GET https://api.linkedin.com/v2/adTargetingEntities?q=adTargetingFacet&queryVersion=QUERY_USES_URNS&facet=urn:li:adTargetingFacet:seniorities
Sample Response
{
"elements": [
{
"urn": "urn:li:seniority:1",
"facetUrn": "urn:li:adTargetingFacet:seniorities",
"name": "Unpaid"
},
{
"urn": "urn:li:seniority:2",
"facetUrn": "urn:li:adTargetingFacet:seniorities",
"name": "Training"
},
{
"urn": "urn:li:seniority:3",
"facetUrn": "urn:li:adTargetingFacet:seniorities",
"name": "Entry"
},
{
"urn": "urn:li:seniority:4",
"facetUrn": "urn:li:adTargetingFacet:seniorities",
"name": "Senior"
},
{
"urn": "urn:li:seniority:5",
"facetUrn": "urn:li:adTargetingFacet:seniorities",
"name": "Manager"
},
...
]
}
For more information, see Ad Targeting Facets & Entities.
Once you have settled on a target audience, you will need to look up the size of the audience you are targeting using the Audience Counts API. Target audiences must have at least 300 members to run a campaign against that audience.
This API takes in query parameters that define your desired targeting criteria.
Note
The parameter q=targetingCriteria
is always required as it represents the Finder targetingCriteria
request.
The following sample targeting request estimates the audience count of members in Canada and the United States while excluding members who are in entry-level positions.
Audience Counts
Sample request
GET https://api.linkedin.com/rest/audienceCounts?q=targetingCriteria&target.includedTargetingFacets.locations[0]=urn:li:geo:101174742&target.includedTargetingFacets.locations[1]=urn:li:geo:103644278&target.excludingTargetingFacets.seniorities[0]=urn:li:seniority:3
GET https://api.linkedin.com/v2/audienceCountsV2?q=targetingCriteria&target.includedTargetingFacets.locations[0]=urn:li:geo:101174742&target.includedTargetingFacets.locations[1]=urn:li:geo:103644278&target.excludingTargetingFacets.seniorities[0]=urn:li:seniority:3
Sample Response
The API returns a list of AudienceCount
results based on the targetingCriteria
parameters input above. The following example shows the data that is returned. Values are rounded estimates.
{
"elements": [
{
"total": 170000000,
"active": 0
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
For more information, see Audience Counts.
View Ad Budget Pricing
The last thing you'll do before creating your campaign is to discover how you should bid. The Ad Budget Pricing API returns pricing metrics such as minimum, maximum, and suggested bids. The Ad Budget Pricing API offers insight into these metrics given the targeting criteria that you specify.
The following sample request returns the pricing based on our targeting criteria of members living in the United States and Canada, while excluding members in an entry-level position. The suggested bid returned is for the specified dailyBudget
of USD 100.
Ad Budget Pricing
Sample request
GET https://api.linkedin.com/rest/adBudgetPricing?account=urn:li:sponsoredAccount:502616245&bidType=CPM&campaignType=TEXT_AD&matchType=EXACT&q=criteria&target.includedTargetingFacets.locations[0]=urn:li:geo:101174742&target.includedTargetingFacets.locations[1]=urn:li:geo:103644278&target.excludingTargetingFacets.seniorities[0]=urn:li:seniority:3&dailyBudget.amount=100&dailyBudget.currencyCode=USD
GET https://api.linkedin.com/v2/adBudgetPricing?account=urn:li:sponsoredAccount:502616245&bidType=CPM&campaignType=TEXT_AD&matchType=EXACT&q=criteria&target.includedTargetingFacets.locations[0]=urn:li:geo:101174742&target.includedTargetingFacets.locations[1]=urn:li:geo:103644278&target.excludingTargetingFacets.seniorities[0]=urn:li:seniority:3&dailyBudget.amount=100&dailyBudget.currencyCode=USD
Sample Response
{
"elements": [
{
"suggestedBid": {
"default": {
"amount": "2.00",
"currencyCode": "USD"
},
"min": {
"amount": "2.00",
"currencyCode": "USD"
},
"max": {
"amount": "2.73",
"currencyCode": "USD"
}
},
"dailyBudgetLimits": {
"default": {
"amount": "25.00",
"currencyCode": "USD"
},
"min": {
"amount": "10.00",
"currencyCode": "USD"
},
"max": {
"amount": "1000000.00",
"currencyCode": "USD"
}
},
"bidLimits": {
"min": {
"amount": "2",
"currencyCode": "USD"
},
"max": {
"amount": "200.0",
"currencyCode": "USD"
}
}
}
],
"paging": {
"count": 10,
"start": 0,
"links": []
}
}
To learn more, see Ad Budget Pricing.
Create a Campaign
Now that you know your target audience and bid amounts, create your campaign.
Campaigns can be created with a variety of types such as SPONSORED_UPDATES
, SPONSORED_INMAILS
, AND TEXT_AD
. This example shows how to create a simple text ad campaign.
Ad Campaigns
Sample request
POST https://api.linkedin.com/rest/adAccounts/{adAccountID}/adCampaigns
POST http://api.linkedin.com/v2/adCampaignsV2
Sample Response
A successful response returns a 201 Created
HTTP status code and the ID in the x-linkedin-id
response header.
{
"account": "urn:li:sponsoredAccount:502616245",
"audienceExpansionEnabled": false,
"costType": "CPC",
"creativeSelection": "OPTIMIZED",
"dailyBudget": {
"amount": "100",
"currencyCode": "USD"
},
"locale": {
"country": "US",
"language": "en"
},
"name": "Text Ad Campaign",
"offsiteDeliveryEnabled": false,
"runSchedule": {
"end": 9876543210123,
"start": 1234567890987
},
"targetingCriteria": {
"include": {
"and": [
{
"or": {
"urn:li:adTargetingFacet:locations": [
"urn:li:geo:103644278",
"urn:li:geo:101174742"
]
}
}
]
},
"exclude": {
"or": {
"urn:li:adTargetingFacet:seniorities": [
"urn:li:seniority:3"
]
}
}
},
"type": "TEXT_AD",
"unitCost": {
"amount": "2",
"currencyCode": "USD"
}
}
To learn more about working with campaigns, see Create and Manage Campaigns.
Create an Ad Creative
Next, you'll create an Ad Creative defining how the ad should appear on LinkedIn. There are several creative types in LinkedIn Campaign Management:
- Text Ads: Appears in various parts of LinkedIn.com
- Sponsored Content: Appears in the homepage feed of members within the targeted audience
- Sponsored InMail: A message delivered to a LinkedIn member’s InMail
- Sponsored Video: Contains user-generated video content
- Sponsored Carousel Ad: Displays multiple images in succession in a single ad unit, each with its own description and destination link
In this example, we'll show you how to create a text ad and associate it with a campaign in the same request by specifying the type
field as a TEXT_AD
and the campaign
field with a campaign's URN.
Ad Creatives
Sample Request
POST https://api.linkedin.com/rest/adAccounts/{adAccountID}/creatives
POST https://api.linkedin.com/v2/adCreativesV2
Sample Response
A successful response returns a 201 Created
HTTP status code and the ID in the x-linkedin-id
response header.
{
"campaign": "urn:li:sponsoredCampaign:123456",
"status": "ACTIVE",
"type": "TEXT_AD",
"variables": {
"clickUri": "https://www.linkedin.com",
"data": {
"com.linkedin.ads.TextAdCreativeVariables": {
"text": "This is a test ad description that links to LinkedIn",
"title": "This is Test Ad!"
}
}
}
}
To learn more about working with creatives, see Ad Creatives.
Next Steps
Check out the Overview page to discover all that's possible with the APIs. LinkedIn's Campaign Management APIs offer a wide range of capabilities to help you build powerful integrations quickly and easily.