Skip to main content

Get campaign groups

Retrieve information about all campaign groups within a chain.​

Contents​

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.

When the name parameter is used to filter campaign groups by name, the results are ordered by how well each group's name matches the search terms, with the best matches first. The order_by and order_dir parameters are then applied to break ties between groups with an equally good match. Without a name filter, results are ordered by order_by and order_dir alone.

Version-specific information​

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

VersionChange details
>= 1.5.8Add 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:

ParameterDescription
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 with prefix search, and multiple search terms can be separated by spaces or commas. Results are ordered by relevance to the search terms, with the best matches first, before the order_by and order_dir parameters are applied.
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. When a name filter is used, this ordering is applied after relevance ordering, as a tiebreaker between equally relevant groups.
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:

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