This document lists changes between Conversations API versions.


The following changelogs reference features which are only available to clients on our Conversations PRR platform. Refer to Conversations PRR Only Features for more information.

v5.4 (Conversations)

Refer to 5.4 Conversations PRR & 5.4 Conversations to learn more about the two 5.4 API versions

Platform Conversations
Released 2016-08-29
  • XML response type no longer supported

        All requests must use .json.

  • No "bulk requests" when syndication in enabled

        If syndication is enabled on a key, requests using that key must always pass a single ProductId, ReviewId,         AuthorId, or AncestorCategoryId as appropriate.

  • Added properties to products.json response

    • "active": true|false
    • "disabled": true|false
  • New search engine

        Search results will be faster, more useful, and may not be identical to search performed in previous versions.

  • Legacy features

        All features documented at Legacy Platform Features are no longer supported.

  • Review search

        Will only work with requests filtered by one product ID.

  • Fixed duplicate badging issue

        In cases where content and author have the same badge, only one badge will be returned.

  • Reduced Question & Answer stats response

        The left side of the graphic diff below shows the response from the previous version of the API and the right         shows the current response.


The above diff has been ordered to make comparison easier. You should not rely on the order of elements in the API response.

  • Removed support for following fields, filters and sorts
Review Display
  • Search_[INCLUDE_TYPE]
  • filter=HasComments
  • sort=HasComments
  • filter=ProductBrandId
Comment Display
  • Search
  • Search_[CONTENT_TYPE]
  • Stats
  • sort=StoryId
  • filter=StoryId
Question Display
  • Search_[CONTENT_TYPE]
  • filter=AdditionalField_[DIMENSION_ID]
  • sort=AdditionalField_[DIMENSION_ID]
  • filter=CategoryId
  • sort=CategoryId
  • filter=ContextDataValue_[DIMENSION_ID]
  • sort=ContextDataValue_[DIMENSION_ID]
  • filter=HasBrandAnswers
  • sort=HasBrandAnswers
  • filter=HasTags
  • sort=HasTags
  • filter=HasVideos
  • sort=HasVideos
  • filter=ProductBrandId
  • filter=Tag_[TAG_NAME]
  • sort=Tag_[TAG_NAME]
Answer Display
  • Search
  • Search_[CONTENT_TYPE]
  • filter=AdditionalField_[DIMENSION_ID]
  • sort=AdditionalField_[DIMENSION_ID]
  • filter=Affiliation
  • sort=Affiliation
  • filter=CategoryId
  • sort=CategoryId
  • filter=ContextDataValue_[DIMENSION_ID]
  • sort=ContextDataValue_[DIMENSION_ID]
  • filter=HasVideos
  • sort=HasVideos
Profile Display
  • filter=LastAnswerTime
  • sort=LastAnswerTime
  • filter=LastCommentTime
  • sort=LastCommentTime
  • filter=LastReviewTime
  • sort=LastReviewTime
  • filter=LastQuestionTime
  • sort=LastQuestionTime
  • filter=LastStoryTime
  • sort=LastStoryTime
  • filter=TotalCommentCount
  • sort=TotalCommentCount
  • filter=TotalStoryCount
  • sort=TotalStoryCount
Product Display
  • Search_[CONTENT_TYPE]
  • filter=LastAnswerTime
  • sort=LastAnswerTime
  • filter=LastCommentTime
  • sort=LastCommentTime
  • filter=LastReviewTime
  • sort=LastReviewTime
  • filter=LastQuestionTime
  • sort=LastQuestionTime
  • filter=RatingsOnlyReviewCount
  • sort=RatingsOnlyReviewCount
  • filter=TotalStoryCount
  • sort=TotalStoryCount
Category Display
  • Include
  • Limit_[CONTENT_TYPE]
  • Search
  • Search_[CONTENT_TYPE]
  • Stats
  • filter=LastAnswerTime
  • sort=LastAnswerTime
  • filter=LastQuestionTime
  • sort=LastQuestionTime
  • filter=LastStoryTime
  • sort=LastStoryTime
  • filter=TotalAnswerCount
  • sort=TotalAnswerCount
  • filter=TotalQuestionCount
  • sort=TotalQuestionCount
  • filter=TotalStoryCount
  • sort=TotalStoryCount

v5.4 (PRR)

Refer to 5.4 Conversations PRR & 5.4 Conversations to learn more about the two 5.4 API versions

Platform PRR
Released 2013-01-14
  • Submission forms pre-filled for non-anonymous users

        When submitting content, the values of all known submission fields are now returned in the submission         response fields. This only affects submissions where the user is not anonymous and the user/userid parameter         is provided with the GET request.

  • Full text search on all UGC and on includes

    The following content types were added to the existing search capabilities:

    • reviews
    • answers
    • comments(review)
    • stories

       All content is now searchable. For a list of all the fields that are searched for any given content type, see full text        searching documentation on the API Basics page.

  • Product family queries

        When filtering by product id, all content from that product's product family is also returned by default. There is         a new excludeFamily parameter that you can set to not return product family content. For examples and full         documentation, see the Product Display method page.

Products display request using the excludeFamily paramete

 Filtered results excluding reviews for others products in the family:>? apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=id:test1&excludeFamily=true&include=reviews
  • Photo upload accepts URLs

       The uploadphoto endpoint now accepts HTTP URLs of images in addition to locally stored photos from the         client side. For examples and full documentation, see the Photo Submission method page.

  • Brightcove Smart Player Javascript integration

        Brightcove videos can be loaded in a variety of ways. The information necessary to load these videos in the         browser is now returned in the Videos block of the response elements. See the API Basics page for details on         the new response items that were added to support Brightcove videos.

  • Story rating field exposed in the response

        The story display response has a new block called "StoryRating" that contains two fields:

  • Average score - average of the rating feedback score displayed for each story ID
  • Range - range of the average score
Average Score and Range fields, JSON

API version 5.3                                                                API version 5.4

Average Score and Range fields, XML

API version 5.3                                                                API version 5.4

  • Special product attributes exposed in the response

The product display response has new fields for each of the following five product attributes:

  1. EANs
  2. UPCs
  3. ISBNs
  4. ModelNumbers
  5. ManufacturerPartNumbers
  • New filtering capabilities

        The following new filters are available:

  1. Affiliation badge filter on reviews
  2. Brand answer filters on questions and answers
  3. Product brand ID filter for reviews, stories, and questions
  4. Product brand ID filter for products
  5. Content locale filter inline ratings (statistics.json)
Filtering Review Display where Affiliation Badge is "staff">?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter:affiliation:staff
Filtering using boolean brand answer for a Question request and an Answer request
Filtering using Product Brand ID for Review request
Filtering using Product Brand ID for Product request
Filtering using Content Locale for Statistics request,Reviews&filter=contentlocale:eq:en\_US,es\_MX,en\_CA

v5.3 (PRR)

Platform PRR
Released 2012-08-03
  • Hosted authentication - email
    Hosted email authentication can be used during submission to confirm the identity of a content submitter. When submitting content for the first time, a user receives an email containing a link. When the link is clicked,  the user is directed to a landing page that calls back to the API to confirm their identity. This call results in the generation of an encrypted user token that can be used in subsequent submission calls. Depending on your configuration, the submitter's content might not be accepted until the confirmation call is submitted. In order to use this feature, you must have hosted authentication enabled for your submission process. If you need more information, read the "Bazaarvoice hosted authentication reference guide" and the submission method documentation for details on the required parameters.

  • Feedback submission for comments

       Feedback submission for review comments and story comments is now supported in addition to the existing        support for feedback submission on reviews, questions, answers, and stories. For complete documentation, see        the Feedback Submission method page.

  • RatingDistribution and SecondaryRatingsAverages added to review statistics

       New RatingDistribution and SecondaryRatingsAverages blocks have been added to the ReviewStatistics block.        You can now see the distribution of ratings for each product, which allows you to construct a rating histogram.        You can also see the average rating of your secondary rating dimensions for reviews in relation to products and        authors.

Rating Distributions JSON

API version 5.2                                                         API version 5.3

Rating Distributions XML

API version 5.2                                                       API version 5.3

  • Error codes added to form errors

        The API response has been updated to return error codes in addition to the existing error message for all form         errors. A complete listing of the error codes can be found in each submission method.

JSON error code sample
XML error code sample

API version 5.2                                                        API version 5.3

  • Syndication attribution on reviews

       All reviews have an "isSyndicated" field set to true or false. If the review is syndicated, a SyndicationSource        block is displayed with details of where the review is being syndicated from. Syndicated content can only be        returned if the API key is configured to show syndicated content.

JSON Response sample

Syndication enabled                                                      Syndicated disabled

v5.2 (PRR)

Platform PRR
Released 2012-06-01
  • Helpfulness and inappropriate feedback

       Submission of helpfulness votes and inappropriate feedback can now be done through the API. The        response for the user-generated content has also been updated to display the actual inappropriate feedback and        total vote and feedback counts. In order for inappropriate feedback to be populated, the API key must be               updated.

  • Implicit default ContentLocale filter removed

        There is no longer any implicit ContentLocale filter if none is specified as an argument. If no filter is provided, all          content will be returned, regardless of what locale the content is in. There is a default locale defined for every          API key. Prior to version 5.2, if the locale parameter was used, it caused an implied ContentLocale filter to be          used. Note that version 5.2 does not change the behavior of explicitly supplied ContentLocale filters. In          addition, you can now ask for labels in any locale and specify a different content locale. Therefore, if you          request a locale of en_US and a ContentLocale of fr_FR, you get English labels and French content.

  • Product and category attributes

        Products and categories now have a new attributes field populated. This field contains a map of attributes                  provided to Bazaarvoice from a product feed import.

  • Hosted video submission and display

        Video elements of all content now contain URLs that can be used to embed the video into an HTML page.          Bazaarvoice provides boilerplate HTML tags for use with embedding these videos. For more information, see          the API Basics page.

  • Inline ratings data

        A new method has been created to provide a quick way to access inline ratings data for products. For complete         documentation, see the Statistics Display method page.

v5.1 (PRR)

Platform PRR
Released 2012-02-14
  • ReviewStats

        Review statistics for Products now returns ReviewStats, which account for product family data in the statistics         calculations. Prior to version 5.1, the ReviewStats were returning NativeStats, which do not take product families         into account.

JSON Response sample

API version 5.0                                                              API version 5.1

XML Response sample

API version 5.0                                                               API version 5.1

  • Moderator Codes

       Moderator codes (content codes) can now be explicitly requested and filtered. A new filter (ModeratorCode) has        been added and can accept any moderator code values. For a list of all moderator codes, see API Reference        section. In addition, a new value for the attribute parameter (ModeratorCodes) has been added. Filtered        results will be returned if only the filter is added. Including the ModeratorCodes attribute along with thefilter        will both filter the results and expose the moderated codes.

Review requests filtered on Moderator Codes

Filters results for moderated code

Filters results for moderated code and while displaying the codes

  • Wildcard character in ContentLocale filter

        The ContentLocale filter now accepts the asterisk (‘*’) as a wildcard character. This wildcard character          represents zero or more characters. Adding the wildcard enables filtering for multiple locales without requiring          each one to be listed. For example, &Filter=ContentLocale:eq:en* would return all the English locales (en_US,          en_CA, en_GB, etc.). When the ContentLocale filter is set to the wildcard character, it is the equivalent of          requesting all locales. It is important to note that the value of the filter cannot start with a wildcard filter. For          example, &Filter=ContentLocale:eq:*_US is not a valid filter.

  • IP address in Content Display

       When the API key is configured to allow access to IP addresses, you will either get the IP address back or null         inside the IpAddress element. If you are interested in getting access to IP address within an application, contact         technical support.

v5.0 (PRR)

Platform PRR
Released 2011-10-11
  • Results XML changes

        In the XML response, the Results element has dropped the list of containing element         (Reviews/Comments/Stories) and now includes the content elements directly.

  • SecondaryRatings changed

       SecondaryRatings/RatingValue is renamed to SecondaryRatings/SecondaryRating. SecondaryRating/Rating is         renamed to SecondaryRating/Value. SecondaryRating/Label is renamed to SecondaryRating/ValueLabel.         SecondaryRating/Label1 is renamed to SecondaryRating/MinLabel. SecondaryRating/Label2 is renamed to         SecondaryRating/MaxLabel. SecondaryRating/Label is now returned as the label of the SecondaryRating         dimension. The JSON response returns a Map of SecondaryRating elements instead of an array.

JSON Response sample

API version 4.9                                                                 API version 5.0

XML Response sample

API version 4.9                                                                API version 5.0

  • ContextDataValues changed

       Context Data Values are flipped inside-out and flattened in the XML format. The JSON format includes label         information.

  • Badges changed

        Badge/Name is renamed to Badge/Id and Badges are returned as a map instead of an array in JSON.

JSON Response sample

API version 4.9                                                              API version 5.0

XML Response sample

API version 4.9API version 5.0

  • "Order" arrays in JSON response included

       For each "Lists" of elements that are returned as a map instead of an array in JSON (Includes/*,                ContextDataValues, AdditionalFields, SecondaryRatings, TagDimensions, ...) an array with the same name as the        map with "Order" added as a suffix is returned with the original order of the elements in the list.

JSON Response sample

API version 4.9                                                              API version 5.0

  • Nulls in the JSON responses

       The JSON response now returns a value for all fields possible. If a value is not explicitly set, a null value is         returned ([] for JSON array types, {} for JSON object types, null for primitive types).

  • Submission format changed

        The XML format has been flattened to match the JSON format more closely.

  • UserNickname returned for Reviews

        UserNickname is now returned for Reviews.

JSON Response sample

API version 4.9                                                               API version 5.0

XML Response sample

API version 4.9                                                              API version 5.0

  • DisplayLocale is renamed to ContentLocale

       When querying for content (Reviews, Stories, Questions, Answers, ReviewComments, StoryComments) the        default behavior in 5.0 (4.9 remains unchanged) is to now return only content in the locale requested (default or        specified). This can be overriden to return content for a specific locale by using the contentlocale filter attribute.        The special value "all" for the contentlocale filter returns content in all locales. *Note that Authors the behavior         remains unchanged and all Authors are returned by default, regardless of their locale.

ContentLocale used for filtering Reviews

Returns content for all locales

Returns content for 'en_US'\_US

Returns content for locales not equal to 'en_US'\_US

Returns content for default local, in this case 'en_US'
  • Locale parameter now available

       Both query and submission API now accept the new 'locale' top-level parameter to get Labels, Configuration,         Product Attributes, Category Attributes in that locale. Note that the particular locale has to have been         configured or the response will be ERROR_PARAM_INVALID_LOCALE

  • User token no longer needed for submission

        The cleartext user id parameter ("userid") can be used to as part of submission.

  • Campaign ID is now returned in repsonses

        Campaign ID is now returned as part of the XML/JSON response for all appropriate content types.

JSON Response sample

API version 4.9                                                              API version 5.0

XML Response sample

API version 4.9                                                              API version 5.0

  • Advanced Operators

       Advanced operators are supported. The following is a list of the supported operators (gt, gte, lt, lte, eq, and neq)

Review Display request filtering on ratings less than 3
Table view detailing advanced operators
OperatorDescriptionAllowable Field TypesExample
gtgreater than (>)numeric fieldsfilter=rating:gt:4
gtegreater than or equal to (>=)numeric fieldsfilter=rating:gte:4
ltless than (<)numeric fieldsfilter=rating:lt:4
lteless than or equal to (<=)numeric fieldsfilter=rating:lte:4
eqequal to (==)numeric, boolean or string fieldsfilter=rating:eq:4 or filter=rating:4 (supported for backward comapatibility)
neqnot equal to (!=)numeric, boolean or string fieldsfilter=rating:neq:4
  • More filter and sort fields

       Additional filters and sorts is now supported for "Tags", "Secondary Ratings", "Additional Fields", "Campaign ID",        "TimeStamps"

v4.9 (PRR)

Platform PRR
Released 2011-08-0

The 4.9 release is considered the first release out of BETA. There are too many API changes to document them all. The following are some of the more significant changes from the previous development release.

  • Renamed "Data" element to "Includes"

       To be more consistent with the name of the "includes" request parameter, we are renamed the "data" response          element to "includes" and denormalized the results section of the response.

  • Renamed various fields

       To be more consistent we have renamed various fields to conform to our naming convention.

  • IsFeatured returned for supported content types

        IsFeatured is now returned for Answers, Questions and Stories

  • ProductReferences renamed

        ProductReferences are renamed to ProductRecommendationIds and now only includes the Id for the products          being recommended instead of the entire Product Definition inline.

  • Tags content was flattened

        Responses in tags content was shortened

  • RatingValues renamed

       RatingValues renamed to SecondaryRatings and structure flattened

  • Submission Fields renamed

       Submission fields were renamed to match query response fields and to conform to our naming convention

  • Display Code removed from URL

       The display code is no longer part of the Data API URL.

  • Comment URL Changes

       Comments are now accessible as either Review Comments or Story Comments. This changed on the query URL        changes, the submission URL changes, and the media upload URL