OpenRTB Reference

Overview

Reticle's real-time bidding integration follows the IAB OpenRTB 2.5 specification. This page documents the object model Reticle sends and expects, the enumerations that matter for our traffic, and worked examples. Where Reticle deviates from or extends the base spec, it is called out explicitly in an ext note.

Each auction is a single HTTP POST carrying a JSON BidRequest. A bidder that wants the impression responds 200 OK with a BidResponse; a bidder that passes responds 204 No Content (or a BidResponse with no bids). All payloads are UTF-8 JSON unless agreed otherwise during onboarding.

Conventions

• Attributes marked required are always present on requests Reticle sends, or mandatory on responses Reticle accepts.
• Types follow the spec: integer, float, string, object, and array notation such as string[] or object[].
• All monetary values are CPM (cost per mille) in the currency given by cur.
• Every object carries an optional ext for extensions. Reticle defines no proprietary fields; the standard extensions shown in the tables — schain on Source, gdpr / us_privacy on Regs, and the TCF consent string on User — are the only ones used.

Endpoints & environments

Reticle connects in both directions. In a demand-side integration Reticle acts as the exchange and POSTs the BidRequest to the endpoint you register with us; in a supply-side integration you POST the request to a Reticle endpoint. Either way the transport is a single HTTP POST carrying a JSON BidRequest, with a JSON BidResponse returned in the body.

Endpoints

Production and sandbox endpoints are issued per partner during onboarding — contact support to obtain yours. Both environments speak the same protocol; the sandbox neither bills nor serves live creative.

Points of presence

Reticle operates points of presence in the United States, Europe and Singapore. Register in the region(s) closest to your infrastructure to keep round-trips comfortably inside tmax.

Transport

• Content type application/json, UTF-8.
• OpenRTB version 2.5, sent in the x-openrtb-version request header.
• gzip is supported on both request and response bodies via Content-Encoding / Accept-Encoding.

Authentication

Requests are authenticated with a token credential issued by Reticle support during onboarding — there is no self-service portal. The token, and where to place it on the request, are provided with the credential.

Who issues the token

The party that receives the requests issues the credential to the party that sends them:

• Supply-side integration — you POST to Reticle, so Reticle provides you with the token to present on each request.
• Demand-side integration — Reticle POSTs to you, so you provide Reticle with the credential your endpoint expects.

Sandbox and production use separate credentials; request each from support.

Bid request

The top-level BidRequest carries the auction id, one or more impressions, and the context — exactly one of app or site, plus device, user and regs. A representative request for a single banner impression in an app:

{
  "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
  "at": 2,
  "cur": ["USD"],
  "tmax": 120,
  "imp": [
    {
      "id": "1",
      "bidfloor": 0.03,
      "bidfloorcur": "USD",
      "secure": 1,
      "banner": {
        "pos": 1,
        "format": [
          { "w": 300, "h": 250 },
          { "w": 300, "h": 600 }
        ],
        "battr": [1, 3]
      }
    }
  ],
  "app": {
    "id": "agltb3B1Yi1pbmMr",
    "name": "Example Game",
    "bundle": "com.example.game",
    "cat": ["IAB9-30"],
    "publisher": { "id": "ex-pub-778", "name": "Example Publisher" }
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)",
    "ip": "123.145.167.10",
    "os": "iOS",
    "osv": "16.0",
    "devicetype": 1,
    "connectiontype": 2,
    "ifa": "AA000DFE74168477C70D291f574D344790E0BB11"
  },
  "user": { "id": "55816b39711f9b5acf3b90e313ed29e51665623f" },
  "source": { "fd": 1, "tid": "tx-77f2c1", "pchain": "ssp.example:pub-778" },
  "regs": { "coppa": 0, "ext": { "gdpr": 0 } }
}

BidRequest object

Top-level bid request. At least one imp is required, as is a means of identifying context via site or app.

Source object

Describes the nature and behaviour of the entity that is the source of the bid request upstream of the exchange, and carries the supply chain.

Regs object

Regulatory conditions in effect for all impressions in the request.

Imp object

Describes an impression being offered and the buy-side restrictions on it. A request may include multiple impressions; each carries exactly one of banner, video, audio or native.

Metric object

An optional metric — such as a viewability or click-through-rate estimate — for the impression, along with the vendor that computed it.

Banner object

Represents a banner impression or a companion for video/audio. Sizes may be given as one or more Format objects in format.

Video object

Represents an in-stream or in-banner video impression.

Audio object

Represents an audio impression, e.g. in a music or podcast stream.

Native object

Represents a native impression. The native creative spec itself is carried as a serialized string in request per the IAB Native Ad Specification.

Format object

Represents an allowed size (height and width) or a ratio for a banner impression.

Pmp object

The private marketplace container for direct deals between buyers and sellers that may apply to this impression.

Deal object

A specific deal struck between a buyer and seller, applicable to a direct or private-marketplace transaction.

Site object

Details of the website. Present for web inventory; mutually exclusive with App.

App object

Details of the non-browser application. Present for in-app inventory; mutually exclusive with Site.

Publisher object

Details of the publisher of the site or app.

Content object

Details of the content in which the impression will appear (independent of the site/app).

Producer object

Defines the producer of the content in which an ad will be shown — distinct from the site or app publisher.

Device object

Information about the device through which the impression is offered, including hardware, platform, location and carrier.

Geo object

Geographic location, appearing on both Device (physical device location) and User (user's home base).

User object

Information about the human user of the device — the advertising audience.

Data object

Additional data about a user or the content, keyed by a data provider (Segments).

Segment object

A specific data point about a user or piece of content — the key/value pairs within a Data object.

Bid response

A bidder that wants the impression replies with a BidResponse echoing the request id and carrying one or more seat bids. Each Bid references an impression by impid.

{
  "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
  "bidid": "abc1123",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "example-dsp",
      "bid": [
        {
          "id": "1",
          "impid": "1",
          "price": 0.5,
          "adid": "88ab13",
          "adm": "",
          "adomain": ["advertiser.com"],
          "cid": "campaign-9",
          "crid": "creative-112",
          "cat": ["IAB3-1"],
          "attr": [1],
          "w": 300,
          "h": 250,
          "nurl": "https://bid.example-dsp.com/win?i=${AUCTION_ID}&p=${AUCTION_PRICE}",
          "burl": "https://bid.example-dsp.com/billing?i=${AUCTION_ID}&p=${AUCTION_PRICE}"
        }
      ]
    }
  ]
}

BidResponse object

Top-level bid response. The id must match the request id. A response with no bids may be a 204 or a BidResponse with an empty or absent seatbid.

SeatBid object

A collection of bids made on behalf of a single buyer seat. A response may contain multiple.

Bid object

A single bid on a specific impression. id, impid and price are required; the winning bid's markup is delivered in adm or fetched from nurl.

Enumerations

The enumerated lists referenced by the fields above. Values are integers unless noted. This covers the lists most relevant to Reticle traffic; for any list not shown, the IAB OpenRTB 2.5 values apply.

Auction Type at

No-Bid Reason Codes nbr

Banner Ad Types btype

Creative Attributes attr

Ad Position pos

Expandable Direction expdir

API Frameworks api

Video Linearity linearity

Protocols protocol / protocols

Video Placement Types placement

Start Delay startdelay

Playback Methods playbackmethod

Playback Cessation Modes playbackend

Content Delivery Methods delivery

Companion Types companiontype

Feed Types feed

Production Quality prodq

Content Context context

Location Type type (Geo)

Device Type devicetype

Connection Type connectiontype

Substitution macros

Win notice, billing notice and loss notice URLs (nurl, burl, lurl) and creative markup may contain substitution macros, which the exchange replaces before firing. The standard OpenRTB macros:

Reticle supports all of the macros above. ${AUCTION_PRICE} is substituted in clear text — it is not encrypted, so no price-decryption key is required.

No-bid & timeouts

A bidder that does not wish to bid should respond as quickly as possible. Reticle prefers an HTTP 204 No Content; a 200 OK carrying a BidResponse with no seatbid and an optional nbr reason (see No-Bid Reason Codes) is also accepted.

tmax is measured at Reticle's edge and includes the network round-trip — it is the wall-clock budget from the request leaving Reticle to the response arriving back. Budget your compute time comfortably below tmax to leave room for transit.

Responses that arrive after tmax, that fail to parse, or that reference an unknown impid are discarded and counted as timeouts or errors against the seat. Seats with sustained high timeout or error rates may be throttled.

Changelog

Versioned changes to this reference will be listed here.