Entity Heirarchy
- Retrieving Entities
- Creating New Entities
- Updating Entities
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 & 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 & 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>