OpenRTB 2.6 Integration

The OpenRTB 2.6 interface provides compatibility with standard programmatic advertising systems and Supply-Side Platforms (SSPs). This interface bridges the gap between traditional RTB workflows and the Adlocaite platform.

Overview

The OpenRTB 2.6 interface was developed for integration with Supply-Side Platforms (SSPs) and other standard RTB systems. It provides a bridge between traditional programmatic advertising workflows and the Adlocaite DOOH platform.

When to use this interface

Use the OpenRTB interface only in these scenarios:

• Your publisher management system is already integrated with an SSP that uses OpenRTB 2.6
• Your playout system cannot make direct API calls to the Adlocaite Core API
• You need compatibility with existing RTB workflows for legacy systems

For all other cases, use the Core API which provides superior functionality and performance.

Developer utilities

To simplify testing and integration, we provide a Postman Collection with pre-configured requests for the OpenRTB 2.6 interface.

Postman Collection download

The OpenAPI specification can be downloaded directly from the API and imported into Postman:

curl -o openrtb-postman.json \
  https://api.adlocaite.com/functions/v1/openrtb-2-6/openapi.json

Or access directly in your browser:

• Production: https://api.adlocaite.com/functions/v1/openrtb-2-6/openapi.json
• Staging: https://staging.api.adlocaite.com/functions/v1/openrtb-2-6/openapi.json

Import into Postman

1. Open Postman and click Import in the top left
2. Select the downloaded openrtb-postman.json file or paste the URL directly
3. The collection will be imported with all endpoints pre-configured

Configure environment variables

After importing, set up your Postman environment with these variables:

The collection includes example BidRequests that you can modify for your specific testing needs.

Implementation constraints

The OpenRTB 2.6 standard was designed for traditional web and mobile advertising. Digital Out-of-Home advertising requires precise timing, screen availability management, and real-time content delivery - capabilities that the OpenRTB protocol does not adequately support.

Why these limitations exist

The Adlocaite platform is optimized for reactive, real-time DOOH advertising where offers must be matched, accepted, and displayed within seconds. This approach maximizes:

• Revenue for publishers: By ensuring the highest-value advertisements are shown at the right time
• Campaign performance for advertisers: Through precise audience targeting and optimal timing
• System efficiency: By avoiding bid conflicts and reducing wasted inventory

The OpenRTB protocol, designed for auction-based environments with longer decision windows, cannot fully support this reactive model. Therefore, this interface operates with significant functional constraints to maintain system integrity.

Supported features

Not supported

• Multiple impressions per request
• Open auction formats (First-price, Second-price)
• Banner object format
• Dynamic creative optimization
• Real-time offer acceptance/rejection workflow
• Flexible scheduling and timing control

How it works

The OpenRTB integration follows a simplified request-response flow:

Request flow

1. BidRequest received: SSP sends OpenRTB 2.6 BidRequest with screen details and deal information
2. Validation: Request is validated against implementation constraints
3. Screen identification: External Screen ID is extracted from imp.tagid (our implementation assumes tagid contains the screen identifier)
4. Minimum bid calculation: Floor price is calculated from deal.bidfloor × imp.ext.totalaud
5. Offer matching: Platform finds matching offers for the screen above minimum bid
6. Resolution check: Asset resolution must exactly match requested dimensions
7. VAST generation: VAST 4.0 XML is generated with tracking URLs and OpenRTB macros
8. BidResponse returned: Response includes bid price, VAST XML, and deal information

Response types

Asset matching

The platform matches advertisements to screens based on the screen type configured by the publisher. When registering a screen, publishers specify which type of content their screen can display.

Screen types and asset compatibility

Publishers classify their screens into one of three types when registering them in the platform:

• Static Screen: Displays only static images (JPEG, PNG)
• Slow Screen: Displays static images and slow animations (Cinemagraphs)
• Moving Screen: Displays any asset type - static images, slow animations, or full video

The matching algorithm automatically selects assets that are compatible with the publisher-configured screen type. The following table shows which asset types can be returned for each screen type:

How the matching works

When a BidRequest arrives, the platform performs the following steps:

1. Screen identification: The External Screen ID from imp.tagid is used to look up the screen and its type (static/slow/moving)
2. Asset selection: The matching algorithm finds the best matching advertisement and selects an asset that is compatible with the screen type
3. MIME type check: The selected asset's MIME type is verified against the SSP's allowed types in video.mimes
4. Response generation: A VAST 4.0 XML response is generated with the asset URL and correct MIME type

SSP MIME type signaling

SSPs use the video.mimes array in the BidRequest to specify which file formats they accept. For example:

• Roadside screens (image-only): ["image/jpeg", "image/png"]
• Indoor video screens: ["video/mp4", "video/webm"]
• Flexible screens: ["video/mp4", "video/webm", "image/jpeg", "image/png"]

The platform checks that the selected asset's MIME type is included in this list. If not, a no-bid response is returned.

Matching examples

Example 1: Moving Screen with video restriction

• Screen Type: Moving
• SSP allows: ["video/mp4"]
• Available assets: Static image, Video
• Result: Video asset is selected (compatible with both screen type and SSP requirements)

Example 2: Static Screen with flexible SSP

• Screen Type: Static
• SSP allows: ["video/mp4", "image/jpeg"]
• Available assets: Static image, Video
• Result: Static image is selected (only compatible asset for static screen)

Example 3: No compatible asset

• Screen Type: Static
• SSP allows: ["video/mp4"]
• Available assets: Static image
• Result: No-bid (HTTP 204) - static image not allowed by SSP

VAST response format

All responses use VAST 4.0 XML format. The MediaFile tag's MIME type reflects the actual asset format:

For static images:

<MediaFile type="image/jpeg" width="1080" height="1920">
  <![CDATA[https://storage.adlocaite.com/assets/static-ad.jpg]]>
</MediaFile>
<Duration>00:00:10</Duration>

For videos:

<MediaFile type="video/mp4" width="1080" height="1920">
  <![CDATA[https://storage.adlocaite.com/assets/video-ad.mp4]]>
</MediaFile>
<Duration>00:00:15</Duration>

The platform automatically determines the correct MIME type from the asset file extension.

Authentication

Authentication uses Bearer token authentication with your Publisher API Key.

curl -X POST https://api.adlocaite.com/functions/v1/openrtb-2-6/bid \
  -H "Authorization: Bearer YOUR_PUBLISHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d @bidrequest.json

See the Authentication guide for details on obtaining your API key.

Endpoints

POST /bid

Submit a BidRequest for a specific screen and receive a BidResponse with pricing and creative details.

curl -X POST https://api.adlocaite.com/functions/v1/openrtb-2-6/bid \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "auction-12345",
    "imp": [{
      "id": "1",
      "tagid": "screen-ext-001",
      "video": {
        "mimes": ["video/mp4"],
        "w": 1920,
        "h": 1080
      },
      "pmp": {
        "deals": [{
          "id": "deal-001",
          "bidfloor": 2.50,
          "at": 3
        }]
      },
      "ext": {
        "totalaud": 119.47
      }
    }],
    "at": 3
  }'

{
  "id": "auction-12345",
  "seatbid": [{
    "bid": [{
      "id": "bid-uuid-12345",
      "impid": "1",
      "price": 2.50,
      "adid": "offer-uuid-67890",
      "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"4.0\">...</VAST>",
      "adomain": ["adlocaite.com"],
      "cid": "offer-uuid-67890",
      "crid": "offer-uuid-67890",
      "dealid": "deal-001",
      "w": 1920,
      "h": 1080
    }]
  }],
  "bidid": "bidid-uuid-99999",
  "cur": "EUR"
}

No Content

{
  "error": "MULTI_IMP_NOT_SUPPORTED",
  "message": "Multiple impressions per request are currently not supported",
  "details": {
    "imp_count": 3
  }
}

POST /

Alternative endpoint that routes to the same bid handler. Use /bid for clarity.

BidRequest format

The BidRequest must follow OpenRTB 2.6 specification with specific requirements for Adlocaite integration.

Required fields

Minimum bid calculation

The minimum bid in cents is calculated as:

minBidCents = (bidfloor × totalaud) / 10

Example:

• bidfloor = 2.50 EUR CPM
• totalaud = 119.47 impressions
• minBidCents = (2.50 × 119.47) / 10 = 30 cents

BidResponse format

The BidResponse follows OpenRTB 2.6 specification with VAST 4.0 XML for creative delivery.

Successful bid

{
  "id": "auction-12345",
  "seatbid": [{
    "bid": [{
      "id": "f7b3c9e1-4d2a-4c8b-9a1e-3f5d6c7b8a9d",
      "impid": "1",
      "price": 2.53,
      "adid": "offer-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<VAST version=\"4.0\">...</VAST>",
      "adomain": ["adlocaite.com"],
      "cid": "offer-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "crid": "offer-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "dealid": "deal-001",
      "w": 1920,
      "h": 1080
    }]
  }],
  "bidid": "bid-transaction-uuid-99999",
  "cur": "EUR"
}

Note: The adm field contains the complete VAST 4.0 XML (truncated above for readability). See the /bid endpoint response for a full example.

No-bid response

{
  "id": "auction-12345",
  "seatbid": [],
  "nbr": 0,
  "cur": "EUR"
}

OpenRTB macros in tracking URLs

The VAST XML includes tracking URLs with OpenRTB macros that are replaced by the SSP:

• ${AUCTION_PRICE}: Final auction price
• ${TOTAL_IMP}: Total audience impressions

Example tracking URL:

https://tracking.adlocaite.com/track?offer_id=abc-123&event=impression&price=${AUCTION_PRICE}&aud=${TOTAL_IMP}

Error handling

The OpenRTB interface uses standard HTTP status codes and error response format.

Error response format

{
  "error": "ERROR_CODE",
  "message": "Human-readable error description",
  "details": {
    "additional": "context information"
  }
}

Common error codes

No-bid reason codes (NBR)

When returning HTTP 200 with empty seatbid, the nbr field indicates the reason:

For legitimate no-bid scenarios (no matching offers, minimum bid not met), HTTP 204 is returned without a response body.