Entity Hierarchy

MediaMath Overview

Retrieving Entities
- Retrieving Single Entities
  - Including Related Entities
- Retrieving Multiple Entities
Creating New Entities
Updating Entities
- Update Timeframes
- Retrieving Entity Changelogs

Retrieving Entities

Individual entities and collections of entities can be retrieved using HTTP GET requests to their respective API endpoints:

GET https://api.mediamath.com/api/v2.0/organizations

<?xml version='1.0' ?>
<result called_on="2014-11-18 16:34:14.008469+00">
  <entities count="1" start="0">
    <entity name="ACME Org" id="100048" type="organization" />
  </entities>
  <status code="ok" />
</result>

Responses are made up of a result element at the root of the document, which contains a status element indicating the status of the API response. If the request was for a single entity, the result element will contain a single entity element; otherwise, it will contain an entities element containing entity elements representing the requested entities.

Retrieving Single Entities

To retrieve an entity by ID, issue a GET request to the entity API base followed by the entity ID, as in this example:

GET https://api.mediamath.com/api/v2.0/strategies/515578

<?xml version='1.0' ?>
<result called_on="2014-11-19 20:28:51.537372+00">
  <entity name="Sassytimes" id="515578" type="strategy" version="1">
    <prop name="campaign_id" value="166047" />
    <prop name="start_date" value="2014-10-08T10:08:41">
      <local_time value="2014-10-08T10:08:41" zone_name="Etc/GMT" />
    </prop>
    <prop name="end_date" value="2014-11-05T23:59:00">
      <local_time value="2014-11-05T23:59:00" zone_name="Etc/GMT" />
    </prop>
    <prop name="use_campaign_start" value="0" />
    <prop name="use_campaign_end" value="1" />
    <prop name="use_optimization" value="0" />
    <prop name="pacing_type" value="even" />
    <prop name="pacing_interval" value="day" />
    [ . . . ]
  </entity>
  <status code="ok" />
</result>

Including Related Entities

Some entities contain references to other entities to which they are related. For example, a strategy belongs to a single campaign; when you retrieve a strategy entity, it will include a campaign_id property. You can include details about this kind of related entity inside the entity you’re requesting by appending the with parameter to the URL you request. Pass the name (singular) of the entity you’re interested in as the value of the with parameter:

GET https://api.mediamath.com/api/v2.0/strategies/515578?with=campaign

<?xml version='1.0' ?>
<result called_on="2014-11-19 20:58:48.106084+00">
  <entity name="Sassytimes" id="515578" type="strategy" version="1">
    <entity name="Adam Test" id="166047" rel="campaign" type="campaign" version="0">
      <prop name="advertiser_id" value="110036" />
      <prop name="status" value="1" />
      [ . . . ]
    </entity>
    <prop name="campaign_id" value="166047" />
    [ . . . ]
  </entity>
  <status code="ok" />
</result>

To retrieve details about multiple entities directly related to the top-level entity you’re requesting, use multiple with parameters:

GET https://api.mediamath.com/api/v2.0/advertisers/125819?with=agency&with=vertical

<?xml version='1.0' ?>
<result called_on="2014-11-19 22:07:01.92313+00">
  <entity name="ITtest - Wed Jul  9 19:34:19 2014" id="125819" type="advertiser" version="0">
    <entity name="Food &amp; Beverages" id="13" rel="vertical" type="vertical" version="0">
      <prop name="created_on" value="2010-05-05T16:13:12" />
      <prop name="updated_on" value="2010-05-05T16:13:12" />
      <prop name="name" value="Food &amp; Beverages" />
    </entity>
    <entity name="ag_release_2.77" id="103078" rel="agency" type="agency" version="0">
      <prop name="organization_id" value="100048" />
      <prop name="name" value="ag_release_2.77" />
      <prop name="created_on" value="2014-04-17T02:35:03" />
      <prop name="updated_on" value="2014-04-17T02:35:03" />
      <prop name="status" value="1" />
      <prop name="allow_x_adv_pixels" value="1" />
      <prop name="allow_x_adv_optimization" value="0" />
      <prop name="dmp_enabled" value="inherits" />
    </entity>
    <prop name="agency_id" value="103078" />
    <prop name="name" value="ITtest - Wed Jul  9 19:34:19 2014" />
    <prop name="vertical_id" value="13" />
    <prop name="ad_server_id" value="9" />
    <prop name="allow_x_strat_optimization" value="0" />
    [ . . . ]
  </entity>
  <status code="ok" />
</result>

You can also retrieve details about entities related to the related entities themselves. To do this, pass a comma-separated list of entity names in a with parameter:

GET https://api.mediamath.com/api/v2.0/strategies/515578?with=campaign,advertiser

<?xml version='1.0' ?>
<result called_on="2014-11-19 21:26:22.509392+00">
  <entity name="Sassytimes" id="515578" type="strategy" version="1">
    <entity name="Adam Test" id="166047" rel="campaign" type="campaign" version="0">
      <entity name="Otniel Test Advertiser" id="110036" rel="advertiser" type="advertiser" version="2">
        <prop name="agency_id" value="101324" />
        <prop name="name" value="Otniel Test Advertiser" />
        <prop name="vertical_id" value="7" />
        <prop name="ad_server_id" value="6" />
        <prop name="allow_x_strat_optimization" value="0" />
        [ . . . ]
      </entity>
      <prop name="advertiser_id" value="110036" />
      <prop name="status" value="1" />
      [ . . . ]
    </entity>
    <prop name="campaign_id" value="166047" />
    [ . . . ]
  </entity>
  <status code="ok" />
</result>

Retrieving Multiple Entities

To retrieve multiple entities in a single call, issue a GET request to the API endpoint for the entity you’re interested in. Lists of entities are paginated by default, and the maximum number of entities per page is 100. Use the page_limit parameter to specify how many entities to retrieve, and the page_offset parameter to specify the index of the first element in the collection to retrieve (not the page number).

GET https://api.mediamath.com/api/v2.0/strategies?page_limit=5&page_offset=10

<?xml version='1.0' ?>
<result called_on="2014-11-20 13:35:01.27436+00">
  <entities count="1213" start="10">
    <entity name="Test Publisher PMP Test 2" id="566901" type="strategy">
    </entity>
    <entity name="testVideoStr" id="566678" type="strategy">
    </entity>
    <entity name="3" id="566653" type="strategy">
    </entity>
    <entity name="test #12" id="566306" type="strategy">
    </entity>
    <entity name="test" id="566080" type="strategy">
    </entity>
  </entities>
  <status code="ok" />
</result>

Including Entity Properties

When requesting a collection of entities, the default output will return only the name, id, and type properties of the entity, as shown in the above example. To include all properties of entities returned by collection endpoints, include the full parameter in the URL query string. Set the full parameter to a comma-separated list of entities to include full properties for. For example, this query returns the requested strategies, and uses the with parameter to include their associated campaign, advertiser, agency, and organization. By setting full=strategy,campaign, it only includes full properties for the strategy and campaign entities:

GET https://api.mediamath.com/api/v2.0/strategies?page_limit=2&with=campaign,advertiser,agency,organization&full=strategy,campaign

<?xml version='1.0' ?>
<result called_on="2015-08-06 20:45:50.38436+00">
  <entities count="781162" start="0">
    <entity name="Strategy 863186" id="863186" type="strategy" version="2">
      <entity name="Campaigns 205095" id="205095" rel="campaign" type="campaign" version="8">
        <entity name="Advertiser 142420" id="142420" rel="advertiser" type="advertiser">
          <entity name="Agency 107447" id="107447" rel="agency" type="agency">
            <entity name="Org 100821" id="100821" rel="organization" type="organization" />
          </entity>
        </entity>
        <prop name="advertiser_id" value="142420" />
        <prop name="status" value="1" />
        <prop name="io_name" value="" />
        <prop name="io_reference_num" value="" />
        <prop name="name" value="Campaigns 205095" />
        [ additional campaign properties ]
      <prop name="campaign_id" value="205095" />
      <prop name="start_date" value="2015-07-27T05:49:59">
        <local_time value="2015-07-27T05:49:59" zone_name="Etc/GMT" />
      </prop>
      <prop name="use_campaign_start" value="0" />
      <prop name="use_campaign_end" value="1" />
      [ additional strategy properties ]
    </entity>
    <entity name="Strategy 863185" id="863185" type="strategy" version="2">
      <entity name="Campaigns 205095" id="205095" rel="campaign" type="campaign" version="8">
        <entity name="Advertiser 142420" id="142420" rel="advertiser" type="advertiser">
          <entity name="Agency 107447" id="107447" rel="agency" type="agency">
            <entity name="Org 100821" id="100821" rel="organization" type="organization" />
          </entity>
        </entity>
        <prop name="advertiser_id" value="142420" />
        <prop name="status" value="1" />
        <prop name="io_name" value="" />
        <prop name="io_reference_num" value="" />
        <prop name="name" value="Campaigns 205095" />
        [ additional campaign properties ]
      </entity>
      <prop name="campaign_id" value="205095" />
      <prop name="start_date" value="2015-07-27T05:49:55">
        <local_time value="2015-07-27T05:49:55" zone_name="Etc/GMT" />
      </prop>
      <prop name="use_campaign_start" value="0" />
      <prop name="use_campaign_end" value="1" />
      [ additional strategy properties ]
    </entity>
  </entities>
  <status code="ok" />
</result>

To include all properties for all entities returned by the API call, use full=*:

GET https://api.mediamath.com/api/v2.0/strategies?page_limit=2&full=*

<?xml version='1.0' ?>
<result called_on="2015-08-06 20:39:37.35757+00">
  <entities count="781162" start="0">
    <entity name="Strategy 863186" id="863186" type="strategy" version="2">
      <prop name="campaign_id" value="205095" />
      <prop name="start_date" value="2015-07-27T05:49:59">
        <local_time value="2015-07-27T05:49:59" zone_name="Etc/GMT" />
      </prop>
      <prop name="use_campaign_start" value="0" />
      <prop name="use_campaign_end" value="1" />
      [ additional strategy properties ]
    </entity>
    <entity name="Strategy 863185" id="863185" type="strategy" version="2">
      <prop name="campaign_id" value="205095" />
      <prop name="start_date" value="2015-07-27T05:49:55">
        <local_time value="2015-07-27T05:49:55" zone_name="Etc/GMT" />
      </prop>
      <prop name="use_campaign_start" value="0" />
      <prop name="use_campaign_end" value="1" />
      [ additional strategy properties ]
    </entity>
  </entities>
  <status code="ok" />
</result>

Sorting

Include a sort_by parameter in a requst for multiple entitites to sort the entities by a named property:

GET https://api.mediamath.com/api/v2.0/strategies?page_limit=5&sort_by=name

<?xml version='1.0' ?>
<result called_on="2014-11-20 13:38:20.127229+00">
  <entities count="1213" start="0">
    <entity name="$100:$5/DayPace" id="375917" type="strategy">
    </entity>
    <entity name="1/3" id="117725" type="strategy">
    </entity>
    <entity name="2.24 RMX API" id="112393" type="strategy">
    </entity>
    <entity name="2.24 RMX API 2" id="112394" type="strategy">
    </entity>
    <entity name="2.31" id="124506" type="strategy">
    </entity>
  </entities>
  <status code="ok" />
</result>

To sort in descending order, use a - sign before the parameter to sort on, e.g. sort_by=-name. To sort by multiple properties, pass a comma-separated list of properties in the sort_by parameter. For example, sort_by=name,-total_budget would return a list of entities sorted by name ascending, then, for entities with the same name, by budget descending.

Querying for entities

To retrieve elements that have properties matching certain expressions, you can use the q parameter. Query predicates are composed of three parts:

the property being searched upon;
the operator; and
the value to match.

Supported operators include:

== (numeric equality or case-sensitive string identity)
!= (numeric inequality or case-sensitive string non-identity)
=: (case-insensitive match, allows substring using * wildcards)
< (less than)
<= (less than or equal to)
> (greater than)
>= (greater than or equal to)

Suppose the user is interested in those campaigns whose name is Lambda Campaign Spend. In this case, the comparison of “exact match” would be expressed by an == operator. Note that query strings must be URL-encoded:

GET https://api.mediamath.com/api/v2.0/campaigns?q=name%3D%3DLambda%20Campaign%20Spend

<?xml version='1.0' ?>
<result called_on="2013-09-23 12:06:57.375102-04">
  <entities count="5" start="0">
    <entity name="Lambda Campaign Spend" id="592" type="campaign" />
    <entity name="Lambda Campaign Spend" id="591" type="campaign" />
    <entity name="Lambda Campaign Spend" id="590" type="campaign" />
    <entity name="Lambda Campaign Spend" id="589" type="campaign" />
    <entity name="Lambda Campaign Spend" id="588" type="campaign" />
  </entities>
  <status code="ok" />
</result>

To combine multiple expressions in a query string, use an ampersand (&). For example, to retrieve all campaigns with the name of Test Campaign and a total_budget greater than or equal to $10,000, you could compose the query string name==Test Campaign&total_budget>=10000. The URL-encoded request would look like this:

GET https://api.mediamath.com/api/v2.0/campaigns?q=name%3D%3DTest%20Campaign%26total_budget%3E%3D10000

<?xml version='1.0' ?>
<result called_on="2013-12-30 14:49:38.379-05">
  <entities count="13" start="0">
    <entity name="Test Campaign" id="256" type="campaign" />
    <entity name="Test Campaign" id="228" type="campaign" />
    <entity name="Test Campaign" id="399" type="campaign" />
  </entities>
  <status code="ok" />
</result>

Retrieving Multiple Specific Entities by ID

The ‘q=’ syntax also supports fetching a list of entities of the same type specified by their entity ID numbers. The general formula for this is:

GET https://api.mediamath.com/api/v2.0/strategies?q=(123,234,456)

<?xml version='1.0' ?>
<result called_on="2013-12-30 14:49:38.379-05">
  <entities count="13" start="0">
    <entity name="Test Strategy" id="123" type="strategy" />
    <entity name="Test Strategy" id="234" type="strategy" />
    <entity name="Test Strategy" id="456" type="strategy" />
  </entities>
  <status code="ok" />
</result>

Entity IDs are limited to the range 1 through 2147483647. Requesting a q=() ID outside that range will result in a 400 response.

Substring search

Adding a search string between angled brackets to the ‘q=’ parameter will perform a substring match across all string fields of an entity.

GET https://api.mediamath.com/api/v2.0/users?q=<trevor>

<?xml version='1.0' ?>
<result called_on="2013-12-30 14:49:38.379-05">
  <entities count="3" start="0">
    <entity name="trev" id="123" type="user" />
    <entity name="auser" id="234" type="user" />
    <entity name="greebl" id="456" type="user" />
  </entities>
  <status code="ok" />
</result>

Filtering based on IDs of related entities

We often want to limit the data returned by an API GET call to those records which display a particular relationship to instances of other business objects. Such a relationship may be one of hierarchy – where an object is a descendent of a “higher-level” type of object – or one of linkage – where an object is linked to a particular instance of a completely different type of business object. In either case, the user wants to limit the selection of objects returned to a particular subset of those business objects.

To accomplish this, you can insert a /limit component in the URL of a request for multiple entities. This allows you to filter the data returned according to a hierarchical relationship, a linkage relationship, or a combination of both.

Filtering based on hierarchical relationships

The main hierarchical relationship in the Execution and Management API is the one between organizations, advertisers, agencies, advertisers, campaigns, and strategies, respectively. When requesting a collection of entities in this hierarchy, you can use a limit URL component to retrieve only entities belonging to a specific parent. For example, to retrieve campaigns belonging to the advertiser with ID 126, you could issue the following request:

GET https://api.mediamath.com/api/v2.0/campaigns/limit/advertiser=126

<?xml version='1.0' ?>
<result called_on="2013-09-23 11:39:32.095432-04">
  <entities count="3" start="0">
    <entity name="Banana" id="582" type="campaign" />
    <entity name="Delta" id="874" type="campaign" />
    <entity name="Epsilon" id="277" type="campaign" />
  </entities>
<status code="ok" />

You can use . in /limit URL components to filter based on entities higher up the hierarchy. For example, to retrieve campaigns for all advertisers in agency ID 914, you could issue this request:

GET https://api.mediamath.com/api/v2.0/campaigns/limit/advertiser.agency=914

<?xml version='1.0' ?>
<result called_on="2013-09-23 11:46:12.422078-04">
  <entities count="11" start="0">
    <entity name="Alpha" id="087" type="campaign" />
    <entity name="Beta" id="609" type="campaign" />
    <entity name="Banana" id="582" type="campaign" />
    <entity name="Gamma" id="085" type="campaign" />
    <entity name="Delta" id="874" type="campaign" />
    <entity name="Kappa Demo Campaign" id="770" type="campaign" />
    <entity name="Epsilon" id="277" type="campaign" />
    <entity name="Zeta" id="553" type="campaign" />
    <entity name="Eta" id="083" type="campaign" />
    <entity name="Theta" id="548" type="campaign" />
    <entity name="Iota" id="417" type="campaign" />
  </entities>
  <status code="ok" />
</result>

Filtering based on linkage relationships

Some entities are linked to other entities through other entities that are related to both. For example, a vendor_contract entity represents a relationship between a campaign entity and a vendor entity. To retrieve all campaigns using a specific vendor, then, you can issue a request like this:

GET https://api.mediamath.com/api/v2.0/campaigns/limit/vendor_contracts.vendor=515

<?xml version='1.0' ?>
<result called_on="2013-12-19 14:34:59.656-05">
  <entities count="272" start="0">
    <entity name="AB managed margin" id="016" type="campaign" />
    <entity name="MM CPC test" id="037" type="campaign" />
    <entity name="OLD Golden Clouds" id="256" type="campaign" />
    <entity name="Golden Clouds" id="274" type="campaign" />
    [ . . . ]
  </entities>
  <status code="ok" />
</result>

Note that, for /limit URL components involving linkage relationships, the plural form of the linkage entity must be used — /limit/vendor_contracts, not /limit/vendor_contract.

Creating New Entities

Entities in the MediaMath Execution and Management API are created by issuing a POST request to the entity’s API endpoint. Entity properties should be sent as URL-encoded parameters in the POST body. The pages in this documentation describing individual entities include details on which properties must be specified when creating new entities. For example, creating a new Agency requires a name parameter and an organization_id parameter.

POST https://api.mediamath.com/api/v2.0/agencies

name=Demo Agency&organization_id=100048

<?xml version='1.0' ?>
<result called_on="2014-11-20 20:38:44.194412+00">
  <entity name="Demo Agency" id="104981" type="agency" version="0">
    <prop name="organization_id" value="100048" />
    <prop name="name" value="Demo Agency" />
    <prop name="created_on" value="2014-11-20T20:38:44" />
    <prop name="updated_on" value="2014-11-20T20:38:44" />
    <prop name="status" value="0" />
    <prop name="allow_x_adv_pixels" value="0" />
    <prop name="allow_x_adv_optimization" value="0" />
    <prop name="dmp_enabled" value="inherits" />
  </entity>
  <status code="ok" />
</result>

If all required parameters are valid, the server returns a new entity with its own id and version parameters. You can then access the entity at https://api.mediamath.com/api/v2.0/[type]/[id], where [type] represents the entity type (agency, in this example) and [id] is the entity ID.

Updating Entities

To update an entity, you’ll first need to know the current version property of the entity. You can access this by issuing a GET request to the entity’s URL:

GET https://api.mediamath.com/api/v2.0/agencies/104981

<?xml version='1.0' ?>
<result called_on="2014-11-20 21:01:08.899205+00">
  <entity name="Demo Agency" id="104981" type="agency" version="0">
    <prop name="organization_id" value="100048" />
    <prop name="name" value="Demo Agency" />
    <prop name="created_on" value="2014-11-20T20:38:44" />
    <prop name="updated_on" value="2014-11-20T20:38:44" />
    <prop name="status" value="0" />
    <prop name="allow_x_adv_pixels" value="0" />
    <prop name="allow_x_adv_optimization" value="0" />
    <prop name="dmp_enabled" value="inherits" />
  </entity>
  <status code="ok" />
</result>

Then, issue a POST request to the entity’s URL, including the version parameter and any properties you’d like to update:

POST https://api.mediamath.com/api/v2.0/agencies/104981

name=Demo Agency Updated&version=0

<?xml version='1.0' ?>
<result called_on="2014-11-20 21:04:35.370908+00">
  <entity name="Demo Agency Updated" id="104981" type="agency" version="1">
    <prop name="organization_id" value="100048" />
    <prop name="name" value="Demo Agency Updated" />
    <prop name="created_on" value="2014-11-20T20:38:44" />
    <prop name="updated_on" value="2014-11-20T21:04:35" />
    <prop name="status" value="0" />
    <prop name="allow_x_adv_pixels" value="0" />
    <prop name="allow_x_adv_optimization" value="0" />
    <prop name="dmp_enabled" value="inherits" />
  </entity>
  <status code="ok" />
</result>

After validating the updated parameters, the server responds with the details of the updated entity. Note that the version parameter is updated, to prevent multiple clients from updating the same version of an entity at once.

Do not include the entity’s ID in the POST body, as it is already implicit from the URL and cannot be modified.

Update Timeframes

Updates to entities have to be propogated to the Bidders in order for them to affect how MediaMath bids for opportunities. Regular updates have an average latency of 1.5 hours. Updates of fields of entities below are fast tracked and update within 5 minutes.

Campaigns:

id
end_date
start_date
status
total_budget

Strategies:

budget
end_date
goal_value
id
max_bid
min_bid
pacing_amount
pacing_interval
pacing_type
start_date
status

USD Budget Flights:

campaign_id
end_date
id
start_date
total_budget
total_budget_usd

Retrieving Entity Changelogs

Certain entities allow you to retrieve a list of changes made to the entity over time. The endpoint only shows 90 days worth of history. To retrieve changelog data, make a request of the following form:

GET https://api.mediamath.com/api/v2.0/[collection]/[id]/history

For example, to retrieve the update history for the agency shown above, you could issue the following request:

GET https://api.mediamath.com/api/v2.0/agencies/104981/history

<?xml version='1.0' ?>
<result>
  <log_entries count="3" start="0">
    <entry action="update" date="2014-11-21T01:35:31" user_id="8135" user_name="rcrosby">
      <field name="name" new_value="Demo Agency" old_value="Demo Agency Updated" />
    </entry>
    <entry action="update" date="2014-11-20T21:04:35" user_id="8135" user_name="rcrosby">
      <field name="name" new_value="Demo Agency Updated" old_value="Demo Agency" />
    </entry>
    <entry action="add" date="2014-11-20T20:38:44" user_id="8135" user_name="rcrosby">
    </entry>
  </log_entries>
  <status code="ok" />
</result>

Your Targeting Options

Targeting is, roughly, the process of limiting the reach of advertisements, either by limiting the set of consumers to whom they will be shown, or by limiting the circumstances under which they will be shown. Mediamath supports multiple types of targeting for strategies, mostly implemented in the Adama service but for some types of targeting, implemented in the related Nemo service.

See the instructions under /nemo/attachment’s GET on how to determine specific values that will help you filter your WURFL, Hyperlocal or IP Targeting needs.

But let’s look at a logical sequence of examining and editing your targeting. The following could be used to fetch all the Hyperlocal Targets who are children of the Hyperlocal parent record (id 1):

GET /target?id=1

{
   "data" : [
      {
         "updated_on" : "2016-06-07 02:06:58.068356+00",
         "created_on" : "2016-06-07 02:06:58.068356+00",
         "path" : null,
         "name" : "Hyperlocal",
         "factual_id" : null,
         "mediamath_organization_id" : null,
         "parent_id" : null,
         "id" : 1
      }
   ],
   "meta" : {
      "count" : 1,
      "total_count" : 1,
      "offset" : 0,
      "status" : "success"
   }
}

You can then create a new target for our Hyperlocal (Factual) design as id=37, then attach that Target 37 to a MediaMath strategy ID:

So now that we know the Hyperlocal parent Target ID (1), we create a new Target for our Hyperlocal (Factual) design:

POST /target { 
  parent_id:                 1,
  name:                      Factual Design 138,
  mediamath_organization_id: 100170,
  factual_id:                1f5b06bd-0cbd-4306-9ec3-37e5dd9cc780,
}

{ ...
  id:                        37,
  path:                      1.37,
  name:                      Factual Design 138,
  mediamath_organization_id: 100170,
  factual_id:                1f5b06bd-0cbd-4306-9ec3-37e5dd9cc780,
  ...
} 

.
.
.

POST /attachment {
  target_id:               37,
  strategy_id:             11010,
  restriction:             INCLUDE,
  operator:                AND
} ,

{ ...
  id:                        42,
  ...
}

You’ve now created Attachment ID 42.

Campaign Management API