Segments API

Segments can be created, edited, deleted and viewed using the following REST api instructions. When you have created a segment, you can attach that list to a demand or supply tag for targeting.

1 Creating a Segment
- 1.1 SDK
- 1.2 REST API
2 Get a segment
- 2.1 SDK
- 2.2 REST API
3 Add elements to a Segment
- 3.1 SDK
- 3.2 REST API
4 Add Items to a Segment using a File
- 4.1 SDK
- 4.2 REST API
5 Replace Entire Segment
- 5.1 SDK
- 5.2 REST API
6 Replace Entire Segment with a File
- 6.1 SDK
- 6.2 REST API
7 Get Device IDs or Cookies in a Segment
- 7.1 SDK
- 7.2 REST API
8 Remove specific Device Ids or Cookies
- 8.1 SDK
- 8.2 REST API
9 Remove specific items using a File
- 9.1 SDK
- 9.2 REST API
10 Remove all items in a segment
- 10.1 SDK
11 Edit Segments
- 11.1 SDK
- 11.2 REST API
- 11.3 Examples
12 Delete Segments
- 12.1 SDK
- 12.2 REST API
13 Attach to a Demand or Supply Tag

Creating a Segment

SDK

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

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.new({'account_id':1, 'name':'my segment'})
 
In [3]: print segm_list.ok, segm_list.id
True 9

REST API

POST /api/v0/segments

Headers

Content-Type application/json
Authorization "yourAuthToken"

Body (example)

Device ID Segment

{

"name": "My Device Segment",

"description": "My Device description",

"segment_type”: "list",
"segment_list_type”: "device_id"

}

Cookie ID Segment

{
"name": "My Cookie ID Segment",
"description": "My Cookie ID description"
"segment_type”: "list",
"segment_list_type”: "cookie"
}

Required parameters: name. If not given a segment_type it will default to 'cookie'

Full options:

segment_type (list or pixel)

segment_list_type (cookie or device_id) – only applies when segment_type is list

segment_pixel_type (cookie or ip) – only applies when segment_type is pixel

Response

Status code 200

{
    "id": 10044,
    "account_id": 1,
    "name": "My DID Segment",
    "description": "My description",
    "active": true,
    "segment_type": "list",
    "segment_list_type": "cookie",
    "created_at": "2020-03-18T19:17:01.383Z"
}

Get a segment

SDK

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

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9)
In [3]: segm_list.raw
Out[3]:
{'id': 10064,
 'account_id': 1,
 'name': 'test segment',
 'description': None,
 'active': True,
 'segment_type': 'pixel',
 'segment_pixel_type': 'cookie',
 'user_expiration_value': None,
 'created_at': '2021-02-11T22:05:47.412Z'}

REST API

GET /api/v0/segments/<id>

Headers

Content-Type application/json
Authorization "yourAuthToken"

Response

Status code 200

{
    "id": 10044,
    "account_id": 1,
    "name": "My DID Segment",
    "description": "My description",
    "active": true,
    "segment_type": "list",
    "segment_list_type": "cookie",
    "created_at": "2020-03-18T19:17:01.383Z"
}

Add elements to a Segment

SDK

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9)
In [3]: add = segm_list.bulk_create(['123456789909nfejwnfkjewrjkweh8368721y6','123456789909nfejwnfkjewrjkweh8768765r7'])
In [4]: add.ok
Out[4]: True

REST API

POST /api/v0/segments/<id>/items/bulk_create

Headers

Content-Type application/json
Authorization "yourAuthToken"

Body (example)

{
  "items": ["d207654f-6bdd-474e-9734-67b7c3d02d96"]
}

Response

Status code 200

{"created": True}

Add Items to a Segment using a File

SDK

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9)
In [3]: add = segm_list.bulk_create(file_path='/<filepath>/appending_segm_list.csv')
In [4]: add.ok
Out[4]: True

REST API

POST /api/v0/segments/<id>/items/file_bulk_create

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

Response

Status code 201

{"created": True}

Replace Entire Segment

SDK

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9) 
In [3]: repl = segm_list.bulk_replace(['123456789909nfejwnfkjewrjkweh8368721y6'])
In [4]: repl.ok
Out[4]: True

REST API

POST /api/v0/segments/<id>/items/bulk_replace

Headers

Content-Type application/json
Authorization "yourAuthToken"

Body (example)

{
"items": ["item1", "item2"]
}

Response

Status code 201

{"created": True}

Replace Entire Segment with a File

Replaces segment with the items in the csv file

SDK

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9)
In [3]: repl = segm.bulk_replace(file_path='/<filepath>/repl_segm_list.csv')
In [4]: repl.ok
Out[4]: True

REST API

POST /api/v0/segments/<id>/items/file_bulk_replace

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

Response

Status code 201

{"created": True}

Get Device IDs or Cookies in a Segment

SDK

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9)
In [3]: my_list = segm_list.get_list()
In [4]: my_list.raw
Out[4]:
[{'item': 'd207654f-6bdd-474e-9734-67b7c3d02d96'},
 {'item': '123456789909nfejwnfkjewrjkweh8368721y3'},
 {'item': 'd207654f-6bdd-474e-9734-67b7c3d02d97'}]

REST API

GET /api/v0/segments/<id>/items

Headers

Content-Type application/json
Authorization "yourAuthToken"

Response (note you need to paginate)

Status code 200

[
    {
        "item": "d207654f-6bdd-474e-9734-67b7c3d02d96"
    },
    {
        "item": "d20gt57i-6bdd-474e-9734-67b7c3d02d96"
    }
]

Remove specific Device Ids or Cookies

SDK

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9)
In [3]: del = segm_list.bulk_delete(['d207654f-6bdd-474e-9734-67b7c3d02d96', '123456789909nfejwnfkjewrjkweh8368721y3'])
In [4]: del.ok
Out[4]: True

REST API

DELETE /api/v0/segments/<id>/items/bulk_delete

Headers

Content-Type application/json
Authorization "yourAuthToken"

Body (example) where "1" and "2" are the numeric

{
  "items": ["d207654f-6bdd-474e-9734-67b7c3d02d96"]
}

Response (note you need to pagenate)

Status code 200

{"deleted": True}

Remove specific items using a File

Removes items in the csv file from the segment

SDK

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9)
In [3]: del = segm_list.bulk_delete(file_path='/<filepath>/ips_to_delete.csv')
In [4]: del.ok
Out[4]: True

REST API

DELETE /api/v0/segments/<id>/items/file_bulk_delete

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

Response

Status code 200

{"deleted": True}

Remove all items in a segment

SDK

In [1]: import springserve
 
In [2]: segm_list = springserve.segment_lists.get(9) 
In [3]: repl = segm_list.bulk_replace([''])
In [4]: repl.ok
Out[4]: True

Edit Segments

SDK

segment = springserve.segment_lists.get(14367)

segment.active = "false"

changed = segment.save()
changed.ok
print(changed.active)

True
False

REST API

Method: PATCH

Endpoint URL: /api/v0/segments/<id>

Parameters:

id - (required, type: integer) ID of the segment.

Request:

PATCH /api/v0/segments/14366

Host: console.springserve.com
Content-Type: application/json
Authorization: "yourAuthToken"

{
	"active": false
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 14366,
    "account_id": 391,
    "name": "API Example Segment",
    "description": null,
    "active": false,
    "segment_count": 3,
    "upload_status": "complete",
    "segment_type": "pixel",
    "segment_pixel_type": "cookie",
    "user_expiration_value": 14,
    "created_at": "2019-05-29T19:12:38.248Z",
    "updated_at": "2023-12-01T10:24:01.506Z"
}

Examples

Python Example

import requests
import json

url = "https://console.springserve.com/api/v0/segments/25528"

payload = json.dumps({
  "active": False
})
headers = {
  'Authorization': 'yourAuthToken',
  'Content-Type': 'application/json'
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)

NodeJS Example

var request = require('request');
var options = {
  'method': 'PATCH',
  'url': 'https://admin-console.springserve.com/api/v0/segments/14366',
  'headers': {
    'Authorization': 'yourAuthToken',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "active": false
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Delete Segments

SDK

n/a

REST API

Method: DELETE

Endpoint URL: /api/v0/segments/<id>

Parameters:

id - (required, type: integer) ID of the segment.

Request:

DELETE /api/v0/segments/14366

Host: console.springserve.com
Content-Type: application/json
Authorization: "yourAuthToken"

Response:

HTTP/1.1 204 No Content
Content-Type: application/json

Attach to a Demand or Supply Tag

See documentation on the Supply and Demand Tag APIs