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.

Contents

(+ show- hide)

This documentation describes the fields that can be submitted using the Bazaarvoice Conversations API using full submission, including information about availability and display recommendations.

This topic applies to full submission only. Information for progressive submission is coming soon.

Introduction

There over 30 different field types exposed by the Conversations API, each with its own semantics, UI expectations and configurations. Many of these field types are customizable, meaning their behavior and properties can be different from client to client.

This documentation provides detailed information about the submittable fields available in Conversations API including:

  • a summary of the field's important properties,
  • a description of the field and how to use it,
  • field availability information,
  • examples of best practice user interfaces along with advice on building them,
  • detailed information about the API interface for each field including responses and HTTP parameters.

A listing of internal fields, explanation of the many factors impacting a field's availability and guidance on how to determine which fields are available is provided in the appendix.

Fields Types

Additional field

AKA: Additional free text field, Free text people question

Description

Platform PRR, Config Hub
Content type Review, Question, Answer , Story
Interface Submission, Display
Input type TextInput, TextAreaInput

Additional fields accept free text. They can be configured to solicit a variety of information from authors. They are very useful for submitting arbitrary data to Bazaarvoice that isn't related to the author (custom IDs, internal tracking numbers, etc.).

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer , Story
Conversations Review
This field type may be configured to be display & submission or submission only.
This field type may be configured to be category dependent.

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                   AdditionalFields": {
                       "FavoriteFood": {
                           "Value": "Pizza",
                           "Label": "Favorite Food",
                           "Id": "FavoriteFood"
                       }
                   },
                  

Because these fields solicit free text answers from authors your UI should accommodate answers of varying lengths.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=AdditionalField_[QuestionID]:[Operator]:[Answer Value]
                  filter=AdditionalField_FavoriteColor:eq:blue
                  
Sort
                  sort=AdditionalField_[QuestionID]:[asc|desc]
                  sort=AdditionalField_FavoriteColor:asc
                  

Submission

User interface

Additional fields can either be represented as text inputs or text areas. This is determined by configuration in the Bazaarvoice platform.

TextInput

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "additionalfield_[QuestionID]": {
                      ....
                  },
                  "additionalfield_FavoriteFood": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 255,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": "What is your favorite food",
                      "Id": "additionalfield_FavoriteFood",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

TextInput additional fields should be sized to discourage users from entering answers longer than about one sentence. These fields will often have a max length consistent with this expectation.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

TextAreaInput

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "additionalfield_[QuestionID]": {
                      ....
                  },
                  "additionalfield_Experience": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 10000,
                      "Required": false,
                      "Type": "TextAreaInput",
                      "Label": "Describe your experience",
                      "Id": "additionalfield_Experience",
                      "Options": [ ],
                      "MinLength": 50
                  },
                  

TextAreaInput additional fields should be sized to encourage users to enter answers that are several sentences to a paragraph in length. These fields will often have a max length consistent with this expectation. Note however, that line breaks will be stripped when stored by Bazaarvoice.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  AdditionalField_[QuestionID]=[Answer Value]
                  AdditionalField_Experience=Proin%20quis%20erat%20facilisis%3B%20tempus%20eros%20in%2C%20tincidunt%20tellus.
                  

The example above is percent encoded.

Agreed to Terms and Conditions

AKA: Opt-in

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission
Input type BooleanInput

This field requires the author to acknowledge their acceptance of your terms and conditions before submission will be accepted.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review, Question, Answer

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "agreedtotermsandconditions": {
                      "Default": null,
                      "MaxLength": null,
                      "Value": "false",
                      "Required": true,
                      "Type": "BooleanInput",
                      "Label": null,
                      "Id": "agreedtotermsandconditions",
                      "MinLength": null,
                      "Options": [ ]
                  },
                  

Be sure to provide your terms and conditions for the author to read.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  agreedtotermsandconditions=true
                  

Campaign ID

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Display, Submission
Input type TextInput

Campaign ID is a text string identifying the action that originated a piece of content. This field is useful for tracking activities intended to promote the submission of content. For example, "API_RR_HOME_PAGE" could indicate an author initiated the review submission process using a link presented by a widget on your home page.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review, Question, Answer, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

User interface
                  "CampaignId": "API_RR_HOME_PAGE",
                  

This field is returned by the API in the format above but should not be displayed to users.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=campaignid:[operator]:[Value]
                  filter=campaignid:eq:API_RR_HOME_PAGE
                  
Sort
                  sort=campaignid:[asc|desc]
                  sort=campaignid:asc
                  

Submission

User interface

This field is never displayed to authors. You should not build a UI element for this field or expect authors to submit it.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  CampaignId={campaign id value}
                  CampaignId=API_RR_HOME_PAGE
                  

The campaign Id should be a string matching the pattern [A-Z_]. The value should have meaning to your application.

Context Data Question

AKA: User profile question, dropdown select people question, context data dimensions

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Story
Interface Submission, Display
Input type BooleanInput, SelectInput

Context data questions solicit information about the author ("How old are you?") or the author's relationship to the product ("How experienced are you?"). The answer to a context data question tells other users how relevant the author is to them. For example, users in a particular age group may consider reviews written by other users in the same age group more relevant.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer , Story
Conversations Review
This field type may be configured to be display & submission or submission only.
This field type may be configured to be category dependent.

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "ContextDataValues": {
                      "Age": {
                          "Value": "18to24",
                          "ValueLabel": "18 to 24",
                          "DimensionLabel": "Age",
                          "Id": "Age"
                      },
                  }
                  

The answers to context data questions should be displayed in close proximity to each other and near other author information (nickname, location, etc) so it is clear to users that the answers apply to the content author. When displaying CDVs to users you would typically use the ValueLabel and DimensionLabel which will be in a human readable format.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=contextdatavalue_[QuestionID]:operator:[OptionValue]
                  filter=contextdatavalue_Age:eq:18to24
                  filter=contextdatavalue_OptIn:eq:true
                  
Sort
                  sort=contextdatavalue_[QuestionID]:[asc|desc]
                  sort=contextdatavalue_Age:asc
                  sort=contextdatavalue_OptIn:asc
                  

Submission

User interface

Context data questions can either be represented as boolean inputs or select inputs. This is determined by configuration in the Bazaarvoice platform.

Depending on your client configuration and if the author has submitted content that has been approved, then Bazaarvoice will return this field pre-populated with the user's previous answer. In that case your application should show that value and give the author the option of submitting a different value. If the author does not provide a different value you should submit the pre-populated value.
BooleanInput

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "contextdatavalue_[QuestionID]": {
                  ...
                  },
                  "contextdatavalue_IncentivizedReview": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": false,
                      "Type": "BooleanInput",
                      "Label": "Did you receive a free product?",
                      "Id": "contextdatavalue_IncentivizedReview",
                      "MinLength": null,
                      "Options": [ ]
                  }
                  

BooleanInput context data questions do not provide an explicit list of options. Instead the options are assumed to be "true" or "false". Your user interface may display other similar verbiage (for example "Yes" for "true") but you should always submit "true" or "false".

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

SelectInput

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "contextdatavalue_[QuestionID]": {
                  ...
                  },
                  "contextdatavalue_FrequencyOfPlay": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": true,
                      "Type": "SelectInput",
                      "Label": "How often do you play?",
                      "Id": "contextdatavalue_FrequencyOfPlay",
                      "MinLength": null,
                      "Options": [
                          {
                              "Value": "",
                              "Selected": true,
                              "Label": ""
                          },
                          {
                              "Value": "MoreThanOncePerWeek",
                              "Selected": false,
                              "Label": "more than once per week"
                          },
                          {
                              "Value": "EveryWeek",
                              "Selected": false,
                              "Label": "every week"
                          },
                          {
                              "Value": "MoreThanOncePerMonth",
                              "Selected": false,
                              "Label": "more than once per month"
                          },
                          {
                              "Value": "LessThanOncePerWeek",
                              "Selected": false,
                              "Label": "less than once per week"
                          }
                      ]
                  },
                  

The available answers to a context data question (the options in the example above) are pre-determined and will be provided by the API. Your UI should present the options in a way that allows the author to select only one.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  contextdatavalue_[QuestionID]=[Value]
                  contextdatavalue_Age=18to24
                  contextdatavalue_OptIn=true
                  

Device fingerprint

AKA: blackbox

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Helpfulness vote, Story
Interface Submission
Input type TextInput

A device fingerprint contains information about the author's device which is used, in conjunction with sophisticated algorithms, by Bazaarvoice to identify, flag and report suspicious content. Learn more about this field at the Device Fingerprinting section.

Per the Bazaarvoice Authenticity Policy, you must send a device fingerprint attached to each submission. If you fail to send a device fingerprint with your submission, Bazaarvoice may take any action deemed necessary in Bazaarvoice’s sole discretion to protect the integrity of the network. Such actions may include but are not limited to: rejection of your content, halting syndication of your content on the Bazaarvoice network, revocation of your API key, or revocation of your API license.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Helpfulness vote, Story
Conversations Review, Question, Answer, Comment, Helpfulness vote, Story

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

This field should not be displayed to authors and is therefore not represented in response to an API submission request without the Action parameter. However, it is available to all clients.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  fp=[Value]
                  

Learn more about this field at our Authenticity tutorial.

Email alert - commented

AKA: Notifications Opt In, Social Alert

Description

Platform PRR, Config Hub
Content type Review, Story
Interface Submission
Input type BooleanInput

Bazaarvoice can send an email notification to a user each time their review or story receives a comment. This field allows review or story authors to opt in to those emails.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Story
Conversations Review, Story

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "sendemailalertwhencommented": {
                      "Default": null,
                      "MaxLength": null,
                      "Value": "false",
                      "Required": false,
                      "Type": "BooleanInput",
                      "Label": null,
                      "Id": "sendemailalertwhencommented",
                      "MinLength": null,
                      "Options": [ ]
                  },
                  

In the example below the user is given the option to opt in to the email alert:

If your app submits this field automatically without giving users the opportunity to opt in, then be sure to indicate prominently in writing that by authoring content they will be receiving email notifications and that they will be able to opt out of those emails when received

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  sendemailalertwhencommented=true
                  

Authors are unsubscribed by default so submitting false is unnecessary.

Email alert - content published

AKA: Notifications Opt In, Social Alert Approved

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission
Input type BooleanInput

Bazaarvoice can send an email notification to a user when our moderators publish their content. Content may be published in an approved or rejected state. This field allows authors to opt in to a single notification on a per-submission basis. Put another way, authors must opt in each time they submit content to receive a notification when that specific submission is either approved or rejected.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review, Question, Answer, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "sendemailalertwhenpublished": {
                      "Default": null,
                      "MaxLength": null,
                      "Value": "false",
                      "Required": false,
                      "Type": "BooleanInput",
                      "Label": null,
                      "Id": "sendemailalertwhenpublished",
                      "MinLength": null,
                      "Options": [ ]
                  },
                  

If you submit this field on behalf of your users be sure to indicate prominently in writing that by authoring content they will be receiving an email notification.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  sendemailalertwhenpublished=true
                  

Authors are unsubscribed by default so submitting false is unnecessary.

Email alert - question snswered

AKA: Social alert, notification opt-in

Description

Platform PRR, Config Hub
Content type Question
Interface Submission
Input type BooleanInput

Bazaarvoice can send an email notification to a user each time their question is answered. This field allows question askers to opt in to those emails.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Question
Conversations Question

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "sendemailalertwhenanswered": {
                      "Default": null,
                      "MaxLength": null,
                      "Value": "false",
                      "Required": false,
                      "Type": "BooleanInput",
                      "Label": null,
                      "Id": "sendemailalertwhenanswered",
                      "MinLength": null,
                      "Options": [ ]
                  },
                  

In the example below the user is given the option to opt in to the email alert:

If your app submits this field automatically without giving users the opportunity to opt in, then be sure to indicate prominently in writing that by authoring content they will be receiving email notifications and that they will be able to opt out of those emails when received

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  sendemailalertwhenanswered=true
                  

Authors are unsubscribed by default so submitting false is unnecessary.

Hosted-authentication email

AKA: Bazaarvoice-mastered authentication email

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission, Display
Input type TextInput

This field is used to capture an author provided email address which Bazaarvoice then associates with that author for future identification.

Learn more about using this field at the hosted authentication tutorial.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review, Question, Answer, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "hostedauthentication_authenticationemail": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 255,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "hostedauthentication_authenticationemail",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

This field accepts an email address. Bazaarvoice will perform validation on the submitted value and return an error if it is not in a valid email address pattern.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  hostedauthentication_authenticationemail=email%40example.com
                  

The example above is percent encoded.

Hosted authentication callback URL

AKA: Bazaarvoice-mastered authentication callback URL

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission
Input type TextInput

When using hosted authentication, authors are identified by their email address. To ensure a submitted email address is actually owned by the author it must be verified by a service you host. Bazaarvoice will send the author a verification email that links them to your verification service. This field is how you provide that URL to us.

Learn more about using this field at the hosted authentication tutorial.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review, Question, Answer, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

This field should not be displayed to authors and is therefore not represented in response to an API submission request without the Action parameter. However, if the response includes hostedauthentication_callbackurl then hostedauthentication_callbackurl will also be available.

HTTP interface

This field should be a fully qualified URL to a service you host. The domain must also be white-listed in the Bazaarvoice system to protect against unvalidated redirects. Your application will submit it along with their their content.

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  HostedAuthentication_CallbackURL=http%3A%2F%2Fwww.example.com%2Fyour%2Fauthentication-service
                  

The example above is percent encoded.

Net Promoter comment

Description

Platform PRR, Config Hub
Content type Review
Interface Submission
Input type TextAreaInput

The Net Promoter Comment is a component of the Net Promoter customer loyalty metric and should be implemented along with the Net Promoter Score field.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review
Conversations Review

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "netpromotercomment": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": false,
                      "Type": "TextAreaInput",
                      "Label": null,
                      "Id": "netpromotercomment",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

Authors use this field to elaborate on their Net Promoter Score and so this field should allow them to express themselves in multiple lines.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  netpromotercomment="Sed%20sit%20amet%20dui%20…"
                  

The example above is percent encoded.

Net Promoter score

Description

Platform PRR, Config Hub
Content type Review
Interface Submission
Input type IntegerInput
Range 0 - 10

The Net Promoter Score is a component of the Net Promoter customer loyalty metric and should be implemented along with the Net Promoter Comment field.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review
Conversations Review

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "netpromoterscore": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": false,
                      "Type": "IntegerInput",
                      "Label": null,
                      "Id": "netpromoterscore",
                      "MinLength": null,
                      "Options": [ ]
                  },
                  

Implement this field as the answer to a question like "How likely is it that you would recommend our [company/product/service] to a friend or colleague?" replacing [company/product/service] as appropriate for your needs.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  netpromoterscore=8
                  

Overall rating

AKA: Rating

Description

Platform PRR, Config Hub
Content type Review
Interface Submission, Display
Input type IntegerInput
Range 1 - 5

The Overall Rating is the author's overall opinion of the product, represented as an integer value from between 1 and 5. Overall rating is separate from ratings questions.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review
Conversations Review

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "Rating": 4
                  

Overall rating are visually similar to ratings questions, therefore you should be careful to visually distinguish them so users are not confused. The Conversations API will include text labels for the ratings questions to help with this and you should consider using different images graphics for overall rating, for example large stars.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=Rating:[operator]:[value]
                  filter=Rating:eq:3
                  
Sort
                  sort=Rating:[asc|desc]
                  sort=Rating:desc
                  

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "rating": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": true,
                      "Type": "IntegerInput",
                      "Label": null,
                      "Id": "rating",
                      "MinLength": null,
                      "Options": [ ]
                  },
                  

Overall rating is classified as an IntegerInput. The user interface should solicit the user to provide an integer value of between 1 - 5. Typically Bazaarvoice UIs have used rectangular "star" images that become highlighted on hover. Clicking on a star selects the value corresponding to the number of highlighted stars.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  rating=3
                  

Photo caption

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission, Display
Input type TextInput

This field is a brief user submitted explanation that goes along with an uploaded photo.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment , Story
Conversations Review, Question, Answer

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  Photos": [{
                      "Caption": "Sed quis lectus in erat viverra ...",
                      "Sizes":{...},
                      "SizesOrder": [....],
                     "Id": "70683"
                  },
                  

The photo caption should be displayed near the photo to which it relates.

HTTP interface

This field does not support filtering or sorting.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "photocaption_n": {
                      ...
                  },
                  "photocaption_3": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 255,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "photocaption_3",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

Each uploaded image may have it's own caption. In the code sample above n will be a value of between 1 - 6 depending on how many photo uploads are allowed.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  photocaption_n=[value]
                  photocaption_1="Sed%20sit%20amet%20dui%20…"
                  

The example above is percent encoded.

Photo URL

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission, Display
Input type TextInput

Photos can be included in a content submission. This is a two step process that involves 1) Uploading the photo to Bazaarvoice, 2) associating the uploaded photo to the content. Once associated, the photo will then be returned along with the content.

Learn more about photo upload at the Photo Upload tutorial.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment , Story
Conversations Review, Question, Answer

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  Photos": [{
                      "Caption": "Sed quis lectus in erat ...",
                      "Sizes": {
                          "thumbnail": {
                              "Url": "http://.../photoThumb.jpg",
                              "Id": "thumbnail"
                          },
                          "normal": {
                              "Url": "http://.../photo.jpg",
                              "Id": "normal"
                          }
                      },
                      "SizesOrder": [...],
                      "Id": "70683"
                  },
                  

The API returns two URLs: thumbnail and normal. The "thumbnail" URL is a smaller version of the image which you can present inline with other content to give users a preview of available photos. When users interact with the thumbnails you can then use the "normal" URL to display the full size image, typically in a lightbox or other pop-in style interface.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=hasPhotos:[operator]:[true|false]
                  filter=hasPhotos:eq:true
                  
Sort
                   sort=HasPhotos:[asc|desc]
                   sort=HasPhotos:asc
                  

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "photourl_n": {
                      ...
                  },
                  "photourl_6": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 2048,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "photourl_6",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

Photo URL is the URL to a user submitted photo that has already been uploaded to Bazaarvoice. In the code sample above n will be a value of between 1 - 6 depending on how many photo uploads are allowed. Read the Photo Upload tutorial to learn how to upload photos.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  photourl_n=[value]
                  photourl_1=http://.../photoThumb.jpg
                  

The exact URL will be provided during the photo upload process as described in the Photo Upload tutorial.

Primary text

AKA: Review text, Story text, Answer text, Comment text

Description

Platform PRR, Config Hub
Content type Review, Answer, Comment, Story
Interface Submission, Display
Input type TextAreaInput

The main text content of a submission. Typically up to 1000 characters or less.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Answer, Comment, Story
Conversations Review, Answer, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "ReviewText": "Sed sit amet dui …"
                  
                  "AnswerText": "Sed sit amet dui …"
                  
                  "CommentText": "Sed sit amet dui …"
                  
                  "StoryText": "Sed sit amet dui …"
                  

Be aware when displaying primary text that it may vary greatly in length from content to content. Your UI should accommodate reviews that range from very short to very long.

HTTP interface

This field does not support filtering or sorting.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "answertext": {
                      ...
                  },
                  
                  "commenttext": {
                     ...
                  },
                  
                  "storytext": {
                      ...
                  },
                  
                  "reviewtext": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 10000,
                      "Required": true,
                      "Type": "TextAreaInput",
                      "Label": null,
                      "Id": "reviewtext",
                      "Options": [ ],
                      "MinLength": 50
                  },
                  

The submission UI for the primary text field should encourage the content author to fully express themselves in multiple lines. Consider feedback in the form of a text counter so they know when they have reached the minimum required characters.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  ReviewText=Sed%20sit%20amet%20dui%20…
                  
                  AnswerText=Sed%20sit%20amet%20dui%20…
                  
                  CommentText=Sed%20sit%20amet%20dui%20…
                  
                  StoryText=Sed%20sit%20amet%20dui%20…
                  

The example above is percent encoded.

Product recommendation ID

AKA: Social recommendation, product references

Description

Platform PRR
Content type Review, Question, Answer, Comment, Story
Interface Submission, Display
Input type TextInput

Conceptually Product Recommendations is a way for authors to add visual links to products related to their content submission. For example while writing a review on one product an author might add a link to recommend a related product.

In practice, when done via the API, authors will submit related product IDs which you will then use to display links to those products on your site.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations

Refer to the field availability section in the appendix for more information.

Display

User interface
                  ProductRecommendationIds": [
                      "0533101P"
                  ],
                  

Use the contents of ProductRecommendationIds in conjunction with your product catalog to link users to the products that the author thinks are relevant to their submission. Displaying a product name, image and link are recommended.

HTTP interface

This field does not support filtering or sorting.

Submission

User interface

How this field is represented in response to an API submission request without the Action parameter.

                  "productrecommendationid_[n]": {
                      ...
                  },
                  "productrecommendationid_1": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "productrecommendationid_1",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

Your user interface for submitting product IDs should provide the author with a way to find products in your catalog. In the code sample above [n] will be a value of between 1 - 3 depending on how many product recommendations are allowed.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  productrecommendationid_[n]=[Value]
                  productrecommendationid_1=12345678
                  

The example above is percent encoded.

Question details

AKA: Question text

Description

Platform PRR, Config Hub
Content type Question
Interface Submission, Display
Input type TextAreaInput

This field, along with the question summary, makes up a complete question. Question details provide a way for the author to submit additional information to clarify and elaborate on their question.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Question
Conversations Question

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  QuestionDetails: "Sed sit amet dui …"
                  

Question details will vary greatly in length between questions and is often optional. You should take these possibilities into account when building your UI. One option is to always show the question summary, but only display the question details if the user indicates their interest by clicking the summary.

HTTP interface

This field does not support filtering or sorting.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "questiondetails": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 10000,
                      "Required": false,
                      "Type": "TextAreaInput",
                      "Label": null,
                      "Id": "questiondetails",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

The submission UI for question details should induce the content author to fully express themselves in multiple lines. Consider feedback in the form of a text counter so they know when they have reached the minimum required characters.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  questiondetails=Sed%20sit%20amet%20dui%20…
                  

The example above is percent encoded.

Question summary

Description

Platform PRR, Config Hub
Content type Question
Interface Submission, Display
Input type TextInput

The question summary is the question being asked. This field, along with the question details field if it exists, makes up a complete question.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Question
Conversations Question

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "QuestionSummary": "Donec vitae mi nec mass"
                  

The question summary is the primary component of a question and should be displayed prominently. One option is to always show the question summary, but only display the question details if the user indicates their interest by clicking the summary.

HTTP interface

This field does not support filtering or sorting.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "questionsummary": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 150,
                      "Required": true,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "questionsummary",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

The submission UI for a question summary should induce the content author to be concise by being limited to one line (no line breaks). An example of a good question can increase the quality of submissions.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  QuestionSummary=Donec%20vitae%20mi%20nec%20mass...
                  

The example above is percent encoded.

Rating question - NORMAL

AKA: Secondary rating dimension

Description

Platform PRR, Config Hub
Content type Review
Interface Submission, Display
Input type IntegerInput
Display Type NORMAL
Range 1 - 5

Rating questions present a more comprehensive way for authors to rate a product. Using this field type authors can rate different aspects or dimensions of a product. For example, an author may be presented with the option to rate a product’s appearance, workmanship, ease of assembly, and value. Rating questions are distinct from the overall rating and do not contribute to the product's overall average rating.

Availability

Platform Content type
Conversations PRR Review
Conversations Review
This field type may be configured to be category dependent.

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "Quality": {
                      "Value": 5,
                      "ValueLabel": null,
                      "MaxLabel": null,
                      "Label": "Quality",
                      "Id": "Quality",
                      "ValueRange": 5,
                      "MinLabel": null,
                      "DisplayType": "NORMAL"
                  }
                  

Normal rating questions are similar to the overall rating, therefore you should be careful to visually distinguish them so users are not confused. The Conversations API will include text labels for the Ratings questions to help with this and you might consider using different graphics, for example small bars instead of stars.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=[QuestionID]:eq:[Value]
                  filter=Quality:eq:3
                  
Sort
                  sort=[QuestionID]:[asc|desc]
                  sort=Quality:asc
                  

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "rating_[QuestionID]": {
                      ....
                  },
                  "rating_Quality": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": false,
                      "Type": "IntegerInput",
                      "Label": "Quality",
                      "Id": "rating_Quality",
                      "MinLength": null,
                      "Options": []
                  },
                  

Normal rating questions are classified as an IntegerInput. The user interface should solicit the author to provide a positive integer value of between 1 - 5. In the example image below the count of highlighted stars from left to right equals the rating.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  rating_[QuestionID]=[Value]
                  rating_Quality=3
                  

The example above is percent encoded.

Rating question - SLIDER

AKA: Secondary rating dimension

Description

Platform PRR, Config Hub
Content type Review
Interface Submission, Display
Input type SelectInput
Display Type SLIDER
Range 1 - 3, 1 - 5, 1 - 7

Slider rating questions are similar to normal rating questions in that they present a more comprehensive way for authors to rate a product. However, SLIDER rating questions represent a range of values in which no answer value is better or worse than another. For example, a rating slider question might ask how an item of clothing fits. To answer that question the author is given a choice between "small' (1), "expected" (2), or "large" (3). Although "large" is the highest value (3) it is not the best answer.

Availability

Platform Content type
Conversations PRR Review
Conversations Review
This field type may be configured to be category dependent.

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "SecondaryRatings": {
                      "FitTrueToSize": {
                          "Value": 2,
                          "ValueLabel": "True to size",
                          "MaxLabel": "Runs Large",
                          "Label": "Fit",
                          "Id": "FitTrueToSize",
                          "ValueRange": 3,
                          "MinLabel": "Runs Small",
                          "DisplayType": "SLIDER"
                      },
                  },
                  

When displaying this field to users it is important to present the answer in a way that indicates it was one option of several in a continuum of values. This can be accomplished by showing the selected answer between the lowest and highest options in a way that indicates its relative value. Put another way, if there are 7 options, with 1 being left most and 7 being rightmost, and the answer is 6, then the display UI should show the answer almost all the way to the right.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=[QuestionID]:eq:[Value]
                  filter=FitTrueToSize:eq:3
                  
Sort
                  sort=[QuestionID]:[asc|desc]
                  sort=FitTrueToSize:asc
                  

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "rating_[QuestionID]": {
                      ....
                  },
                  "rating_FitTrueToSize": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": true,
                      "Type": "SelectInput",
                      "Label": "Fit",
                      "Id": "rating_FitTrueToSize",
                      "MinLength": null,
                      "Options": [
                          {
                              "Value": "1",
                              "Selected": false,
                              "Label": "Runs small"
                          },
                          {
                              "Value": "2",
                              "Selected": false,
                              "Label": "True to size"
                          },
                          {
                              "Value": "3",
                              "Selected": false,
                              "Label": "Runs large"
                          }
                      ]
                  },
                  

The user interface you present for slider ratings questions should indicate to the author that there is no best answer. The answer labels and values for this type of question have been pre-configured and will be provided by the API.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  rating_[QuestionID]=[Value]
                  rating_FitTrueToSize=3
                  

The example above is percent encoded.

Is recommended

AKA: Recommend to a friend

Tags - legacy free text pros and cons

AKA: Pros, Cons

Description

Platform PRR
Content type Review
Interface Submission, Display
Input type TextInput

Legacy free text pros / cons are an early implementation of tagging. They allow users to submit words or short strings of text that can be characterized as expressing pro or con sentiment about the product being reviewed. Legacy pro / con free text tags are limited to reviews.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review
Conversations
This field type may be configured to be display & submission or submission only.
This field type may be configured to be category dependent.

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "Pros": "Great product, well made, easy install",
                  "Cons": "Should be included with the $2000.00 SYSTEM",
                  

Each of these fields will be a long string of text with no line breaks. When displaying to end users you aren't restricted to the labels "Pro" or "Con"; consider using more user friendly values like "What I like" for "Pro" or "Needs improvement" for "Con".

HTTP interface

These feilds do not support filtering or sorting.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "pros": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 120,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "pros",
                      "Options": [ ],
                      "MinLength": 1
                  },
                  "cons": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 120,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "cons",
                      "Options": [ ],
                      "MinLength": 1
                  },
                  

These fields should encourage authors to submit positive (pro) or negative (con) sentiment about a product, preferably in the form of words or short phrases separated by commas. Provide a helper text example to encourage quality submissions.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  Pros=Great%20product%2C%20well%20made%2C%20easy%20install
                  Cons=Should%20be%20included%20with%20the%20$2000.00%20SYSTEM
                  

The example above is percent encoded.

Tags - tag dimensions

AKA: Generic tags, Tag groups

Description

Platform PRR, Config Hub
Content type Review, Question, Story
Interface Submission, Display
Input type BooleanInput, TextInput

Tag Dimensions let you create custom tag types with tags that identify the different attributes of a product. Depending on configuration, authors can express sentiment by selecting from predefined tags or by creating their own tags at submission time.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question , Story
Conversations Review
This field type may be configured to be display & submission or submission only.
This field type may be configured to be category dependent.

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "TagDimensions": {
                      "Cons": {
                          "Values": [
                              "messy",
                              "hard to start",
                          ],
                          "Id": "Cons",
                          "Label": "Cons"
                      },
                      "Pros": {
                          "Values": [
                              "works well",
                              "easy to clean",
                          ],
                          "Id": "Pros",
                          "Label": "Pros"
                      },
                      "FavoriteDays": {
                          "Values": [
                              "Thursday",
                              "Saturday"
                          ],
                          "Id": "FavoriteDays",
                          "Label": "I like using this on"
                      }
                  },
                  

When displaying tags use the Label value to provide context and separate each tag with a delimiter, such as a comma, to make it clear that each tag is distinct. Because tags can be user defined you should build your UI to handle unexpected values. For example, unusually long tags should not break your layout.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=tag_[QuestionID]:eq:[Value]
                  filter=tag_FavoriteDate:eq:Thursday
                  filter=tag_Pros:eq:Easy%20To%20Clean
                  
Sort
                  sort=HasTags:[asc|desc]
                  
Sorting by specific tags is not supported.

Submission

User interface

Whether predefined or user defined the inputs for tags should be displayed close together to indicate they are related to each other.

Predefined

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "tagid_[QuestionID]/[TagID]": {
                      ....
                  },
                  "tagid_Pro/Quality": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": null,
                      "Required": false,
                      "Type": "BooleanInput",
                      "Label": "High quality",
                      "Id": "tagid_Pro/Quality",
                      "MinLength": null,
                      "Options": [ ]
                  },
                  

Because the values are predefined the author will only need to indicate that a tag applies. This can be accomplished using multi-select style UI (e.g. check boxes). If a tag is not selected there is no need to submit it.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

Author Defined

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "tag_[QuestionID]_n": {
                      ...
                  },
                  "tag_Pro_4": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 50,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "tag_Pro_4",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

Author defined tags should be displayed as a text inputs, one for each tag. The maximum number of author defined tags per submission is 10. In the example above n stands for an integer between 1 - 10. Consider providing examples to encourage authors to submit meaningful tags

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface
Predefined

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  tagid_[QuestionID]/[TagID]=true
                  tagid_FavoriteDay%2fThursday=true
                  tagid_Pro%2fEasyToClean=true
                  

The example above is percent encoded.

User Defined

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  tag_[QuestionID]_[n]=[value]
                  tag_Pros_1=Goes%20with%20my%20outfit
                  

The example above is percent encoded.

Title

AKA: Review title, Comment title, Story title

Description

Platform PRR, Config Hub
Content type Review, Comment, Story
Interface Submission, Display
Input type TextInput

Introduces or summarizes content. Typically 50 characters or less.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Comment, Story
Conversations Review, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  title: "This is a great product..."
                  

A title or summary should be prominently displayed in a position above most other elements, with the possible exception of the overall rating in the case of a review.

HTTP interface

This field does not support filtering or sorting.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  title": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 50,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "title",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

The submission UI for a title should induce the content author to be concise by being limited to one line (no line breaks). Consider providing an example to increase the quality of submissions.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  title=This%20is%20a%20greatp%20roduct..
                  

The example above is percent encoded.

User email

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission
Input type TextInput

The user email field is intend specifically for email addresses. Successful submissions will be stored in an encrypted format to ensure secrecy and comply with PII related regulations.

You do not need to use this field if you are already submitting the author's email address via the Hosted Authentication Email field.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review, Question, Answer, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

This field is not returned for display by the Conversations API.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "useremail": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 255,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "useremail",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

Bazaarvoice will perform validation on the submitted value and return an error if it is not in a valid email address pattern.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  useremail=email%40example.com
                  

The example above is percent encoded.

User location

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment
Interface Submission, Display
Input type TextInput

Geographic region where the content author lives.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review, Question, Answer, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "UserLocation": "Austin, TX"
                  

Because user location allows free text your UI should be able to accommodate submissions of varying length.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=UserLocation:[Operator]:[Value]
                  filter=UserLocation:eq:Austin%2C%20TX
                  
Sort
                  sort=UserLocation:[asc|desc]
                  sort=UserLocation:asc
                  

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

If the author has submitted content previously and has been approved then Bazaarvoice will return this field pre-populated with the user's location. In that case your application should show that value and give the author the option of submitting a new location. If the author does not provide a new value you should submit the pre-populated location.
                  "userlocation": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 50,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "userlocation",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

Although this is a free-text field, we recommend that your UI offer the author some guidance. For example, provide helper text demonstrating the desired format or suggestions as the author types. This will result in more consistent and meaningful data.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  userlocation=Austin%2C%20TX
                  

The example above is percent encoded.

User nickname

AKA: Display name

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission, Display
Input type TextInput

The persona adopted by a content author. Bazaarvoice moderators will reject nicknames that appear to be real names to protect the author's identity .

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review, Question, Answer, Comment, Story

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "UserNickname": "tester",
                  

Your UI should be able to accommodate submissions of varying length because this field allows free text.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=UserNickname:[operator]:[AnswerValue]
                  filter=UserNickname:eq:jane123
                  
Sort
                  sort=UserNickname:[asc|desc]
                  sort=UserNickname:asc
                  

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

If the author has submitted content previously and has been approved then Bazaarvoice will return this field pre-populated with the author's nickname. In that case your application should show the existing nickname instead of giving the author the option to submit a new nickname.
                  "usernickname": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 25,
                      "Required": true,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "usernickname",
                      "Options": [ ],
                      "MinLength": 4
                  },
                  

Your UI should make it clear to the content author that a nickname should not be their real name. It is also recommended that the nickname field be placed in the same area of the form as other user related fields. Finally, if you provide a user ID when requesting the form fields Bazaarvoice will return this field pre-populated with the author's existing nickname if it is known. Bazaarvoice does not support changing nicknames so in that case your UI should show the existing nickname in an uneditable fashion.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  UserNickname=[nickname]
                  UserNickname=Jane123  // Approved: not real name
                  UserNickname=JanetCWhite  // Rejected: real name
                  

Video caption

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission, Display
Input type TextInput

This field is a brief user submitted explanation that goes along with a video.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "Videos": [{
                          "Caption": "Sed sit amet dui…",
                          ...
                  }],
                  

The video caption should be displayed in close proximity to the video it describes.

HTTP interface

This field does not support filtering or sorting.

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "videocaption_1": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 255,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "videocaption_1",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

In the code sample above videocaption_ is suffixed with 1 to indicate it applies to the video also associated with 1. However, Bazaarvoice Conversations currently supports only a single video upload so the suffix will always be 1.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                   videocaption_1="Sed%20sit%20amet%20dui…"
                  

The example above is percent encoded.

YouTube video URL

Description

Platform PRR, Config Hub
Content type Review, Question, Answer, Comment, Story
Interface Submission, Display
Input type TextInput

Bazaarvoice Conversations can accept a YouTube video URL along with a content submission which will be returned with the display of that content. For example, an author could submit the URL to their YouTube hosted video review of a product to be displayed along with their text review of that product.

Availability

This field is available on the designated platforms and content types listed below.

Platform Content type
Conversations PRR Review, Question, Answer, Comment, Story
Conversations Review

Refer to the field availability section in the appendix for more information.

Display

User interface

How this field type is represented in response to an API display request. Your API response may vary due to client configuration and API version.

                  "Videos": [{
                      "Caption": "Sed sit amet dui…",
                      "VideoHost": "www.youtube.com",
                      "VideoId": "CLK1D8bAhRc",
                      "VideoUrl": "https://www.youtube.com/watch?v=CLK1D8bAhRc",
                  }],
                  

Bazaarvoice will return information about the author's video. Use this information in conjunction with a YouTube API to embed the video in your application. See YouTube's developer documentation for more information on YouTube's current methods for displaying YouTube hosted video.

HTTP interface

The code samples below demonstrate how to filter and sort with this field.

Filter
                  filter=HasVideos:[true|false]
                  filter=HasVideos:true
                  
Sort
                  sort=HasVideos:[asc|desc]
                  sort=HasVideos:asc
                  

Submission

User interface

How this field type is represented in response to an API submission request without the Action parameter. Your API response may vary due to client configuration and API version.

                  "videourl_1": {
                      "Default": null,
                      "Value": null,
                      "MaxLength": 1024,
                      "Required": false,
                      "Type": "TextInput",
                      "Label": null,
                      "Id": "videourl_1",
                      "Options": [ ],
                      "MinLength": 0
                  },
                  

This field accepts the URL to a YouTube hosted video. In the code sample above videourl_ is suffixed with 1 to indicate it applies to the video caption also associated with 1. However, Bazaarvoice Conversations supports up to one video URL so the suffix will always be 1.

Learn more about creating this type of input and how to submit the author's answer at our Input types tutorial.

HTTP interface

The following code sample shows how a field Id is associated with a value in a GET or POST request.

                  VideoUrl_1=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DCLK1D8bAhRc
                  

The example above is percent encoded.

Appendix

Internal fields

The following fields may be returned in the Conversations API, but are for internal usage by Bazaarvoice application only and can be safely ignored.

  • HostedAuthentication_RememberMe
  • isratingsonly
  • IsUserAnonymous
  • netpromoterexpanded
  • productrecommendationcaption_[n]
  • socialconnect_facebook_usertoken
  • socialconnect_facebook_hostname
  • socialconnect_facebook_postresult
  • socialconnect_facebook_postdesired
  • socialconnect_facebook_postonsubmit
  • userlocationgeocode_latitude
  • userlocationgeocode_longitude
  • userlocationgeocode_country
  • userlocationgeocode_region
  • userlocationgeocode_city

Field availability

Fields will be available in the Conversations API based on a combination of the following criteria:

  • Platform

    Client instances are provisioned on one of our two platforms. The availability of fields varies between platforms.

    Conversations PRR
    Our first platform. Originally called "Product Rating and Reviews" or "PRR". On this platform client configuration are internal and all changes must be done by Bazaarvoice personal.
    Conversations
    Conversations is our latest platform. For this platform we've created a self service configuration UI that allows our clients to see and interact with their configurations without relying on Bazaarvoice personal.

    Learn more about platforms at Platform & API Concepts.

  • Client instance

    A client instance consists of a data store and the configurations that control available features. Different client instances can have different fields.

  • Deployment Zone

    Clients on our Conversations platform with access to our configuration hub can configure fields on a per deployment zone basis. A single client instance can have multiple deployment zones. To distinguish between them you will need different API keys for each deployment zone. Contact our support team for more information.

  • Display

    Clients on our Conversations PRR platform may have fields configured on a per display basis. A single client instance can have multiple displays. To distinguish between them you will need different API keys for each display. Contact our support team for more information.

  • Category Dependent

    Fields can be limited to content written about products in particular categories. For example, reviews about products in a "clothing" category may have different fields than reviews about products in an "Electronics" category.

    The following fields are eligible for this configuration:

    • Additional fields
    • Context data questions
    • Ratings questions
    • Tags
  • Submission & Display or Submission only

    Some fields, which would normally be available for both submission and display, can be configured to be submission only. This is useful when collecting information for business purposes but that you do not want to display on product pages to the public. API keys may have access to these submission only fields based on a per key configuration.

    The following fields are eligible for this configuration:

    • Additional fields - per field
    • Context data questions - per field
    • Tags - all or none
  • Bazaarvoice content type

    Fields may be configurable for reviews, questions, answers, stories or comments. See the specific fields above for more information.

  • Localization

    Although not common, it is possible for fields to be available on a per locale basis. For example, due to varying regulations, authors in a particular locale might be asked questions that authors in another locale are not asked.