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

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)

Submit a comment on a review.

Overview

Submission is divided into the following three HTTP operations controlled by the Action parameter:

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

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

Examples

The following examples demonstrate common Conversations API submission requests. For a complete overview of using the Conversations API to display data, refer to the Submission tutorials.

View a comment submission form

https://[stg.]api.bazaarvoice.com/data/submitreviewcomment.[FORMAT]?ApiVersion=[latestApiVersion]&ReviewId=[reviewId]&UserId=[userId]&PassKey=[yourKey]

ReviewId is required for all review comment submissions. This action may be done with an HTTP POST or GET.

View a comment submission form prepopulated with user data

https://[stg.]api.bazaarvoice.com/data/submitreviewcomment.[FORMAT]?ApiVersion=[latestApiVersion]&ReviewId=[reviewId]&PassKey=[yourKey]&User|UserId=[valueOfUserOrUserId]

Use either the User or UserId parameter depending on your API key configuration. This action may be done with an HTTP POST or GET.

Preview a comment submission

https://[stg.]api.bazaarvoice.com/data/submitreviewcomment.[FORMAT]?ApiVersion=[latestApiVersion]&ReviewId=[reviewId]&Action=preview&CommentText=[yourCommentText]&UserId=[userId]&PassKey=[yourKey]

A ReviewId is required for all review comment submissions. This action may be done with an HTTP POST or GET.

Submit a comment

POST /data/submitreviewcomment.[FORMAT] HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/x-www-form-urlencoded
X-Forwarded-For: [AuthorIPAddress]
...

ApiVersion=[latestApiVersion]&ReviewId=[reviewId]&Action=submit&CommentText=[yourCommentText]&UserId=[userId]&PassKey=[yourKey]&fp=[deviceFingerprint]

Ellipses (...) in above examples indicate that your app may generate other headers.

A ReviewId is required for all review comment submissions. This action must be done with HTTP POST.

Headers

Name Description
Content-Type

The media-type type of the request body. Value must be application/x-www-form-urlencoded.

Required This field is required in all API requests.

X-Forwarded-For

IP address of content author. This header is only necessary when performing submissions from your server. See Authenticity Tutorial for more information.

Per the Bazaarvoice Authenticity Policy, you must send author IP address attached to each submission. If you fail to send author IP address 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.

Alert Failure to submit this field will result in your content being ineligible for syndication, authenticity or other business processes.

Your app may generate other headers.

Parameters

Name Description
[FORMAT]

Response format (json)

Required This field is required in all API requests.

Action

The submission action to take -- either 'Action=', 'Action=Preview' or 'Action=Submit'. 'Action=' will show information that can be used to build a submission form, 'Action=Preview' will show a draft of the content to be submitted; 'Action=Submit' will submit the content. If 'Action=Submit', the request must be an HTTP POST. Learn more.

ApiVersion

The API version, e.g. 5.4.

Required This field is required in all API requests.

CommentText

Contains the text of the comment.

Required This field is required in all API requests.

CampaignId

Arbitrary text that may be saved alongside content to indicate vehicle by which content was captured, e.g. “post-purchase email”.

fp

Fingerprint of content author's device. See the Authenticity Tutorial for more information.

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.

Alert Failure to submit this field will result in your content being ineligible for syndication, authenticity or other business processes.

HostedAuthentication_AuthenticationEmail

Email address where the submitter will receive the confirmation email. If you are configured to use hosted email authentication, this parameter is required. See the Authenticate User method for more information on hosted authentication.

Caution This field may be required depending on per client configurations.

HostedAuthentication_CallbackUrl

URL of the link contained in the user authentication email. This should point to a landing page where a web application exists to complete the user authentication process. The host for the URL must be one of the domains configured for the client. The link in the email will contain a user authentication token (authtoken) that is used to verify the submitter. If you are configured to use hosted email authentication, this parameter is required. See the hosted authentication tutorial for more information.

Caution This field may be required depending on per client configurations.

Locale

Locale to display Labels, Configuration, Product Attributes and Category Attributes in. The default value is the locale defined in the display associated with the API key.

Alert Failure to submit this field will result in your content being ineligible for syndication, authenticity or other business processes.

PassKey

API key is required to authenticate API user and check permission to access particular client's data.

Required This field is required in all API requests.

ReviewId

The id of the review that this comment is being submitted on. Required for review comments.

Required This field is required in all API requests.

SendEmailAlertWhenPublished

Boolean indicating whether or not the user wants to be notified when his/her content is published.

Title

Value is content title text.

Caution This field may be required depending on per client configurations.

User

Value of the encrypted user. This parameter demonstrates that a user has been authenticated. Note that the UserId parameter does not contain authentication information and should not be used for hosted authentication. See the Authenticate User method for more information.

Caution This field may be required depending on per client configurations.

UserEmail

User's email address.

Caution This field may be required depending on per client configurations.

UserId

User's external ID. This value should come from your authentication system. See Client-Mastered Authentication for more information.

Alert Do not use an email address for this value.

Caution This field may be required depending on per client configurations.

UserLocation

User location text

Caution This field may be required depending on per client configurations.

UserNickname

User nickname display text.

Caution This field may be required depending on per client configurations.

Response format

Do not reuse the API passkey below in your application.

Preview a comment submission:

https://stg.api.bazaarvoice.com/data/submitreviewcomment.json?apiversion=5.4&ReviewId=16970607&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&action=preview

The following is an example of a comment submission response after submitting the form by HTTP POST:

{
   "Data":{},
   "HasErrors":false,
   "Form":[],
   "FormErrors":{},
   "TypicalHoursToPost":72,
   "Comment":{
     "SendEmailAlertWhenPublished":false,
     "SubmissionTime":"2011-11-16T13:51:01.196-00:00",
     "TypicalHoursToPost":null,
     "Id":null,
     "SubmissionId":null,
     "CommentText":"texttexttexttexttexttexttexttext"
   },
   "SubmissionId":"acshmx7d74fgvdenwo4zgat19",
   "Locale":"en_US",
   "Errors":[]
}

Response elements

Name Description
Data

Section containing the fields and field groups.

HasErrors

Boolean value indicating if there are errors present.

Form

Section containing an array of field and group references.

FormErrors

Section containing an object whose properties represent user input errors. For example, failure to submit the minimum required characters for a particular field.

Comment

Section containing the comment data.

TypicalHoursToPost

Usual time it takes for the content to get posted.

SubmissionId

Unique ID assigned to content when submission is successful. This value can be used to look up content later.

Locale

The locale that will be associated with this submission.

Errors

Error section is populated instead of other fields if there is an error with a query syntax or problem executing a query.

Error codes

Value Description
ERROR_ACCESS_DENIED

Insufficient privileges to perform the operation

ERROR_FORM_DUPLICATE

The nickname is already in use.

ERROR_FORM_DUPLICATE_NICKNAME

The nickname is already in use.

ERROR_FORM_EMOJI

Emoji are not supported.

ERROR_FORM_INVALID_EMAILADDRESS

Email address is not in the proper format.

ERROR_FORM_INVALID_IPADDRESS

The IP address is invalid.

ERROR_FORM_INVALID_OPTION

The selected option has been removed.

ERROR_FORM_PATTERN_MISMATCH

This field is not in the correct format.

ERROR_FORM_PROFANITY

The content contains inappropriate language.

ERROR_FORM_REJECTED

The submission was rejected.

ERROR_FORM_REQUIRED

A required field was not supplied.

ERROR_FORM_REQUIRED_EITHER

Both of the required hosted authentication parameters are missing.

ERROR_FORM_REQUIRED_NICKNAME

You must enter a nickname.

ERROR_FORM_REQUIRES_TRUE

A field requires a value of true. (e.g., "You must agree to the terms and conditions.")

ERROR_FORM_RESTRICTED

Content provider's age is too young. (e.g., "Content cannot be accepted from minors under age 13.")

ERROR_FORM_STORAGE_PROVIDER_FAILED

The uploaded file could not be stored. Try uploading again later.

ERROR_FORM_SUBMITTED_NICKNAME

This nickname has already been submitted.

ERROR_FORM_TOO_FEW

There must be a minimum number of items contributed for this field.

ERROR_FORM_TOO_HIGH

This field has too many items.

ERROR_FORM_TOO_LONG

The field has too many characters.

ERROR_FORM_TOO_LOW

This field has too few items.

ERROR_FORM_TOO_SHORT

The field doesn't have enough characters.

ERROR_FORM_UPLOAD_IO

The item could not be uploaded. Ensure that it is a valid file type.

ERROR_PARAM_DUPLICATE_SUBMISSION

Duplicate submissions are not allowed for this client

ERROR_PARAM_INVALID_API_KEY

Invalid API Key value

ERROR_PARAM_INVALID_LOCALE

Invalid locale code

ERROR_PARAM_INVALID_PARAMETERS

Invalid parameter in content submission

ERROR_PARAM_INVALID_SUBJECT_ID

A review id must be specified, but not both, since comments can only be submitted on a review.

ERROR_PARAM_MISSING_SUBJECT_ID

Submission is missing a review to submit against. A review id must be specified.

ERROR_PARAM_MISSING_USER_ID

This client does not allow unauthenticated submissions. A valid UserId is required.

ERROR_REQUEST_LIMIT_REACHED

Rate limiting error, i.e. too many requests per time interval

ERROR_UNKNOWN

Unknown error (internal server error, for instance)

ERROR_UNSUPPORTED

For unsupported features, clients etc.