Marketplaces API V2.0 API (2.0)

Download OpenAPI description
Overview
Languages
Servers
https://api.mediamath.com/deals/v1.0/

Private Marketplace Exchange (PMP-E)

Private Marketplace Direct (PMP-E)

Operations

Update Deal

Request

Update Deal

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.

Path
idintegerrequired

id

Headers
Content-Typestringrequired

Content-Type

Default application/json
Cookiestringrequired

Cookie

Default adama_session=<<sessionid>>
Body

Note: The owner type and ID cannot be altered once the deal has been created.

bill_typestring

Bill recipient when creating a deal

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

the identifier used within a bid request to reference the deal

deal_typestring

When updating deal to 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-##:##

namestring<= 255 characters

the name of the deal

permissionsobject

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.

priceobject

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

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)

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

statusboolean

whether 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_idinteger

the exchange providing the deal

curl -i -X POST \
  'https://api.mediamath.com/deals/v1.0/deals/{id}' \
  -H 'Content-Type: application/javascript' \
  -H 'Cookie: adama_session=<<sessionid>>' \
  -d '[object Object]'

Responses

Body
dataobject
metaobject
Response
{
  "data": {
    "bill_type": "EXCHANGE",
    "created_on": "2019-08-19T14:14:59+00:00",
    "deal_identifier": "somethingelselongerstring3",
    "deal_type": "STANDARD",
    "description": "My First Deal Update",
    "end_datetime": "2999-12-31T05:00:00+00:00",
    "entity_type": "deal",
    "id": 384607,
    "name": "Alec",
    "owner": {
      "id": 464566,
      "type": "INTERNAL"
    },
    "permissions": {
      "advertiser_ids": [],
      "agency_ids": [],
      "all_organizations": true,
      "organization_ids": []
    },
    "price": {
      "currency_code": "EUR",
      "value": "2.7500"
    },
    "price_method": "CPM",
    "price_type": "FLOOR",
    "start_datetime": "2999-03-13T16:39:22+00:00",
    "status": true,
    "sub_supply_source_id": null,
    "supply_source_id": 41,
    "updated_on": "2019-08-19T14:58:33+00:00"
  },
  "meta": {
    "status": "ok"
  }
}

List the Deal Groups

Request

List the Deal Groups When executing the GET call, you must specify one of the following: 'owner.organization_id', or 'ids' parameter, or else you will receive an error.

Query
idsstring

ids

exportstring

export

allinteger

all

statusboolean

status

deal_idinteger

deal_id

strategy_idintegerrequired

strategy_id

owner.organization_idintegerrequired

owner.organization_id

page_offsetinteger

page_offset

page_limitinteger

page_limit

sort_bystring

sort_by

qstring

q

Headers
Authorizationstring

Authorization

curl -i -X GET \
  'https://api.mediamath.com/deals/v1.0/deal_groups?all=0&deal_id=0&export=string&ids=string&owner.organization_id=0&page_limit=0&page_offset=0&q=string&sort_by=string&status=true&strategy_id=0' \
  -H 'Authorization: string'

Responses

Body
dataArray of objects
metaobject
Response
No response example

Create a Deal Group

Request

Create a Deal Group

Deal Groups are a feature that will allow you and your team to package individual deals into groups. This should streamline targeting, improve marketability (ex. creating a viewability deal group), and simplify bulk updating of strategies targeting deals.

Deal Groups Ownership and Targeting Permissions: Ownership: Deal Groups can be created at the Organization, Agency, or Advertiser level of the T1 hierarchy. The creating entity (ex. Agency Z) owns the Deal Group, and any users with access to that entity can edit the Deal Group. Similarly, individual deals can be created at the Organization, Agency, or Advertiser level. The creating entity owns and can edit the deal. A Deal Group can only include deals which have the same owning entity as the Deal Group. This means that a Deal Group created by Agency Z can only include deals owned by Agency Z. That Deal Group cannot include deals created by any other entity, including Agency Z’s parent Organization or subsidiary Advertisers. Like deals, ownership of a Deal Group cannot change once it is created. Please consider this when creating deals and Deal Groups and developing targeting strategies. Targeting: Targeting permissions are set within individual deals. The default setting permissions all sub-entities of the deal owning entity to target the deal. For example, a deal created by Org X will by default be targetable by all agencies, advertisers and their strategies within Org X. Targeting permissions can also be restricted to particular subsidiary entities of the owning entity. For example, a deal may be created at the Agency level, but only permission targeting for two out of three advertisers within that agency. There are no targeting permissions set within a deal group. Deal Groups instead honor the targeting permissions of the deals within them. Inside a strategy, users can expand Deal Groups to view the deals within them. Users will only be able to view deals which they are permissioned to target. Deals showing in gray are inactive.

Note: the text above, with screenshots of T1 editing, can be found here

Headers
Content-Typestringrequired

_

Cookiestringrequired

_

Body

_

deal_idsArray of integers
descriptionstring
namestring
ownerobject
statusboolean
curl -i -X POST \
  https://api.mediamath.com/deals/v1.0/deal_groups \
  -H 'Content-Type: application/javascript' \
  -H 'Cookie: string' \
  -d '[object Object]'

Responses

Body
dataobject
metaobject
Response
No response example