Create and Manage Programmatic Line Items

Greta
Greta
  • Updated

Create Programmatic Line Items With API

A line item is an element of a campaign, grouped under an order. It has all the ad delivery details that a publisher needs to show your ad in a defined context. With programmatic line items, you can buy ad impressions programmatically through Supply-Side Platforms (SSPs) and ad exchanges in real time. Line items give flexibility for advertisers to test, optimize, and manage distinct segments of a campaign independently, making it easier to tailor strategies to different audiences or placements.

Tip

For more information about programmatic line items, see Create Programmatic Line Items and General Programmatic Line Item Settings.

After you've created a campaign and order, you need to create a line item to define your ad delivery settings, such as budget allocation, buying strategy, and targeting criteria.

With Line Items section of RTB Line Items Setup API, you can create, update, pause, and delete programmatic line items. You can also search for specific line items by their ID, and retrieve information about them. To define targeting criteria for the line item, you need to use other APIs to retrieve specific targeting settings and then assign them to the programmatic line item.

Authentication

To authenticate and use Adform APIs, your user account must have the necessary permissions and your OAuth client must have the required scopes assigned to it.

To create a line item, Adform DSP and Ad Server user account must have these permissions assigned by the business account admin:

  • Manage Campaigns & Orders

  • Manage Programmatic Line Items

Depending on your objectives and workflow, you'll need some or all of the following scopes assigned to your OAuth client by Adform Support (technical@adform.com):

  • https://api.adform.com/scope/buyer.rtb.lineitem: Grants access to RTB Line Items Setup API.

  • https://api.adform.com/scope/buyer.marketplace.inventories.readonly: Grants access to Inventory Marketplace API.

  • https://api.adform.com/scope/market.stats: Grants access to Inventory Marketplace Stats API.

  • https://api.adform.com/scope/buyer.rtb.targetinglists: Grants access to RTB Targeting Lists API.

  • https://api.adform.com/scope/integrations.classifiers.readonly: Grants access to Classifiers API.

  • https://api.adform.com/scope/buyer.campaigns.api.readonly: Grants access to Campaigns API.

  • https://api.adform.com/scope/dmp.segments.readonly: Grants access to the Segments section of the Data Management Platform API.

Tip

If you don't have an OAuth client yet, follow the procedure in Get Authentication Credentials for Adform APIs to register one.

Prerequisites

To create a programmatic line item with API, use the following IDs in your requests:

ID

Used To

Retrieve From

orderId

Specify the order to which the line item belongs

Orders v2 API

templateId

Specify the domain template to assign it to the line item

Templates API

lineItemId

Specify the line item to assign targeting settings

Provided as part of response body after creating a line item (see step 6 in Workflow)

Note

Additional IDs might be used, but the listed ones are required to pass a request.

Workflow

After you've created an advertiser, campaign, and order, you can continue with creating a line item.

Tip

To learn how to use Adform APIs, read Guide to Using Adform APIs.

To create a programmatic line item with API, use these endpoints:

  1. POST endpoints in Inventory Marketplace API: To create lists of ad exchanges, deals, deal groups, apps, and domains for inventory targeting setup.

    Tip

    You can use Inventory Marketplace Stats API to retrieve information about performance KPIs of the selected inventory sources, deals, websites, and apps.

  2. (Optional) GET endpoint in Domains section of Templates API: To retrieve the created domain template ID for inventory targeting setup.

  3. (Optional) GET endpoints in Segments section of Data Management Platform API: To retrieve lists of audience IDs for audience targeting setup.

  4. (Optional) POST endpoint of the DeviceAndCookieIdLists section of RTB Line Items Setup v3 API: To upload a list of device and cookie IDs for technical targeting setup.

  5. (Optional) POST endpoint of the IpRangeLists section of RTB Line Items Setup v3 API: To upload a list of IP ranges for technical targeting setup.

  6. (Optional) GET endpoints in Classifiers API: To retrieve criteria for technology and geography targeting setups.

  7. (Optional) GET endpoints in AdsOverview section in Standard Banners API: If you already have ads created, use these endpoints to retrieve a list of ads to assign to your line item.

  8. POST endpoint of LineItems section of RTB Line Items Setup v3 API: To create a line item with general settings and assign inventory, audience, technical, and geography targeting lists and criteria.

After you've created a line item, you can continue with creating ads.

Endpoints

[{"api":"Data Management Platform","titles":"Segment"},

{"api":"Classifier","titles":"Bandwidths, Cities, Continents, Countries, DeviceProperties, DmaRegions, IabCategories, IpLocations, Isps, Languages, Locales, Locations, MobileCarriers, Regions, ZipCodes"}]

Use Forecasting for Programmatic Line Items With API

When you create a programmatic line item, you can use forecasting tools to evaluate its effectiveness. Forecasting shows how many impressions and cookies are available based on your current programmatic line item setup, assuming that the line item bids on every request. Overview of past traffic gives you access to historical information about the ad traffic for specific inventories.

You can use both forecasting and past traffic tools to examine the expected performance of your programmatic line item and adjust its settings to better reach your goals.

Tip

For more information about forecasting capabilities for programmatic line items, see Learn About Forecasting and Bid Landscape.

With RTB Line Items v2 Forecasting API, you can get the following information about your programmatic line item:

  • Forecasting: Retrieve the estimated number of impressions and cookies available based on current line item settings. You can group this data by audience, geography, device, or by specific websites, apps, inventory sources, or deals.

  • Past Traffic: Retrieve historical number of impressions and cookies that were available for a specific line item.

Authentication

To authenticate and use Adform APIs, your user account must have the necessary permissions and your OAuth client must have the required scopes assigned to it.

To use forecasting for your programmatic line item, Adform DSP and Ad Server user account must have these permissions assigned by the business account admin:

  • Manage Campaigns & Orders

  • Manage Programmatic Line Items

Depending on your objectives and workflow, you'll need some or all of the following scopes assigned to your OAuth client by Adform Support (technical@adform.com):

  • https://api.adform.com/scope/buyer.rtb.lineitem: Grants access to RTB Line Items Setup API.

  • https://api.adform.com/scope/buyer.marketplace.inventories.readonly: Grants access to Inventory Marketplace API.

  • https://api.adform.com/scope/buyer.rtb.targetinglists: Grants access to RTB Targeting Lists API.

  • https://api.adform.com/scope/integrations.classifiers.readonly: Grants access to Classifiers API.

  • https://api.adform.com/scope/buyer.campaigns.api.readonly: Grants access to Campaigns API.

  • https://api.adform.com/scope/dmp.segments.readonly: Grants access to the Segments section of the Data Management Platform API.

Tip

If you don't have an OAuth client yet, follow the procedure in Get Authentication Credentials for Adform APIs to register one.

Prerequisites

To use forecasting for a programmatic line item with API, use the following IDs in your requests:

ID

Used To

Retrieve From

orderId

Specify the order to which the line item that you want to use forecasting for belongs

Orders v2 API

Note

Additional IDs might be used, but the listed ones are required to pass a request.

Workflow

To evaluate the effectiveness of your programmatic line item, we recommend using Adform forecasting tools before creating the line item.

Tip

To learn how to use Adform APIs, read Guide to Using Adform APIs.

To get forecasting data for your programmatic line item with API, use these endpoints:

  1. POST endpoints in Inventory Marketplace API: To create lists of ad exchanges, deals, apps, and domains for inventory targeting setup.

  2. (Optional) GET endpoints in Segments section of Data Management Platform API: To retrieve lists of audience IDs for audience targeting setup.

  3. (Optional) POST endpoint of the DeviceAndCookieIdLists section of RTB Line Items Setup v3 API: To upload a list of device and cookie IDs for technical targeting setup.

  4. (Optional) POST endpoint of the IpRangeLists section of RTB Line Items Setup v3 API: To upload a list of IP ranges for technical targeting setup.

  5. (Optional) GET endpoints in Classifiers API: To retrieve criteria for technology and geography targeting setups.

  6. (Optional) GET endpoints in AdsOverview section in Standard Banners API: If you already have ads created, use these endpoints to retrieve a list of ads to assign to your line item.

  7. POST endpoints in the RTB Line Items v2 Forecasting API of RTB Line Items Setup v3 API: To enter all programmatic line item settings and retrieve the forecasting information for it.

Once you've checked the forecasting for the line item, you can reuse the setup to create the programmatic line item.

Endpoints

[{"api":"Data Management Platform","titles":"Segment"},

{"api":"Classifier","titles":"Bandwidths, Cities, Continents, Countries, DeviceProperties, DmaRegions, IabCategories, IpLocations, Isps, Languages, Locales, Locations, MobileCarriers, Regions, ZipCodes"}]

Optimize Programmatic Line Item Settings With API

When you run active programmatic campaigns, you can optimize programmatic line item settings to better reach your campaign goals. You can optimize the settings manually or apply recommendations provided by Adform IQ. Adform IQ analyzes your campaign performance data, including KPIs, delivery, remaining flight time, and inventory trends. It then recommends optimization strategies for your programmatic line item settings, specifically for targeting websites and apps, deals, inventory sources, or schedule time slots. It also predicts the potential impact of these changes and forecasts KPI performance if the recommendations are applied.

Tip

For more information about optimizing programmatic line items, see  Optimize Programmatic Line Item Settings and Guide to Programmatic Line Item Optimization.

After you've created a campaign, order, and programmatic line item, you can adjust and optimize line item settings to improve delivery, performance, and efficiency. Optimization becomes available when KPIs are defined, the selected buying strategy aligns with those KPIs, and the line item has collected enough delivery data during its flight.

With the RTB Line Item Recommendations API, you can generate, view, and apply optimization recommendations suggested by Adform IQ or manually optimize your line item settings for targeting websites and apps, deals, inventory sources, and schedule time slots.

With the Recommendation Preferences - Line Items API, you can mark recommendations as ignored to prevent them from appearing again.

Authentication

To authenticate and use Adform APIs, your user account must have the necessary permissions and your OAuth client must have the required scopes assigned to it.

To optimize programmatic line item settings, Adform DSP and Ad Server user account must have these permissions assigned by the business account admin:

  • Manage Campaigns & Orders

  • Manage Programmatic Line Items

Depending on your objectives and workflow, you'll need some or all of the following scopes assigned to your OAuth client by Adform Support (technical@adform.com):

  • https://api.adform.com/scope/buyer.rtb.lineitems.recommendations: Grants access to RTB Line Item Recommendations API.

  • https://api.adform.com/scope/buyer.recommendation.preferences: Grants access to Recommendation Preferences - Line Items API.

Tip

If you don't have an OAuth client yet, follow the procedure in Get Authentication Credentials for Adform APIs to register one.

Prerequisites

To use line item optimization recommendations APIs, use the following IDs in your requests:

ID

Used To

Retrieve From

lineItemId

Specify the line item for which to retrieve available recommendations, generate recommendations manually, or apply recommendations

RTB Line Items Setup API

recommendationId

Specify the recommendation to apply to a line item or to ignore for the user

Provided as part of response body after generating or retrieving recommendations (see steps 1 - 3 in Workflow)

jobId

Specify the applied recommendation job to check its status

Provided as part of response body after applying recommendations (see step 4 in Workflow)

Note

Additional IDs might be used, but the listed ones are required to pass a request.

Workflow

Adform IQ starts generating recommendations one day after a programmatic line item's budget flight begins. New recommendations are generated every three days, or one day after you update the line item's settings. This gives programmatic line items enough time to collect data for optimization strategies. Once recommendations become available, you can use them to optimize line item settings. 

Note

Adform IQ generates recommendations only if the programmatic line items have defined KPIs, buying strategy, and have gathered sufficient data during the budget flight. For more information, see Apply Optimization Strategies.

Tip

To learn how to use Adform APIs, read the Guide to Using Adform APIs.

To optimize programmatic line item settings with RTB Line Item Recommendations API, use these endpoints:

  1. POST Endpoint in RTB Line Item Recommendations API: To retrieve a list of all currently available recommendations for eligible line items across all active campaigns.

  2. GET Endpoint in RTB Line Item Recommendations API: To retrieve current recommendations and supply forecast for a single programmatic line item.

  3. POST Endpoint in RTB Line Item Recommendations API: To generate new recommendations manually for a specific line item.

  4. POST Endpoint in RTB Line Item Recommendations API: To apply recommendations.

  5. GET Endpoint in RTB Line Item Recommendations API: To retrieve the status of applied recommendation jobs.

To mark recommendations as ignored with Recommendation Preferences - Line Items API, use these endpoints:

  1. (Optional) POST Endpoint in Recommendation Preferences - Line Items API: To mark specific recommendations as ignored so they aren't shown again for the same user.

  2. (Optional) GET Endpoint in Recommendation Preferences - Line Items API: To retrieve the list of recommendations that have been marked as ignored by the user.

After you've applied recommendations to optimize programmatic line item performance, you can use reporting and forecasting to monitor the results.

Adform IQ
Adform IQ

Was this article helpful?

/
How can we make it better?

Thank you for your feedback!