api

Sponsored Ads API

active

Audience: developerUpdated 2026-07-28

Exhaustive reference for the Sponsored Ads API — every field of the request and the response. Retail media services use it to request sponsored advertisements from the Binoban platform, tailored to specific products, categories, or keywords.

For the step-by-step integration, see Request and render Sponsored Ads.

Endpoint

POST {rtbPath}/api/rtb/sponsoredAd

rtbPath is the host URL from your connection. This endpoint takes no authentication — do not send an Authorization header.

Headers:

accept: */*
Content-Type: application/json

Request body

Field	Description	Type	Constraints	Mandatory
`productId`	ID of the product to show related ads for (e.g., when user is on a product page)	String	maxLength: 255	No
`categoryId`	ID of the category to show related ads for (e.g., when user is on a category page)	String	maxLength: 255	No
`keyword`	Search keyword to show related ads for (e.g., based on user’s search query)	String	maxLength: 255	No
`id`	Unique UUID to identify the request	String	UUID format	Yes
`adSlotIds`	Array of ad slot IDs for ad placements, predefined in Binoban’s back-office (contact Binoban team for setup)	Array[Integer]	$int32	Yes
`mediaSource`	Details of the media source sending the request	Object	-	No
`mediaSource.type`	Type of the media source (e.g., app or website)	String	Enum: `APP`, `SITE`	Yes
`mediaSource.page`	Full URL of the page being viewed	String	maxLength: 512	No
`mediaSource.version`	Version of the application (if applicable)	String	maxLength: 100	No
`mediaSource.properties`	Additional key-value pairs for future use	Object	Arbitrary key-value pairs	No
`device`	Device information for the request	Object	-	No
`device.userAgent`	User agent of the device	String	maxLength: 512	No
`device.ip`	IP address of the device	String	maxLength: 45	No
`device.model`	Device model (e.g., iPhone 14)	String	maxLength: 100	No
`device.width`	Screen width in pixels	Integer	$int32	No
`device.height`	Screen height in pixels	Integer	$int32	No
`device.operatingSystem`	Operating system of the device	String	Enum: `ANDROID`, `IOS`, `IPOD`, `LINUX`, `WINDOWS`, `MAC`	No
`device.browser`	Browser used by the device	String	Enum: `CHROME`, `SAFARI`, `EDGE`, `INTERNET_EXPLORER`, `FIREFOX`, `CHROMIUM`, `FACEBOOK_IN_APP_BROWSER`, `WEBVIEW`, `SAMSUNG_BROWSER`, `GOOGLE_SEARCH_APP`, `ANDROID_APP`, `OPERA`, `MIUI_BROWSER`, `AMAZON_SILK`, `UC_BROWSER`, `YANDEX`, `APPLE_IN_APP_BROWSER`	No
`device.deviceType`	Type of the device	String	Enum: `MOBILE`, `TABLET`, `DESKTOP`, `TV`, `CONNECTED_DEVICE`, `SET_TOP_BOX`	No
`user`	User information for the request	Object	-	No¹
`user.id`	Device identifier (from Binoban SDK), critical for conversion tracking; recommended to include for accurate attribution	String	maxLength: 255	No¹
`user.userId`	ID of the logged-in user	String	maxLength: 255	No¹
`timeout`	Request timeout in milliseconds (default: 200ms for ad networks)	Number	-	No

¹ The user (user.id or user.userId or both) field is highly recommended for conversion tracking to ensure accurate attribution, ideally sourced from the Binoban SDK. See Web SDK reference → Identity for complete details.

Example request

{
  "productId": "shoe123",
  "categoryId": "cat456",
  "keyword": "sneakers",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "adSlotIds": [
    1073741824
  ],
  "mediaSource": {
    "id": "source789",
    "name": "Sneaker Store Homepage",
    "domain": "example.com",
    "type": "SITE",
    "page": "https://www.example.com/home",
    "version": "1.0.0",
    "properties": {
      "theme": "dark",
      "region": "US"
    }
  },
  "device": {
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1",
    "ip": "192.168.1.1",
    "model": "iPhone 14",
    "width": 1170,
    "height": 2532,
    "operatingSystem": "IOS",
    "browser": "SAFARI",
    "deviceType": "MOBILE"
  },
  "user": {
    "id": "device123",
    "userId": "user789"
  },
  "timeout": 200
}

Response body (200 OK)

Field	Description	Type	Constraints
`ads`	Array of advertisements for the requested ad slots	Array[Object]	-
`ads[].adSlotId`	ID of the ad slot this ad is for	Integer	$int32
`ads[].type`	Type of the advertisement	String	Enum: `BRAND`, `DISPLAY_BANNER`, `DISPLAY_NATIVE`, `PRODUCT`
`ads[].brand`	Name of the brand (for `BRAND` type)	String	maxLength: 255
`ads[].products`	List of products (for `BRAND` and `PRODUCT` types)	Array[Object]	-
`ads[].products[].id`	Product ID in the marketplace	String	maxLength: 255
`ads[].products[].bidId`	Unique ID of the ad for tracking and analytics	String	UUID format
`ads[].products[].sellerId`	ID of the seller for the product	String	maxLength: 255
`ads[].products[].variantId`	ID of the product variant	String	maxLength: 255
`ads[].products[].url`	Product url on website	String	maxLength: 255
`ads[].products[].variantUrl`	Specific Url for this variant and seller	String	maxLength: 255
`ads[].banner`	URL of the banner image (for `DISPLAY_BANNER` type)	String	maxLength: 512
`ads[].width`	Width of the banner in pixels (for `DISPLAY_BANNER` type)	Integer	$int32
`ads[].height`	Height of the banner in pixels (for `DISPLAY_BANNER` type)	Integer	$int32
`ads[].landing_url`	URL where the user lands after clicking the ad (for `DISPLAY_BANNER` and `DISPLAY_NATIVE` types)	String	maxLength: 512
`ads[].bidId`	Unique ID of the ad for tracking and analytics (for `DISPLAY_BANNER` and `DISPLAY_NATIVE` types)	String	UUID format
`ads[].natives`	List of native ad components (for `DISPLAY_NATIVE` type)	Array[Object]	-
`ads[].natives[].image`	URL of the main image for the native ad	String	maxLength: 512
`ads[].natives[].title`	Title of the native ad	String	maxLength: 255
`ads[].natives[].logo`	URL of the logo (e.g., ad network, marketplace, or advertiser logo)	String	maxLength: 512
`ads[].natives[].icon`	URL of the icon for the native ad	String	maxLength: 512
`ads[].natives[].cta`	Call to Action button text (e.g., "Shop Now", "Learn More") to drive user interaction	String	maxLength: 100
`ads[].natives[].landing_url`	URL where the user lands after clicking the native ad	String	maxLength: 512
`ads[].natives[].bidId`	Unique ID of the native ad for tracking and analytics	String	UUID format

Example response (200 OK)

{
  "ads": [
    {
      "adSlotId": 1073741824,
      "brand": "Nike",
      "products": [
        {
          "id": "shoe123",
          "bidId": "550e8400-e29b-41d4-a716-446655440001",
          "sellerId": "seller789",
          "variantId": "var123"
        }
      ],
      "type": "BRAND"
    },
    {
      "adSlotId": 1073741824,
      "banner": "https://cdn.example.com/ads/banner.jpg",
      "width": 300,
      "height": 250,
      "landing_url": "https://www.example.com/products/sneakers",
      "bidId": "550e8400-e29b-41d4-a716-446655440002",
      "type": "DISPLAY_BANNER"
    },
    {
      "adSlotId": 1073741824,
      "natives": [
        {
          "image": "https://cdn.example.com/ads/native-image.jpg",
          "title": "Explore New Sneakers",
          "logo": "https://cdn.example.com/ads/nike-logo.png",
          "icon": "https://cdn.example.com/ads/icon.png",
          "cta": "Shop Now",
          "landing_url": "https://www.example.com/products/sneakers",
          "bidId": "550e8400-e29b-41d4-a716-446655440003"
        }
      ],
      "type": "DISPLAY_NATIVE"
    },
    {
      "adSlotId": 1073741824,
      "products": [
        {
          "id": "shoe456",
          "bidId": "550e8400-e29b-41d4-a716-446655440004",
          "sellerId": "seller456",
          "variantId": "var456"
        }
      ],
      "type": "PRODUCT"
    }
  ]
}

Notes

At least one of productId, categoryId, or keyword should be provided to determine the context of the ads (product page, category page, or search results).
Request Processing Priority: The processing of requests follows this priority order for the provided context fields:
1. productId: If productId is provided, it takes the highest priority, and categoryId is ignored. You may omit categoryId in this case, as it will not be considered.
2. categoryId: If no productId is provided, categoryId is used to determine the ad context.
3. keyword: If neither productId nor categoryId is provided, keyword is used to tailor the ads.
Ad Slot Context: Sponsored ad requests are processed based on the context of the adSlotIds provided in the request. Each ad slot has a predefined context, as outlined in Ad Slots & Formats. This context determines how the ad slot is filled. For example:
- If the ad slot’s context is a product listing page, the ad slot is filled exclusively with campaigns using promotion targeting, and the provided productId, categoryId, or keyword fields are ignored. In this case, the products displayed may belong to different categories and are selected based on the promotion context rather than the provided input fields.
The adSlotIds field is mandatory and must contain valid slot IDs predefined in Binoban’s back-office. Contact the Binoban team to configure ad slots.
The mediaSource object requires only the type field (APP or SITE). Other fields (name, domain, etc.) are optional.
The user field is highly recommended for conversion tracking to ensure accurate attribution, ideally sourced from the Binoban SDK.
The timeout field specifies the maximum time to wait for a response in milliseconds (default: 200ms for ad networks).
The ads array in the response contains advertisements tailored to the requested adSlotIds. Each ad slot has a specific type (BRAND, DISPLAY_BANNER, DISPLAY_NATIVE, PRODUCT) with corresponding fields.
For DISPLAY_NATIVE ads, the cta field (Call to Action) is a button text (e.g., "Shop Now", "Learn More", "Buy Now") designed to drive user interaction, making the ad more engaging and aligned with the publisher’s site style. Native ads blend seamlessly with a platform's content, matching its style for higher engagement (e.g., sponsored posts in feeds). OpenRTB, an IAB standard, supports Native ads since version 2.3 via a Native Object, enabling SSPs to request assets (e.g., Title, Image, CTA) and DSPs to respond with tailored ads in real-time auctions. This ensures scalable, engaging ad delivery with minimal disruption.
All bidId fields in the response (products[].bidId, bidId, natives[].bidId) would be in UUID format for tracking and analytics.

landing_url vs landingUrl

This API's native/banner destination field is landing_url (snake_case) — different from the Ad Request API's landingUrl / targetUrl (camelCase). This is a pre-existing, intentional difference between the two endpoints; don't "fix" one to match the other.

Request and render Sponsored Ads — the how-to that uses this endpoint.
Ad Request API — the display-ads counterpart.
Ad Slots & Formats — where adSlotIds and their contexts come from.
Track ad impressions and clicks — reporting impressions, clicks, and loads.

Endpoint​

Request body​

Example request​

Response body (200 OK)​

Example response (200 OK)​

Notes​

Related​