Topics

Available Endpoints

Base Route: /preference-center/api/v1/topics

1. GET /preference-center/api/v1/topics

Retrieves a list of preference topics.

Query Parameters:

• brandGroupId (optional): Filters results by brand group ID
• hideFromUi (optional): Filters topics by UI visibility flag. Defaults to false (returns only non-hidden topics) if not provided

Response: Returns a list of Topic objects with HTTP 200 OK status

2. POST /preference-center/api/v1/topics

Creates a new preference topic.

Request Body Example:

{
    "name": "Topic name",
    "description": "Topic description",
    "brandGroupId": "926608d8-c884-4ce3-b789-f369363b1c81",
    "hideFromUi": false
}

Response: Returns the created Topic object with HTTP 201 Created status

Error Responses:

• HTTP 400 Bad Request: Returns validation errors if the request is invalid

3. PUT /preference-center/api/v1/topics

Updates an existing preference topic.

Request Body Example:

{
    "id": "5bbbc38d-6n76-4ee8-8443-74c69094b267",
    "name": "Topic name",
    "description": "Topic description",
    "brandGroupId": "926608d8-c884-4ce3-b789-f369363b1c81",
    "hideFromUi": false
}

Important Note: The hideFromUi property cannot be changed after a topic is created.

Response: Returns the updated Topic object with HTTP 200 OK status

Error Responses:

• HTTP 400 Bad Request: Returns validation errors if the request is invalid

4. DELETE /preference-center/api/v1/topics/{id}

Deletes a preference topic by its ID.

Route Parameters:

• id: The unique identifier (GUID) of the topic to delete

Response: Returns the deleted Topic object with HTTP 200 OK status

Error Responses:

• HTTP 404 Not Found: Returns if the topic with the specified ID does not exist

Authentication

API key authentication with role-based access control is required. Include a valid API key in the X-API-KEY header. The API key must have the admin role. For details on creating an API key, see here.

Key Features

• Brand Group Filtering: Topics can be filtered by brand group, allowing management of topics specific to different brand groups
• UI Visibility Control: Topics can be hidden from the user interface using the hideFromUi flag, used for topics that shouldn't be displayed to end users in the UI
• Request Validation: All requests are validated to ensure data integrity and proper formatting

Topic Model

Each topic contains the following properties:

• Id (Guid): Unique identifier for the topic
• Name (string): Display name of the topic
• Description (string): Description of what the topic represents
• ParentId (Guid): Reference to a parent topic
• Order (int): Display order for sorting topics in the UI
• BrandGroupId (Guid): The brand group which the topic belongs to
• HideFromUi (bool): Flag indicating whether the topic should be hidden from user interfaces
• CreatedAt (DateTime): Timestamp when the topic was created
• CreatedBy (string): Identifier of the user who created the topic
• UpdatedAt (DateTime): Timestamp when the topic was last updated
• UpdatedBy (string): Identifier of the user who last updated the topic