Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Progressive Submission
The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.
Contents
Supports obtaining multiple review forms at once and submitting parts of a review as a user provides content.
Overview
Progressive Submission is comprised of the following two endpoints: initiateSubmit and progressiveSubmit. initiateSubmit returns data to assist in building the product's submission form. progressiveSubmit supports submitting consumer generated content on a single product. The ability to continue a submission (or edit) is limited to 30 days after the first submission of content. As per latest changes, progressive submission support both Hosted Authentication and Client-Mastered Authentication
Environments
The following environments are supported:
| Environment | Domain | Description |
|---|---|---|
| Staging |
|
Used while developing your application. |
| Production |
|
Used when your application is complete. |
Initiate Submit
The initiateSubmit endpoint is used to request product info for building review submission form(s). This action must be done with an HTTP POST.
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
POST /data/initiateSubmit.{FORMAT}?passkey={CONVERSATIONS_API_PASSKEY}&apiVersion={latestApiVersion} HTTP/1.1
Host: [stg.]api.bazaarvoice.com
Content-Type: application/json
X-Forwarded-For: [AuthorIPAddress]
…
{
"locale": "en_US",
"userToken": "{SOME_USER_TOKEN}",
"productIds": [
"Product1",
"ProductZ"
]
}
Ellipses (…) in above example indicate that your app may generate other headers.
Parameters
| Name | Description | Required |
|---|---|---|
format |
Data format (should be json) |
Yes |
QueryString |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
Latest version of the API for the request (should be 5.4). |
Yes |
extended |
This parameter is sent as a single key and does not need a value. When omitted, the When included, |
No |
Header |
||
Content-Type |
application/json |
Yes |
Body |
||
productIds |
Array of productId(s) for which to return submission form and check for previous submissions. 20 or less is recommended. |
Yes |
userToken |
Authenticated user data. Fields can instead be sent in post body. |
No |
userId |
Unique id for user. Can be encoded in |
Yes* |
locale |
Locale for content |
Yes |
deviceFingerprint |
Unique identifier for author's device. Read more about deviceFingerprint |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
Response format
POST an initiateSubmit request with two productIds:
curl -X POST \
'http://stg.api.bazaarvoice.com/data/initiateSubmit.json?passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&apiVersion=5.4' \
-H 'Content-Type: application/json' \
...
{
"locale": "en_US",
"userId": "demo",
"productIds": [
"wsd005c",
"wbk003xl"
]
}
Ellipses (…) in above example indicate that your app may generate other content.
The following response is a sample from a HTTP POST to the initiateSubmit endpoint:
{
"hasErrors": false,
"response": {
"userNickname": "SOME_USER_NICKNAME",
"productFormData": {
"wsd005c": {
"review": {
"submissionID": "qbk13gsqk9ffyqbwhs2y51m2z",
"productExternalID": "wbk003xl",
"submissionTime": "2019-08-06@20:43:47"
},
"fieldsOrder": [
"rating",
"title",
"reviewtext",
....
],
"fields": {
"rating": {
"required": true,
"id": "rating",
"type": "integer",
"class": "rating"
},
"title": {
"required": true,
"id": "title",
"maxLength": 50,
"type": "text",
"class": "title"
},
"reviewtext": {
"required": true,
"id": "reviewtext",
"minLength": 50,
"type": "text",
"class": "reviewtext"
},
"Gender": {
"valuesLabels": {
"Male": "Male",
"Female": "Female"
},
"autoPopulate": true,
"label": "What is your gender?",
"id": "contextdatavalue_Gender",
"type": "choice",
"class": "cdv",
"required": false
},
...
},
"submissionSessionToken": "{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
| Key | Value |
|---|---|
response |
Dictionary containing "productFormData" (see below). Only present when request is successful. |
hasErrors |
Boolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics. |
errors |
List of error dictionaries, containing the keys "code", "message", and "field". Only present when the request fails. |
productFormData is a dictionary of dictionaries, with keys matching "productIds" sent in the request body, and values defined as follows:
| Key | Value |
|---|---|
review |
A dictionary representation of the current state of the review, used to fill out form fields with existing user data. Contains |
fieldsOrder |
A list of strings indicating an order for the fields definitions in "fields". |
fields |
A dictionary of form fields for a review form. Format depends on whether "extended" parameter is set. |
submissionSessionToken |
Unique token id required for |
*expired=true indicates that the prior review content is not eligible for editing becuase it is older than 30 days. Attempts to submit updates will result in a duplicate submission error. expired is absent when the value is false.
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
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
| Name | Description | Required |
|---|---|---|
format |
Data format (should be json) |
Yes |
QueryString |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
Latest version of the API for the request (should be 5.4). |
Yes |
extended |
This parameter is sent as a single key and does not need a value. When omitted, the When included, |
No |
hostedauth |
Indicates the action being performed, is using hosted authentication |
Yes |
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 |
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 |
userId and userToken are not allowed in Hosted Authentication.
Response format
POST an initiateSubmit request with two productIds:
curl -X POST \
'http://stg.api.bazaarvoice.com/data/initiateSubmit.json?passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&apiVersion=5.4&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
| Key | Value |
|---|---|
response |
Dictionary containing "productFormData" (see below). Only present when request is successful. |
hasErrors |
Boolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics. |
errors |
List of error dictionaries, containing the keys "code", "message", and "field". Only present when the request fails. |
productFormData is a dictionary of dictionaries, with keys matching "productIds" sent in the request body, and values defined as follows:
| Key | Value |
|---|---|
review |
A dictionary representation of the current state of the review, used to fill out form fields with existing user data. Contains |
fieldsOrder |
A list of strings indicating an order for the fields definitions in "fields". |
fields |
A dictionary of form fields for a review form. Format depends on whether "extended" parameter is set. |
submissionSessionToken |
Unique token id required for |
userId |
Unique user Id generated for user of to perform |
*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.
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
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":"test@test.com",
"submissionFields":{
"rating":"5",
"agreedtotermsandconditions":"true",
"title":"This is a great product ",
...
}
}
Ellipses (…) in above example indicate that your app may generate other content.
Parameters
| Name | Description | Required |
|---|---|---|
format |
Data format (should be json) |
Yes |
QueryString |
||
passkey |
Conversations API pass key. |
Yes |
apiVersion |
Latest version of the API for the request (should be 5.4). |
Yes |
fields |
Included to indicate that form fields, as from initiateSubmit, should be returned along with the response. This parameter is sent as a single key and does not need a value. |
No |
preview |
Included to indicate that the API should not submit and instead return a display representation of the review. Read more about correct usage. This parameter is sent as a single key and does not need a value. |
No |
Header |
||
Content-Type |
application/json |
Yes |
Body |
||
productId |
A single productId for review or review form. |
Yes |
submissionSessionToken |
Unique token id required for |
Yes |
locale |
Locale for translated product dimensions. |
Yes |
userToken |
Authenticated user data. Fields can instead be sent in post body. |
No |
userId |
Unique id for user. Can be encoded in |
Yes* |
useremail |
Email address for user. Can either be sent separately at this level, or be encoded in UserToken. |
Yes* |
deviceFingerprint |
Unique identifier for author's device. |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
submissionFields |
Key value pairs for submitted fields on submission form. Data varies per API key configurations. |
No |
Response format
POST a progressiveSubmit request:
curl -X POST \
'http://stg.api.bazaarvoice.com/data/progressiveSubmit.json?passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&apiVersion=5.4&Action=submit' \
-H 'Content-Type: application/json' \
-d '{
"locale":"en_US",
"userId": "tom",
"submissionSessionToken": "{some_Token_Value}",
"productId":"1000001",
"useremail":"foo@bazaarvoice.com",
"submissionFields":{
"rating":"5",
"agreedtotermsandconditions":"true",
"title": "This is some title",
"reviewtext": "This is some review text. This is some review text. This is some review text. This is some review text. This is some review text. This is some review text. This is some review text.",
"usernickname": "largeMouthBass"
}
}'
The following response is a sample from a HTTP POST to the progressiveSubmit endpoint:
{
"hasErrors": false,
"response": {
"review": {
"SendEmailAlertWhenCommented": false,
"Rating": 5,
"SubmissionTime": "2019-08-07T21:45:12.051+00:00",
"ReviewText": "this is some title this is some title this is some title this is some title this is some title this is some title this is some title",
"Title": "this is some title",
"SendEmailAlertWhenPublished": false
},
"submissionId": "h7jcqg70gil5ggqcfqs3ru7bt",
"isFormComplete": true,
"submissionSessionToken": "h3fh0cbwjgyoud7ncqtgb6nd8_eebf6f276a745e1d0323bab2e143ecf14e92f8103ea9509c3e40ebef88de1380_laoXsLeVBDQ=_v"
}
}
Response elements
| Key | Value |
|---|---|
hasErrors |
Boolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics. |
response |
Dictionary containing "productFormData" (see below). Only present when request is successful. |
errors |
List of error dictionaries, containing the keys "code", "message", and "field". Only present when the request fails. |
submissionId |
ID of UGC submission |
isFormComplete |
Boolean indicating if all the required fields have been completed. |
submissionSessionToken |
Unique token id required for progressive submission of the review. Read more about the |
| Key | Value |
|---|---|
review |
A dictionary representation of the current state of the review, used to fill out form fields with existing user data. Child elements are specific to a clients API key submission configuration. |
formValidationErrors |
Dictionary with form validation errors. Key is field with validation error, and values are "message" and "code". |
The table does not show all possible data returned. Data, such as CDVs, additional fields depends on a client's API submission configuration.
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
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
| 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 |
hostedauth |
Indicates the action being performed, is using hosted authentication |
Yes |
Header |
||
Content-Type |
application/json |
Yes |
Body |
||
productId |
A single productId for review or review form. |
Yes |
submissionSessionToken |
Unique token id required for |
Yes |
locale |
Locale for translated product dimensions. |
Yes |
userId |
Unique id for user. Can be retrieved as part of initiateSubmit response. |
Yes |
useremail |
Email address for user. Can either be sent separately at this level, or be encoded in UserToken. |
Yes* |
deviceFingerprint |
Unique identifier for author's device. |
No |
campaignId |
Campaign ID is a text string identifying the action that originated a piece of content. Read more. |
No |
submissionFields |
Key value pairs for submitted fields on submission form. Data varies per API key configurations. |
No |
Response format
POST a progressiveSubmit request:
curl -X POST \
'http://stg.api.bazaarvoice.com/data/progressiveSubmit.json?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": "test@test.com",
"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
| Key | Value |
|---|---|
hasErrors |
Boolean indicating that there were errors with the request. When 'true' check the "errors" list for specifics. |
response |
Dictionary containing "productFormData" (see below). Only present when request is successful. |
errors |
List of error dictionaries, containing the keys "code", "message", and "field". Only present when the request fails. |
submissionId |
ID of UGC submission |
isFormComplete |
Boolean indicating if all the required fields have been completed. |
submissionSessionToken |
Unique token id required for progressive submission of the review. Read more about the |
| Key | Value |
|---|---|
review |
A dictionary representation of the current state of the review, used to fill out form fields with existing user data. Child elements are specific to a clients API key submission configuration. |
formValidationErrors |
Dictionary with form validation errors. Key is field with validation error, and values are "message" and "code". |
The table does not show all possible data returned. Data, such as CDVs, additional fields depends on a client's API submission configuration.
Error codes
| Value | Description |
|---|---|
ERROR_ACCESS_DENIED |
Insufficient privileges to perform the operation |
ERROR_FORM_DUPLICATE |
The nickname is already in use. |
ERROR_FORM_DUPLICATE_NICKNAME |
The nickname is already in use. |
ERROR_FORM_EMOJI |
Emoji are not supported. |
ERROR_FORM_INVALID_EMAILADDRESS |
Email address is not in the proper format. |
ERROR_FORM_INVALID_IPADDRESS |
The IP address is invalid. |
ERROR_FORM_INVALID_OPTION |
The selected option has been removed. |
ERROR_FORM_PATTERN_MISMATCH |
This field is not in the correct format. |
ERROR_FORM_PROFANITY |
The content contains inappropriate language. |
ERROR_FORM_REJECTED |
The submission was rejected. |
ERROR_FORM_REQUIRED |
A required field was not supplied. |
ERROR_FORM_REQUIRED_EITHER |
Both of the required hosted authentication parameters are missing. |
ERROR_FORM_REQUIRED_NICKNAME |
You must enter a nickname. |
ERROR_FORM_REQUIRES_TRUE |
A field requires a value of true. (e.g., "You must agree to the terms and conditions.") |
ERROR_FORM_RESTRICTED |
Content provider's age is too young. (e.g., "Content cannot be accepted from minors under age 13.") |
ERROR_FORM_SUBMITTED_NICKNAME |
This nickname has already been submitted. |
ERROR_FORM_TOO_FEW |
There must be a minimum number of items contributed for this field. |
ERROR_FORM_TOO_HIGH |
This field has too many items. |
ERROR_FORM_TOO_LONG |
The field has too many characters. |
ERROR_FORM_TOO_LOW |
This field has too few items. |
ERROR_FORM_TOO_SHORT |
The field doesn't have enough characters. |
ERROR_FORM_UPLOAD_IO |
The item could not be uploaded. Ensure that it is a valid file type. |
ERROR_DUPLICATE_SUBMISSION |
Duplicate submissions are not allowed for this client |
ERROR_PARAM_INVALID_API_KEY |
Invalid API Key value |
ERROR_PARAM_INVALID_LOCALE |
Invalid locale code |
ERROR_PARAM_INVALID_PARAMETERS |
Invalid parameter in content submission |
ERROR_PARAM_MISSING_SUBJECT_ID |
Submission is missing a product to submit against. A product id is REQUIRED for review submission. |
ERROR_PARAM_MISSING_USER_ID |
This client does not allow unauthenticated submissions. A valid UserId is required. |
ERROR_REQUEST_LIMIT_REACHED |
Rate limiting error, i.e. too many requests per time interval |
ERROR_UNKNOWN |
Unknown error (internal server error, for instance) |
ERROR_UNSUPPORTED |
For unsupported features, clients etc. |
Appendix
Session Token
The submissionSessionToken is returned by all requests and must be provided to all 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.