Skip to main content
Screens represent individual display devices (or groups of identical devices) at a location. Screens are the requesting entities for ad delivery — each screen has its own resolution, loop duration, and venue classification.
You must create a location before adding screens to it. Locations are the containers for geo info and opening hours; screens are the entities that request and display ads.

​
The Screen object

FieldTypeDescription
screen_idstringUnique identifier in UUID format, provided by the client on creation
titlestringHuman-readable screen name
venue_type_idstringVenue type ID — must match or be a child of the parent location’s venue type
location_idstringParent location ID
widthintScreen resolution width in pixels
heightintScreen resolution height in pixels
loop_durationintAd loop duration in seconds
archivedbooleanWhether the screen is hidden from the dashboard
available_for_adsbooleanWhether the screen accepts ad delivery
amountintNumber of physical display units this entry represents
imps_weeklyintEstimated weekly impressions

​
Key constraints

Venue type relationship — A screen’s venue_type_id must satisfy one of these conditions:
  • It is the same as the parent location’s venue_type_id (level 2), or
  • It is a child (level 3) of the parent location’s venue type
Use the Venue Types API to retrieve the taxonomy and verify parent-child relationships. Client-generated IDs — Unlike locations (where the system assigns the location_id), you must generate the screen_id yourself in UUID v4 format. Sending a duplicate screen_id on creation returns an error — the API does not upsert. Location must exist first — You cannot create a screen for a location_id that does not exist. Always create the location before its screens.

​
Disabling ad delivery

Setting available_for_ads: false on a screen immediately stops ad delivery. The Get Spot endpoint will return ad: null for that screen, and it will appear offline in the Ads Manager. This is different from the location-level available_for_ads, which only affects future campaign targeting but does not stop already-running campaigns. See Locations - Archiving vs. disabling ads for details.

​
Common screen resolutions

OrientationWidthHeightAspect Ratio
Landscape1920108016:9
Portrait108019209:16
While the API accepts any resolution, the ad network is optimized for 16:9 (landscape) and 9:16 (portrait) aspect ratios. Using other ratios may result in fewer ad fills.