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.

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	stg.api.bazaarvoice.com/	Used while developing your application.
Production	api.bazaarvoice.com/	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 fields elements are returned in an ordered list that honors the submission field order as specified in the configuration hub, with the exception that required fields are presented first in the ordered list. When included, fields elements are returned in full submission-style format.	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 UserToken or sent as own element, depending on API key configuration. Must not contain any personally identifiable information (PII) data, particularly email address.	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 submissionID, productExternalID, submissionTime, expired* and any other review supplied data.
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. fields will be pre-populated with previously submitted content.
submissionSessionToken	Unique token id required for progressiveSubmit of the review. Read more about the submissionSessionToken

*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 progressiveSubmit of the review. Read more about the submissionSessionToken	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 UserToken or sent as own element, depending on key configuration. See the hosted authentication documentation in the Appendix for for additional considerations.	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 submissionSessionToken

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 progressiveSubmitrequests. 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.