Skip to main content
GET /v3/vendor/{org_token}/1/rt_ad/{screen_id}
Request ad creatives and news content for immediate playback on a specific screen. Each request triggers a new auction decision on the server — responses are one-time use and must not be replayed offline.
Requests must come from the screen itself (or its player software). Each request triggers a fresh auction. Caching the media file for playback is fine, but only play it when an ad response tells you to do so. Do not replay old responses.

​
Path parameters

ParameterTypeRequiredDescription
org_tokenstringYesYour organization token (find it here)
screen_idstringYesThe screen to fetch content for

​
Example request

curl -X GET "https://api.framen.com/v3/vendor/Org_9WeJxcVrRnM/1/rt_ad/d3c8dbb6-c21b-4b26-8f35-d73260c95fa1"

​
Response scenarios

Ad and news available: 
{
  "data": {
    "requestId": "b576b083-a7cd-47fa-b33e-642b93457339",
    "ad": {
      "id": "Itm_cgK3bmLgWMC",
      "title": "Campaign Creative",
      "mimeType": "video/mp4",
      "height": 1080,
      "width": 1920,
      "duration": 10000,
      "url": "https://d3kdzyvtj6vooy.cloudfront.net/video-opt.mp4",
      "pop": "https://api.framen.com/pop/GtzksoSqPq2ojMzcDbdAahGgz4ogDKjLF44tdowMHFue",
      "md5": "1a61d314216ed9b267be3b6f93cdb78d"
    },
    "news": null,
    "billable": false,
    "newsFirst": true
  }
}
No content available (valid request, nothing to serve): 
{
  "data": {
    "requestId": "175e6560-21ef-4263-b7de-269172572512",
    "ad": null,
    "news": null,
    "billable": false,
    "newsFirst": true
  }
}
Invalid request (404): 
{
  "detail": "Not Found"
}

​
Response fields

FieldTypeDescription
data.requestIdstringUnique identifier for this request
data.billablebooleanWhether this response contains a billable impression
data.newsFirstbooleanPlayback order flag (see below)
data.adobject | nullAd creative, or null if none available
data.newsobject | nullNews item, or null if none available

​
Ad object

FieldTypeDescription
idstringAd creative ID
titlestringCreative name
mimeTypestringContent type (e.g., video/mp4, image/jpeg)
widthintContent width in pixels
heightintContent height in pixels
durationintPlayback duration in milliseconds
urlstringURL to download or stream the creative
popstringProof-of-play callback URL
md5stringMD5 hash of the creative file, for cache validation

​
News object

FieldTypeDescription
idstringNews item ID
titlestringNews headline
mimeTypestringContent type (e.g., text/html)
widthintContent width in pixels
heightintContent height in pixels
newsTypestringNews category
durationintDisplay duration in milliseconds
urlstringURL to load the news content
popstringProof-of-play callback URL
Duration values in the ad and news objects are in milliseconds, while loop_duration on screens is in seconds. Be careful not to mix these units.

​
Playback order

When both ad and news are present, the newsFirst flag determines the order:
newsFirstPlay order
truePlay news first, then ad immediately after
falsePlay ad first, then news immediately after
When only one item is present, play it regardless of the newsFirst value. When both are null, show your default/fallback content or request again after a delay.

​
Handling null responses

Both ad and news can be null independently. Your player must handle all four combinations:
adnewsAction
presentpresentPlay both in newsFirst order, fire both PoPs
presentnullPlay ad only, fire ad PoP
nullpresentPlay news only, fire news PoP
nullnullShow fallback content, request again after delay