/
Deal ID List API

Deal ID List API

Oct 23, 2023

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

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

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