Skip to content
Developer Guides (v3)
/
/
Topic Group
Last updated

Listening Topic Group API V3 — Developer Guide

1. Overview

Topic Groups organize Listening Topics into categories. The V3 API uses one resource path and differentiates operations by HTTP method.

OperationMethodPath
Fetch one, multiple, or all Topic GroupsGET/api/v3/listening/topicGroup
Create a Topic GroupPOST/api/v3/listening/topicGroup
Partially update a Topic GroupPATCH/api/v3/listening/topicGroup?id={id}
Delete one or more Topic GroupsDELETE/api/v3/listening/topicGroup?id={id}

1.1 Topic Group object

FieldTypeRequiredDescription
idStringNoUnique identifier of the Topic Group.
nameStringYesName of the Topic Group.
descriptionStringNoDescription of the Topic Group.
shareConfigsArray<AssetShareConfig>NoSharing configurations associated with the Topic Group.

1.2 AssetShareConfig object

FieldTypeRequiredDescription
typeStringYesSharing scope. Documented values include GLOBAL, CLIENT, CLIENT_GROUP, USER, and USER_GROUP.
idsArray<String>ConditionalIdentifiers associated with the selected sharing scope.

1.3 GET/POST and PATCH sharing models

GET and POST use shareConfigs, a plural array. PATCH uses shareConfig, a singular object, and may also contain permissionEntity.

ModelFieldShapePurpose
GET/POSTshareConfigsArray of {type, ids[]}Sharing configuration returned with Topic Groups or supplied during creation.
PATCHshareConfigObject with user, group, client, and client-group IDsControls who can view Topics in the Topic Group.
PATCHpermissionEntityObject with the same sub-fields as shareConfigControls who can edit or update Topics in the Topic Group.

2. Base URL and environments

Use the environment-specific API V3 base URL:

https://api3.sprinklr.com/{env}/api/v3

The Topic Group resource is:

https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup

Replace {env} with the assigned environment identifier.

3. Authentication and common headers

HeaderValueRequired onDescription
AuthorizationBearer {{accessToken}}All requestsOAuth credential used to authenticate the user.
Key{{apiKey}}All requestsAPI key used to authenticate the application.
Content-Typeapplication/jsonPOST, PATCHIndicates that the request body is JSON.
Acceptapplication/jsonRecommended on all requestsRequests a JSON response.

Do not publish access tokens, API keys, or session cookies in examples.

4. Fetch Topic Groups

GET /api/v3/listening/topicGroup

The same GET operation supports three retrieval modes:

  • Omit id to fetch all Topic Groups available to the caller.
  • Provide one ID to retrieve a specific Topic Group.
  • Provide comma-separated IDs to retrieve multiple Topic Groups.

4.1 Query parameters

ParameterSub-parameterLocationTypeRequiredDescription
idN/AQueryStringNoUnique identifier or comma-separated list of Topic Group IDs. When omitted, the API fetches all accessible Topic Groups.

id is a query parameter, not a path parameter.

4.2 Fetch a single Topic Group

Example request

curl --location 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup?id=6a9c0379fc2ea04ab3c62dce' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'

Example response

{
  "data": [
    {
      "id": "6a9c0379fc2ea04ab3c62dce",
      "name": "New Group 007",
      "description": "Optional description"
    }
  ],
  "errors": []
}

4.3 Fetch all Topic Groups

Omit the id query parameter.

Example request

curl --location 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'

Example response

{
  "data": [
    {
      "id": "6a9c0379fc2ea04ab3c62dce",
      "name": "New Group 007",
      "description": "Optional description"
    }
  ],
  "errors": []
}

4.4 Fetch multiple Topic Groups

Provide up to 50 comma-separated Topic Group IDs. Commas may be URL-encoded as %2C.

Example request

curl --location --globoff 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup?id=6967654151649239c74dfc0d%2C6995a3f1d7890350f0cd8e2c' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'

Example response

{
  "data": [
    {
      "id": "6967654151649239c74dfc0d",
      "name": "topic_backfill_dnd",
      "description": "Created via Automation",
      "shareConfigs": [
        {
          "type": "GLOBAL"
        }
      ]
    },
    {
      "id": "6995a3f1d7890350f0cd8e2c",
      "name": "Test-Topic-Group",
      "description": "Dummy Group For API test",
      "shareConfigs": [
        {
          "type": "CLIENT",
          "ids": ["66000002", "66000437"]
        },
        {
          "type": "CLIENT_GROUP",
          "ids": []
        },
        {
          "type": "USER",
          "ids": ["66006626"]
        },
        {
          "type": "USER_GROUP",
          "ids": ["682b6b7d296ee9626e5004fc"]
        }
      ]
    }
  ],
  "errors": []
}

4.5 Partial success with valid and invalid IDs

When a multi-ID request includes valid, invalid, missing, or blank values, the response may contain both successfully retrieved Topic Groups in data and item-level failures in errors.

Example request

curl --location --globoff 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup?id=6967654151649239c74dfc0d%2C6995a3f1d7890350f0cd8e2c%2CINVALID%2CTEST%2C%2C%2Cabcd' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}'

Example response

{
  "data": [
    {
      "id": "6967654151649239c74dfc0d",
      "name": "topic_backfill_dnd",
      "description": "Created via Automation",
      "shareConfigs": [
        {
          "type": "GLOBAL"
        }
      ]
    },
    {
      "id": "6995a3f1d7890350f0cd8e2c",
      "name": "Test-Topic-Group",
      "description": "Dummy Group For API test"
    }
  ],
  "errors": [
    {
      "id": "6995a49cf58d8b601be9ec24",
      "code": 404,
      "message": "Listening_topic_group not found for id: 'INVALID'. Verify the listening_topic_group exists and you have access permissions."
    },
    {
      "id": "6995a49cf58d8b601be9ec25",
      "code": 404,
      "message": "Listening_topic_group not found for id: 'TEST'. Verify the listening_topic_group exists and you have access permissions."
    },
    {
      "id": "6995a49cf58d8b601be9ec23",
      "code": 400,
      "message": "Invalid id format: ''. Value cannot be empty or blank."
    },
    {
      "id": "6995a49cf58d8b601be9ec26",
      "code": 404,
      "message": "Listening_topic_group not found for id: 'abcd'. Verify the listening_topic_group exists and you have access permissions."
    }
  ]
}

Always inspect errors, even when data contains records.

4.6 Maximum ID limit

A single request supports a maximum of 50 Topic Group IDs. Split larger lists into batches of 50.

Example response for 51 IDs

{
  "errors": [
    {
      "id": "6995bcdaf58d8b601be9edc3",
      "code": 400,
      "message": "Maximum of 50 listening_topic_group identifiers supported per request. Provided: 51. Consider splitting you request in batches of 50 identifiers per request"
    }
  ]
}

4.7 GET response parameters

ParameterSub-parameterTypeDescription
dataN/AArrayTopic Groups successfully returned by the API.
dataidStringUnique identifier of the Topic Group.
datanameStringName of the Topic Group.
datadescriptionStringDescription of the Topic Group. May be empty or omitted.
datashareConfigsArraySharing configurations associated with the Topic Group.
data.shareConfigstypeStringSharing scope. Values shown in the source include GLOBAL, CLIENT, CLIENT_GROUP, USER, and USER_GROUP.
data.shareConfigsidsArray<String>Identifiers associated with the sharing scope. Returned only where applicable.
errorsN/AArrayErrors encountered while processing the request. Empty on complete success.
errorsidStringUnique identifier associated with an error.
errorscodeIntegerError code.
errorsmessageStringDescription of the error.

5. Create a Topic Group

POST /api/v3/listening/topicGroup

Creates a Listening Topic Group and returns its identifier and related fields.

5.1 Request body

ParameterSub-parameterTypeRequiredDescription
nameN/AStringYesName of the Topic Group to create.
descriptionN/AStringNoAdditional details about the Topic Group.
shareConfigsN/AArrayNoSharing configurations associated with the Topic Group.
shareConfigs[]typeStringYes within objectSharing scope.
shareConfigs[]idsArray<String>ConditionalIDs associated with the sharing scope.

5.2 Example request

curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "name": "Brand Monitoring Groups",
    "description": "Optional description"
  }'

5.3 Example response

{
  "data": {
    "id": "6a86f91b670de61b6833e25a",
    "name": "Brand Monitoring Groups",
    "description": "Optional description"
  },
  "errors": []
}

5.4 POST response parameters

ParameterSub-parameterTypeDescription
dataidStringUnique identifier of the created Topic Group.
datanameStringName of the Topic Group.
datadescriptionStringDescription of the Topic Group.
errorsN/AArrayErrors encountered during processing. Empty on success.

POST returns data as an object, while GET returns data as an array.

6. Partially Update a Topic Group

PATCH /api/v3/listening/topicGroup?id={id}

Updates selected fields of one Topic Group.

6.1 Query parameters

ParameterLocationTypeRequiredDescription
idQueryStringYesUnique identifier of the Topic Group to update. Update one Topic Group per call.

6.2 Request body

ParameterSub-parameterTypeRequiredDescription
nameN/AStringNoUpdated Topic Group name.
descriptionN/AStringNoUpdated Topic Group description.
shareConfigN/AObjectNoConfiguration controlling who can view Topics in the Topic Group.
shareConfiguserIdsArray<Long>NoUser IDs.
shareConfiguserGroupIdsArray<String>NoUser Group IDs.
shareConfigclientIdsArray<Long>NoClient IDs.
shareConfigclientGroupIdsArray<String>NoClient Group IDs.
shareConfigshareWithEveryOneBooleanNoWhen true, shares with every user.
permissionEntityN/AObjectNoConfiguration controlling who can edit or update Topics in the Topic Group. Uses the same sub-fields as shareConfig.

6.3 Example request

curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup?id=6a86f91b670de61b6833e25a' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "name": "Renamed Group",
    "description": "Updated description"
  }'

6.4 Example response

HTTP/1.1 204 No Content

The source materials contain conflicting PATCH response descriptions. Validate the published status and body against the current service contract.

7. Delete Topic Groups

DELETE /api/v3/listening/topicGroup?id={id}

Deletes one or more Topic Groups.

7.1 Query parameters

ParameterLocationTypeRequiredDescription
idQueryStringYesTopic Group ID or comma-separated Topic Group IDs to delete.

7.2 Delete one Topic Group

curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup?id=6a86f91b670de61b6833e25a' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}' \
  --header 'Accept: application/json'

7.3 Bulk delete Topic Groups

curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup?id=6a86f91b670de61b6833e25a,64dc93460cfbc0371ee1ac54' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Key: {{apiKey}}' \
  --header 'Accept: application/json'

7.4 Example response

HTTP/1.1 204 No Content

The source materials contain conflicting DELETE response descriptions. Validate the published status and body against the current service contract.

8. Response Formats

8.1 GET success envelope

{
  "data": [
    {
      "id": "<TOPIC_GROUP_ID>",
      "name": "Topic Group Name"
    }
  ],
  "errors": []
}

8.2 POST success envelope

{
  "data": {
    "id": "<TOPIC_GROUP_ID>",
    "name": "Topic Group Name"
  },
  "errors": []
}

8.3 Partial-success envelope

{
  "data": [],
  "errors": [
    {
      "id": "<ERROR_ID>",
      "code": 404,
      "message": "<ERROR_MESSAGE>"
    }
  ]
}

9. Error Handling and Response Codes

CodeMeaningDocumented scenario
200 OKSuccessRequest processed successfully. Inspect errors for partial failures.
204 No ContentSuccess with no bodyShown in supplied PATCH and DELETE examples.
400 Bad RequestInvalid requestBlank ID or more than 50 IDs.
401 UnauthorizedAuthentication failedMissing, expired, or invalid authorization token.
403 ForbiddenPermission failureCaller lacks required access.
404 Not FoundResource not foundNo accessible Topic Group found for the supplied ID.

Error object

FieldTypeDescription
idStringIdentifier associated with the error.
codeIntegerError code.
messageStringHuman-readable failure description.

10. V2 to V3 Migration

V2 operationV2 endpointV3 endpoint
Create Topic GroupPOST /api/v2/listening-topic-groupPOST /api/v3/listening/topicGroup
Read Topic GroupGET /api/v2/listening-topic-group/{Id}GET /api/v3/listening/topicGroup?id={id}
Fetch All Topic GroupsGET /api/v2/listening-topic-groupGET /api/v3/listening/topicGroup
Update Topic GroupPUT /api/v2/listening-topic-group/{Id}PATCH /api/v3/listening/topicGroup?id={id}
Delete Topic GroupDELETE /api/v2/listening-topic-group/{Id}DELETE /api/v3/listening/topicGroup?id={id}

Migration considerations

  • V3 uses a query parameter for the Topic Group ID.
  • V3 GET supports one ID, multiple comma-separated IDs, or no ID.
  • V3 PATCH replaces the V2 PUT operation.
  • GET returns data as an array, while POST returns data as an object in the supplied samples.

11. Use Cases

11.1 Create and verify a Topic Group

Create the Topic Group with POST, persist the returned data.id, and retrieve it with GET.

11.2 Retrieve multiple Topic Groups

Submit up to 50 comma-separated Topic Group IDs and review both data and errors.

11.3 Fetch all accessible Topic Groups

Omit id to retrieve Topic Groups available to the caller.

11.4 Update Topic Group metadata

Use PATCH to change the name or description without replacing the complete object.

11.5 Delete multiple Topic Groups

Pass comma-separated IDs to the DELETE endpoint.

12. Caveats and Best Practices

  • Use /api/v3/listening/topicGroup without a trailing slash before the query string.
  • Treat id as a query parameter.
  • Send no more than 50 IDs in a multi-ID GET request.
  • Always inspect errors because bulk GET can return partial results.
  • URL-encode commas and any IDs containing spaces when required by the client.
  • Do not assume every Topic Group ID follows a 24-character hexadecimal format.
  • Keep shareConfigs for GET/POST distinct from shareConfig and permissionEntity on PATCH.
  • Do not include cookies, access tokens, or API keys in published examples.
  • Confirm PATCH and DELETE success responses against the service contract before publication.

13. Quick Reference

TaskMethodRequest
Fetch allGET/api/v3/listening/topicGroup
Fetch oneGET/api/v3/listening/topicGroup?id={id}
Fetch multipleGET/api/v3/listening/topicGroup?id={id1},{id2}
CreatePOST/api/v3/listening/topicGroup
UpdatePATCH/api/v3/listening/topicGroup?id={id}
Delete oneDELETE/api/v3/listening/topicGroup?id={id}
Delete multipleDELETE/api/v3/listening/topicGroup?id={id1},{id2}

14. Publishing Checklist

  • Verify the production base URL and {env} placement.
  • Verify PATCH and DELETE status codes and response bodies.
  • Confirm the maximum delete batch size.
  • Confirm behavior when id is explicitly present but blank.
  • Confirm permission requirements for create, update, and delete.
  • Validate every cURL request.
  • Remove real credentials and session cookies.
  • Confirm sharing-model behavior for shareConfigs, shareConfig, and permissionEntity.

All identifiers and credentials in this guide are placeholders or documentation examples. Do not commit or log real credentials.

Theme

Topics