# 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 ```text Content-Type: application/protobuf X-Timeout: 15 ``` #### Request Body Example 1 - with Open Auction only (protobuf decoded) ```json { "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) ```json { "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 ```txt HTTP/1.1 200 OK content-type: application/json ``` ### Response Body Example 1 - Open Auction with only one creative ```json { "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 ```json { "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.