Skip to main content

​
Screens

Screens represent individual display devices deployed within a location. Each screen displays advertisements in a continuous loop and is identified by its unique configuration, including resolution and loop timing parameters.

​
Key Concepts

  • Screen: A physical or virtual display device that plays a sequence of ads
  • Location: Parent location containing one or more screens
  • Loop Duration: The total time (in seconds) for one complete rotation through all queued advertisements
  • Venue Type: Classification that must match or be compatible with the parent location’s venue type
  • Resolution: Pixel dimensions (width x height) of the display
Before creating screens, you must first create a location. Each screen belongs to exactly one location and inherits the location’s organizational context.

​
Screen Object

The Screen object contains all configuration and metadata for a display device:
FieldTypeDescription
screen_idstringUnique identifier for the screen (client-generated, UUID format)
titlestringHuman-readable label for the screen (e.g., “Main Lobby Display”)
venue_type_idstringVenue type classification (e.g., "205" for Malls); must match or be a child of the location’s venue type
location_idstringID of the parent location
widthintegerPixel width of the display resolution
heightintegerPixel height of the display resolution
loop_durationintegerDuration in seconds for one complete advertisement loop
archivedbooleanWhether hidden from Dashboard. Default: false
available_for_adsbooleanWhether the screen accepts ad campaigns. Default: true
amountintegerNumber of physical screens this entry represents
imps_weeklyintegerEstimated weekly impressions

​
Example Screen Object

{
  "screen_id": "d3c8dbb6-c21b-4b26-8f35-d73260c95fa1",
  "title": "Main Lobby Display",
  "venue_type_id": "602",
  "location_id": "Loc_f9FxuWDTfzy",
  "width": 1920,
  "height": 1080,
  "loop_duration": 120,
  "archived": false,
  "available_for_ads": true,
  "amount": 1,
  "imps_weekly": 12503
}

​
Common Use Cases

  • Create a Screen: Add a new display device to your location with specific resolution and timing parameters
  • Retrieve Screen Details: Look up configuration and metadata for a specific screen
  • Update Screen Settings: Modify display name, loop duration, or venue classification
  • List Organization Screens: View all screens deployed across your organization
  • Manage Ad Content: Use the screen ID to request and manage advertisements for that specific display

​
Requirements

  • Parent location must exist before creating screens
  • Screen venue_type_id must be compatible with the location’s venue type hierarchy
  • Resolution values (width/height) must be positive integers
  • Loop duration must be a positive integer representing seconds
  • The client generates the screen_id (UUID format). Sending a duplicate returns an error.
Last modified on April 17, 2026