Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents

...

Code Block
languagepy
themeRDark
import requests
import json

url = "https://admin-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)

...

Code Block
languagejs
themeRDark
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://admin-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);
});

...

Code Block
languagepy
themeRDark
import requests
import json

url = "https://admin-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)

...

Code Block
languagejs
themeRDark
var request = require('request');
var options = {
  'method': 'GET',
  'url': 'https://admin-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);
});

...

Code Block
languagepy
themeRDark
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>

...

NOTE: Enabling Open Market in the API without specifying bidders will add all eligible bidders.

Adding Event Pixels to a Supply Tag

SDK

Code Block
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'}]

...

Object NameValue TypeObject DescriptionExampleNotes
idintegersupply tag ID25530
account_idintegeraccount ID391
namestringsupply tag name"API Example Router"
activebooleanstatus of supply tagtrue / false
rateintegerrate70 / 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_termsstringpayment 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
integerRPM floor rate12.24
rpm_floor_openrtb
booleanDC OM floor activetrue / falseDC only
rpm_floor_hb
booleanapply floor to header bidder demandtrue / false
openrtb_floor
integerDC OM floor rate13.24DC only
environmentstringsupply device environment type"desktop" / "mobile_web" / "in_app" / "ctv"
domain_targetingstringdomain targeting type"All" / "Allowlist" / "Blocklist"use for environment "desktop" or "mobile_web". use in conjunction with domain_list_ids
domain_list_idsarray integerID of domain lists [211852, 123456]created under targeting tab in UI. use in conjunction with domain_targeting
app_name__targetingstringapp name targeting type"All" / "Allowlist" / "Blocklist"use for environment "in_app" or "ctv". use in conjunction with app_name_list_ids
app_name_list_idsarrayID of app name lists [527, 5352]created under targeting tab in UI. use in conjunction with app_name_targeting
app_bundle_targetingstringapp bundle targeting active"All" / "Allowlist" / "Blocklist"use for environment "in_app" or "ctv". use in conjunction with app_bundle_list_ids
app_bundle_list_idsarray integerID of app bundle lists [250761, 247375]created under targeting tab in UI. use in conjunction with app_bundle_targeting
ip_targetingstringIP targeting active"All" / "Allowlist" / "Blocklist"use in conjunction with ip_list_ids
ip_list_idsarray integerID of IP lists [164, 907]created under targeting tab in UI. use in conjunction with ip_targeting
advertiser_domain_targetingstringadvertiser domain targeting type"All" / "Allowlist" / "Blocklist"use in conjunction with advertiser_domain_list_ids
advertiser_domain_list_idsarray integerID of advertiser domain lists[433, 484]created under targeting tab in UI. use in conjunction with advertiser_domain_targeting
blocking_unknown_advertiser_domainsbooleantoggle to block unknown advertiser domainstrue / falseBlocks all SSHB and Open Market demand tags that don't return an Advertiser Domain in the VAST response
ignore_advertiser_domain_targeting
booleanadvertiser domain target overridetrue / false

pod settings

removes all advertiser domain targeting, allowing all to serve. sets duplicate creatives to allowed.

podobjectpod 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
booleanwaterfall buildtrue / false

build waterfall as slot or tag

true - slot

false - tag

allow_duplicate_creatives
booleanallow duplicate creativestrue / falsepod settings
allow_duplicate_adomains
booleanallow duplicate advertiser domainstrue / falsepod settings
ignore_iab_targeting
booleanIAB category targeting overridetrue / false

pod settings

allows all categories to serve

creative_brandsafe_override
booleanallow non brand safe creatives to servetrue / falsebrand safe blocks by default - gambling, nicotine replacement, lingerie, weapons/warfare, contraception
creative_allow_objectionable
booleanallow restricted audience adstrue / falserestricted blocks by default - violence, sexual content, weightloss, political
post_imp_detection_enabledbooleanpost impression detection activetrue / falsespecify 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
integerpost impression percentage Whiteops (HUMAN)0 - 100use in conjunction with below post_imp_detection_enabled
post_imp_percentage_ias
integerpost impression percentage IAS0 - 100use in conjunction with below post_imp_detection_enabled
post_imp_percentage_moat
integerpost impression percentage MOAT0 - 100use in conjunction with below post_imp_detection_enabled
post_imp_percentage_protected
integerpost impression percentage Protected0 - 100use in conjunction with below post_imp_detection_enabled
post_imp_percentage_forensiq
integerpost impression percentage ForensIQ0 - 100use in conjunction with below post_imp_detection_enabled
pre_bid_blocking_enabled
booleanpre-bid filtering activetrue / false
pre_bid_blocking_components
array stringpre-bid filtering providers["springserve",  "whiteops", "protected"]specify percentages using post_imp_percentage for providers
key_idsarray integerKVPs included in reporting[2102, 3124]max 15 reporting keys per router
notestringnotes"notes about router"
min_aspect_ratiostringmin aspect ratio as float
"0.563"
9:16 (0.56)
max_aspect_ratio
stringmax aspect ratio as float"1.777"16:9 (1.78)
formatstringad format type"video" / "tile" / "audio"
third_party_overridesboolean

n/a
player_sizesarray integerplayer size targeting
["xs", "s", "m", "l", "xl", "u"]
user_agent_devicesarray stringallowed device targeting
["Computer", "Mobile Web", "Mobile In-app", "Tablet Web", "Tablet In-app", "Games Console", "CTV", "Set-top Box", "Other"]
[] - empty array targets all devices
user_agent_brandsarray stringallowed device brand targeting
["Samsung", "Philips", "Panasonic", "Hisense", "Vizio", "Sanyo", "Magnavox", "Android TV", "LG", "Comcast", "Other Connected TV", "Apple TV", "Roku", "Fire TV", "Chromecast", "Smartcast by Vizio"]
[] - empty array targets all brands
user_agent_operating_systems
array stringallowed OS targeting
["Android", "iOS", "Linux", "Windows", "Mac OS X", "Chrome OS", "Fire OS", "Xbox OS", "VIZIO SmartCast", "Tizen", "Roku OS", "webOS TV", "Other"]
[] - empty array targets all operating systems
user_agent_browsersarray stringallow browser targeting
["Chrome", "Edge", "Firefox", "Safari", "IE", "Chromium", "Chrome Mobile", "WebView", "Android", "Samsung Browser", "Facebook on Android", "Facebook on iOS", "Mobile Safari", "Roku App"]
[] - empty array targets all browsers
segment_targeting_enabled
booleanaudience segment targeting activetrue / falseuse in conjunction with segment_groups
segment_groupsarray objectaudience segment targeting groups and types
[
        {
            "id": 28839,
            "group": "1",
            "white_list": true,
            "segment_group_type": "segments",
            "segment_ids": [
                10869,
                10004
            ],
            "partner_segment_ids": []
        }
]

use multiple groups for OR targeting and same group for AND targeting.

"whitelist": true/false, for allow or block user segments

media_file_mime_type_targeting
booleanmime type targetingtrue / false
media_file_mime_types
array stringallowed mime types
["application/dash+xml", "application/javascript", "application/json", "application/octet-stream", "application/vnd.apple.mpegurl", "application/x-mpegURL", "application/x-shockwave-flash", "video/3gpp", "video/hls", "video/m3u8", "video/mov", "video/mp4", "video/mpeg", "video/ogg", "video/quicktime", "video/webm", "video/wmv", "video/x-flv", "video/x-m4v", "video/x-ms-wmv"]

blocking_unknown_media_file_mime_type
booleanblock unknown mime typestrue / false
media_file_duration_targeting
booleanmedia file targeting activetrue / falseset media_file_min_duration and media_file_max_duration to null for all durations when false. specify min and max durations for true
media_file_min_duration
integermedia file targeting min duration10 / null

unit:seconds

media_file_max_duration
integermedia file targeting max duration30 / nullunit:seconds
blocking_unknown_media_file_duration
booleanblock unknown durations toggletrue / false
media_file_bit_rate_targeting
booleanmedia file bitrate targeting activetrue / falseset media_file_min_bit_rate and media_file_max_bit_rate to null for all bitrates when false. specify min and max bitrates for true
media_file_min_bit_rate
integermedia file bitrate targeting min bitrate1000 / nullunit:kbps
media_file_max_bit_rate
integermedia file bitrate targeting max bitrate5000 / nullunit:kbps
blocking_unknown_media_file_bit_rate
booleanblock unknown bitrates toggletrue / false
targeted_macros_enabled
booleancontent attribute  targeting activetrue / false
targeted_macros
array objectcontent attribute  targeting
[
        {
            "id": 20135,
            "macro_param": "{{CHANNEL_NAME}}",
            "list_type": "white_list",
            "source_type": "values",
            "targeted_values": [
                "12345"
            ],
            "parameter_list_ids": [],
            "param_required": false,
            "created_at": "2023-07-18T11:41:40.835Z"
        }
]

"source_type": "values" / "lists"

for lists use "parameter_list_ids" to specify id's

blocking_unknown_media_containers
booleanblock unknown media containerstrue / false
media_file_media_container_targeting
booleanallowed media containers targeting activetrue / false
media_file_media_containers
array stringallowed media containers
[
        "MPEG-41",
        "MPEG-42"
]

media_file_audio_volume_targeting
booleanmedia file audio volume targeting activetrue / false
media_file_audio_volume_mean
integermedia file audio volume targeting mean volume-17unit: dBs
blocking_unknown_media_file_audio_volume
booleanblock unknown media file audio volumetrue / false
blocking_vast_containing_companion_ads
booleanblock vast containing companion adstrue / false
removing_companion_ads_from_vast
booleanremove companion ads from vast containing companion adstrue / falseblocking_vast_containing_companion_ads supersedes removing_companion_ads_from_vast
country_sourcestringcountry targeting source"list" / "values"use in conjunction with either country_list_ids if value is "lists" or country_codes if value is "values"
country_list_ids
array integerID of country lists [184]use in conjunction with country_source with value "lists".
country_white_list
booleancountry targeting include / excludetrue / false

true - include

false - exclude

country_codes
array stringcountry code["UK", "US", "IT"]ISO 3166 Alpha-2 codes
dma_sourcestringDMA targeting source"list" / "values"use in conjunction with either country_list_ids if value is "lists" or country_codes if value is "values"
dma_list_ids
array integerID of DMA lists[199]use in conjunction with country_source with value "lists".
dma_white_list
booleanDMA targeting include / excludetrue / false

true - include

false - exclude

dma_codes
array integerDMA ID[525]
postal_code_targeting
stringpostal code targeting type"All" / "Include" / "Exclude"
postal_codes
array stringpostal code values"10001", "GB:SW1A", "FR:75001", "AR:B1228"
postal_code_source
stringpostal code source"values" / "lists"use "values" for "postal_codes" or "lists" with "postal_code_list_ids"
postal_code_list_ids
array integerpostal code list[1235]
creative_language_allow_list
booleancreative language targeting type" " / true / false

" " - all

true - allowlist

false - blocklist

creative_language_codes
array stringcreative language targeting list
["en-GB", "en-US", "fr-FR"]

creative_language_block_unknown
booleanblock unknown creative languagetrue / false
supply_partner_idintegerID of supply partner assigned66463
supply_label_ids
array integersupply label ID's
[1051]
Found on settings tab → More Info → Labels:
supply_type
stringsupply type"null" / "Outstream" 

"null" - instream

"outstream" - outstream

tracking_player_cost
booleantrack player costs based on player loads and not impressionstrue / falsesee "supply_type" for outstream specific setting
direct_connectbooleandirect connect statustrue / falsesee "supply_class" object
supply_class
integersupply class1 / 2 / 3

1 - tag

2 - direct connect

3 - bidlink


for 2 see "direct_connect" object

targeted_iab_category_white_list
booleanIAB tier 1 targeting activetrue (allowlist) / false (blocklist) / null (all categories)
targeted_iab_categories
array stringIAB tier 1 category name["Automotive"]IAB content taxonomy download
targeted_iab_tier2_categories_white_list
booleanIAB tier 2 targeting activetrue (allowlist) / false (blocklist) / null (all categories)
targeted_iab_tier2_category
array stringIAB tier 2 category name["Auto Body Styles", "Automotive"]IAB content taxonomy download
dnt_valuesarray stringDNT (do not track) targeting["true", "false", "empty"]
dnt_param_required
booleanDNT (do not track) parameter requiredtrue / false
lmt_valuesarray stringLMT (limit tracking) targeting["true", "false", "empty"]
lmt_param_required
booleanLMT (limit tracking) parameter required["true", "false", "empty"]
us_privacy_supply_white_list
booleanUS privacy targeting activetrue / false
us_privacy_param_required
booleanUS privacy parameter requiredtrue / false
us_privacy_values
array stringUS privacy values["1yyy"]
gdpr_supply_param_requiredbooleansupply from GDPR country flag requiredtrue / false
gdpr_supply_valuesarray stringsupply from GDPR country flag targeting values["true", "false", "empty"]
gdpr_consent_param_required
booleanGDPR consent string parameter requiredtrue / false
gdpr_consent_string_values
array stringGDPR consent string targeting["valid", "invalid", "empty"]

valid - valid consent string

invalid - invalid consent string

coppa_valuesarray stringallowed COPPA values["true", "false", "empty"]
coppa_param_requiredbooleanCOPPA parameter requiredtrue / false
audited_creative_statuses
array stringallowed audited creative statuses["pending", "approved", "rejected"]
optimization
objectoptimisation 
{
        "active": true,
        "version": "",
        "learn_pct": "1.0",
        "mode": "black_box",
        "settings": {
            "metric": "rpm",
            "lookback_minutes": "60"
        }
}
Recommended optimisation methods are RPM for singles ad requests and revenue per second for pods. 
timeoutintegertimeout of supply tagnull / 3000

unit: ms

null for default

set this lower than player or supply partner timeout

js_vpaid_enabled
booleanresponse type supportedtrue / false
vpaid_none_allow_vpaid_demand
booleanallow vpaid demandtrue / falseif js_vpaid_enabled is true





vast_versionstringmax VAST version supported"3.0" / "2.0"
obfuscate_ip_address_enabled
booleanobfuscate IPtrue / falsesee obf_ip_flags
obf_ip_flags
array stringobfuscate IP on opt out["coppa", "gdpr", "dnt"]
budget_timezone
stringtimezone of budget"America/New_York" / "Europe/London"tz database time zones
budgets




day_partingarray booleanday parting schedule
truncated example for Sunday hours 00 to 07 day parting.
[true, true, true, true, true, true, true, true, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false], ...........

when active day parting is broken into 7 arrays of 24 fields of true / false to indicate the day parting window. week starts Sunday

true - active

false - inactive

day_parting_users_timezone is not in API

...