Custom Bid Router Request and Response examples
Bid Opportunity Requests
MediaMath delivers bid opportunity requests to the configured Custom Bid Router endpoints over HTTPS. The content type for the body of the request is set when the endpoint is configured. Binary protobuf is supported.
Request Header example
Content-Type: application/protobuf
X-Timeout: 15Request Body Example 1 - with Open Auction only (protobuf decoded)
{
"device": {
"devicetype": "HIGHEND_PHONE",
"geo": {
"lat": 35.165496826171875,
"lon": 126.86268615722656
},
"ip": "118.219.167.0",
"js": 0,
"language": "ko",
"lmt": 0,
"ua": "Mozilla/5.0 (Linux; Android 8.0.0; SAMSUNG SM-G930S Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/8.2 Chrome/63.0.3239.111 Mobile Safari/537.36"
},
"ext": {
"mmExt": {
"BidFeature": {
"AppID": "0",
"BidInvBrowserType": "50000",
"BrowserID": "40001",
"BrowserLangID": "28523",
"ChannelID": "16",
"ChannelType": "4",
"CID": "93e75a86-036a-4000-9679-000000000000",
"ConnSpeed": "20005",
"CountryID": "60122",
"DeviceID": "41000",
"DmaID": "80723",
"ExchangeID": "5",
"FoldPosition": "2",
"HistCtr": "0.009",
"IdVintage": "2",
"Interstitial": "false",
"IspID": "30001",
"IsPixelTarget": "0",
"OSID": "40009",
"PublisherID": "123456789",
"RegionID": "72917",
"SiteID": "0",
"UserSessionFreq": "99",
"UserTime": {
"Hour": 4,
"Minute": 30,
"WeekDay": 2
},
"UUID": "93e75a86-036a-4000-9679-000000000000",
"VideoCompletion": "-1.000",
"ViewPrcnt": "70"
},
"SelectedEntities": [
{
"CampaignID": "123456",
"OrganizationID": "123456",
"Pacing": {
"PacingIntervalPercentThru": 50,
"PI": 9296
},
"CompanionData": {
"Creatives": [
{
"Height": 250,
"ID": "1234567",
"Width": 300
},
{
"Height": 250,
"ID": "1234568",
"Width": 250
}
],
"AIBTargets": [
{
"SegmentName": "mm:1234567",
"Recency": 79010,
"Frequency": 1
},
{
"SegmentName": "sm:123456789",
"Recency": 82199,
"Frequency": 1
}
],
"CrossDeviceCklessFlags": "0",
"PmpFloorPriceInMicro": 0,
"StrategyGoalType": "CPC",
"StrategyGoalValue": "90000",
"StrategyID": "1234567",
"TargetValues": {
"24": {
"1": {
"targeted": [],
"untargeted": [
"br_Samsung Browser:ve_8.2.0"
]
}
},
"25": {
"1": {
"targeted": [],
"untargeted": [
"os_Android:ve_8.0.0"
]
}
},
"26": {
"1": {
"targeted": [],
"untargeted": [
"fo_Smartphone"
]
}
},
"27": {
"1027": {
"matched": []
}
},
"28": {
"2": {},
"3": {},
"6": {}
},
"29": {
"1": {
"targeted": [],
"untargeted": [
"ma_Samsung:mo_Galaxy S7"
]
}
}
}
}
}
]
}
},
"id": "5c61cd45000836540abd000000000000",
"imp": [
{
"banner": {
"battr": [
1,
6,
100,
104
],
"h": 250,
"pos": "BELOW_THE_FOLD",
"w": 300
},
"bidfloor": 0.01,
"id": "12346",
"instl": 0,
"pmp": {
"deals": [
{
"at": "SECOND_PRICE",
"bidfloor": 0.01,
"id": "12345678901234"
}
],
"privateAuction": 0
},
"secure": 1
}
],
"site": {
"cat": [
"16"
],
"publisher": {
"id": "1233210000"
}
},
"user": {
"buyeruid": "0a1b2c3d-4e5f-6a7b-8c9d-000000000000",
"id": "ABC123RKczLWbWl000000000000"
},
"wseat": [
"1111111111",
"2222222222"
]
}Request Body Example 2 - with Open Auction and PMP-E deals (protobuf decoded)
{
"device": {
"devicetype": "HIGHEND_PHONE",
"geo": {
"lat": 35.165496826171875,
"lon": 126.86268615722656
},
"ip": "118.219.167.0",
"js": 0,
"language": "ko",
"lmt": 0,
"ua": "Mozilla/5.0 (Linux; Android 8.0.0; SAMSUNG SM-G930S Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/8.2 Chrome/63.0.3239.111 Mobile Safari/537.36"
},
"ext": {
"mmExt": {
"BidFeature": {
"AppID": "0",
"BidInvBrowserType": "50000",
"BrowserID": "40001",
"BrowserLangID": "28523",
"ChannelID": "16",
"ChannelType": "4",
"CID": "93e75a86-036a-4000-9679-000000000000",
"ConnSpeed": "20005",
"CountryID": "60122",
"DeviceID": "41000",
"DmaID": "80723",
"ExchangeID": "5",
"FoldPosition": "2",
"HistCtr": "0.009",
"IdVintage": "2",
"Interstitial": "false",
"IspID": "30001",
"IsPixelTarget": "0",
"OSID": "40009",
"PublisherID": "123456789",
"RegionID": "72917",
"SiteID": "0",
"UserSessionFreq": "99",
"UserTime": {
"Hour": 4,
"Minute": 30,
"WeekDay": 2
},
"UUID": "93e75a86-036a-4000-9679-000000000000",
"VideoCompletion": "-1.000",
"ViewPrcnt": "70"
},
"SelectedEntities": [
{
"CampaignID": "123456",
"OrganizationID": "123456",
"Pacing": {
"PacingIntervalPercentThru": 50,
"PI": 9296
},
"CompanionData": {
"Creatives": [
{
"Height": 250,
"ID": "1234567",
"Width": 300
},
{
"Height": 250,
"ID": "1234568",
"Width": 250
}
],
"AIBTargets": [
{
"SegmentName": "mm:12345678",
"Recency": 79010,
"Frequency": 1
},
{
"SegmentName": "sm:123456789",
"Recency": 82199,
"Frequency": 1
}
],
"PMPDeals": [
{
"ID": "12345678901234",
"IsGlobal": false,
"MinBidPrice": 10.500
}
],
"CrossDeviceCklessFlags": "0",
"PmpFloorPriceInMicro": 0,
"StrategyGoalType": "CPC",
"StrategyGoalValue": "90000",
"StrategyID": "12345678",
"TargetValues": {
"24": {
"1": {
"targeted": [],
"untargeted": [
"br_Samsung Browser:ve_8.2.0"
]
}
},
"25": {
"1": {
"targeted": [],
"untargeted": [
"os_Android:ve_8.0.0"
]
}
},
"26": {
"1": {
"targeted": [],
"untargeted": [
"fo_Smartphone"
]
}
},
"27": {
"1027": {
"matched": []
}
},
"28": {
"2": {},
"3": {},
"6": {}
},
"29": {
"1": {
"targeted": [],
"untargeted": [
"ma_Samsung:mo_Galaxy S7"
]
}
}
}
}
}
]
}
},
"id": "5c61cd45000836540abd000000000000",
"imp": [
{
"banner": {
"battr": [
1,
6,
100,
104
],
"h": 250,
"pos": "BELOW_THE_FOLD",
"w": 300
},
"bidfloor": 0.01,
"id": "12346",
"instl": 0,
"pmp": {
"deals": [
{
"at": "SECOND_PRICE",
"bidfloor": 0.01,
"id": "12345678901234"
}
],
"privateAuction": 0
},
"secure": 1
}
],
"site": {
"cat": [
"16"
],
"publisher": {
"id": "1826264727"
}
},
"user": {
"buyeruid": "0a1b2c3d-4e5f-6a7b-8c9d-000000000000",
"id": "ABC123RKczLWbWl000000000000"
},
"wseat": [
"1111111111",
"2222222222"
]
}Response
The CPM response will not be used in MediaMath's bidder if one of the following cases are true:
- Status Code != 200
- len(CampaignID) <= 0
- len(StrategyID) <= 0
- len(CreativeID) <= 0
- CPM <= 0
For returning the ModelID we recommend using a unique modelID or a name with model creation date, so that troubleshooting can be done efficiently. This will be logged for you to be able to identify and perform tasks like A/B splits.
The CPM response can only be for one Open Auction or one PMP-E deal only with one Creative at a time.
Allowed Status Codes List
| Status Code | Description |
|---|---|
| 200 OK | Generic successful execution |
| 204 No Content | Pass the bid opportunity |
Response Header
| HTTP Header Name | Is Required | Description | Type |
|---|---|---|---|
| content-type | Required | The endpoint MUST reply back with application/json as content type. | string |
| X-Log-Request | Optional | See S3 Setup documentation | boolean |
**X-Log-Request: True will allow the given bid request/response to be logged into your S3 bucket. In case of timeout, we automatically log the request.
Response Body
| Field | Is Required | Description | Type |
|---|---|---|---|
| CampaignID | Required | The CampaignID of the CPM Response | string |
| StrategyID | Required | The StrategyID of the CPM Response | string |
| CPM | Required | The Media Cost CPM | double |
| CreativeID | Required | The CreativeID if the CPM Response | string |
| PmpDealID | Required | The PmpDealID of the CPM Response. Set this to an empty string if the CPM is for the Open Auction. | string |
| ModelID | Required | The ModelID of the CPM Response. We recommend using a unique modelID (which can also trace back to the model creation date), so that troubleshooting can be done efficiently. | string |
Example
Response Header Example 1
HTTP/1.1 200 OK
content-type: application/jsonResponse Body Example 1 - Open Auction with only one creative
{
"CampaignID":"123456",
"StrategyID":"1234567",
"CPM":0.3659111954076997,
"CreativeID":"1234567",
"PmpDealID":"",
"ModelID":"Model_123456_09_16_2019"
}The CPM response above is for Open Auction only. The PmpDealID needs to be set to an empty string. This response submits a CPM response for Creative 1234567.
Response Body Example 2 - Pmp deal with only one creative
{
"CampaignID":"123456",
"StrategyID":"1234567",
"CPM":0.3659111954076997,
"CreativeID":"1234567",
"PmpDealID":"12345678901234",
"ModelID":"Model_123456_09_16_2019"
}The CPM response above is for Pmp-E deal only. You need to set the PmpDealID according to the Pmp deal field being received. This response submits a CPM response for Creative 1234567.