Migration Guide: OpenRTB to Core API

This guide walks you through migrating from the legacy OpenRTB 2.6 interface to the Adlocaite Core API. The Core API provides better performance, more features, and a simpler integration model.

Why migrate?

The Core API was built specifically for DOOH advertising workflows and removes the limitations imposed by the OpenRTB protocol.

What you gain

What changes

Key differences

Migration steps

Step 1: Map your screen identifiers

In OpenRTB, screens are identified via imp[0].tagid (External Screen ID). The Core API supports both UUIDs and external IDs:

• If you have Adlocaite UUIDs: Use them directly in the path -- this is recommended for best performance
• If you only have external IDs: Use the /external-id/ endpoint variant (see External Screen IDs)

Step 2: Replace the bid request with an offer request

Instead of constructing a full OpenRTB BidRequest, make a simple GET request:

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
  }'

Note the pricing difference: in OpenRTB, the minimum bid is calculated as (bidfloor x totalaud) / 10. In the Core API, you pass min_bid_cents directly.

Step 3: Handle the simpler response

The Core API returns a flat JSON object instead of the nested OpenRTB BidResponse:

{
  "id": "auction-12345",
  "seatbid": [{
    "bid": [{
      "id": "bid-uuid-12345",
      "impid": "1",
      "price": 2.50,
      "adm": "<?xml version=\"1.0\"?>...<VAST>...</VAST>",
      "dealid": "deal-001",
      "w": 1920,
      "h": 1080
    }]
  }],
  "cur": "EUR"
}

Step 4: Add explicit offer acceptance

This is the biggest workflow change. In OpenRTB, winning a bid implicitly means the ad will be shown. In the Core API, you must explicitly accept or reject offers:

curl -X POST https://api.adlocaite.com/functions/v1/api/offers/response/[offer_id] \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "accept",
    "accepted_price_cents": 253
  }'

This returns a deal_id that you use for playout tracking.

Step 5: Implement playout tracking

Replace VAST tracking pixels with the dedicated playout confirmation endpoint:

curl -X POST "https://api.adlocaite.com/functions/v1/api/playout/confirm/[deal_id]" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "played_at": "2025-10-10T14:30:00Z",
    "duration_seconds": 15,
    "completion_rate": 100
  }'

Endpoint mapping

Request & response comparison

Field mapping

Use this table to map your existing OpenRTB field handling to the Core API:

Playout tracking

The Core API provides richer playout tracking compared to VAST tracking pixels:

See the full Playout Tracking documentation for details.

Testing your migration

The Core API provides built-in demo mode for testing without affecting production data.

Demo offer request

curl -X GET "https://api.adlocaite.com/functions/v1/api/offers/request/test-display-test" \
  -H "Authorization: Bearer YOUR_API_KEY"

Demo offer acceptance

curl -X POST https://api.adlocaite.com/functions/v1/api/offers/response/test-offer-test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "accept",
    "accepted_price_cents": 250
  }'

Demo playout confirmation

curl -X POST "https://api.adlocaite.com/functions/v1/api/playout/confirm/test-deal-test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "duration_seconds": 15,
    "completion_rate": 100
  }'

All demo endpoints return realistic responses without modifying any data. Use the Staging environment for integration testing with real API keys.