Creating a Supply Tag
SDK
Use tab completion with SDK to auto-complete function names or show field options!
In [1]: import springserve In [2]: tag = springserve.supply_tags.new({'name': 'TEST API DOCS', 'rate': 0.02, 'demand_tag_priorities':[{'demand_tag_id':30424, 'priority':1}]}) In [3]: print tag.ok, tag.id True, 28852
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.
REST API
POST /api/v0/supply_tags
Headers
Content-Type application/json Authorization "yourAuthToken"
Body (example)
{ "name": "TEST API DOCS", "rate": 0.02 } |
Required parameters: name, 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, 'dma_codes': [], 'dma_targeting': 'All', 'domain_list_ids': [], 'domain_targeting': 'All', 'environment': 'desktop', 'flash_vpaid_enabled': False, 'id': 28852, 'js_vpaid_enabled': True, 'js_vpaid_flash_enabled': True, 'key_ids': [], 'name': 'TEST API DOCS', '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.02', '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': [] }
Get a Supply Tag
SDK
In [1]: tag = springserve.supply_tags.get(28852) In [2]: print tag.name "TEST API DOCS"
REST API
GET /api/v0/supply_tags/<id>
Headers
Content-Type application/json Authorization "yourAuthToken"
Response
Status code 200
{ ... 'name': 'TEST API DOCS', 'rate': '0.02', ... }
Edit a Supply Tag
SDK
In [1]: tag = springserve.supply_tags.get(28852) In [2]: tag.name = "I want to change the name" In [3]: changed = tag.save() In [4]: changed.ok Out [4]: True In [5]: print changed.name "I want to change the name"
Note 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
PUT /api/v0/supply_tags/<id>
Headers
Content-Type application/json Authorization "yourAuthToken"
Body (example)
{ "name" : "I want to change the name" } |
Response
Status code 200
{ ... 'name': 'I want to change the name', 'rate': '0.02', ... }
Adding Demand to a Supply Tag
SDK
In [1]: import springserve In [2]: tag = springserve.supply_tags.get(123456) In [3]: tag.demand_tag_priorities = [{'demand_tag_id':2345}] In [4]: saved_tag = tag.save() In [5]: print saved_tag.ok, saved_tag.demand_tag_priorities True, [{'demand_tag_id':2345}]
REST API
PUT /api/v0/supply_tags/<id>
Headers
Content-Type application/json
Authorization "yourAuthToken"
Body (example)
{ "demand_tag_priorities": [{"demand_tag_id": 2345}] } |
Response
Status code 200
{ "id": 123456, "account_id": 1, ... "demand_tag_priorities": { "demand_tag_id": 2345, "priority": 1, "tier": 1, "locked": false, "ratio": null, "slot_number": null, "slot_order": null } ... }
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 65034
REST 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, 28852
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.
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, 'dma_codes': [], 'dma_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, 123456
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", "dma_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": [], "dma_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, 123456
The '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", "dma_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": [], "dma_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 }] } }