Media Planning

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.

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.

Request Schema

request Object

Ad Account User Roles:

• ACCOUNT_BILLING_ADMIN
• ACCOUNT_MANAGER
• CAMPAIGN_MANAGER
• CREATIVE_MANAGER
• VIEWER

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:

• Ad Account User Role Definitions
• Create and Manage Ad Account Users

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.

Sample Request

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,
 }
}

curl -X POST 'https://api.linkedin.com/rest/mediaPlanning?action=forecastReaches' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'X-RestLi-Protocol-Version:2.0.0'\
-H 'Linkedin-Version:{version number in the format YYYYMM}'\
--data '
{ 
 "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

ForecastMetrics Object

MediaPlanningForecastDatapoint Object

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