Deal ID List API

Deal ID lists can be created, edited and viewed using the API. When you have created a Deal ID list, you can use that list in the Programmatic Supply section on a Demand Tag.

This feature is available for ClearLine account types.

SDK Object Dictionary

Object: response from springserve.deal_id_lists.get(<id>)

Name	Attribute/Method	Arguments	Description
account_id	attribute		SpringServe Account ID for object
active	attribute		Is Deal ID List active
bulk_create	method	list[str]	Add up to 10,000 values to a list
bulk_delete	method	list[str]	Remove up to 10,000 values to a list
bulk_replace	method	list[str]	Replace up to 10,000 values to a list
created_at	attribute		When object was created
deleted_at	attribute		When object was deleted
description	attribute		Optional description
duplicate	method	name: str	Copies original object, returns new object. Specify name as argument to provide a name to the new list
get_list	method	None	Returns object array of Deal ID Names
id	attribute		ID of Deal ID List Object
ids_count	attribute		Number of IDs stored
name	attribute		Name of Deal ID List
ok	attribute		Checks data types and values of object. If not ok, returns False.
pending_ids_count	attribute		Number of Deal IDs in processing queue to be added to list
processed_ids_count	attribute		Number of Deal IDs processed and added to list
raw	attribute		Returns Dictionary of object
save	method	None	Makes POST request to save object
status	attribute		Status of Pending/Processed IDs
updated_at	attribute		When object was last updated

Creating a Deal ID List

SDK

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

import springserve as ss
 
deal_id_list = ss.deal_id_lists.new({"name": "New Deal ID List"})
 
print(deal_id_list.ok, deal_id_list.id)
True 348

REST API

Method: POST

Endpoint: /api/v0/deal_id_lists

Fields:

Field	Data Type	Required	Notes
name	string	True	List title
description	string	False	Add your own description
active	bool	False	Default = true

Headers

Content-Type application/json
Authorization "yourAuthToken"

Body (example)

{
  "name": "New Deal ID List"
}

Response: Status code 200

{
  "id": 348,
  "name": "New Deal ID List",
  "description": null,
  "account_id": 1,
  "active": true,
  "status": "completed",
  "ids_count": 0,
  "pending_ids_count": 0,
  "processed_ids_count": 0,
  "created_at": "2023-10-02T21:24:08.989Z",
  "updated_at": "2023-10-02T21:25:12.713Z",
  "deleted_at": null
}

Get a Deal ID List

SDK

import springserve as ss

deal_id_list = ss.deal_id_lists.get(348)

print(deal_id_list.name)
# Output
"New Deal ID List"

REST API

Method: GET

Endpoint: /api/v0/deal_id_lists/<id>

Headers:

Content-Type application/json
Authorization "yourAuthToken"

Response: Status code 200

{
  "id": 348,
  "name": "New Deal ID List",
  "description": null,
  "account_id": 1,
  "active": true,
  "status": "completed",
  "ids_count": 0,
  "pending_ids_count": 0,
  "processed_ids_count": 0,
  "created_at": "2023-10-02T21:24:08.989Z",
  "updated_at": "2023-10-02T21:25:12.713Z",
  "deleted_at": null
}

Add Deal IDs

SDK

import springserve as ss

deal_id_list = ss.deal_id_lists.get(348)

response = deal_id_list.bulk_create(['deal_id_1', 'deal_id_2'])

print(response.ok)
True

REST API

Method: POST

Endpoint: /api/v0/deal_id_lists/<id>/deal_ids/bulk_create

Headers

Content-Type application/json
Authorization "yourAuthToken"

Body (example)

{
  "deal_ids": ["deal_id_1", "deal_id_2"]
}

Response: Status code 200

{"created": True}

Add Deal IDs from a File

Appends Deal IDs in the csv file to the list

REST API

Method: POST

Endpoint: /api/v0/deal_id_lists/<id>/deal_ids/file_bulk_create

curl --location --request POST 'https://console.springserve.com/api/v0/deal_id_lists/<id>/deal_ids/file_bulk_create' \
--header 'Content-Type: application/json' \
--header 'Authorization: <yourAuthToken>' \
--form 'csv_file=@"/<filepath>/appending_deal_id_list.csv"'

Response: Status code 201

{"created": True}

Replace Entire Deal ID List

SDK

import springserve as ss

deal_id_list = ss.deal_id_lists.get(348)

response = deal_id_list.bulk_replace(['new_deal_1', 'new_deal_2'])

print(response.ok)
# Output
True

REST API

Method: POST

Endpoint: /api/v0/deal_id_lists/<id>/deal_ids/bulk_replace

Headers

Content-Type application/json
Authorization "yourAuthToken"

Body (example)

{
    "deal_ids": ["new_deal_1", "new_deal_2"]
}

Response: Status code 201

{"created": True}

Replace Entire Deal ID List with a File

Replaces Deal ID list with the Deal IDs in the csv file

REST API

Method: POST

Endpoint: /api/v0/deal_id_lists/<id>/deal_ids/file_bulk_replace

curl --location --request POST 'https://console.springserve.com/api/v0/deal_id_lists/<id>/deal_ids/file_bulk_replace' \
--header 'Content-Type: application/json' \
--header 'Authorization: <yourAuthToken>' \
--form 'csv_file=@"/<filepath>/replacement_deal_id_list.csv"'

Response: Status code 201

{"created": True}

Get Deal IDs in Deal ID List

SDK

import springserve as ss

did_list = ss.deal_id_lists.get(348)

list_values = did_list.get_list()

for i in list_values:
	print(i["deal_id"])

# Output
deal_id_1
deal_id_2
deal_id_3

REST API

Method: GET

Endpoint: /api/v0/deal_id_lists/<id>/deal_ids

Headers

Content-Type application/json
Authorization "yourAuthToken"

Response: Status code 200 (note: you need to paginate)

[
	{"deal_id": "deal_id_1"}, 
    {"deal_id": "deal_id_2"}
]

Remove Deal IDs

SDK

import springserve as ss

deal_id_list = ss.deal_id_lists.get(348)

response = deal_id_list.remove_names(['deal_id_2'])

print(response.ok)
# Output
True

print(response.deleted)
# Output
True

REST API

Method: DELETE

Endpoint: /api/v0/deal_id_lists/<id>/deal_ids/bulk_delete

Headers

Content-Type application/json
Authorization "yourAuthToken"

Body (example)

{
	"deal_ids": ["deal_id_2"]
}

Response: Status code 200 (note you need to paginate)

{"deleted": True}

Remove Deal IDs Using a File

Removes Deal IDs in the csv file from the list

REST API

Method: POST

Endpoint: /api/v0/deal_id_lists/<id>/deal_ids/file_bulk_delete

curl --location --request POST 'https://console.springserve.com/api/v0/deal_id_lists/<id>/deal_ids/file_bulk_delete' \
--header 'Content-Type: application/json' \
--header 'Authorization: <yourAuthToken>' \
--form 'csv_file=@"/<filepath>/delete_these_deal_ids.csv"'

Response: Status code 200

{"deleted": True}

Target Deal IDs on a Demand Tag

To attach a Deal ID List to a demand tag, you must populate the "inventory_groups" object array.

SDK

import springserve as ss

tag = ss.demand_tags.get(1)

targeting_group = {
	"group": "1",
	"list_type": "white_list",
	"source_type": "list",
	"inventory_object": "DealIdList",
	"deal_id_list_ids": [348]
}

tag.inventory_groups.append(targeting_group)

print(tag.save().ok)
# Output
True

REST API

See documentation on the Supply and Demand Tag APIs