Progressive Submission

Supports obtaining multiple review forms at once and submitting parts of a review as a user provides content.

🚧

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

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. As per latest changes, progressive submission support both Hosted Authentication and Client-Mastered Authentication

Environments

The following environments are supported:

EnvironmentDomainDescription
Stagingstg.api.bazaarvoice.com/Used while developing your application.
Productionapi.bazaarvoice.com/Used when your application is complete.

Initiate Submit

πŸ“˜

Try out Initiate Submit API reference here.

The initiateSubmit endpoint is used to request product info for building review submission form(s). This action must be done with an HTTP POST.

Using Client Mastered Authentication

Below is an example of initiate submit request using Client Mastered authentication

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

πŸ“˜

HTTP POST is required.

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

NameDescriptionRequired
formatData format (should be json)Yes
QueryString
passkeyConversations API pass key.Yes
apiVersionLatest version of the API for the request (should be 5.4).Yes
extendedThis 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/jsonYes
Body
productIdsArray of productId(s) for which to return submission form and check for previous submissions. 20 or less is recommended.Yes
userTokenAuthenticated user data. Fields can instead be sent in post body.No
userIdUnique 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*
localeLocale for contentYes
deviceFingerprintUnique identifier for author's device. Read more about deviceFingerprintNo
campaignId | Campaign ID is a text string identifying the action that originated a piece of content. Read more.No

Response format

🚧

Do not reuse the API passkey below in your application.

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": "{some_token}"
              },
              "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": "{some_token}"
              }
            }
          }
        }
        

Ellipses (…) in above example indicate that your app may generate additional content.

Response elements

KeyValue
responseDictionary containing "productFormData" (see below). Only present when request is successful.
hasErrorsBoolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics.
errorsList 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:

KeyValue
reviewA 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.
fieldsOrderA list of strings indicating an order for the fields definitions in "fields".
fieldsA 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.
submissionSessionTokenUnique 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.


Using Hosted Authentication

Below is an example of initiate submit request using Hosted authentication

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

πŸ“˜

HTTP POST is required.

POST /data/initiateSubmit.{FORMAT}?passkey={CONVERSATIONS_API_PASSKEY}&apiVersion={latestApiVersion}&action=submit&hostedauth HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/json
X-Forwarded-For: [AuthorIPAddress]
…

{
  "locale": "en_US",
  "productIds": [
    "Product1"
  ]
}

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

Parameters

NameDescriptionRequired
formatData format (should be json)Yes
QueryString
passkeyConversations API pass key.Yes
apiVersionLatest version of the API for the request (should be 5.4).Yes
extendedThis 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
hostedauth Indicates the action being performed, is using hosted authenticationYes
Header
Content-Typeapplication/jsonYes
Body
productIdsArray of productId(s) for which to return submission form and check for previous submissions. 20 or less is recommended.Yes
localeLocale for contentYes
deviceFingerprintUnique identifier for author's device. Read more about deviceFingerprintNo
campaignId Campaign ID is a text string identifying the action that originated a piece of content. Read more.No

🚧

userId and userToken are not allowed in Hosted Authentication.

Response format

🚧

Do not reuse the API passkey below in your application.

POST an initiateSubmit request with two productIds:

curl -X POST \
'http://stg.api.bazaarvoice.com/data/initiateSubmit.json?passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&apiVersion=5.4&action=submit&hostedauth' \
-H 'Content-Type: application/json' \
...


{
  "locale": "en_US",
  "productIds": [
    "Product1"
  ]
}

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": {
                        "productFormData": {
                            "product1": {
                                "review": {
                                    "submissionID": "r116143_16323803KMdC8LfyA8",
                                    "productExternalID": "product1",
                                    "submissionTime": "2021-09-23@06:59:28"
                                },
                                "fieldsOrder": [
                                    "rating",
                                    "reviewtext",
                                    "title",
                                    "usernickname",
                                    "authenticationemail",
                                    "photourl_1",
                                    "photocaption_1",
                                    "photourl_2",
                                    "photocaption_2",
                                    "photourl_3",
                                    "photocaption_3",
                                    "photourl_4",
                                    "photocaption_4",
                                    "photourl_5",
                                    "photocaption_5",
                                    "photourl_6",
                                    "photocaption_6",
                                    "videourl_1",
                                    "videocaption_1",
                                    "isrecommended",
                                    "userlocation",
                                    "Age",
                                    "Gender",
                                    "BodyType",
                                    "Quality",
                                    "Value",
                                    "Appearance1",
                                    "Fit_22",
                                    "Con",
                                    "BestUsesFlowersGifts"
                                ],
                                "fields": {
                                    "photourl_6": {
                                        "id": "photourl_6",
                                        "type": "url",
                                        "class": "photourl"
                                    },
                                    "videourl_1": {
                                        "id": "videourl_1",
                                        "type": "url",
                                        "class": "videourl"
                                    },
                                    "BestUsesFlowersGifts": {
                                        "valuesLabels": {
                                            "AnyOccasion": "Any occasion",
                                            "ChristmasGift": "Christmas Gift",
                                            "BirthdayGift": "Birthday Gift",
                                            "ThankYouAppreciation": "Thank you/Appreciation",
                                            "GiftCorporate": "Gift Corporate",
                                            "GiftSympathy": "Gift Sympathy",
                                            "BasketCongratulations": "Basket Congratulations"
                                        },
                                        "autoPopulate": false,
                                        "label": "Best Uses",
                                        "id": "tagid_BestUsesFlowersGifts",
                                        "type": "multichoice",
                                        "class": "tag",
                                        "required": false
                                    },
                                    "photourl_2": {
                                        "id": "photourl_2",
                                        "type": "url",
                                        "class": "photourl"
                                    },
                                    "photourl_3": {
                                        "id": "photourl_3",
                                        "type": "url",
                                        "class": "photourl"
                                    },
                                    "photourl_4": {
                                        "id": "photourl_4",
                                        "type": "url",
                                        "class": "photourl"
                                    },
                                    "photourl_5": {
                                        "id": "photourl_5",
                                        "type": "url",
                                        "class": "photourl"
                                    },
                                    "rating": {
                                        "id": "rating",
                                        "type": "integer",
                                        "class": "rating"
                                    },
                                    "Gender": {
                                        "valuesLabels": {
                                            "Male": "Male",
                                            "Female": "Female"
                                        },
                                        "autoPopulate": true,
                                        "label": "What is your gender?",
                                        "id": "contextdatavalue_Gender",
                                        "type": "choice",
                                        "class": "cdv",
                                        "required": false
                                    },
                                    "BodyType": {
                                        "valuesLabels": {
                                            "Apple": "Apple",
                                            "Curvy": "Curvy",
                                            "FullFigured": "Full figured",
                                            "Hourglass": "Hourglass",
                                            "LongAndLean": "Long and Lean",
                                            "PearShaped": "Pear shaped",
                                            "Slender": "Slender",
                                            "Petite": "Petite"
                                        },
                                        "autoPopulate": false,
                                        "label": "What is your body type?",
                                        "id": "contextdatavalue_BodyType",
                                        "type": "choice",
                                        "class": "cdv",
                                        "required": false
                                    },
                                    "title": {
                                        "required": false,
                                        "hidden": false,
                                        "id": "title",
                                        "maxLength": 50,
                                        "type": "text",
                                        "class": "title"
                                    },
                                    "reviewtext": {
                                        "required": false,
                                        "hidden": false,
                                        "id": "reviewtext",
                                        "minLength": 50,
                                        "type": "text",
                                        "class": "reviewtext"
                                    },
                                    "isrecommended": {
                                        "id": "isRecommended",
                                        "type": "boolean",
                                        "class": "isrecommended"
                                    },
                                    "photocaption_2": {
                                        "id": "photocaption_2",
                                        "type": "text",
                                        "class": "photocaption"
                                    },
                                    "photocaption_1": {
                                        "id": "photocaption_1",
                                        "type": "text",
                                        "class": "photocaption"
                                    },
                                    "Quality": {
                                        "autoPopulate": false,
                                        "label": "How would you rate the quality of this product?",
                                        "id": "rating_Quality",
                                        "type": "integer",
                                        "class": "rating",
                                        "required": false
                                    },
                                    "photocaption_6": {
                                        "id": "photocaption_6",
                                        "type": "text",
                                        "class": "photocaption"
                                    },
                                    "authenticationemail": {
                                        "required": true,
                                        "hidden": false,
                                        "id": "hostedauthentication_authenticationemail",
                                        "type": "text",
                                        "class": "hostedauthentication_authenticationemail"
                                    },
                                    "photocaption_5": {
                                        "id": "photocaption_5",
                                        "type": "text",
                                        "class": "photocaption"
                                    },
                                    "photocaption_4": {
                                        "id": "photocaption_4",
                                        "type": "text",
                                        "class": "photocaption"
                                    },
                                    "photourl_1": {
                                        "id": "photourl_1",
                                        "type": "url",
                                        "class": "photourl"
                                    },
                                    "photocaption_3": {
                                        "id": "photocaption_3",
                                        "type": "text",
                                        "class": "photocaption"
                                    },
                                    "videocaption_1": {
                                        "id": "videocaption_1",
                                        "type": "text",
                                        "class": "videocaption"
                                    },
                                    "Age": {
                                        "valuesLabels": {
                                            "17orUnder": "17 or under",
                                            "18to24": "18 to 24",
                                            "25to34": "25 to 34",
                                            "35to44": "35 to 44",
                                            "45to54": "45 to 54",
                                            "55to64": "55 to 64",
                                            "65orOver": "65 or over"
                                        },
                                        "autoPopulate": true,
                                        "label": "How old are you?",
                                        "id": "contextdatavalue_Age",
                                        "type": "choice",
                                        "class": "cdv",
                                        "required": false
                                    },
                                    "Con": {
                                        "valuesLabels": {
                                            "Bulky": "Bulky",
                                            "Heavy": "Heavy",
                                            "RetainsOdors": "Retains Odors",
                                            "StainsEasily": "Stains Easily"
                                        },
                                        "autoPopulate": false,
                                        "label": "Cons",
                                        "id": "tagid_Con",
                                        "type": "multichoice",
                                        "class": "tag",
                                        "required": false
                                    },
                                    "Appearance1": {
                                        "autoPopulate": false,
                                        "label": "How would you rate the appearance of the product?",
                                        "id": "rating_Appearance1",
                                        "type": "integer",
                                        "class": "rating",
                                        "required": false
                                    },
                                    "usernickname": {
                                        "required": true,
                                        "hidden": false,
                                        "id": "usernickname",
                                        "minLength": 4,
                                        "type": "text",
                                        "class": "usernickname"
                                    },
                                    "Value": {
                                        "autoPopulate": false,
                                        "label": "How would you rate the value of this product?",
                                        "id": "rating_Value",
                                        "type": "integer",
                                        "class": "rating",
                                        "required": false
                                    },
                                    "_Location": {
                                        "required": false,
                                        "hidden": false,
                                        "id": "userlocation",
                                        "type": "text",
                                        "class": "userlocation"
                                    },
                                    "Fit_22": {
                                        "valuesLabels": {
                                            "valueLabel1": "Too small",
                                            "valueLabel2": "A little small",
                                            "valueLabel3": "True to size",
                                            "valueLabel4": "A little big",
                                            "valueLabel5": "Too big"
                                        },
                                        "autoPopulate": false,
                                        "label": "Fit",
                                        "id": "rating_Fit_22",
                                        "type": "integer",
                                        "sliderSize": 5,
                                        "class": "slider",
                                        "required": false
                                    },
                                    "useremail": {
                                        "required": true,
                                        "hidden": false,
                                        "id": "useremail",
                                        "type": "text",
                                        "class": "useremail"
                                    }
                                },
                                "submissionSessionToken": "{some_token}"
                            }
                        },
                        "userId": "{some_id}"
                    }
                }

Ellipses (…) in above example indicate that your app may generate additional content.


Response elements

KeyValue
responseDictionary containing "productFormData" (see below). Only present when request is successful.
hasErrorsBoolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics.
errorsList 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:

KeyValue
reviewA 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.
fieldsOrderA list of strings indicating an order for the fields definitions in "fields".
fieldsA 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.
submissionSessionTokenUnique token id required for progressiveSubmit of the review. Read more about the submissionSessionToken
userIdUnique user Id generated for user of to perform progressiveSubmit of the review. The same is required to perform the progressive submit operation.

*expired=true indicates that the prior review content is not eligible for editing because 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

πŸ“˜

Try out Progressive Submit API reference here.

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.

Using Client Mastered Authentication

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

πŸ“˜

HTTP POST is required.

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": "{some_token}",
  "productId":"wbk003xl",
  "useremail":"[email protected]",
  "submissionFields":{
    "rating":"5", 
    "agreedtotermsandconditions":"true",
    "title":"This is a great product ",
    ...
  }
}

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


Parameters

NameDescriptionRequired
formatData format (should be json)Yes
QueryString
passkeyConversations API pass key.Yes
apiVersionLatest version of the API for the request (should be 5.4).Yes
fieldsIncluded 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
previewIncluded 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-Typeapplication/jsonYes
Body
productIdA single productId for review or review form.Yes
submissionSessionTokenUnique token id required for progressiveSubmit of the review. Read more about the submissionSessionTokenYes
localeLocale for translated product dimensions.Yes
userTokenAuthenticated user data. Fields can instead be sent in post body.No
userIdUnique id for user. Can be encoded in UserToken or sent as own element, depending on key configuration.Yes*
useremailEmail address for user. Can either be sent separately at this level, or be encoded in UserToken.Yes*
deviceFingerprintUnique identifier for author's device.No
campaignIdCampaign ID is a text string identifying the action that originated a piece of content. Read more.No
submissionFieldsKey value pairs for submitted fields on submission form. Data varies per API key configurations.No

Response format

🚧

Do not reuse the API passkey below in your application.

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":"[email protected]",
  "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

KeyValue
hasErrorsBoolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics.
responseDictionary containing "productFormData" (see below). Only present when request is successful.
errorsList of error dictionaries, containing the keys "code", "message", and "field". Only present when the request fails.
submissionIdID of UGC submission
isFormCompleteBoolean indicating if all the required fields have been completed.
submissionSessionTokenUnique token id required for progressive submission of the review. Read more about the submissionSessionToken
KeyValue
reviewA 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.
formValidationErrorsDictionary 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.

Using Hosted Authentication

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

πŸ“˜

HTTP POST is required.

POST /data/progressiveSubmit.{FORMAT}?apiVersion={latestApiVersion}&action=preview&fields=true&passkey={CONVERSATIONS_API_PASSKEY}&hostedauth HTTP/1.1
Content-Type: application/json
Host: [stg.]api.bazaarvoice.com
X-Forwarded-For: [AuthorIPAddress]
...

{
    "locale": "en_US",
    "productId": "Product1",
    "userId": "{{INITIATE\_SUBMISSION\_USERID}}",
    "submissionSessionToken": "{{SUBMISSION\_SESSION\_TOKEN}}",
    "submissionFields": {
        "rating":"5",
        "agreedtotermsandconditions": "true",
        ....
        "hostedauthentication\_authenticationemail": "{{authenticationemail}}",
        "hostedauthentication\_callbackurl": "{{callback\_url}}"
    }
}

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


Parameters

NameDescriptionRequired
formatData format (should be json)Yes
QueryString
passkeyConversations API pass key.Yes
apiVersionLatest version of the API for the request (should be 5.4).Yes
fieldsIncluded 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
previewIncluded 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
hostedauthIndicates the action being performed, is using hosted authenticationYes
Header
Content-Typeapplication/jsonYes
Body
productIdA single productId for review or review form.Yes
submissionSessionTokenUnique token id required for progressiveSubmit of the review. Can be retrieved as part of initiateSubmit response.Yes
localeLocale for translated product dimensions.Yes
userIdUnique id for user. Can be retrieved as part of initiateSubmit response.Yes
useremailEmail address for user. Can either be sent separately at this level, or be encoded in UserToken.Yes*
deviceFingerprintUnique identifier for author's device.No
campaignIdCampaign ID is a text string identifying the action that originated a piece of content. Read more.No
submissionFieldsKey value pairs for submitted fields on submission form. Data varies per API key configurations.No

Response format

🚧

Do not reuse the API passkey below in your application.

POST a progressiveSubmit request:

curl -X POST \
 'http://stg.api.bazaarvoice.com/data/progressiveSubmit.json?apiVersion=5.4&action=preview&fields=true&passkey=canCClB6qhUpgE3G8bsr0idot7h3j62lNFpoEUHNIvfmg&hostedauth' \
 -H 'Content-Type: application/json' \
 -d '{
    "locale": "en_US",
    "productId": "Product1",
    "userId": "zky95dwa4fagufurne8",
    "submissionSessionToken": "{some_token_value}",
    "submissionFields": {
        "rating":"5",
        "agreedtotermsandconditions": "true",
        "reviewtext": "Product 1: test test test test test test test test test test test test test test test test test test test test",
        "title":"Product 1: Test",
        "hostedauthentication_authenticationemail": "[email protected]",
        "hostedauthentication_callbackurl": "http://testcustomer.bazaarvoice.com/cburl"
    }
}'

The following response is a sample from a HTTP POST to the progressiveSubmit endpoint:

{
    "hasErrors": false,
    "response": {
        "review": {
            "SendEmailAlertWhenCommented": true,
            "Rating": 5,
            "SubmissionTime": "2021-09-22T06:23:00.610+00:00",
            "ReviewText": "Product 1: test test test test test test test test test test test test test test test test test test test test",
            "Title": "Product 1: Test",
            "SendEmailAlertWhenPublished": true
        },
        "fieldsOrder": [
            "rating",
            "reviewtext",
            "title",
            "usernickname",
            "authenticationemail",
            "photourl_1",
            "photocaption_1",
            "photourl_2",
            "photocaption_2",
            "photourl_3",
            "photocaption_3",
            "photourl_4",
            "photocaption_4",
            "photourl_5",
            "photocaption_5",
            "photourl_6",
            "photocaption_6",
            "videourl_1",
            "videocaption_1",
            "isrecommended",
            "userlocation",
            "Age",
            "Gender",
            "BodyType",
            "Quality",
            "Value",
            "Appearance1",
            "Fit_22",
            "Con",
            "BestUsesFlowersGifts"
        ],
        "fields": {
            "photourl_6": {
                "id": "photourl_6",
                "type": "url",
                "class": "photourl"
            },
            "videourl_1": {
                "id": "videourl_1",
                "type": "url",
                "class": "videourl"
            },
            "BestUsesFlowersGifts": {
                "valuesLabels": {
                    "AnyOccasion": "Any occasion",
                    "ChristmasGift": "Christmas Gift",
                    "BirthdayGift": "Birthday Gift",
                    "ThankYouAppreciation": "Thank you/Appreciation",
                    "GiftCorporate": "Gift Corporate",
                    "GiftSympathy": "Gift Sympathy",
                    "BasketCongratulations": "Basket Congratulations"
                },
                "autoPopulate": false,
                "label": "Best Uses",
                "id": "tagid_BestUsesFlowersGifts",
                "type": "multichoice",
                "class": "tag",
                "required": false
            },
            "photourl_2": {
                "id": "photourl_2",
                "type": "url",
                "class": "photourl"
            },
            "photourl_3": {
                "id": "photourl_3",
                "type": "url",
                "class": "photourl"
            },
            "photourl_4": {
                "id": "photourl_4",
                "type": "url",
                "class": "photourl"
            },
            "photourl_5": {
                "id": "photourl_5",
                "type": "url",
                "class": "photourl"
            },
            "rating": {
                "id": "rating",
                "type": "integer",
                "class": "rating"
            },
            "Gender": {
                "valuesLabels": {
                    "Male": "Male",
                    "Female": "Female"
                },
                "autoPopulate": true,
                "label": "What is your gender?",
                "id": "contextdatavalue_Gender",
                "type": "choice",
                "class": "cdv",
                "required": false
            },
            "BodyType": {
                "valuesLabels": {
                    "Apple": "Apple",
                    "Curvy": "Curvy",
                    "FullFigured": "Full figured",
                    "Hourglass": "Hourglass",
                    "LongAndLean": "Long and Lean",
                    "PearShaped": "Pear shaped",
                    "Slender": "Slender",
                    "Petite": "Petite"
                },
                "autoPopulate": false,
                "label": "What is your body type?",
                "id": "contextdatavalue_BodyType",
                "type": "choice",
                "class": "cdv",
                "required": false
            },
            "title": {
                "required": false,
                "hidden": false,
                "id": "title",
                "maxLength": 50,
                "type": "text",
                "class": "title"
            },
            "reviewtext": {
                "required": false,
                "hidden": false,
                "id": "reviewtext",
                "minLength": 50,
                "type": "text",
                "class": "reviewtext"
            },
            "isrecommended": {
                "id": "isRecommended",
                "type": "boolean",
                "class": "isrecommended"
            },
            "photocaption_2": {
                "id": "photocaption_2",
                "type": "text",
                "class": "photocaption"
            },
            "photocaption_1": {
                "id": "photocaption_1",
                "type": "text",
                "class": "photocaption"
            },
            "Quality": {
                "autoPopulate": false,
                "label": "How would you rate the quality of this product?",
                "id": "rating_Quality",
                "type": "integer",
                "class": "rating",
                "required": false
            },
            "photocaption_6": {
                "id": "photocaption_6",
                "type": "text",
                "class": "photocaption"
            },
            "authenticationemail": {
                "required": true,
                "hidden": false,
                "id": "hostedauthentication_authenticationemail",
                "type": "text",
                "class": "hostedauthentication_authenticationemail"
            },
            "photocaption_5": {
                "id": "photocaption_5",
                "type": "text",
                "class": "photocaption"
            },
            "photocaption_4": {
                "id": "photocaption_4",
                "type": "text",
                "class": "photocaption"
            },
            "photourl_1": {
                "id": "photourl_1",
                "type": "url",
                "class": "photourl"
            },
            "photocaption_3": {
                "id": "photocaption_3",
                "type": "text",
                "class": "photocaption"
            },
            "videocaption_1": {
                "id": "videocaption_1",
                "type": "text",
                "class": "videocaption"
            },
            "Age": {
                "valuesLabels": {
                    "17orUnder": "17 or under",
                    "18to24": "18 to 24",
                    "25to34": "25 to 34",
                    "35to44": "35 to 44",
                    "45to54": "45 to 54",
                    "55to64": "55 to 64",
                    "65orOver": "65 or over"
                },
                "autoPopulate": true,
                "label": "How old are you?",
                "id": "contextdatavalue_Age",
                "type": "choice",
                "class": "cdv",
                "required": false
            },
            "Con": {
                "valuesLabels": {
                    "Bulky": "Bulky",
                    "Heavy": "Heavy",
                    "RetainsOdors": "Retains Odors",
                    "StainsEasily": "Stains Easily"
                },
                "autoPopulate": false,
                "label": "Cons",
                "id": "tagid_Con",
                "type": "multichoice",
                "class": "tag",
                "required": false
            },
            "Appearance1": {
                "autoPopulate": false,
                "label": "How would you rate the appearance of the product?",
                "id": "rating_Appearance1",
                "type": "integer",
                "class": "rating",
                "required": false
            },
            "usernickname": {
                "required": true,
                "hidden": false,
                "id": "usernickname",
                "minLength": 4,
                "type": "text",
                "class": "usernickname"
            },
            "Value": {
                "autoPopulate": false,
                "label": "How would you rate the value of this product?",
                "id": "rating_Value",
                "type": "integer",
                "class": "rating",
                "required": false
            },
            "_Location": {
                "required": false,
                "hidden": false,
                "id": "userlocation",
                "type": "text",
                "class": "userlocation"
            },
            "Fit_22": {
                "valuesLabels": {
                    "valueLabel1": "Too small",
                    "valueLabel2": "A little small",
                    "valueLabel3": "True to size",
                    "valueLabel4": "A little big",
                    "valueLabel5": "Too big"
                },
                "autoPopulate": false,
                "label": "Fit",
                "id": "rating_Fit_22",
                "type": "integer",
                "sliderSize": 5,
                "class": "slider",
                "required": false
            },
            "useremail": {
                "required": true,
                "hidden": false,
                "id": "useremail",
                "type": "text",
                "class": "useremail"
            }
        },
        "submissionId": "{some_id}",
        "submissionSessionToken": "{some_token}",
        "isFormComplete": false
    }
}

Response elements

KeyValue
hasErrorsBoolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics.
responseDictionary containing "productFormData" (see below). Only present when request is successful.
errorsList of error dictionaries, containing the keys "code", "message", and "field". Only present when the request fails.
submissionIdID of UGC submission
isFormCompleteBoolean indicating if all the required fields have been completed.
submissionSessionTokenUnique token id required for progressive submission of the review. Read more about the submissionSessionToken
KeyValue
reviewA 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.
formValidationErrorsDictionary 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

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_SUBMITTED_NICKNAMEThis nickname has already been submitted.
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_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_MISSING_SUBJECT_IDSubmission is missing a product to submit against. A product id is REQUIRED for review submission.
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.

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.