Reference Guide

API Parameters Reference

Complete reference of request parameters for the Ad Decision Engine.

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.

FieldTypeDescription
user.eids[].sourcestringIdentity provider domain, e.g. "your-domain.com"
user.eids[].inserterstringParty that inserted the EID, e.g. "your-domain.com"
user.eids[].uids[].idstringThe user identifier value
user.eids[].uids[].atypeinteger1 = device-level, 500 = custom/session-level
user.eids[].uids[].ext.id_typestring"session" or "tracking"
user.eids[].uids[].ext.consent_requiredbooleantrue = 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 }
        }
      ]
    }
  ]
}
info

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.

Updated 4 months ago

Updated 4 months ago