Bid Requests

Bid Request Specification

3.2.1 Object: BidRequest

Please note that all auctions are first price.

FieldTypeDescription
idstring; requiredUnique ID of the bid request, provided by the supply partner.
testintegerIndicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.
badvarray of stringsBlocked advertiser domains (max 50).
bcatarray of stringsSpecifies a list of blocked IAB content categories (see OpenRTB 2.5 section 5.1). This is not supported by all of our demand partners.
wseatarray of stringsSpecifies 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.
bseatarray of stringsSpecifies 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.
tmaxintegerMaximum 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.
imparray with object; requiredImpression offered in this bid request. MobileFuse supports only a single impression per bid request. See 3.2.4 Object: Imp
appobject; requiredSpecifies information about the app. See 3.2.14 Object: App
deviceobject; requiredSpecifies information about the user’s device. See 3.2.18 Object: Device
userobjectSpecifies information about the user. See 3.2.20 Object: User
sourceobjectSpecifies information about the source. See 3.2.2 Object: Source
regsobjectSpecifies regulations for this impression. See 3.2.3 Object: Regs

3.2.2 Object: Source

FieldTypeDescription
pchainstringPayment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.
tidstringTransaction ID
extobject; recommendedObject 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

FieldTypeDescription
coppaintegerFlag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.
extobjectObject 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.

FieldTypeDescription
idstring; requiredA unique identifier for this impression within the context of the bid request (typically just “1”)
tagidstring; requiredMobileFuse-provided ID for the ad unit, or publisher’s tagid if preferred and provided to account manager
bannerobjectRequired if this request is for a banner ad unit. See 3.2.6 Object: Banner
videoobjectRequired if this request is for a video ad unit. See 3.2.7 Object: Video
nativeobjectRequired if this request is for a native ad unit. See 3.2.9 Object: Native
instlinteger; default 01 = the ad is interstitial or full screen, 0 = not interstitial.
secureinteger; default 0Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure.
bidfloorfloat, default 0Bidfloor in USD
expintAdvisory as to the number of seconds that may elapse between the auction and the actual impression.
extobjectSupports skadn field to supply SKAdNetwork info as well as gpid field

3.2.6 Object: Banner

FieldTypeDescription
wintegerExact width in device independent pixels (DIPS). Note that the format field is preferred instead
hintegerExact height in device independent pixels (DIPS). Note that the format field is preferred instead
btypearray of integersSpecifies 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.
battrarray of integersSpecifies 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.
posinteger; default 0Ad Position. Fully supported: 0 = Unknown, 1 = Above Fold, 3 = Below Fold. Some demand supports all OpenRTB 2.5 list 5.4.
apiarray of integersList 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.
formatarray of objectsArray of format objects representing the banner sizes permitted. See 3.2.10 Object: Format
mimesarray of stringsContent MIME types supported
expdirarray of integersDirections in which the banner may expand. Refer to OpenRTB List 5.5.

3.2.7 Object: Video

FieldTypeDescription
mimesarray of stringsSpecifies the video content MIME types supported; for example, video/mp4 and video/x-ms-wmv. If not specified, any MIME type is allowed.
mindurationinteger; recommendedSpecifies the minimum video ad duration, in seconds.
maxdurationinteger; recommendedSpecifies the maximum video ad duration, in seconds.
wintegerSpecifies the width of the video player, in pixels.
hintegerSpecifies the height of the video player, in pixels.
startdelayintegerIndicates 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.
battrarray of integersSpecifies 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.
minbitrateintegerSpecifies the minimum bit rate, in kilobytes per second. If specified, only return creatives having at least one media file within the appropriate bit range.
maxbitrateintegerList 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.
playbackmethodarray of integersPlayback methods that may be in use. If none are specified, any method may be used. Refer to OpenRTB 2.5 List 5.10.
posintegerAd position on screen. Refer to OpenRTB 2.5 List 5.4.
apiarray of integersList 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.
protocolsarray of integersArray of supported video protocols. Refer to OpenRTB 2.5 List 5.8.
placementintegerPlacement type for the impression. Refer to OpenRTB 2.5 List 5.9.
plcmtintegerPlacement type for the impression. Refer to AdCOM Plcmt Subtypes.
boxingallowedinteger; default 1Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes
deliveryarray of integersSupported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. Refer to List 5.15.
skipintegerIndicates if the player will allow the video to be skipped, where 0 = no, 1 = yes.
skipafterinteger; default 0Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
skipmininteger; default 0Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable
podidstringUnique 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.
sequenceinteger; 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.
maxseqinteger; recommendedIndicates 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.
poddurinteger; recommendedIndicates 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.
podseqinteger; default 0The 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.
rqddursinteger arrayPrecise 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.
slotinpodinteger; default 0For 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.
mincpmpersecfloatMinimum 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.
maxextendedintegerMaximum 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

FieldTypeDescription
requestobject or stringThe native ad request object, see the OpenRTB Native Ads Specification for details. Can be passed as a JSON object, or a JSON encoded string.
verstringExpected to be "1.2"
apiarray of integersThe 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

FieldTypeDescription
wintegerSpecifies the width of the creative, in pixels.
hintegerSpecifies the height of the creative, in pixels.

3.2.14 Object: App

FieldTypeDescription
bundlestring; requiredOn Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it should be a numeric ID.
domainstringDomain of the app (e.g., “mygame.foo.com”).
catarray of stringsArray of IAB content categories of the app. Refer to OpenRTB 2.5 List 5.1
namestringApp name
publisherobjectDetails about the publisher of the app. See 3.2.15 Object: Publisher
storeurlstringApp store URL for an installed app
verstringApplication version
keywordsstringComma separated list of keywords about the app.
idstringPlease use bundle instead
paidinteger0 = app is free, 1 = the app is a paid version
contentobjectDetails about the content of the app. See 3.2.16 Object: Content

3.2.15 Object: Publisher

FieldTypeDescription
namestringPublisher name
idstringPublisher id

3.2.16 Object: Content

FieldTypeDescription
contentratingstringContent rating (e.g., MPAA).
genrestringGenre that best describes the content (e.g., rock, pop, etc).
lenintegerLength of content in seconds; appropriate for video
livestreaminteger0 = not live, 1 = content is live (e.g., stream, live blog).
seriesstringContent series.
Video Examples: “The Office” (television), “Star Wars” (movie), or “Arby ‘N’ The Chief” (made for web).
Non-Video Example: “Ecocentric” (Time Magazine blog).
titlestringContent 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).
contextintegerType of content (game, video, text, etc.). Refer to OpenRTB List 5.18.
catarray of stringsContent category
episodeintegerEpisode number
languagestringContent language using ISO-639-1-alpha-2 (i.e., EN)
seasonstringContent season (e.g., “Season 3”)
urlstringURL of the content, for buy-side contextualization or review

3.2.18 Object: Device

FieldTypeDescription
ifastring; recommendedID sanctioned for advertiser use in the clear (i.e., not hashed).
uastring; requiredBrowser user agent string.
geoobject; recommendedLocation of the device assumed to be the user’s current location defined by a Geo object. See 3.2.19 Object: Geo
dntintegerStandard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.
lmtinteger“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.
ipstring; required if no ipv6IPv4 address closest to device
ipv6string; required if no ipIP address closest to device as IPv6
devicetypeintegerThe general type of device. Refer to OpenRTB 2.5 List 5.21
makestringDevice make (e.g., “Apple”).
modelstringDevice model (e.g., “iPhone”).
osstringDevice operating system (e.g., “iOS”).
osvstringDevice operating system version (e.g., “3.1.2”).
languagestringBrowser language using ISO-639-1-alpha-2.
carrierstringCarrier or ISP
connectiontypeintegerNetwork connection type. Refer to List 5.22.
wintegerPhysical width of the screen in pixels.
hintegerPhysical height of the screen in pixels.
extobjectSupports ifv and atts fields per the SKAdNetwork extension

3.2.19 Object: Geo

FieldTypeDescription
citystringCity using United Nations Code for Trade & Transport Locations. See OpenRTB Appendix A for a link to the codes
countrystringCountry code using ISO-3166-1-alpha-3. MobileFuse only accepts USA, CAN, and EU traffic. See full country list here.
latfloat; recommendedLatitude from -90.0 to +90.0, where negative is south. Highly recommended to increase ability to monetize.
lonfloat; recommendedLongitude from -180.0 to +180.0, where negative is west. Highly recommended to increase ability to monetize.
metrostringGoogle metro code; similar to but not exactly Nielsen DMAs. See OpenRTB Appendix A for a link to the codes
regionstringRegion code using ISO-3166-2; 2-letter state code if USA.
typeinteger; recommendedSource of location data; recommended when passing lat/lon. Refer to OpenRTB 2.5 List 5.20.
utcoffsetintegerLocal time as the number +/- of minutes from UTC.
zipstringZip or postal code.

3.2.20 Object: User

FieldTypeDescription
genderstringGender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
yobintegerYear of birth as a 4-digit integer.
extobjectObject containing one field for “consent” for TCF2 strings for Canadian users. Use of gpp is recommended instead.

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
          }
        ]
      }
    }
  }
}