Last updated

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: 15

Request 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 CodeDescription
200 OKGeneric successful execution
204 No ContentPass the bid opportunity

Response Header


HTTP Header NameIs RequiredDescriptionType
content-typeRequiredThe endpoint MUST reply back with application/json as content type.string
X-Log-RequestOptionalSee S3 Setup documentationboolean

**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


FieldIs RequiredDescriptionType
CampaignIDRequiredThe CampaignID of the CPM Responsestring
StrategyIDRequiredThe StrategyID of the CPM Responsestring
CPMRequiredThe Media Cost CPMdouble
CreativeIDRequiredThe CreativeID if the CPM Responsestring
PmpDealIDRequiredThe PmpDealID of the CPM Response. Set this to an empty string if the CPM is for the Open Auction.string
ModelIDRequiredThe 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/json

Response 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.