Overview

The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.

This page contains general information about the Conversations API that applies to all versions.

Versions

• Version 5.4 (Conversations)

  The latest API version for clients on our Conversations platform. Refer to Platforms to learn more.

• Version 5.4 (PRR)

  The latest API version for clients on our PRR platform. Refer to Platforms to learn more.

CGC Content Types

The Conversations API allows display access to the following:

• Content types
  • Reviews
  • Review Comments
  • Questions
  • Answers
• Subject types
  • Products
  • Product Categories
• Content Authors

The API allows submission to the following:

• Content types
  • Reviews
  • Review Comments
  • Questions
  • Answers
  • Photos
  • Videos PRR

Display Request Format

The same general request format applies to queries for all data types.

http://[stg.]api.bazaarvoice.com/data/[TYPE].[FORMAT]
?passkey=[yourPassKey]
&ApiVersion=[latestApiVersion]
&Include=[TYPE],...,[TYPE]
&Filter=[ATTRIBUTE_NAME]:[ATTRIBUTE_VALUE],...,[ATTRIBUTE_VALUE]*
&Filter_[TYPE]=[ATTRIBUTE_NAME]:[ATTRIBUTE_VALUE],...,[ATTRIBUTE_VALUE]*
&Sort=[ATTRIBUTE_NAME]:[asc|desc],...,[ATTRIBUTE_NAME]:[asc|desc]
&Sort_[TYPE]=[ATTRIBUTE_NAME]:[asc|desc],...,[ATTRIBUTE_NAME]:[asc|desc]
&Search=[SEARCH_TEXT]
&Search_[TYPE]=[SEARCH_TEXT]
&Offset=[OFFSET_VALUE]
&Limit=[LIMIT_VALUE]
&Limit_[TYPE]=[TYPE_LIMIT_VALUE]
&Callback=[CALLBACK_FUNCTION_NAME]

While querying for Products, Categories, and Authors, an additional parameter is supported

&Stats=[TYPE],...,[TYPE]

Display Parameter Notes

• The parameter names and values are all case-insensitive
• Commas or colons within a filter value must be escaped with a backslash (\, or \:) and that backslash must be percent encoded. For example, when percent encoded would be %5C
• Ampersands (&) within a filter value must be percent encoded. For example, when percent encoded & would be %26
• Any date/time returned by the API is displayed in Coordinated Universal Time (UTC) format
• Advanced operators are supported on filters. The following table lists the supported operators and describes their usage:

  Operator	Description	Allowable Field Types	Example
  gt	greater than (>)	numeric fields	filter=rating:gt:4
  gte	greater than or equal to (>=)	numeric fields	filter=rating:gte:4
  lt	less than (<)	numeric fields	filter=rating:lt:4
  lte	less than or equal to (<=)	numeric fields	filter=rating:lte:4
  eq	equal to (==)	numeric, boolean or string fields	filter=rating:eq:4 or filter=rating:4 (supported for backward comapatibility)
  neq	not equal to (!=)	numeric, boolean or string fields	filter=rating:neq:4

• The REQUIRED parameter TYPE is used to specify the Object (Content/Subject/Author) type to be returned, where TYPE = reviews|questions|answers||comments|authors|products|categories
• The REQUIRED parameter FORMAT is used to specify the response format, where FORMAT = json|xml
• The OPTIONAL parameter Callback is only available for the json response format. See Cross-domain requests section below for more details.
• The parameters, responses, and error codes for each Object are listed on the Object's spec page.

Submission Request Format

The same general request format applies to queries for all data types.

API endpoint:

http://[stg.]api.bazaarvoice.com/data/submit[TYPE].[FORMAT]

POST body (basic example for reviews):

?PassKey=[yourKey]
&ApiVersion=[latestApiVersion]
&ProductId=[productId]
&Action=[action]
&Rating=[rating]
&ReviewText=[reviewText]
&Title=[title]
&UserNickname=[nickname]

Submission Parameter Notes

• The parameter names and values are all case-insensitive
• The REQUIRED parameter TYPE is used to specify the content type to be submitted, where TYPE = review|question|answer||reviewcomment|
• The REQUIRED parameter FORMAT is used to specify the response format, where FORMAT = json|xml
• The parameters, responses, and error codes for each TYPE are listed on each TYPE's spec page
• The OPTIONAL parameter Callback is only available for preview requests (using HTTP GET) and using the json response format. See Cross-domain requests section below for more details.
• The Action parameter combined with HTTP GET or POST determines the how the Bazaarvoice platform will respond:

  Action	Description	HTTP Method
  Action=	Response represents fields necessary to create a submission form. The Action parameter is optional for this operation.	GET, POST
  Action=Preview	Used to validate a submission. Response will include errors on failure. Data will not be stored.	GET, POST
  Action=Submit	On success data will be stored and response will include a submission ID. On failure response will contain errors.	POST

  Action=Submit may occur without first performing Action= and Action=Preview.

Response Formats

Response Format for Display

{
    "Results": [
           {
               "[NAME]": "[VALUE]"
                ...
           },
           ...
    ],
    "Includes": {
           "[TYPE]": {
               "[ID]": {
                   "[NAME]": "[VALUE]"
                   ...
               }
           }
    },
    "HasErrors": [TRUE|FALSE]
    "Offset": [OFFSET]
    "LIMIT": [LIMIT]
    "TotalResults": [TOTAL_RESULTS]
}

Response Format for Errors

{
    "Error": {
        "Code": "[ERROR_CODE]",
        "Message": "[ERROR_MESSAGE]"
    }
}

The following HTTP response codes are used:

The following error codes are used:

Response Format for Submission

{
   "[CONTENT_TYPE]":{
      "[NAME]":"[VALUE]",
      ...
   },
   "Data":{
      "Field":{
         "[FIELD_NAME]":{
            "[FIELD_ATTRIBUTE_NAME]":"[FIELD_ATTRIBUTE_VALUE]",
            ...
         },
         ...
      },
      "Group":{
         "[GROUP_NAME]":{
            "[GROUP_ATTRIBUTE_NAME]":"GROUP_ATTRIBUTE_VALUE",
            ...
            "SubElements":[
               {
                  "Type":"[GROUP_SUBELEMENT_TYPE]",
                  "ID":"[GROUP_SUBELEMENT_VALUE]"
               },
               ...
            ]
         },
        ...
      }
   },
   "FormErrors": {
        "FieldErrors": {
            "[FIELD_ID]" : "[ERROR_MESSAGE]",
            ...
        }
    },
   "Form":[
      {
         "Type":"[TYPE]",
         "ID":"[ID]"
      },
      ...
   ],
   "TypicalHoursToPost":[TYPICAL_HOURS_TO_POST]
}

Moderator Codes for Content

When content is moderated, specific codes are applied to the content. Starting with version 5.1, you can filter your query using the ModeratorCode filter option. The following standard moderator codes are supported:

• CR (Competitor Reference)
• CS (Customer Service Complaint)
• DBA (Directing Business Away)
• FL (Content in a Foreign Language)
• GIU (Generally Inappropriate Comments)
• IMG (Inappropriate Image)
• INT (Product Accolades)
• LI (Liability Concerns)
• NCR (Neutral Competitor Reference)
• PC (Promotions and Sales)
• PD (Reviewer claims Product Description is somehow inaccurate)
• PF (Product Flaw)
• PII (Personally Identifiable Information)
• PLI (Potential Danger - Liability)
• PRF (Profanity)
• PRI (Price Reference)
• PS (Product Suggestion)
• PUX (Lack of Product Experience)
• RET (Retailer Mention)
• RW (Restricted Words)
• SI (Shipping Issues)
• SPM (Spam or Duplicate Content)
• SR (Staff Rejection)
• UA (Underaged User)
• URL (Presence of URL)
• VAC (Vacuous)
• WP (Wrong Product)

There may also be client-specific codes that can be queried. Refer the Conversations Knowledge base for more information on content moderation.