🚧
Only API keys on our Conversations PRR platform are eligible to use this API version. Refer to the Platforms section of our Platform & API Concepts documentation to learn which platform your API keys are on

Returns Questions along with nested content like Answers and related subjects like Product/Category.

Examples

🚧
Demonstration purposes only. Do not reuse the API passkeys below in your application.

Requesting all questions for a particular product sorted by submission time

This example call shows how to use multiple filters. The questions are sorted in descending order by Submission Time.

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter=Productid:1000001&Filter=Id:14902&Sort=SubmissionTime:desc>

Requesting a question by question ID for a particular product

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter=Id:14902&Filter=Productid:1000001

You can request multiple questions by separating the question IDs with a comma - e.g. filter=id:14801,14802,14902

Requesting a single question by question ID including answers for a particular product

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter=Id:14898&Include=Answers&Filter=Productid:1000001

You can request multiple pieces of related information by separating them with a comma - e.g. include=products,categories,authors.

Requesting 25 questions that have answers, sorted by submission time in descending order for a particular product

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter=HasAnswers:true&Sort=SubmissionTime:desc&Limit=25&Filter=Productid:1000001

You can sort by multiple attributes by separating them with a comma - e.g. sort=id:desc,submissiontime:asc

Requesting all native (non-syndicated) questions

🚧
Native (non-syndicated) content only. Continue reading for more details.

https://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo

Requests for this content type that do not include a ProductId, AuthorId, CategoryAncestorId, SubmissionId, or Question Id filter will only work with API keys that are configured to exclude syndicated content.

We recommend using our Displayable Content Export service to download all of your native and syndicated content. If you still prefer the Conversations API, then you may contact our support team to have your Conversations API keys re-configured.

Parameters

Name	Description	Required	Default Value
`ApiVersion`	The API version, e.g. 5.4.	Yes
`[FORMAT]`	Response format ( xml This feature will not be available or will behave differently in future versions of the Conversations API. Click for more information. or json)	Yes
`PassKey`	API key is required to authenticate API user and check permission to access particular client's data.	Yes
`Attributes`	Attributes to be included when returning content. For example, if includes are requested along with the &attributes=ModeratorCodes parameter, both the includes and the results will contain moderator codes. In order to filter by ModeratorCode, you must request the ModeratorCodes attribute parameter.	No
`Callback`	Callback function name used with JSONP. Value is a string consisting of the following characters: `a-z,A-Z,0-9,_` (excluding comma). See the JSONP tutorial for more information.	No
`ExcludeFamily`	Boolean flag indicating whether to exclude content from other products in the same family as the requested product. For example, "&filter=productid:eq:1101&excludeFamily=true" limits returned content to just that of product 1101 and not any of the products in the same family. If a value is not defined, content on all products in the family will be returned.	No	False
`Filter`	Filter criteria for primary content of the query. Multiple filter criteria are supported.	No
`Filter_[Type]`	Filtering option for included nested content. TYPE can be any included nested content. e.g. Answers for Questions.	No
`Include`	Related subjects to be included (e.g. Products, Categories, Authors, or Answers).	No	Will only return Questions if not specified
`Limit`	Max number of records returned. An error is returned if the value passed exceeds 100.	No	10
`Limit_TYPE`	Limit option for the nested content type returned. TYPE can be any nested content. e.g. Answers for Questions. An error is returned if the value passed exceeds 20.	No	10
`Locale`	Locale to display Labels, Configuration, Product Attributes and Category Attributes in. The default value is the locale defined in the display associated with the API key.	No
`Offset`	Index at which to return results. By default, indexing begins at 0 when you issue a query. Using Limit=100, Offset=0 returns results 0-99. When changing this to Offset=1, results 1-100 are returned. The maximum supported value is 300000.	No	0
`Search`	Full-text search string used to find UGC. For more information about what fields are searched by default, see the Conversations API page. Note: This invalidates sort options due to the fact that search takes precedence in returned data.	No
`Search_[Type]`	Searching option for included content followed by full-text search string. See the Conversations API page for examples of searching for included data. Note: This invalidates sort options due to the fact that search takes precedence in returned data.	No
`Sort`	Sort criteria for primary content type of the query. Sort order is required (asc or desc). Multi-attribute sorting for each content/subject type is supported.	No
`Sort_[TYPE]`	Sorting option for nested content. TYPE can be any nested content. e.g. Answers for Questions.	No
`Stats`	The type of statistics that will be calculated on included subjects. Available content types are: Reviews, Questions, Answers. Note: Not all statistical content types apply to every possible include.	No

Filter options

Each filter argument specifies the attribute to filter on followed by a comma-separated list of values. For instance, "Filter=Id:eq:3,4" will match Questions with Ids 3 OR 4.
Advanced operators can be used to define filters. For instance, "Filter=Id:gt:50" will match Questions with an Id value greater than 50. All advanced operators are documented on the Conversations API page.
If a filter value contains a comma or a colon, that character needs to be escaped with a backslash (\, or \:). If a filter value contains an ampersand (&), the ampersand must be encoded in the filter value by replacing & with %26.
Multiple filters are allowed as URL parameters in which case filters are AND'ed. For instance, "Filter=ProductId:eq:75&Filter=isfeatured:eq:true" will match all featured Questions for the Product with Id 75.
Time-based filters can be used for SubmissionTime, LastModificationTime and LastModeratedTime. Dates in time-based filters are calculated as the number of seconds since January 1, 1970, 00:00:00 UTC. In a future version, we will be adding support for comparing date/time string values. The following example returns content that was submitted on November 9, 2009: &filter=SubmissionTime:gt:1257746400&filter=SubmissionTime:lt:1257832800

The following table lists the attributes available for filtering.

Name	Description
`Id`	The identifier of the content/subject type.
`AdditionalField\_[FIELD_NAME]`	Additional field to filter by, e.g., filter=AdditionalField_[FIELD_NAME]:eq:[FIELD_VALUE]	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`AuthorId`	The identifier of the author who wrote the content.
`CampaignId`	The identifier of the Campaign associated with the content
`CategoryAncestorId`	The identifier of the Ancestor of the Product Category that the Question was written on. Syndicated content will not be returned when using this filter.
`CategoryId`	The identifier of the Product Category that the Question was written on.	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`ContentLocale`	Locale of the content to display. If this filter is not defined, all content regardless of its locale is returned. To return specific content by locale, define the value in the filter. A wildcard character “” can be used to define the value, e.g., “en” returns all content in English (en_US, en_CA, en_GB, etc.) or you can use a single ContentLocale code (e.g., “fr_FR”). ContentLocale codes are case-sensitive.
`ContextDataValue_[DIMENSION_EXTERNAL_ID]`	The context data value for the content. DIMENSION_EXTERNAL_ID can be age, gender, etc. e.g. filter=contextdatavalue_age:under21	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`HasAnswers`	Boolean flag indicating whether the question has answers.
`HasBestAnswer`	Boolean flag indicating whether the question has a best answer.
`HasBrandAnswers`	Boolean flag indicating whether the question has at least one brand answer.
`HasPhotos`	Boolean flag indicating whether content has photos
`HasStaffAnswers`	Boolean flag indicating whether the question has staff answers.
`HasTags`	`HasTags`	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`HasVideos`	Boolean flag indicating whether content has videos. For more information on inserting the returned VideoUrl into HTML, see the Conversations API page.	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`IsFeatured`	Boolean flag indicating whether content is featured
`IsSubjectActive`	Boolean flag indicating whether the content subject is active
`LastApprovedAnswerSubmissionTime`	The date/time of the latest approved answer submission time. See the Introduction for an example of using advanced operators for filtering.
`LastModeratedTime`	The date/time of the latest moderation of the content. See the Introduction for an example of using advanced operators for filtering.
`LastModificationTime`	The date/time of the latest modification of the content. See the Introduction for an example of using advanced operators for filtering.
`ModeratorCode`	String value indicating the moderator code for rejected content, e.g., &Filter=ModeratorCode:eq:CR returns UGC that contains the CR (Competitor Reference) code. Multiple codes can be entered in a comma-delimited list, e.g., &Filter=ModeratorCode:eq:CS,IU returns UGC with either the CS (Customer Service Complaint) or the IU (Inappropriate/Unusable Content) code. For a list of all Moderator Codes, see the Conversations API page. Note that the ModeratorCodes attribute parameter must be explicitly requested in order to use this filter. See the Parameters section above.
`ProductBrandId`	The value of the external product brand ID. The value is case-insensitive. To return content that doesn't have a brand ID associated with it, set productbrandid:eq:null
`ProductId`	The identifier of the Product that the Question was written on.
`SubmissionId`	Submission identifier assigned to the content when it was initially submitted
`SubmissionTime`	The submission date/time of the content. See the Introduction for an example of using advanced operators for filtering.
`Summary`	Question Summary.
`Tag_[TAG_NAME]`	The tag name to filter by, e.g., filter=tag_[TAG_NAME]:eq:[TAG_VALUE]
`TotalAnswerCount`	The number of answers that the question has.
`TotalFeedbackCount`	Number of feedbacks received
`TotalNegativeFeedbackCount`	Number of negative feedbacks received
`TotalPositiveFeedbackCount`	Number of positive feedbacks received
`UserLocation`	Location of the author

Sort options

Sort order is required (asc or desc). There is no default.
Multi-attribute sorting is supported by using a comma separated list of sort criteria for a content/subject type. e.g. Sort=rating:asc,submissiontime:desc

The following table lists the attributes that are available for sorting.

Name	Description
`Id`	The identifier of the Question.
`AdditionalField_[FIELD_NAME]`	Additional field to sort by, e.g., sort=AdditionalField_[FIELD_NAME]:desc	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`AuthorId`	The Identifier of the author of the question.
`CampaignId`	The identifier of the Campaign associated with the content
`CategoryId`	The identifier of the product category that the Question was written on.	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`ContentLocale`	Locale value of the content
`ContextDataValue_[DIMENSION_EXTERNAL_ID]`	The context data value for the content. DIMENSION_EXTERNAL_ID can be age, gender, etc. e.g. sort=contextdatavalue_age:desc	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`HasAnswers`	Boolean flag indicating whether the Question has answers.
`HasBestAnswer`	Boolean flag indicating whether the Question has a best answer.
`HasPhotos`	Boolean flag indicating whether content has photos
`HasStaffAnswers`	Boolean flag indicating whether the Question has staff answers.
`HasTags`	Boolean flag indicating whether content has tags	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`HasVideos`	Boolean flag indicating whether content has videos. For more information on inserting the returned VideoUrl into HTML, see the Conversations API page.	PRR (This feature is only available to clients on our Conversations PRR platform. Click for more information.)
`IsBestAnswer`	Boolean flag indicating if this answer is the best answer of the question to which it belongs.
`IsFeatured`	Boolean flag indicating whether content is featured
`IsSubjectActive`	Boolean flag indicating whether the content subject is active
`LastApprovedAnswerSubmissionTime`	The date/time of the latest approved answer submission
`LastModeratedTime`	The date/time of the latest moderation of the content
`LastModificationTime`	The date/time of the latest modification of the content
`ProductId`	The identifier of the Product that the Question was written on.
`QuestionId`	Id of the Question on which the Answer was written.
`SubmissionId`	Submission identifier assigned to the content when it was initially submitted
`SubmissionTime`	The submission date/time of the content
`Summary`	Summary of the question
`TotalAnswerCount`	The number of Answers that have been written to the Questions.
`TotalFeedbackCount`	Number of feedbacks received
`TotalNegativeFeedbackCount`	Number of negative feedbacks received
`TotalPositiveFeedbackCount`	Number of positive feedbacks received
`UserLocation`	Location of the author

Response format

This is the response for Requesting all Questions that have Answers. The Answers data is also included in the response.

http://[stg.]api.bazaarvoice.com/data/questions.json?ApiVersion=[latestApiVersion]&passkey=[yourKey]&Filter=HasAnswers:true&Include=Answers,Products&Sort=SubmissionTime:desc

{
    "Includes": { },
    "HasErrors": false,
    "Offset": 200,
    "TotalResults": 2320,
    "Locale": "en_US",
    "Errors": [ ],
    "Results": [
        {
            "QuestionSummary": "Take the monarch butterfly,",
            "TagDimensions": {
                "Topic": {
                    "Values": [
                        "Topic 2",
                        "Example of wordy topic value"
                    ],
                    "Label": "Topic",
                    "Id": "Topic"
                }
            },
            "TagDimensionsOrder": [
                "Topic"
            ],
            "AdditionalFieldsOrder": [ ],
            "TotalAnswerCount": 0,
            "QuestionDetails": "In this group are the shads and the alewives or river herrings, the white perch, the striped bass or rock fish, some of the sturgeons, and the Atlantic salmon, all of which go back to sea after spawning, and the Pacific salmons (five species), all of which die after spawning.\n\nOf the catadromous fishes there is a single example in our waters--the common eel.",
            "UserNickname": "2hTZ",
            "Photos": [
                {
                    "Caption": null,
                    "Sizes": {
                        "thumbnail": {
                            "Url": "http://testcustomer.ugc.bazaarvoice.com/answers/0001/170860/photoThumb.jpg",
                            "Id": "thumbnail"
                        },
                        "normal": {
                            "Url": "http://testcustomer.ugc.bazaarvoice.com/answers/0001/170860/photo.jpg",
                            "Id": "normal"
                        }
                    },
                    "SizesOrder": [
                        "thumbnail",
                        "normal"
                    ],
                    "Id": "170860"
                }
            ],
            "CategoryId": null,
            "ContextDataValues": { },
            "Videos": [ ],
            "ContextDataValuesOrder": [ ],
            "SubmissionId": null,
            "LastModificationTime": "2011-10-12T14:32:32.000-00:00",
            "AnswerIds": [ ],
            "TotalFeedbackCount": 0,
            "TotalPositiveFeedbackCount": 0,
            "TotalInappropriateFeedbackCount": 0,
            "InappropriateFeedbackList: [ ],
            "UserLocation": "N",
            "BadgesOrder": [
                "top250Contributor"
            ],
            "Badges": {
                "top250Contributor": {
                    "Id": "top250Contributor",
                    "ContentType": "QUESTION"
                }
            },
            "AuthorId": "data-gen-user-b82iyxmi2k4a8lxcaamzzyh4w",
            "IsFeatured": false,
            "ProductRecommendationIds": [ ],
            "ProductId": "data-gen-puzri1hax8074pba42wq1hqes",
            "AdditionalFields": { },
            "CampaignId": null,
            "TotalNegativeFeedbackCount": 0,
            "SubmissionTime": "2011-10-12T14:12:12.000-00:00",
            "ContentLocale": "en_US",
            "ModerationStatus": "APPROVED",
            "Id": "305209",
            "LastModeratedTime": "2011-10-12T14:20:23.000-00:00"
        }
    ],
    "Limit": 1
 
}

Response elements

Name	Description
`Data`	Section containing all the data matched by a query grouped by content/subject type. Within each data section there is a map of objects keyed by ids
`Errors`	Error section is populated instead of other fields if there is an error with a query syntax or problem executing a query.
`Limit`	The total number of results returned, specified by user in the URL. Defaults to 10 and has a maximum of 100.
`Offset`	Dataset offset used for pagination (passed as URL parameter in a query request). The maximum supported value is 300000.
`Results`	Section containing an array of primitive type object references matched by a query.
`TotalResults`	Total number of records matched.

Error codes

Value	Description
`ERROR_ACCESS_DENIED`	Insufficient privileges to perform the operation
`ERROR_PARAM_INVALID_API_KEY`	Invalid API Key value
`ERROR_PARAM_INVALID_CALLBACK`	Invalid JsonP callback function name
`ERROR_PARAM_INVALID_FILTER_ATTRIBUTE`	Invalid filter attribute name
`ERROR_PARAM_INVALID_INCLUDED`	Invalid parameter value
`ERROR_PARAM_INVALID_LIMIT`	Invalid limit value
`ERROR_PARAM_INVALID_LOCALE`	Invalid locale code
`ERROR_PARAM_INVALID_OFFSET`	Invalid offset value
`ERROR_PARAM_INVALID_SORT_ATTRIBUTE`	Invalid sort attribute name
`ERROR_REQUEST_LIMIT_REACHED`	Rate limiting error, i.e. too many requests per time interval
`ERROR_UNKNOWN`	Unknown error (internal server error, for instance)
`ERROR_UNSUPPORTED`	For unsupported features, clients etc.

Questions Display

🚧
Only API keys on our Conversations PRR platform are eligible to use this API version. Refer to the Platforms section of our Platform & API Concepts documentation to learn which platform your API keys are on

Examples

🚧
Demonstration purposes only. Do not reuse the API passkeys below in your application.

Requesting all questions for a particular product sorted by submission time

Requesting a question by question ID for a particular product

Requesting a single question by question ID including answers for a particular product

Requesting 25 questions that have answers, sorted by submission time in descending order for a particular product

Requesting all native (non-syndicated) questions

🚧
Native (non-syndicated) content only. Continue reading for more details.

Parameters

Filter options

Sort options

Response format

Response elements

Error codes

🚧Only API keys on our Conversations PRR platform are eligible to use this API version. Refer to the Platforms section of our Platform & API Concepts documentation to learn which platform your API keys are on

Examples

🚧Demonstration purposes only. Do not reuse the API passkeys below in your application.

Requesting all questions for a particular product sorted by submission time

Requesting a question by question ID for a particular product

Requesting a single question by question ID including answers for a particular product

Requesting 25 questions that have answers, sorted by submission time in descending order for a particular product

Requesting all native (non-syndicated) questions

🚧Native (non-syndicated) content only. Continue reading for more details.

Parameters

Filter options

Sort options

Response format

Response elements

Error codes

🚧
Only API keys on our Conversations PRR platform are eligible to use this API version. Refer to the Platforms section of our Platform & API Concepts documentation to learn which platform your API keys are on

🚧
Demonstration purposes only. Do not reuse the API passkeys below in your application.

🚧
Native (non-syndicated) content only. Continue reading for more details.