Media Planning
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 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.
Overview
Media Planning API can help Media Planners understand the reach and ROI that LinkedIn can offer to their client. It allows them to make budget allocation recommendations with confidence and know how to improve the results, even before spending the first dollar. Media Planning API helps Media Planners make that decision by giving the forecasted reach, impressions (and more in future, like clicks, leads) curve over the budget, based on inputs provided like targeted audience, campaign start/end date and more.
Note
This is a private API that is available to qualified developers who meet additional criteria for access. To learn more about eligibility qualifications and how to request access, please see the FAQ. If you wish to apply for access, submit a Zendesk support ticket.
Permissions
Media Planning API requires a 3-legged OAuth member token, and your developer application needs to be provisioned with the Media Planning API product. Once you have been approved to access, you can use any valid member access token associated with the authenticated user with any valid scope permissions for member authentication. If there is no valid member token for the relevant user from any previous integration, we recommend using the bare minimum scope permissions like r_ads which will be required to fetch authenticated user's ad accounts.
Note
This API is application-specific; hence, explicit member consent is not required. Any valid member access token associated with the authenticated user can be used, and you do not need to add any additional permission in the scope of your Oauth2 flow for authorization.
Request Schema
| Field | Type | Description | Required |
|---|---|---|---|
| request | request Object | request Object that wraps the entire request body. See details below. | Yes |
request Object
| Field | Type | Description | Required |
|---|---|---|---|
| sponsoredAccountUrn | URN | The sponsored ad account URN where the authenticated user has a valid ad account user role. | Yes |
| targetingCriteria | targetingCriteria Object | targetingCriteria Object defines the audience that the desired insights are for. This is a boolean expression of ad targeting facets and entities that identifies the member attributes to be included/excluded in the audience. See details below. | Yes |
| currencyCode | string | The currency units for the forecasting curve. | Optional(default=USD) |
| objectiveType | string (Enum) | The objective of your marketing campaign. Refer objectivetype. | Yes |
| optimizationType | string (Enum) | The marketing results that you’re optimizing for. | Optional (default=MAX_REACH for BRAND_AWARENESS objectiveType, default=MAX_VIDEO_VIEW for VIDEO_VIEW objective type, and default=MAX_LEAD for LEAD_GENERATION objective type) |
| startDate | date | The start date of the media plan. | Optional (default=today’s date in UTC) |
| endDate | date | The end date of the media plan. | Optional (default=90 days since today’s date in UTC) |
| targetBudgetMicros | long | A specific budget that the caller is interested in. More metrics will be returned about this point. Note that this budget is represented in micros for precision ($1 USD = 1000000 micros) | Optional (default=none) |
| enableAudienceNetwork | boolean | The LinkedIn Audience Network status. (It’s enabled if true and disabled if false.) | Optional (default=true) |
| enableAudienceExpansion | boolean | The Audience Expansion status. (It’s enabled if true and disabled if false.) | Optional (default=true) |
| Field | Type | Description | Required |
|---|---|---|---|
| sponsoredAccountUrn | URN | The sponsored ad account URN where the authenticated user has a valid ad account user role. | Yes |
| targetingCriteria | targetingCriteria Object | targetingCriteria Object defines the audience that the desired insights are for. This is a boolean expression of ad targeting facets and entities that identifies the member attributes to be included/excluded in the audience. See details below. | Yes |
| currencyCode | string | The currency units for the forecasting curve. | Optional(default=USD) |
| objectiveType | string (Enum) | The objective of your marketing campaign. Refer objectivetype. | Yes |
| optimizationType | string (Enum) | The marketing results that you’re optimizing for. | Optional (default=MAX_REACH for BRAND_AWARENESS objectiveType, default=MAX_VIDEO_VIEW for VIDEO_VIEW objective type, and default=MAX_LEAD for LEAD_GENERATION objective type) |
| startDate | date | The start date of the media plan. | Optional (default=today’s date in UTC) |
| endDate | date | The end date of the media plan. | Optional (default=90 days since today’s date in UTC) |
| targetBudgetMicros | long | A specific budget that the caller is interested in. More metrics will be returned about this point.`Note': This budget is represented in micros for precision ($1 USD = 1000000 micros) | Optional (default=none) |
| enableAudienceNetwork | boolean | The LinkedIn Audience Network status. (It’s enabled if true and disabled if false.) | Optional (default=true) |
| enableAudienceExpansion | boolean | The Audience Expansion status. (It’s enabled if true and disabled if false.) | Optional (default=true) |
| ctvOnly | boolean | Forecast for connected TV only campaigns if true. This will only be supported if objective is BRAND_AWARENESS and enableAudienceNetwork is set to true. | Optional (default=false) |
Ad Account User Roles:
ACCOUNT_BILLING_ADMINACCOUNT_MANAGERCAMPAIGN_MANAGERCREATIVE_MANAGERVIEWER
To make a request on behalf of a given user, you should fetch that authenticated user’s ad accounts and select one of their ad accounts. Refer Find Ad Accounts By Authenticated User to find and select an ad account.
For more information on Ad Account roles and permissions:
targetingCriteria Object
targetingCriteria provides a generic AND / OR construct to include and exclude different adTargetingFacets when defining the audience. The targeting criteria can be composed of LinkedIn Audience Attributes and/or existing matched audience Ad Segments (Contact/Company lists). See Ad Segments to fetch existing matched audience ad segment URNs that can be passed to urn:li:adTargetingFacet:audienceMatchingSegments.
The basic structure for a targetingCriteria object is as follows:
{
"targetingCriteria":{
"include":{
"and":[
{
"or":{
"urn:li:adTargetingFacet:{facet1}":[
"{facet1_value1}",
"{facet1_value2}"
],
"urn:li:adTargetingFacet:{facet2}":[
"{facet2_value1}"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:{facet3}":[
"{facet3_value1}",
"{facet3_value2}"
]
}
}
]
},
"exclude":{
"or":{
"urn:li:adTargetingFacet:{facet4}":[
"{facet4_value1}"
]
}
}
}
}
Refer the below links for additional details:
- targetingCriteria object
- Descriptive examples for targetingCriteria object
- List of supported adTargetingFacets in targetingCriteria object
- Ad Targeting Entities
Validations and Minimum Requirements
- A sponsored ad account ID must be provided in the request. Authenticated members must have access to that sponsored ad account (any role VIEWER or above).
- For the MVP version of the API, the only currency supported as input is USD (default).
- An objectiveType must always be present as input in the API request. Current supported values are "BRAND_AWARENESS", "VIDEO_VIEW", and "LEAD_GENERATION".
- The optimizationType values supported are "MAX_REACH", "MAX_IMPRESSION", "MAX_VIDEO_VIEW" and "MAX_LEAD". This is an optional input in the API request and defaults to "MAX_REACH" for the objectiveType "BRAND_AWARENESS", "MAX_VIDEO_VIEW" for the objectiveType "VIDEO_VIEW", and "MAX_LEAD" for the objectiveType "LEAD_GENERATION".
- The minimum target budget to be input for a single point metric corresponding to that budget is $100 USD. The upper bound of the metric curve is dynamic instead of fixed, any request with budget value exceeding the upper bound will not be served.
- The total audience counts for the Targeting Criteria provided should be at least 300 for the API to predict reach metrics.
- The targeting criteria provided in the request should always have a geo or profileGeo criteria in the input.
- The start date and end date are optional inputs and defaults to today’s date in UTC and 90 days after respectively. If set explicitly, both the dates must be in the future and the duration between them should not exceed 90 days.
Note
Applications utilizing LinkedIn's targeting capabilities are required to clearly and prominently display a notice in their user interface notifying advertisers that they cannot use LinkedIn to discriminate against members based on personal characteristics. The notice should include the following text: LinkedIn tools may not be used to discriminate based on personal characteristics like gender, age, race, or ethnicity. Learn more. Applications utilizing the Media Planning API need to clearly and prominently display notice in their user interface notifying advertisers the forecasted results are directional estimates and do not guarantee performance. The notice should include the following text: The forecasted results are directional estimates and don't guarantee the actual performance of campaigns.
Sample Request
Note
All API requests are represented in Rest.li Protocol 2.0.0 and require the header: X-Restli-Protocol-Version: 2.0.0. Read the Protocol Versions document to learn about using Rest.li Protocol 2.0.0.
To generate Reach/Reach Percentage curve use action=forecastReaches, to generate Impression/Average Lifetime Frequency curve action=forecastImpressions and to generate Lead Generation curve use action=forecastLeads.
POST https://api.linkedin.com/rest/mediaPlanning?action=forecastReaches
{
"request": {
"sponsoredAccountUrn": "urn:li:sponsoredAccount:123"
"targetingCriteria":{
"include":{
"and":[
{
"or":{
"urn:li:adTargetingFacet:locations":[
"urn:li:geo:105080838"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:interfaceLocales":[
"urn:li:locale:en_US"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:skills":[
"urn:li:skill:236",
"urn:li:skill:242",
"urn:li:skill:252"
]
}
}
]
}
},
"targetBudgetMicros": 300000000,
"optimizationType": "MAX_IMPRESSION",
"objectiveType": "VIDEO_VIEWS",
"startDateOn": {"day":20, "month":1, "year":2024},
"endDateOn": {"day":25, "month":2, "year":2024},
"enableAudienceNetwork": true,
"enableAudienceExpansion": true,
}
}
Response Schema
| Field Name | Type | Description |
|---|---|---|
| reachCurve | ForecastMetrics | The array of points along the reach curve. Will currently return 100 points and an additional point if an input targetBudget was provided. If we were illustrating the curve, budget would be on the x-axis and reach would be on the y-axis. Optional(returned only when action= forecastReaches). The forecasted results are direction estimates and don’t guarantee the actual performance of campaigns. |
| reachPercentageCurve | ForecastMetrics object | The array of points along the reach percentage curve. Will currently return 100 points and an additional point if an input targetBudget was provided. If we were illustrating the curve, budget would be on the x-axis and reach would be on the y-axis. Optional(returned only when action= forecastReaches and enableAudienceExpansion=false). The forecasted results are direction estimates and don’t guarantee the actual performance of campaigns. |
| impressionCurve | ForecastMetrics object | The array of points along the impressions curve. Will currently return 100 points and an additional point if an input targetBudget was provided. If we were illustrating the curve, budget would be on the x-axis and reach would be on the y-axis. Optional(returned only when action= forecastImpressions). The forecasted results are direction estimates and don’t guarantee the actual performance of campaigns. |
| averageFrequency | ForecastMetrics object | Average Frequency is a single point value calculated by impression/reach assuming the single point budget in the request was used to forecast impression and reach results. It would be returned together with the impression curve if the forecasted impression is requested. Optional (returned when action=forecastImpressions and targetBudgetMicros is set in the input). The forecasted results are direction estimates and don’t guarantee the actual performance of campaigns. |
| leadCurve | ForecastMetrics object | The array of points along the lead generation curve. Will currently return 100 points and an additional point if an input targetBudget was provided. If we were illustrating the curve, budget would be on the x-axis and leads generated would be on the y-axis. Optional(returned only when action= forecastLeads). The forecasted results are direction estimates and don’t guarantee the actual performance of campaigns. |
ForecastMetrics Object
| Field Name | Type | Description |
|---|---|---|
| metricCurve | array [MediaPlanningForecastDataPoint] | The array of points along the reach, impressions, reachPercentage or averageFrequency curve. |
| singlePointMetric | array [MediaPlanningForecastDataPoint]] | Optional metrics on a specific point (only returned when targetBudget in the request is populated). |
MediaPlanningForecastDatapoint Object
| Field Name | Type | Description |
|---|---|---|
| budgetMicros | long | The position on the budget axis of the curve. That is, how much budget is required to reach this point on the curve. |
| metricValue | double | The metric number on the curve. |
| metricUpper | double | Optional, the upper bound of the metric. |
| metricLower | double | Optional, the lower bound of the metric. |
Sample Response
{
"value": {
"reachCurve": {
"metricCurve": [
{
"metricValue": 21137.181640625,
"budgetMicros": 100000000
},
{
"metricValue": 22540.12109375,
"budgetMicros": 109020202
},
{
"metricValue": 23913.630859375,
"budgetMicros": 118040405
},
{
"metricValue": 25260.513671875,
"budgetMicros": 127060607
}
... 96 other points
],
"singlePointMetric": {
"metricValue": 21137.181640625,
"budgetMicros": 100000000
}
}
}
}
After fetcing the required forecasts,, you can save the targeting criteria used to plan for the campaigns with the Saved Audience Templates API so that you can activate them through the campaign API or from the Campaign Manager User Interface.
API Error Details
| HTTP Status Code | ERROR MESSAGE | DESCRIPTION | ERROR RESOLUTION |
|---|---|---|---|
| 401 | EMPTY_ACCESS_TOKEN | Empty or expired oauth2 access token | Use a valid member access token. |
| 403 | ACCESS_DENIED | Not enough permissions to access: targetingAudienceInsights | Make sure your developer application is provisioned with the (Private) Media Planning API. |
| 403 | USER_NOT_AUTHORIZED | Caller should have access to the Ad Account provided in the request | Make sure the member associated with access token has a user role on the provided Ad Account. |
| 422 | FAILED_VALIDATION_CONDITION | Request fails structure validation. / Missing required fields in the request. | Make sure all required fields are passed and follow valid structure. |
| 500 | sINTERNAL_SERVER_ERROR | Internal server side error | N/A |