Publisher Integration Guide

1. Overview

Digibid Ads implements the OpenRTB 2.5 specification. Publishers send a JSON bid request over HTTPS POST to the /ortb/adx endpoint. The exchange runs a real-time auction among demand partners and returns the winning bid in an OpenRTB bid response.

Field status legend:  Required — omission breaks the protocol   Recommended — strongly advised for fill quality   Optional — provides additional context   Cond. — required only in specific contexts

2. Endpoints by Data Center

Choose the endpoint closest to your ad server to minimize latency. Each DC endpoint is fully independent; the pos_id assigned to you is valid across all DCs.

3. Quick Start

Below is the minimal valid banner bid request. Replace pos_id with your assigned value and POST.

Minimal Banner Request{
  "id": "req-001",
  "imp": [{
    "id": "1",
    "banner": { "w": 320, "h": 50 },
    "bidfloor": 0.50,
    "bidfloorcur": "USD"
  }],
  "app": {
    "bundle": "com.yourcompany.app",
    "publisher": { "id": "YOUR_PUBLISHER_ID" }
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 ...)",
    "ip": "203.0.113.45",
    "ifa": "550e8400-e29b-41d4-a716-446655440000"
  },
  "ext": { "pos_id": 101 },
  "at": 2,
  "tmax": 300
}

curl
curl -s -X POST https://adx-use.digibid.com/ortb/adx \
  -H "Content-Type: application/json" \
  -d @request.json

4. Bid Request Fields

4.1 Top-Level Object

4.2 Impression Object (imp)

4.3 Banner Object

4.4 Video Object

4.5 Native Object

Native Asset Types

4.6 App / Site Object

4.7 Device Object

4.8 Privacy Signals

4.9 Extension Object (ext)

5. Bid Response Fields

The exchange always returns HTTP 200 OK. An empty seatbid array (or absent) means no winning bid (no fill). The response structure follows the OpenRTB 2.5 BidResponse / SeatBid / Bid object model.

6. Full Examples

6.1 Banner Ad Request

Request JSON{
  "id": "banner-req-001",
  "imp": [
    {
      "id": "1",
      "banner": {
        "w": 320,
        "h": 50,
        "format": [{ "w": 320, "h": 50 }, { "w": 728, "h": 90 }],
        "btype": [1, 2],
        "pos": 1
      },
      "bidfloor": 0.50,
      "bidfloorcur": "USD"
    }
  ],
  "app": {
    "id": "app-001",
    "bundle": "com.example.newsapp",
    "publisher": { "id": "42" }
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15",
    "ip": "203.0.113.45",
    "ifa": "550e8400-e29b-41d4-a716-446655440000",
    "os": "iOS",
    "make": "Apple",
    "devicetype": 4
  },
  "ext": { "pos_id": 101 },
  "at": 2,
  "tmax": 300
}

6.2 Video Ad Request

Request JSON{
  "id": "video-req-002",
  "imp": [
    {
      "id": "1",
      "video": {
        "mimes": ["video/mp4"],
        "w": 640,
        "h": 480,
        "minduration": 5,
        "maxduration": 30,
        "protocols": [2, 3, 5, 6],
        "linearity": 1,
        "skip": 1,
        "placement": 1
      },
      "bidfloor": 1.00,
      "bidfloorcur": "USD"
    }
  ],
  "app": {
    "bundle": "com.example.videoapp",
    "publisher": { "id": "42" }
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36",
    "ip": "198.51.100.10",
    "ifa": "38400000-8cf0-11bd-b23e-10b96e40000d",
    "os": "Android",
    "make": "Google",
    "devicetype": 4
  },
  "ext": { "pos_id": 202 },
  "at": 1,
  "tmax": 500
}

6.2b Rewarded Video Request

Request JSON{
  "id": "reward-req-003",
  "imp": [
    {
      "id": "1",
      "video": {
        "mimes": ["video/mp4"],
        "w": 640,
        "h": 480,
        "minduration": 15,
        "maxduration": 30,
        "protocols": [3, 6],
        "linearity": 1
      },
      "bidfloor": 2.00,
      "bidfloorcur": "USD",
      "rwdd": 1
    }
  ],
  "app": { "bundle": "com.example.game", "publisher": { "id": "42" } },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)",
    "ip": "198.51.100.20",
    "ifa": "6D92078A-8246-4479-8C7D-A7CF568C5E9E"
  },
  "ext": { "pos_id": 303 },
  "at": 1,
  "tmax": 500
}

6.3 Native Ad Request

Request JSON{
  "id": "native-req-004",
  "imp": [
    {
      "id": "1",
      "native": {
        "request": "{\"ver\":\"1.2\",\"layout\":6,\"adunit\":2,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":100}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"w\":300,\"h\":250}},{\"id\":3,\"required\":1,\"img\":{\"type\":1,\"wmin\":50,\"hmin\":50}},{\"id\":4,\"required\":0,\"data\":{\"type\":2,\"len\":90}}]}",
        "ver": "1.2"
      },
      "bidfloor": 0.80,
      "bidfloorcur": "USD"
    }
  ],
  "app": { "bundle": "com.example.readingapp", "publisher": { "id": "42" } },
  "device": {
    "ua": "Mozilla/5.0 (iPad; CPU OS 16_0 like Mac OS X)",
    "ip": "192.0.2.100",
    "ifa": "7C553443-9D8E-4BE8-B11E-C3D8D3A7B1F3",
    "devicetype": 5
  },
  "ext": { "pos_id": 404 },
  "at": 2,
  "tmax": 300
}

6.4 Bid Response

Response JSON – With Bid{
  "id": "banner-req-001",
  "bidid": "txid-abc123_1",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "Digibid",
      "bid": [
        {
          "id": "txid-abc123_1",
          "impid": "1",
          "price": 0.42,
          "adm": "<div>...banner HTML...</div>",
          "nurl": "https://ads-us-east.digibid.com/tracking?txid=txid-abc123&type=9&...",
          "adid": "dsp-ad",
          "crid": "cr-001",
          "w": 320,
          "h": 50
        }
      ]
    }
  ]
}

Response JSON – No Fill{
  "id": "banner-req-001",
  "seatbid": []
}

6.5 Pounder Request and Response (with ADM Example)

A pounder (popunder) request has imp objects with no banner, native, or video — only fields such as id, instl, secure.

Pounder Request JSON{
  "id": "5ccab55d-a5a5-5555-5e55-aa5b5b55b5a5",
  "at": 1,
  "imp": [
    {
      "id": "555555555",
      "instl": 1,
      "secure": 0
    }
  ],
  "site": {
    "id": "555555",
    "domain": "example.com",
    "cat": ["IAB25-3"],
    "page": "http://example.com"
  },
  "device": {
    "ua": "Mozilla/5.0 (Linux; Android 10; M2006C3LG) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.120 Mobile Safari/537.36",
    "ipv6": "2a00:1756:0a1e:a100:1571:8b01:f36:1d8f",
    "ifa": "5974d090-4516-4565-933d-69c79c9abf75",
    "geo": {
      "country": "UKR",
      "utcoffset": 120
    },
    "language": "ru",
    "os": "Android",
    "js": 1,
    "ext": {
      "remote_addr": "203.0.113.50",
      "x_forwarded_for": ""
    }
  },
  "user": {
    "id": "55f7d5acada5b5.555555555555555555"
  },
  "bcat": ["IAB24", "IAB25", "IAB26"],
  "badv": ["example.com", "example.ru", "example.net"]
}

Pounder Response JSON (with adm example){
  "id": "5ccab55d-a5a5-5555-5e55-aa5b5b55b5a5",
  "bidid": "txid-xxx_imp-1",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "Digibid",
      "bid": [
        {
          "id": "txid-xxx_imp-1",
          "impid": "555555555",
          "price": 0.01,
          "nurl": "https://tracking.example.com/tracking?txid=txid-xxx&did=...&imp=1&type=9&...",
          "burl": "https://tracking.example.com/tracking?txid=txid-xxx&did=...&imp=1&type=10&...",
          "lurl": "https://tracking.example.com/tracking?txid=txid-xxx&did=...&imp=1&type=11&loss=${AUCTION_LOSS}&...",
          "adm": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><ad><popunderAd><url><![CDATA[https://www.landing.example/]]></url></popunderAd></ad>\n<img src=\"https://tracking.example.com/tracking?txid=txid-xxx&imp=1&type=1&iv=1&...\" width=\"1\" height=\"1\" style=\"display:none;border:0;\" alt=\"\" aria-hidden=\"true\"/>",
          "adid": "266",
          "adomain": ["landing.example"],
          "cid": "1",
          "crid": "27",
          "cattax": 3,
          "cat": ["IAB25-3"],
          "w": 192,
          "h": 192
        }
      ]
    }
  ]
}

ADM (ad markup) for pounder: adm is XML with a popunderAd block; url inside CDATA is typically a data:text/html;base64,... page that fires click trackers then navigates to the landing URL (fallback: raw landing URL). This is followed by one or more 1×1 <img> impression tracking pixels. The exchange substitutes ${AUCTION_PRICE} in nurl/burl/lurl when firing; lurl includes loss=${AUCTION_LOSS} for loss reason.

7. Error Codes

8. FAQ

How do I get a pos_id?

Contact your Digibid account manager. A pos_id represents a specific ad placement configuration (publisher margin, position type, allowed formats). One publisher may have multiple pos_ids for different placements.

What happens if there is no fill?

The endpoint always returns HTTP 200 OK with an empty seatbid array. Never interpret a 200 response as a guaranteed fill.

Which DC should I use?

Choose the DC geographically closest to your ad server to minimize latency. Contact your Digibid account manager if you need guidance on DC selection.

Can I send gzip-compressed requests?

Yes. Set Content-Encoding: gzip and gzip the JSON body. Recommended for large native requests.

Digibid Ads Publisher Integration Guide v1.0  ·  For support: publisher-support@digibid.com