BV-Mastered Authentication

Overview

Bazaarvoice-mastered authentication allows users to submit content without prior authentication. This is useful for sites whose logins are difficult to customize or for sites that don't have account creation capabilities. Further our experience has shown that up to 40% of potential content authors will not complete the submission process if they are required to login first. Bazaarvoice-mastered authentication can raise your submission rate.

📘

HTTP POST is required.

initiateSubmit.json

Below are the details to be used when using initiateSubmit using hosted authentication

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
hostedauthIndicates the action being performed, is using hosted authenticationYes
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 recommendedYes
locale Locale for contentYes
deviceFingerprintUnique identifier for author's device. Read more about deviceFingerprintNo
campaignIdCampaign ID is a text string identifying the action that originated a piece of content. Read more.No

POST request

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.

initiateSubmit.json Response

The following response is a sample from a HTTP POST to the initiateSubmit.json 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}"
                    }
                }
                

progressiveSubmit.json

Below details describe using a progressive submission request using Hosted authentication

Request 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

POST 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"
    }
}'
progressiveSubmit.json response
{
    "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
    }
}

Additional Tips

How to avoid submitting 'ratings only' reviews

With progressive submission, it is possible to submit a 'ratings-only' review. A 'ratings-only' review is where a review contains no content other than an integer rating.

Avoid this by setting the preview flag on submission until the point where the review is ready for moderation and publication.

How to change the fieldsOrder elements

The fieldsOrder element is contained within the progressiveSubmit.json response. This element contains the suggested order of the review elements as they should be presented on a review submission form. The array of elements contained within the fieldsOrder elements are ordered by:

  1. Overall rating
  2. Review text
  3. Review title
  4. Nickname
  5. Required submission elements
    • Email
    • Location
  6. All other required questions as ordered in the Submission Form editor
  7. Photo
  8. Video
  9. Would you recommend to a friend
  10. Non-required fields as ordered in the Submission Form editor

If email and location are not configured as required, they are expected to appear with the non-required fields and ordered in the same way as the submission form editor.

The order of the review submission questions can be modified in the Submission Form Editor within the the site manager from the Bazaarvoice Workbench. Read more about working with the configuration hub.

What should be included in the UserToken?

The UserToken is an encoded set of fields sent in the request body that are authenticated via an HMAC generated with the client's encodingKey.

Read more about creating the UserToken. The following table details some of the values you can encode in the token:

User Token FieldValue
dateYYYYMMDD formatted date on which this token was generated
useridReviewer's unique ID.
emailAddressReviewer's email address.
usernameReviewer's username.
verifiedPurchaser'true' to indicate that the reviewer has been verified to have purchased the product.
IncentivizedReviewIndicates user has purchased item they are reviewing. Omit if value is not 'true'.
MaxAgeThe number of days before the user authentication string expires. The default number of days is one. Changing this to a greater value is useful in preauthenticated URLs such as in email campaigns.