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.
Progressive Submission for submission experiences that are not triggered by an email to the author requires that clients use Client-Mastered Authentication. This is because progressive submission relies on the ability to verify a user's identity in order to manage submission sessions. If using Bazaarvoice-mastered authentication, please read the following considerations.

The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.

Contents

(+ show- hide)

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

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

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

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": "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

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": "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

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":"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.