Create a Campaign Matrix Buy with the API

This example illustrates how to create a Matrix Buy campaign by using the Guaranteed Campaigns REST API. It shows the complete set of operations required to create a line item, validate the booking requests, check the availability, and update Matrix Buy line items. This example also shows how to identify Matrix Buy line items in the Guaranteed Campaigns user interface.

The Guaranteed Campaigns REST API endpoints and parameters are described in the REST Method Reference.

Note: The ID#s we use in these samples are for illustration purposes. They are invalid. Be sure to use your own ID#s for your integrations.

Note: All request body examples in this document are raw JSONs.

Matrix Buy Campaign

Guaranteed Campaigns

Tip: The Matrix Buy can only be created and updated via the Guaranteed Campaigns REST API.

Note: The Matrix Buy feature must be activated in your Guaranteed Campaigns domain. Contact Broadsign Services to activate the feature.

The Matrix Buy is used for booking campaigns involving fixed multi-targeted (e.g. time of day, day of week, set of screens) schedules within a day or across several days, with minimum workflows. It can be used by Guaranteed Campaigns customers who use an external planning tool and leverage the Guaranteed Campaigns REST API to book their campaigns in a more efficient way.

The Matrix Buy offers the following benefits:

  • Allows Guaranteed Campaigns REST API users to implement advanced campaign targeting strategies instructions coming from external planning tools and including booking screens or sets of screens with multiple non-contiguous schedules as one line item.
  • Minimizes the number of line items a user is required to create. You can create a single line item involving multiple and/or non-contiguous schedules, which in the past required users to create multiple line items to achieve.
  • Minimizes the resulting number of campaigns in the Content and Network Management solution to reduce the content scheduling overhead.

Matrix Buy Cloning

A Matrix Buy line item cannot be cloned.

Impact on Content and Network Management

The Guaranteed Campaigns module will pass a saturation file marking appropriate saturation data for each screen selected in the Matrix Buy line item.

The existing external saturation file format will not be affected.

Takeovers

Takeovers will be prioritized to be played in the usual manner, meaning that a Matrix Buy line item might under-deliver. It cannot be rebalanced elsewhere because of its fixed allocations. However, should a Takeover affecting a Matrix Buy line item subsequently be canceled, the affected Matrix Buy line items allocations will be reinstated.

To create a Matrix Buy campaign:

Guaranteed Campaigns

You will need to use the following methods to create a Matrix Buy campaign.

Note: You will need the ID#s from the responses as values for parameters in the next steps in sequence.

  1. Create a Matrix Buy line item. Use the /api/v1/proposal/proposal_items POST method.
  2. Check the availability of the screens that you have selected. Use one of the following methods:
    • hold: /api/v1/proposal/{proposal_id}/availability?type=[hold] GET method.
    • book: /api/v1/proposal/{proposal_id}/availability?type=[book] GET method.
  3. Using the ID# of your new campaign, Hold or Book the campaign. Use one of the following methods:
    • hold: /api/v1/proposal/{proposal_id}/hold PUT method
    • book: /api/v1/proposal/book_proposal/{proposal_id} POST method
  4. Ensure that the campaign has been actually put on hold or submitted for booking. Use the /api/v1/proposal/{proposal_id} GET method.
  5. Update, amend and cancel Matrix Buy line items. Use the /api/v1/proposal/proposal_item/{proposal_item_id} PUT method.

Request Method: POST

Request URL: https://direct.broadsign.com/api/v1/proposal/proposal_items

Documentation: Swagger /api/v1/proposal/proposal_items

Create a Matrix Buy line item by calling this method.

The Guaranteed Campaigns module accepts and stores booking requests from an external planning tool, through an API endpoint. Booking request must contain:

  • Start and End date of each segment of the booking request.
  • Start and End time of each segment of the booking request.
  • Target Screen_ids.
  • Booking requests must be sent in a valid JSON format.

For example:

Schedule Start Date End Date Start Time End Time Frame/Screen ID
1 2023-01-01 2023-01-01 13:00:00 14:59:58 167781
2 2023-01-01 2023-01-01 16:00:00 17:59:58 167782

Request

Copy 
 {
  "proposal_id": 623387,
  "line_items": [
 {
  "name": "Matrix PLI",
  "reference_id": "123321",
  "slot_duration": "5.0",
  "buy_mode": {
  "type": "matrix",
  "values":
 {
 "saturation": 1
 }
 },
  "price": 1,
  "priority": 1,
  "matrix": [{
  "start_date": "2023-06-30",
  "end_date": "2023-07-05",
  "start_time": "8:00:00",
  "end_time": "9:00:00",
  "screen_ids": [220710]
 }
 ]
}
 ]
 }

Response

Copy 
{
   "proposal_id": 623387,
   "line_items": [
       {
           "reference_id": "123321",
           "id": 926096
       }
   ]
}

The following response codes are possible:

  • If the payload is valid:

    • 201 - {"schedule/matrix created successfully"}

  • if the payload is not valid:

    • 40x, {"problematic_schedules": []}

    or

    40x, {"proposal item doesn't exist"}

You must always check the availability of the screens before holding the campaign or submitting it for booking.

The availability check takes into account Reallocation and Rebalancing.

  • Availability check is done in the following two steps:
    1. Availability check, if passed, will allow the line item to be Held or Booked. If the Availability check is not passed, the line item will be sent to Rebalancing for further calculations.
    2. If Rebalancing is required and able to solve the availability check problem, it will return the result and the line item can be Held or Booked. Otherwise, the initial result from Step 1 – Create a Matrix Buy Line Item will be published.
  • Bookings made with the Matrix Buy will handle Reallocation as usual. The existing Held, Booked, Submitted and Live campaigns will be reallocated to make room for inbound booking requests, as long as there is space available to move.
  • Campaigns booked with the Matrix Buy cannot be rebalanced, as they are booked with a fixed and immovable schedule.
  • Bookings that pass the Availability check will be able to be held or submitted.
  • For booking requests that do not pass the Availability check, the API will send back the list of unavailable screen IDs, dates and times.
  • Line items that do not pass the Availability check will remain in a Saved state unless they are updated (via API only) or removed via the API or UI.

Request Method: GET

Request URL: https://direct.broadsign.com/api/v1/proposal/{proposal_id}/availability?type=hold

Documentation: Swagger /api/v1/proposal/{proposal_id}/availability

Check the availability of the screens that you have selected by calling this method.

Use the proposal ID that you have created in Step 1 – Create a Matrix Buy Line Item as proposal_id.

Response

To hold the campaign, the availability parameter must be "available".

Copy 
 {
    "proposal_id": 623387,
    "proposal_name": "Broadsign Proposal",
    "availability": "available",
    "goals": [],
    "proposal_items": [
       {
           "proposal_item_id": 926096,
           "proposal_item_name": "Matrix PLI",
           "availability": "available",
           "inventory_type": "digital",
           "is_package": false,
           "screens": {
               "available": {
                   "screen_ids": [
                       220710
                   ],
                   "messages": [],
                   "group_count": 0,
                   "screen_count": 1
               }
           },
           "messages": [],
           "proposal_item_reference_id": "123321"
       }
   ],
   "requested_group_count": 0,
   "bookable_group_count": 0,
   "requested_screen_count": 1,
   "bookable_screen_count": 1
 }

Request Method: GET

Request URL: https://direct.broadsign.com/api/v1/proposal/{proposal_id}/availability?type=book

Documentation: Swagger /api/v1/proposal/{proposal_id}/availability

Check the availability of the screens that you have selected by calling this method.

Use the proposal ID that you have created in Step 1 – Create a Matrix Buy Line Item as proposal_id.

Response

To book the campaign, the availability parameter must be "available".

Copy 
 {
   "proposal_id": 623387,
   "proposal_name": "Broadsign Proposal",
   "availability": "available",
   "goals": [],
   "proposal_items": [
       {
           "proposal_item_id": 926096,
           "proposal_item_name": "Matrix PLI",
           "availability": "available",
           "inventory_type": "digital",
           "is_package": false,
           "screens": {
               "available": {
                   "screen_ids": [
                       220710
                   ],
                   "messages": [],
                   "group_count": 0,
                   "screen_count": 1
               }
           },
           "messages": [],
           "proposal_item_reference_id": "123321"
       }
   ],
   "requested_group_count": 0,
   "bookable_group_count": 0,
   "requested_screen_count": 1,
   "bookable_screen_count": 1
 }

You can now hold the campaign or submit it for booking.

Request Method: PUT

Request URL: https://direct.broadsign.com/api/v1/proposal/{proposal_id}/hold

Documentation: Swagger /api/v1/proposal/{proposal_id}/hold

If you want to hold the campaign, call this method.

Use the proposal ID that you have created in Step 1 – Create a Matrix Buy Line Item as proposal_id.

Response

Copy 
{
   "id": 623387,
   "creation_tm": "2023-06-19 19:37:17",
   "modification_tm": "2023-06-19 21:51:05",
   "active": true,
   "domain_id": 53,
   "name": "Broadsign Proposal",
   "description": "This is a test proposal",
   "price": 0.0,
   "discount": 0.0,
   "status": 1,
   "client_id": "Client ID 1234",
   "client_name": "Doe Company",
   "client_address": "Montreal, Canada",
   "contact_name": "John Doe",
   "contact_phone": "1-888-000-0000",
   "contact_email": "john@doe.com",
   "start_date": "2023-06-30",
   "earliest_start_datetime_in_utc": "2023-06-30 12:00:00",
   "latest_end_datetime_in_utc": "2023-07-05 13:00:00",
   "picture": "",
   "contract_id": "ABC-1234",
   "contract_number": "ABC-1234",
   "hold_expiry_tm": "2023-06-28 21:51:05",
   "locks": {
       "book": false,
       "edit": false,
       "hold": false,
       "sync": false,
       "delete": false,
       "download": false,
       "sync_button": false,
       "contact_edit": false
   },
   "custom_data": {},
   "owner_user_id": 3186,
   "hold_requested": false,
   "hold_tm": "2023-06-19 21:51:05",
   "creation_user_id": 3186,
   "modification_user_id": 3186,
   "creation_date_time": "2023-06-19 19:37:17",
   "last_modification_date_time": "2023-06-19 21:51:05",
   "owner_user_name": "Sarah",
   "creation_user_name": "Sarah",
   "suggested_price": 1.0,
   "end_date": "2023-07-05",
   "proposal_item_id_list": [
       926096
   ],
   "category_ids": [],
   "is_cloneable": false
}

Request Method: POST

Request URL: https://direct.broadsign.com/api/v1/proposal/book_proposal/{proposal_id}

Documentation: Swagger /api/v1/proposal/book_proposal/{proposal_id}

If you want to submit a campaign for booking, call this method.

Use the proposal ID that you have created in Step 1 – Create a Matrix Buy Line Item as proposal_id.

Response

The following response codes are possible:

  • If the payload is valid:

    • 200 - {"success"}

  • if the payload is not valid:

    • 40x, {"problematic_schedules": []}

    or

    40x, {"proposal item doesn't exist"}

Request Method: GET

Request URL: https://direct.broadsign.com/api/v1/proposal/{proposal_id}

Documentation: Swagger /api/v1/proposal/{proposal_id}

This step is important, as it ensures that the campaign has been actually put on hold or submitted for booking.

Use the proposal ID that you have created in Step 1 – Create a Matrix Buy Line Item as proposal_id.

Response

For a held campaign, the status parameter should be "4".

For a campaign submitted for booking, the status parameter should be "10".

For more information on campaign status values, see Campaign Status Values for the REST API.

Copy 
{
   "id": 623387,
   "creation_tm": "2023-06-19 21:58:28",
   "modification_tm": "2023-06-19 21:59:40",
   "active": true,
   "domain_id": 53,
   "name": "Broadsign Proposal",
   "description": "This is a test proposal",
   "price": 0.0,
   "discount": 0.0,
   "status": 10,
   "client_id": "Client ID 1234",
   "client_name": "Doe Company",
   "client_address": "Montreal, Canada",
   "contact_name": "John Doe",
   "contact_phone": "1-888-000-0000",
   "contact_email": "john@doe.com",
   "start_date": "2023-06-30",
   "earliest_start_datetime_in_utc": "2023-06-30 12:00:00",
   "latest_end_datetime_in_utc": "2023-07-05 13:00:00",
   "picture": "",
   "contract_id": "ABC-1234",
   "contract_number": "ABC-1234",
   "hold_expiry_tm": null,
   "locks": {
       "book": false,
       "hold": false,
       "contact_edit": false,
       "download": false,
       "sync": false,
       "delete": false,
       "edit": false,
       "sync_button": false
   },
   "custom_data": {},
   "owner_user_id": 3186,
   "hold_requested": false,
   "hold_tm": null,
   "creation_user_id": 3186,
   "modification_user_id": 3186,
   "creation_date_time": "2023-06-19 21:58:28",
   "last_modification_date_time": "2023-06-19 21:59:40",
   "owner_user_name": "Sarah",
   "creation_user_name": "Sarah",
   "suggested_price": 1.0,
   "end_date": "2023-07-05",
   "proposal_item_id_list": [
       926106
   ],
   "category_ids": [],
   "is_cloneable": false
}

Making changes to Matrix Buy line items depends on their current state.

  • Changes to Matrix Buy line items in a Saved state can be updated via the API.
  • Changes to Matrix Buy line items in a Held state can be made by releasing the line item and updating it via the API.
  • Changes to Matrix Buy line items in a Submitted state require a cancellation and a new line item request to be made via the API.

Request Method: PUT

Request URL: https://direct.broadsign.com/api/v1/proposal/proposal_item/{proposal_item_id}

Documentation: Swagger /api/v1/proposal/proposal_item/{proposal_item_id}

You can update a line item in a Saved state.

Response

Copy 
{
   "id": 926154,
   "creation_tm": "2023-06-19 22:40:19",
   "modification_tm": "2023-06-19 23:34:33",
   "active": true,
   "active_type": "matrix",
   "actual_impressions": null,
   "actual_repetitions": null,
   "name": "Matrix PLI",
   "price": 1,
   "custom_price": null,
   "proposal_id": 623446,
   "package_id": null,
   "flight_duration": 1,
   "flight_type": 0,
   "slot_duration": 5.0,
   "saturation": 1.0,
   "suggested_price": "0",
   "status": 1,
   "start_date": "2023-06-30",
   "end_date": "2023-07-05",
   "start_time": "08:00:00",
   "end_time": "10:00:00",
   "earliest_start_datetime_in_utc": "2023-06-30 12:00:00",
   "latest_end_datetime_in_utc": "2023-07-05 14:00:00",
   "dow_mask": 127,
   "provider_id": null,
   "external_id": null,
   "multiplier": 6,
   "filters": [],
   "mode": [
       {
           "type": "matrix",
           "active": true,
           "values": {
               "saturation": 1.0
           }
       }
   ],
   "inventory_type": "digital",
   "day_masks": {
       "1560824": null
   },
   "priority": 1,
   "performance_update_tm": null,
   "last_auto_rebalance_tm": null,
   "synchronized": false,
   "is_processing": false,
   "is_preemptible": null,
   "booking_tm": null,
   "is_name_templatized": false,
   "expected": null,
   "projected": 0,
   "target": 0,
   "proposal_goal_id": null,
   "reference_id": "1234562",
   "cpm": 0.0,
   "custom_cpm": 0.0,
   "saturation_freeze_tm": null,
   "creation_user_id": 3186,
   "modification_user_id": 3186,
   "group_count": 1,
   "screen_count": 3,
   "screens": [
       204114,
       220710
   ],
   "dynamic_screen_selection": null
}

Request Method: DELETE

Request URL: https://direct.broadsign.com/api/v1/proposal/proposal_item/{proposal_item_id}/hold

Documentation: Swagger /api/v1/proposal/proposal_item/{proposal_item_id}/hold

Changes to Matrix Buy line items in a Held state can be made by releasing the line item, and then updating it as described in Step 5A – Change Saved Matrix Buy Line Items.

Response

Copy 
{
   "id": 623387,
   "creation_tm": "2023-06-19 22:40:19",
   "modification_tm": "2023-06-19 22:43:08",
   "active": true,
   "active_type": "matrix",
   "actual_impressions": null,
   "actual_repetitions": null,
   "name": "Matrix PLI",
   "price": 1,
   "custom_price": null,
   "proposal_id": 623446,
   "package_id": null,
   "flight_duration": 1,
   "flight_type": 0,
   "slot_duration": 5.0,
   "saturation": 1.0,
   "suggested_price": "0",
   "status": 1,
   "start_date": "2023-06-30",
   "end_date": "2023-07-05",
   "start_time": "08:00:00",
   "end_time": "09:00:00",
   "earliest_start_datetime_in_utc": "2023-06-30 12:00:00",
   "latest_end_datetime_in_utc": "2023-07-05 13:00:00",
   "dow_mask": 127,
   "provider_id": null,
   "external_id": null,
   "multiplier": 6,
   "filters": [],
   "mode": [
       {
           "type": "ppl",
           "active": false,
           "values": {
               "bs_saturation": null,
               "saturation": null
           }
       },
       {
           "type": "sov",
           "active": false,
           "values": {
               "sov": 15.0
           }
       },
       {
           "type": "takeover",
           "active": false,
           "values": {
               "sov": 100.0
           }
       },
       {
           "type": "goal_impressions",
           "active": false,
           "values": {
               "impressions": null,
               "cpm": null,
               "budget": null
           }
       },
       {
           "type": "goal_budget",
           "active": false,
           "values": {
               "impressions": null,
               "cpm": null,
               "budget": null
           }
       },
       {
           "type": "goal_repetitions",
           "values": {
               "repetitions": null
           },
           "active": false
       },
       {
           "type": "average_sov",
           "active": false,
           "values": {
               "sov": 15.0,
               "distribution": "screen_day"
           }
       },
       {
           "type": "matrix",
           "active": true,
           "values": {
               "saturation": 1.0,
               "expected_repetitions": 360,
               "expected_impressions": 0
           }
       }
   ],
   "inventory_type": "digital",
   "day_masks": {
       "1560824": null
   },
   "priority": 1,
   "performance_update_tm": null,
   "last_auto_rebalance_tm": null,
   "synchronized": false,
   "is_processing": false,
   "is_preemptible": null,
   "booking_tm": null,
   "is_name_templatized": false,
   "expected": null,
   "projected": 0,
   "target": 0,
   "proposal_goal_id": null,
   "reference_id": "123321",
   "cpm": null,
   "custom_cpm": 0.0,
   "saturation_freeze_tm": null,
   "creation_user_id": 3186,
   "modification_user_id": 3186,
   "group_count": 0,
   "screen_count": 1,
   "dynamic_screen_selection": null
}

Request Method: POST

Request URL: https://direct.broadsign.com/api/v1/proposal/proposal_item/{proposal_item_id}/cancel

Documentation: Swagger /api/v1/proposal/proposal_item/{proposal_item_id}/cancel

Changes to Matrix Buy line items in a Submitted state require to cancel the line items, and a create a new line item with the changes, as described in Step 1 – Create a Matrix Buy Line Item.

Response

The following response codes are possible:

  • If the payload is valid:

    • 200 - {"success"}

  • if the payload is not valid:

    • 40x, {"PROPOSAL_NOT_FOUND": []}

The bookings are created in the Guaranteed Campaigns module under a new Type of Buy (ToB) called Matrix.

Live Status

Saved Status

Matrix Buy line items cannot be cloned or amended in the Guaranteed Campaigns user interface.

They can only be created and updated via the API.