Ad Request API

Exhaustive reference for the Ad Request API — every field of the request and the response. Publishers use it to request advertisements from the Binoban platform for predefined ad slots via real-time bidding (RTB).

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

Endpoint

POST {rtbPath}/api/rtb/ad

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
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	-	Yes
mediaSource.type	Type of the media source (e.g., app or website)	String	Enum: APP, SITE	Yes
mediaSource.pageUrl	Full URL of the page being viewed	String	maxLength: 512	No
mediaSource.version	Version of the application (if applicable)	String	maxLength: 100	No
mediaSource.pageTitle	Title of the page being viewed	String	maxLength: 255	No
mediaSource.pageCategory	Category of the page	String	maxLength: 255	No
mediaSource.pageDescription	Description of the page	String	maxLength: 512	No
mediaSource.pageRef	Referrer URL or reference page	String	maxLength: 512	No
mediaSource.keywords	Array of keywords related to the page	Array[String]	-	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	Number	-	Yes

¹ The user.id or user.userId (or both) fields are highly recommended for conversion tracking to ensure accurate attribution. These values should be obtained from the Binoban Web SDK using Binoban.user().id() and Binoban.user().anonymousId(). See Web SDK reference → Identity for complete details.

Example request

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "adSlotIds": [
    7
  ],
  "mediaSource": {
    "type": "SITE",
    "pageUrl": "https://www.example.com/home",
    "version": "1.0.0",
    "pageTitle": "Sneaker Store Homepage",
    "pageCategory": "home",
    "pageDescription": "Welcome to the best sneaker store",
    "pageRef": "https://www.example.com/referral",
    "keywords": [
      "sneakers",
      "shoes"
    ],
    "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[].ui	Additional UI configuration properties (arbitrary key-value pairs for rendering the ad)	Object	Arbitrary key-value pairs
ads[].template	Specific template for the ad format	String	e.g. BANNER_STICKY, NATIVE_NOTIF
ads[].banners	List of banner advertisements (present when type is BANNERS)	Array[Object]	-
ads[].banners[].bidId	Unique ID of the bid for tracking and analytics	String	UUID format
ads[].banners[].banner	URL of the banner image	String	maxLength: 512
ads[].banners[].campaignId	ID of the campaign	Integer	$int32
ads[].banners[].targetUrl	The advertiser's destination, set in their campaign	String	maxLength: 512
ads[].banners[].clickUrl	Tracker URL that counts the click, then redirects to targetUrl	String	maxLength: 512
ads[].banners[].title	Title of the banner ad	String	maxLength: 255
ads[].width	Width of the ad in pixels (for banner types)	Integer	$int32
ads[].height	Height of the ad in pixels (for banner types)	Integer	$int32
ads[].type	Type of the advertisement	String	Enum: BANNERS, NATIVE
ads[].natives	List of native advertisements (present when type is NATIVE)	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[].bidId	Unique ID of the native ad for tracking and analytics	String	UUID format
ads[].natives[].landingUrl	The advertiser's destination, set in their campaign	String	maxLength: 512
ads[].natives[].clickUrl	Tracker URL that counts the click, then redirects to landingUrl	String	maxLength: 512
ads[].natives[].campaignId	ID of the campaign	Integer	$int32
ads[].natives[].logo	URL of the 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	String	maxLength: 100

Example response (200 OK)

{
  "ads": [
    {
      "adSlotId": 1073741824,
      "ui": {
        "theme": "dark"
      },
      "template": "BANNER_STICKY",
      "banners": [
        {
          "bidId": "550e8400-e29b-41d4-a716-446655440001",
          "banner": "https://cdn.example.com/ads/banner.jpg",
          "campaignId": 123456,
          "targetUrl": "https://www.example.com/products/sneakers",
          "clickUrl": "https://www.example.com/api/tracker/ad/click?bidId=550e8400-e29b-41d4-a716-446655440001&redirectURL=<base64 of targetUrl>",
          "title": "Nike Sneakers Sale"
        }
      ],
      "width": 300,
      "height": 250,
      "type": "BANNERS"
    },
    {
      "adSlotId": 1073741824,
      "ui": {
        "position": "bottom"
      },
      "template": "NATIVE_NOTIF",
      "natives": [
        {
          "image": "https://cdn.example.com/ads/native-image.jpg",
          "title": "Explore New Sneakers",
          "bidId": "550e8400-e29b-41d4-a716-446655440003",
          "landingUrl": "https://www.example.com/products/sneakers",
          "clickUrl": "https://www.example.com/api/tracker/ad/click?bidId=550e8400-e29b-41d4-a716-446655440003&redirectURL=<base64 of landingUrl>",
          "campaignId": 123457,
          "logo": "https://cdn.example.com/ads/nike-logo.png",
          "icon": "https://cdn.example.com/ads/icon.png",
          "cta": "Shop Now"
        }
      ],
      "type": "NATIVE"
    }
  ]
}

Notes

• The id, adSlotIds, mediaSource.type, and timeout fields are mandatory.
• The user.id and/or user.userId fields are highly recommended for conversion tracking to ensure accurate attribution, ideally sourced from the Binoban SDK using Binoban.user().id() and Binoban.user().anonymousId().
• The ads array in the response contains advertisements for the requested adSlotIds. Each entry includes a type (BANNERS or NATIVE) with the corresponding banners or natives array, plus a template for specific rendering instructions.
• The ui object can contain any additional key-value pairs needed for custom UI rendering of the ad.
• The adSlotIds must be valid slot IDs predefined in Binoban’s back-office. Contact the Binoban team to configure ad slots.

Related

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