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.

Creating a Deal ID List

SDK

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

In [1]: import springserve as ss
 
In [2]: deal_id_list = ss.deal_id_lists.new({"name": "New Deal ID List"})
 
In [3]: 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

In [1]: import springserve as ss

In [2]: deal_id_list = ss.deal_id_lists.get(348)
 
In [3]: print deal_id_list.name
"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

In [1]:  import springserve as ss

In [2]:  deal_id_list = ss.deal_id_lists.get(348)

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

In [4]:  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

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

In [1]:  import springserve as ss

In [2]:  did_list = ss.deal_id_lists.get(348)

In [3]:  list_values = did_list.get_list()

In [4]: for i in vals:
   ...:     print(i["deal_id"])
Out [4]:
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

In [1]: import springserve as ss

In [2]: deal_id_list = ss.deal_id_lists.get(348)

In [3]: response = deal_id_list.remove_names(['deal_id_2'])

In [4]: response.ok
Out [4]: True

In [5]: print response.deleted
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

In [1]: import springserve as ss

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

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

In [3]: tag.inventory_groups.append(targeting_group)

In [4]: print(tag.save().ok)
True

REST API

See documentation on the Supply and Demand Tag APIs