Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Submission Fundamentals
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
This tutorial explains Conversations API full submission request fundamentals. It does not apply to progressive submission.
Overview
Submission using the Bazaarvoice Conversations API is accomplished by performing an HTTP request that includes a content type, an API version, your API Passkey and the following:
- subject ID
- API submission action
- author identification
- authenticity information
- author input
Continue reading to learn about each of these submission components and how they are used.
HTTP methods
Submissions can use either HTTP GET or HTTP POST depending on the nature of the request. In general, GET will be used to request information about the available submission options or to request a submission preview. The final act of submission, when you are ready for Bazaarvoice to save the author's input, must be performed with POST. When POST is used you must also include the HTTP ContentType
header with a value of application/x-www-form-urlencoded
. The section The Action
parameter and the submission process will discuss when to use GET or POST in more detail.
The following examples show a GET request as well as a POST request with the HTTP Content-Type
header:
GET https://[stg.]api.bazaarvoice.com/data/[ContentType].json?ApiVersion=[LatestApiVersion]&Passkey=[YourApiKey]&ProductId=[ProductId]&Action=[SubmissionAction]&Rating=[Rating]&ReviewText=[ReviewText]&Title=[TitleText]&UserNickname=[Nickname]
POST /data/submitreview.json HTTP/1.1 Host: [stg.]api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: [AuthorIPAddress] ... ApiVersion=[LatestApiVersion]&ProductId=[ProductId]&Action=[SubmissionAction]&Rating=[Rating]&ReviewText=[ReviewText]&Title=[TitleText]&UserNickname=[Nickname]&Passkey=[YourApiKey]
Ellipses (...) in above example indicate that your app may generate other headers.
Content types
All submissions to the Bazaarvoice platform will be of a particular consumer-generated content type. Review is the most common content type, but there are others. The table below shows the API endpoint for each content type. Click on an endpoint to see examples, options, and error codes:
Content type | Submission Endpoint |
---|---|
Review | |
Review Comment | |
Question | |
Answer | |
Story | |
Story Comment |
This example shows a review submission request using submitreview.json
:
GET https://[stg.]api.bazaarvoice.com/data/submitreview.json?ApiVersion=[LatestApiVersion]&Passkey=[YourApiKey]&ProductId=[ProductId]&Action=[SubmissionAction]&Rating=[Rating]&ReviewText=[ReviewText]&Title=[TitleText]&UserNickname=[Nickname]
Subject ID
All submissions to the Bazaarvoice platform must identify a subject. For example, reviews and questions are written about products, comments are written in response to reviews, and answers are written in response to questions. The subject's ID is communicated using one of the subject ID parameter keys listed below:
Content types | Subject ID parameter key |
---|---|
|
ProductId |
|
QuestionId |
|
PRRCategoryId |
|
ReviewId |
StoryId |
In this review submission request the subject is a product and the subject ID (the product id) is 123456:
GET https://[stg.]api.bazaarvoice.com/data/submitreview.json?ApiVersion=[LatestApiVersion]&Passkey=[YourApiKey]&ProductId=123456&Action=[SubmissionAction]&Rating=[Rating]&ReviewText=[ReviewText]&Title=[TitleText]&UserNickname=[Nickname]
Subject ID source
ProductId
and CategoryId
are mastered by our clients; they will come from your system. These IDs must not contain the forward-slash character ( / ) and for maximum compatibility we recommend limiting them to alphanumeric characters and the following special characters: asterisk (*), hyphen (-), period (.), and underscore (_). You may substitute non-matching characters in your IDs with the closest characters that do match (ex: use "a" instead of "à") or by replacing non-conforming characters with the underscore (ex: replace "/" with "_").
ReviewId
, QuestionId
, and StoryId
are created by Bazaarvoice shortly after submission. You can determine those values by making a display request for the appropriate content type. Be aware that content only appears in the API display response after it has been moderated as approved, so do not expect to see content immediately after submission. In staging moderation is automated and will take up to a half hour. In production it is done by human moderators and can take up to 72 business hours, but usually happens faster.
Failure to include a subject ID will result in an error as shown below:
{ "Data": { }, "HasErrors": true, "Form": [ ], "AuthorSubmissionToken": null, "FormErrors": { }, "TypicalHoursToPost": null, "SubmissionId": null, "Locale": null, "Errors": [ { "Message": "400 - ERROR_PARAM_MISSING_SUBJECT_ID", "Code": "ERROR_BAD_REQUEST" } ] }
Subject IDs with a forward slash will result in the following error:
{ "Data": { }, "HasErrors": true, "Form": [ ], "AuthorSubmissionToken": null, "FormErrors": { }, "TypicalHoursToPost": null, "SubmissionId": null, "Locale": null, "Errors": [ { "Message": "Subject ID cannot contain '/'", "Code": "ERROR_PARAM_INVALID_SUBJECT_ID" } ] }
The action parameter and the submission process
Submission to the Bazaarvoice platform is designed to be a three step process:
- Request form information
- Preview the author's input
- Submit author input to be saved by Bazaarvoice
1. Request form information
Make a GET or POST request including Action=
(or just exclude Action
). The response will contain field information and meta-data, that can be used to dynamically build a product specific submission form. If an author ID is included, then fields will be pre-populated with known information about that author (Ex: author name).
Both of the following URLs demonstrate valid ways to request form information:
GET https://[stg.]api.bazaarvoice.com/data/submitreview.json?ApiVersion=[LatestApiVersion]&ProductId=[ProductId]&Passkey=[YourApiKey]
GET https://[stg.]api.bazaarvoice.com/data/submitreview.json?ApiVersion=[LatestApiVersion]&ProductId=[ProductId]&Passkey=[YourApiKey]&Action=
This step is optional, but the alternative, hard coding the form fields, is fragile and may break when field configurations and their properties are changed.
Action
parameter in later steps because omitting it is understood to be a request for form data.2. Preview the author's input
Make a GET or POST request including Action=preview
and the author's input. In addition to the field information and meta-data from step 1 the response to this request also includes input errors (Ex: missing required fields) as appropriate and the field values are populated with the author's input. This allows you to build a form populated with the author's input and errors as necessary.
This URLs demonstrates how to use the Action
parameter to perform a submission preview:
GET https://[stg.]api.bazaarvoice.com/data/submitreview.json?ApiVersion=[LatestApiVersion]&ProductId=[ProductId]&Passkey=[YourApiKey]&Action=preview
This step is optional, but if you omit it you should perform submission while the author is available to fix validation errors to ensure content will be accepted. See step #3 for more details.
3. Submit author input to be saved by Bazaarvoice
Make a POST request including Action=submit
and the author's input. If there are input errors, then the response will be identical to a preview request with errors. If there are no errors, then Bazaarvoice will save the data and return a submission ID. You should save the submission ID for your records.
The Bazaarvoice Authenticity Policy forbids modifications to content by anyone other than the original author. If there are content validation errors and the author is not available to correct them, then Bazaarvoice will not accept that content. For this reason, submission to Bazaarvoice should occur as soon as the author has completed their input. This will allow you to give the author an opportunity to fix any validation errors that would otherwise prevent Bazaarvoice from accepting the submission. If you save content to be submitted at a later time, then you should perform a preview request (see step #2) as soon as the author has completed their input, so that you can give them the opportunity to fix any validation errors at that time.
This example demonstrates how to use the Action
parameter to save data in the Bazaarvoice system:
POST /data/submitreview.json HTTP/1.1 Host: [stg.]api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: [AuthorIPAddress] ... ApiVersion=[LatestApiVersion]&ProductId=[ProductId]&Action=submit&Rating=[Rating]&ReviewText=[ReviewText]&Title=[TitleText]&UserNickname=[Nickname]&Passkey=[YourApiKey]
Ellipses (...) in above example indicate that your app may generate other headers.
The Conversations API supports Cross Origin Resource Sharing (CORS) to allow JavaScript applications to perform submissions from the browser. The
X-Forwarded-For
header is not necessary when using CORS. Refer to the CORS tutorial to learn more.Author identification
When submitting content using the Conversations API you will need to identify the author. This is accomplished by submitting an author ID or author email address to Bazaarvoice through one of the authentication methods summarized below:
- Bazaarvoice-mastered
-
Bazaarvoice-mastered authentication, also referred to as 'hosted authentication', allows authors to submit content without prior authentication. In this authentication method Bazaarvoice generates an author ID that is associated with an email address provided during content submission.
-
- Client-mastered
-
Client-mastered authentication, also referred to as 'site authentication', requires authors to log in using your authentication system before submitting content to Bazaarvoice. In this authentication method the author ID comes from your system and Bazaarvoice stores a copy of it to identify the author.
-
Learn more at the authentication documentation section.
Authenticity information
All content submitted to the Bazaarvoice platform is evaluated by our risk-based filtering systems to limit fraudulent content and spam from being posted on clients' websites. We require you to submit the author's IP address and a device fingerprint to facilitate this evaluation.
Author IP address
The IP address of a computer initiating an HTTP request (the client) is automatically communicated to the computer receiving the request (the server). If your Conversations API submissions originate from a web-browser or mobile app, we will automatically receive the author's IP address.
However, if you are performing the submission from your server to our server, then you must use the X-Forwarded-For
header to communicate the author's IP address to us. Otherwise, we will receive your server's IP address for every submission, which increases the likelihood that your submissions will be flagged as inauthentic.
In the following example, the IP address 192.0.2.1
represents the IP address of the content author:
POST /data/submitreview.json HTTP/1.1
Host: stg.api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: 192.0.2.1
...
Rating=5&Title=This+is+a+review+TitleText&ReviewText=This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+&UserNickname=bvtester&ProductId=io_bb_callback&UserId=1234567&ApiVersion=[LatestApiVersion]&Action=submit&Passkey=[YourApiKey]
Ellipses (...) in above example indicate that your app may generate other headers.
Device fingerprint
A device fingerprint is an encoded string containing information about a user agent. The technique for generating a device fingerprint varies based on environment and device reputation partner, but in general will involve the following steps:
- Configure and load a device fingerprint library in your app.
- Wait for the script to analyze the user agent and create a device fingerprint.
- Communicate the device fingerprint to Bazaarvoice or one of our reputation management partners.
Read the Device Fingerprinting section for more information and code samples demonstrating how to perform device fingerprinting.
Author input
Author input is communicated to Bazaarvoice using percent encoded key-value pairs in the query component of an HTTP GET request or in the body of an HTTP POST request. The parameter keys can be determined from the API response. As previously discussed above, a submission request with Action=
(or no Action=
) will return form metadata, including information about each field. The example below shows how a field is represented in the API submission response. The Id
value isrecommended
(line 8) is the key used for submission:
"isrecommended": { "Default": null, "MaxLength": null, "Value": "", "Required": false, "Type": "BooleanInput", "Label": null, "Id": " isrecommended ", "MinLength": null, "Options": [ ] },
Depending on the type of input, the author will either enter arbitrary values or choose from pre-determined options. In the previous example the input type is BooleanInput
(line 6).
The Conversations API supports the following input types:
Input type | Value source |
---|---|
BooleanInput | Author indicates true or false |
FileInput | Author uploads image or video |
IntegerInput | Author enters number from a pre-determined range |
SelectInput | Author select value from a pre-determined set of options |
TextAreaInput | Author enters arbitrary text and line breaks |
TextInput | Author enters arbitrary text |
This example shows author input being submitted in the body of a HTTP POST request.
POST /data/submitreview.json HTTP/1.1
Host: stg.api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...
IsRecommended=true&Rating=5&Title=This+is+a+review+TitleText&ReviewText=This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+This+is+review+text.+&UserNickname=bvtester&ProductId=123456&UserId=1234567&ApiVersion=[LatestApiVersion]&Action=submit&Passkey=[YourApiKey]
Ellipses (...) in above example indicate that your app may generate other headers.
Refer to the Input Type tutorial for general information about input types. For information about a specific field refer to the Field Type tutorial.
Overview - Progressive Submission
This section explains how to use the progressive submission endpoints. These endpoints are available as part of the Conversations API.
Progressive submission improves review content collection in two ways:
- By allowing collection of reviews on multiple products; and
- By allowing incremental submission of review attributes
The combination of these two functionalities makes it especially valuable for clients that sell multiple items to a consumer at once. This will improve review coverage across products as well as the content submission rate.
Additionally, the incremental submission functionality may be used to enhance existing single product review submissions. This will improve content submission using this simplified approach.
The flow-chart below is a summary of a multi-product submission process using the progressive submission endpoints:
As previously described, progressive submission also supports the ability to collect review partials (i.e. ratings, review text, title, context data values) over multiple sessions. Reviews can be submitted for moderation once the required fields are completed. This is determined by the isFormComplete
field. Partial reviews can be iterated over using the submissionSessionToken
.
Components
The following table summarizes the components you will need to understand in order to implement progressive submission. These components will be referenced throughout the rest of this documentation.
Component | Description | Responsibility |
---|---|---|
Submission form | This a web form you build and host. Authors will use it to submit reviews. | client |
UserToken | The UserToken is an encoded set of fields sent in the body that are authenticated via an HMAC generated with the client's encodingKey. Must contain userId. Read more about userToken.The userToken and userId fields are mutually exclusive. Use one or the other. Using both will result in an error. | client |
UserId | Unique id for user. Can either be sent seprately at this level, or be encoded in UserToken. The userToken and userId fields are mutually exclusive. Use one or the other. Using both will result in an error. | client |
submissionSessionToken | Unique token ID required for progressive submission of the review. | Bazaarvoice/client |
preview parameter | Query string parameter indicating if content should be submitted for moderation. Used with the progressiveSubmit.json endpoint. Read more about the preview parameter. |
Bazaarvoice/client |
isFormComplete parameter | A boolean value returned as a query string parameter indicating if content should be submitted for moderation. Used with the progressiveSubmit.json endpoint. | Bazaarvoice/client |
Walk-through
How it works
-
Request reviews
Solicit reviews from consumers.
-
Initiate progressive submission
Request form data on product(s) using the initiateSubmit.json endpoint. For additional metadata about the product, you will also need to request data from the products endpoint.
-
Build product(s) submission form
Build the submission form(s) for the given productId(s). Render the HTML controls and values for the product submission form.
-
Submit product(s) review
Handle the productId(s) submissions. Use the
preview
parameter in the request to stage the review submission and theisFormComplete
in the response to observe if all the required fields are provided.
Step 1: Request reviews
Consumers are asked to provide reviews. This often comes through a post interactive email (PIE) containing a link to 'write reviews on your purchase'.
The user clicks the link in the email and is shown review submission forms for any number of products.
Other methods to solicit a shopper's feedback are also possible, such as hosting a recently purchased page where shoppers can leave reviews.
Step 2: Initiate Progressive Submission
Products may have different review attributes. For instance while a review form for an article of clothing may ask 'how was the fit', that question does not make sense for an electronics good.
The purpose of the initiateSubmit.json call is to provide API users with data to create the review submission form for a given productId. The endpoint accepts an array of productIds in the body parameter.
Step 3: Build product(s) submission form
Building a progressive submission form is similar to building a submission form using the full submission endpoint. High level steps include:
Obtaining product metadata from the products endpoint. This may include product descriptions, images and any other relevant data to help users write a review. Rather than displaying just the questions to review a product, it is often helpful to provide context. Product images, title, and price are just some attributes that help when writing a review.
Review form without any product context.
Review form displaying product context (images, title).
The products endpoint supports passing in a list of productIds to optimize the number of API requests.
Use both the
fieldsOrder
andfields
elements from the initiateSubmit.json response to create the HTML controls needed for the submission form.The fieldsOrder lists the required submission questions first, followed by those submission elements set up on the Site Manager.
The field data contains attributes that provide information on the specific HTML controls that should be displayed on the submission form.
The possible field types are shown below
"title": { "required": true, "id": "title", "maxLength": 50, "type": "text", "class": "title" },
As you can see, there is a list of name/value pairs that are returned for each
Fields
object. The sole purpose of this data is to provide developers a blue print to construct a submission form.Let's take a look at these name/value pairs:
The boolean value
hidden
, indicates if the element should be displayed on the form. Only form elements with a true value are returned in the response. When not found in the response,hidden
is false.⚠hidden
field is available only for Progressive Submission"OrderNumber": { "hidden": true, "autoPopulate": false, "answerLength": "SHORT_LINE", "label": "Order Number", "id": "additionalfield_OrderNumber", "type": "text", "class": "additionalField", "required": false, "maxLength": 35 },
A
autoPopulate
value makes it possible to pre-populated a control when building the form. An example of this is signing a user up to receive a newsletter.newslettersignup: { autoPopulate: true, maxLength: null, value: "true", required: true, type: "boolean", label: null, id: "newslettersignup", minLength: null },
The
value
represents the user's answer to a question and is what Bazaarvoice will store. When obtaining pre-populated data such as making a request using the &User and/or &UserID parameter, the value is returned in theValue
key.The
maxLength
is configured on the BV side and submissions will not be allowed unless it is met. The value can be used to create client side validation to ensure that the submission form meets the requirement. In the sample below the Review Text must not exceed 5000 characters.reviewtext: { default: null, value: "", maxLength: 50000, required: false, type: "TextAreaInput", label: null, id: "reviewtext", minLength: 50 },
⚠ERROR_FORM_TOO_LONG
error will be returned from the API if a submission exceeds themaxLength
value.required
indicates that some value must be provided with submission of the form. Combination ofrequired
andtype
can be used to create client side validation.commenttext: { default: null, value: null, maxLength: 10000, required: true, type: "TextAreaInput", label: null, id: "commenttext", minLength: 1 },
⚠ERROR_FORM_REQUIRED
will be returned from the API if a submission is missing aRequired
field.The
type
name/value gives the developer an indication of the HTML control that should be used to capture the input on the form. These values can also be used to generate client side validation rules. Values returned withintype
include:- text
- choice
- boolean
- integer
- url
The Inputs Types tutorialis the authoritative source documenting the different field types.
The
label
name/value will return labels for Additional fields, context data, tag dimensions and rating dimensions. If the label is "null", it is up to developers to provide values.The
id
value can be used to uniquely identify any controls used to build the form. This is also the value developers would use as the key in the submission (i.e id=value). In the HTML it would be the value of the name attribute.The
valuesLabels
is an array of values that have been configured for the parentfield
element. An example when to use thevaluesLabels
object, is in forms that contains a drop-down list control. Programmatically a developer would iterate over the array extracting out the values and label to construct HTML. An example is shown below:"valuesLabels": { "1week": "1 week", "1month": "1 month", "3months": "3 months", "6months": "6 months", "1year": "1 year or longer" }, "autoPopulate": false, "label": "Approximately how long have you owned this product?", "id": "contextdatavalue_LengthOfOwnership", "type": "choice", "class": "cdv", "required": false },
So programmatically you could end up with something like:
"choice" is thetype
value when thevaluesLabels
array is populated.The
minLength
is configured on the Bavaarvoice side and submissions will not be allowed unless it is met. The value can be used to create client-side validation to ensure that the submission form meets the requirements as defined in the configuration. It's preferred that form contain as much validation as possible before submitting. In the sample below the Review Text must be at least 50 characters.reviewtext: { default: null, value: "", maxLength: 50000, required: false, yype: "TextAreaInput", label: null, id: "reviewtext", minLength: 50 },
⚠ERROR_FORM_TOO_SHORT
error will be returned from the API if a submission does not meet theMinLength
value.
Step 4: Submit product(s) review
By this time, the review submission form(s) should be presented to the consumer to fill out. Again, this may be a single review form or a collection of submission forms.
The significance of progressive submission is that it allows shoppers the ability to partially submit a review and then return to that review to update it up to 30 days after the initial submission. For instance, it is possible to submit a review where all the required fields are not completed, then return to that review and complete the review.
The following discussion assumes the progressive submission described below:
Product review submission forms are unique and require client-side validation that must be handled by clients.