Campaign Management API
- Version: 2.0
- Host: api.mediamath.com/api/v2.0
- Protocols:
https - Accepts:
application/x-www-form-urlencoded - Responds With:
application/vnd.mediamath.v1+json,application/json,application/xml
- Contact Us by Email
- Contact URL: https://apidocs.mediamath.com
- Download Spec: adama.oas2.json
Entity Hierarchy
- 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
{
{
"data": [
{
"id": 100048,
"entity_type": "organization",
"name": "ACME Org"
},
...
],
"meta": {
"status": "success",
"count": 100,
"total_count": 2276,
"offset": 0
}
}
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 with ID 515578:
GET https://api.mediamath.com/api/v2.0/strategies/515578
{
"data": {
...
"campaign_id": 166047,
"name": "Sassytimes",
"entity_type": "strategy",
...
"id": 515578,
...
},
"meta": {
"etag": "3a355adfc9d1bb6c2253b8e5f721a2416ec6ff06",
"called_on": "2021-02-05T14:14:56+0000",
"status": "ok"
},
"uuid": "85D71180-67BC-11EB-91C5-2C489219D3DC"
}
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
{
"meta": {
"status": "ok",
"called_on": "2021-02-05T14:17:36+0000",
"etag": "f3d2cb2c9e0f3d42a54e7f09872b060f641990a2"
},
"uuid": "E3F11AF4-67BC-11EB-AEE7-EE4F9219D3DC",
"data": {
"start_date": "2014-10-08T10:08:41+0000",
...
"name": "Sassytimes",
"entity_type": "strategy",
...
"campaign": {
"conversion_type": "variable",
"created_on": "2014-10-06T21:21:59+0000",
"suspicious_traffic_filter_level": 25,
"id": 166047,
"political": false,
...
"id": 515578,
...
}
}
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
{
"meta": {
"called_on": "2021-02-05T14:23:04+0000",
"status": "ok",
"etag": "11a2a494327b980b75c9f50df577eef19938984a"
},
"data": {
"agency": {
...
"name": "ag_release_2.77",
"organization_id": 100048,
"allow_x_adv_pixels": true,
"id": 103078,
"entity_type": "agency",
...
},
"ad_server_id": 9,
"agency_id": 103078,
"entity_type": "advertiser",
...
"vertical": {
"entity_type": "vertical",
"id": 13,
...
"name": "Food & Beverages"
},
...
"id": 125819,
"frequency_type": "no-limit",
"vertical_id": 13,
...
},
"uuid": "A737F262-67BD-11EB-8BBA-3C100F7B78B9"
}
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
{
"data": {
...
"campaign": {
...
"id": 166047,
...
"advertiser_id": 110036,
"advertiser": {
...
"id": 110036,
"name": "Otniel Test Advertiser",
...
"entity_type": "advertiser",
...
},
...
},
...
"campaign_id": 166047,
"id": 515578,
"name": "Sassytimes",
"created_on": "2014-10-07T14:10:39+0000",
"audience_segment_include_op": "OR",
"description": "Omnia_Test_Nov6_3 test",
...
"entity_type": "strategy",
"source_only": false
},
"meta": {
"etag": "bed511c2c5ebadc42e79ae86ec49fbf14ca61da3",
"called_on": "2021-02-05T14:25:02+0000",
"status": "ok"
},
"uuid": "ED7CA34E-67BD-11EB-85C1-D4BBA84A17C5"
}
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
{
"meta": {
"called_on": "2021-02-05T15:20:28+0000",
"offset": "10",
"status": "ok",
"next_page": "https://api.mediamath.com/api/v2.0/strategies?page_limit=5&page_offset=15",
"count": 5,
"etag": "5e9249330578f13c3d0e283aee7afb49eebad454",
"total_count": 7334213
},
"uuid": "AD8A22AE-67C5-11EB-BF37-A9FB9119D3DC",
"data": [
{
"entity_type": "strategy",
"id": 7441293,
"name": "SP317548_Amplify_vehicle.league.small_suv"
},
{
"entity_type": "strategy",
"id": 7441292,
"name": "SP317548_Amplify_vehicle.league.minivan"
},
{
"id": 7441291,
"name": "SP317548_Focus and Reconnect",
"entity_type": "strategy"
},
{
"name": "REM_Remarketing_MM_Catchall 6 48-168h_Web_Banner_Desktop and Mobile_NFL_ #2",
"id": 7441290,
"entity_type": "strategy"
},
{
"name": "MMP_DEU_Mobile.de_ROS - Exchanges",
"id": 7441289,
"entity_type": "strategy"
}
]
}
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
{
"meta": {
"called_on": "2021-02-05T15:21:30+0000",
"etag": "07318a61e6a0ccb8c659d9e78882a3c65ca89de9",
"next_page": "https://api.mediamath.com/api/v2.0/strategies?full=strategy%2Ccampaign&page_limit=2&page_offset=2&with=campaign%2Cadvertiser%2Cagency%2Corganization",
"total_count": 7334213,
"status": "ok",
"count": 2,
"offset": 0
},
"data": [
{
"site_restriction_transparent_urls": false,
"version": 0,
"campaign": {
"margin_pct": 173,
"frequency_type": "even",
...
"advertiser": {
"id": 238316,
"agency": {
"id": 117098,
"organization": {
"id": 101080,
"name": "Headway South America",
"entity_type": "organization",
"rel": "organization"
},
"name": "HWD Costa Rica",
"entity_type": "agency",
"rel": "agency"
},
"entity_type": "advertiser",
"rel": "advertiser",
"name": "CS - London CR - Zukra - USD"
},
...
"id": 877291,
...
},
...
],
...
"id": 7441314,
...
"name": "ROC",
...
"campaign_id": 877291,
...
},
{
...
"campaign_id": 877294,
...
"id": 7441313,
"entity_type": "strategy",
"campaign": {
...
"id": 877294,
...
"advertiser": {
...
"entity_type": "advertiser",
"rel": "advertiser",
"agency": {
"entity_type": "agency",
...
"id": 117992,
"organization": {
...
"entity_type": "organization",
"id": 101684
}
},
"id": 208369
},
...
},
...
}
],
"uuid": "D28F20E0-67C5-11EB-BB33-85DC57FE940B"
}
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=*
{
"meta": {
"count": 2,
"status": "ok",
...
},
"uuid": "DB451B48-67C7-11EB-918A-80A6C7FF51CA",
"data": [
{
...
"entity_type": "strategy",
"campaign_id": 877300,
"id": 7441391,
...
},
{
...
"id": 7441390,
"campaign_id": 877300,
"entity_type": "strategy",
...
}
]
}
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
{
"meta": {
"offset": 0,
"count": 5,
"status": "ok",
"etag": "00cc1e051fd288a932123c6c24e3ad03074105d8",
"next_page": "https://api.mediamath.com/api/v2.0/strategies?page_limit=5&page_offset=5&sort_by=name",
"total_count": 7334478,
"called_on": "2021-02-05T15:45:30+0000"
},
"uuid": "2CB24AEA-67C9-11EB-8877-B9DC57FE940B",
"data": [
{
"name": "마",
"entity_type": "strategy",
"id": 554604
},
{
"entity_type": "strategy",
"name": "검수",
"id": 3887226
},
{
"id": 2376832,
"entity_type": "strategy",
"name": "배너"
},
{
"entity_type": "strategy",
"name": "배너",
"id": 2340922
},
{
"entity_type": "strategy",
"name": "여성",
"id": 2837757
}
]
}```
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:**
``` request
GET https://api.mediamath.com/api/v2.0/campaigns?q=name%3D%3DTEST1
{
"uuid": "C8F5B59A-67C9-11EB-B25B-5F25A94A17C5",
"data": [
{
"name": "TEST1",
"id": 342430,
"entity_type": "campaign"
},
{
"entity_type": "campaign",
"name": "TEST1",
"id": 335656
},
{
"name": "TEST1",
"id": 294967,
"entity_type": "campaign"
},
{
"id": 124377,
"name": "TEST1",
"entity_type": "campaign"
}
],
"meta": {
"etag": "066a6c9f4d87d6bf65bbc78ffecb5089b2daf56d",
"total_count": 4,
"offset": 0,
"count": 4,
"called_on": "2021-02-05T15:49:52+0000",
"status": "ok"
}
}
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%3DTEST1%26total_budget%3E%3D10000
{
"data": [
{
"id": 335656,
"name": "TEST1",
"entity_type": "campaign"
}
],
"uuid": "14F97274-67CA-11EB-8168-B9B8A9EA18AB",
"meta": {
"etag": "ad3b9a40d31b1042ba83fcdd1c5c36479190ed29",
"offset": 0,
"total_count": 1,
"called_on": "2021-02-05T15:51:59+0000",
"count": 1,
"status": "ok"
}
}
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)
{
"meta": {
"count": 100,
...
"status": "ok"
},
"data": [
{
"entity_type": "strategy",
"id": 123,
"name": ...
},
{
"entity_type": "strategy",
"id": 234,
"name": ...
},
{
"name": ...
"id": 345,
"entity_type": "strategy"
},
...
],
"uuid": "51AD367C-67CC-11EB-81E2-741D9219D3DC"
}```
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.
``` request
GET https://api.mediamath.com/api/v2.0/users?q=<aneva>
{
"uuid": "720EB998-67D3-11EB-9BE5-BEDD0E7B78B9",
"data": [
{
"name": "...daneva@...org",
"entity_type": "user",
"id": ...
},
{
"id": ...,
"entity_type": "user",
"name": "...taneva@...com"
}
],
"meta": {
"etag": "1cce6bca334e5aabebe150199b0a437fcfc042fc",
"total_count": 2,
"offset": 0,
"count": 2,
"called_on": "2021-02-05T16:59:01+0000",
"status": "ok"
}
}
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=123
{
"meta": {
"etag": "e53d48b523b2b8223219759cf8708637977d2d7c",
"total_count": 13,
"offset": 0,
"count": 13,
"called_on": "2021-02-05T17:01:50+0000",
"status": "ok"
},
"data": [
{
"entity_type": "campaign",
"id": ...,
"name": ...
},
...
],
"uuid": "D6791FF4-67D3-11EB-A486-6F51A94A17C5"
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
{
"uuid": "26E5D194-67D4-11EB-9DC9-759757FE940B",
"data": [
{
"id": ...,
"name": ...,
"entity_type": "campaign"
},
{
"entity_type": "campaign",
"name": ...,
"id": ...
}
],
"meta": {
"status": "ok",
"count": 2,
"offset": 0,
"total_count": 2,
"etag": "b7a9136f934225b6189c4714403870d14a1c009a",
"called_on": "2021-02-05T17:04:04+0000"
}
}```
#### 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:
``` request
GET https://api.mediamath.com/api/v2.0/campaigns/limit/vendor_contracts.vendor=515
{
"uuid": "53563A2A-67D4-11EB-82DF-0026A94A17C5",
"data": [
{
"name": ...,
"id": ...,
"entity_type": "campaign"
},
...
],
"meta": {
"count": 100,
"offset": 0,
"status": "ok",
"etag": "ae8b359411c4a8b8f444e178fd6585f3af13e0ea",
"next_page": "https://api.mediamath.com/api/v2.0/campaigns/limit/vendor_contracts.vendor=515?page_offset=100",
"called_on": "2021-02-05T17:05:19+0000",
"total_count": 1580
}
}
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
{
"data": {
"dmp_enabled": "inherits",
"status": false,
"eligible_for_data_sharing": true,
"created_on": "2014-11-20T20:38:44+0000",
"allow_x_adv_optimization": false,
"entity_type": "agency",
"updated_on": "2017-03-17T18:01:42+0000",
"version": 13,
"allow_x_adv_pixels": false,
"id": 104981,
"name": "Demo Agency",
"ads_txt_verified": "ANY",
"organization_id": 100048
},
"meta": {
"called_on": "2021-02-05T17:12:50+0000",
"status": "ok",
"etag": "0538ae0f47fe7665bc2bea7208eaf31e7958a7aa"
},
"uuid": "6070E9FC-67D5-11EB-BBCC-9859A9EA18AB"
}
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
{
"data": {
"dmp_enabled": "inherits",
"status": false,
"eligible_for_data_sharing": true,
"created_on": "2014-11-20T20:38:44+0000",
"allow_x_adv_optimization": false,
"entity_type": "agency",
"updated_on": "2017-03-17T18:01:42+0000",
"version": 13,
"allow_x_adv_pixels": false,
"id": 104981,
"name": "Demo Agency",
"ads_txt_verified": "ANY",
"organization_id": 100048
},
"meta": {
"called_on": "2021-02-05T17:12:50+0000",
"status": "ok",
"etag": "0538ae0f47fe7665bc2bea7208eaf31e7958a7aa"
},
"uuid": "6070E9FC-67D5-11EB-BBCC-9859A9EA18AB"
}
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
{
"data": {
"dmp_enabled": "inherits",
"status": false,
"eligible_for_data_sharing": true,
"created_on": "2014-11-20T20:38:44+0000",
"allow_x_adv_optimization": false,
"entity_type": "agency",
"updated_on": "2021-02-13T11:21:34+0000",
"version": 14,
"allow_x_adv_pixels": false,
"id": 104981,
"name": "Demo Agency",
"ads_txt_verified": "ANY",
"organization_id": 100048
},
"meta": {
"called_on": "2021-02-05T17:12:50+0000",
"status": "ok",
"etag": "0538ae0f47fe7665bc2bea7208eaf31e7958a7aa"
},
"uuid": "6070E9FC-67D5-11EB-BBCC-9859A9EA18AB"
}
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/.../history
{
"meta": {
"count": 1,
"start": 0,
"status": "ok"
},
"with": {
"count": "0",
"log_entries": []
},
"data": {
"log_entries": [
{
"field": [],
"date": "2021-02-05T14:04:05",
"action": "add",
"user_id": ...,
"user_name": ...
}
]
}
}
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.