Request Structure

{
  "id": "string",
  "imp": [...],
  "site": {...},
  "user": {...},
  "at": 1,
  "tmax": 800,
  "regs": {...},
  "ext": {...}
}

Required Parameters

`id` (string, required)

Unique identifier for this bid request.

Example: "request-123", "4e343884ce8ec3"

Best practice: Include timestamp for traceability: req-${Date.now()}

`imp` (array, required)

Array of impression objects. At least one impression is required.

Example:

"imp": [
  {
    "id": "1",
    "banner": {
      "format": [{"w": 300, "h": 250}]
    }
  }
]

`site` (object, required)

Site information where the ad will appear.

Example:

"site": {
  "id": "HOMEPAGE",
  "domain": "example.com"
}

Impression Parameters

`imp[].id` (string, required)

Unique identifier for this impression within the request.

Example: "imp-1", "header", "sidebar"

`imp[].tagid` (string, optional)

Ad slot identifier or tag name.

Example: "branding", "sidebar", "footer"

Use case: Identify specific ad slots in your site.

`imp[].secure` (integer, optional)

Requires HTTPS creatives.

1 = HTTPS required
0 = HTTP allowed

Default: 0

Recommendation: Always use 1 for secure sites.

`imp[].banner` (object, required for banner ads)

Banner ad specification.

Example:

"banner": {
  "format": [
    {"w": 300, "h": 250},
    {"w": 728, "h": 90}
  ]
}

banner.format - Array of size objects with width (w) and height (h).

`imp[].native` (object, required for native ads)

Native ad specification.

Example:

"native": {
  "request": "{}"
}

Note: native.request should be JSON string with OpenRTB Native spec.

`imp[].bidfloor` (float, optional)

Minimum bid price for this impression (CPM).

Format: Float value in network currency

Default: 0.0

Example: 2.50 (means $2.50 CPM minimum)

Use case: Set minimum acceptable bid price to protect inventory value.

Note: Can be overridden by imp[].ext.efp (encoded bid floor) if both are present.

Site Parameters

`site.id` (string, required)

Site identifier.

Example: "HOMEPAGE", "TECH_SECTION", "GLOWNA"

Use case: Different sections may have different inventories.

`site.domain` (string, required)

Site domain name.

Example: "example.com", "onet.pl"

`site.page` (string, optional)

Full page URL where ad will appear.

Example: "https://example.com/articles/tech-news"

Use case: Contextual targeting based on page content.

`site.publisher` (object, optional)

Publisher information.

Example:

"publisher": {
  "id": "pub-123",
  "domain": "example.com"
}

Site Extensions (`site.ext`)

`site.ext.area` (string, optional)

Site section identifier.

Example: "TECH", "LIFESTYLE", "NEWS", "ROS"

Default: "ROS" (if not specified)

Use case: Target specific site sections.

`site.ext.kwrd` (string, optional)

Keywords separated by plus signs.

Example: "technology+gadgets+smartphones"

Use case: Contextual targeting based on page keywords.

`site.ext.dv` (string, optional)

Device/platform/location string.

Format: {platform}/{section}/{location}

Example: "www/TECH/NONE", "mobile/NEWS/PL"

User Parameters

`user.ext.ids` (object, optional)

User identifiers for targeting and frequency capping.

Example:

"user": {
  "ext": {
    "ids": {
      "lu": "202408221036415499301131",
      "aid": "hashed-user-id",
      "sid": "your-persistent-user-or-session-id"
    }
  }
}

`user.ext.ids.lu` (string, optional)

Local user ID - anonymous browser identifier.

Format: Timestamp-based string or cookie value.

Length: Typically 24 characters (e.g., 201905161437551994208900)

Validation:

Alphanumeric characters (0-9, a-z, A-Z)
Maximum length: 128 characters
No special characters or spaces

Use case: Frequency capping, cross-session tracking (anonymous).

`user.ext.ids.aid` (string, optional)

Advertising ID - logged-in user identifier (hashed).

Format: Hashed email or user ID (typically MD5).

Length: Typically 64 characters for MD5 hash

Validation:

Hexadecimal characters (0-9, a-f, A-F) for hashed values
Maximum length: 128 characters
No special characters or spaces

Use case: Personalization, cross-device targeting.

`user.ext.ids.sid` (string, optional)

Custom user/session identifier provided by the integrating party.

Format: Free-form string. No specific format constraints — the integrator can use any persistent, unique value (e.g., internal user ID, session token, device identifier).

Use case: Frequency capping, budget pacing, attribution, and cross-session tracking. The integrating party is responsible for ensuring the value is persistent and consistent per user.

`user.ext.npa` (boolean, optional)

Non-personalized ads flag.

true = No personalization (privacy mode)
false = Personalization allowed (default)

Use case: GDPR compliance, privacy preferences.

`user.ext.localcapping` (string, optional)

Frequency capping data for this user.

Format: Internal capping data string.

Use case: Advanced frequency management.

`user.eids` (array, optional)

OpenRTB-standard Extended Identity Array. Used to pass user identifiers with per-ID GDPR consent metadata.

Can coexist with user.ext.ids — both are supported simultaneously in the same request.

Field	Type	Description
`user.eids[].source`	string	Identity provider domain, e.g. `"your-domain.com"`
`user.eids[].inserter`	string	Party that inserted the EID, e.g. `"your-domain.com"`
`user.eids[].uids[].id`	string	The user identifier value
`user.eids[].uids[].atype`	integer	`1` = device-level, `500` = custom/session-level
`user.eids[].uids[].ext.id_type`	string	`"session"` or `"tracking"`
`user.eids[].uids[].ext.consent_required`	boolean	`true` = GDPR consent required

Example:

"user": {
  "eids": [
    {
      "source": "your-domain.com",
      "inserter": "your-domain.com",
      "uids": [
        {
          "id": "1772048521...",
          "atype": 500,
          "ext": { "id_type": "session", "consent_required": false }
        },
        {
          "id": "2983157634...",
          "atype": 1,
          "ext": { "id_type": "tracking", "consent_required": true }
        }
      ]
    }
  ]
}

Relation to user.ext.ids.lu: The lu field is Ring DAS's internal session identifier. Both lu and user.eids can be sent in the same request.

Impression Extensions (`imp[].ext`)

`imp[].ext.pos` (integer, optional)

Ad position on page.

0 = Unknown
1 = Above the fold
3 = Below the fold

Use case: Position-based pricing and targeting.

`imp[].ext.efp` (string, optional)

Encoded bid floor token.

Format: Encoded string containing the floor price value.

Priority: Overrides imp[].bidfloor if both are present.

Example: "efp": "c.fb"

Use case:

Dynamic floor pricing from server-side logic
Protect floor price values from client-side inspection
Advanced yield optimization strategies

`imp[].ext.swidth` (integer, optional)

Slot width for responsive ads.

Example: 728, 300

Use case: Responsive ad selection.

`imp[].ext.offerids` (array of strings, optional)

List of specific offer IDs from product catalog to prioritize.

Format: Array of offer ID strings

Example: ["offer-123", "offer-456", "offer-789"]

Use case:

Retail Media Network (RMN) campaigns
Product-specific ad targeting
Catalog-based creative rendering
Sponsored product ads

Note: Used with Offer Decision Engine for personalized product ads.

`imp[].ext.websiteid` (integer, optional)

Website or store identifier

Format: Integer website ID

Example: 12345

Use case:

Multi-store retail media campaigns
Store-specific product catalogs
Website-level targeting and reporting
Marketplace vendor segregation

Note: Links impression to specific eCommerce website/store in the network.

`imp[].ext.categoryids` (array of integers, optional)

Product category IDs for contextual product targeting.

Format: Array of category ID integers

Example: [101, 205, 330]

Use case:

Category-based product targeting
Contextual product recommendations
Product catalog filtering
Category-level performance optimization

Note: Uses VAST Product Catalog categories unless should_use_store_category_matching is enabled.

`imp[].ext.should_use_non_context_offers` (boolean, optional)

Enable non-contextual offers for broader reach (Products emission logic).

Format: Boolean flag

Default: false

Example: true

Use case:

false (default): Show only contextual offers based on user behavior (Max Conversion Rate / Balanced strategy)
true: Include popular/placeholder offers when no user context available (Max Range strategy)

Strategy mapping:

Max Conversion Rate: false (user must have viewed/added products)
Balanced: false (user must have category interest)
Max Range: true (reach-focused, any user)

Note: Affects audience reach vs. conversion rate trade-off.

`imp[].ext.min_in_context_offers` (integer, optional)

Minimum number of in-context offers required for RMN candidate eligibility.

Format: Integer (must be positive)

Default: 1

Example: 2

Validation:

Must be greater than 0
Values ≤ 0 will cause candidate rejection

Use case:

Quality control for RMN campaigns
Ensure sufficient personalized offers before showing ad
Balance between reach and relevance

How it works:

Counts offers marked as "in-context"
If insufficient in-context offers, candidate is rejected

Example scenarios:

min_in_context_offers: 1 (default): Show ad if at least 1 offer
min_in_context_offers: 3: Require 3+ in-context offers for higher relevance

Note: Works with RMN offer selection and contextual targeting strategies.

`imp[].ext.should_use_store_category_matching` (boolean, optional)

Use store-specific category taxonomy instead of central catalog categories.

Format: Boolean flag

Default: false

Example: true

Use case:

false (default): Use standardized central product catalog categories
true: Use retailer's native category taxonomy

When to use:

Retailer has unique/atypical categorization system
Better match with store's product organization

Note: Works in conjunction with categoryids and offerids parameters.

Auction Parameters

`at` (integer, optional)

Auction type.

1 = First-price auction (default)
2 = Second-price auction

Default: 1

`tmax` (integer, optional)

Maximum processing time in milliseconds.

Range: 100-5000ms

Default: 800ms

Extended: 2000ms (when ext.adbeta is set)

Example:

"tmax": 800

Use case: Balance between response time and bid quality.

Privacy & Compliance Parameters

`regs.gdpr` (integer, optional)

GDPR applies flag.

1 = GDPR applies
0 = GDPR does not apply

Use case: EU user privacy compliance.

Example:

"regs": {
  "gdpr": 1
}

`regs.ext.dsa` (integer, optional)

Digital Services Act compliance required.

1 = DSA applies (response includes DSA URL)
0 = DSA does not apply

Use case: EU transparency requirements.

Example:

"regs": {
  "ext": {
    "dsa": 1
  }
}

Request Extensions (`ext`)

`ext.network` (string, optional)

Network ID.

Must match the {network_id} in the URL path.

Example:

"ext": {
  "network": "7012768"
}

`ext.adbeta` (string, optional)

Shows an ad without producing any events (for testing/demo purposes)

Effect: Enables extended timeout (2000ms instead of 800ms).

Example: "l1011816!slot.flat-link-wiadomosci2", "pl1025931!slot.right"

Use case: Demonstration or Tests

`ext.keyvalues` (object, optional)

Custom targeting key-value pairs.

Example:

"ext": {
  "keyvalues": {
    "category": "technology",
    "section": "news",
    "custom_tag": "featured"
  }
}

Note: System automatically adds enrichment fields like browser, os, geoip_*.

Known Standard Keys

The following keys are used by Ring DAS retail media formats:

`ext.keyvalues.manufacturer_id` (string, conditional)

Brand or manufacturer identifier. Required for Brand Store format — determines which brand's campaign to display.

Example: "manufacturer_id": "12345678"

Use case: Brand Store ad matching and campaign selection.

`ext.keyvalues.main_category_id` (integer, conditional)

Main product category ID of the page context

Example: "main_category_id": 101

Use case: Primary signal for ad matching and reporting. A product may belong to multiple categories, but has one main category.

`ext.keyvalues.page_product_id` (string, conditional)

Product identifier of the currently viewed product.

Example: "page_product_id": "987654"

Use case: Reporting purposes — associates ad impressions and clicks with specific products.

`ext.keyvalues.page_product_name` (string, conditional)

Display name of the currently viewed product.

Example: "page_product_name": "Nike Air Max 90"

Use case: Reporting purposes — human-readable product label in analytics.

`ext.keyvalues.page_type` (string, conditional)

Page context type.

Values: SEARCH, CATEGORY

Example: "page_type": "SEARCH"

Use case: Contextual targeting — determines which ad variants are eligible based on page intent.

`ext.keyvalues.search_query` (string, optional)

User's search query string. Used with Sponsored Single Tile on SEARCH pages.

Example: "search_query": "nike shoes"

Use case: Keyword-level targeting and reporting for search-triggered ads.

`ext.keyvalues.IP` (string, optional)

Page View ID — set once per page load and stays constant for the lifetime of that page (e.g. "202603041502158687149647"). In SPAs, the value does not change between view transitions.

Use case: Identifying all ad requests originating from the same page load, cross-request correlation.

`ext.keyvalues.IV` (string, optional)

Page View Unique ID — changes on every logical view change, including SPA navigation (route change without full page reload) (e.g. "202603041502158687149647"). On traditional multi-page sites, equals IP.

Use case: Deduplication and attribution per unique view — especially useful in SPAs where multiple views share the same IP.

`ext.keyvalues.TABID` (string, optional)

Browser Tab Identifier — stable ID per browser tab session (e.g. "tab-7f3e2a").

Use case: Per-tab frequency capping, multi-tab session analysis.

`ext.keyvalues.ab_variant` (string, optional)

A/B test variant identifier — string identifying which experiment variant the user is currently assigned to (e.g. "variant-b", "control", "treatment-1").

Use case: Segment ad delivery and reporting by experiment variant. Allows correlating ad performance metrics with A/B test outcomes.

`ext.excluded_adids` (array, optional)

List of ad IDs to exclude from this request.

Example:

"ext": {
  "excluded_adids": ["das,1234,5678", "das,9012,3456"]
}

Use case: Frequency capping, competitive exclusion.

`ext.excluded_offer_ids` (array of strings, optional)

List of offer IDs already shown as organic content on the same page — prevents the same offer appearing both organically and as a sponsored tile.

Format: Array of offer ID strings

Example:

"ext": {
  "excluded_offer_ids": ["10", "102", "305"]
}

Use case: Deduplication between organic product listings and sponsored tiles.

`ext.is_non_prebid_request` (boolean, optional)

Indicates direct integration (non-Prebid).

true = Direct integration
false = Prebid integration (default)

Use case: Direct ad serving integration (without header bidding), slot targeting

Complete Parameter Example

Standard Display Ad Request

{
  "id": "complete-example-123",
  "imp": [
    {
      "id": "header-banner",
      "tagid": "header",
      "secure": 1,
      "bidfloor": 2.50,
      "banner": {
        "format": [
          {"w": 728, "h": 90},
          {"w": 970, "h": 90}
        ]
      },
      "ext": {
        "pos": 1,
        "swidth": 728,
        "efp": "c.fb"
      }
    }
  ],
  "site": {
    "id": "TECH_SECTION",
    "domain": "example.com",
    "page": "https://example.com/tech/article",
    "publisher": {
      "id": "pub-123",
      "domain": "example.com"
    },
    "ext": {
      "area": "TECH",
      "kwrd": "technology+gadgets",
      "dv": "www/TECH/NONE"
    }
  },
  "user": {
    "eids": [
      {
        "source": "your-domain.com",
        "inserter": "your-domain.com",
        "uids": [
          {
            "id": "1772048521...",
            "atype": 500,
            "ext": { "id_type": "session", "consent_required": false }
          },
          {
            "id": "2983157634...",
            "atype": 1,
            "ext": { "id_type": "tracking", "consent_required": true }
          }
        ]
      }
    ],
    "ext": {
      "ids": {
        "lu": "202408221036415499301131",
        "aid": "hashed-user-123"
      },
      "npa": false
    }
  },
  "at": 1,
  "tmax": 800,
  "regs": {
    "gdpr": 1,
    "ext": {
      "dsa": 1
    }
  },
  "ext": {
    "network": "7012768",
    "keyvalues": {
      "category": "technology",
      "IP": "202603041502158687149647",
      "IV": "202603041502158687149647",
      "TABID": "tab-7f3e2a",
      "ab_variant": "variant-b"
    }
  }
}

Standard Retail Media Ad Request

 {                                                                                                                                                                             
    "id": "rmn-sponsored-products-456",                                                                                                                                         
    "imp": [                                                                                                                                                                    
      {                                                                                                                                                                         
        "id": "rmn-sponsored-product-1234",                                                                                                                                               
        "tagid": "rmn-sponsored-product",                                                                                                                                           
        "secure": 1,                                                                                                                                                            
        "ext": {                                                                                                                                                                
          "pos": "1",                                                                                                                                                           
          "websiteid": 12345,                                                                                                                                                   
          "offerids": ["offer-abc123", "offer-def456", "offer-ghi789"],                                                                                                                               
          "efp": "f.bb",                                                                                                                                                        
          "should_use_store_category_matching": true,                                                                                                                           
          "should_use_non_context_offers": false,                                                                                                                               
          "min_in_context_offers": 2                                                                                                                                            
        },                                                                                                                                                                      
        "banner": {                                                                                                                                                             
          "format": [                                                                                                                                                           
            {"w": 1200, "h": 300}                                                                                                                                               
          ]                                                                                                                                                                     
        }                                                                                                                                                                       
      }                                                                                                                                                                         
    ],                                                                                                                                                                          
    "site": {                                                                                                                                                                   
      "domain": "shop.example.com",                                                                                                                                             
      "publisher": {                                                                                                                                                            
        "domain": "shop.example.com"                                                                                                                                            
      },                                                                                                                                                                        
      "id": "ECOMMERCE_HOME",                                                                                                                                                   
      "page": "https://shop.example.com/",                                                                                                                                      
      "ext": {                                                                                                                                                                  
        "area": "HOMEPAGE",                                                                                                                                                     
        "kwrd": "electronics+smartphones+accessories",                                                                                                                          
        "dv": "www/HOMEPAGE/NONE",                                                                                                                                              
        "mode": "rmn",                                                                                                                                                          
        "data": {                                                                                                                                                               
          "documentLang": "en"                                                                                                                                                  
        }                                                                                                                                                                       
      }                                                                                                                                                                         
    },                                                                                                                                                                          
    "user": {
      "eids": [
        {
          "source": "your-domain.com",
          "inserter": "your-domain.com",
          "uids": [
            {
              "id": "1772048521...",
              "atype": 500,
              "ext": { "id_type": "session", "consent_required": false }
            },
            {
              "id": "2983157634...",
              "atype": 1,
              "ext": { "id_type": "tracking", "consent_required": true }
            }
          ]
        }
      ],
      "ext": {
        "ids": {
          "lu": "202508221036415499301131"
        }
      }
    },
    "ext": {                                                                                                                                                                    
      "network": "7012768",                                                                                                                                                     
      "keyvalues": {
        "IP": "202603041502158687149647",
        "IV": "202603041502158687149647",
        "TABID": "tab-7f3e2a",
        "ab_variant": "variant-b"
      },
      "is_non_prebid_request": true,                                                                                                                                            
      "websiteid": 6070,                                                                                                                                                        
      "offerids": [                                                                                                                                                             
        "111",                                                                                                                                                                  
        "222",                                                                                                                                                                  
        "333"                                                                                                                                                                   
      ]                                                                                                                                      
    },                                                                                                                                                                          
    "at": 1,                                                                                                                                                                    
    "tmax": 800,                                                                                                                                                                
    "regs": {                                                                                                                                                                   
      "ext": {                                                                                                                                                                  
        "dsa": 1                                                                                                                                                                
      },                                                                                                                                                                        
      "gdpr": 1                                                                                                                                                                 
    }                                                                                                                                                                           
  }

RMN Example Explanation:

offerids: Pre-selected sponsored products from catalog.
websiteid: Links to specific store/retailer in network
categoryids: Product categories (electronics, smartphones, accessories). Sometimes used instead of offerids. If present it overrides categories inferred from offerids
should_use_non_context_offers: false: Only show products user has interest in (Max Conversion Rate strategy)
should_use_store_category_matching: true: Use retailer's native category taxonomy instead of central product catalog
min_in_context_offers: 2: Require at least 2 personalized offers for quality control

Use case: Sponsored product carousel on eCommerce homepage showing personalized product recommendations based on user's browsing history and category interests.

Parameter Validation

The API validates:

Required fields present
Data types correct
Value ranges within limits
Format matches specification

Invalid requests return HTTP 400 with error details.