Overview

Screen object definition, constraints, and ad delivery control.

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

Field	Type	Description
screen_id	string	Unique identifier in UUID format, provided by the client on creation
title	string	Human-readable screen name
venue_type_id	string	Venue type ID — must match or be a child of the parent location’s venue type
location_id	string	Parent location ID
width	int	Screen resolution width in pixels
height	int	Screen resolution height in pixels
loop_duration	int	Ad loop duration in seconds
archived	boolean	Whether the screen is hidden from the dashboard
available_for_ads	boolean	Whether the screen accepts ad delivery
amount	int	Number of physical display units this entry represents
imps_weekly	int	Estimated 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

Orientation	Width	Height	Aspect Ratio
Landscape	1920	1080	16:9
Portrait	1080	1920	9: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.