View Source

Creating a Demand Tag

SDK

Use tab completion with SDK to auto-complete function names or show field options!

In [1]: import springserve as ss

In [2]: tag = ss.demand_tags.new({"name": "TEST API DOCS", "rate": 10.0, 'vast_endpoint_url': 'http://myvastendpoint.com/123', 'demand_partner_id':4321})

In [3]: print tag.ok, tag.id)
True, 30424

REST API

POST /api/v0/demand_tags

cURL (example)

curl --location 'https://console.clearline.magnite.com/api/v0/demand_tags' \
--header 'Authorization: authtokenhere' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Demand Tag - ClearLine API",
  "active": false,
  "demand_partner_id": 79715,
  "demand_class": 11,
  "format": "video",
  "bid_floor_type": "static",
  "rate": "20.0"
}'

Response

Status code 200

{
	"id": 1472406,
	"account_id": 1215,
	"name": "Demand Tag - ClearLine API",
	"is_active": false,
	"note": null,
	"rate": "20.0",
	"player_size_targeting": "All",
	"player_sizes": [
		"xs",
		"s",
		"m",
		"l",
		"xl",
		"u"
  ],
...
}

Get a demand tag by id

SDK

In [1]: import springserve as ss

In [2]: tag = ss.demand_tags.get(1472406)

In [3]: print(tag.name)
Out[3]: "Demand Tag - ClearLine API"

REST API

GET /api/v0/demand_tags/<id>

cURL (example):

curl --location 'https://console.clearline.magnite.com/api/v0/demand_tags/1472406' \
--header 'Authorization: authtokenhere' \
--header 'Content-Type: application/json'

Response:

{
	"id": 1472406,
	"account_id": 1215,
	"name": "Demand Tag - ClearLine API",
	"is_active": false,
	"note": null,
	"rate": "20.0",
...
}

Get demand tags based on multiple conditions

SDK

In [1]: active_tags_by_account = ss.demand_tags.get(account_id=123, active=True)

In [2]: print(active_tags_by_account[0].name)
Out[2]: "TEST ACTIVE DEMAND TAG"

REST API

GET /api/v0/demand_tags

cURL (example):

curl --location 'https://console.clearline.magnite.com/api/v0/demand_tags?active=false' \
--header 'Authorization: authtokenhere' \
--header 'Content-Type: application/json'

Response

Status code 200

[
	{
		"id": 1051320,
		"account_id": 1215,
		"name": "Line Item A",
		"is_active": false,
		...
	},
	{
		"id": 1051321,
		"account_id": 1215,
		"name": "Line Item B",
		"is_active": false,
		...
	},
	...
]

Edit a Demand Tag

SDK

In [1]: tag = ss.demand_tags.get(30424)

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)
Out[5]: "I want to change the name"

REST API

PUT /api/v0/demand_tags/<id>

cURL (example):

Co
curl --location --request PATCH 'https://console.clearline.magnite.com/api/v0/demand_tags/1472406' \
--header 'Authorization: authtokenhere' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Demand Tag - ClearLine API (With new name)"
}'

Response

Status code 200

{
	"id": 1472406,
	"account_id": 1215,
	"name": "Demand Tag - ClearLine API (With new name)",
	"is_active": false,
	"note": null,
	"rate": "20.0",
	...
}

Duplicate a Demand Tag

Please note that this works for both Managed and Direct Connect tags.

SDK

In [1]: tag = springserve.demand_tags.get(30424)

ln [2]: dupe = tag.duplicate()

ln [3]: dupe.ok
Out [3]: True

In [4]: print dupe.id
72302

REST API

GET /api/v0/demand_tags/<id>/duplicate

Headers

Content-Type application/json
Authorization "yourAuthToken"

Response

Status code 201

{
  'account_id': 1,
  'active': True,
  'demand_partner_id': 1764,
  'id': 72302,
  'name': 'I want to change the name (copy)',
    ...
  'rate': '0.01',
  'demand_tag_priorities': [{'supply_tag_id': 123456, 'priority': 1, 'tier': 0},
  {'supply_tag_id': 123456, 'priority': 1, 'tier': 1}],
  'vast_endpoint_url': 'http://test.com'
}

Demand Tag Creation Examples:

Create Demand Tags with Dynamic Bid Pricing:

Min Bid Price and Max Bid Price need to be set when any of the following conditions are true:

One or more Bid Modifiers are applied
Bid Shading is 'Enabled'
Bid Type is 'Dynamic'

Demand Tag using Bid Modifiers:

Apply one or more Bid Modifiers

Fields in API:

bid_modifier_ids (Bid Shading)
rate (Bid Price)
min_bid_price (Min Bid Price)
max_bid_price (Max Bid Price)

SDK

import springserve as ss
demand_tag = ss.demand_tags.new({
	"name": "Bid Modifier Line Item",
	"is_active": False,
	"rate": "15.0",
	"active": False,
	"demand_partner_id": 79715,
	"demand_class": 11,
	"bid_floor_type": "static",
	"min_bid_price": "10.0",
	"max_bid_price": "20.0",
	"bid_modifier_ids": [1]
})

REST API

curl --location 'https://console.clearline.magnite.com/api/v0/demand_tags' \
--header 'Authorization: authtokenhere' \
--header 'Content-Type: application/json' \
--data '{
	"name": "Bid Modifier Line Item",
	"is_active": false,
	"rate": "15.0",
	"active": false,
	"demand_partner_id": 79715,
	"demand_class": 11,
	"bid_floor_type": "static",
	"min_bid_price": "10.0",
	"max_bid_price": "20.0",
	"bid_modifier_ids": [1]
}'

Demand Tag using Bid Shading:

Set Bid Shading = Enabled

ClearLine Documentation > CL -Demand Tag API > Screenshot 2024-10-31 at 5.53.26 PM.png

This reveals the following pricing options:

ClearLine Documentation > CL -Demand Tag API > Screenshot 2024-10-31 at 5.52.50 PM.png

Fields in API:

bid_shading (Bid Shading)
rate (Bid Price)
min_bid_price (Min Bid Price)
max_bid_price (Max Bid Price)

SDK

import springserve as ss

demand_tag = ss.demand_tags.new({
	'name': "Bid Shading Line Item",
	'rate': "10.0",
	'bid_floor_type': 'static',
	'format': 'video',
	'bid_shading': True,
	'min_bid_price': '9.0',
	'max_bid_price': None,
	'demand_class': 11,
	'demand_partner_id': 79715,
	'is_active': False
})

REST API

curl --location 'https://console.clearline.magnite.com/api/v0/demand_tags' \
--header 'Authorization: authtokenhere' \
--header 'Content-Type: application/json' \
--data '{
	"name": "Bid Shading Line Item Example",
	"rate": "10.0",
	"bid_floor_type": "static",
	"format": "video",
	"bid_shading": true,
	"min_bid_price": "9.0",
	"max_bid_price": null,
	"demand_class": 11,
	"demand_partner_id": 79715,
	"is_active": false
}'

Demand Tag using Dynamic Bid Type:

Setting Bid Type to Dynamic reveals the following pricing options:

ClearLine Documentation > CL -Demand Tag API > Screenshot 2024-10-31 at 5.50.58 PM.png

Fields in API:

bid_floor_type (Bid Type)
bid_margin (Bid Percent Over Floor)
min_bid_price (Min Bid Price)
max_bid_price (Max Bid Price)

SDK

import springserve as ss

demand_tag = ss.demand_tags.new({
	"name": "Dynamic Bid Price Line Item - CL",
	"is_active": False,
	"active": False,
	"demand_partner_id": 79715,
	"demand_class": 11,
	"bid_floor_type": "dynamic",
	"bid_margin": 15.0,
	"format": "video",
	"min_bid_price": "1.0",
	"max_bid_price": "15.0",
	"buying_model": "private_market"
})

REST API

curl --location 'https://console.clearline.magnite.com/api/v0/demand_tags' \
--header 'Authorization: authtokenhere' \
--header 'Content-Type: application/json' \
--data '{
	"name": "Dynamic Bid Price Line Item - CL",
	"is_active": false,
	"active": false,
	"demand_partner_id": 79715,
	"demand_class": 11,
	"bid_floor_type": "dynamic",
	"bid_margin": 15.0,
	"format": "video",
	"min_bid_price": "1.0",
	"max_bid_price": "15.0",
	"buying_model": "private_market"
}'

Create Demand Tags with Geo Targeting:

Geo targeting can be applied at the following levels:

Country
Region (state, province, or territory)
DMA
City
Postal Code

For each option, you can select the following:

All (This is the default value)
Include
Exclude

If Include or Exclude are chosen, you must declare a source for the values that will be used. The options are as follows:

values
list

If "values" is the selected option, use the following objects:

country_codes (two-letter Country code) > array of strings
state_codes (two-letter Country code with State code, separated by "-". Example: "US-NY") > array of integers
dma_codes > array of integers
postal_codes > array of strings

If "list" is the selected option, use the following objects:

country_list_ids > array of integers
state_list_ids > array of integers
dma_list_ids > array of integers
postal_code_list_ids > array of integers

SDK

Target New York State, with the City Code of 5128581, and the Postal Code of 10001

import springserve as ss

demand_tag = ss.demand_tags.new({
	"name": "Line Item with GEO Targeting",
	"demand_partner_id": 79715,
	"is_active": False,
	"rate": "15.0",
	"active": False,
	"demand_class": 11,
	"bid_floor_type": "static",
	"format": "video",
	"buying_model": "private_market",
	"state_source": "values",
	"state_targeting": "Include",
	"state_codes": ["US-NY"],
	"state_lists": [],
	"state_list_ids": [],
	"city_source": "values",
	"city_targeting": "Include",
	"city_codes": [5128581],
	"city_lists": [],
	"city_list_ids": [],
	"postal_code_source": "values",
	"postal_code_targeting": "Include"
	"postal_codes": ["10001"],
	"postal_code_lists": [],
	"postal_code_list_ids": []
})

REST API

url --location 'https://console.clearline.magnite.com/api/v0/demand_tags' \
--header 'Authorization: authtokenhere' \
--header 'Content-Type: application/json' \
--data '{
	"name": "Line Item with GEO Targeting",
	"demand_partner_id": 79715,
	"is_active": False,
	"rate": "15.0",
	"active": False,
	"demand_class": 11,
	"bid_floor_type": "static",
	"format": "video",
	"buying_model": "private_market",
	"state_source": "values",
	"state_targeting": "Include",
	"state_codes": ["US-NY"],
	"state_lists": [],
	"state_list_ids": [],
	"city_source": "values",
	"city_targeting": "Include",
	"city_codes": [5128581],
	"city_lists": [],
	"city_list_ids": [],
	"postal_code_source": "values",
	"postal_code_targeting": "Include"
	"postal_codes": ["10001"],
	"postal_code_lists": [],
	"postal_code_list_ids": []
}'