Create a Proposal Matrix Buy with the API

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

The Broadsign Direct 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 Proposal

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

Note: The Matrix Buy feature must be activated in your Broadsign Direct 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 Broadsign Direct customers who use an external planning tool and leverage the Broadsign Direct REST API to book their campaigns in a more efficient way.

The Matrix Buy offers the following benefits:

  • Allows Broadsign Direct 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 proposal item.
  • Minimizes the number of proposal items a user is required to create. You can create a single proposal 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 Broadsign Control to reduce the content scheduling overhead.

Matrix Buy Cloning

A Matrix Buy proposal item cannot be cloned.

Impact on Broadsign Control

Broadsign Direct will pass a saturation file marking appropriate saturation data for each screen selected in the Matrix Buy proposal 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 proposal item might underdeliver. It cannot be rebalanced elsewhere because of its fixed allocations. However, should a Takeover affecting a Matrix Buy proposal item subsequently be canceled, the affected Matrix Buy proposal items allocations will be reinstated.

To create a Matrix Buy proposal:

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

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 proposal 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 proposal, Hold or Book the proposal. 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 proposal 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 proposal 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 proposal item by calling this method.

Broadsign Direct 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 proposal 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 proposal item to be Held or Booked. If the Availability check is not passed, the proposal 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 proposal item can be Held or Booked. Otherwise, the initial result from Step 1 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.
  • Proposal 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/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 Proposal Item as proposal_id.

Response

To hold the proposal, 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 Proposal Item as proposal_id.

Response

To book the proposal, 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 proposal 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 proposal, call this method.

Use the proposal ID that you have created in Step 1 – Create a Matrix Buy Proposal 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 proposal for booking, call this method.

Use the proposal ID that you have created in Step 1 – Create a Matrix Buy Proposal 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 proposal 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 Proposal Item as proposal_id.

Response

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

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

For more information on proposal status values, see Proposal 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 proposal items depends on their current state.

  • Changes to Matrix Buy proposal items in Saved state can be updated via the API.
  • Changes to Matrix Buy proposal items in a Held state can be made by releasing the proposal item and updating it via the API.
  • Changes to Matrix Buy proposal items in a Submitted state require a cancellation and a new proposal 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 proposal item in 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 proposal items in a Held state can be made by releasing the proposal item, and then updating it as described in Step 5A – Change Saved Matrix Buy Proposal 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 proposal items in a Submitted state require to cancel the proposal items, and a create a new proposal item with the changes, as described in Step 1 – Create a Matrix Buy Proposal 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 Broadsign Direct under a new Type of Buy (ToB) called Matrix.

Live Status

Save Status

Matrix Buy proposal items cannot be cloned or amended in the Broadsign Direct user interface.

They can only be created and updated via the API.