Supply Tag API
- 1 Creating a Supply Tag
- 2 Get a Supply Tag
- 2.1 Examples:
- 3 Edit a Supply Tag
- 4 Add Demand to a Supply Tag
- 4.1 SDK
- 5 Duplicate a Supply Tag
- 6 Create a Direct Connect Supply Tag
- 7 Enabling a Supply Tag for Open Market
- 8 Adding Event Pixels to a Supply Tag
- 9 Adding Open Market Bidders to a Supply Tag
- 10 Adding Pods to a Supply Tag
- 11 Object Descriptions
Creating a Supply Tag
SDK
Use tab completion with SDK to auto-complete function names or show field options!
tag = springserve.supply_tags.new({'name': 'TEST API DOCS', 'rate': 0.02, 'js_vpaid_enabled': false)
print tag.ok, tag.id
True, 28852REST API
Method: POST
Endpoint URL: /api/v0/supply_tags
Notes: Note that for flat waterfalls, the tier parameter defaults to 1. Same goes for any demand tag included in demand_tag_priorities that does not specify the tier parameter.
Parameters:
name - (required, type: string) Name of the new supply tag.rate - (required, type: float) CPM rate of the new supply tag.supply_partner_id - (required, type: int) ID of supply partner to be associated with.js_vpaid_enabled - (required, type: boolean) Response type, JS VPAID or VAST Only
Request:
POST /api/v0/supply_tags
Content-Type: application/json
Authorization: "yourAuthToken"
{
"name": "MS TEST API DOCS",
"rate": 0.02,
"js_vpaid_enabled": false
}
Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": 730124,
"account_id": 391,
"name": "TEST API DOCS",
"active": true,
"rate": "0.02",
"js_vpaid_enabled": false,
.......
}Examples
Python Example
import requests
import json
url = "https://console.springserve.com/api/v0/supply_tags/"
payload = json.dumps({
"name": "TEST API DOCS",
"rate": 10.25,
"js_vpaid_enabled": False
})
headers = {
'Authorization': 'yourAuthToken',
'Content-Type': 'application/json',
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
NodeJS Example
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://console.springserve.com/api/v0/supply_tags/',
'headers': {
'Authorization': 'yourAuthToken',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "TEST API DOCS",
"rate": 10.25,
"js_vpaid_enabled": false
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});Get a Supply Tag
SDK
Use tab completion with SDK to auto-complete function names or show field options!
tag = springserve.supply_tags.get(730124)
print tag.id, tag.name
730124, "TEST API DOCS"
REST API
Method: GET
Endpoint URL: /api/v0/supply_tags/<id>
Parameters:
id - (required, type: integer) ID of the supply tag.
Request:
GET /api/v0/supply_tags/730124
Content-Type: application/json
Authorization: "yourAuthToken"
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 730124,
"account_id": 391,
"name": "TEST API DOCS",
"active": true,
"rate": "0.02",
.......
}
Examples:
Python Example
import requests
import json
url = "https://console.springserve.com/api/v0/supply_tags/730124"
payload = ""
headers = {
'Authorization': 'yourAuthToken',
'Content-Type': 'application/json'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
NodeJS Example
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://console.springserve.com/api/v0/supply_tags/730124',
'headers': {
'Authorization': 'yourAuthToken',
'Content-Type': 'application/json'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});Edit a Supply Tag
SDK
tag = springserve.supply_tags.get(28852)
tag.name = "I want to change the name"
changed = tag.save()
changed.ok
TrueNote that when enabling post_imp_detection, you must also set at least one of post_imp_percentage_whiteops, post_imp_percentage_moat, post_imp_percentage_ias to >0 before saving your changes.
REST API
Method: PATCH
Endpoint URL: /api/v0/supply_tags/<id>
Parameters:
id - (required, type: integer) ID of the supply tag.
Request:
PATCH /api/v0/supply_tags/730124
Content-Type: application/json
Authorization: "yourAuthToken"
{
"name": "I want to change the name"
}Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 730124,
"account_id": 391,
"name": "I want to change the name",
"active": true,
"rate": "0.02",
.......
}
Add Demand to a Supply Tag
SDK
tag = springserve.supply_tags.get(123456)
tag.demand_tag_priorities = [{'demand_tag_id':2345}]
saved_tag = tag.save()
print saved_tag.ok, saved_tag.demand_tag_priorities
True, [{'demand_tag_id':2345}]
REST API
Method: PATCH
Endpoint URL: /api/v0/supply_tags/<id>
Notes - You will need to pass back other demand_tag_priorities objects in order to not delete them
Parameters:
id - (required, type: integer) ID of the supply tag.
Request:
PATCH /api/v0/supply_tags/730124
Content-Type: application/json
Authorization: "yourAuthToken"
{
"demand_tag_priorities": [
{
"demand_tag_id": 1110673
}
]
}Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 730124,
"account_id": 391,
"name": "I want to change the name",
.......
"demand_tag_priorities": [
{
"demand_tag_id": 1110673,
"priority": 1,
"tier": 1,
"locked": false,
"ratio": null,
"slot_number": 0,
"slot_order": "n/a"
}
}
.......
}Duplicate a Supply Tag
Please note that this works for both Managed and Direct Connect tags.
SDK
In [1]: tag = springserve.supply_tags.get(28852)
In [2]: dupe = tag.duplicate()
In [4]: dupe.ok
Out [4]: True
In [5]: print dupe.id
65034REST API
GET /api/v0/supply_tags/<id>/duplicate
Headers
Content-Type application/json
Authorization "yourAuthToken"Response
Status code 200
{
...
'id': 65034,
'name': 'I want to change the name',
'rate': '0.02',
...
}Create a Direct Connect Supply Tag
SDK
In [1]: import springserve
In [2]: tag = springserve.connected_supply.new({'direct_connect':'true', 'supply_partner_id':10000, 'name': 'TEST API DC', 'rate': 0.02, 'demand_tag_priorities':[{'demand_tag_id':30420, 'priority':1}]})
In [3]: print tag.ok, tag.id
True, 28852Note that for flat waterfalls, the tier parameter defaults to 1. Same goes for any demand tag included in demand_tag_priorities that does not specify the tier parameter.
REST API
POST /api/v0/connected_supply
Headers
Content-Type application/json
Authorization "yourAuthToken"Body (example)
{ |
Required parameters: name, demand_tag_priorities, supply_partner_id, direct_connect, rate
Response
Status code 200
{
'account_id': 1,
'active': True,
'allowed_player_sizes': [
's',
'm',
'l',
'u'
],
'country_codes': [],
'country_targeting': 'All',
'demand_tag_priorities': [
{
'demand_tag_id': 30424,
'locked': False,
'priority': 1,
'tier': 1
}
],
'detected_domain_targeting': False,
'detected_player_size_targeting': False,
'direct_connect': False,
'metro_area_codes': [],
'metro_area_targeting': 'All',
'domain_list_ids': [],
'domain_targeting': 'All',
'environment': 'desktop',
'flash_vpaid_enabled': False,
'id': 65034,
'js_vpaid_enabled': True,
'js_vpaid_flash_enabled': True,
'key_ids': [],
'name': 'I want to change the name',
'optimization': {
'active': True,
'learn_pct': '1.0',
'settings': {
'lookback_minutes': '60',
'metric': 'fill_speed',
'minimum_requests': '250'
},
'version': ''
},
'payment_terms': 'CPM',
'player_size_targeting': 'All',
'post_imp_detection_enabled': True,
'pre_bid_blocking_enabled': True,
'pre_bid_blocking_components': ['whiteops', 'springserve'],
'rate': '0',
'segment_user_as': [],
'supply_group_id': None,
'supply_partner_id': None,
'supply_type': None,
'tag_health': None,
'targeting_supply_ids': [],
'targeting_supply_white_list': '',
'timeout': None,
'tracking_player_cost': False,
'updated_at': '2017-07-07T15:17:28.315Z',
'user_agent_devices': [],
'user_agent_operating_systems': []
}Enabling a Supply Tag for Open Market
SDK
In [1]: import springserve
In [2]: tag = springserve.supply_tags.get(123456)
In [3]: tag.open_market_enabled = True
In [4]: saved_tag = tag.save()
In [5]: print saved_tag.ok, saved_tag.id
True, 123456REST API
PATCH /api/v0/supply_tags/<id>
Headers
Content-Type application/json
Authorization "yourAuthToken"Body (example)
|
Response
Status code 200
{
"id": 123456,
"account_id": 1,
"name": "Supply Tag with Open Market",
"active": true,
"rate": "1.0",
"domain_targeting": "All",
"app_name_targeting": "All",
"app_bundle_targeting": "All",
"ip_targeting": "All",
"country_targeting": "All",
"player_size_targeting": "All",
"metro_area_targeting": "All",
"allowed_player_sizes": [
"xs",
"s",
"m",
"l",
"xl",
"u"
],
"country_codes": [],
"domain_list_ids": [],
"app_name_list_ids": [],
"app_bundle_list_ids": [],
"ip_list_ids": [],
"metro_area_codes": [],
"user_agent_devices": [],
"user_agent_operating_systems": [],
"user_agent_browsers": [],
"updated_at": "2019-09-27T21:02:53.466Z",
"created_at": "2019-05-14T20:25:01.156Z",
"direct_connect": false,
"supply_label_ids": [],
"supply_partner_id": 244,
"supply_type": null,
"payment_terms": "CPM",
"tracking_player_cost": false,
"optimization": {
"active": true,
"version": null,
"learn_pct": "1.0",
"mode": "white_box",
"settings": {
"metric": "opportunity_fill",
"lookback_minutes": "60"
}
},
"timeout": null,
"environment": "desktop",
"js_vpaid_enabled": false,
"detected_domain_targeting": false,
"detected_player_size_targeting": false,
"targeting_supply_ids": [],
"targeting_supply_white_list": "",
"post_imp_detection_enabled": false,
"post_imp_percentage_whiteops": 0,
"post_imp_percentage_ias": 0,
"post_imp_percentage_moat": 0,
"post_imp_percentage_protected": 0,
"post_imp_percentage_forensiq": 0,
"pre_bid_blocking_enabled": false,
"pre_bid_blocking_components": [],
"tag_health": null,
"key_ids": [],
"vpaid_none_allow_vpaid_demand": true,
"rpm_floor": "1.2",
"rpm_floor_openrtb": true,
"openrtb_floor": "1.2",
"tier_0_broadfall": true,
"tier_1_broadfall": true,
"tier_2_broadfall": true,
"tier_3_broadfall": true,
"tier_4_broadfall": true,
"tier_5_broadfall": true,
"vast_version": "3.0",
"min_aspect_ratio": null,
"max_aspect_ratio": null,
"bulk_add_enabled": true,
"format": "video",
"allow_traffic_exclusions": true,
"open_market_enabled": true,
"auto_add_external_bidders": false,
"evaluation_learn_pct": "50.0",
"tag_pixels": [],
"demand_tag_priorities": [
{
"demand_tag_id": 21892,
"priority": 1,
"tier": 0,
"locked": false
}
],
"give_up_percents": [],
"budgets": [],
"frequency_caps": [],
"open_market_external_bidders": [
{
"other_account_id": 20,
"openrtb_floor": null
},
{
"other_account_id": 23,
"openrtb_floor": null
},
{
"other_account_id": 27,
"openrtb_floor": null
},
{
"other_account_id": 14,
"openrtb_floor": null
},
{
"other_account_id": 55,
"openrtb_floor": null
},
{
"other_account_id": 56,
"openrtb_floor": null
},
{
"other_account_id": 28,
"openrtb_floor": null
},
{
"other_account_id": 15,
"openrtb_floor": null
},
{
"other_account_id": 3,
"openrtb_floor": null
},
{
"other_account_id": 58,
"openrtb_floor": null
},
{
"other_account_id": 46,
"openrtb_floor": null
},
{
"other_account_id": 4,
"openrtb_floor": null
},
{
"other_account_id": 62,
"openrtb_floor": null
},
{
"other_account_id": 17,
"openrtb_floor": null
},
{
"other_account_id": 65,
"openrtb_floor": null
},
{
"other_account_id": 64,
"openrtb_floor": null
},
{
"other_account_id": 80,
"openrtb_floor": null
},
{
"other_account_id": 79,
"openrtb_floor": null
},
{
"other_account_id": 81,
"openrtb_floor": null
}
]
}NOTE: Enabling Open Market in the API without specifying bidders will add all eligible bidders.
Adding Event Pixels to a Supply Tag
SDK
In [1]: import springserve
In [2]: tag = springserve.supply_tags.get(123456)
In [3]: tag.tag_pixels = [{'pixel_type':'AdImpression', 'pixel_url':'https://springserve.com/',
'pixel_format':'image'}]
In [4]: saved_tag = tag.save()
In [5]: print saved_tag.ok, saved_tag.tag_pixels
True, [{'id': 244, 'pixel_type': 'AdImpression', 'pixel_url': 'https://springserve.com/',
'pixel_format': 'image', 'created_at': '2021-03-19T14:30:06.675Z'}]The fields for 'pixel_type' are the following:
Impression: 'AdImpression'
Start: 'AdVideoStart'
1st Quartile: 'AdVideoFirstQuartile'
Midpoint: 'AdVideoMidpoint'
3rd Quartile: 'AdVideoThirdQuartile'
Complete: 'AdVideoComplete'
Click: 'AdClickThru'
Fields for 'pixel_format':
Image URL: 'image'
Javascript URL: 'js'
REST API
PATCH /api/v0/supply_tags/<id>
Headers
Content-Type application/json
Authorization "yourAuthToken"Body (example)
|
Response
Status code 200
{
"id": 123456,
"rate": "1.0",
...
"tag_pixels": [
{
"id":311732,"pixel_type":"AdImpression",
"pixel_url":"https://springserve.com/",
"pixel_format":"image","created_at":"2021-03-24T15:40:03.935Z"
}
],
...
}Adding Open Market Bidders to a Supply Tag
SDK
In [1]: import springserve
In [2]: tag = springserve.supply_tags.get(123456)
In [3]: tag.open_market_external_bidders = [{'other_account_id':58},{'openrtb_floor': 2.2, 'other_account_id':4},{'other_account_id':28}]
In [4]: saved_tag = tag.save()
In [5]: print saved_tag.ok, saved_tag.id
True, 123456The 'other_account_id' represents the bidder account id to add to the open market for this supply tag. There's an optional 'openrtb_floor' field that allows you to set a specific floor for a bidder (otherwise, the default Open Market floor is used).
REST API
PATCH /api/v0/supply_tags/<id>
Headers
Content-Type application/json
Authorization "yourAuthToken"Body (example)
|
Response
Status code 200
{
"id": 123456,
"account_id": 1,
"name": "Supply Tag with Open Market",
"active": true,
"rate": "1.0",
"domain_targeting": "All",
"app_name_targeting": "All",
"app_bundle_targeting": "All",
"ip_targeting": "All",
"country_targeting": "All",
"player_size_targeting": "All",
"metro_area_targeting": "All",
"allowed_player_sizes": [
"xs",
"s",
"m",
"l",
"xl",
"u"
],
"country_codes": [],
"domain_list_ids": [],
"app_name_list_ids": [],
"app_bundle_list_ids": [],
"ip_list_ids": [],
"metro_area_codes": [],
"user_agent_devices": [],
"user_agent_operating_systems": [],
"user_agent_browsers": [],
"updated_at": "2019-09-27T21:02:53.466Z",
"created_at": "2019-05-14T20:25:01.156Z",
"direct_connect": false,
"supply_label_ids": [],
"supply_partner_id": 244,
"supply_type": null,
"payment_terms": "CPM",
"tracking_player_cost": false,
"optimization": {
"active": true,
"version": null,
"learn_pct": "1.0",
"mode": "white_box",
"settings": {
"metric": "opportunity_fill",
"lookback_minutes": "60"
}
},
"timeout": null,
"environment": "desktop",
"js_vpaid_enabled": false,
"detected_domain_targeting": false,
"detected_player_size_targeting": false,
"targeting_supply_ids": [],
"targeting_supply_white_list": "",
"post_imp_detection_enabled": false,
"post_imp_percentage_whiteops": 0,
"post_imp_percentage_ias": 0,
"post_imp_percentage_moat": 0,
"post_imp_percentage_protected": 0,
"post_imp_percentage_forensiq": 0,
"pre_bid_blocking_enabled": false,
"pre_bid_blocking_components": [],
"tag_health": null,
"key_ids": [],
"vpaid_none_allow_vpaid_demand": true,
"rpm_floor": "1.2",
"rpm_floor_openrtb": true,
"openrtb_floor": "1.2",
"tier_0_broadfall": true,
"tier_1_broadfall": true,
"tier_2_broadfall": true,
"tier_3_broadfall": true,
"tier_4_broadfall": true,
"tier_5_broadfall": true,
"vast_version": "3.0",
"min_aspect_ratio": null,
"max_aspect_ratio": null,
"bulk_add_enabled": true,
"format": "video",
"allow_traffic_exclusions": true,
"open_market_enabled": true,
"auto_add_external_bidders": false,
"evaluation_learn_pct": "50.0",
"tag_pixels": [],
"demand_tag_priorities": [
{
"demand_tag_id": 21892,
"priority": 1,
"tier": 0,
"locked": false
}
],
"give_up_percents": [],
"budgets": [],
"frequency_caps": [],
"open_market_external_bidders": [
{
"other_account_id": 27,
"openrtb_floor": 12.0
},
{
"other_account_id": 4,
"openrtb_floor": null
}
]
}Adding Pods to a Supply Tag
SDK
In [1]: import springserve
In [2]: tag = springserve.supply_tags.get(123456)
In [3]: tag.pod = {'max_duration': 300, 'custom_ad_slot_duration': True,'unfilled_slot_opt_out_enabled': False, 'ad_slots': [{
'position': 3
}, {
'position': 2
}, {
'position': 1
}]
}
In [4]: saved_tag = tag.save()
In [5]: print saved_tag.ok, saved_tag.id
True, 123456 Max_unfilled_slots is initially null, you can set it to an integer between 0 and 2
To EDIT a pod you have to add the pod id to the request
REST API
PUT /api/v0/supply_tags/<id>
Headers
Content-Type application/json
Authorization "yourAuthToken"
Body (example)
{ "pod":{ "max_duration": 200, "custom_ad_slot_duration": true, "unfilled_slot_opt_out_enabled": false, "max_unfilled_slots":0, "ad_slots": [{"position": 3, "min_duration":40, "max_duration":60}, {"position": 2}, {"position": 1}] } } |
Response
Status code 200
{
"id": 123456,
"account_id": 1,
...
"pod": {
"id": 345,
"max_duration": 200,
"custom_ad_slot_duration": true,
"unfilled_slot_opt_out_enabled": false,
"max_unfilled_slots": null,
"ad_slots": [
{
"id": 764,
"position": 1,
"min_duration": null,
"max_duration": null
},
{
"id": 763,
"position": 2,
"min_duration": null,
"max_duration": null
},
{
"id": 762,
"position": 3,
"min_duration": 40,
"max_duration": 60
}]
}
} Object Descriptions
Object Name | Value Type | Object Description | Example | Notes |
|---|---|---|---|---|
id | integer | supply tag ID | 25530 |
|
account_id | integer | account ID | 391 |
|
name | string | supply tag name | "API Example Router" |
|
active | boolean | status of supply tag | true / false |
|
rate | integer | rate | 70 / 10.2 | See "payment_terms" CPM - CPM rate paid for inventory. CPM Rev Share - rate at which you pay revenue share for inventory. % Dynamic - margin added to demand. % |
payment_terms | string | payment terms | "Rev-Share" / "CPM" / "Dynamic" | Dynamic - Pricing will be passed via the {{PRICE_PAID}} macro. Please make sure this macro is implemented in your exported tag. Price must be a CPM value. |
rpm_floor | integer | RPM floor rate | 12.24 |
|
rpm_floor_openrtb | boolean | DC OM floor active | true / false | DC only |
rpm_floor_hb | boolean | apply floor to header bidder demand | true / false |
|
openrtb_floor | integer | DC OM floor rate | 13.24 | DC only |
environment | string | supply device environment type | "desktop" / "mobile_web" / "in_app" / "ctv" |
|
domain_targeting | string | domain targeting type | "All" / "Allowlist" / "Blocklist" | use for environment "desktop" or "mobile_web". use in conjunction with domain_list_ids |
domain_list_ids | array integer | ID of domain lists | [211852, 123456] | created under targeting tab in UI. use in conjunction with domain_targeting |
app_name__targeting | string | app name targeting type | "All" / "Allowlist" / "Blocklist" | use for environment "in_app" or "ctv". use in conjunction with app_name_list_ids |
app_name_list_ids | array | ID of app name lists | [527, 5352] | created under targeting tab in UI. use in conjunction with app_name_targeting |
app_bundle_targeting | string | app bundle targeting active | "All" / "Allowlist" / "Blocklist" | use for environment "in_app" or "ctv". use in conjunction with app_bundle_list_ids |
app_bundle_list_ids | array integer | ID of app bundle lists | [250761, 247375] | created under targeting tab in UI. use in conjunction with app_bundle_targeting |
ip_targeting | string | IP targeting active | "All" / "Allowlist" / "Blocklist" | use in conjunction with ip_list_ids |
ip_list_ids | array integer | ID of IP lists | [164, 907] | created under targeting tab in UI. use in conjunction with ip_targeting |
advertiser_domain_targeting | string | advertiser domain targeting type | "All" / "Allowlist" / "Blocklist" | use in conjunction with advertiser_domain_list_ids |
advertiser_domain_list_ids | array integer | ID of advertiser domain lists | [433, 484] | created under targeting tab in UI. use in conjunction with advertiser_domain_targeting |
blocking_unknown_advertiser_domains | boolean | toggle to block unknown advertiser domains | true / false | Blocks all SSHB and Open Market demand tags that don't return an Advertiser Domain in the VAST response |
ignore_advertiser_domain_targeting | boolean | advertiser domain target override | true / false | pod settings removes all advertiser domain targeting, allowing all to serve. sets duplicate creatives to allowed. |
pod | object | pod settings | { "id": 67830, "max_duration": 300, "custom_ad_slot_duration": false, "unfilled_slot_opt_out_enabled": true, "max_unfilled_slots": 2, "duplicate_creatives": true, "duplicate_adomains": true, "ad_slots": [ { "id": 36713, "position": 3, "min_duration": 10, "max_duration": 30 }, { "id": 36712, "position": 2, "min_duration": 10, "max_duration": 30 }, { "id": 36711, "position": 1, "min_duration": 10, "max_duration": 30 } ] } | default - null "custom_ad_slot_duration" - defines dynamic pod or predefined pod settings true - custom ad slot duration false - dynamic ad slot duration |
waterfall_slot_build | boolean | waterfall build | true / false | build waterfall as slot or tag true - slot false - tag |
allow_duplicate_creatives | boolean | allow duplicate creatives | true / false | pod settings |
allow_duplicate_adomains | boolean | allow duplicate advertiser domains | true / false | pod settings |
ignore_iab_targeting | boolean | IAB category targeting override | true / false | pod settings allows all categories to serve |
creative_brandsafe_override | boolean | allow non brand safe creatives to serve | true / false | brand safe blocks by default - gambling, nicotine replacement, lingerie, weapons/warfare, contraception |
creative_allow_objectionable | boolean | allow restricted audience ads | true / false | restricted blocks by default - violence, sexual content, weightloss, political |
post_imp_detection_enabled | boolean | post impression detection active | true / false | specify the portion of impressions on which to run verification. sampling rates are independant per verification provider. use in conjunction with below post_imp_percentage fields |
post_imp_percentage_whiteops | integer | post impression percentage Whiteops (HUMAN) |