Developer GuideDemand SourcesBid Request Reference

Bid Request Reference

Praevis sends OpenRTB 2.5 bid requests to traditional RTB bidder endpoints. This page documents every field we send, what it contains, and when it’s present.

Endpoint: POST https://rtb.praevis.com/rtb (supply-side sends here; demand endpoint receives from Praevis) Timeout: 150ms hard cutoff Content-Type: application/json

Full annotated example — CTV app

{
  "id": "auction-3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "at": 1,
  "tmax": 150,
 
  "app": {
    "id": "app-uuid",
    "name": "Example Streaming App",
    "bundle": "com.example.streamingapp",
    "cat": ["IAB1", "IAB1-7"],
    "storeurl": "https://apps.apple.com/app/example/id123456",
    "publisher": {
      "id": "pub-uuid",
      "name": "Example Publisher"
    },
    "content": {
      "id": "content-uuid",
      "title": "The Crown - Season 5",
      "series": "The Crown",
      "season": "5",
      "episode": 3,
      "cat": ["IAB1-7"],
      "genre": "drama",
      "len": 3600,
      "livestream": 0,
      "language": "en"
    }
  },
 
  "imp": [
    {
      "id": "imp-001",
      "video": {
        "mimes": ["video/mp4"],
        "minduration": 15,
        "maxduration": 30,
        "protocols": [2, 3, 5, 6],
        "w": 1920,
        "h": 1080,
        "startdelay": 0,
        "linearity": 1,
        "skip": 0,
        "api": []
      },
      "bidfloor": 3.00,
      "bidfloorcur": "USD",
      "secure": 1,
      "ext": {
        "pool_id": "pool-uuid",
        "auction_type": "first_price"
      }
    }
  ],
 
  "device": {
    "ua": "Mozilla/5.0 (SMART-TV; Linux; Tizen 6.0) ...",
    "ip": "203.0.113.42",
    "geo": {
      "country": "AE",
      "region": "AE-DU",
      "city": "Dubai",
      "type": 2
    },
    "devicetype": 3,
    "make": "Samsung",
    "model": "QN65Q800T",
    "os": "Tizen",
    "language": "en",
    "dnt": 0
  },
 
  "user": {
    "id": "user-hashed-id"
  },
 
  "ext": {
    "partner_id": "partner-uuid",
    "praevis_version": "1.0"
  }
}

Top-level fields

FieldTypeAlways presentDescription
idstring✓Unique auction ID (UUID)
atint✓Auction type: always 1 (first-price)
tmaxint✓Bid timeout in ms — always 150
appobjectApp inventoryCTV/mobile app context (see below)
siteobjectWeb inventoryWeb context (see below)
imparray✓Impression opportunities (always 1 element)
deviceobject✓Device and geo information
userobject✓Hashed user ID (GDPR-safe)
extobject✓Praevis extension fields

app object (CTV / mobile)

FieldDescription
idApp identifier
nameApp display name
bundleApp store bundle ID (com.example.app)
catIAB content categories
publisher.idPraevis Publisher ID
content.genreContent genre (e.g., "drama", "sport", "news") — use for Delegate targeting
content.titleEpisode or show title
content.seriesSeries name
content.livestream1 = live, 0 = VOD
content.languageContent language (ISO 639-1)

site object (web)

FieldDescription
idSite identifier
domainRoot domain (e.g., example.com)
pageCurrent page URL
catIAB content categories
publisher.idPraevis Publisher ID

imp object

FieldDescription
idImpression ID
videoVideo impression spec (see below)
bannerBanner impression spec (mutually exclusive with video)
bidfloorFloor price in USD CPM
bidfloorcurAlways "USD"
secureAlways 1 — HTTPS required
ext.pool_idPool the publisher belongs to
ext.auction_typeAlways "first_price"

video spec

FieldDescription
mimesSupported MIME types (["video/mp4"])
mindurationMin ad duration in seconds
maxdurationMax ad duration in seconds
protocolsVAST protocols: 2=VAST 2.0, 3=VAST 3.0, 5=VAST 2.0 Wrapper, 6=VAST 3.0 Wrapper
w, hPlayer dimensions in pixels
startdelay0 = pre-roll, -1 = mid-roll, -2 = post-roll
linearity1 = in-stream linear
skip0 = not skippable, 1 = skippable

device object

FieldDescription
uaUser agent string
ipIPv4 address of the viewer
geo.countryISO 3166-1 alpha-2 ("AE", "GB", "US")
geo.regionISO 3166-2 region ("AE-DU", "GB-ENG")
geo.cityCity name
devicetype1=mobile, 2=desktop, 3=CTV/connected TV, 4=tablet
makeDevice manufacturer
modelDevice model
osOperating system
dntDo Not Track (0=no preference, 1=opted out)

ext fields

FieldDescription
ext.partner_idPlatform partner UUID (if inventory is partner-scoped)
ext.praevis_versionAPI version — currently "1.0"

Bid response format

Return HTTP 200 with a valid bid:

{
  "id": "auction-3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "seatbid": [
    {
      "bid": [
        {
          "id": "your-bid-id",
          "impid": "imp-001",
          "price": 4.50,
          "adid": "your-creative-id",
          "adm": "https://your-vast-server.com/vast?params=...",
          "crid": "creative-001",
          "w": 1920,
          "h": 1080
        }
      ],
      "seat": "your-dsp-id"
    }
  ],
  "cur": "USD"
}

No bid: Return HTTP 204 with empty body. Do not return a 200 with an empty seatbid array.

⚠️

First-price auction: price is the amount you will pay if you win. There is no second-price reduction. Set price to your true willingness to pay.

Field presence rules

ConditionFields present
CTV / mobile appapp, app.content, device.devicetype=3
Web publishersite, no app
Video inventoryimp[0].video, no banner
Banner inventoryimp[0].banner, no video
Partner-scopedext.partner_id present
Geo knowndevice.geo.country, device.geo.region, device.geo.city
Geo unknowndevice.geo.country only, region/city absent

Privacy & Consent

Praevis passes through all privacy signals from publishers to DSPs unchanged.

GDPR (TCF 2.0)

FieldTypeDescription
regs.ext.gdprinteger1 if GDPR applies, 0 otherwise
user.ext.consentstringTCF consent string

CCPA

FieldTypeDescription
regs.ext.us_privacystringCCPA consent string (e.g., 1YNN)

GPP (Global Privacy Platform)

FieldTypeDescription
regs.gppstringGPP consent string (consolidates GDPR, CCPA, and US state laws)
regs.gpp_sidinteger[]Section IDs that apply (e.g., [7] for US national)

For VAST GET requests, pass privacy via query params: ?gdpr=1&gdpr_consent=...&us_privacy=1YNN&gpp=...&gpp_sid=7

Getting StartedDelegate Strategy Guide