Partager via

Manage Media Plans

  • Article

Warning

Deprecation Notice
The Marketing Version 202311 (Marketing November 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.

Try in Postman

Overview

Media Planners can utilize the /mediaPlan API to save and retrieve media plans within an advertising account, allowing them to reference previously created media plans.

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

Permission Description
rw_media_plans Manage an authenticated member's Media Plans. Can manage and read Media Plans. This permission belongs to the Media Planning API program and is not granted automatically as part of the LinkedIn Marketing API Program.

Schema

Field Type Description Required
mediaPlanUrn URN The URN of the media plan. read-only Yes
name string The name of the media plan. Yes
createdAt timestamp The timestamp when the media plan was created. read-only Yes
creator URN The URN of the creator of the media plan. read-only Yes
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. 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 from 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)
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)
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. read-only Optional
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. read-only Optional
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. read-only Optional
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. read-only Optional
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. read-only Optional

Forecast Metric Type

Forecast metrics type is an enum that specifies the type of forecast metrics to include when creating a media plan. The following forecast metric types are supported:

Forecast Metric Type Description
REACH This metric describes the forecasted amount of unique members that will see the ad. Media plan will be created with reach and reach percentage curve.
IMPRESSION This metric describes the forecasted number of impressions on the ad. Media plan will be created with impression and average frequency curve.
LEAD This metric describes the forecasted number of leads generated from the campaign. Media Plan will be created with lead curve.

Create a Media Plan

Create a media plan to retrieve and refer later. Types of curves included in media plan depends on ForecastMetricType.

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

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.

This sample request creates media plan with Impression and Average Frequency curve.

POST https://api.linkedin.com/rest/mediaPlans?forecastMetricType=REACH

{
  "name": "TEST_MEDIA_PLAN",
  "createdAt": 1716526432,
  "creator": "urn:li:member:9876",
  "sponsoredAccountUrn": "urn:li:sponsoredAccount:2",
  "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"
            ]
          }
        }
      ]
    }
  },
  "currencyCode": "USD",
  "objectiveType": "BRAND_AWARENESS",
  "optimizationType": "MAX_REACH",
  "startDate": "05-24-2024",
  "endDate": "07-24-2024",
  "targetBudgetMicros": 200,
  "enableAudienceNetwork": true,
  "enableAudienceExpansion": true,
  "ctvOnly": false
}

Get a Media Plan by ID

Retrieve a media plan with specific URN.

Search Parameters

Field Name Required Description
accountUrn yes Ad account urn in which the media plan is saved

Sample Request

GET https://api.linkedin.com/rest/mediaPlans/urn%3Ali%3AmediaPlan%3A4f1dc5d9-3ed2-41d6-8c7c-2aa4c46756a6?accountUrn=urn%3Ali%3AsponsoredAccount%3A1234567

Finder To Get All Media Plans For An Account

Retrieve all media plans saved for specific account.

Search Parameters

Field Name Required Description
accountUrn yes Ad account urn in which the media plan is saved

Sample Request

GET https://api.linkedin.com/rest/mediaPlans?q=getAllMediaPlans&accountUrn=urn%3Ali%3AsponsoredAccount%3A1234567

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 Plan API.
404 NOT_FOUND Media plan not found while getting media plan by ID Make sure media plan urn provided is correct.
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 INTERNAL_SERVER_ERROR Internal server side error N/A