# Listening Topic APIs V3 — Developer Guide **Applies to:** Sprinklr Listening Topic APIs ## 1. Overview The Listening Topic APIs enable you to create, update, delete, and reorganize Listening Topics programmatically. A Listening Topic defines the query, sources, filters, and collection period used to monitor conversations. The guide covers the following operations: | Operation | Method | Endpoint | | --- | --- | --- | | Create a topic | `POST` | `/api/v3/listening-topic` | | Update a Topic Group | `PATCH` | `/api/v3/listening/topicGroup/?id={id}` | | Get one or more topics | `GET` | `/api/v3/listening/topic?id={id}` | | Delete a topic | `DELETE` | `/api/v3/listening/topic/?id={id}` | | Bulk transfer topics | `POST` | `/api/v3/listening/topic/topicGroup/bulk-transfer` | ## 2. Base URLs and Environments The Create Topic example uses the following production endpoint pattern: ```text https://api3.sprinklr.com/{env}/api/v3 ``` Replace `{env}` with your assigned environment identifier. ## 3. Prerequisites Before sending a request, ensure that you have: - A valid authorization token. - An API key. - Access to the applicable environment. - The required Topic ID or Topic Group ID for update, delete, or transfer operations. ## 4. Authentication and Common Headers All API calls are authenticated with OAuth 2.0. See [Developer Tools in Sprinklr](https://www.sprinklr.com/help/articles/developer-tools/developer-tools-in-sprinklr/692e8b39f0afa271d18a5929) for API key and secret generation, and the Authorize flow. | Header | Value | Purpose | Required on | | --- | --- | --- | --- | | `Authorization` | `Bearer {{accessToken}}` | Authenticates the user with the server | All requests | | `Key` | `{{apiKey}}` | The API key acts as both a unique identifier and a secret token for authentication to a set of access rights | All requests | | `Content-Type` | `application/json` | Request format should be JSON, as the endpoint expects a JSON body | `POST`, `PUT` | | `Accept` | `application/json` | Declares the acceptable response type | All requests | ## 5. Create a Topic Creates a Listening Topic. A topic defines the query, sources, filters, and collection period used for listening. ### 5.1 Endpoint ```http POST https://api3.sprinklr.com/{env}/api/v3/listening-topic ``` ### 5.2 Request Body | Parameter | Sub-parameter | Type | Required | Description | | --- | --- | --- | --- | --- | | `name` | N/A | String | Yes | Name of the Listening Topic. | | `topicGroupId` | N/A | String | Yes | Unique identifier of the Topic Group to which the topic belongs. | | `topicType` | N/A | String | Yes | Type of topic. Example: `QUERY_LISTENING`. | | `sources` | N/A | Array | Yes | Listening sources from which data is collected. | | `sources` | `source` | String | Yes | Individual listening source. Example: `TWITTER`. | | `query` | N/A | String | Yes | Query used to collect and monitor conversations. | | `enabled` | N/A | Boolean | Yes | Determines whether the topic is active. | | `startDate` | N/A | Long | Yes | Start date and time in epoch milliseconds. | | `endDate` | N/A | Long | Yes | End date and time in epoch milliseconds. | ### 5.3 Example Request ```bash curl --location 'https://api3.sprinklr.com/{env}/api/v3/listening-topic' \ --header 'Authorization: Bearer ' \ --header 'Key: ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --data '{ "name": "Topic 1", "topicGroupId": "", "topicType": "QUERY_LISTENING", "sources": ["TWITTER"], "query": "sprinklr OR social", "enabled": true, "startDate": 1615140543000, "endDate": 1787875200000 }' ``` ### 5.4 Example Response ```json { "data": { "id": "", "name": "Topic 1", "topicType": "QUERY_LISTENING", "topicGroupId": "", "startDate": 1615140543000, "endDate": 1787875200000, "sources": ["TWITTER"], "enabled": true, "query": "sprinklr OR social", "languageCodes": [], "countryCodes": [], "excludeRetweets": false, "matchQuotedRetweets": false, "excludePossiblySensitiveContent": false, "excludeUrlsInSearch": false, "excludeRevItemName": false, "onlyVerifiedUser": false, "createdTime": 1787830639730, "modifiedTime": 1787830639730, "ownerUserId": 66009896, "lastModifiedUserId": 66009896, "clientId": 66001165, "autoBackfill": false }, "errors": [] } ``` ### 5.5 Response Parameters | Parameter | Sub-parameter | Type | Description | | --- | --- | --- | --- | | `data` | N/A | Object | Contains the created topic. | | `data` | `id` | String | Unique identifier of the topic. | | `data` | `name` | String | Name of the topic. | | `data` | `topicType` | String | Type of Listening Topic. | | `data` | `topicGroupId` | String | Topic Group associated with the topic. | | `data` | `startDate` | Long | Collection start time in epoch milliseconds. | | `data` | `endDate` | Long | Collection end time in epoch milliseconds. | | `data` | `sources` | Array | Source platforms monitored by the topic. | | `data.sources` | `source` | String | Individual listening source. | | `data` | `enabled` | Boolean | Indicates whether the topic is active. | | `data` | `query` | String | Listening query. | | `data` | `languageCodes` | Array | Language filters. An empty array indicates no language filter. | | `data.languageCodes` | `languageCode` | String | Individual language code. | | `data` | `countryCodes` | Array | Country filters. An empty array indicates no country filter. | | `data.countryCodes` | `countryCode` | String | Individual country code. | | `data` | `excludeRetweets` | Boolean | Indicates whether retweets are excluded. | | `data` | `matchQuotedRetweets` | Boolean | Indicates whether quoted retweets are matched. | | `data` | `excludePossiblySensitiveContent` | Boolean | Indicates whether potentially sensitive content is excluded. | | `data` | `excludeUrlsInSearch` | Boolean | Indicates whether posts containing URLs are excluded. | | `data` | `excludeRevItemName` | Boolean | Indicates whether reverse item names are excluded from matching. | | `data` | `onlyVerifiedUser` | Boolean | Indicates whether results are restricted to verified users. | | `data` | `createdTime` | Long | Topic creation timestamp. | | `data` | `modifiedTime` | Long | Last-modified timestamp. | | `data` | `ownerUserId` | Long | Identifier of the topic owner. | | `data` | `lastModifiedUserId` | Long | Identifier of the user who last modified the topic. | | `data` | `clientId` | Long | Identifier of the client account. | | `data` | `autoBackfill` | Boolean | Indicates whether automatic historical backfill is enabled. | | `errors` | N/A | Array | Error details. An empty array indicates a successful request. | | `errors` | `error` | Object | Individual error object, when applicable. | ## 6. Get Topics Retrieves one or more Listening Topics by unique identifier. The module includes single-topic retrieval, successful multi-topic retrieval, partial-success responses, and validation behavior when more than 50 identifiers are supplied. ### 6.0 Endpoint `GET {{baseUrl}}/api/v3/listening/topic?id={id}` ### 6.1 Get Topic by ID: Single Topic Found **Example Request** ```bash curl --location --globoff '{{baseUrl}}/api/v3/listening/topic?id=6981adc69bd0bb359f73ca2c' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer {{accessToken}}' ``` #### **Request Parameter** | **Parameter** | **Sub-parameter** | **Location** | **Required** | **Type** | **Description** | | --- | --- | --- | --- | --- | --- | | id | N/A | Query Parameter | Yes | String | Unique identifier of the Listening Topic to retrieve. You can provide a single Topic ID or a comma-separated list of Topic IDs for bulk retrieval. | | Accept | N/A | Header | Recommended | String | Specifies the expected response media type. Supported value: application/json. | | Authorization | accessToken | Header | Yes | String | OAuth bearer token used to authenticate the request. Format: Bearer {{accessToken}}. | #### **Example Response** ```json { "data": \[ { "id": "6981adc69bd0bb359f73ca2c", "name": "mfkhncg", "topicType": "QUERY_LISTENING", "description": "", "topicGroupId": "6982106d0b3819650b7a1478", "startDate": 1770106289824, "endDate": 1770143400000, "sources": \[ "INSTAGRAM", "FACEBOOK", "SNAPCHAT", "THREADS", "TWITTER", "BLUESKY", "QUORA", "STACK_EXCHANGE", "TIKTOK", "YOUTUBE", "VK", "FLICKR", "RSS_FEED", "WORDPRESS", "LINKEDIN", "REDDIT", "NEWS", "BLOGS", "FORUMS", "REVIEWS", "VIDEOS", "VIDEO_COMMENTS", "BLOG_COMMENTS", "CLASSIFIED", "PODCAST", "TV", "PRINT", "RADIO", "DATA_INGESTION" \], "enabled": false, "languageCodes": \[\], "countryCodes": \[\], "blockedDomains": \[\], "blockedDomainsListIds": \[\], "blockedClientProfileLists": \[\], "blockedPartnerProfileLists": \[\], "blockedCountryCodes": \[\], "blockedLanguageCodes": \[\], "blockedGeneratingSourceList": \[\], "blockedGeneratingSources": \[\], "inclusiveDomains": \[\], "inclusiveDomainsListIds": \[\], "inclusiveClientProfileLists": \[\], "inclusivePartnerProfileLists": \[\], "accountIds": \[\], "accountGroupIds": \[\], "excludeRetweets": false, "matchQuotedRetweets": false, "excludePossiblySensitiveContent": true, "excludeUrlsInSearch": false, "excludeRevItemName": false, "onlyVerifiedUser": false, "createdTime": 1770106310799, "modifiedTime": 1771328944176, "ownerUserId": 66066981, "lastModifiedUserId": 66000149, "clientId": 66000002, "partnerCustomProperties": { "\_c_67e45acb4405902aa25ebb9f": \[ "911" \], "\_c_656ae9d8e6089467fe77a5a3": \[ "Test 1" \], "\_c_659be6225b60146a7f2ab4b0": \[ "0" \] }, "clientCustomProperties": {}, "autoBackfill": false } \], "errors": \[\] } ``` #### **Response Parameters** | **Parameter** | **Sub-parameter** | **Type** | **Description** | | --- | --- | --- | --- | | data | N/A | Array | List of Listening Topic objects returned by the API. | | data | id | String | Unique identifier of the Listening Topic. | | data | name | String | Name of the Listening Topic. | | data | topicType | String | Type of Listening Topic. Example: QUERY_LISTENING. | | data | description | String | Description associated with the topic. May be empty if no description is configured. | | data | topicGroupId | String | Unique identifier of the Topic Group associated with the topic. | | data | startDate | Long | Topic start time in epoch milliseconds. | | data | endDate | Long | Topic end time in epoch milliseconds. | | data | sources | Array[String] | List of sources monitored by the topic. | | sources | N/A | String | Source name. Examples include INSTAGRAM, FACEBOOK, TWITTER, REDDIT, NEWS, REVIEWS, and DATA_INGESTION. | | data | enabled | Boolean | Indicates whether the topic is enabled for data collection. | | data | languageCodes | Array[String] | List of included language codes. Empty when no language filtering is configured. | | data | countryCodes | Array[String] | List of included country codes. Empty when no country filtering is configured. | | data | blockedDomains | Array[String] | Domains excluded from topic collection. | | data | blockedDomainsListIds | Array[String] | References to blocked domain lists. | | data | blockedClientProfileLists | Array[String] | Client profile lists excluded from collection. | | data | blockedPartnerProfileLists | Array[String] | Partner profile lists excluded from collection. | | data | blockedCountryCodes | Array[String] | Countries excluded from collection. | | data | blockedLanguageCodes | Array[String] | Languages excluded from collection. | | data | blockedGeneratingSourceList | Array[String] | Blocked source list identifiers. | | data | blockedGeneratingSources | Array[String] | Sources excluded from content generation. | | data | inclusiveDomains | Array[String] | Domains explicitly included in topic collection. | | data | inclusiveDomainsListIds | Array[String] | References to included domain lists. | | data | inclusiveClientProfileLists | Array[String] | Included client profile lists. | | data | inclusivePartnerProfileLists | Array[String] | Included partner profile lists. | | data | accountIds | Array[String] | Social account identifiers associated with the topic. | | data | accountGroupIds | Array[String] | Social account group identifiers associated with the topic. | | data | excludeRetweets | Boolean | Indicates whether retweets are excluded from collection. | | data | matchQuotedRetweets | Boolean | Indicates whether quoted retweets are matched and collected. | | data | excludePossiblySensitiveContent | Boolean | Indicates whether potentially sensitive content is excluded. | | data | excludeUrlsInSearch | Boolean | Indicates whether URLs are excluded from search matching. | | data | excludeRevItemName | Boolean | Indicates whether review item names are excluded from matching. | | data | onlyVerifiedUser | Boolean | Indicates whether only content from verified users is collected. | | data | createdTime | Long | Topic creation timestamp in epoch milliseconds. | | data | modifiedTime | Long | Last modification timestamp in epoch milliseconds. | | data | ownerUserId | Long | User ID of the topic owner. | | data | lastModifiedUserId | Long | User ID of the most recent modifier. | | data | clientId | Long | Unique identifier of the client associated with the topic. | | data | partnerCustomProperties | Object | Collection of partner-defined custom properties associated with the topic. | | partnerCustomProperties | | Array[String] | Values associated with the custom property key. | | data | clientCustomProperties | Object | Collection of client-defined custom properties associated with the topic. | | data | autoBackfill | Boolean | Indicates whether automatic backfill is enabled for the topic. | | errors | N/A | Array | List of errors encountered during request processing. Returns an empty array when the request is successful. | ### 6.2 Get Topics by ID: Multiple Topics Found #### **Request Parameters** | **Parameter** | **Sub-parameter** | **Location** | **Required** | **Type** | **Description** | | --- | --- | --- | --- | --- | --- | | id | N/A | Query Parameter | Yes | String | Comma-separated list of Listening Topic IDs to retrieve. The API returns details for each valid Topic identifier provided in the request. | | Accept | N/A | Header | Recommended | String | Specifies the expected response format. Supported value: application/json. | | Authorization | accessToken | Header | Yes | String | OAuth bearer token used to authenticate the API request. Format: Bearer {{accessToken}}. | | Key | apiKey | Header | Yes | String | API key used to authenticate the calling application. | #### **Example Request** ```bash curl --location --globoff '{{baseUrl}}/api/v3/listening/topic?id=6995980cbc163922662c9a27%2C6981adc69bd0bb359f73ca2c%2C699570a4bd0cf95d4a5cf360' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer {{accessToken}}' \\ --header 'Key: {{apiKey}}' ``` #### **Example Response** ```json { "data": \[ { "id": "6995980cbc163922662c9a27", "name": "Topic_filter_verification", "topicType": "QUERY_LISTENING", "description": "", "topicGroupId": "6967654151649239c74dfc0d", "startDate": 1771411371662, "endDate": 1771439400000, "sources": \[ "INSTAGRAM", "FACEBOOK", "SNAPCHAT", "THREADS", "TWITTER", "BLUESKY", "QUORA", "STACK_EXCHANGE", "TIKTOK", "YOUTUBE", "VK", "FLICKR", "RSS_FEED", "WORDPRESS", "LINKEDIN", "REDDIT", "NEWS", "BLOGS", "FORUMS", "REVIEWS", "VIDEOS", "VIDEO_COMMENTS", "BLOG_COMMENTS", "CLASSIFIED", "PODCAST", "TV", "PRINT", "RADIO", "DATA_INGESTION" \], "enabled": false, "languageCodes": \[\], "countryCodes": \[\], "blockedDomains": \[\], "blockedDomainsListIds": \[\], "blockedClientProfileLists": \[\], "blockedPartnerProfileLists": \[\], "blockedCountryCodes": \[\], "blockedLanguageCodes": \[\], "blockedGeneratingSourceList": \[\], "blockedGeneratingSources": \[\], "inclusiveDomains": \[\], "inclusiveDomainsListIds": \[\], "inclusiveClientProfileLists": \[\], "inclusivePartnerProfileLists": \[\], "accountIds": \[\], "accountGroupIds": \[\], "excludeRetweets": false, "matchQuotedRetweets": false, "excludePossiblySensitiveContent": true, "excludeUrlsInSearch": false, "excludeRevItemName": false, "onlyVerifiedUser": false, "createdTime": 1771411468873, "modifiedTime": 1771411644552, "ownerUserId": 66070831, "lastModifiedUserId": 66070831, "clientId": 66000002, "partnerCustomProperties": { "\_c_67e45acb4405902aa25ebb9f": \[ "911" \], "\_c_656ae9d8e6089467fe77a5a3": \[ "Test 1" \], "\_c_659be6225b60146a7f2ab4b0": \[ "0" \] }, "clientCustomProperties": {}, "autoBackfill": false }, { "id": "6981adc69bd0bb359f73ca2c", "name": "mfkhncg", "topicType": "QUERY_LISTENING", "description": "", "topicGroupId": "6982106d0b3819650b7a1478", "startDate": 1770106289824, "endDate": 1770143400000, "sources": \[ "INSTAGRAM", "FACEBOOK", "SNAPCHAT", "THREADS", "TWITTER", "BLUESKY", "QUORA", "STACK_EXCHANGE", "TIKTOK", "YOUTUBE", "VK", "FLICKR", "RSS_FEED", "WORDPRESS", "LINKEDIN", "REDDIT", "NEWS", "BLOGS", "FORUMS", "REVIEWS", "VIDEOS", "VIDEO_COMMENTS", "BLOG_COMMENTS", "CLASSIFIED", "PODCAST", "TV", "PRINT", "RADIO", "DATA_INGESTION" \], "enabled": false, "languageCodes": \[\], "countryCodes": \[\], "blockedDomains": \[\], "blockedDomainsListIds": \[\], "blockedClientProfileLists": \[\], "blockedPartnerProfileLists": \[\], "blockedCountryCodes": \[\], "blockedLanguageCodes": \[\], "blockedGeneratingSourceList": \[\], "blockedGeneratingSources": \[\], "inclusiveDomains": \[\], "inclusiveDomainsListIds": \[\], "inclusiveClientProfileLists": \[\], "inclusivePartnerProfileLists": \[\], "accountIds": \[\], "accountGroupIds": \[\], "excludeRetweets": false, "matchQuotedRetweets": false, "excludePossiblySensitiveContent": true, "excludeUrlsInSearch": false, "excludeRevItemName": false, "onlyVerifiedUser": false, "createdTime": 1770106310799, "modifiedTime": 1771328944176, "ownerUserId": 66066981, "lastModifiedUserId": 66000149, "clientId": 66000002, "partnerCustomProperties": { "\_c_67e45acb4405902aa25ebb9f": \[ "911" \], "\_c_656ae9d8e6089467fe77a5a3": \[ "Test 1" \], "\_c_659be6225b60146a7f2ab4b0": \[ "0" \] }, "clientCustomProperties": {}, "autoBackfill": false }, { "id": "699570a4bd0cf95d4a5cf360", "name": "Test 1", "topicType": "QUERY_LISTENING", "description": "", "topicGroupId": "products", "startDate": 1771400932179, "endDate": 1772217000000, "sources": \[ "INSTAGRAM", "FACEBOOK", "SNAPCHAT", "THREADS", "TWITTER", "BLUESKY", "QUORA", "STACK_EXCHANGE", "TIKTOK", "YOUTUBE", "VK", "FLICKR", "RSS_FEED", "WORDPRESS", "LINKEDIN", "REDDIT", "NEWS", "BLOGS", "FORUMS", "REVIEWS", "VIDEOS", "VIDEO_COMMENTS", "BLOG_COMMENTS", "CLASSIFIED", "PODCAST", "TV", "PRINT", "RADIO", "DATA_INGESTION" \], "enabled": true, "query": "(\\Apple\\ OR \\Apple Inc.\\ OR \\Apple brand\\) AND ((\\Iphone\\ OR \\Iphones\\ OR \\iPhone 14\\ OR \\iPhone 13\\ OR \\iPhone SE\\ OR \\iPhone 12\\ OR \\iPhone 11\\) OR (\\Apple smartphone\\ OR \\Apple mobile\\ OR \\Apple device\\)) AND (\\text@1\\ OR \\text@2\\ OR \\text@3\\ OR \\text@4\\)", "languageCodes": \[\], "countryCodes": \[\], "blockedDomains": \[\], "blockedDomainsListIds": \[\], "blockedClientProfileLists": \[\], "blockedPartnerProfileLists": \[\], "blockedCountryCodes": \[\], "blockedLanguageCodes": \[\], "blockedGeneratingSourceList": \[\], "blockedGeneratingSources": \[\], "inclusiveDomains": \[\], "inclusiveDomainsListIds": \[\], "inclusiveClientProfileLists": \[\], "inclusivePartnerProfileLists": \[\], "accountIds": \[\], "accountGroupIds": \[\], "excludeRetweets": false, "matchQuotedRetweets": false, "excludePossiblySensitiveContent": true, "excludeUrlsInSearch": false, "excludeRevItemName": false, "onlyVerifiedUser": false, "createdTime": 1771401380537, "modifiedTime": 1771401497874, "ownerUserId": 66007965, "lastModifiedUserId": 66007965, "clientId": 66000002, "partnerCustomProperties": { "\_c_67e45acb4405902aa25ebb9f": \[ "911" \], "\_c_656ae9d8e6089467fe77a5a3": \[ "Test 1" \], "\_c_659be6225b60146a7f2ab4b0": \[ "0" \] }, "clientCustomProperties": {}, "autoBackfill": false } \], "errors": \[\] } ``` #### **Response Parameters** | **Parameter** | **Sub-parameter** | **Type** | **Description** | | --- | --- | --- | --- | | data | N/A | Array | List of Listening Topic objects returned by the API. | | data | id | String | Unique identifier of the Listening Topic. | | data | name | String | Name of the Listening Topic. | | data | topicType | String | Type of Listening Topic. Example: QUERY_LISTENING. | | data | description | String | Description associated with the topic. May be empty if no description is configured. | | data | topicGroupId | String | Unique identifier of the Topic Group associated with the topic. | | data | startDate | Long | Topic start date and time represented in epoch milliseconds. | | data | endDate | Long | Topic end date and time represented in epoch milliseconds. | | data | sources | Array[String] | List of data sources monitored by the topic. | | sources | N/A | String | Source included in the topic, such as INSTAGRAM, FACEBOOK, TWITTER, REDDIT, NEWS, BLOGS, REVIEWS, or DATA_INGESTION. | | data | enabled | Boolean | Indicates whether the topic is active and collecting data. | | data | query | String | Boolean search query used by the Listening Topic. Present only for query-based topics. | | data | languageCodes | Array[String] | List of included language codes. Empty when no language filter is configured. | | data | countryCodes | Array[String] | List of included country codes. Empty when no country filter is configured. | | data | blockedDomains | Array[String] | Domains excluded from topic collection. | | data | blockedDomainsListIds | Array[String] | References to blocked domain lists. | | data | blockedClientProfileLists | Array[String] | Client profile lists excluded from collection. | | data | blockedPartnerProfileLists | Array[String] | Partner profile lists excluded from collection. | | data | blockedCountryCodes | Array[String] | Country codes excluded from collection. | | data | blockedLanguageCodes | Array[String] | Language codes excluded from collection. | | data | blockedGeneratingSourceList | Array[String] | References to blocked generating source lists. | | data | blockedGeneratingSources | Array[String] | Sources excluded from generated results. | | data | inclusiveDomains | Array[String] | Domains explicitly included in topic collection. | | data | inclusiveDomainsListIds | Array[String] | References to included domain lists. | | data | inclusiveClientProfileLists | Array[String] | Client profile lists explicitly included in collection. | | data | inclusivePartnerProfileLists | Array[String] | Partner profile lists explicitly included in collection. | | data | accountIds | Array[String] | Identifiers of monitored social accounts. | | data | accountGroupIds | Array[String] | Identifiers of monitored account groups. | | data | excludeRetweets | Boolean | Indicates whether retweets are excluded from collection. | | data | matchQuotedRetweets | Boolean | Indicates whether quoted retweets are matched and collected. | | data | excludePossiblySensitiveContent | Boolean | Indicates whether potentially sensitive content is excluded. | | data | excludeUrlsInSearch | Boolean | Indicates whether URLs are ignored in search matching. | | data | excludeRevItemName | Boolean | Indicates whether review item names are excluded from matching. | | data | onlyVerifiedUser | Boolean | Indicates whether content is collected only from verified users. | | data | createdTime | Long | Topic creation timestamp in epoch milliseconds. | | data | modifiedTime | Long | Last modification timestamp in epoch milliseconds. | | data | ownerUserId | Long | Identifier of the user who owns the topic. | | data | lastModifiedUserId | Long | Identifier of the user who last modified the topic. | | data | clientId | Long | Identifier of the client associated with the topic. | | data | partnerCustomProperties | Object | Partner-defined custom properties configured for the topic. | | partnerCustomProperties | | Array[String] | Values associated with a specific partner custom property. | | data | clientCustomProperties | Object | Client-defined custom properties configured for the topic. | | data | autoBackfill | Boolean | Indicates whether automatic backfill is enabled for the topic. | | errors | N/A | Array | List of errors encountered while processing the request. Returns an empty array when the request succeeds. | ### 6.3 Get Topics by ID: Partial Success with Invalid or Missing IDs #### **Request Parameters** | **Parameter** | **Sub-parameter** | **Location** | **Required** | **Type** | **Description** | | --- | --- | --- | --- | --- | --- | | id | N/A | Query Parameter | Yes | String | Comma-separated list of Listening Topic identifiers to retrieve. The request can contain both valid and invalid identifiers. Valid topics are returned in the data array, while invalid or non-existent identifiers are returned in the errors array. | | Accept | N/A | Header | Recommended | String | Specifies the expected response format. Supported value: application/json. | | Authorization | accessToken | Header | Yes | String | OAuth bearer token used to authenticate the API request. Format: Bearer {{accessToken}}. | | Key | apiKey | Header | Yes | String | API key used to authenticate the calling application. | #### **Example Request** ```bash curl --location --globoff '{{baseUrl}}/api/v3/listening/topic?id=6995980cbc163922662c9a27%2C6981adc69bd0bb359f73ca2c%2C699570a4bd0cf95d4a5cf360%2Cabcd%2Cdummy' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer {{accessToken}}' \\ --header 'Key: {{apiKey}}' ``` #### **Examples Response** ```json { "data": \[ { "id": "6995980cbc163922662c9a27", "name": "Topic_filter_verification", "topicType": "QUERY_LISTENING", "description": "", "topicGroupId": "6967654151649239c74dfc0d", "startDate": 1771411371662, "endDate": 1771439400000, "sources": \[ "INSTAGRAM", "FACEBOOK", "SNAPCHAT", "THREADS", "TWITTER", "BLUESKY", "QUORA", "STACK_EXCHANGE", "TIKTOK", "YOUTUBE", "VK", "FLICKR", "RSS_FEED", "WORDPRESS", "LINKEDIN", "REDDIT", "NEWS", "BLOGS", "FORUMS", "REVIEWS", "VIDEOS", "VIDEO_COMMENTS", "BLOG_COMMENTS", "CLASSIFIED", "PODCAST", "TV", "PRINT", "RADIO", "DATA_INGESTION" \], "enabled": false, "languageCodes": \[\], "countryCodes": \[\], "blockedDomains": \[\], "blockedDomainsListIds": \[\], "blockedClientProfileLists": \[\], "blockedPartnerProfileLists": \[\], "blockedCountryCodes": \[\], "blockedLanguageCodes": \[\], "blockedGeneratingSourceList": \[\], "blockedGeneratingSources": \[\], "inclusiveDomains": \[\], "inclusiveDomainsListIds": \[\], "inclusiveClientProfileLists": \[\], "inclusivePartnerProfileLists": \[\], "accountIds": \[\], "accountGroupIds": \[\], "excludeRetweets": false, "matchQuotedRetweets": false, "excludePossiblySensitiveContent": true, "excludeUrlsInSearch": false, "excludeRevItemName": false, "onlyVerifiedUser": false, "createdTime": 1771411468873, "modifiedTime": 1771411644552, "ownerUserId": 66070831, "lastModifiedUserId": 66070831, "clientId": 66000002, "partnerCustomProperties": { "\_c_67e45acb4405902aa25ebb9f": \[ "911" \], "\_c_656ae9d8e6089467fe77a5a3": \[ "Test 1" \], "\_c_659be6225b60146a7f2ab4b0": \[ "0" \] }, "clientCustomProperties": {}, "autoBackfill": false }, { "id": "6981adc69bd0bb359f73ca2c", "name": "mfkhncg", "topicType": "QUERY_LISTENING", "description": "", "topicGroupId": "6982106d0b3819650b7a1478", "startDate": 1770106289824, "endDate": 1770143400000, "sources": \[ "INSTAGRAM", "FACEBOOK", "SNAPCHAT", "THREADS", "TWITTER", "BLUESKY", "QUORA", "STACK_EXCHANGE", "TIKTOK", "YOUTUBE", "VK", "FLICKR", "RSS_FEED", "WORDPRESS", "LINKEDIN", "REDDIT", "NEWS", "BLOGS", "FORUMS", "REVIEWS", "VIDEOS", "VIDEO_COMMENTS", "BLOG_COMMENTS", "CLASSIFIED", "PODCAST", "TV", "PRINT", "RADIO", "DATA_INGESTION" \], "enabled": false, "languageCodes": \[\], "countryCodes": \[\], "blockedDomains": \[\], "blockedDomainsListIds": \[\], "blockedClientProfileLists": \[\], "blockedPartnerProfileLists": \[\], "blockedCountryCodes": \[\], "blockedLanguageCodes": \[\], "blockedGeneratingSourceList": \[\], "blockedGeneratingSources": \[\], "inclusiveDomains": \[\], "inclusiveDomainsListIds": \[\], "inclusiveClientProfileLists": \[\], "inclusivePartnerProfileLists": \[\], "accountIds": \[\], "accountGroupIds": \[\], "excludeRetweets": false, "matchQuotedRetweets": false, "excludePossiblySensitiveContent": true, "excludeUrlsInSearch": false, "excludeRevItemName": false, "onlyVerifiedUser": false, "createdTime": 1770106310799, "modifiedTime": 1771328944176, "ownerUserId": 66066981, "lastModifiedUserId": 66000149, "clientId": 66000002, "partnerCustomProperties": { "\_c_67e45acb4405902aa25ebb9f": \[ "911" \], "\_c_656ae9d8e6089467fe77a5a3": \[ "Test 1" \], "\_c_659be6225b60146a7f2ab4b0": \[ "0" \] }, "clientCustomProperties": {}, "autoBackfill": false }, { "id": "699570a4bd0cf95d4a5cf360", "name": "Test 1", "topicType": "QUERY_LISTENING", "description": "", "topicGroupId": "products", "startDate": 1771400932179, "endDate": 1772217000000, "sources": \[ "INSTAGRAM", "FACEBOOK", "SNAPCHAT", "THREADS", "TWITTER", "BLUESKY", "QUORA", "STACK_EXCHANGE", "TIKTOK", "YOUTUBE", "VK", "FLICKR", "RSS_FEED", "WORDPRESS", "LINKEDIN", "REDDIT", "NEWS", "BLOGS", "FORUMS", "REVIEWS", "VIDEOS", "VIDEO_COMMENTS", "BLOG_COMMENTS", "CLASSIFIED", "PODCAST", "TV", "PRINT", "RADIO", "DATA_INGESTION" \], "enabled": true, "query": "(\\Apple\\ OR \\Apple Inc.\\ OR \\Apple brand\\) AND ((\\Iphone\\ OR \\Iphones\\ OR \\iPhone 14\\ OR \\iPhone 13\\ OR \\iPhone SE\\ OR \\iPhone 12\\ OR \\iPhone 11\\) OR (\\Apple smartphone\\ OR \\Apple mobile\\ OR \\Apple device\\)) AND (\\text@1\\ OR \\text@2\\ OR \\text@3\\ OR \\text@4\\)", "languageCodes": \[\], "countryCodes": \[\], "blockedDomains": \[\], "blockedDomainsListIds": \[\], "blockedClientProfileLists": \[\], "blockedPartnerProfileLists": \[\], "blockedCountryCodes": \[\], "blockedLanguageCodes": \[\], "blockedGeneratingSourceList": \[\], "blockedGeneratingSources": \[\], "inclusiveDomains": \[\], "inclusiveDomainsListIds": \[\], "inclusiveClientProfileLists": \[\], "inclusivePartnerProfileLists": \[\], "accountIds": \[\], "accountGroupIds": \[\], "excludeRetweets": false, "matchQuotedRetweets": false, "excludePossiblySensitiveContent": true, "excludeUrlsInSearch": false, "excludeRevItemName": false, "onlyVerifiedUser": false, "createdTime": 1771401380537, "modifiedTime": 1771401497874, "ownerUserId": 66007965, "lastModifiedUserId": 66007965, "clientId": 66000002, "partnerCustomProperties": { "\_c_67e45acb4405902aa25ebb9f": \[ "911" \], "\_c_656ae9d8e6089467fe77a5a3": \[ "Test 1" \], "\_c_659be6225b60146a7f2ab4b0": \[ "0" \] }, "clientCustomProperties": {}, "autoBackfill": false } \], "errors": \[ { "id": "6995a269f58d8b601be9ebe9", "code": 404, "message": "Listening_topic not found for id: 'abcd'. Verify the listening_topic exists and you have access permissions." }, { "id": "6995a269f58d8b601be9ebea", "code": 404, "message": "Listening_topic not found for id: 'dummy'. Verify the listening_topic exists and you have access permissions." } \] } ``` #### **Response Parameters** | **Parameter** | **Sub-parameter** | **Type** | **Description** | | --- | --- | --- | --- | | data | N/A | Array | List of Listening Topic objects successfully retrieved by the API. | | data | id | String | Unique identifier of the Listening Topic. | | data | name | String | Name of the Listening Topic. | | data | topicType | String | Type of Listening Topic. Example: QUERY_LISTENING. | | data | description | String | Description associated with the topic. | | data | topicGroupId | String | Unique identifier of the Topic Group associated with the topic. | | data | startDate | Long | Topic start date and time in epoch milliseconds. | | data | endDate | Long | Topic end date and time in epoch milliseconds. | | data | sources | Array[String] | Collection of sources monitored by the topic. | | sources | N/A | String | Individual monitored source such as INSTAGRAM, FACEBOOK, TWITTER, REDDIT, NEWS, BLOGS, REVIEWS, or DATA_INGESTION. | | data | enabled | Boolean | Indicates whether the topic is active and collecting data. | | data | query | String | Boolean query associated with the topic. Present only for query-based topics. | | data | languageCodes | Array[String] | List of language codes included in the topic configuration. | | data | countryCodes | Array[String] | List of country codes included in the topic configuration. | | data | blockedDomains | Array[String] | Domains excluded from topic collection. | | data | blockedDomainsListIds | Array[String] | References to blocked domain lists. | | data | blockedClientProfileLists | Array[String] | Client profile lists excluded from collection. | | data | blockedPartnerProfileLists | Array[String] | Partner profile lists excluded from collection. | | data | blockedCountryCodes | Array[String] | Country codes excluded from collection. | | data | blockedLanguageCodes | Array[String] | Language codes excluded from collection. | | data | blockedGeneratingSourceList | Array[String] | Identifiers of blocked generating source lists. | | data | blockedGeneratingSources | Array[String] | Sources excluded from generated results. | | data | inclusiveDomains | Array[String] | Domains explicitly included in topic collection. | | data | inclusiveDomainsListIds | Array[String] | References to included domain lists. | | data | inclusiveClientProfileLists | Array[String] | Included client profile lists. | | data | inclusivePartnerProfileLists | Array[String] | Included partner profile lists. | | data | accountIds | Array[String] | Identifiers of monitored social accounts. | | data | accountGroupIds | Array[String] | Identifiers of monitored account groups. | | data | excludeRetweets | Boolean | Indicates whether retweets are excluded from collection. | | data | matchQuotedRetweets | Boolean | Indicates whether quoted retweets are matched. | | data | excludePossiblySensitiveContent | Boolean | Indicates whether potentially sensitive content is excluded. | | data | excludeUrlsInSearch | Boolean | Indicates whether URLs are ignored during query matching. | | data | excludeRevItemName | Boolean | Indicates whether review item names are excluded from query matching. | | data | onlyVerifiedUser | Boolean | Indicates whether content is collected only from verified users. | | data | createdTime | Long | Topic creation timestamp in epoch milliseconds. | | data | modifiedTime | Long | Last modification timestamp in epoch milliseconds. | | data | ownerUserId | Long | Identifier of the topic owner. | | data | lastModifiedUserId | Long | Identifier of the user who last modified the topic. | | data | clientId | Long | Identifier of the client associated with the topic. | | data | partnerCustomProperties | Object | Partner-defined custom properties associated with the topic. | | partnerCustomProperties | | Array[String] | Values configured for a specific partner custom property. | | data | clientCustomProperties | Object | Client-defined custom properties associated with the topic. | | data | autoBackfill | Boolean | Indicates whether automatic backfill is enabled for the topic. | | errors | N/A | Array | List of errors encountered during request processing. | | errors | id | String | Unique identifier associated with the error record. | | errors | code | Integer | HTTP-style error code indicating the error type. | | errors | message | String | Detailed description of the error. | ### 6.4 Get Topics by ID: More Than 50 IDs #### **Request Parameters** | **Parameter** | **Sub-parameter** | **Location** | **Required** | **Type** | **Description** | | --- | --- | --- | --- | --- | --- | | id | N/A | Query Parameter | Yes | String | Comma-separated list of Listening Topic identifiers to retrieve. A maximum of **50 Topic IDs** can be provided in a single request. Requests containing more than 50 IDs return a validation error. | | Accept | N/A | Header | Recommended | String | Specifies the expected response format. Supported value: application/json. | | Authorization | accessToken | Header | Yes | String | OAuth bearer token used to authenticate the API request. Format: Bearer {{accessToken}}. | | Key | apiKey | Header | Yes | String | API key used to authenticate the calling application. | #### **Examples Request** ```bash curl --location --globoff '{{baseUrl}}/api/v3/listening/topic?id=id1%2Cid2%2Cid3%2Cid4%2Cid5%2Cid6%2Cid7%2Cid8%2Cid9%2Cid10%2Cid11%2Cid12%2Cid13%2Cid14%2Cid15%2Cid16%2Cid17%2Cid18%2Cid19%2Cid20%2Cid21%2Cid22%2Cid23%2Cid24%2Cid25%2Cid26%2Cid27%2Cid28%2Cid29%2Cid30%2Cid31%2Cid32%2Cid33%2Cid34%2Cid35%2Cid36%2Cid37%2Cid38%2Cid39%2Cid40%2Cid41%2Cid42%2Cid43%2Cid44%2Cid45%2Cid46%2Cid47%2Cid48%2Cid49%2Cid50%2Cid51' \\ --header 'Accept: application/json' \\ --header 'Authorization: Bearer {{accessToken}}' \\ --header 'Key: {{apiKey}}' ``` #### **Examples Response** ```json { "errors": \[ { "id": "6995a283f58d8b601be9ebed", "code": 400, "message": "Maximum of 50 listening_topic identifiers supported per request. Provided: 51. Consider splitting you request in batches of 50 identifiers per request" } \] } ``` #### **Response Parameters** | **Parameter** | **Sub-parameter** | **Type** | **Description** | | --- | --- | --- | --- | | errors | N/A | Array | List of errors encountered during request processing. No topic data is returned when the request exceeds the maximum supported number of Topic IDs. | | errors | id | String | Unique identifier associated with the error record. | | errors | code | Integer | Error code indicating the type of validation failure. | | errors | message | String | Detailed description of the validation error, including the maximum supported limit and the number of identifiers provided. | ## 7. Update a Topic Group Updates an existing resource using its unique identifier. ### 7.1 Endpoint Shown in the Source Example ```http PATCH https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup/?id={id} ``` ### 7.2 Query Parameter | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `id` | String | Yes | Unique identifier of the Topic Group to update. | ### 7.3 Request Body | Parameter | Sub-parameter | Type | Required | Description | | --- | --- | --- | --- | --- | | `name` | N/A | String | No | Updated name of the Topic Group. | | `description` | N/A | String | No | Updated description of the Topic Group. | ### 7.4 Example Request ```bash curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/listening/topicGroup/?id=' \ --header 'Authorization: Bearer ' \ --header 'Key: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "Renamed Group", "description": "Updated description" }' ``` ### 7.5 Response ```http HTTP/1.1 204 No Content ``` A successful update returns no response body. ## 8. Delete a Topic Deletes a Listening Topic by its unique identifier. ### 8.1 Endpoint Shown in the Source Example ```http DELETE /api/v3/listening/topic/?id= ``` ### 8.2 Request Parameters | Parameter | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | Query | String | Yes | Unique identifier of the Listening Topic to delete. | | `Authorization` | Header | String | Yes | Bearer token used to authenticate the request. | | `Key` | Header | String | Yes | API key used to authorize access. | ### 8.3 Example Request ```bash curl -X DELETE '/api/v3/listening/topic/?id=' \ -H 'Authorization: Bearer ' \ -H 'Key: ' ``` ### 8.4 Response ```http HTTP/1.1 204 No Content ``` A successful deletion returns no response body. ## 9. Bulk Transfer Topics to a Topic Group Moves one or more Listening Topics from their current Topic Groups to a destination Topic Group in a single request. ### 9.1 Endpoint ```http POST /api/v3/listening/topic/topicGroup/bulk-transfer ``` ### 9.2 Request Body | Parameter | Sub-parameter | Type | Required | Description | | --- | --- | --- | --- | --- | | `topicIds` | N/A | Array | Yes | Topic IDs to transfer. | | `topicIds` | `item` | String | Yes | Unique identifier of an individual topic. | | `destTopicGroupId` | N/A | String | Yes | Unique identifier of the destination Topic Group. | ### 9.3 Example Request ```bash curl -X POST '/api/v3/listening/topic/topicGroup/bulk-transfer' \ -H 'Authorization: Bearer ' \ -H 'Key: ' \ -H 'Content-Type: application/json' \ -d '{ "topicIds": ["", ""], "destTopicGroupId": "" }' ``` ### 9.4 Response ```http HTTP/1.1 204 No Content ``` A successful bulk transfer returns no response body. ## 10. Response Format and Status Codes ### 10.1 Create Topic Response Envelope The Create Topic operation returns a `data` object and an `errors` array. ```json { "data": { "id": "" }, "errors": [] } ``` ### 10.2 No-content Responses The update, delete, and bulk-transfer operations return the following success response: ```http HTTP/1.1 204 No Content ``` ### 10.3 Documented Status Codes | HTTP status | Scenario | Description | | --- | --- | --- | | `204 No Content` | Successful update, delete, or bulk transfer | The request completed successfully and returned no response body. | The source document does not define API-specific error status codes or error response schemas. Add them only after confirming them against the service contract or OpenAPI specification. ## 11. Use Cases ### 11.1 Create a Listening Topic Create a topic with a query, source list, and collection period to monitor relevant conversations. ### 11.2 Update Topic Group Metadata Change the name or description of an existing Topic Group by supplying its unique identifier. ### 11.3 Delete an Obsolete Topic Delete a Listening Topic that is no longer required by supplying its Topic ID. ### 11.4 Reorganize Topics Move multiple Listening Topics to a destination Topic Group in a single bulk-transfer request.