Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Progressive Submission
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
Supports obtaining multiple review forms at once and submitting parts of a review as a user provides content.
Overview
Progressive Submission is comprised of the following two endpoints: initiateSubmit
and progressiveSubmit
. initiateSubmit
returns data to assist in building the product's submission form. progressiveSubmit
supports submitting consumer generated content on a single product. The ability to continue a submission (or edit) is limited to 30 days after the first submission of content.
Environments
The following environments are supported:
Environment | Domain | Description |
---|---|---|
Staging |
|
Used while developing your application. |
Production |
|
Used when your application is complete. |
Initiate Submit
The initiateSubmit
endpoint is used to request product info for building review submission form(s). This action must be done with an HTTP POST.
URL pattern
The following example demonstrates the basic URL pattern for the initiateSubmit
endpoint.
https://[stg].api.bazaarvoice.com/data/initiateSubmit.{FORMAT}?passkey={CONVERSATIONS_API_PASSKEY}&apiVersion={latestApiVersion}
Submitting an initiateSubmit request
POST /data/initiateSubmit.{FORMAT}?passkey={CONVERSATIONS_API_PASSKEY}&apiVersion={latestApiVersion} HTTP/1.1 Host: [stg.]api.bazaarvoice.com Content-Type: application/json X-Forwarded-For: [AuthorIPAddress] … { "locale": "en_US", "userToken": "{SOME_USER_TOKEN}", "productIds": [ "Product1", "ProductZ" ] }
Ellipses (…) in above example indicate that your app may generate other headers.
Parameters
Name | Description | Required |
---|---|---|
format |
Data format (should be json) |
Yes |
QueryString |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
Latest version of the API for the request (should be 5.4). |
Yes |
extended |
This parameter is sent as a single key and does not need a value. When omitted, the When included, |
No |
Header |
||
Content-Type |
application/json |
Yes |
Body |
||
productIds |
Array of productId(s) for which to return submission form and check for previous submissions. 20 or less is recommended. |
Yes |
userToken |
Authenticated user data. Fields can instead be sent in post body. |
No |
userId |
Unique id for user. Can be encoded in |
Yes* |
locale |
Locale for content |
Yes |
deviceFingerprint |
Unique identifier for author's device. Read more about deviceFingerprint |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
Response format
POST an initiateSubmit
request with two productIds:
curl -X POST \ 'http://stg.api.bazaarvoice.com/data/initiateSubmit.json?passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&apiVersion=5.4' \ -H 'Content-Type: application/json' \ ... { "locale": "en_US", "userId": "demo", "productIds": [ "wsd005c", "wbk003xl" ] }
Ellipses (…) in above example indicate that your app may generate other content.
The following response is a sample from a HTTP POST to the initiateSubmit
endpoint:
{ "hasErrors": false, "response": { "userNickname": "SOME_USER_NICKNAME", "productFormData": { "wsd005c": { "review": { "submissionID": "qbk13gsqk9ffyqbwhs2y51m2z", "productExternalID": "wbk003xl", "submissionTime": "2019-08-06@20:43:47" }, "fieldsOrder": [ "rating", "title", "reviewtext", .... ], "fields": { "rating": { "required": true, "id": "rating", "type": "integer", "class": "rating" }, "title": { "required": true, "id": "title", "maxLength": 50, "type": "text", "class": "title" }, "reviewtext": { "required": true, "id": "reviewtext", "minLength": 50, "type": "text", "class": "reviewtext" }, "Gender": { "valuesLabels": { "Male": "Male", "Female": "Female" }, "autoPopulate": true, "label": "What is your gender?", "id": "contextdatavalue_Gender", "type": "choice", "class": "cdv", "required": false }, ... }, "submissionSessionToken": "qbk13gsqk9ffyqbwhs2y51m2z_caa2ab8becea612e79d7c5abe31de4877267d744ac3f157816bb55e1aef2037c_X2E6cHCr5bs=" }, "wbk003xl": { "review": { "submissionID": "q2wxet06q1xfp6onq906uze57", "productExternalID": "wsd005c", "submissionTime": "2019-08-06@20:43:47", "isFromSubmitDB": true }, "fieldsOrder": [ "rating", "title", "reviewtext", .... ], "fields": { "rating": { "id": "rating", "type": "integer", "class": "rating" }, "title": { "required": true, "id": "title", "maxLength": 50, "type": "text", "class": "title" } "reviewtext": { "required": true, "id": "reviewtext", "minLength": 50, "type": "text", "class": "reviewtext" }, "Gender": { "valuesLabels": { "Male": "Male", "Female": "Female" }, "autoPopulate": true, "label": "What is your gender?", "id": "contextdatavalue_Gender", "type": "choice", "class": "cdv", "required": false }, ... }, "submissionSessionToken": "q2wxet06q1xfp6onq906uze57_4a4e35f8a38ad43859fe5433c8bdeb4c7e1bfff0944252a8b866b44c4114e5ac_JKAYiolGI+g=" } } } }
Ellipses (…) in above example indicate that your app may generate additional content.
Response elements
Key | Value |
---|---|
response |
Dictionary containing "productFormData" (see below). Only present when request is successful. |
hasErrors |
Boolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics. |
errors |
List of error dictionaries, containing the keys "code", "message", and "field". Only present when the request fails. |
productFormData is a dictionary of dictionaries, with keys matching "productIds" sent in the request body, and values defined as follows:
Key | Value |
---|---|
review |
A dictionary representation of the current state of the review, used to fill out form fields with existing user data. Contains |
fieldsOrder |
A list of strings indicating an order for the fields definitions in "fields". |
fields |
A dictionary of form fields for a review form. Format depends on whether "extended" parameter is set. |
submissionSessionToken |
Unique token id required for |
*expired=true indicates that the prior review content is not eligible for editing becuase it is older than 30 days. Attempts to submit updates will result in a duplicate submission error. expired
is absent when the value is false.
Progressive Submit
The progressiveSubmit
endpoint is for handling progressive submissions. Each progressiveSubmit
call represents a complete revision of prior submissions. Blank fields will overwrite previously completed ones. This action must be done with an HTTP POST.
URL pattern
The following example demonstrates the basic URL pattern for the progressiveSubmit
endpoint.
https://[stg].api.bazaarvoice.com/data/progressiveSubmit.{FORMAT}?passkey={CONVERSATIONS_API_PASSKEY}&apiVersion={latestApiVersion}
Submitting a progressiveSubmit request
POST /data/progressiveSubmit.{FORMAT}?passkey={CONVERSATIONS_API_PASSKEY}&apiVersion={latestApiVersion} HTTP/1.1 Content-Type: application/json Host: [stg.]api.bazaarvoice.com X-Forwarded-For: [AuthorIPAddress] … { "locale":"en_US", "userId": "demo", "submissionSessionToken": "i7o0099rqklkgpxtbv6137n2x_5a66c65c494a682cb14cbd7642a760514f0baec1696207da5a11c45405cf5d91", "productId":"wbk003xl", "useremail":"test@test.com", "submissionFields":{ "rating":"5", "agreedtotermsandconditions":"true", "title":"This is a great product ", ... } }
Ellipses (…) in above example indicate that your app may generate other content.
Parameters
Name | Description | Required |
---|---|---|
format |
Data format (should be json) |
Yes |
QueryString |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
Latest version of the API for the request (should be 5.4). |
Yes |
fields |
Included to indicate that form fields, as from initiateSubmit, should be returned along with the response. This parameter is sent as a single key and does not need a value. |
No |
preview |
Included to indicate that the API should not submit and instead return a display representation of the review. Read more about correct usage. This parameter is sent as a single key and does not need a value. |
No |
Header |
||
Content-Type |
application/json |
Yes |
Body |
||
productId |
A single productId for review or review form. |
Yes |
submissionSessionToken |
Unique token id required for |
Yes |
locale |
Locale for translated product dimensions. |
Yes |
userToken |
Authenticated user data. Fields can instead be sent in post body. See the hosted authentication documentation in the Appendix for for additional considerations. |
No |
userId |
Unique id for user. Can be encoded in |
Yes* |
useremail |
Email address for user. Can either be sent separately at this level, or be encoded in UserToken. |
Yes* |
deviceFingerprint |
Unique identifier for author's device. |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
submissionFields |
Key value pairs for submitted fields on submission form. Data varies per API key configurations. |
No |
Response format
POST a progressiveSubmit
request:
curl -X POST \ 'http://stg.api.bazaarvoice.com/data/progressiveSubmit.json?passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&apiVersion=5.4&Action=submit' \ -H 'Content-Type: application/json' \ -d '{ "locale":"en_US", "userId": "tom", "submissionSessionToken": "{some_Token_Value}", "productId":"1000001", "useremail":"foo@bazaarvoice.com", "submissionFields":{ "rating":"5", "agreedtotermsandconditions":"true", "title": "This is some title", "reviewtext": "This is some review text. This is some review text. This is some review text. This is some review text. This is some review text. This is some review text. This is some review text.", "usernickname": "largeMouthBass" } }'
The following response is a sample from a HTTP POST to the progressiveSubmit
endpoint:
{ "hasErrors": false, "response": { "review": { "SendEmailAlertWhenCommented": false, "Rating": 5, "SubmissionTime": "2019-08-07T21:45:12.051+00:00", "ReviewText": "this is some title this is some title this is some title this is some title this is some title this is some title this is some title", "Title": "this is some title", "SendEmailAlertWhenPublished": false }, "submissionId": "h7jcqg70gil5ggqcfqs3ru7bt", "isFormComplete": true, "submissionSessionToken": "h3fh0cbwjgyoud7ncqtgb6nd8_eebf6f276a745e1d0323bab2e143ecf14e92f8103ea9509c3e40ebef88de1380_laoXsLeVBDQ=_v" } }
Response elements
Key | Value |
---|---|
hasErrors |
Boolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics. |
response |
Dictionary containing "productFormData" (see below). Only present when request is successful. |
errors |
List of error dictionaries, containing the keys "code", "message", and "field". Only present when the request fails. |
submissionId |
ID of UGC submission |
isFormComplete |
Boolean indicating if all the required fields have been completed. |
submissionSessionToken |
Unique token id required for progressive submission of the review. Read more about the |
Key | Value |
---|---|
review |
A dictionary representation of the current state of the review, used to fill out form fields with existing user data. Child elements are specific to a clients API key submission configuration. |
formValidationErrors |
Dictionary with form validation errors. Key is field with validation error, and values are "message" and "code". |
The table does not show all possible data returned. Data, such as CDVs, additional fields depends on a client's API submission configuration.
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 submission. |
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. |
Appendix
Session Token
The submissionSessionToken
is returned by all requests and must be provided to all progressiveSubmit
requests. The submissionSessionToken
may always be obtained by calling initiateSubmit
. The submissionSessionToken
is specific to the user and subject, and may not be used for other requests.
The submissionSessionToken
returned by any request may be different than the one originally provided. While any version of the submissionSessionToken
may be used for the progressiveSubmit
, it is strongly encouraged that the most recent version be used. This allows the application to process requests most efficiently.
Preview parameter
The preview parameter may be used to persist the state of a submission. The content is saved, and will be returned in subsequent calls to initiateSubmit, but does not go through moderation and is not available for display. When the preview parameter is present, the response will also not return an error because a required field has not been completed. This is useful to save the state of the submission when it would otherwise fail due to incomplete required fields. Content persisted by the preview parameter is available for up to 30 days.
Hosted authentication considerations
If configured for hosted authentication, clients must include hosted="VERIFIED" as part of the User authentication string (UAS). Submissions which do not contain this will be treated as if coming from site authentication. The "hosted=VERIFIED" value indicates that the client has confirmed that the user is the rightful owner of the supplied email address. This is generally not a problem if the submission is coming via PIE.