Build a Proposal with the API

This example illustrates how to build a simple proposal by using the Broadsign Direct REST API. It shows the complete set of operations required to create a proposal, add proposal items, select screens, check the availability, and book or hold the proposal.

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.

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

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

  1. Create a proposal. Use the /api/v1/proposal POST method.
  2. (Optional) search for screens to put in your proposal. Use the /api/v1/screen/search POST method.
  3. Create a proposal item by adding screens to it. Use the /api/v1/proposal/add_screens POST method.
  4. 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.
  5. 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
  6. Ensure that the proposal has been actually put on hold or submitted for booking. Use the /api/v1/proposal/{proposal_id} GET method.

Request Method: POST

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

Documentation: Swagger /api/v1/proposal

Create a proposal by calling this method.

Request

Copy 
{
  "name": "Broadsign Proposal",
  "description": "This is a test proposal",
  "price": 0,
  "discount": 0,
  "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",
  "contract_id": "ABC-1234",
  "contract_number": "ABC-12345",
  "locks": {
    "book": false,
    "contact_edit": false,
    "sync_button": false,
    "hold": false,
    "sync": false,
    "download": false,
    "edit": false,
    "delete": false
  },
  "owner_user_name": "Sarah",
  "category_ids": [
    51
  ]
}

Response

Copy 
{
  "id": 12345,
  "creation_tm": "2022-01-13 15:43:13",
  "modification_tm": "2022-01-13 15:43:13",
  "active": true,
  "domain_id": 1,
  "name": "Broadsign Proposal",
  "description": "This is a test proposal",
  "price": 0,
  "discount": 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": "2022-01-13",
  "earliest_start_datetime_in_utc": "2022-01-13 15:43:13",
  "latest_end_datetime_in_utc": "2022-01-13 15:43:13",
  "picture": "",
  "contract_id": "ABC-1234",
  "contract_number": "ABC-1234",
  "hold_expiry_tm": null,
  "locks": {
    "book": false,
    "contact_edit": false,
    "sync_button": false,
    "hold": false,
    "sync": false,
    "download": false,
    "edit": false,
    "delete": false
  },
  "custom_data": {},
  "owner_user_id": 207,
  "hold_requested": false,
  "creation_user_id": 207,
  "modification_user_id": 207,
  "creation_date_time": "2022-01-13 15:43:13",
  "last_modification_date_time": "2022-01-13 15:43:13",
  "owner_user_name": "Sarah",
  "creation_user_name": "Sarah",
  "suggested_price": 0,
  "end_date": null,
  "proposal_item_id_list": [],
  "category_ids": [
    51
  ],
  "is_cloneable": true
}

Request Method: POST

Request URL: https://direct.broadsign.com/api/v1/screen/search

Documentation: Swagger /api/v1/screen/search

This step is optional. You can search for specific screens by calling this method.

Request

Copy 
{
  "$top": 100,
  "$skip": 0,
  "$sort": [
    {
      "field": "selection",
      "dir": "desc",
      "selected_screens": [],
      "type": "proposal"
    }
  ],
  "criteria": [
    8304
  ],
  "available_only": false,
  "deployed_only": false,
  "dow_mask": 127,
  "multiplier": 14,
  "end_date": "2022-02-14",
  "end_time": "23:59:59",
  "start_date": "2022-02-01",
  "start_time": "00:00:00",
  "inventory_type": "digital",
  "gender_age": [],
  "resolution": [],
  "orientation": [],
  "screen_format": [],
  "category_ids": [
    51
  ],
  "slot_duration": 10,
  "mode": [
    {
      "type": "ppl",
      "values": {
        "bs_saturation": 1,
        "saturation": 1
      },
      "active": true
    }
  ],
  "proposal_goal_id": null,
  "dynamic_screen_quantity": 1,
  "keywords": []
}

Response

Copy 
{
  "data": [
    {
      "id": 54016,
      "name": "JFK - Terminal 1 - Food Court",
      "address": "John F. Kennedy International Airport (JFK), Queens, NY 11430, USA",
      "resolution": "900x780",
      "orientation": "Landscape",
      "screen_format": null,
      "lat": 40.6413,
      "long": -73.778099,
      "fill_rate": 0,
      "rate_card_name": null,
      "has_fixed_slot_duration": true,
      "reference_id": null,
      "__row": 0,
      "audience_filter_impression": 277532.64,
      "audience_total_impression": 277532.64,
      "availability": 100,
      "available_slots": 9
    },
    {
      "id": 54023,
      "name": "JFK - Terminal 5 - Food Hall",
      "address": "Terminal 5, Jamaica, NY 11430, USA",
      "resolution": "900x780",
      "orientation": "Landscape",
      "screen_format": null,
      "lat": 40.645802,
      "long": -73.775299,
      "fill_rate": 0,
      "rate_card_name": null,
      "has_fixed_slot_duration": true,
      "reference_id": null,
      "__row": 1,
      "audience_filter_impression": 1273440,
      "audience_total_impression": 1273440,
      "availability": 100,
      "available_slots": 12
    },
    {
      "id": 54024,
      "name": "JFK - Terminal 7 - Food Court",
      "address": "John F. Kennedy International Airport (JFK), Queens, NY 11430, USA",
      "resolution": "900x780",
      "orientation": "Landscape",
      "screen_format": null,
      "lat": 40.6413,
      "long": -73.778099,
      "fill_rate": 0,
      "rate_card_name": null,
      "has_fixed_slot_duration": true,
      "reference_id": null,
      "__row": 2,
      "audience_filter_impression": 277532.64,
      "audience_total_impression": 277532.64,
      "availability": 100,
      "available_slots": 9
    }
  ],
  "totalScreen": 3,
  "total": 3,
  "unfilteredScreenCount": 45,
  "unfilteredCount": 45
}

Request Method: POST

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

Documentation: Swagger /api/v1/proposal/add_screens

Create a proposal item in the proposal by adding screens to it.

If you have performed Step 2: Search for Screens (Optional), use the screen IDs that are in the response. Use the proposal ID that you have created in Step 1: Create the Proposal as proposal_id.

Request

Copy 
{
  "name": "Broadsign Proposal",
  "price": 0,
  "status": 1,
  "screens": [
    54016,
    54023,
    54024
  ],
  "package_id": null,
  "proposal_id": 12345,
  "multiplier": 14,
  "start_date": "2022-02-01",
  "end_date": "2022-02-14",
  "start_time": "00:00:00",
  "end_time": "23:59:59",
  "flight_duration": 1,
  "flight_type": 0,
  "dow_mask": 127,
  "slot_duration": 10,
  "saturation": 1,
  "filters": [
    {
      "uuid": "criteria:8304",
      "id": 8304,
      "type": "criteria",
      "name": "Restaurant"
    }
  ],
  "bs_saturation": 1,
  "available_only": false,
  "deployed_only": false,
  "mode": [
    {
      "type": "ppl",
      "values": {
        "bs_saturation": 1,
        "saturation": 1
      },
      "active": true
    },
    {
      "type": "sov",
      "values": {
        "sov": 15
      },
      "active": false
    },
    {
      "type": "takeover",
      "values": {
        "sov": 100
      },
      "active": false
    },
    {
      "type": "goal_impressions",
      "values": {
        "impressions": null,
        "budget": null,
        "cpm": null
      },
      "active": false
    },
    {
      "type": "goal_budget",
      "values": {
        "budget": null,
        "impressions": null,
        "cpm": null
      },
      "active": false
    },
    {
      "type": "goal_repetitions",
      "values": {
        "repetitions": 1
      },
      "active": false
    },
    {
      "type": "average_sov",
      "values": {
        "sov": 15,
        "distribution": "day"
      },
      "active": false
    }
  ],
  "inventory_type": "digital",
  "is_preemptible": false,
  "proposal_goal_id": null,
  "custom_cpm": 0
}

Response

Copy 
{
  "id": 418495,
  "creation_tm": "2022-01-13 15:51:13",
  "modification_tm": "2022-01-13 15:51:13",
  "active": true,
  "active_type": "ppl",
  "actual_impressions": 0,
  "actual_repetitions": 0,
  "name": "Broadsign Proposal",
  "price": 12600,
  "proposal_id": 12345,
  "package_id": null,
  "flight_duration": 1,
  "flight_type": 0,
  "slot_duration": 10,
  "saturation": 1,
  "suggested_price": "12600",
  "status": 1,
  "start_date": "2022-02-01",
  "end_date": "2022-02-14",
  "start_time": "00:00:00",
  "end_time": "23:59:59",
  "earliest_start_datetime_in_utc": "2022-02-01 05:00:00",
  "latest_end_datetime_in_utc": "2022-02-15 04:59:59",
  "dow_mask": 127,
  "provider_id": null,
  "external_id": null,
  "multiplier": 14,
  "filters": [
    {
      "uuid": "criteria:8304",
      "id": 8304,
      "type": "criteria",
      "name": "Restaurant"
    }
  ],
  "mode": [
    {
      "type": "ppl",
      "active": true,
      "values": {
        "bs_saturation": 1,
        "saturation": 1,
        "projected_repetitions": 0,
        "custom_cpm": 0
      }
    },
    {
      "type": "sov",
      "active": false,
      "values": {
        "sov": 15
      }
    },
    {
      "type": "takeover",
      "active": false,
      "values": {
        "sov": 100
      }
    },
    {
      "type": "goal_impressions",
      "active": false,
      "values": {
        "budget": null,
        "impressions": null,
        "cpm": null
      }
    },
    {
      "type": "goal_budget",
      "active": false,
      "values": {
        "budget": null,
        "impressions": null,
        "cpm": null
      }
    },
    {
      "type": "goal_repetitions",
      "active": false,
      "values": {
        "repetitions": 1
      }
    },
    {
      "type": "average_sov",
      "active": false,
      "values": {
        "sov": 15,
        "distribution": "day"
      }
    }
  ],
  "inventory_type": "digital",
  "day_masks": {},
  "priority": 1,
  "performance_update_tm": "2022-01-13 15:51:13",
  "last_auto_rebalance_tm": null,
  "synchronized": false,
  "is_processing": false,
  "is_preemptible": false,
  "booking_tm": null,
  "is_name_templatized": false,
  "expected": null,
  "projected": 0,
  "target": 0,
  "proposal_goal_id": null,
  "reference_id": null,
  "cpm": 0,
  "custom_cpm": null,
  "creation_user_id": 207,
  "modification_user_id": 207,
  "screen_count": 3,
  "dynamic_screen_selection": null
}

In the Response, only one mode can be active at a time. The mode represents the type of buy used.

Mode Type of Buy
ppl Frequency
sov Fixed Share of Voice
average_sov

Average Share of Voice. The distribution parameter indicates which Average SoV is active:

  • day: Daily Average
  • screen-day: Daily Average per Screen
  • campaign: Campaign Average
takeover Takeover
goal_impressions Impressions Goal
goal_budget Budget Goal
goal_repetitions Play Goal

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

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 the Proposal as proposal_id.

Response

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

Copy 
{
  "proposal_id": 12345,
  "proposal_name": "Broadsign Proposal",
  "availability": "available",
  "goals": [],
  "proposal_items": [
    {
      "proposal_item_id": 418495,
      "proposal_item_name": "Broadsign Proposal",
      "availability": "available",
      "inventory_type": "digital",
      "is_package": false,
      "screens": {
        "available": {
          "screen_ids": [
            54016,
            54024,
            54023
          ],
          "messages": [],
          "screen_count": 3
        }
      },
      "messages": []
    }
  ],
  "requested_screen_count": 3,
  "bookable_screen_count": 3
}

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 the Proposal as proposal_id.

Response

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

Copy 
{
  "proposal_id": 12345,
  "proposal_name": "Broadsign Proposal",
  "availability": "available",
  "goals": [],
  "proposal_items": [
    {
      "proposal_item_id": 418495,
      "proposal_item_name": "Broadsign Proposal",
      "availability": "available",
      "inventory_type": "digital",
      "is_package": false,
      "screens": {
        "available": {
          "screen_ids": [
            54016,
            54024,
            54023
          ],
          "messages": [],
          "screen_count": 3
        }
      },
      "messages": []
    }
  ],
  "requested_screen_count": 3,
  "bookable_screen_count": 3
}

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 the Proposal as proposal_id.

Response

Copy 
{
  "id": 12345,
  "creation_tm": "2022-01-13 15:43:13",
  "modification_tm": "2022-01-13 15:57:04",
  "active": true,
  "domain_id": 53,
  "name": "Broadsign Proposal",
  "description": "This is a test proposal",
  "price": 12600,
  "discount": 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": "2022-02-01",
  "earliest_start_datetime_in_utc": "2022-02-01 05:00:00",
  "latest_end_datetime_in_utc": "2022-02-15 04:59:59",
  "picture": "",
  "contract_id": "ABC-1234",
  "contract_number": "ABC-1234",
  "hold_expiry_tm": "2022-01-20 15:57:04",
  "locks": {
    "book": false,
    "edit": false,
    "hold": false,
    "sync": false,
    "delete": false,
    "download": false,
    "sync_button": false,
    "contact_edit": false
  },
  "custom_data": {},
  "owner_user_id": 207,
  "hold_requested": false,
  "creation_user_id": 207,
  "modification_user_id": 207,
  "creation_date_time": "2022-01-13 15:43:13",
  "last_modification_date_time": "2022-01-13 15:57:04",
  "owner_user_name": "Sarah",
  "creation_user_name": "Sarah",
  "suggested_price": 12600,
  "end_date": "2022-02-14",
  "proposal_item_id_list": [
    418495
  ],
  "category_ids": [
    51
  ],
  "is_cloneable": true
}

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 the Proposal as proposal_id.

Response

You must get a 200 Success response.

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 the Proposal 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 
{
  "active": true,
  "category_ids": [
    0
  ],
  "client_address": "Montreal, Canada",
  "client_id": "Client ID 1234",
  "client_name": "Doe Company",
  "contact_email": "john@doe.com",
  "contact_name": "John Doe",
  "contact_phone": "1-888-000-0000",
  "contract_id": "ABC-1234",
  "contract_number": "ABC-12345",
  "creation_date_time": "2022-01-13 15:43:13",
  "creation_tm": "2022-01-13 15:43:13",
  "creation_user_id": 207,
  "creation_user_name": "Sarah",
  "custom_data": {},
  "description": "This is a test proposal",
  "discount": 0,
  "domain_id": 53,
  "earliest_start_datetime_in_utc": "2022-01-13 15:43:13",
  "end_date": "2022-01-13 15:43:13",
  "hold_expiry_tm": null,
  "id": 12345,
  "is_cloneable": true,
  "last_modification_date_time": "2022-01-13 15:43:13",
  "latest_end_datetime_in_utc": "2022-01-13 15:43:13",
  "locks": {
    "book": false,
    "contact_edit": false,
    "delete": false,
    "download": false,
    "edit": false,
    "hold": false,
    "sync": false,
    "sync_button": false
  },
  "modification_tm": "2022-01-13 15:43:13",
  "modification_user_id": 207,
  "name": "Broadsign Proposal",
  "owner_user_id": 207,
  "owner_user_name": "Sarah",
  "picture": "",
  "price": 0,
  "proposal_item_id_list": [
    0
  ],
  "start_date": "2022-01-13",
  "status": 4,
  "suggested_price": 0
}