---
updatedAt: 2026-03-30T09:19:11.000Z
agentTools:
projectIndex: https://developers.bazaarvoice.com/v1.0-PRR/llms.txt
---
# Reviews Submissions
> 🚧 Only API keys on our Conversations PRR platform are eligible to use this API version. Refer to the [Platforms](https://developer.bazaarvoice.com/conversations-api/getting-started/platform-api-concepts#platforms) section of our [Platform & API Concepts](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/platform-api-concepts) documentation to learn which platform your API keys are on.
Submit reviews on a product.
# 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 review submission form
```http URL
https://[stg.]api.bazaarvoice.com/data/submitreview.[FORMAT]?ApiVersion=[latestApiVersion]&ProductId=[productId]&PassKey=[yourKey]
```
This action may be done with an HTTP POST or GET.
## View a review submission form prepopulated with user data
```http URL
https://[stg.]api.bazaarvoice.com/data/submitreview.[FORMAT]?ApiVersion=[latestApiVersion]&ProductId=[productId]&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 review submission
```http URL
https://[stg.]api.bazaarvoice.com/data/submitreview.[FORMAT]?ApiVersion=[latestApiVersion]&ProductId=[productId]&Action=Preview&Rating=[rating]&ReviewText=[reviewText]&Title=[title]&UserNickname=[nickname]&PassKey=[yourKey]
```
This action may be done with an HTTP POST or GET.
## Submit a review
```Text URL
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=[title]&UserNickname=[nickname]&PassKey=[yourKey]&fp=[deviceFingerprint]
```
Ellipses (...) in above example indicate that your app may generate other headers.
This action must take the form of an HTTP POST.
# Headers
[block:parameters]
{
"data": {
"h-0": "Name",
"h-1": "Description",
"0-0": "`Content-Type`",
"0-1": "The media-type type of the request body. Value must be `application/x-www-form-urlencoded`. \n \n:memo: Required
This field is required in all API requests.",
"1-0": "`X-Forwarded-For`",
"1-1": "IP address of content author. This header is only necessary when performing submissions from your server. See [Authenticity Tutorial](https://developer.bazaarvoice.com/conversations-api/tutorials/authenticity) for more information. \n \nPer 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. \n \n:small_red_triangle:Alert
Failure to submit this field will result in your content being ineligible for syndication, authenticity or other business processes."
},
"cols": 2,
"rows": 2,
"align": [
"left",
"left"
]
}
[/block]
Your app may generate other headers.
# Parameters
[block:parameters]
{
"data": {
"h-0": "Name",
"h-1": "Description",
"0-0": "`[FORMAT]`",
"0-1": "Response format ([xml](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/future-deprecations) This feature will not be available or will behave differently in future versions of the Conversations API. Click for more information.
or json) \n \n:memo: Required
This field is required in all API requests.",
"1-0": "`Action`",
"1-1": "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](https://developer.bazaarvoice.com/conversations-api/getting-started/submission-fundamentals#the-action-parameter-and-the-submission-process).",
"2-0": "`AdditionalField_`",
"2-1": "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). \n \n⚠️Caution
This field may be required depending on per client configurations.",
"3-0": "`AgreedToTermsAndConditions`",
"3-1": "Boolean indicating whether or not the user agreed to the terms and conditions. Required depending on the client's settings. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"4-0": "`ApiVersion`",
"4-1": "The API version, e.g. 5.4. \n \n:memo: Required
This field is required in all API requests.",
"5-0": "`CampaignId`",
"5-1": "Arbitrary text that may be saved alongside content to indicate vehicle by which content was captured, e.g. “post-purchase email”.",
"6-0": "`Cons`",
"6-1": "Legacy free text tags allow a user to submit a delimited string of negative words or phrases. This field does not support filtering or sorting and is only available to clients with it enabled already. All other clients should use [tag dimensions](https://developer.bazaarvoice.com/conversations-api/tutorials/field-types#tags---tag-dimensions) . \n \nPRR
This feature is only available to clients on our Conversations PRR platform. [Learn more](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/conversations-prr-only-features) .
⚠️Caution
This field may be required depending on per client",
"7-0": "`ContextDataValue_`",
"7-1": "Some examples of this parameter include the following. Each is followed by possible values. \n \n- ContextDataValue\\_PurchaserRank - \"top\", \"top10\", \"top100\", \"top1000\"\n- ContextDataValue\\_Purchaser - \"yes\", \"no\"\n- ContextDataValue\\_Age - \"under21\", \"21to34\", \"35to44\", \"45to54\", \"55to64\", \"over65\"\n- ContextDataValue\\_Gender - \"male\", \"female\"
⚠️Caution
This field may be required depending on per client configurations.",
"8-0": "`fp`",
"8-1": "Fingerprint of content author's device. See the [Authenticity Tutorial](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/authenticity) for more information. \n \nPer 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. \n \n:small_red_triangle:Alert
Failure to submit this field will result in your content being ineligible for syndication, authenticity or other business processes.",
"9-0": "`HostedAuthentication_AuthenticationEmail`",
"9-1": "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](https://developers.bazaarvoice.com/docs/authenticate-user-submission) method for more information on hosted authentication. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"10-0": "`HostedAuthentication_CallbackUrl`",
"10-1": "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](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/b-mastered) tutorial for more information. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"11-0": "`IsRecommended` ",
"11-1": "Value is true or false; default is null – \"true\" or \"false\" answer to \"I would recommend this to a friend\". \n \n⚠️Caution
This field may be required depending on per client configurations.",
"12-0": "`Locale`",
"12-1": "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. \n \n:small_red_triangle:Alert
Failure to submit this field will result in your content being ineligible for syndication, authenticity or other business processes.",
"13-0": "`NetPromoterComment`",
"13-1": "Value is text representing a user comment to explain numerical Net Promoter score.",
"14-0": "`NetPromoterScore`",
"14-1": "Value is positive integer between 1 and 10 representing a numerical rating in response to “How would you rate this company?”",
"15-0": "`PassKey`",
"15-1": "API key is required to authenticate API user and check permission to access particular client's data. \n \n:memo: Required
This field is required in all API requests.",
"16-0": "`PhotoCaption_`",
"16-1": "Value is caption text for the photo URL with the same value of \\. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"17-0": "`PhotoUrl_`",
"17-1": "Value is a [Bazaarvoice URL of a photo uploaded using the Data API](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/photo-upload#image-url) , where \\ is a non-negative integer. See our [photo upload tutorial](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/photo-upload) for more information. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"18-0": "`ProductId`",
"18-1": "The ID of the product that this content is being submitted on. \n \n:memo: Required
This field is required in all API requests.",
"19-0": "`ProductRecommendationId_`",
"19-1": "Value is non-negative integer representing the product external ID of the \\'th product recommendation (for Social Recommendations). \n \nPRR
This feature is only available to clients on our Conversations PRR platform. [Learn more](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/conversations-prr-only-features) .",
"20-0": "`Pros`",
"20-1": "Legacy free text tags allow a user to submit a delimited string of positive words or phrases. This field does not support filtering or sorting and is only available to clients with it enabled already. All other clients should use [tag dimensions](https://developer.bazaarvoice.com/conversations-api/tutorials/field-types#tags---tag-dimensions) . \n \nPRR
This feature is only available to clients on our Conversations PRR platform. [Learn more](https://developer.bazaarvoice.com/conversations-api/deprecations/conversations-prr-only-features) .
⚠️Caution
This field may be required depending on per client configurations.",
"21-0": "`Rating`",
"21-1": "Value is positive integer between 1 and 5, and represents review overall rating. Required depending on client settings. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"22-0": "`Rating_`",
"22-1": "A concrete example might be Rating\\_Quality where the value would represent the user's opinion of the quality of the product. The value is a positive integer between 1 and 5 and represents rating dimension value. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"23-0": "`ReviewText`",
"23-1": "Value is review body text. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"24-0": "`SendEmailAlertWhenCommented`",
"24-1": "Boolean indicating whether or not the user wants to be notified when a comment is posted on the content.",
"25-0": "`SendEmailAlertWhenPublished`",
"25-1": "Boolean indicating whether or not the user wants to be notified when his/her content is published.",
"26-0": "`tag__`",
"26-1": "A concrete example of the parameter might be 'tag\\_Pro\\_1'. Valid values could be any free-form text. \\ should be a non-negative integer starting at the number 1.",
"27-0": "`tagid_/`",
"27-1": "Boolean indicating whether or not the tag applies to the user. A concrete example might be 'tagid\\_Pro/EasyToUse=true'. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"28-0": "`Title`",
"28-1": "Value is content title text. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"29-0": "`User`",
"29-1": "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](https://developers.bazaarvoice.com/docs/authenticate-user-submission) method for more information. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"30-0": "`UserEmail`",
"30-1": "User's email address. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"31-0": "`UserId`",
"31-1": "User's external ID. This value should come from your authentication system. See [Client-Mastered Authentication](/conversations-api/tutorials/submission/authentication/client-mastered) for more information. \n \n:small_red_triangle:Alert
Do not use an email address for this value.
⚠️Caution
This field may be required depending on per client configurations.",
"32-0": "`UserLocation`",
"32-1": "User location text. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"33-0": "`UserNickname`",
"33-1": "User nickname display text. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"34-0": "`VideoCaption_`",
"34-1": "Value is caption text for the video URL with the same value of \\. \n \n⚠️Caution
This field may be required depending on per client configurations.",
"35-0": "`VideoUrl_`",
"35-1": "Value is valid URL to a YouTube video or a Bazaarvoice [hosted video](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/conversations-prr-only-features)This feature is only available to clients on our Conversations PRR platform. Click for more information.
where \\ is a non-negative integer. \n \n⚠️Caution
This field may be required depending on per client configurations."
},
"cols": 2,
"rows": 36,
"align": [
"left",
"left"
]
}
[/block]
# Response format
> 🚧 Do not reuse the API passkey below in your application.
Preview a review submission:
```http URL
https://stg.api.bazaarvoice.com/data/submitreview.json?apiversion=5.4&ProductId=1000001&passkey=2cpdrhohmgmwfz8vqyo48f52g&Action=Preview
```
The following is an example of a review submission response after submitting the form by HTTP POST:
```json
{
"Data":{},
"HasErrors":false,
"Form":[],
"FormErrors":{},
"TypicalHoursToPost":72,
"SubmissionId":"3bjfuudsrjt516vitpvwnqrli",
"Review":{
"SendEmailAlertWhenPublished":false,
"SendEmailAlertWhenCommented":false,
"SubmissionTime":"2011-11-16T13:51:01.196-00:00",
"Rating":5,
"IsRecommended":false,
"ReviewText":"testtesttesttesttesttestesttest",
"TypicalHoursToPost":null,
"Id":null,
"SubmissionId":null,
"Title":"This product is really nifty"
},
"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. |
| `TypicalHoursToPost` | Usual time it takes for the content to get posted. |
| `SubmissionId` | Unique submission event ID referring to successful submission events such as submission, update, and others |
| `Review` | Section containing the review data. |
| `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_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_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_MISSING_SUBJECT_ID` | Submission is missing a product to submit against. A product id is REQUIRED for review submissions. |
| `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. |