Deal Lists API

Overview

The Deal Lists API v0 provides endpoints for managing deal lists and their associated deals. Deal lists are collections of deal objects.

Base URL

https://console.springserve.com/api/v0

Parameters

Deal List Parameters

Parameter	Type	Required	Description

Parameter	Type	Required	Description
`name`	string	Yes (create)	Name of the deal list
`description`	string	No	Description of the deal list
`is_active`	boolean	No	Whether the deal list is active (default: true)
`deals`	array[integer]	No	Array of deal IDs to associate with the list

Bulk Operations Parameters

Parameter	Type	Required	Description

Parameter	Type	Required	Description
`deals`	array[integer]	Yes	Array of deal IDs for bulk operations

Endpoints

1. List Deal Lists

Retrieve a paginated list of deal lists.

Endpoint: GET /api/v0/deal_lists

Response Format: Array of deal list objects

Example Request:

curl -X GET "<https://console.springserve.com/api/v0/deal_lists?page=1&per=10>" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response:

[
  {
    "id": 123,
    "name": "A List of Great Deals",
    "description": "High-quality publisher deals",
    "account_id": 456,
    "is_active": true,
    "deal_count": 15,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z"
  }
]

2. Get Deal List Details

Retrieve detailed information about a specific deal list, including associated deals and deal objects.

Endpoint: GET /api/v0/deal_lists/:id

Example Request:

curl -X GET "<https://console.springserve.com/api/v0/deal_lists/123>" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response:

{
  "id": 123,
  "name": "A List of Great Deals",
  "description": "High quality deals",
  "account_id": 456,
  "is_active": true,
  "deal_count": 2,
  "deals": [789, 790],
  "deal_objects": [
    {
      "id": 789,
      "name": "Super Deluxe",
      "is_active": true,
      "deal_setting_id": 101
    },
    {
      "id": 790,
      "name": "Super Premium Deluxe",
      "is_active": true,
      "deal_setting_id": 102
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

3. Create Deal List

Create a new deal list with optional initial deals.

Endpoint: POST /api/v0/deal_lists

Example Request:

curl -X POST "<https://console.springserve.com/api/v0/deal_lists>" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Deal List",
    "description": "A collection of sweet deals",
    "is_active": true,
    "deals": [789, 790, 791]
  }'

Example Response:

{
  "id": 124,
  "name": "New Deal List",
  "description": "A collection of sweet deals",
  "account_id": 456,
  "is_active": true,
  "deal_count": 3,
  "deals": [789, 790, 791],
  "deal_objects": [
    {
      "id": 789,
      "name": "Elite deal",
      "is_active": true,
      "deal_setting_id": 101
    }
  ],
  "created_at": "2024-01-22T09:15:00Z",
  "updated_at": "2024-01-22T09:15:00Z"
}

4. Update Deal List

Update an existing deal list's properties and/or associated deals.

Endpoint: PUT /api/v0/deal_lists/:id or PATCH /api/v0/deal_lists/:id

Example Request:

curl -X PUT "<https://console.springserve.com/api/v0/deal_lists/123>" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "deals": [789, 790, 792]
  }'

Example Response:

{
  "id": 123,
  "name": "A List of Great Deals",
  "description": "Updated description",
  "account_id": 456,
  "is_active": true,
  "deal_count": 3,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-22T11:30:00Z"
}

5. Delete Deal List

Delete a deal list permanently.

Endpoint: DELETE /api/v0/deal_lists/:id

Example Request:

curl -X DELETE "<https://console.springserve.com/api/v0/deal_lists/123>" \
  -H "Authorization: YOUR_API_KEY"

Response:

Responds with a 204 if successful and an error message otherwise

6. Get Deal IDs

Retrieve only the deal IDs associated with a deal list.

Endpoint: GET /api/v0/deal_lists/:id/deals

Example Request:

curl -X GET "<https://console.springserve.com/api/v0/deal_lists/123/deals>" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response:

[789, 790, 791]

7. Add Deals to List (Bulk Create)

Add multiple deals to an existing deal list without removing existing deals.

Endpoint: POST /api/v0/deal_lists/:id/deals/bulk_create

Example Request:

curl -X POST "<https://console.springserve.com/api/v0/deal_lists/123/deals/bulk_create>" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deals": [793, 794]
  }'

Example Response:

[789, 790, 791, 793, 794]

8. Replace All Deals (Bulk Replace)

Replace all deals in a deal list with a new set of deals.

Endpoint: POST /api/v0/deal_lists/:id/deals/bulk_replace

Example Request:

curl -X POST "<https://console.springserve.com/api/v0/deal_lists/123/deals/bulk_replace>" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deals": [800, 801, 802]
  }'

Example Response:

[800, 801, 802]

9. Remove Deals from List (Bulk Delete)

Remove specific deals from a deal list.

Endpoint: DELETE /api/v0/deal_lists/:id/deals/bulk_delete

Example Request:

curl -X DELETE "<https://console.springserve.com/api/v0/deal_lists/123/deals/bulk_delete>" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deals": [790, 791]
  }'

Example Response:

[789]

Response Formats

Deal List Object

Field	Type	Description

Field	Type	Description
`id`	integer	Unique identifier for the deal list
`name`	string	Name of the deal list
`description`	string	Description of the deal list
`account_id`	integer	ID of the associated account
`is_active`	boolean	Whether the deal list is active
`deal_count`	integer	Number of deals in the list
`deals`	array[integer]	Array of deal IDs (only in show/create responses)
`deal_objects`	array[object]	Array of deal objects (only in show/create responses)
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update

Deal Object

Field	Type	Description

Field	Type	Description
`id`	integer	Unique identifier for the deal
`name`	string	Name of the deal
`is_active`	boolean	Whether the deal is active
`deal_setting_id`	integer	ID of the associated deal setting

Error Responses

All error responses follow the standard format:

{
  "error": "Error message description"
}

Notes

All timestamps are in UTC and follow ISO 8601 format
Deal validation occurs when adding deals to lists - non-existent deal IDs will cause validation errors
Bulk operations return the updated list of deal IDs
Empty arrays are valid for the deals parameter when creating or updating deal lists