Use the External Pricing API

This page describes how to compute pricing information by using a third-party integration.

External Pricing API

The external pricing API feature allows you to bypass the internal Broadsign Direct rate cards and manage pricing externally through your own pricing engine. This way, Broadsign Direct ingests pricing data from your external pricing engine, offering flexibility and control over the pricing strategy.

  • The external pricing API provides a CPM override to the proposal item.
  • The CPM override reflects the externally managed pricing and appears in the CPM Overwrite field on the Digital Inventory Page.

Note: The CPM will only be updated if you modify anything on the proposal item, which ensures that pricing remains stable unless you make any edits.

You can set the URL and API key of your external pricing API endpoint in the Domain settings. See Pricing API.

Note: Domain settings are available only to users assigned the Admin role. For more information, see User Privileges by Role.

To configure the external pricing API endpoint:

  1. In the Domain Settings section, click Digital Inventory.

  2. In the Pricing API part, enter the URL for the external pricing endpoint and your API Authentication key.

To use the External Pricing API in Broadsign Direct and perform final calculations for different types of buy, follow these steps:

To use the External Pricing API:

  1. Go to the Digital Inventory Page.
  2. Choose the screens and configure ad settings such as type of buy, ad length, and duration as usual.
  3. Provide one of the following pricing values based on the type of buy.
    • The Price for the following types of buy:
      • Frequency
      • Share of Voice
      • Takeover
    • The CPM for the following types of buy:
      • Impression
      • Budget
      • Plays

With the Price or CPM value, Broadsign Direct can communicate with the External Pricing API. The API will fetch and update the pricing information dynamically based on the specified type of buy.

Broadsign Direct performs the final calculation using the pricing information received from the External Pricing API.

The calculated values are then used to complete the setup of the proposal item, ensuring accurate and dynamic pricing for the specified type of buy.

Broadsign Direct calculates the line item summary based on the values received by the pricing engine and displays them on the UI:

For:

  • Frequency
  • Share of Voice
  • Takeover

For:

  • Impressions
  • Budget
  • Plays

Note: If the Pricing API does not return a value, the Overwrite box is activated so that you can enter the desired price/CPM manually. See CPM Overwrite.

You can also override the cost of the line item. In this case, Broadsign Direct will consider the override value for final price calculation.

The following describes how the External Pricing API works.

Broadsign Direct sends all the selection details to the external pricing engine with the following API call:

Copy 
POST https://direct.broadsign.com/api/v1/third_party/pricing

The following is a sample payload:

Copy 
{
"schedule":
{
"start_date":"2023-12-19",
"end_date":"2024-01-01",
"start_time":"00:00:00",
"end_time":"23:59:59",
"dow_mask":127,
"slot_duration":15
},
"screens":[224016,224020],
"filters":[],
"buy_mode":
{
"type":"ppl",
"values":{"bs_saturation":1,"saturation":1,"custom_cpm":0},
"active":true
}
}

The following is a sample response for the following types of buy:

  • Frequency
  • Share of Voice
  • Takeover
Copy 
{
"override_type": "price",  #override type is price for these type of buys, Direct will expect a price value
"value": 450.0             #final value of price returned
}

The following is a sample response for the following types of buy:

  • Impression
  • Budget
  • Plays
Copy 
{
"value": 10.0,            #final value of CPM returned
"override_type": "cpm"    #override type is CPM for these type of buys, Direct will expect a CPM value
}

You can call the pricing engine to extract the recent values sent by the external pricing engine with the following API:

Copy 
GET /api/v1/third_party/pricing/logs/proposal_item/<proposal_item_id>

The following is a sample response to that call:

Copy 
   "id":12345,
   "override_type": "cpm",
   "value":10.0,
   "arbitrary_additional_info":
{
      "screens":[
         {
            "id":"1",
            "Cpm":15.0 // CPM for screen 1
         },
         {
            "id":"2",
            "Cpm": 2.0  // CPM for screen 2
         }
      ]

Broadsign Direct will cache the response of any upstream API call made for a duration of 20 minutes.

You can clear your cache at any time by using the following endpoint:

Copy 
POST api/v1/pricing/cache_clear