Sign in

v52

latestOpenAPI 3.0.3raw.githubusercontent.com2026-07-2113138232.4 KB
billboards

Billboards

Retrieve a list of all billboards configured in the system.

    ### Billboards Overview:
    - Billboards are custom promotional ads, notification banners, or call-to-actions shown on the Forem website.
    - Requires administrative privileges.
    - Returned objects include layout code, scheduling parameters, geo-targeting configurations, and custom target audience segment associations.
get/api/billboards

Response

successful

idinteger

The ID of the Billboard

namestring required

For internal use, helps distinguish ads from one another

body_markdownstring required

The text (in markdown) of the ad (required)

approvedboolean

Ad must be both published and approved to be in rotation

publishedboolean

Ad must be both published and approved to be in rotation

expires_atstring date-time nullable

Timestamp when the billboard expires. After this time, the billboard will automatically be marked as not approved.

organization_idinteger nullable

Identifies the organization to which the ad belongs

creator_idinteger nullable

Identifies the user who created the ad.

placement_area'sidebar_left' | 'sidebar_left_2' | 'sidebar_right' | 'sidebar_right_second' | 'sidebar_right_third' | 'feed_first' | 'feed_second' | 'feed_third' | 'home_hero' | 'footer' | 'page_fixed_bottom' | 'post_fixed_bottom' | 'post_body_bottom' | 'post_sidebar' | 'post_comments' | 'post_comments_mid' | 'digest_first' | 'digest_second' required

Identifies which area of site layout the ad can appear in

tag_liststring

Tags on which this ad can be displayed (blank is all/any tags)

exclude_article_idsstring nullable

Articles this ad should not appear on (blank means no articles are disallowed, and this ad can appear next to any/all articles). Comma-separated list of integer Article IDs

audience_segment_idinteger

Specifies a specific audience segment who will see this billboard

audience_segment_type'manual' | 'trusted' | 'posted' | 'no_posts_yet' | 'dark_theme' | 'light_theme' | 'no_experience' | 'experience1' | 'experience2' | 'experience3' | 'experience4' | 'experience5'

Specifies a group of users who will see this billboard (must match audience_segment_id if both provided)

target_geolocationsstring[]

Locations to show this billboard in (blank means it will be shown in all locations). Specified as a comma-separated list or array of ISO 3166-2 country and optionally region codes)

display_to'all' | 'logged_in' | 'logged_out'

Potentially limits visitors to whom the ad is visible

type_of'in_house' | 'community' | 'external'

Types of the billboards: in_house (created by admins), community (created by an entity, appears on entity's content), external ( created by an entity, or a non-entity, can appear everywhere)