Skip to content

Nimbus S2S Documentation

Jump to bottom
Marc Santiago edited this page Oct 22, 2019 · 42 revisions

Nimbus Publisher API Documentation

The Nimbus ad server is Open Real-Time Bidding (ORTB) version 2.5 compliant, however please review below as the spec has been optimized for communication performance around the Nimbus specific hybrid auctions.

Endpoint: https://[ask_project_manager].adsbynimbus.com/rta/v1 Method: POST

Request Headers

The following headers are required with the request:

  • Content-Type: application/json
  • x-openrtb-version: 2.5

It is also suggested that the following headers are also sent along with the request

  • Content-Encoding: gzip

Note: Nimbus is http/2 compatible and it is also recommend to use http/2 if possible

Object: BidRequest

Atribute Type Description
imp object array; required Array of ORTB 2.5 objects, currently only an array of size 1 is valid, see section 3.2.4
app object; required See ORTB 2.5 section 3.2.14
device object; required See ORTB 2.5 section 3.2.18
format object; required See ORTB 2.5 section 3.2.10. This is a Nimbus modification which allows the device height and width to be passed outside of the banner and video objects, this is used for demand partners that are not yet on the ORTB spec
user object; recommended See ORTB 2.5 section 3.2.18
test integer; default 0 Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode
wseat string array; See ORTB section 3.2.1
bseat string array; See ORTB section 3.2.1
wlang string array; See ORTB section 3.2.1
bcat string array; See ORTB section 3.2.1
badv string array; See ORTB section 3.2.1
bapp string array; See ORTB section 3.2.1
source object; Source object is needed if using the OM SDK
regs object; recommended See ORTB 2.5 section 3.2.1
ext object; required Nimbus specific extension needed for authentication validation

Object: Ext (BidRequest extension object)

Atribute Type Description
api_key string; required Needed to validate the request to Nimbus, please ask your ad manager for this key
session_id string; required Needed for tracing and potential client side rate limiting, this id should be passed for each ad request, for the entire user session

Object: Regs

Atribute Type Description
coppa integer See ORTB 2.5 section 3.2.3
ext object; recommended See ORTB 2.5 section 3.2.3, to be GDPR compliant, the consent value is passed in this extension

Object: Ext (Regs extension object)

Atribute Type Description
gdpr integer; default 0 See section gdpr compliance documentation

Object: Imp

The impression object has been modified from the ORTB specification. Nimbus allows for both the Banner object and Video object to be present in the same Imp object. This is to allow for dual auctions to be triggered on the Nimbus ad server, where both static inventory and video inventory are part of the same auction. This removes the need to make two separate calls to Nimbus. note: While both the banner object and video object are optional, at least 1 must be present in the request

Atribute Type Description
banner object; optional See ORTB 2.5 section 3.2.6
video object; optional See ORTB 2.5 section 3.2.7
instl integer; default 0 See ORTB 2.5 section 3.2.4 recommended if using Banner Adsizes 320x480 or 480x320
bidfloor float; default 1.00 This deviates from 2.5, this is the base auction floor, however it is best to speak to your Nimbus ad manager what a base floor should be
secure integer; default 1 See ORTB 2.5 section 3.2.4
ext object; required Used to pass in the optional APS and Facebook data as well as the required position data

Object: Ext (Imp extension object)

Atribute Type Description
position string; required Adds meta about the impression. It allows a publisher to track performance by naming their ad slot for the impression
facebook_app_id string; optional Needed if integrated with facebook demand and to run them in the auction, this is equal your facebook app id
aps []APS (object); optional Needed if integrated with amazon's APS demand

Object: Banner

note: The height and width in the banner object is extremely important and it is not equal to the height and width of the device. Take special care as it effects the types of ads returned Acceptable ad sizes for Banner.h and Banner.w

Canonical Name Size (WxH)
Banner300x50 300x50
Banner320x50 320x50
Interstitial Portrait 320x480
Interstitial Landscape 480x320
HalfScreen 300x600
LetterBox 300x250
LeaderBoard 728x90

The Interstitial ad size type is special. If Interstitial Portrait or Interstitial Landscape landscape sizes are submitted in the Banner request, the Banner.Format array will be used to allow for additional ad sizes to fill the full screen placement. This is a great way to increase fill, by allowing additional demand for the same placement. If any other size from the above table is submitted Nimbus will ensure ONLY that ad size is returned in the response.

Atribute Type Description
bidfloor float; default 2.00 This deviates from 2.5 this is the floor for the Banner object, used because of the Nimbus dual auction setup
battr integer array Blocked creative attributes. Refer to ORTB 2.5 List 5.3
format object array; recommended See ORTB 2.5 section 3.2.6, is an array of supported ad sizes for the placement, see the example bid request for an example
w integer See ORTB 2.5 section 3.2.6, this is equal to a single supported ad size. For example for interstitial ads set to 320, rectangle banners set to 300, and for small banners set to 728
h integer See ORTB 2.5 section 3.2.6 this is equal to a single supported ad size. For example for interstitial ads set to 420, rectangle banners set to 250, and for small banners set to 90
api integer array See ORTB 2.5 section 3.2.6
pos integer; recommended See ORTB 2.5 section 3.2.6

Object: Video

Atribute Type Description
bidfloor float; default 3.00 This deviates from 2.5 this is the floor for the Video object, used because of the Nimbus dual auction setup
battr integer array Blocked creative attributes. Refer to ORTB 2.5 List 5.3
mimes string array; required See ORTB 2.5 section 3.2.7, example [video/mp4]
minduration integer; recommended; defaults 0 See ORTB 2.5 section 3.2.7
maxduration integer; recommended; defaults 60 See ORTB 2.5 section 3.2.7
protocols integer array; recommended See ORTB 2.5 section section 5.8 Valid values are [2,3,5,6]
w integer See ORTB 2.5 section 3.2.7, this is equal to the devices width
h integer See ORTB 2.5 section 3.2.7, this is equal to the devices height
startdelay integer; default 0 See ORTB 2.5 section 3.2.7
placement integer; default 0 Placement type for the impression. Refer to ORTB List 5.9
linearity integer; default 0 Indicates if the impression must be linear, nonlinear, etc. Refer to ORTB List 5.7
playbackmethod integer array; recommended; default 2 See ORTB 2.5 section 5.10
skip integer; default 0 See ORTB 2.5 section 3.2.7
delivery integer array; Supported delivery methods (e.g., streaming, progressive). Refer to ORTB List 5.15
pos integer; recommended See ORTB 2.5 section 3.2.7
api integer array; List of supported API frameworks for this impression. Refer to ORTB
List 5.6. If an API is not explicitly listed, it is assumed not to be supported
minbitrate integer; recommended; default 0 See ORTB 2.5 section 3.2.7
maxbitrate integer; recommended; default 20000 See ORTB 2.5 section 3.2.7

Object: Format

This is object normally is found with the imp[0].banner, however Nimbus requires that this object also be passed at the request level. bidrequest.format, this is to support SSPs and DSPs that use legacy (non RTB) integrations on Nimbus. This is equal the device's height and width

Atribute Type Description
w int; required See ORTB 2.5 section 3.2.10
h int; required See ORTB 2.5 section 3.2.10

Object: App

Atribute Type Description
name string; required See ORTB 2.5 section 3.2.14
bundle string; required See ORTB 2.5 section 3.2.14
domain string; required See ORTB 2.5 section 3.2.14
storeurl string; required See ORTB 2.5 section 3.2.14
cat string array; recommended See ORTB 2.5 section 3.2.14
sectioncat string array; See ORTB 2.5 section 3.2.14
pagecat string array; See ORTB 2.5 section 3.2.14
ver string; recommended See ORTB 2.5 section 3.2.14
privacypolicy int; recommended; default 0 See ORTB 2.5 section 3.2.14
paid int; recommended; default 0 See ORTB 2.5 section 3.2.14
publisher object; recommended See ORTB 2.5 section 3.2.14

Object: Publisher

Atribute Type Description
name string; recommended See ORTB 2.5 section 3.2.15
domain string; recommended See ORTB 2.5 section 3.2.15
cat string array; recommended See ORTB 2.5 section 3.2.15

Object: APS

The APS data structure is gotten from a proper invocation of the APS SDK. This information is passed to Nimbus so that it can include APS in an agnostic fair auction. Nimbus will return the APS markup in the bid response if APS wins the auction. Note the APS SDK does not send normalized data between video and static demand. The response is also different between app platforms. For Publishers using the Nimbus Request SDK this is handled for you. For Publishers making a server call to Nimbus, simply take the information your client sends you as is and pass it Nimbus. Nimbus will normalize the Data types to []string.

Atribute Type Description
amzn_b any type (string or string array); required Data from the Response from the APS SDK
amzn_h any type (string or string array); required Data from the Response from the APS SDK
amzn_vid any type (string or string array); required Data from the Response from the APS SDK
amznp any type (string or string array); required Data from the Response from the APS SDK
amznrdr any type (string or string array); required Data from the Response from the APS SDK
amznslots any type (string or string array); required Data from the Response from the APS SDK
dc any type (string or string array); required Data from the Response from the APS SDK

Object: Device

Atribute Type Description
ua string; required See ORTB 2.5 section 3.2.18, this must be a valid webview based user-agent, not a constructed one otherwise traffic will be flagged as fraud
geo object; recommended See ORTB 2.5 section 3.2.18
dnt int; recommended See ORTB 2.5 section 3.2.18
lmt int; recommended See ORTB 2.5 section 3.2.18
ip string; required See ORTB 2.5 section 3.2.18, this must be the ip on the handheld device not a server ip, if is missing the X-Forwarded-For header will be looked for the ip. If the body and header are missing the IP the request will fail
devicetype integer See ORTB 2.5 section 3.2.18
make string; required See ORTB 2.5 section 3.2.18, if os is ios the make should be apple; if the os is android the make should be android
model string; required See ORTB 2.5 section 3.2.18, if the os is ios the model should be iphone
os string; required See ORTB 2.5 section 3.2.18, this is a Nimbus + DSP requirement. os is either android or ios
osv string; recommended See ORTB 2.5 section 3.2.18, if this field is missing certain DSP buyers will not buy your inventory
w int; See ORTB 2.5 section 3.2.18
h int; See ORTB 2.5 section 3.2.18
connectiontype integer; See ORTB 2.5 section 5.22
ifa string; required See ORTB 2.5 section 3.2.18, this is also known as the advertising id

Object: Geo

If the Geo object is missing from the Device object, the geolocation will be determined using the ip of the device and a Geo object will be constructed from that

Atribute Type Description
lat float; required See ORTB 2.5 section 3.2.19
lon float; required See ORTB 2.5 section 3.2.19
type int; required See ORTB 2.5 section 3.2.19
ipservice int; recommended See ORTB 2.5 section 3.2.19
country string; required See ORTB 2.5 section 3.2.19
city string; recommended See ORTB 2.5 section 3.2.19
metro string; recommended See ORTB 2.5 section 3.2.19
city string; recommended See ORTB 2.5 section 3.2.19

Object: User

If the Geo object is missing from the Device object, the geolocation will be determined using the ip of the device and a Geo object will be constructed from that

Atribute Type Description
age int; recommended Nimbus specific it provides an alternative to yob
buyeruid string; recommended See ORTB 2.5 section 3.2.20, it is used to incorporate facebook into the auction and is equal to the facebook bidder token in this use case
yob int; recommended See ORTB 2.5 section 3.2.20
gender string; recommended See ORTB 2.5 section 3.2.20
keywords string; recommended See ORTB 2.5 section 3.2.20

Object: Ext (User extension object)

Atribute Type Description
consent string; optional Nimbus specific, this is the IAB consent string, this string can be created by Nimbus under certain conditions, for more details ask your ad manager
did_consent integer; default 0 Nimbus specific, the value can either be 0 or 1. It indicates that a user consented to GDPR

Object: Source (User extension object)

Atribute Type Description
ext object; required Needed to pass OM SDK information

Object: Ext (Source extension object)

Atribute Type Description
omidpn string; required identifier of the OM SDK integration, this is the same as the "name" parameter of the OMID Partner object
Omidpv string; optional version of the OM SDK version

Static Bid Request Body Example

{
 "imp": [
  {
   "banner": {
    "format": [
     {
      "w": 480,
      "h": 320
     },
     {
      "w": 320,
      "h": 480
     },
     {
      "w": 300,
      "h": 600
     }
    ],
    "w": 320,
    "h": 480,
    "pos": 7
   },
   "instl": 1,
   "bidfloor": 3,
   "secure": 1,
   "ext": {
    "position": "Above the fold"
   }
  }
 ],
 "app": {
  "name": "foo",
  "bundle": "app_bundle_id",
  "domain": "https://company_domain.com",
  "storeurl": "https://app_store_location.com",
  "cat": [
   "IAB14",
   "IAB1",
   "IAB9",
   "IAB12",
   "IAB16",
   "IAB17",
   "IAB18",
   "IAB20"
  ],
  "ver": "4.2.4",
  "privacypolicy": 1,
  "paid": 0,
  "publisher": {
   "name": "foo",
   "domain": "https://company_domain.com"
  }
 },
 "device": {
  "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_0 like Mac OS X) AppleWebKit/600.1.3 (KHTML, like Gecko) Version/8.0 Mobile/12A4345d Safari/600.1.4",
  "geo": {
   "lat": 40.7089,
   "lon": -74.0012,
   "ipservice": 3,
   "country": "USA",
   "city": "New York"
  },
  "dnt": 0,
  "lmt": 0,
  "ip": "71.125.59.151",
  "make": "apple",
  "model": "8",
  "os": "iphone",
  "osv": "4.3.2",
  "language": "en",
  "carrier": "Verizon",
  "connectiontype": 6,
  "ifa": "1N1F8C2C-60D9-5000-971B-6158BD7A0E50"
 },
 "format": {
  "w": 780,
  "h": 1080
 },
 "user": {
  "age": 28,
  "yob": 1991,
  "gender": "male",
 },
 "regs": {
  "coppa": 0,
 },
 "ext": {
  "api_key": "0b0afa7f-d884-486d-b196-47124e9e13de",
  "session_id": "unique_session_id"
 }
}

Video Bid Request Body Example

{
 "imp": [
  {
   "video": {
    "mimes": [
     "video/mp4"
    ],
    "minduration": 0,
    "maxduration": 60,
    "protocols": [
     2,
     3,
     5,
     6
    ],
    "w": 780,
    "h": 1080,
    "startdelay": 0,
    "skip": 0,
    "minbitrate": 1,
    "maxbitrate": 20000
   },
   "instl": 1,
   "bidfloor": 3,
   "secure": 1,
   "ext": {
    "position": "Above the fold"
   }
  }
 ],
 "app": {
  "name": "foo",
  "bundle": "app_bundle_id",
  "domain": "https://company_domain.com",
  "storeurl": "https://app_store_location.com",
  "cat": [
   "IAB14",
   "IAB1",
   "IAB9",
   "IAB12",
   "IAB16",
   "IAB17",
   "IAB18",
   "IAB20"
  ],
  "ver": "4.2.4",
  "privacypolicy": 1,
  "paid": 0,
  "publisher": {
   "name": "foo",
   "domain": "https://company_domain.com"
  }
 },
 "device": {
  "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_0 like Mac OS X) AppleWebKit/600.1.3 (KHTML, like Gecko) Version/8.0 Mobile/12A4345d Safari/600.1.4",
  "geo": {
   "lat": 40.7089,
   "lon": -74.0012,
   "ipservice": 3,
   "country": "USA",
   "city": "New York"
  },
  "dnt": 0,
  "lmt": 0,
  "ip": "71.125.59.151",
  "make": "apple",
  "model": "8",
  "os": "iphone",
  "osv": "4.3.2",
  "language": "en",
  "carrier": "Verizon",
  "connectiontype": 6,
  "ifa": "1N1F8C2C-60D9-5000-971B-6158BD7A0E50"
 },
 "format": {
  "w": 780,
  "h": 1080
 },
 "user": {
  "age": 28,
  "yob": 1991,
  "gender": "male",
 },
 "regs": {
  "coppa": 0,
 },
 "ext": {
  "api_key": "0b0afa7f-d884-486d-b196-47124e9e13de",
  "session_id": "unique_session_id"
 }
}

Dual Static/Video Auction Bid Request Body Example

This is a Nimbus specific example. ORTB does not allow for more than one creative object to be present in the Imp object. However, this would mean as a publisher that you would have to construct two separate request, which would yield two very different auction. To static allow inventory and video inventory to compete in a fair auction, we allow for one than one creative object to be submitted for a single impression. In this case we currently allow for both the Banner object and Video Object to coexist in the Imp Object

{
 "imp": [
  {
   "banner": {
    "format": [
     {
      "w": 480,
      "h": 320
     },
     {
      "w": 320,
      "h": 480
     },
     {
      "w": 300,
      "h": 600
     }
    ],
    "w": 320,
    "h": 480,
    "pos": 7
   },
   "video": {
    "mimes": [
     "video/mp4"
    ],
    "minduration": 0,
    "maxduration": 60,
    "protocols": [
     2,
     3,
     5,
     6
    ],
    "w": 780,
    "h": 1080,
    "startdelay": 0,
    "skip": 0,
    "minbitrate": 1,
    "maxbitrate": 20000
   },
   "instl": 1,
   "bidfloor": 3,
   "secure": 1,
   "ext": {
    "position": "Above the fold"
   }
  }
 ],
 "app": {
  "name": "foo",
  "bundle": "app_bundle_id",
  "domain": "https://company_domain.com",
  "storeurl": "https://app_store_location.com",
  "cat": [
   "IAB14",
   "IAB1",
   "IAB9",
   "IAB12",
   "IAB16",
   "IAB17",
   "IAB18",
   "IAB20"
  ],
  "ver": "4.2.4",
  "privacypolicy": 1,
  "paid": 0,
  "publisher": {
   "name": "foo",
   "domain": "https://company_domain.com"
  }
 },
 "device": {
  "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_0 like Mac OS X) AppleWebKit/600.1.3 (KHTML, like Gecko) Version/8.0 Mobile/12A4345d Safari/600.1.4",
  "geo": {
   "lat": 40.7089,
   "lon": -74.0012,
   "ipservice": 3,
   "country": "USA",
   "city": "New York"
  },
  "dnt": 0,
  "lmt": 0,
  "ip": "71.125.59.151",
  "make": "apple",
  "model": "8",
  "os": "iphone",
  "osv": "4.3.2",
  "language": "en",
  "carrier": "Verizon",
  "connectiontype": 6,
  "ifa": "1N1F8C2C-60D9-5000-971B-6158BD7A0E50"
 },
 "format": {
  "w": 780,
  "h": 1080
 },
 "user": {
  "age": 28,
  "yob": 1991,
  "gender": "male",
 },
 "regs": {
  "coppa": 0,
 },
 "ext": {
  "api_key": "0b0afa7f-d884-486d-b196-47124e9e13de",
  "session_id": "unique_session_id"
 }
}

Bid Response Object

Atribute Type Description
type string; required allows a publisher to quickly know if this is VAST video, HTML banner, or Native
auction_id string; required is a Nimbus trace id
bid_in_cents int; required the winning bid value in cents to avoid float math loss
content_type int; optional meta data about the ad markup
height int; optional height meta data about the asset
width int; optional width meta data about the asset
markup string; required markup containing the asset to render
network string; required winning demand source
trackers Trackers (object); optional provides additional trackers that must be handled by the client, used for Native display such as Facebook
placement_id string; required provides additional information about the network's winning line item. Used with legacy demand sources

Bid Trackers Object

Atribute Type Description
type string; required allows a publisher to quickly know if this is VAST video, HTML banner, or Native
impression_trackers string array; required provides a list of trackers that the client has to fire as a callback event to rendering the ad successfully

Basic Publisher Example Response

This response structure deviates from the ORTB response structure and is more publisher friendly. Because of the Nature of the dual auction, auction return types are needed so that the client knows how to handle rendering

{
    "type": "static", // indicates that the admarkup is html
    "auction_id": "11679895-4523-440c-925a-96d4cd4c58ba", // used for tracing
    "bid_in_cents": 0, // used for analytics
    "content_type": "text/html; charset=utf-8", // meta information
    "height": 480,
    "width": 320,
    "markup": "<html><body><img src=\"https://s3.amazonaws.com/nimbus.test.ads/Nimbus_testad_static_320x480.png\">\n<html>\n<img src=\"https://abepanel.timehop.com/events/track?advertiser_id=1N1F8C2C-60D9-5000-971B-6158BD7A0E50&age=28&app_platform=iphone&app_version=4.3.2&auction_id=11679895-4523-440c-925a-96d4cd4c58ba&auction_type=static&bid=0.00&city=New+York&country=USA&gender=Male&height=390&ip=71.125.59.151&key=nimbus_static_impression&language=en&lat=40.7089000&long=-74.0012000&network=test_demand&placement=&publisher=foo&user_agent=Mozilla%2F5.0+%28iPhone%3B+CPU+iPhone+OS+8_0+like+Mac+OS+X%29+AppleWebKit%2F600.1.3+%28KHTML%2C+like+Gecko%29+Version%2F8.0+Mobile%2F12A4345d+Safari%2F600.1.4&width=640\" alt=\"\" height=\"0\" width=\"0\"/></body></html>\n", // to be loaded in a webview
    "network": "test_demand" //winning ssp/dsp
}

Special Notes

Regarding underscores in property names: The OpenRTB spec itself is occasionally inconsistent when it comes to underscores. Nearly all properties in the spec are lowercase, no underscored. However, there’s an Anti-patterns section int he spec that references a private_auction flag containing an underscore. The api_key, facebook_app_id, and session_id properties in our docs are both properties contained within Extension objects in the spec. As such, we include underscores in those properties as an anti-pattern to enable the reader to quickly distinguish custom fields from RTB specified fields. We’ve seen some demand partners take this approach as well and we favored it ourselves.

Clone this wiki locally