Answers Submissions

๐Ÿšง

Only API keys on our Conversations PRR 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.

Submit answers on questions.

Overview

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

ActionDescriptionHTTP Method
Action=Response represents fields necessary to create a submission form. The Action parameter is optional for this operation.GET, POST
Action=PreviewUsed to validate a submission. Response will include errors on failure. Data will not be stored.GET, POST
Action=SubmitOn 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 an answer submission form

https://[stg.]api.bazaarvoice.com/data/submitanswer.json?ApiVersion=[latestApiVersion]&QuestionId=[questionId]&UserId=[userId]&PassKey=[yourKey]

A QuestionId is required for all answer submissions. This action may be done with an HTTP POST or GET.

View an answer submission form prepopulated with user data

https://[stg.]api.bazaarvoice.com/data/submitanswer.[FORMAT]?ApiVersion=[latestApiVersion]&QuestionId=[questionId]&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 an answer submission

https://[stg.]api.bazaarvoice.com/data/submitanswer.json?ApiVersion=[latestApiVersion]&QuestionId=[questionId]&Action=preview&AnswerText=[answerText]&UserId=[userId]&PassKey=[yourKey]

A QuestionId is required for all answer submissions. This action may be done with an HTTP POST or GET.

Submit an answer

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

ApiVersion=[latestApiVersion]&QuestionId=[questionId]&Action=submit&AnswerText=[answerText]&UserId=[userId]&PassKey=[yourKey]&fp=[deviceFingerPrint]

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

A QuestionId is required for all answer submissions. Answers must be submitted on a question and take the form of an HTTP POST.

Headers

NameDescription
Content-TypeThe 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-ForIP 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

NameDescription
[FORMAT]Response format (
xml This feature will not be available or will behave differently in future versions of the Conversations API. Click for more information.
or json)

๐Ÿ“
Required
This field is required in all API requests.
ActionThe 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.
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).

PRR
This feature is only available to clients on our Conversations PRR platform. Learn more.

โš ๏ธ
Caution
This field may be required depending on per client configurations.
AgreedToTermsAndConditionsBoolean indicating whether or not the user agreed to the terms and conditions. Required depending on the client's settings.

โš ๏ธ
Caution
This field may be required depending on per client configurations.
AnswerTextContains the text of the answer.

๐Ÿ“
Required
This field is required in all API requests.
ApiVersionThe API version, e.g. 5.4.

๐Ÿ“
Required
This field is required in all API requests.
CampaignIdArbitrary text that may be saved alongside content to indicate vehicle by which content was captured, e.g. โ€œpost-purchase emailโ€.
ContextDataValue_<Dimension-External-Id>Some examples of this parameter include the following. Each is followed by possible values.

- ContextDataValue_PurchaserRank - "top", "top10", "top100", "top1000"
- ContextDataValue_Purchaser - "yes", "no"
- ContextDataValue_Age - "under21", "21to34", "35to44", "45to54", "55to64", "over65"
- ContextDataValue_Gender - "male", "female"

โš ๏ธ
Caution
This field may be required depending on per client configurations.


PRR
This feature is only available to clients on our Conversations PRR platform. Learn more .
fpFingerprint 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_AuthenticationEmailEmail 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_CallbackUrlURL 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.
LocaleLocale 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.
PassKeyAPI 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.
PhotoCaption_<n>Value is caption text for the photo URL with the same value of <n>.

โš ๏ธ
Caution
This field may be required depending on per client configurations.
PhotoUrl_<n>Value is a Bazaarvoice URL of a photo uploaded using the Data API , where <n> is a non-negative integer. See our photo upload tutorial for more information.

โš ๏ธ
Caution
This field may be required depending on per client configurations.
ProductRecommendationId_<n>Value is non-negative integer representing the product external ID of the <n>'th product recommendation (for Social Recommendations).

PRR
This feature is only available to clients on our Conversations PRR platform. Learn more .
QuestionIdThe id of the question that this answer is being submitted on.

๐Ÿ“
Required
This field is required in all API requests.
SendEmailAlertWhenPublishedBoolean indicating whether or not the user wants to be notified when his/her content is published.
UserValue 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.
UserEmailUser's email address.

โš ๏ธ
Caution
This field may be required depending on per client configurations.
UserIdUser'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.
UserLocationUser location text.

โš ๏ธ
Caution
This field may be required depending on per client configurations.
UserNicknameUser nickname display text.

โš ๏ธ
Caution
This field may be required depending on per client configurations.
VideoCaption_<n>Value is caption text for the video URL with the same value of <n>.

PRR
This feature is only available to clients on our Conversations PRR platform. Learn more.

โš ๏ธ
Caution
This field may be required depending on per client configurations.
VideoUrl_<n>Value is valid URL to a YouTube video or a Bazaarvoice
hosted video This feature is only available to clients on our Conversations PRR platform. Click for more information.
where <n> is a non-negative integer.

PRR
This feature is only available to clients on our Conversations PRR platform. Learn more.

โš ๏ธ
Caution
This field may be required depending on per client configurations.

Response format

๐Ÿšง

Do not reuse the API passkey below in your application.

Preview an answer submission:

https://stg.api.bazaarvoice.com/data/submitanswer.json?apiversion=5.4&QuestionId=6104&passkey=2cpdrhohmgmwfz8vqyo48f52g&action=preview

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

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

Response elements

NameDescription
DataSection containing the fields and field groups.
HasErrorsBoolean value indicating if there are errors present.
FormSection containing an array of field and group references.
FormErrorsSection containing an object whose properties represent user input errors. For example, failure to submit the minimum required characters for a particular field.
TypicalHoursToPostUsual time it takes for the content to get posted.
SubmissionIdUnique submission event ID referring to successful submission events such as submission, update, and others
AnswerSection containing the answer data.
LocaleThe locale that will be associated with this submission.
ErrorsError section is populated instead of other fields if there is an error with a query syntax or problem executing a query.

Error codes

ValueDescription
ERROR_ACCESS_DENIEDInsufficient privileges to perform the operation
ERROR_FORM_DUPLICATEThe nickname is already in use.
ERROR_FORM_DUPLICATE_NICKNAMEThe nickname is already in use.
ERROR_FORM_EMOJIEmoji are not supported.
ERROR_FORM_INVALID_EMAILADDRESSEmail address is not in the proper format.
ERROR_FORM_INVALID_IPADDRESSThe IP address is invalid.
ERROR_FORM_INVALID_OPTIONThe selected option has been removed.
ERROR_FORM_PATTERN_MISMATCHThis field is not in the correct format.
ERROR_FORM_PROFANITYThe content contains inappropriate language.
ERROR_FORM_REJECTEDThe submission was rejected.
ERROR_FORM_REQUIREDA required field was not supplied.
ERROR_FORM_REQUIRED_EITHERBoth of the required hosted authentication parameters are missing.
ERROR_FORM_REQUIRED_NICKNAMEYou must enter a nickname.
ERROR_FORM_REQUIRES_TRUEA field requires a value of true. (e.g., "You must agree to the terms and conditions.")
ERROR_FORM_RESTRICTEDContent provider's age is too young. (e.g., "Content cannot be accepted from minors under age 13.")
ERROR_FORM_STORAGE_PROVIDER_FAILEDThe uploaded file could not be stored. Try uploading again later.
ERROR_FORM_TOO_FEWThere must be a minimum number of items contributed for this field.
ERROR_FORM_TOO_HIGHThis field has too many items.
ERROR_FORM_TOO_LONGThe field has too many characters.
ERROR_FORM_TOO_LOWThis field has too few items.
ERROR_FORM_TOO_SHORTThe field doesn't have enough characters.
ERROR_FORM_UPLOAD_IOThe item could not be uploaded. Ensure that it is a valid file type.
ERROR_PARAM_DUPLICATE_SUBMISSIONDuplicate submissions are not allowed for this client
ERROR_PARAM_INVALID_API_KEYInvalid API Key value
ERROR_PARAM_INVALID_LOCALEInvalid locale code
ERROR_PARAM_INVALID_PARAMETERSInvalid parameter in content submission
ERROR_PARAM_INVALID_SUBJECT_IDA question id must be specified since answers can only be submitted on questions.
ERROR_PARAM_MISSING_SUBJECT_IDSubmission is missing a question to submit against. A question id is REQUIRED for answer submissions.
ERROR_PARAM_MISSING_USER_IDThis client does not allow unauthenticated submissions. A valid UserId is required.
ERROR_REQUEST_LIMIT_REACHEDRate limiting error, i.e. too many requests per time interval
ERROR_UNKNOWNUnknown error (internal server error, for instance)
ERROR_UNSUPPORTEDFor unsupported features, clients etc.