Bid Requests

Bid Request Specification

3.2.1 Object: BidRequest

Please note that all auctions are first price.

Field	Type	Description
id	string; required	Unique ID of the bid request, provided by the supply partner.
test	integer	Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.
badv	array of strings	Blocked advertiser domains (max 50).
bcat	array of strings	Specifies a list of blocked IAB content categories (see OpenRTB 2.5 section 5.1). This is not supported by all of our demand partners.
wseat	array of strings	Specifies an array representing an include list of buyer seats allowed to bid on this impression. If omitted, there are no seat restrictions for this impression. This is not supported by all of our demand partners.
bseat	array of strings	Specifies an array representing an exclude list of buyer seats disallowed to bid on this impression. This is not supported by all of our demand partners.
tmax	integer	Maximum time in milliseconds the exchange allows for bids to be received, including Internet latency, to avoid timeout. Must be >= 100. Most responses should arrive in under 200-300ms. MobileFuse will attempt to achieve the tmax, but due to latency inconsistency, it is not guaranteed.
imp	array with object; required	Impression offered in this bid request. MobileFuse supports only a single impression per bid request. See 3.2.4 Object: Imp
app	object; required	Specifies information about the app. See 3.2.14 Object: App
device	object; required	Specifies information about the user’s device. See 3.2.18 Object: Device
user	object	Specifies information about the user. See 3.2.20 Object: User
source	object	Specifies information about the source. See 3.2.2 Object: Source
regs	object	Specifies regulations for this impression. See 3.2.3 Object: Regs

3.2.2 Object: Source

Field	Type	Description
pchain	string	Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.
tid	string	Transaction ID
ext	object; recommended	Object with fields for `omidpn`, `omidpv`, `schain`, and `ssreq`. schain attribute is required when MobileFuse's relationship with the publisher is not dire

3.2.3 Object: Regs

Field	Type	Description
coppa	integer	Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.
ext	object	Object that supports the following extensions: - “us_privacy” to specify that this request is subject to CCPA US privacy regulations in support of the IAB OpenRTB Extension for US Privacy. Usage of gpp is preferred. - "gpp" string to specify regulations via Global Privacy Platform String__ - "gpp_sid" array to specify relevant GPP section ID

3.2.4 Object: Imp

Please note that MobileFuse only allows one impression object per bid request.

Field	Type	Description
id	string; required	A unique identifier for this impression within the context of the bid request (typically just “1”)
tagid	string; required	MobileFuse-provided ID for the ad unit, or publisher’s tagid if preferred and provided to account manager
banner	object	Required if this request is for a banner ad unit. See 3.2.6 Object: Banner
video	object	Required if this request is for a video ad unit. See 3.2.7 Object: Video
native	object	Required if this request is for a native ad unit. See 3.2.9 Object: Native
instl	integer; default 0	1 = the ad is interstitial or full screen, 0 = not interstitial.
secure	integer; default 0	Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure.
bidfloor	float, default 0	Bidfloor in USD
exp	int	Advisory as to the number of seconds that may elapse between the auction and the actual impression.
ext	object	Supports skadn field to supply SKAdNetwork info as well as gpid field

3.2.6 Object: Banner

Field	Type	Description
w	integer	Exact width in device independent pixels (DIPS). Note that the format field is preferred instead
h	integer	Exact height in device independent pixels (DIPS). Note that the format field is preferred instead
btype	array of integers	Specifies the banner creative types to block. Refer to section 5.2 of the IAB specification for a list of types. This is not supported by all demand sources.
battr	array of integers	Specifies the banner creative attributes to block. Refer to section 5.3 of the IAB specification for a list of attributes. This is not supported by all demand sources.
pos	integer; default 0	Ad Position. Fully supported: 0 = Unknown, 1 = Above Fold, 3 = Below Fold. Some demand supports all OpenRTB 2.5 list 5.4.
api	array of integers	List of supported API frameworks for this banner. If an API is not explicitly listed, it is assumed not to be supported. Refer to OpenRTB 2.5 list 5.6.
format	array of objects	Array of format objects representing the banner sizes permitted. See 3.2.10 Object: Format
mimes	array of strings	Content MIME types supported
expdir	array of integers	Directions in which the banner may expand. Refer to OpenRTB List 5.5.

3.2.7 Object: Video

Field	Type	Description
mimes	array of strings	Specifies the video content MIME types supported; for example, video/mp4 and video/x-ms-wmv. If not specified, any MIME type is allowed.
minduration	integer; recommended	Specifies the minimum video ad duration, in seconds.
maxduration	integer; recommended	Specifies the maximum video ad duration, in seconds.
w	integer	Specifies the width of the video player, in pixels.
h	integer	Specifies the height of the video player, in pixels.
startdelay	integer	Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to OpenRTB 2.5 List 5.12 for values.
battr	array of integers	Specifies the banner creative attributes to block. Refer to section 5.3 of the IAB specification for a list of attributes. This is not supported by all demand sources. This is not supported by all demand sources.
minbitrate	integer	Specifies the minimum bit rate, in kilobytes per second. If specified, only return creatives having at least one media file within the appropriate bit range.
maxbitrate	integer	List of supported API frameworks for this banner. If an API is not explicitly listed, it is assumed not to be supported. Refer to OpenRTB 2.5 list 5.6.
playbackmethod	array of integers	Playback methods that may be in use. If none are specified, any method may be used. Refer to OpenRTB 2.5 List 5.10.
pos	integer	Ad position on screen. Refer to OpenRTB 2.5 List 5.4.
api	array of integers	List of supported API frameworks for this impression. Refer to OpenRTB 2.5 List 5.6. If an API is not explicitly listed, it is assumed not to be supported.
protocols	array of integers	Array of supported video protocols. Refer to OpenRTB 2.5 List 5.8.
placement	integer	Placement type for the impression. Refer to OpenRTB 2.5 List 5.9.
plcmt	integer	Placement type for the impression. Refer to AdCOM Plcmt Subtypes.
boxingallowed	integer; default 1	Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes
delivery	array of integers	Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. Refer to List 5.15.
skip	integer	Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes.
skipafter	integer; default 0	Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
skipmin	integer; default 0	Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable
podid	string	Unique identifier indicating that an impression opportunity belongs to a video ad pod. If multiple impression opportunities within a bid request share the same podid, this indicates that those impression opportunities belong to the same video ad pod.
sequence	integer; default 0 DEPRECATED	If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.
maxseq	integer; recommended	Indicates the maximum number of ads that may be served into a "dynamic" video ad pod (where the precise number of ads is not predetermined by the seller). See Section 7.6 for more details.
poddur	integer; recommended	Indicates the total amount of time in seconds that advertisers may fill for a "dynamic" video ad pod (See Section 7.6 for more details), or the dynamic portion of a "hybrid" ad pod. This field is required only for the dynamic portion(s) of video ad pods. This field refers to the length of the entire ad break, whereas minduration/maxduration/rqddurs are constraints relating to the slots that make up the pod.
podseq	integer; default 0	The sequence (position) of the video ad pod within a content stream. Refer to List: Pod Sequence in AdCOM 1.0 for guidance on the use of this field.
rqddurs	integer array	Precise acceptable durations for video creatives in seconds. This field specifically targets the Live TV use case where non-exact ad durations would result in undesirable "dead air". This field is mutually exclusive with minduration and maxduration; if rqddurs is specified, minduration and maxduration must not be specified and vice versa.
slotinpod	integer; default 0	For video ad pods, this value indicates that the seller can guarantee delivery against the indicated slot position in the pod. Refer to List: Slot Position in Pod in AdCOM 1.0 guidance on the use of this field.
mincpmpersec	float	Minimum CPM per second. This is a price floor for the "dynamic" portion of a video ad pod, relative to the duration of bids an advertiser may submit.
maxextended	integer	Maximum extended ad duration if extension is allowed. If blank or 0, extension is not allowed. If -1, extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.

3.2.9 Object: Native

Field	Type	Description
request	object or string	The native ad request object, see the OpenRTB Native Ads Specification for details. Can be passed as a JSON object, or a JSON encoded string.
ver	string	Expected to be "1.2"
api	array of integers	The APIs that your native ad renderer supports, refer to list 5.3 of the IAB OpenRTB Specification for valid values

3.2.10 Object: Format

Field	Type	Description
w	integer	Specifies the width of the creative, in pixels.
h	integer	Specifies the height of the creative, in pixels.

3.2.14 Object: App

Field	Type	Description
bundle	string; required	On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it should be a numeric ID.
domain	string	Domain of the app (e.g., “mygame.foo.com”).
cat	array of strings	Array of IAB content categories of the app. Refer to OpenRTB 2.5 List 5.1
name	string	App name
publisher	object	Details about the publisher of the app. See 3.2.15 Object: Publisher
storeurl	string	App store URL for an installed app
ver	string	Application version
keywords	string	Comma separated list of keywords about the app.
id	string	Please use bundle instead
paid	integer	0 = app is free, 1 = the app is a paid version
content	object	Details about the content of the app. See 3.2.16 Object: Content

3.2.15 Object: Publisher

Field	Type	Description
name	string	Publisher name
id	string	Publisher id

3.2.16 Object: Content

Field	Type	Description
contentrating	string	Content rating (e.g., MPAA).
genre	string	Genre that best describes the content (e.g., rock, pop, etc).
len	integer	Length of content in seconds; appropriate for video
livestream	integer	0 = not live, 1 = content is live (e.g., stream, live blog).
series	string	Content series. Video Examples: “The Office” (television), “Star Wars” (movie), or “Arby ‘N’ The Chief” (made for web). Non-Video Example: “Ecocentric” (Time Magazine blog).
title	string	Content title. Video Examples: “Search Committee” (television), “A New Hope” (movie), or “Endgame” (made for web). Non-Video Example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article).
context	integer	Type of content (game, video, text, etc.). Refer to OpenRTB List 5.18.
cat	array of strings	Content category
episode	integer	Episode number
language	string	Content language using ISO-639-1-alpha-2 (i.e., EN)
season	string	Content season (e.g., “Season 3”)
url	string	URL of the content, for buy-side contextualization or review

3.2.18 Object: Device

Field	Type	Description
ifa	string; recommended	ID sanctioned for advertiser use in the clear (i.e., not hashed).
ua	string; required	Browser user agent string.
geo	object; recommended	Location of the device assumed to be the user’s current location defined by a Geo object. See 3.2.19 Object: Geo
dnt	integer	Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.
lmt	integer	“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. Values of 1 will be treated as opt outs for the purpose of us privacy laws.
ip	string; required if no ipv6	IPv4 address closest to device
ipv6	string; required if no ip	IP address closest to device as IPv6
devicetype	integer	The general type of device. Refer to OpenRTB 2.5 List 5.21
make	string	Device make (e.g., “Apple”).
model	string	Device model (e.g., “iPhone”).
os	string	Device operating system (e.g., “iOS”).
osv	string	Device operating system version (e.g., “3.1.2”).
language	string	Browser language using ISO-639-1-alpha-2.
carrier	string	Carrier or ISP
connectiontype	integer	Network connection type. Refer to List 5.22.
w	integer	Physical width of the screen in pixels.
h	integer	Physical height of the screen in pixels.
ext	object	Supports ifv and atts fields per the SKAdNetwork extension

3.2.19 Object: Geo

Field	Type	Description
city	string	City using United Nations Code for Trade & Transport Locations. See OpenRTB Appendix A for a link to the codes
country	string	Country code using ISO-3166-1-alpha-3. MobileFuse only accepts USA, CAN, and EU traffic. See full country list here.
lat	float; recommended	Latitude from -90.0 to +90.0, where negative is south. Highly recommended to increase ability to monetize.
lon	float; recommended	Longitude from -180.0 to +180.0, where negative is west. Highly recommended to increase ability to monetize.
metro	string	Google metro code; similar to but not exactly Nielsen DMAs. See OpenRTB Appendix A for a link to the codes
region	string	Region code using ISO-3166-2; 2-letter state code if USA.
type	integer; recommended	Source of location data; recommended when passing lat/lon. Refer to OpenRTB 2.5 List 5.20.
utcoffset	integer	Local time as the number +/- of minutes from UTC.
zip	string	Zip or postal code.

3.2.20 Object: User

Field	Type	Description
gender	string	Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
yob	integer	Year of birth as a 4-digit integer.
eids	object array	Array of objects of third party alternative IDs, per the OpenRTB spec.
consent	string	TField for TCF2 strings for Canadian users. Use of gpp is recommended instead.
ext	object	Supports the "hems" array of objects for passing hashed email(s) for the user, eg. `"user": { "ext": { "hems": [ {"hem": "<hashed_email>", "hem_type": "sha256"}, {"hem": "<hashed_email>", "hem_type": "sha1"}, {"hem": "<hashed_email>", "hem_type": "md5"}, ] } }`

## Sample Bid Requests

{
  "id": "mybidrequestid",
  "imp": [
    {
      "id": "1",
      "tagid": "123456",
      "bidfloor": 1.5,
      "banner": {
        "format": [
          {
            "w": 320,
            "h": 50
          }
        ]
      }
    }
  ],
  "device": {
    "geo": {
      "lat": 42.9999,
      "lon": -89.5522
    },
    "ua": "Mozilla/5.0 (Linux; Android 9; Pixel 3 XL Build/PD1A.180720.030; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/70.0.3538.64 Mobile Safari/537.36",
    "ip": "123.123.123.123",
    "ifa": "01234567-1234-1234-1234-012345678901"
  },
  "app": {
    "bundle": "com.test",
    "cat": [
      "IAB14"
    ]
  },
  "source": {
    "ext": {
      "schain": {
        "complete": 1,
        "ver": "1.0",
        "nodes": [
          {
            "asi": "test.com",
            "sid": "1234",
            "rid": "request_id",
            "hp": 1
          }
        ]
      }
    }
  }
}

{
  "id": "mybidrequestid",
  "imp": [
    {
      "id": "1",
      "tagid": "123456",
      "instl": 1,
      "bidfloor": 4.5,
      "video": {
        "w": 320,
        "h": 480,
        "mimes": [
          "video/mp4",
          "video/3gpp",
          "video/ogg",
          "video/webm"
        ],
        "minduration": 15,
        "maxduration": 60,
        "protocols": [
          2,
          5
        ],
        "startdelay": 0,
        "maxbitrate": 750,
        "minbitrate": 0,
        "linearity": 1,
        "pos": 1
      }
    }
  ],
  "device": {
    "geo": {
      "lat": 42.9999,
      "lon": -89.5522
    },
    "ua": "Mozilla/5.0 (Linux; Android 9; Pixel 3 XL Build/PD1A.180720.030; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/70.0.3538.64 Mobile Safari/537.36",
    "ip": "123.123.123.123",
    "ifa": "01234567-1234-1234-1234-012345678901"
  },
  "app": {
    "bundle": "com.test",
    "cat": [
      "IAB14"
    ]
  },
  "source": {
    "ext": {
      "schain": {
        "complete": 1,
        "ver": "1.0",
        "nodes": [
          {
            "asi": "test.com",
            "sid": "1234",
            "rid": "request_id",
            "hp": 1
          }
        ]
      }
    }
  }
}

{
  "id": "mybidrequestid",
  "imp": [
    {
      "id": "1",
      "tagid": "123456",
      "bidfloor": 1.5,
      "native": {
        "ver": "1.2",
        "request": {
          "aurlsupport": 1,
          "privacy": 1,
          "assets": [
            { "id": 100, "title": { "len": 25 }, "required": 1 },
            { "id": 200, "img":   { "type": 1 } },
            { "id": 201, "img":   { "type": 3, "wmin": 627, "hmin": 627 } },
            { "id": 400, "data":  { "type": 1, "len": 25 } },
            { "id": 401, "data":  { "type": 2, "len": 140 } },
            { "id": 402, "data":  { "type": 11 } },
            { "id": 403, "data":  { "type": 12, "len": 15 } },
            { "id": 300, "video": { "mimes": ["video/mp4"], "maxduration": 60, "minduration": 10, "protocols": [2, 3, 7, 5, 6, 8] } }
          ],
          "eventtrackers": [
            { "event": 1, "methods": [1] },
            { "event": 2, "methods": [1] },
            { "event": 3, "methods": [1] },
            { "event": 4, "methods": [1] }
          ]
        }
      }
    }
  ],
  "device": {
    "geo": {
      "lat": 42.9999,
      "lon": -89.5522
    },
    "ua": "Mozilla/5.0 (Linux; Android 9; Pixel 3 XL Build/PD1A.180720.030; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/70.0.3538.64 Mobile Safari/537.36",
    "ip": "123.123.123.123",
    "ifa": "01234567-1234-1234-1234-012345678901"
  },
  "app": {
    "bundle": "com.test",
    "cat": [
      "IAB14"
    ]
  },
  "source": {
    "ext": {
      "schain": {
        "complete": 1,
        "ver": "1.0",
        "nodes": [
          {
            "asi": "test.com",
            "sid": "1234",
            "rid": "request_id",
            "hp": 1
          }
        ]
      }
    }
  }
}