Supply Tag API

Supply Tag API

 


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, 28852

REST 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 True

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

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 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)

{
   "name": "TEST API DC",
   "direct_connect":true,
   "supply_partner_id":10000,
   "rate": 0,
   "demand_tag_priorities":[{"demand_tag_id":30424, "priority":1}]
}


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, 123456

REST API

PATCH /api/v0/supply_tags/<id>

Headers

Content-Type application/json Authorization "yourAuthToken"

Body (example)

{
    "open_market_enabled": "True"
}

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)

{
    "tag_pixels": [{pixel_type":"AdImpression", "pixel_url":"https://springserve.com/", "pixel_format":"image"}]

}

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)

{
    "open_market_external_bidders": [{"other_account_id": 4}, {"other_account_id": 27, "openrtb_floor" : 12.0}]

}

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

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)