Get campaign groups

Retrieve information about all campaign groups within a chain.

Contents

• Overview
• Version-specific information
• Permissions and Authentication
• HTTP parameters
• Headers
• Example request & response
  • Request
  • Response
• Possible error responses

Overview

• Call name: get-campaign-groups
• Endpoint URL: https://{API hostname}/get-campaign-groups
• Request methods: GET
• Response Content-Type: application/json
• Auth required: yes

The get-campaign-groups endpoint is used to fetch a list of campaign groups that are associated with a chain. Campaign groups are collections of campaigns, and this endpoint allows you to retrieve all groups for a given chain.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version	Change details
>= 1.5.8	Add pagination parameter support (limit and offset parameters) and show pagination details in response (limit, offset, total_count fields)

Permissions and authentication

This API call requires a valid Spaaza session. The session can be as follows:

• Admin authentication: the performing user needs to be logged in and have read access to the chain to which the user is connected.
• User authentication: a session generated by an end-user login.
• Privileged authentication: the use of privileged authentication is permitted for this endpoint.

HTTP parameters

The following HTTP parameters can be passed to the API:

Parameter	Description
chain_id	(integer, mandatory) The ID of the chain for which the campaign groups are being requested.
name	(string, optional) Filter campaign groups by name using text search. Supports partial matching.
match_all	(boolean, optional, default false) When used with name parameter, requires all search terms to match.
status	(string, optional) Filter campaign groups by status. Accepts scheduled, active, or completed.
order_by	(string, optional, default created_date) Order results by: name, created_date, active_date_from, active_date_until.
order_dir	(string, optional, default DESC) Order direction: ASC or DESC.
limit	(integer, optional) Limits the number of results returned. Defaults to 500 if not set. Only available if API version >= 1.5.8.
offset	(integer, optional) Offsets the results returned. Defaults to 0 if not set. Only available if API version >= 1.5.8.

Headers

The following headers can/must be passed to the API call:

No special headers are required for this endpoint, but a valid session is required as described above.

Example Request & Response

Request

Example curl request:

curl --location 'https://{API hostname}/internal/get-campaign-groups?chain_id=1743&name=Alpha&status=active&order_by=name&order_dir=ASC&limit=2&offset=0' \
--header 'X-Spaaza-Session-User-Id: 1548854' \
--header 'X-Spaaza-Session-Key: 564e5b4faa7f639dacf1983f1dae62155d5734b789b06b5986c43bfe2542854e' \
--header 'X-Spaaza-API-Version: 1.5.8'

Response

Example response (paginated):

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "campaign_groups": [
            {
                "id": 1,
                "campaign_ids": [2],
                "created_date": "2025-07-01T12:00:00+00:00",
                "last_modified_date": "2025-07-10T09:00:00+00:00",
                "last_updated_by": [
                    {
                        "user_id": 2,
                        "name": "Admin Spaaza"
                    }
                ],
                "name": "Group A"
            },
            {
                "id": 2,
                "campaign_ids": [3, 4],
                "active_date_from": "2025-01-01T00:00:00+00:00",
                "active_date_until": "2025-12-31T23:59:59+00:00",
                "created_date": "2025-01-01T12:00:00+00:00",
                "last_modified_date": "2025-01-10T09:00:00+00:00",
                "last_updated_by": [
                    {
                        "user_id": 3,
                        "name": "User Spaaza"
                    }
                ],
                "name": "Group B"
            }
        ],
        "limit": 2,
        "offset": 0,
        "total_count": 5,
        "result_type": "get-campaign-groups"
    }
}

Example response (non-paginated, API version < 1.5.8):

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "campaign_groups": [
            {
                "id": 1,
                "campaign_ids": [2],
                "created_date": "2025-07-01T12:00:00+00:00",
                "last_modified_date": "2025-07-10T09:00:00+00:00",
                "last_updated_by": [
                    {
                        "user_id": 2,
                        "name": "Admin Spaaza"
                    }
                ],
                "name": "Group A"
            }
        ],
        "result_type": "get-campaign-groups"
    }
}

Possible error responses

The following represents a list of possible error responses for the get-campaign-groups endpoint:

Code	Name and Description	HTTP Status Code
6	no_valid_session The user needs to be logged in and a valid session key needs to be sent	401
68	permission_denied_or_non_existent This user has insufficient permissions for this object or the object does not exist.	500
217	chain_id_not_found No record has been found for that chain_id	400
419	parameter_invalid One of the parameters is invalid and should be in a different format.	400