Marketplaces API V2.0 API (2.0)

Download OpenAPI description
Overview
Languages
Servers
Mock server
https://apidocs.mediamath.com/_mock/apis/marketplaces/
https://api.mediamath.com/deals/v1.0/

Private Marketplace Exchange (PMP-E)

Private Marketplace Direct (PMP-E)

Operations

List Deals

Request

List the Deals

You can read more about deals and deal groups (including adding them through T1), deal ownership, and deal best practices here. You may also find it useful for exploring input values.

Query
idsstring

_

exportstring

_

deal_typestring

Returns a list of deals that match the specified query

qstring

Returns a list of deals that match the specified query

sort_byboolean

Returns a list of deals sorted by the specified parameter

page_offsetstring

Returns a list of deals starting from the specified page offset

page_limitinteger

Returns a number of deals equal to the specified page limit

currency_codestring

Returns a list of deals with price attributes converted to such currency

statusboolean

Returns a list of deals that match the specified status

owner.typestring

Returns a list of deals that match the specified owner type

Enum"INTERNAL""ORGANIZATION""AGENCY""ADVERTISER"
strategy_idinteger

Returns a list of deals that are currently targeted by the strategy with that id

owner.advertiser_idinteger

Returns a list of deals that are editable by users of the advertiser with that id

owner.agency_idinteger

Returns a list of deals that are editable by users of the agency with that id

owner.organization_idintegerrequired

Returns a list of deals that are editable by users of the organization with that id

permissions.advertiser_idinteger

Returns a list of deals that are targetable by the advertiser with that id

Headers
Authorizationstringrequired

_

curl -i -X GET \
  'https://apidocs.mediamath.com/_mock/apis/marketplaces/deals?currency_code=string&deal_type=string&export=string&ids=string&owner.advertiser_id=0&owner.agency_id=0&owner.organization_id=0&owner.type=INTERNAL&page_limit=0&page_offset=string&permissions.advertiser_id=0&q=string&sort_by=true&status=true&strategy_id=0' \
  -H 'Authorization: string'

Responses

Please note that currently bill_type does not disclose here. GET /deals/{deal ID) will however disclose that parameter, and the creation or updating of the deal will both allow bill_type to be set and display it in the response.

Body
dataArray of objects
metaobject
Response
{
  "data": [
    {
      "created_on": "2019-08-14T17:23:56+00:00",
      "deal_identifier": "MDM-17302-00003",
      "deal_type": "STANDARD",
      "description": "News",
      "end_datetime": "2999-12-31T05:00:00+00:00",
      "entity_type": "deal",
      "id": 384382,
      "name": "Rubicon Project_The Washington Post_EBDA_Private Auction_Standard_Desktop & TabletWeb Display_Display_728x90, 160x600, 300x250_FLOOR_First Price_NAR_13_PREMIUM",
      "owner": {
        "id": 166628,
        "type": "ADVERTISER"
      },
      "permissions": {
        "advertiser_ids": [
          166628
        ],
        "agency_ids": [],
        "all_organizations": false,
        "organization_ids": []
      },
      "price": {
        "currency_code": "USD",
        "value": "13.0000"
      },
      "price_method": "CPM",
      "price_type": "FLOOR",
      "start_datetime": "2019-08-14T17:23:31+00:00",
      "status": true,
      "sub_supply_source_id": null,
      "supply_source_id": 11,
      "updated_on": "2019-08-14T17:23:56+00:00"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "status": "ok",
    "total_count": 1
  }
}

Create Deal

Request

Create Deal

For more insight into deal creation (inside T1), read here. You may find it useful for exploring input values.

Headers
Content-Typestringrequired

Content-Type

Default application/json
Cookiestringrequired

Cookie

Default adama_session=<<sessionid>>
Body

_

bill_typestring

Bill recipient when creating a deal

Enum"EXCHANGE""NONE""PUBLISHER"
deal_identifierstring<= 255 characters

the identifier used within a bid request to reference the deal

Default "EXCHANGE"
deal_typestring

When creating deal type PG, price_type must be set to FIXED and valid start_datetime and end_datetime must be present.

Default "STANDARD"
Enum"PG""STANDARD"
descriptionstring<= 4095 characters

the description of the deal

end_datetimestring(date-time)

string / timestamp as full RFC 3339 date strings including timezone offsets: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS-##:##. Default is current time.

namestring<= 255 charactersrequired

the name of the deal

ownerobjectrequired

level of ownership for the deal (i.e. who can edit the deal) and the id of the ownership entity. for example, if the ownership level is set to ADVERTISER, anyone with access to such advertiser can edit this deal.

owner.​idinteger
owner.​typestring
Enum"ADVERTISER""AGENCY""INTERNAL""ORGANIZATION"
permissionsobjectrequired

List of entities that are allowed to target this deal, which should be either the owner entity or sub-entities of the owner entity. if a higher-level entity is included, then do not include any lower-level entity that is part of the included higher level entity. for example, if an organization X is listed in this parameter, then automatically all agencies and advertisers that are part of the organization X will be included and listing any such agencies and advertisers part of organization X will cause a validation error.

permissions.​advertiser_idsArray of integers
permissions.​agency_idsArray of integers
permissions.​all_organizationsbooleanrequired
permissions.​organization_idsArray of integers
priceobjectrequired

price floor or fixed value to use in auction along with the associated currency code

price.​currency_codestring= 3 characters

3-character currency code

Default "USD"
price.​valuestring

$9,999,999.9999 maximum

price_methodstring

only CPM cost accrual is supported

Default "CPM"
Value"CPM"
price_typestring

The deal is a "FLOOR" price deal (bids must be above this floor, and will likely clear above this floor) or "FIXED" price deal (bids must be at this price or above, and will clear at the fixed price)

Default "FLOOR"
Enum"FIXED""FLOOR"
start_datetimestring(date-time)

string / timestamp as full RFC 3339 date strings including timezone offsets: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS-##:##. Default is current time.

statusboolean

If the deal is active

Default true
sub_supply_source_idinteger or null

the id of the publisher if the supply_source_id is set to 83 (BidSwitch)

supply_source_idintegerrequired

the exchange providing the deal

curl -i -X POST \
  https://apidocs.mediamath.com/_mock/apis/marketplaces/deals \
  -H 'Content-Type: application/javascript' \
  -H 'Cookie: adama_session=<<sessionid>>' \
  -d '[object Object]'

Responses

Body
dataobject
metaobject
Response
No response example

List Deals and their reporting data

Request

List the Deals

This call returns all information you get with a deal and also the reporting data for a specified time interval (time_window : "yesterday", "last_7_days", "last_30_days", "month_to_date", or a custom range using "start_date" and "end_date"). You should only send time_window or start_date/end_date but not a combination of the both. The filters field allows you to filter the results based on what you need, e.g: "filters": [{"field":"id", "op":"in", "value": [123]}] will look for deals that have 123 in their ID. {"field" :"match_rate", "op":">", "value" :0} will return deals that have a "match_rate" greater than 0. You can also use the "sorting" field to sort the results, eg: "sorting":[{"field":"viewability_rate", "dir":"asc"}] will give the results sorted by the viewability_rate field.

  "reporting": {
    "organization_id": 100048,
    "time_window": "last_7_days",
    "start_date": null,
    "end_date": null
  },
  "filters": [
   {"field": "id",
               "op": "in",
               "value" : [447824]},
               {"field": "match_rate",
               "op": ">",
               "value" : 0}
  ],
  "sorting": [
      {
               "field": "viewability_rate",
               "dir": "asc"
           }
 
  ],
  "paging": {
    "page_offset": 0
  }
}
Headers
Content-Typestringrequired

Content-Type

Default application/json
Cookiestringrequired

Cookie

Default adama_session=<<sessionid>>
Body

_

bill_typestring

Bill recipient when creating a deal

Enum"EXCHANGE""NONE""PUBLISHER"
deal_identifierstring<= 255 characters

the identifier used within a bid request to reference the deal

Default "EXCHANGE"
deal_typestring

When creating deal type PG, price_type must be set to FIXED and valid start_datetime and end_datetime must be present.

Default "STANDARD"
Enum"PG""STANDARD"
descriptionstring<= 4095 characters

the description of the deal

end_datetimestring(date-time)

string / timestamp as full RFC 3339 date strings including timezone offsets: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS-##:##. Default is current time.

namestring<= 255 charactersrequired

the name of the deal

ownerobjectrequired

level of ownership for the deal (i.e. who can edit the deal) and the id of the ownership entity. for example, if the ownership level is set to ADVERTISER, anyone with access to such advertiser can edit this deal.

owner.​idinteger
owner.​typestring
Enum"ADVERTISER""AGENCY""INTERNAL""ORGANIZATION"
permissionsobjectrequired

List of entities that are allowed to target this deal, which should be either the owner entity or sub-entities of the owner entity. if a higher-level entity is included, then do not include any lower-level entity that is part of the included higher level entity. for example, if an organization X is listed in this parameter, then automatically all agencies and advertisers that are part of the organization X will be included and listing any such agencies and advertisers part of organization X will cause a validation error.

permissions.​advertiser_idsArray of integers
permissions.​agency_idsArray of integers
permissions.​all_organizationsbooleanrequired
permissions.​organization_idsArray of integers
priceobjectrequired

price floor or fixed value to use in auction along with the associated currency code

price.​currency_codestring= 3 characters

3-character currency code

Default "USD"
price.​valuestring

$9,999,999.9999 maximum

price_methodstring

only CPM cost accrual is supported

Default "CPM"
Value"CPM"
price_typestring

The deal is a "FLOOR" price deal (bids must be above this floor, and will likely clear above this floor) or "FIXED" price deal (bids must be at this price or above, and will clear at the fixed price)

Default "FLOOR"
Enum"FIXED""FLOOR"
start_datetimestring(date-time)

string / timestamp as full RFC 3339 date strings including timezone offsets: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS-##:##. Default is current time.

statusboolean

If the deal is active

Default true
sub_supply_source_idinteger or null

the id of the publisher if the supply_source_id is set to 83 (BidSwitch)

supply_source_idintegerrequired

the exchange providing the deal

curl -i -X POST \
  https://apidocs.mediamath.com/_mock/apis/marketplaces/deal_analytics \
  -H 'Content-Type: application/javascript' \
  -H 'Cookie: adama_session=<<sessionid>>' \
  -d '[object Object]'

Responses

Body
dataobject
metaobject
Response
No response example

Get Deal

Request

Get Deal

You can read more about deals and deal groups (including adding them through MediaMath Platform), deal ownership, and deal best practices here. You may also find it useful for exploring input values.

Path
idintegerrequired

id

Query
currency_codestring

Returns a list of deals with price attributes converted to such currency

Headers
Authorizationstringrequired

Authorization