Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Story Submit - v5.4 (PRR)
Refer to Conversations PRR Only Features for more information.
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
Submit stories on a product or a category.
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
View a story submission form for a particular product
http://[stg.]api.bazaarvoice.com/data/submitstory.[FORMAT]?ApiVersion=[latestApiVersion]&PassKey=[yourKey]&ProductId=[productId]
This action may be done with an HTTP POST or GET.
View a story submission form for a particular product prepopulated with existing user data
http://[stg.]api.bazaarvoice.com/data/submitstory.[FORMAT]?ApiVersion=[latestApiVersion]&PassKey=[yourKey]&ProductId=[productId]&User|UserId=[valueOfUserOrUserId]
View a story submission form for a particular category
http://[stg.]api.bazaarvoice.com/data/submitstory.[FORMAT]?ApiVersion=[latestApiVersion]&PassKey=[yourKey]&CategoryId=[categoryId]
This action may be done with an HTTP POST or GET.
View a story submission form for a particular category prepopulated with existing user data
http://[stg.]api.bazaarvoice.com/data/submitstory.[FORMAT]?ApiVersion=[latestApiVersion]&PassKey=[yourKey]&CategoryId=[categoryId]&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 story submission
http://[stg.]api.bazaarvoice.com/data/submitstory.[FORMAT]?ApiVersion=[latestApiVersion]&PassKey=[yourKey]&ProductId=[productId]&Action=preview&StoryText=[storyText]&Title=[storyTitle]
This action may be done with an HTTP POST or GET.
Submit a story
POST /data/submitstory.[FORMAT] HTTP/1.1 Host: [stg.]api.bazaarvoice.com Content-Type: application/x-www-form-urlencoded X-Forwarded-For: [AuthorIPAddress] ... ApiVersion=[latestApiVersion]&PassKey=[yourKey]&Action=submit&CategoryId=[categoryId]&Title=[title]&StoryText=[storyText]&fp=[deviceFingerprint]
Ellipses (...) in above example indicate that your app may generate other headers.
Stories must be submitted on a product or category and take the form of an HTTP POST.
Headers
Name | Description | Additional info | |
---|---|---|---|
Content-Type |
The media-type type of the request body. Value must be application/x-www-form-urlencoded . |
API | |
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. |
Business |
Your app may generate other headers.
Parameters
Name | Description | Additional Info |
---|---|---|
ApiVersion |
The API version, e.g. 5.4. | API |
[FORMAT] |
Response format (xml or json) | API |
PassKey |
API key is required to authenticate API user and check permission to access particular client's data. | API |
Action |
The submission action to take -- either 'Preview' or 'Submit'. 'Preview' will show a draft of the content to be submitted; 'Submit' will submit the content. Note that if Action=Submit, the request must be an HTTP POST. | |
AdditionalField_<Dimension-External-Id> |
A concrete example of the parameter might be 'AdditionalField_Seat' with a value of '24F' (describing the seat number at a stadium or on a plane). | Configuration |
AgreedToTermsAndConditions |
Boolean indicating whether or not the user agreed to the terms and conditions. Required depending on the client's settings. | Configuration |
Callback |
Callback function name used with JSONP. Value is a string consisting of the following characters: a-z,A-Z,0-9,_ (excluding comma). See the JSONP tutorial for more information. |
|
CampaignId |
Arbitrary text that may be saved alongside content to indicate vehicle by which content was captured, e.g. “post-purchase email”. | |
CategoryId |
The id of the category that this content is being submitted on. One of ProductId or CategoryId must be provided. | |
ContextDataValue_<Dimension-External-Id> |
Some examples of this parameter include the following. Each is followed by possible values.
|
Configuration |
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. |
Business |
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. | Configuration |
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 Bazaarvoice-Mastered Authentication tutorial for more information. | Configuration |
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. | Business |
ProductId |
The id of the product that this content is being submitted on. One of ProductId or CategoryId must be provided. | |
PhotoCaption_<n> |
Value is caption text for the photo URL with the same value of <n>. | Configuration |
PhotoUrl_<n> |
Value is a Bazaarvoice URL of a photo uploaded using the Data API, where <n> is a non-negative integer. | Configuration |
ProductRecommendationId_<n> |
Value is non-negative integer representing the product external ID of the <n>'th product recommendation (for Social Recommendations) | |
SendEmailAlertWhenPublished |
Boolean indicating whether or not the user wants to be notified when his/her content is published. | |
SendEmailAlertWhenCommented |
Boolean indicating whether or not the user wants to be notified when a comment is posted on the content. | |
StoryText |
The text of the story | Configuration |
tag_<Dimension-External-Id>_<n> |
A concrete example of the parameter might be 'tag_Pro_1'. Valid values could be any free-form text. <n> should be a non-negative integer starting at the number 1. | |
tagid_<Dimension-External-Id>/<Tag-Label> |
Boolean indicating whether or not the tag applies to the user. A concrete example might be 'tagid_Pro/EasyToUse=true'. | Configuration |
Title |
Value is content title text. | Configuration |
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. | Configuration |
UserEmail |
User's email address | Configuration |
UserId |
User's external ID. Do not use email addresses for this value. | Configuration |
UserLocation |
User location text | Configuration |
UserNickname |
User nickname display text | Configuration |
VideoCaption_<n> |
Value is caption text for the video URL with the same value of <n>. | Configuration |
VideoUrl_<n> |
Value is valid YouTube or Bazaarvoice video-upload URL where <n> is a non-negative integer. | Configuration |
Response format
Preview a story submission to the product with id value "971":
The following is an example of a Story Submission response after submitting the form by HTTP POST:
{ "Story":{ "SendEmailAlertWhenPublished":false, "SendEmailAlertWhenCommented":false, "SubmissionTime":"2011-11-16T13:51:01.196-00:00", "Id":null, "SubmissionId":null, "StoryText":"texttexttexttexttexttexttexttext", "Title":"StoryTitle StoryTitle StoryTitle", }, "Data":{}, "HasErrors":false, "Form":[], "FormErrors":{}, "TypicalHoursToPost":72, "SubmissionId":"em3a1hwkz2bbhze", "Locale":"en_US", "Errors":[] }
Response elements
Name | Description |
---|---|
Data |
Section containing the fields and field groups
|
Errors |
Error section is populated instead of other fields if there is an error with a query syntax or problem executing a query.
|
Form |
Section containing an array of field and group references
|
Story |
Section containing the story data
|
TypicalHoursToPost |
Usual time it takes for the content to get posted
|
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 |
Either a product id or category id must be specified, not both. |
ERROR_PARAM_MISSING_SUBJECT_ID |
Submission is missing a subject (either a product or category) to submit against. A subject id is REQUIRED for submissions. Either a product id or category id must be specified, not both. |
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. |
Use either the User or UserId parameter depending on your API key configuration. This action may be done with an HTTP POST or GET.