> For the complete documentation index, see [llms.txt](https://docs.blueseasx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blueseasx.com/advertiser/integration/openrtb.md).
# OpenRTB
## BidRequest
| Field | Type | Description |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string; required | Unique ID of the bid request, provided by supply partner. |
| imp | object array; required | Array of Imp object, **only one imp is supported on Bluesea side.** |
| app | object; recommended | Details via an App object about the publisher's app. |
| device | object; recommended | Details via a Device object about the user's device to which the impression will be delivered. |
| user | object; recommended | Details via a User object about the human user of the device; the advertising audience. |
| tmax | integer | Maximum time in milliseconds supply side allows for bids to be received including Internet latency to avoid timeout. |
| source | object; recommended | Details via a Source object provides data about theinventory source and which entity makes the final decision. |
| bcat | string array | Blocked advertiser categories using the IAB content categories. |
| bapp | sting array | Block list of applications by their platform-specific application identifiers. On Android, these should be bundle or package names (e.g., com.foo.mygame). On iOS, these are numeric IDs. |
| badv | string array | Block list of advertisers by their domains (e.g., “ford.com”). |
| at | int | Auction type, where 1=First Price, 2=Second Price. |
| cur | string | currency, **It is always USD.** |
| regs | object; recommended | Details via a Regs object specifies any industry, legal, or governmental regulations in force for this request. |
### **BidRequest.Imp**
| Field | Type | Description |
| ----------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string; required | A unique identifier for this impression within the context of the bid request (typically, it starts with 1). |
| banner | object | A Banner object required if this impression is offered as a banner ad opportunity. |
| video | object | A Video object required if this impression is offered as a video ad opportunity. |
| native | object | A Native object required if this impression is offered as a native ad opportunity. |
| displaymanager | string | Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). |
| displaymanagerver | string | Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). |
| instl | integer; default 0 | 1 = the ad is interstitial or full screen, 0 = not interstitial. |
| tagid | string | Identifier for specific ad placement or ad tag that was used to initiate the auction. T |
| bidfloor | float; default 0 | Minimum bid for this impression expressed in CPM. |
| bidfloorcur | string | **It is always USD.** |
| clickbrowser | integer, default 0 | Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native. |
| secure | integer | Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure.
|
| rwdd | integer | Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. Typically video ad implementations allow users to read an additional news article for free, receive an extra life in a game, or get a sponsored ad-free music session. The reward is typically distributed after the video ad is completed. |
| ext | object | Bluesea BidRequest.Imp extensions |
#### **BidRequest.Imp.Banner**
| Field | Type | Description |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| format | object array; recommended | Array of Format objects representing the banner sizes permitted. If none are specified, then use of the h and w attributes is highly recommended. |
| w | integer | Exact width in device independent pixels (DIPS); recommended if no format objects are specified. |
| h | integer | Exact height in device independent pixels (DIPS); recommended if no format objects are specified. |
| battr | integer array | Blocked creative attributes. |
| api | integer array | List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. |
| pos | integer | Ad position on screen. |
| id | string | Unique identifier for this banner object. Recommended when Banner objects are used with a Video object to represent an array of companion ads.Values usually start at 1 and increase with each object. |
#### **BidRequest.Imp.Banner.Format**
| Field | Type | Description |
| ----- | ------- | ------------------------------------------- |
| w | integer | Width in device independent pixels (DIPS). |
| h | integer | Height in device independent pixels (DIPS). |
#### **BidRequest.Imp.Native**
| Field | Type | Description |
| ------- | ------------------- | -------------------------------------------------------------------------------------------------- |
| request | string; required | Request payload complying with the Native Ad Specification. |
| ver | string; recommended | Version of the Dynamic Native Ads API to which request complies; allowed versions are 1.1 and 1.2. |
| api | integer array | Blocked creative attributes. |
#### **BidRequest.Imp.Video**
| Field | Type | Description |
| ------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| mimes | string array; required | Content MIME types supported (e.g., “video/x-ms-wmv”, “video/mp4”). |
| minduration | integer; recommended; default 5 | Minimum video ad duration in seconds. |
| maxduration | integer; recommended; default 60 | Maximum video ad duration in seconds. |
| protocols | integer array; recommended | Array of supported video protocols. |
| w | integer; recommended | Width of the video player in device independent pixels (DIPS). |
| h | integer; recommended | Height of the video player in device independent pixels (DIPS). |
| startdelay | integer; recommended; default 0 | Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. |
| placement | integer | Placement type for the impression. |
| plcmt | integer | Video placement type for the impression. Reference of IAB Plcmt Subtypes - Video |
| skip | integer; default 0 | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. |
| skipmin | integer; default 0 | Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable. |
| skipafter | integer; default 0 | Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable. |
| linearity | integer | Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. |
| companionad | object array | Array of Banner objects if companion ads are available. |
| companiontype | integer array | Supported VAST companion ad types. |
| battr | integer array | Blocked creative attributes. |
| api | integer array | List of supported API frameworks for this impression. |
| pos | integer | Ad position on screen. |
| ext | object | Bluesea BidRequest.Imp.Video extensions. |
**BidRequest.Imp.Video.Ext**
| Field | Type | Description |
| -------- | ------------------ | ---------------------------------------- |
| rewarded | integer; default 0 | 1 = the ad is rewarded, 0 = non-rewarded |
#### **BidRequest.Imp.Ext**
| Field | Type | Description |
| -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| skadn | object | [Reference of IAB SKAdNetwork](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/skadnetwork.md#object-bidrequestimpextskadn). SKOverlay is supported as well. |
| deeplink | int | 1 = deeplink is supported. |
| fallback | int | Providing a fallback URL if the destination of the deeplink URL cannot be found on the device. 1 = fallback is supported. |
### **BidRequest.App**
| Field | Type | Description |
| --------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string; recommend | supply-specific app ID. |
| name | string | App name (may be aliased at the publisher’s request). |
| bundle | string | A platform-specific application identifier intended to be unique to the app. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is typically a numeric ID. |
| domain | string; recommended | Domain of the app (e.g., “mygame.foo.com”). |
| storeurl | string; recommended | App store URL for an installed app. |
| cat | string array | Array of IAB content categories of the app. |
| ver | string | Application version. |
| publisher | object | Details about the Publisher of the app. |
#### **BidRequest.App.Publisher**
| Field | Type | Description |
| ----- | ------ | -------------- |
| id | string | publisher ID |
| name | string | Publisher name |
### **BidRequest.Device**
| Field | Type | Description |
| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ua | string; recommended | Browser user agent string. |
| geo | object; recommended | Location of the device assumed to be the user’s current location defined by a Geo object. |
| dnt | integer; recommended | Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track. |
| lmt | integer; recommended | “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. |
| ip | string; recommended | IPv4 address closest to device. |
| ipv6 | string | IP address closest to device as IPv6. |
| devicetype | integer | The general type of device. |
| 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”). |
| hwv | string | Hardware version of the device (e.g., “5S” for iPhone 5S). |
| h | integer | Physical height of the screen in pixels. |
| w | integer | Physical width of the screen in pixels. |
| js | integer | Support for JavaScript, where 0 = no, 1 = yes. |
| language | string | Browser language using ISO-639-1-alpha-2 |
| connectiontype | | Network connection type. |
| ifa | string | ID sanctioned for advertiser use in the clear. |
| didsha1 | string | Hardware device ID (e.g., IMEI); hashed via SHA1. |
| didmd5 | string | Hardware device ID (e.g., IMEI); hashed via MD5. |
| dpidsha1 | string | Platform device ID (e.g., Android ID); hashed via SHA1. |
| dpidmd5 | string | Platform device ID (e.g., Android ID); hashed via MD5 |
| macsha1 | string | MAC address of the device; hashed via SHA1. |
| macmd5 | string | MAC address of the device; hashed via MD5. |
| ext | object | Bluesea BidRequest.Device extensions |
#### **BidRequest.Device.Ext**
| Field | Type | Description |
| ----- | ------ | -------------------------------------------------------------------------------------------- |
| ifv | string | A unique identifier for each app on a device that identifies the device to the app's vendor. |
#### **BidRequest.Device.Geo**
| Field | Type | Description |
| --------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| lat | float | Latitude from -90.0 to +90.0, where negative is south. |
| lon | float | Longitude from -180.0 to +180.0, where negative is west. |
| type | integer | Source of location data; recommended when passing lat/lon |
| ipservice | integer | Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2). |
| country | string; recommend | Country code using ISO-3166-1-alpha-3. |
| region | string | Region code using ISO-3166-2; 2-letter state code if USA. |
### **BidRequest.User**
| Field | Type | Description |
| -------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| id | string | Supply-specific ID for the user. At least one of id or buyeruid is recommended. |
| buyeruid | string | Buyer-specific(Bluesea) ID for the user as mapped by supply. At least one of buyeruid or id is recommended. |
| yob | integer | Year of birth as a 4-digit integer. |
| gender | string | Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown). |
| ext | object | Bluesea BidRequest.User extensions. |
**BidRequest.User.Ext**
| Field | Type | Description |
| ------- | ------ | ------------------------------------------------------------------------------------------ |
| consent | string | Extension to signal whether or not the user subject to GDPR regulations has given consent. |
### **BidRequest.Source**
| Field | Type | Description |
| ----- | -------------------- | ------------------------------------------------------------------------------------------------- |
| fd | integer; recommended | Entity responsible for the final impression sale decision, where 0 = supply, 1 = upstream source. |
| ext | object | Bluesea BidRequest.Source extensions |
**BidRequest.Source.Ext**
| Field | Type | Description |
| ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| omid | string | An identifier for the Open Measurement SDK integration. |
| omidpv | string | The version of the Open Measurement SDK integration. |
| schain | object; recommended | Reference of IAB's [SupplyChain](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md) object |
### **BidRequest.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 | | Bluesea Bidrequest.Regs extensions |
**BidRequest.Regs.Ext**
| Field | Type | Description |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| gdpr | integer | Flag indicating if the request is subject to GDPR. |
| us\_privacy | string | Flag indicating consent for requests subject to [CCPA regulations](https://oag.ca.gov/privacy/ccpa). The string format must follow the IAB’s [U.S. privacy specifications](https://iabtechlab.com/standards/ccpa/). |
## BidResponse
| Field | Type | Description |
| ------- | --------------------- | --------------------------------------------------- |
| id | string; required | Bluesea transaction ID, BidRequest.id |
| seatbid | object array | Array of SeatBid objects. |
| bidid | string | Demand response ID to assist with logging/tracking. |
| cur | string; default “USD” | **Only USD is allowed** |
### BidResponse.SeatBid
| Field | Type | Description |
| ----- | ---------------------- | --------------------------------------------------------------------------------- |
| bid | object array; required | Array of Bid objects each related to an impression. **only 1 Bid is allowed**. |
| seat | string | ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid is made. |
**BidResponse.SeatBid.Bid**
| Field | Type | Description |
| -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | string; required | Demand bid ID to assist with logging/tracking. |
| impid | string; required | ID of the Imp object in the related bid request. |
| price | float; required | Bid price expressed as CPM although the actual transaction is for a unit impression only. |
| nurl | string | Win notice URL called if the bid wins. Substitution macros may be included. |
| burl | string | Billing notice URL calledwhen a winning bid becomes billable based on Bluesea side.Substitution macros may be included. |
| lurl | string | Loss notice URL called by the exchange when a bid is known to have been lost.Substitution macros may be included. |
| adm | string | ad markup.Substitution macros may be included. |
| adid | string | ID of a preloaded ad to be served if the bid wins. |
| adomain | string array | Advertiser domain for block list checking (e.g., “ford.com”) |
| bundle | string | A platform-specific application identifier intended to be unique to the app. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID. |
| iurl | string | URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. |
| cid | string | Campaign ID |
| crid | string | Creative ID |
| cat | string array | IAB content categories of the creative. |
| api | integer | Set of attributes describing the creative. |
| attr | integer array | API required by the markup if applicable. |
| protocol | integer | Video response protocol of the markup if applicable. |
| w | integer | Width of the creative in device independent pixels (DIPS). |
| h | integer | Height of the creative in device independent pixels (DIPS). |
| exp | integer | Advisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression. |
| ext | object | Bluesea BidResponseSeatBid.Bid extensions. |
**BidResponse.SeatBid.Bid.Ext**
| Field | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| skadn | object | [Reference of IAB SKAdNetwork](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/skadnetwork.md#object-bidresponseseatbidbidextskadn). SKOverlay is supported as well. |
| deeplink | string | the deeplink URL |
| fallback | string | the fallback URL |
## **Macros**
| Macro | Description |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ${AUCTION\_PRICE} | Clearing price using the same currency and units as the bid.
When rendering markup for test or ad quality purposes,substitute “AUDIT” as the macro value.
|
| ${AUCTION\_MIN\_TO\_WIN}
${AUCTION\_MINIMUM\_BID\_TO\_WIN}
| Minimum bid to win the exchange's auction, using the same currency and units as the bid. |
| ${AUCTION\_LOSS} | Loss reason codes. |