TurnTo API v1
Overview
Our API is designed for developers who want to programmatically submit and retrieve TurnTo data, apart from the provided TurnTo front-end web widgets.
It provides access to user generated content as well as product catalog, shopper orders, and other statistical data stored in the TurnTo system from within your own applications.
Using the API provides many opportunities to extend the power of the TurnTo platform. Some possible examples:
-
Native mobile applications
-
Custom display applications
-
In-store kiosks
-
Site-wide search integration
-
Shopper profile integration
-
Catalog maintenance
-
Import/export knowledge base articles
-
Multi-language display and translation
Note: To prevent misuse of the access token, consider using a proxy server for external clients (such as Native mobile applications). See the API Implementation overview.
Data Types
-
Questions
-
Answers
-
Replies
-
Checkout Comments
-
Product Ratings & Reviews
-
Knowledgebase Articles
-
User Media
-
Customer Orders
-
Customer Profiles
-
Content Statistics
Mixed Widget and API Installations
Developers can use their custom API-based applications alongside the TurnTo Widgets for the same site ID. This is particularly important for sites that use TurnTo widgets on their website and the API for their native mobile apps.
Localization
TurnTo API supports multi-language sites so that UGC may be created for a specific locale that has been configured for the site. When using an API endpoint to retrieve UGC the locale parameter is used to filter for the required site language.
Note that when using a locale parameter in a request to an endpoint that accepts it, like /products/ugc_summary, only text values that are localizable, like subdimension labels will be returned in the requested language. Values that are decimal numbers are represented with a ‘.’ as decimal point.
Moderation
Content moderation and expert answering is handled through the TurnTo.com Customer Portal.
Emails and Notifications
Emails and notifications are triggered by the TurnTo active outreach engine to either TurnTo’s ESP or a third party.
RESTful Services
Read
The HTTP GET method is used to retrieve resources. Parameters are passed as encoded values in the URL Query String.
Example:
https://api.turnto.com/v1/questions?sku=12345&related=false&publishedOnly=true&limit=10&offset=20
A successful response is returned as a UTF-8 JSON representation with an HTTP response code of 200 (OK).
Content-Type: application/json;charset=UTF-8
Create
The HTTP POST method is used to create resources. Parameters are passed as a UTF-8 JSON representation in the request body.
Content-Type: application/json;charset=UTF-8
A successful response is returned as a UTF-8 JSON representation with an HTTP response code of 201 (Created) and the ‘Location’ header containing link to the newly created resource.
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/questions/{id}
Update (Operation)
The HTTP POST method is used to perform certain operations (such as voteup).
Example:
https://api.turnto.com/v1/questions/12345/voteup
A successful response to a resource operation request is returned as a UTF-8 JSON representation with an HTTP response code of 200 (OK).
Content-Type: application/json;charset=UTF-8
API Rate Limiting
The purpose of API Rate Limiting is to ensure efficient use of system resources and prevent excessive usage from negatively impacting the overall system performance.
Requests to the API are subject to a default limit of 50 requests per second for each site key. If API rate limit is exceeded then a HTTP response code of 429 (Too Many Requests) is returned.
How to Get Started
Step 1: Establish a test account and API key with TurnTo Customer Support
Step 2: Upload test data feeds for order history, product catalog (or use API)
Step 3: Visit http://developers.turnto.com for API documentation resources
Response Codes ¶
When a request cannot be processed successfully a response is returned as a block of JSON containing the error code and an error message.
{"errors": [{
"message": "Unknown access_token",
"code": 115
}]}
A list of all error codes are shown in the table below:
Code | Message | Description | HTTP Status |
---|---|---|---|
101 | Invalid sort parameter format | The supplied sort parameter did not have the correct format. | 400 |
102 | Invalid field in sort parameter | One or more fields in the supplied sort parameter were not valid. | 400 |
103 | Invalid limit or offset | The limit or offset was not numeric. | 400 |
104 | Offset was out of range | The offset was less than zero or greater than or equal to the total number of result set rows. | 400 |
105 | Limit was out of range | The limit was less than zero. | 400 |
106 | No catalog item found for SKU ( |
The SKU was not found in the catalog. | 400 |
107 | No question was found for the specified ID ( |
A question with the specified ID could not be found. | 404 |
108 | Missing Required Fields | Fields were missing for a create or update. | 400 |
109 | Catalog item not found for one or more supplied SKUs | One of the supplied SKUs was not found in the catalog. | 400 |
110 | Please do not include links to other sites | A link to another site was included in the supplied text. | 400 |
111 | Failed to save the question | An unknown error occurred while attempting to save the question. | 500 |
112 | Invalid client_id or client_secret | Client ID / Client Secret combination is not valid. | 403 |
113 | Unknown grant_type | Invalid grant_type. | 400 |
114 | Missing or invalid parameters client_secret, grant_type | The client_secret and/or grant_type was missing or invalid. | 400 |
115 | Unknown access_token | Access token missing or incorrect for invalidate_token service. | 400 |
116 | Missing Authorization header | OAuth2 token not present. | 403 |
117 | Invalid access token | OAuth2 token invalid. | 403 |
118 | Error while generating access_token | Server error. | 500 |
119 | Error while invalidating access_token | Server error. | 400 |
120 | $$$$ method not allowed for this request type | The requested method is not allowed for this request type. | 405 |
121 | Failed to save answer | An unknown error occurred while attempting to save the answer. | 500 |
122 | Too many SKUs requested | There is a maximum of 25 UGC counts that can be returned in a single request. | 400 |
123 | No comment was found for the specified ID ( |
A comment with the specified ID could not be found. | 400 |
124 | Failed to save the comment | An unknown error occurred while attempting to save the comment. | 500 |
125 | Too many SKUs attached to question | The maximum number of SKUs (catalog items) for a question was exceeded. Maximum is 10. | 400 |
126 | Limit too large. Max is 100 | The maximum limit for pagination was exceeded. Maximum is 100. | 400 |
127 | Failed to save the reply | An unknown error occurred while attempting to save the reply. | 500 |
128 | Invalid email address | The format of the email address is invalid. | 400 |
129 | Unknown email address | The email address was not a match for any user. | 400 |
130 | Unknown external ID | The external id was not a match for any user. | 400 |
131 | Bad search filters | At least one of the search filter parameters has an invalid value, or a required filter parameter is missing | 400 |
132 | No answer was found for the specified ID ( |
An answer with the specified ID could not be found. | 404 |
133 | No reply was found for the specified ID ( |
A reply with the specified ID could not be found. | 404 |
134 | No replies found for the specified answer id ( |
No replies found for the specified answer ID ( |
400 |
135 | Error parsing JSON properties | Error parsing JSON properties. | 400 |
136 | Must specify at least one catalog item | Must specify at least one catalog item. | 400 |
137 | One or more duplicate SKUs | At least one SKU is duplicated in the catalog items section. | 400 |
138 | Too many SKUs attached to answer | The maximum number of SKUs (catalog items) for an answer was exceeded. Maximum is 10. | 400 |
139 | No review was found for the specified ID ( |
A review with the specified ID could not be found. | 404 |
140 | Failed to save the review | An unknown error occurred while attempting to save the review. | 500 |
141 | Review rating must be between 1 and 5 | The review rating must be between 1 and 5. | 400 |
142 | Review text too short | The review text length is less than site minimum number of characters. | 400 |
143 | No parent reply was found for the specified id ( |
No parent reply was found for the specified ID. | 400 |
144 | Must specify email address or external ID | User must be identified by an email address or an external ID. | 400 |
145 | Invalid field | The field value was not valid. | 400 |
146 | Invalid delivery date format. | The delivery date was not correctly formatted as yyyy-MM-dd | 400 |
147 | Order not created | The order could not be created. | 400 |
148 | Order not cancelled | The order could not be cancelled. | 400 |
149 | Invalid locale for site | Invalid locale for site. | 400 |
150 | Product update failed | The product update could not be completed. | 400 |
151 | Invalid shopper profile | The shopper profile was invalid. | 400 |
152 | Duplicate shopper profile | The supplied shopper profiles contains duplicates. | 400 |
153 | Failed to save the article | An unknown error occurred while attempting to save the article. | 500 |
154 | No article was found for the specified ID ( |
An article with the specified ID could not be found. | 404 |
155 | No article was found for the specified external ID ( |
An article with the specified external ID could not be found. | 404 |
156 | Must specify ID or external ID | Article to be deleted must be identified by ID or external ID. | 400 |
157 | Invalid expiration date format. | The expiration date was not correctly formatted as yyyy-MM-dd | 400 |
158 | Category not found for one or more supplied category names | One of the supplied category names was not found. | 400 |
159 | One or more duplicate categories | At least one category is duplicated. | 400 |
160 | Brand not found for one or more supplied brand names | One of the supplied brand names was not found. | 400 |
161 | One or more duplicate brands | At least one brand is duplicated. | 400 |
162 | Too many SKUs requested | There is a maximum of 25 SKUs that can be matched in a single request. | 400 |
163 | Invalid date specified for dateCreatedFrom parameter | The date created from parameter is invalid. | 400 |
164 | Invalid date specified for dateCreatedTo parameter | The date created to parameter is invalid. | 400 |
165 | Invalid date specified for dateCreated parameter | The date created parameter is invalid. | 400 |
166 | DateCreated parameter not allowed without external Id | The date created parameter is not allowed without external Id. | 400 |
167 | API rate limit exceeded | The number of requests has exceeded the API rate limit. | 429 |
168 | Reviews not enabled | Reviews are not enabled for this site. | 400 |
169 | No order item found for the specified order ID ( |
An order item with the specified ID and SKU could not be found | 400 |
170 | The specified media could not be associated with the review | The specified media could not be associated with the review | 400 |
171 | Failed to save the media | An unknown error occurred while attempting to save the media. | 500 |
172 | No media items | There were no media items to be uploaded. | 400 |
173 | Too many media items | There is a maximum of 5 media items that can be uploaded in a single request. | 400 |
174 | Unsupported video service | Unsupported video service. | 400 |
175 | Video not found | Video not found. | 400 |
176 | Invalid image type | The uploaded image type is not valid. | 400 |
177 | Image exceeds maximum size | Image exceeds maximum size. | 400 |
178 | Invalid SKU | SKUs must contain at least 1 alphanumeric character. | 400 |
179 | One or more duplicate dimensions | At least one dimension is duplicated. | 400 |
180 | Invalid dimension () | The specified dimension could not be found for this product. | 400 |
181 | Invalid rating | The rating must be between 1 and 5. | 400 |
182 | Tag code not found | One of the specified tag codes was not found. | 400 |
183 | One or more duplicate tag codes | At least one tag code is duplicated. | 400 |
184 | Too many SKUs attached to review | Only 1 SKU can be attached to a review. | 400 |
186 | Invalid boolean parameter | The boolean parameter is not valid. | 400 |
187 | Thanking users is not enabled | Thanking users is not enabled in site configuration. | 400 |
188 | Answer already thanked | The answerer has already been thanked. | 400 |
189 | Invalid UGC Type () | The ugcType parameter contained an invalid UGC type. | 400 |
190 | Failed to register new user | An unknown error occurred while attempting to register a new user. | 400 |
191 | Site not active | The request cannot be processed for a site that is not active. | 403 |
192 | Review text too long | Review text length exceeds maximum of 5000 characters. | 400 |
193 | Review title mandatory | Review title mandatory for site. | 400 |
194 | Review title too long | Review title length exceeds maximum of 1000 characters. | 400 |
195 | Review text mandatory with review title | The review text is mandatory when review title is provided. | 400 |
196 | User already reviewed this catalog item | The user has already submitted a review for this catalog item. | 400 |
197 | Invalid date specified for orderDateFrom parameter | The order date from parameter is invalid. | 400 |
198 | Terms and conditions not accepted | The user has not accepted the terms and conditions. | 400 |
199 | Form submission not found | Form submission not found. | 400 |
200 | Invalid external ID | The external id was invalid for specified email address. | 400 |
201 | Failed to return reviews | An unknown error occurred while attempting to return review results. | 500 |
202 | A single SKU must be specified when searching for related content. | Must supply a single SKU when searching for related content. | 400 |
203 | Shopper profile should be id or code. | Cannot specify shopper profile using both id and code. | 400 |
204 | Unknown profile code (). | Specified shopper profile code was not found. | 400 |
205 | Dimension should be value or code. | Cannot specify dimension using both id and code… | 400 |
206 | Unknown dimension code (). | Specified dimension code was not found. | 400 |
207 | Response text too long. | The review response text length exceeds maximum of 1000 characters. | 400 |
208 | No response was found for the specified id (). | The review response was not found. | 404 |
209 | Failed to save the response. | An unknown error occurred while attempting to save the review response. | 500 |
210 | Must specify Review Response ID. | The review response Id was missing. | 400 |
211 | Seller Ratings not enabled. | Seller ratings not enabled for this site. | 400 |
212 | Invalid orderExternalId or turntoTrackingToken. | Specified order was not found. | 400 |
213 | User already submitted a seller rating for this transaction. | Cannot specify order that already has a seller rating. | 400 |
214 | Invalid ratings value specified. | Comma separated ratings values expected when filtering seller ratings by rating. | 400 |
OAuth ¶
TurnTo uses the OAuth 2.0 Bearer token mechanism to secure most API requests. You can use the ‘/v1/oauth2/token’ endpoint to obtain the Bearer token using your site’s siteKey and authKey which you can copy from your site’s settings area at www.turnto.com.
The Bearer token that’s returned in the response has to be included with every request to the API as part of the value of an ‘Authorization’ request header:
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
As required by OAuth 2.0, every request must be made over SSL (HTTPS). If a request is made over HTTP, the API will return a 403 response error.
Your site can only have one valid API access token at a time and once generated an access token does not expire.
NOTE: It is not necessary to obtain the access token before each API call and doing so may harm performance.
Obtain Access Token ¶
Obtain Access TokenPOST/v1/oauth2/token
Use your site’s site key and auth key (obtainable from the site settings page on www.turnto.com) to request an access token which can then be used to authorize subsequent requests to the API.
Note: Do not share or expose the access token.
If you call this endpoint multiple times, it will return the same access_token, until the token is invalidated either by using the /v1/oauth2/invalidate_token endpoint, or through your site’s settings page on www.turnto.com. Once generated, an access token does not expire.
Example URI
- client_id
string
(required) Example: aaa-aaaThe site key.
- client_secret
string
(required) Example: bbb-bbbThe site secret.
- grant_type
string
(required)The type of credentials. Must be ‘client_credentials’.
Headers
Content-Type: application/x-www-form-urlencoded
Body
client_id=[yourSiteKey]&client_secret=[yourAuthKey]&grant_type=client_credentials
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"token_type": "bearer",
"access_token": "R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya"
}
403
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Invalid client_id or client_secret",
"code": 112
}
]
}
Invalidate Access Token ¶
Invalidate Access TokenPOST/v1/oauth2/invalidate_token
Invalidates the access token passed in the body of the request if this is the currently active token for your site.
Please note that your site can only have one valid access token at a time. Any clients that are making API requests using your token will begin seeing authorization errors once the token is invalidated using this endpoint. Use this endpoint only if your access token has become compromised, or you have a security policy that requires periodically renewing the token.
Example URI
- client_id
string
(required) Example: aaa-aaaThe site key.
- client_secret
string
(required) Example: bbb-bbbThe site secret.
- access_token
string
(required)The access token.
Headers
Content-Type: application/x-www-form-urlencoded
Body
client_id=[your_site_key]&client_secret=[your_auth_key]&access_token=[your_access_token]
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"access_token": "R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya"
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Unknown access_token",
"code": 115
}
]
}
Sites ¶
A number of site configuration settings may be accessed using the TurnTo API. This includes user settings that control which additional user information is to be collected and displayed. Site user settings are considered applicable to all products.
Resource Properties - User Settings
User Settings contains definitions of information to be collected for a user when reviewing a product. Settings for the predefined profiles age range and city/state are included if profile is enabled. A list of any active shopper profiles is also included.
Property | Type | Description |
---|---|---|
ageRange.hidden | boolean | Include age range input on review submission form |
ageRange.required | boolean | Age range is required with content submission |
ageRange.collectDuringContentSubmit | boolean | Age range to be collected during content submission. |
ageRange.displayPublic | boolean | Display age range with user content |
cityState.hidden | boolean | Include user location input on review submission form |
cityState.required | boolean | User location is required with content submission |
cityState.collectDuringContentSubmit | boolean | User location to be collected during content submission |
cityState.displayPublic | boolean | Display user location with user content |
shopperProfiles | resource | List of shopper profiles definitions |
Resource Properties - Shopper Profile
Shopper Profiles are defined by the site administrator and used to capture additional information relating to a user. E.g. Height, Body Type.
Property | Type | Description |
---|---|---|
name | string | Name of profile |
label | string | Localized label |
type | number | Profile type: 0 = select, 1 = free-form text |
hidden | boolean | |
required | boolean | Profile value is required with content submission |
collectDuringContentSubmit | boolean | Profile value to be collected during content submission |
displayPublic | boolean | Display profile value with user content |
values[].id | number | Identifier for a profile value |
values[].label | string | Localized label |
values[].hidden | boolean | |
values[].sortOrder | number | Sort order of profile values |
Site Settings ¶
The site settings contains information on how the site is configured.
Site SettingsGET/v1/sites{?locale}
This endpoint will return site settings for the site identified in the request.
Labels will be localized according to the specified locale.
Example URI
- locale
string
(optional) Example: en_USLabels will be returned in target locale. If omitted use site default.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
userSettings: {
"ageRange": {
"hidden": false,
"required": true,
"collectDuringContentSubmit": true,
"displayPublic": false
},
"cityState": {
"hidden": false,
"required": true,
"collectDuringContentSubmit": false,
"displayPublic": true
},
"shopperProfiles": [
{
"name": "level",
"label": "Level",
"type": 0,
"hidden": false,
"required": true,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 1,
"label": "Head Chef",
"hidden": false,
"sortOrder": 0
},
{
"id": 2,
"label": "Sous Chef",
"hidden": false,
"sortOrder": 1
},
{
"id": 3,
"label": "Line Chef",
"hidden": false,
"sortOrder": 2
}
]
},
{
"name": "signature",
"label": "Signature Dish",
"type": 1,
"hidden": false,
"required": true,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [ {
"id": 4,
"label": "Signature Dish",
"hidden": false,
"sortOrder": 0
}]
}]
}
}
Products ¶
A product is a catalog item which is identified by a SKU in your catalog.
Resource Properties - Product
Property | Type | Description |
---|---|---|
sku | string | Unique catalog identifier for this product |
title | string | Name of the product |
url | string | Web page for this product |
dimensions | resource | Rating sub-dimensions associated with this product |
Resource Properties - Dimension
Dimensions are customer defined rating sub-dimension values that may be captured for a review.
Property | Type | Description |
---|---|---|
id | number | Identifier for the dimension |
label | string | Label to be displayed |
type | number | Dimension type: 1 = Rating, 2 = Range, 3 = Single Select, 4 = Multi Select |
required | boolean | Is dimension value required when submitting review by widget? |
average | number | The average value for this dimension |
values[].id | number | Identifier for a dimension value |
values[].label | string | Display label for a dimension value |
values[].sortOrder | number | Sort order for a dimension value |
values[].count | number | Number of times dimension selected in a review for this product |
Product List ¶
The product detail information describes the product.
Product ListGET/v1/products{?sku,locale}
This endpoint will return the product information for each SKU identified in the request. Up to 25 SKUs may be specified in a single request.
If an individual SKU is invalid or not found this will be reported in the list of results.
Example URI
- sku
string
(required) Example: 12345,22222,33333Comma separated list of SKUs to return product information for. Maximum is 25.
- locale
string
(optional) Example: en_USReturn product information for this locale. If omitted use site default.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
[
{
"sku": "700285064826",
"title": "Oakley XX Frame Accessory Kit - Black",
"url": "http://www.testtt.info/tt4_2/responsivesite/qaOverlay-reviewsEmbed.php?sku=700285064826",
"dimensions": [
{
"id": 1,
"label": "Overall Quality",
"type": 1,
"required": true,
"average": 1,
"values": [
{
"id": 1,
"value": 1
},
{
"id": 2,
"value": 2
},
{
"id": 3,
"value": 3
},
{
"id": 4,
"value": 4
},
{
"id": 5,
"value": 5
}
]
},
{
"id": 2,
"label": "Comfort",
"type": 2,
"required": true,
"average": 2,
"values": [
{
"id": 6,
"sortOrder": 0,
"label": "Low"
},
{
"id": 7,
"sortOrder": 1,
"label": "Medium"
},
{
"id": 8,
"sortOrder": 2,
"label": "High"
}
]
},
{
"id": 3,
"label": "Impression",
"type": 4,
"required": false,
"average": null,
"values": [
{
"id": 9,
"sortOrder": 0,
"label": "Durable",
"count": 0
},
{
"id": 10,
"sortOrder": 1,
"label": "Stylish",
"count": 1
},
{
"id": 11,
"sortOrder": 2,
"label": "Modern",
"count": 0
},
{
"id": 12,
"sortOrder": 3,
"label": "Youthful",
"count": 0
}
]
},
{
"id": 4,
"label": "Weight",
"type": 3,
"required": false,
"average": null,
"values": [
{
"id": 13,
"sortOrder": 0,
"label": "Light",
"count": 1
},
{
"id": 14,
"sortOrder": 1,
"label": "Heavy",
"count": 0
}
]
}
]
},
{
"sku": "088989217022",
"title": "Croakies Suede Leather Spec Cords Eyewear Retainer",
"url": "http://www.testtt.info/tt4_2/responsivesite/qaOverlay-reviewsEmbed.php?sku=088989217022",
"dimensions": [
{
"id": 1,
"label": "Overall Quality",
"type": 1,
"required": true,
"average": null,
"values": [
{
"id": 1,
"value": 1
},
{
"id": 2,
"value": 2
},
{
"id": 3,
"value": 3
},
{
"id": 4,
"value": 4
},
{
"id": 5,
"value": 5
}
]
},
{
"id": 2,
"label": "Comfort",
"type": 2,
"required": true,
"average": null,
"values": [
{
"id": 6,
"sortOrder": 0,
"label": "Low"
},
{
"id": 7,
"sortOrder": 1,
"label": "Medium"
},
{
"id": 8,
"sortOrder": 2,
"label": "High"
}
]
},
{
"id": 3,
"label": "Impression",
"type": 4,
"required": false,
"average": null,
"values": [
{
"id": 9,
"sortOrder": 0,
"label": "Durable",
"count": 0
},
{
"id": 10,
"sortOrder": 1,
"label": "Stylish",
"count": 0
},
{
"id": 11,
"sortOrder": 2,
"label": "Modern",
"count": 0
},
{
"id": 12,
"sortOrder": 3,
"label": "Youthful",
"count": 0
}
]
},
{
"id": 4,
"label": "Weight",
"type": 3,
"required": false,
"average": null,
"values": [
{
"id": 13,
"sortOrder": 0,
"label": "Light",
"count": 0
},
{
"id": 14,
"sortOrder": 1,
"label": "Heavy",
"count": 0
}
]
}
]
}
]
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Too many SKUs requested. Maximum is 25.",
"code": 122
}
]
}
UGC Summary ¶
The UGC (User Generated Content) summary is a collection of data points relating to a particular catalog item, such as number of questions, number of reviews, average rating.
Resource Properties - UGC Summary
Property | Type | Description |
---|---|---|
sku | string | Unique catalog identifier for this product |
questions | number | Number of questions for this product |
relatedQuestions | number | Number of related questions for this product |
comments | number | Number of comments for this product |
answers | number | Number of answers for this product |
relatedAnswers | number | Number of related answers for this product |
reviews | number | Number of reviews for this product |
averageRating | number | Average rating for this product |
ratingBreakdown | map | Number of ratings received for this product broken down the rating value (1-5) |
dimensions | resource | Custom values that can be assigned for this product |
UGC SummaryGET/v1/products/ugc_summary{?sku,locale}
This endpoint will return the UGC summary for each SKU identified in the request. Up to 25 SKUs may be specified in a single request.
If an individual SKU is invalid or not found this will be reported in the list of results.
Example URI
- sku
string
(required) Example: 12345,22222,33333Comma separated list of SKUs to return UGC counts for. Maximum is 25.
- locale
string
(optional) Example: en_USReturn product information for this locale. If omitted use site default.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
[
{
"sku": "700285064826",
"questions": 1,
"relatedQuestions": 0,
"comments": 0,
"answers": 1,
"relatedAnswers": 0,
"reviews": 7,
"averageRating": 4.86,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 6
},
"dimensions": [
{
"id": 1,
"label": "Overall Quality",
"type": 1,
"required": true,
"average": "1.00",
"values": [
{
"id": 1,
"value": 1
},
{
"id": 2,
"value": 2
},
{
"id": 3,
"value": 3
},
{
"id": 4,
"value": 4
},
{
"id": 5,
"value": 5
}
]
},
{
"id": 2,
"label": "Comfort",
"type": 2,
"required": true,
"average": "2.00",
"values": [
{
"id": 6,
"sortOrder": 0,
"label": "Low"
},
{
"id": 7,
"sortOrder": 1,
"label": "Medium"
},
{
"id": 8,
"sortOrder": 2,
"label": "High"
}
]
},
{
"id": 3,
"label": "Impression",
"type": 4,
"required": false,
"average": null,
"values": [
{
"id": 9,
"sortOrder": 0,
"label": "Durable",
"count": 0
},
{
"id": 10,
"sortOrder": 1,
"label": "Stylish",
"count": 1
},
{
"id": 11,
"sortOrder": 2,
"label": "Modern",
"count": 0
},
{
"id": 12,
"sortOrder": 3,
"label": "Youthful",
"count": 0
}
]
},
{
"id": 4,
"label": "Weight",
"type": 3,
"required": false,
"average": null,
"values": [
{
"id": 13,
"sortOrder": 0,
"label": "Light",
"count": 1
},
{
"id": 14,
"sortOrder": 1,
"label": "Heavy",
"count": 0
}
]
}
]
},
{
"sku": "088989217022",
"questions": 0,
"relatedQuestions": 0,
"comments": 0,
"answers": 0,
"relatedAnswers": 0,
"reviews": 0,
"averageRating": 0,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
},
"dimensions": [
{
"id": 1,
"label": "Overall Quality",
"type": 1,
"required": true,
"average": null,
"values": [
{
"id": 1,
"value": 1
},
{
"id": 2,
"value": 2
},
{
"id": 3,
"value": 3
},
{
"id": 4,
"value": 4
},
{
"id": 5,
"value": 5
}
]
},
{
"id": 2,
"label": "Comfort",
"type": 2,
"required": true,
"average": null,
"values": [
{
"id": 6,
"sortOrder": 0,
"label": "Low"
},
{
"id": 7,
"sortOrder": 1,
"label": "Medium"
},
{
"id": 8,
"sortOrder": 2,
"label": "High"
}
]
},
{
"id": 3,
"label": "Impression",
"type": 4,
"required": false,
"average": null,
"values": [
{
"id": 9,
"sortOrder": 0,
"label": "Durable",
"count": 0
},
{
"id": 10,
"sortOrder": 1,
"label": "Stylish",
"count": 0
},
{
"id": 11,
"sortOrder": 2,
"label": "Modern",
"count": 0
},
{
"id": 12,
"sortOrder": 3,
"label": "Youthful",
"count": 0
}
]
},
{
"id": 4,
"label": "Weight",
"type": 3,
"required": false,
"average": null,
"values": [
{
"id": 13,
"sortOrder": 0,
"label": "Light",
"count": 0
},
{
"id": 14,
"sortOrder": 1,
"label": "Heavy",
"count": 0
}
]
}
]
}
]
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Too many SKUs requested. Maximum is 25.",
"code": 122
}
]
}
Update Product ¶
Update product information.
Update ProductPOST/v1/products
This endpoint allows product information to be kept up to date. The product is uniquely identified by sku. If the product for the sku does not exist then it is created.
Request body JSON object properties
Property | Required | Note |
---|---|---|
sku | Yes | Unique identifier for the item in your catalog. |
imageUrl | No | The URL of the image of your catalog item. |
title | Yes | |
price | No | Defaults to 0.00 |
currency | No | Defaults to USD. |
active | No | Boolean - defaults to true. |
url | Yes | The URL of the item on your site. |
category | No | Name of the category this item belongs to. |
categoryPath | No | If you’d like to pass TurnTo a category path for this product, you can include a JSON array of category objects, in the order of most general to the most specific. Each object in the array must include an ‘id’ field (which should be unique across categories as well as regular product SKUs, a ‘name’ field, and optionally a ‘url’ if your store has a page for this category. |
keywords | No | Comma delimited list of keywords that apply to this item. |
inStock | No | Boolean - defaults to true. |
virtualParentCode | No | An arbitrary string used to group products. |
isCategory | No | Is this a category rather than an orderable item - defaults to false. |
members | No | If product is a bundle of other products, specify comma delimited list of skus. |
brand | No | The product’s brand name. If used together with ‘MPN’, this field uniquely identifies the product. |
mpn | No | (Manufacturer part number) The number which uniquely identifies the product to its manufacturer. If used together with ‘BRAND’, this field uniquely identifies the product across the entire catalog. |
isbn | No | (International Standard Book Number) A unique numerical identifier for commercial books published since 1970 that can be found on the back of the book along with the barcode. |
upc | No | (Universal Product Code) A unique numerical identifier for commercial products that’s usually associated with a barcode printed on retail merchandise. Used mainly in North America. |
ean | No | (European Article Number) A unique numerical identifier for commercial products that’s usually associated with a barcode printed on retail merchandise. Used mainly outside of North America. |
jan | No | (Japanese Article Number) A unique numerical identifier for commercial products that’s usually associated with a barcode printed on retail merchandise. Used in Japan. |
asin | No | (Amazon Standard Identification Number) Uniquely identifies each product sold on amazon.com. |
mobileItemUrl | No | The URL of the item on your mobile site. |
localeData | No | A JSON field that allows the specification of locale specific product titles and urls. If specified, ‘title’ and ‘itemUrl’ are required, ‘mobileItemUrl’ is optional. |
Example URI
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"sku": "11112222",
"title": "Bananas",
"url": "www.fruit.com/bananas",
"imageUrl": "www.fruit.com/img/banana.jpg",
"currency": "USD",
"price": "109.99",
"active": true,
"category": "fruit",
"categoryPath": "",
"keywords": "fruit,yellow",
"inStock": true,
"virtualParentCode": "BAN",
"isCategory": false,
"members": "",
"brand": "",
"mpn": "",
"isbn": "",
"upc": "",
"ean": "",
"jan": "",
"asin": "",
"mobileItemUrl": "",
"localeData": "{\"fr_CA\": {\"title\": \"Bleu Chemise\", \"itemUrl\": \"http://domain.com/pathToFrenchProductPage\"} }"
}
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"sku": "11112222"
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Invalid field (price)",
"code": 145
}
]
}
Orders ¶
An order is a record of a customer purchase on your site. The order consists of order information, customer contact details, and a list of line items for each product purchased.
Resource Properties - Order
Property | Type | Description |
---|---|---|
orderId | string | Unique order Id |
deliveryDate | date | Date of delivery |
postalCode | string | Order postal code |
emailOptOut | boolean | User opted out of receiving emails |
user | resource | |
items | resource | list order items |
Resource Properties - Order Item
Property | Type | Description |
---|---|---|
lineItemId | string | Identifier for the line item |
title | string | Product title |
url | string | Product URL |
sku | string | Product sku |
brand | string | Product brand |
price | number | Line item amount |
itemImageUrl | string | Item image URL |
Create Order ¶
Creates an order representing a customer purchase. The order may contain multiple order lines.
Create OrderPOST/v1/orders/create
This endpoint will typically will be called from an order confirmation page. The customer first name, last name, and email address are required. An order item object is populated for each line item.
Request body JSON object properties
The properties that are passed during Order creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
orderId | Yes | Unique Id of the order to be created. |
deliveryDate | No | Date of delivery, format is yyyy-MM-dd |
locale | No | If omitted use site default. |
postalCode | No | |
emailOptOut | No | Set to the boolean value ‘true’ if the user is to receive no emails from TurnTo. Defaults to false. |
user.firstName | Yes | |
user.lastName | Yes | |
user.nickName | No | |
user.emailAddress | Yes | Email address is required to identify the user |
user.externalId | No | |
items[].lineItemId | No | |
items[].title | Yes | |
items[].url | Yes | |
items[].sku | Yes | |
items[].brand | No | |
items[].price | No | |
items[].itemImageUrl | Yes |
Example URI
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"orderId": "99977",
"deliveryDate": "2015-05-20",
"locale": "en_US",
"postalCode": "10667",
"emailOptOut": false,
"user": {
"firstName": "Andy",
"lastName": "Adamson",
"nickName": "",
"emailAddress": "andrew@sample.com",
"externalId": null
},
"items": [
{
"lineItemId": "1",
"title": "Sneakers",
"url": "www.treadzzzzz.com/sneakers",
"sku": "BF0010020",
"brand": "Sprinter",
"price": "29.99",
"itemImageUrl": "www.treadzzzzz.com/img/sneakers.jpg"
},
{
"lineItemId": "2",
"title": "Cleats",
"url": "www.treadzzzzz.com/cleats",
"sku": "BF0020080",
"brand": "Hoofer",
"price": "49.99",
"itemImageUrl": "www.treadzzzzz.com/img/cleats.jpg"
}
]
}
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 3317217,
"orderId": "99977"
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Invalid delivery date",
"code": 146
}
]
}
Cancel Order ¶
Cancel OrderPOST/v1/orders/cancel
This endpoint allows an entire order or an order line item to be cancelled. To cancel an entire order only the order Id is supplied. To cancel an order line item the sku matching the line item sku must be supplied.
Request body JSON object properties
Property | Required | Note |
---|---|---|
orderId | Yes | Id of the order to be cancelled. |
sku | No | If provided only the order item with matching sku will be cancelled. |
Example URI
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"orderId": "99977",
"sku": ""
}
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"orderId": "99977",
"sku": ""
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Order not cancelled",
"code": 148
}
]
}
Media ¶
Media is a UGC type that includes photos, videos, and audio that can be created for a user. A media content item must be associated with at least one catalog item when it is created.
Photos
Photo images are sent as Base64 binary encoded data in request body JSON properties. The maximum size of an image is 10MB.
Valid image MIME types are:
-
image/jpeg
-
image/jpg
-
image/pjpeg
-
image/png
-
image/x-png
After photos have been uploaded the images are resized and transferred to a web accessible location.
The following image sizes will be generated:
Key | Description |
---|---|
PZ320 | Scales down the lesser of the width and height to be 320 then hides the difference in the other dimension by cropping on each side |
L560 | Scales down the larger of the width and height to be 560 |
L1000 | Scales down the larger of the width and height to be 1000 |
L1800 | Scales down the larger of the width and height to be 1800 |
LH720 | Scales the height to be 720 up to maximum width of 1280 |
LW600 | Scales the width to be 600 up to maximum height of 10000 |
The key can be appended to the image name of the ‘originalUrl’ and used to display a resized image with the corresponding format and dimensions. For example, to display the small size image “L560” the image name would be modified as follows: <originalImage>_L560.<imageType>
The resized images are available once processing has completed.
Until processing has completed the ‘normalUrl’ property will return a URL for the raw uploaded image and the ‘thumbnailUrl’ property will return null.
Videos
Videos are specified by using the video URL link. Currently, all videos must be hosted by YouTube and set to Public.
Information allowing the video to be embedded on customer site is retrieved and made available in the Media properties.
Audio
Audio is not currently supported.
Resource Properties - Media
Property | Type | Description |
---|---|---|
id | number | TurnTo unique ID for this media |
caption | string | Caption |
type | string | Media type (photo,video,audio) |
width | number | Image width |
height | number | Image height |
imageType | string | Image type (jpeg, jpg, png) |
normalUrl | string | Normal image URL |
thumbnailUrl | string | Thumbnail image/video URL |
originalUrl | string | Original image URL |
provider | string | Video service provider |
providedLink | string | Video URL |
thumbnailWidth | string | Video thumbnail width |
thumbnailHeight | string | Video thumbnail height |
authorName | string | Video author name |
authorUrl | string | Video author URL |
providerId | string | Video provider Id |
html | string | Video html |
authorName | string | Video author name |
tags | string | List of tag codes associated with this media |
user | resource | The user that created this media content. Nested user block - see Users section |
catalogItems | resource | Products for which this media is associated with. Nested products block - see Products section |
dateCreated | date | Date media created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
Save Media ¶
This endpoint is used to create media content. In the case of photos, the image is uploaded by including its Base64-encoded data in the request. Images are oriented based on their EXIF orientation data. For video, the URL link must be supplied which is then verified with the video provider. Up to 5 media items may be specified.
A user credential is required to create a media content. For an existing user, the user will be identified either by email address or a unique external ID. If the media content is being created by a new user then the user first and last name must be supplied.
The media content must be associated with at least 1 catalog item and up to 10 SKUs may be specified.
Save MediaPOST/v1/media
This endpoint
Request body JSON object properties
The properties that are passed during Media creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
locale | No | If omitted use site default. |
user.firstName | No | |
user.lastName | No | |
user.nickName | No | |
user.emailAddress | No | Either email address or externalId is required to identify the user |
user.externalId | No | Either email address or externalId is required to identify the user |
user.city | No | |
user.state | No | |
user.country | No | |
user.ageRange | No | |
user.shopperProfiles[].id | No | |
user.shopperProfiles[].value | No | |
catalogItems[].sku | Yes | The SKU of the catalog item that this media is associated with. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created. |
catalogItems[].title | No | The title of the catalog item that this media is associated with. This can be omitted if the item already exists in your site’s catalog at TurnTo |
catalogItems[].url | No | The URL of the catalog item that this media is associated with. This can be omitted if the item already exists in your site’s catalog at TurnTo |
photo[].caption | No | The caption must be provided for each photo b64data supplied |
photo[].b64data | No | Base64 encoded image |
video[].caption | No | The caption must be provided for each video URL supplied |
video[].url | No | Video URL link |
Example URI
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"locale": "en_US",
"catalogItems": [
{
"sku": "sku0207644428",
"title": "zzz tablet",
"url": "www.zzz.com/tablet"
}
],
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "andrew@sample.com"
},
"photo": [
{
"caption": "so cool!",
"b64data": "data:image/jpeg;base64,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"
}
],
"video": [
{
"caption": "build customer community",
"url": "https://www.youtube.com/watch?v=Vr_r2uBg56g"
}
]
}
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"media": {
"photo": [
{
"id": 2,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": false,
"dateCreated": null,
"normalUrl": "http://www.turnto.com/imagestore/media/temp/6AACB0D7BB7A1DC9AE8455D6690A86F5_1535487113608_1.jpeg",
"thumbnailUrl": null,
"originalUrl": "http://www.turnto.com/imagestore/media/temp/6AACB0D7BB7A1DC9AE8455D6690A86F5_1535487113608_1.jpeg",
"tags": []
}
],
"video": [
{
"id": 3,
"type": "video",
"caption": "build customer community",
"provider": "youtube",
"providedLink": "https://www.youtube.com/watch?v=Vr_r2uBg56g",
"thumbnailUrl": "https://i.ytimg.com/vi/Vr_r2uBg56g/hqdefault.jpg",
"thumbnailWidth": 480,
"thumbnailHeight": 360,
"width": 480,
"height": 270,
"authorName": "TurnTo",
"authorUrl": "https://www.youtube.com/user/TurnToNetworks",
"providerId": "Vr_r2uBg56g",
"html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/Vr_r2uBg56g?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen></iframe>",
"s88thumbDims": {
"width": 117,
"height": 88,
"scaledTo": "h",
"targetLeft": -15,
"targetTop": 0
},
"s64thumbDims": {
"width": 85,
"height": 64,
"scaledTo": "h",
"targetLeft": -11,
"targetTop": 0
},
"locale": "en_US",
"published": false,
"dateCreated": null,
"tags": []
}
],
"audio": []
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No catalog item found for sku (5558886554)",
"code": 106
}
]
}
User Media List ¶
User Media ListGET/v1/media{?userId,email,sku}
This endpoint will return a list of media for a user, optionally filtered by SKU. Must specify either userId or email to identify a user.
Example URI
- userId
string
(optional) Example: EXT12345External Id of the user.
string
(optional) Example: andrew@sample.comThe email address of the user.
- sku
string
(optional) Example: 12345The SKU to filter media by.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"media": {
"photo": [
{
"id": 1,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": false,
"dateCreated": "2018-08-28T16:09:11-04:00",
"normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/5C11B3371CEACE00A7DBBDEDA9360E17_1535486950501_1_L1000.jpeg",
"thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/5C11B3371CEACE00A7DBBDEDA9360E17_1535486950501_1_PZ320.jpeg",
"originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/5C11B3371CEACE00A7DBBDEDA9360E17_1535486950501_1.jpeg",
"tags": []
}
],
"video": [
{
"id": 2,
"type": "video",
"caption": "build customer community",
"provider": "youtube",
"providedLink": "https://www.youtube.com/watch?v=Vr_r2uBg56g",
"thumbnailUrl": "https://i.ytimg.com/vi/Vr_r2uBg56g/hqdefault.jpg",
"thumbnailWidth": 480,
"thumbnailHeight": 360,
"width": 480,
"height": 270,
"authorName": "TurnTo",
"authorUrl": "https://www.youtube.com/user/TurnToNetworks",
"providerId": "Vr_r2uBg56g",
"html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/Vr_r2uBg56g?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen></iframe>",
"s88thumbDims": {
"width": 117,
"height": 88,
"scaledTo": "h",
"targetLeft": -15,
"targetTop": 0
},
"s64thumbDims": {
"width": 85,
"height": 64,
"scaledTo": "h",
"targetLeft": -11,
"targetTop": 0
},
"locale": "en_US",
"published": false,
"dateCreated": "2018-08-28T16:11:54-04:00",
"tags": []
}
],
"audio": []
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Unknown Email Address",
"code": 129
}
]
}
Questions ¶
A question is a UGC type that is tied to a catalog item, which is identified by a SKU in your catalog. A question can contain nested answers.
Resource Properties - Question
Property | Type | Description |
---|---|---|
id | number | TurnTo unique ID for this question |
dateCreated | date | Date question created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
approvedDate | date | Date question approved (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
text | string | Question text |
textLength | number | Number of characters in question text |
locale | string | Locale of question |
published | boolean | Is published? |
csFlag | boolean | Is flagged for customer service? |
irrelevantFlag | boolean | Is irrelevant? |
unansweredAlert | boolean | Unanswered alert? |
reviewedFlag | boolean | Is reviewed? |
autoModerated | boolean | Is auto moderated? |
flagForExpert | boolean | Flag for expert? |
upVotes | number | Number of up votes received |
isStaff | boolean | Is staff? |
isCategoryQuestion | boolean | Is category question? |
tags | string | List of tag codes associated with this question |
user | resource | The user that asked this question. Nested user block - see Users section |
userIpAddr | string | The IP address of the UGC author |
catalogItems | resource | Products for which this question was asked. Nested products block - see Products section |
answerCount | number | Number of answers posted for this question |
answers | resource | Answers posted for this question. Nested answers block - see Answers section |
Question List ¶
Question ListGET/v1/questions{?sku,related,publishedOnly,tags,locale,limit,offset,sort}
This endpoint will return a list of questions about a catalog item with nested answers and replies. The nested answers will be sorted to return Best Answers first. The best answer for a question is indicated by the boolean property bestAnswer being set to true.
Options to sort using answer count, date created, text, text length, and up votes are available. Results may be filtered by by whether or not related question, published status, tag code, and locale. Pagination of results is supported using limit and offset parameters.
Example URI
- sku
string
(required) Example: 12345The SKU of the topic catalog item that the returned questions are about.
- related
boolean
(optional) Default: false Example: falseIf true, the questions that are returned will be ones that are related to the SKU, either as Virtual Parent Siblings, or group members, or category members.
Choices:
true
false
- publishedOnly
boolean
(optional) Default: true Example: trueIf true, only return published questions.
Choices:
true
false
- tags
string
(optional) Example: CSR,DAM,SOTIf specified, only return questions that contain at least 1 of the comma separated tag codes.
- locale
string
(optional) Example: en_USOnly return questions for this locale.
- limit
number
(optional) Default: 50 Example: 10Maximum number of questions to show.
- offset
number
(optional) Default: 0 Example: 10Offset into question results. Zero based so first result is offset = 0.
- sort
string
(optional) Default: dateCreated:desc Example: dateCreated:descField to sort questions by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
answerCount
dateCreated
text
textLength
upVotes
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"questions": [
{
"id": 7,
"dateCreated": "2016-02-08T11:17:16-05:00",
"approvedDate": null,
"text": "How many different attachments come with this food processor?",
"textLength": 61,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 1,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 3,
"answers": [
{
"id": 6,
"dateCreated": "2016-02-08T11:17:18-05:00",
"reviewedDate": null,
"text": "It came with 5. 3 for slicing, 2 for puree.",
"textLength": 43,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 3,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 1,
"replies": [
{
"id": 2,
"text": "Thank you so much!",
"locale": "en_US",
"published": false,
"dateCreated": "2016-02-08T14:14:42-05:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"parentReplyId": null,
"parentAnswerId": 6,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 2
},
"replies": [],
"replyCount": 0
}
],
"user": {
"nickName": "Billy B.",
"firstName": "Bill",
"lastName": "Brine",
"emailAddress": null,
"externalId": "22222",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"bestAnswer": true,
"tags": []
},
{
"id": 7,
"dateCreated": "2016-02-08T11:17:18-05:00",
"reviewedDate": null,
"text": "There were no attachments with this item.",
"textLength": 41,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 1,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Chuck C.",
"firstName": "Chuck",
"lastName": "Chips",
"emailAddress": null,
"externalId": "33333",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"tags": [
"COM",
"ALU"
]
},
{
"id": 5,
"dateCreated": "2016-02-08T11:17:17-05:00",
"reviewedDate": null,
"text": "Can't remember exactly... might have been 3 or 4.",
"textLength": 49,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Alan A.",
"firstName": "Alan",
"lastName": "Armley",
"emailAddress": null,
"externalId": "11111",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"tags": []
}
],
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 2
},
"catalogItems": [
{
"sku": "FRSM0987742",
"title": "Fruit Samarai",
"url": "http://dev.turntodev.com/products?sku=FRSM0987742",
"category": null
}
],
"tags": [
"SOT",
"FLF",
"DAM",
"BRL"
]
},
{
"id": 8,
"dateCreated": "2016-02-08T11:17:23-05:00",
"approvedDate": null,
"text": "How long is the warranty for this product?",
"textLength": 42,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 0,
"answers": [],
"user": {
"nickName": "Dougie D.",
"firstName": "Douglas",
"lastName": "Diamond",
"emailAddress": "dd@example.com",
"externalId": null,
"city": "Portland",
"state": "OR",
"country": "US",
"ageRange": 3
},
"catalogItems": [
{
"sku": "FRSM0987742",
"title": "Fruit Samarai",
"url": "http://dev.turntodev.com/products?sku=FRSM0987742",
"category": null
}
],
"tags": []
}
],
"offset": 0,
"limit": 50,
"total": 2
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{"errors": [{
"message": "Invalid limit or offset",
"code": 103
}]}
{"errors": [{
"message": "No catalog item was found for sku 7969494",
"code": 106
}]}
Question Detail ¶
Question DetailGET/v1/questions/{id}
This endpoint will return a single question with its nested answers and replies. The required question is identified by its ID.
The nested answers will be sorted to return Best Answers first. The best answer for a question is indicated by the boolean property bestAnswer being set to true.
Example URI
- id
number
(required) Example: 12345The ID of the question.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 7,
"dateCreated": "2016-02-08T11:17:16-05:00",
"approvedDate": null,
"text": "How many different attachments come with this food processor?",
"textLength": 61,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 1,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 3,
"answers": [
{
"id": 6,
"dateCreated": "2016-02-08T11:17:18-05:00",
"reviewedDate": null,
"text": "It came with 5. 3 for slicing, 2 for puree.",
"textLength": 43,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 3,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 1,
"replies": [
{
"id": 2,
"text": "Thank you so much!",
"locale": "en_US",
"published": false,
"dateCreated": "2016-02-08T14:14:42-05:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"parentReplyId": null,
"parentAnswerId": 6,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 2
},
"replies": [],
"replyCount": 0
}
],
"user": {
"nickName": "Billy B.",
"firstName": "Bill",
"lastName": "Brine",
"emailAddress": null,
"externalId": "22222",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"tags": [],
"bestAnswer": true
},
{
"id": 7,
"dateCreated": "2016-02-08T11:17:18-05:00",
"reviewedDate": null,
"text": "There were no attachments with this item.",
"textLength": 41,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 1,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Chuck C.",
"firstName": "Chuck",
"lastName": "Chips",
"emailAddress": null,
"externalId": "33333",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"tags": [
"COM",
"ALU"
]
},
{
"id": 5,
"dateCreated": "2016-02-08T11:17:17-05:00",
"reviewedDate": null,
"text": "Can't remember exactly... might have been 3 or 4.",
"textLength": 49,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Alan A.",
"firstName": "Alan",
"lastName": "Armley",
"emailAddress": null,
"externalId": "11111",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"tags": []
}
],
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 2
},
"catalogItems": [
{
"sku": "FRSM0987742",
"title": "Fruit Samarai",
"url": "http://dev.turntodev.com/products?sku=FRSM0987742",
"category": null
}
],
"tags": [
"SOT",
"FLF",
"DAM",
"BRL"
]
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No question was found for the specified id (949494949949)",
"code": 107
}
]
}
Create Question ¶
Create QuestionPOST/v1/questions
Creates a new question for a catalog item or multiple catalog items. Up to 10 SKUs may be specified for a question.
A user credential is required to create a user question. For an existing user, the user will be identified either by email address or a unique external ID. If the question is being created by a new user then the user first and last name must be supplied.
If the user credentials are omitted then an anonymous question will be created.
Request body JSON object properties
The properties that are passed during Question creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
text | Yes | |
locale | No | If omitted use site default. |
user.firstName | No | |
user.lastName | No | |
user.nickName | No | |
user.emailAddress | No | Either email address or externalId is required to identify the user |
user.externalId | No | Either email address or externalId is required to identify the user |
user.city | No | |
user.state | No | |
user.country | No | |
user.ageRange | No | |
user.shopperProfiles[].id | No | |
user.shopperProfiles[].value | No | |
userIpAddr | No | The IP address of the UGC author |
catalogItems[].sku | Yes | The SKU of the catalog item that this question is about. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created. |
catalogItems[].title | No | The title of the catalog item that this question is about. This can be omitted if the item already exists in your site’s catalog at TurnTo |
catalogItems[].url | No | The URL of the catalog item that this question is about. This can be omitted if the item already exists in your site’s catalog at TurnTo |
Example URI
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"text": "How many different attachments come with this food processor?",
"locale": "en_US",
"catalogItems": [
{
"sku": "FRSM0987742",
"title": "Fruit Samarai",
"url": "http://dev.turntodev.com/products?sku=FRSM0987742"
}
],
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 2,
"shopperProfiles": []
},
"userIpAddr": "123.456.789.100"
}
201
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/questions/{id}
Body
{
"id": 7,
"dateCreated": "2016-02-08T11:17:15-05:00",
"approvedDate": null,
"text": "How many different attachments come with this food processor?",
"textLength": 61,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": false,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 2
},
"answerCount": 0,
"answers": [],
"catalogItems": [
{
"sku": "FRSM0987742",
"title": "Fruit Samarai",
"url": "http://dev.turntodev.com/products?sku=FRSM0987742",
"category": null
}
]
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No catalog item was found for sku (7969494)",
"code": 106
}
]
}
Question Vote Up ¶
Question Vote UpPOST/v1/questions/{id}/voteup
This endpoint registers an up vote for a question.
Example URI
- id
number
(required) Example: 12345The ID of the question.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 7,
"dateCreated": "2016-02-08T11:17:16-05:00",
"approvedDate": null,
"text": "How many different attachments come with this food processor?",
"textLength": 61,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 1,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 0,
"answers": [],
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 2
},
"catalogItems": [
{
"sku": "FRSM0987742",
"title": "Fruit Samarai",
"url": "http://dev.turntodev.com/products?sku=FRSM0987742",
"category": null
}
],
"tags": []
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No question was found for the specified id (145454)",
"code": 107
}
]
}
Answer More Questions ¶
Answer More QuestionsGET/v1/amq{?email,userId,sku,locale,questionsOnly,purchasesOnly,limit,offset}
This endpoint supports an API implementation of the “Do More” functionality, also known as Answer More Questions (AMQ).
A “Do More” screen or AMQ box displays after a user has written an answer or a review or clicks the “Do More” link in the TurnTo widget.
It displays products that the user is eligible to review or questions the users may be able to answer. Questions shown are for the current item, related items, and items connected to previous purchases.
The user is identified using either email address or external ID. User identifier can be omitted to obtain questions for anonymous users.
Pagination of questions is supported using the ‘limit’ and ‘offset’ parameters. The boolean property ‘moreQuestions’ is used to indicate if more questions are available.
The ‘questionsOnly’ and ‘purchasesOnly’ parameters can be used to return only questions or purchases respectively.
Example URI
string
(optional) Example: a@a.comThe user’s email address.
- userId
string
(optional) Example: 7654321The user’s external ID.
- sku
string
(required) Example: 12345The SKU of the current item.
- locale
string
(optional) Example: en_USReturn results for this locale. If omitted use site default.
- questionsOnly
boolean
(optional) Default: false Example: falseOnly return questions.
Choices:
true
false
- purchasesOnly
boolean
(optional) Default: false Example: falseOnly return purchases.
Choices:
true
false
- limit
number
(optional) Default: 10 Example: 10Maximum number of questions to return.
- offset
number
(optional) Default: 0 Example: 0Offset into question results. Zero based so first result is offset = 0.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"questions": [
{
"id": 12,
"dateCreated": "2016-07-21T14:51:18-04:00",
"approvedDate": "2016-07-21T14:51:43-04:00",
"text": "Is this a trilogy?",
"textLength": 18,
"locale": "en_US",
"published": true,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": true,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 0,
"answers": [],
"user": {
"nickName": "bobby",
"firstName": "Bob",
"lastName": "Peterson",
"emailAddress": "bob@peterson.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null
},
"catalogItems": [
{
"sku": "2",
"title": "The Matrix",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
"category": "movies"
}
]
},
{
"id": 11,
"dateCreated": "2016-07-21T14:51:17-04:00",
"approvedDate": "2016-07-21T14:51:44-04:00",
"text": "Are there DVD extras?",
"textLength": 21,
"locale": "en_US",
"published": true,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": true,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 0,
"answers": [],
"user": {
"nickName": "Paulie",
"firstName": "Paul",
"lastName": "Back",
"emailAddress": "paul@back.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null
},
"catalogItems": [
{
"sku": "1",
"title": "Die Hard 2",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
"category": "movies"
}
]
},
{
"id": 3,
"dateCreated": "2013-09-19T16:00:58-04:00",
"approvedDate": null,
"text": "What happens at the end?",
"textLength": 24,
"locale": "en_US",
"published": true,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": true,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 1,
"answers": [
{
"id": 16,
"dateCreated": "2013-09-22T14:24:05-04:00",
"reviewedDate": null,
"text": "Our hero survives",
"textLength": 17,
"locale": "en_US",
"published": true,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": true,
"purchaseDate": null,
"itemQuestionId": 15,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "buzz",
"firstName": "Buzz",
"lastName": "Right",
"emailAddress": "buzz@right.org",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": {
"text": "Staff",
"imageUrl": ""
}
},
"bestAnswer": true
}
],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Barker",
"emailAddress": "isharee2@bbbb.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null
},
"catalogItems": [
{
"sku": "1",
"title": "Die Hard 2",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
"category": "movies"
}
]
}
],
"moreQuestions": false,
"purchases": [
{
"orderId": "W5249315",
"sku": "030150 SM",
"title": "Everlasting Fire Plug 2.25 Inch",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=030150 SM",
"imgId": 22
},
{
"orderId": "W5249331",
"sku": "311408 4L",
"title": "Kong Training Dummy Large",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=311408 4L",
"imgId": 22
},
{
"orderId": "W5249347",
"sku": "311066",
"title": "Kong Bone w/Rope",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=311066",
"imgId": 22
},
{
"orderId": "W5249366",
"sku": "492059 5 GLW",
"title": "Orbee-Tuff Cosmos Ball 5 Inch Luna Glow",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=492059 5 GLW",
"imgId": 22
}
],
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "spike@dog.org",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Invalid Email Address",
"code": 128
}
]
}
Answers ¶
An answer is a UGC type that’s tied to a question, which is identified by a unique identifier. An answer can contain nested replies.
Resource Properties - Answer
Property | Type | Description |
---|---|---|
id | number | TurnTo unique ID for this answer |
dateCreated | date | Date that the answer was created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
reviewedDate | date | Date that the answer was reviewed by moderator (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
text | string | Answer text |
textLength | number | Number of characters in answer text |
locale | string | Locale of answer |
published | boolean | Is published? |
csFlag | boolean | Is flagged for customer service? |
inappropriateFlag | boolean | Is inappropriate? |
reviewedFlag | boolean | Is reviewed? |
autoModerated | boolean | Is auto moderated? |
upVotes | number | Number of up votes received |
thanked | boolean | Is thanked? |
isStaff | boolean | Is staff? |
purchaseDate | date | Date product purchased (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
itemQuestionId | number | TurnTo unique ID for the question |
tags | string | List of tag codes associated with this answer |
user | resource | The user that posted this answer. Nested user block - see Users section |
userIpAddr | string | The IP address of the UGC author |
catalogItems | resource | Products for which this answer is also applicable. Nested products block - see Products section |
replyCount | number | Number of replies posted for this answer |
replies | resource | Replies posted for this answer. Nested replies block - see Replies section |
Question Answers ¶
Question AnswersGET/v1/questions/{id}/answers{?publishedOnly,locale,limit,offset,sort}
This endpoint will return a list of answers for the specified question. By default, the answers will be sorted to return Best Answers first. Additional options to sort using date created, text, text length, and up votes are available. The best answer for a question is indicated by the boolean property bestAnswer being set to true.
Results may be filtered by published status and locale. Pagination of results is supported using limit and offset parameters.
Example URI
- id
number
(required) Example: 12345The ID of the question.
- publishedOnly
boolean
(optional) Default: true Example: trueIf true, only return published answers.
Choices:
true
false
- locale
string
(optional) Example: en_USOnly return answers for this locale.
- limit
number
(optional) Default: 50 Example: 50Maximum number of answers to show.
- offset
number
(optional) Default: 0 Example: 10Offset into answers results. Zero based so first result is offset = 0.
- sort
string
(optional) Default: dateCreated:desc Example: textLength:descField to sort answers by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
dateCreated
text
textLength
upVotes
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"answers": [
{
"id": 6,
"dateCreated": "2016-02-08T11:17:18-05:00",
"reviewedDate": null,
"text": "It came with 5. 3 for slicing, 2 for puree.",
"textLength": 43,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 3,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Billy B.",
"firstName": "Bill",
"lastName": "Brine",
"emailAddress": null,
"externalId": "22222",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"bestAnswer": true,
"tags": []
},
{
"id": 7,
"dateCreated": "2016-02-08T11:17:18-05:00",
"reviewedDate": null,
"text": "There were no attachments with this item.",
"textLength": 41,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 1,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Chuck C.",
"firstName": "Chuck",
"lastName": "Chips",
"emailAddress": null,
"externalId": "33333",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"tags": [
"COM",
"ALU"
]
},
{
"id": 5,
"dateCreated": "2016-02-08T11:17:17-05:00",
"reviewedDate": null,
"text": "Can't remember exactly... might have been 3 or 4.",
"textLength": 49,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Alan A.",
"firstName": "Alan",
"lastName": "Armley",
"emailAddress": null,
"externalId": "11111",
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"tags": []
}
],
"offset": 0,
"limit": 50,
"total": 3
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No question was found for the specified id (49439)",
"code": 107
}
]
}
Answer Detail ¶
Answer DetailGET/v1/answers/{id}
This endpoint will return a single answer.
The required answer is identified by its ID.
Example URI
- id
number
(required) Example: 12345The ID of the answer.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 12,
"dateCreated": "2015-06-25T14:28:57-04:00",
"reviewedDate": null,
"text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
"textLength": 65,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 18,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Brimmer",
"emailAddress": null,
"externalId": "12345",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 0,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "waffles"
},
{
"id": 1
}
]
},
"tags": []
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No answer was found for the specified id (949494949949)",
"code": 132
}
]
}
Create Answer ¶
Create AnswerPOST/v1/questions/{id}/answers
Creates a new answer for an existing question. The answer may be associated with up to 10 additional catalog items by supplying a list of those catalog items. If the answer is only associated with the catalog item for which the question was created then no catalog items should be supplied.
A user credential is required to create an answer. For an existing user, the user will be identified either by email address or a unique external ID. If the answer is being created by a new user then the user first and last name must be supplied.
If the answer is created in response to a question email, the embedded link to initiate the create answer flow includes a parameter ‘turntoTrackingToken’ that contains encoded information about the email recipient. The token can be passed to the create answer endpoint to allow the answer to be associated with the question email it came from.
Request body JSON object properties
The properties that are passed during Answer creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
text | Yes | |
locale | No | If omitted use site default. |
user.firstName | Yes | |
user.lastName | Yes | |
user.nickName | No | |
user.emailAddress | No | Either email address or externalId is required to identify the user |
user.externalId | No | Either email address or externalId is required to identify the user |
user.city | No | |
user.state | No | |
user.country | No | |
user.ageRange | No | |
user.shopperProfiles[].id | No | |
user.shopperProfiles[].value | No | |
userIpAddr | No | The IP address of the UGC author |
catalogItems[].sku | No | The SKU of the catalog item that this answer is also being attached to. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created. |
catalogItems[].title | No | The title of the catalog item for this SKU. This can be omitted if the item already exists in your site’s catalog at TurnTo |
catalogItems[].url | No | The URL of the catalog item for this SKU. This can be omitted if the item already exists in your site’s catalog at TurnTo |
turntoTrackingToken | No | The tracking token included in the create answer link. |
Example URI
- id
number
(required) Example: 12345The ID of the answer.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
"locale": "en_US",
"catalogItems": [],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Brimmer",
"emailAddress": "",
"externalId": "12345",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 0,
"shopperProfiles": [
{
"id": 1
},
{
"id": 4,
"value": "waffles"
}
]
},
"userIpAddr": "123.456.789.100",
"turntoTrackingToken": "eyJpcXJsSWQiOjEyMzQ1LCJ0dXJudG9RdWVzdGlvbklkIjoiNyIsInR1cm50b0VtYWlsVHlwZSI6InF1ZXN0aW9uIn0%3D"
}
201
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/answers/{id}
Body
{
"id": 12,
"dateCreated": "2015-06-25T14:28:57-04:00",
"reviewedDate": null,
"text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
"textLength": 65,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 18,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Brimmer",
"emailAddress": null,
"externalId": "12345",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 0,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "waffles"
},
{
"id": 1
}
]
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No question was found for the specified id (49439)",
"code": 107
}
]
}
Answer Vote Up ¶
Answer Vote UpPOST/v1/answers/{id}/voteup
Registers an up vote for an answer.
Example URI
- id
number
(required) Example: 12345The ID of the answer.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 12,
"dateCreated": "2015-06-25T14:28:57-04:00",
"reviewedDate": null,
"text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
"textLength": 65,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 1,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 18,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Brimmer",
"emailAddress": null,
"externalId": "12345",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 0,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "waffles"
},
{
"id": 1
}
]
},
"tags": []
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No answer was found for the specified id (145454)",
"code": 132
}
]
}
Flag Answer ¶
Flag AnswerPOST/v1/answers/{id}/flag
Flag an answer as inappropriate.
Example URI
- id
number
(required) Example: 12345The ID of the answer.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 12,
"dateCreated": "2015-06-25T14:28:57-04:00",
"reviewedDate": null,
"text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
"textLength": 65,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": true,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 1,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 18,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Brimmer",
"emailAddress": null,
"externalId": "12345",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 0,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "waffles"
},
{
"id": 1
}
]
},
"tags": []
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No answer was found for the specified id (145454)",
"code": 132
}
]
}
Thank Answerer ¶
Thank AnswererPOST/v1/answers/{id}/thank
Sends a thank you email to the user who created the answer.
Example URI
- id
number
(required) Example: 12345The ID of the answer.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 12,
"dateCreated": "2015-06-25T14:28:57-04:00",
"reviewedDate": null,
"text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
"textLength": 65,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 1,
"thanked": true,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 18,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Brimmer",
"emailAddress": null,
"externalId": "12345",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 0,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "waffles"
},
{
"id": 1
}
]
},
"tags": []
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No answer was found for the specified id (145454)",
"code": 132
}
]
}
Replies ¶
A reply is a UGC type that’s tied to an answer or a previous reply to an answer. A reply can contain nested replies.
Resource Properties - Reply
Property | Type | Description |
---|---|---|
id | number | TurnTo unique ID for this reply |
dateCreated | date | Date that reply was created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
reviewedDate | date | Date that reply was reviewed by moderator (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
text | string | Reply text |
locale | string | Locale of reply |
published | boolean | Is published? |
csFlag | boolean | Is flagged for customer service? |
reviewedFlag | boolean | Is reviewed? |
autoModerated | boolean | Is auto moderated? |
isStaff | boolean | Is staff? |
user | resource | The user that posted this reply. Nested user block - see Users section |
userIpAddr | string | The IP address of the UGC author |
Answer Replies ¶
Answer RepliesGET/v1/answers/{id}/replies{?publishedOnly,locale,limit,offset,sort}
This endpoint will return a list of replies for an answer.
Options are available to filter results by published status.
Pagination and sorting of results is supported.
Example URI
- id
number
(required) Example: 12345The ID of the answer.
- publishedOnly
boolean
(optional) Default: true Example: trueIf true, only return published replies.
Choices:
true
false
- locale
string
(optional) Example: en_USOnly return replies for this locale.
- limit
number
(optional) Default: 50 Example: 50Maximum number of replies to show.
- offset
number
(optional) Default: 0 Example: 20Offset into replies results. Zero based so first result is offset = 0.
- sort
string
(optional) Default: dateCreated:desc Example: textLength:descField to sort replies by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
dateCreated
text
textLength
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"replies": [
{
"id": 2,
"text": "Thank you for the advise and I will check them out. Thank you again.",
"locale": "en_US",
"published": false,
"dateCreated": "2011-09-23T13:09:26-04:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": null,
"externalId": null
}
}
],
"offset": null,
"limit": null,
"total": 1
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No answer was found for the specified id (49439)",
"code": 132
}
]
}
Reply Detail ¶
Reply DetailGET/v1/replies/{id}
This endpoint will return a single reply.
The required reply is identified by its ID.
Example URI
- id
number
(required) Example: 12345The ID of the reply.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 12345,
"text": "Thank you!",
"locale": "en_US",
"published": false,
"dateCreated": "2013-09-20T09:14:29-04:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"parentReplyId": null,
"parentAnswerId": 3,
"user": {
"nickName": "Eric E.",
"firstName": "Eric",
"lastName": "Ericsson",
"emailAddress": "e@e.com",
"externalId": null
},
"replies": []
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No reply was found for the specified id (949494949949)",
"code": 133
}
]
}
Create Reply ¶
Create ReplyPOST/v1/answers/{id}/replies
Creates a new reply for an existing answer or reply.
A user credential is required to create an reply. For an existing user, the user will be identified either by email address or a unique external ID. If the reply is being created by a new user then the user first and last name must be supplied.
Request body JSON object properties
The properties that are passed during Reply creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
text | Yes | |
locale | No | If omitted use site default. |
parentReplyId | No | Provide parentReplyId if this reply is to an earlier reply. |
user.firstName | Yes | |
user.lastName | Yes | |
user.nickName | No | |
user.emailAddress | No | Either email address or externalId is required to identify the user |
user.externalId | No | Either email address or externalId is required to identify the user |
user.city | No | |
user.state | No | |
user.country | No | |
user.ageRange | No | |
user.shopperProfiles[].id | No | |
user.shopperProfiles[].value | No | |
userIpAddr | No | The IP address of the UGC author |
Example URI
- id
number
(required) Example: 12345The ID of the reply.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"text": "Thank you so much!",
"locale": "en_US",
"parentReplyId": null,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com"
},
"userIpAddr": "123.456.789.100"
}
201
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/replies/{id}
Body
{
"id": 3,
"text": "Thank you so much!",
"locale": "en_US",
"published": true,
"dateCreated": "2015-04-09T14:18:07-04:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"parentReplyId": null,
"parentAnswerId": 1,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null
},
"replies": []
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No answer was found for the specified id (49439)",
"code": 132
}
]
}
Comments ¶
A Comment, also known as a Checkout Comment, is a UGC type that’s tied to a catalog item, which is identified by a SKU in your catalog.
Resource Properties - Comments
Property | Type | Description |
---|---|---|
id | number | TurnTo unique ID for this comment |
dateCreated | date | Date comment created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
text | string | Comment text |
textLength | number | Number of characters in comment text |
locale | string | Locale of comment |
published | boolean | Is published? |
tags | string | List of tag codes associated with this comment |
user | resource | The user that posted this comment. Nested user block - see Users section |
userIpAddr | string | The IP address of the UGC author |
orderId | string | Unique Id of order associated with this comment |
catalogItem | resource | Product for which this comment was posted. Nested products block - see Products section |
Comment Detail ¶
Comment DetailGET/v1/comments/{id}
This endpoint will return a single Comment.
The required comment is identified by its ID.
Example URI
- id
number
(required) Example: 12345The ID of the Comment.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 8,
"text": "This Master Chef has loads of power and more speeds than you will ever need!",
"locale": "en_US",
"textLength": 76,
"published": true,
"dateCreated": "2015-07-01T09:49:43-04:00",
"catalogItem": {
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef"
},
"orderId": "5555522",
"user": {
"nickName": "Andy A.",
"firstName": "Andy",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Miami",
"state": "FL",
"country": "US",
"ageRange": 1
},
"tags": []
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No comment was found for the specified id (12292929)",
"code": 123
}
]
}
Create Comment ¶
Create CommentPOST/v1/comments
Creates a new Comment for a catalog item. An authorization token is required to create a Comment. A Comment is created by posting a JSON object in the body of the request.
A nested user object describes the author of the Comment. A user will be identified either by email address or a unique external ID that is maintained in your system. A nested catalogItem object describes the item that is the subject of the Comment.
The comment may optionally be associated with an order previously created on TurnTo system by supplying its order Id.
Request body JSON object properties
The properties that are passed during Comment creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
text | Yes | |
locale | No | If omitted use site default. |
user.firstName | Yes | |
user.lastName | Yes | |
user.nickName | No | |
user.emailAddress | No | Either email address or externalId is required to identify the user |
user.externalId | No | Either email address or externalId is required to identify the user |
user.city | No | |
user.state | No | |
user.country | No | |
user.ageRange | No | |
user.shopperProfiles[].id | No | |
user.shopperProfiles[].value | No | |
userIpAddr | No | The IP address of the UGC author |
orderId | No | The Id of an order that this comment is associated with. The order must already exist at TurnTo |
catalogItem.sku | Yes | The SKU of the catalog item that this comment is about. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created. |
catalogItem.title | No | The title of the catalog item that this comment is about. This can be omitted if the item already exists in your site’s catalog at TurnTo |
catalogItem.url | No | The URL of the catalog item that this comment is about. This can be omitted if the item already exists in your site’s catalog at TurnTo |
Example URI
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"text": "This Master Chef has loads of power and more speeds than you will ever need!",
"locale": "en_US",
"catalogItem": {
"sku": "11112222"
},
"orderId": "5555522",
"user": {
"nickName": "",
"firstName": "Andy",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"city": "Miami",
"state": "FL",
"country": "US",
"ageRange": 1
},
"userIpAddr": "123.456.789.100"
}
201
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/comments/{id}
Body
{
"id": 8,
"text": "This Master Chef has loads of power and more speeds than you will ever need!",
"textLength": 76,
"locale": "en_US",
"published": true,
"dateCreated": "2015-07-01T09:49:43-04:00",
"catalogItem": {
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef"
},
"orderId": "5555522",
"user": {
"nickName": "",
"firstName": "Andy",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Miami",
"state": "FL",
"country": "US",
"ageRange": 1
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Missing or invalid parameters sku",
"code": 114
}
]
}
Reviews ¶
A review is a UGC type representing a user review for a product and is identified by a unique identifier.
Resource Properties - Review
Property | Type | Description |
---|---|---|
id | number | TurnTo unique ID for this review |
dateCreated | date | Date that review was created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
reviewedDate | date | Date that review was reviewed by moderator (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
title | string | Review title |
text | string | Review text |
textLength | number | Number of characters in review text |
locale | string | Locale of review |
rating | number | Product rating (1,2,3,4, or 5) |
published | boolean | Is published? |
csFlag | boolean | Is flagged for customer service? |
inappropriateFlag | boolean | Is inappropriate? |
reviewedFlag | boolean | Is reviewed? |
autoModerated | boolean | Is auto moderated? |
incentivized | boolean | Did reviewer receive incentive? |
upVotes | number | Number of up votes received |
downVotes | number | Number of down votes received |
orderId | string | The order Id that is associated with the review |
purchaseDate | date | Date product purchased (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
tags | string | List of tag codes associated with this review |
user | resource | The user that posted this review. Nested user block - see Users section |
userIpAddr | string | The IP address of the UGC author |
catalogItems | resource | Product(s) for which this review is applicable. Nested products block - see Products section |
dimensions | resource | Custom dimension properties that can be captured for this product. Nested dimensions block - see Products section |
media | resource | Published media associated with this review. Nested media block - see Media section |
responses[].text | string | Response text |
responses[].locale | string | Locale of response |
responses[].user | resource | The user that posted this response. Nested user block - see Users section |
responses[].dateCreated | date | Date response created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
syndication.sourceName | string | Syndication source name |
syndication.siteUrl | string | Syndication source site URL |
syndication.logoUrl | string | Syndication source logo URL |
Review List ¶
Review ListGET/v1/reviews{?sku,related,includeRelated,includeRatingOnlyReviews,publishedOnly,tags,locale,dateCreatedFrom,dateCreatedTo,limit,offset,sort}
This endpoint can be used to return a list of reviews associated with a catalog item. The catalog item is identified by the ‘sku’ parameter.
Options are available to return direct reviews, related reviews, or a combined list containing both. Direct reviews are reviews that were created for a catalog item. Related reviews are reviews that are related to a catalog item, either as Virtual Parent Siblings, or as bundle parents.
To return reviews created within a specified time period the ‘dateCreatedFrom’ and ‘dateCreatedTo’ parameters should be used.
Any published media content associated with a review will be embedded with the review.
Options are available to filter results by published status, tag code, and locale. Pagination of results is supported via the ‘limit’ and ‘offset’ parameters.
Example URI
- sku
string
(required) Example: 12345The SKU of the topic catalog item that the returned reviews are about.
- related
boolean
(optional) Default: false Example: falseIf true, the reviews that are returned will be ones that are related to the SKU, either as Virtual Parent Siblings, or as bundle parents.
Choices:
true
false
- includeRelated
boolean
(optional) Default: false Example: falseIf true, the reviews returned will be a combined list of direct and related reviews for the SKU.
Choices:
true
false
- includeRatingOnlyReviews
boolean
(optional) Default: true Example: trueIf includeRatingOnlyReviews is false, rating only reviews (those without title and text) will be excluded from results.
Choices:
true
false
- publishedOnly
boolean
(optional) Default: true Example: trueIf true, only return published reviews.
Choices:
true
false
- tags
string
(optional) Example: CSR,DAM,SOTIf specified, only return reviews that contain at least 1 of the comma separated tag codes.
- locale
string
(optional) Example: en_USOnly return reviews for this locale. If omitted use site default.
- dateCreatedFrom
date
(optional) Example: 2015-09-14T00:00:00-04:00Only return reviews created on or after this date.
- dateCreatedTo
date
(optional) Example: 2015-09-14T23:59:59-04:00Only return reviews created on or before this date.
- limit
number
(optional) Default: 50 Example: 50Maximum number of reviews to show.
- offset
number
(optional) Default: 0 Example: 10Offset into reviews results. Zero based so first result is offset = 0.
- sort
string
(optional) Default: dateCreated:desc Example: textLength:descField to sort reviews by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
dateCreated
rating
textLength
upVotes
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"reviews": [
{
"id": 7,
"locale": "en_US",
"rating": 2,
"title": "An awesome jacket!",
"text": "This dinner jacket fits perfects and looks absolutely amazing.",
"textLength": 62,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": true,
"autoModerated": false,
"published": true,
"incentivized": false,
"upVotes": 0,
"downVotes": 0,
"orderId": null,
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"value": 4
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Fit",
"value": 7,
"label": [
"Spot on"
]
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Occasion",
"label": [
"Formal"
]
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"label": [
"Stylish",
"Modern"
]
}
],
"responses": [
{
"text": "Thank you for your review.",
"locale": "en_US",
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "spike@dog.org",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null,
"shopperProfiles": []
},
"dateCreated": "2018-08-31T15:33:11-04:00"
}
],
"tags": [
"CSR",
"INA"
],
"media": {
"photo": [
{
"id": 13,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": true,
"dateCreated": "2018-08-31T15:27:03-04:00",
"normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/06BF7F7E4FE46518D9486D6A67B95D76_1535743622388_1_L1000.jpeg",
"thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/06BF7F7E4FE46518D9486D6A67B95D76_1535743622388_1_PZ320.jpeg",
"originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/06BF7F7E4FE46518D9486D6A67B95D76_1535743622388_1.jpeg",
"tags": []
}
],
"video": [
{
"id": 14,
"type": "video",
"caption": "build customer community",
"provider": "youtube",
"providedLink": "https://www.youtube.com/watch?v=Vr_r2uBg56g",
"thumbnailUrl": "https://i.ytimg.com/vi/Vr_r2uBg56g/hqdefault.jpg",
"thumbnailWidth": 480,
"thumbnailHeight": 360,
"width": 480,
"height": 270,
"authorName": "TurnTo",
"authorUrl": "https://www.youtube.com/user/TurnToNetworks",
"providerId": "Vr_r2uBg56g",
"html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/Vr_r2uBg56g?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen></iframe>",
"s88thumbDims": {
"width": 117,
"height": 88,
"scaledTo": "h",
"targetLeft": -15,
"targetTop": 0
},
"s64thumbDims": {
"width": 85,
"height": 64,
"scaledTo": "h",
"targetLeft": -11,
"targetTop": 0
},
"locale": "en_US",
"published": true,
"dateCreated": "2018-08-31T15:27:03-04:00",
"tags": []
}
],
"audio": []
},
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.90506@mymail.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 3
}
]
},
"syndication": null,
"reviewedDate": "2018-08-31T15:32:30-04:00",
"purchaseDate": null,
"dateCreated": "2018-08-31T15:27:03-04:00",
"acceptedTermsAndConditions": true,
"catalogItems": [
{
"sku": "1234567",
"title": "Dinner Jacket",
"url": "www.sample.com/products/Dinner Jacket",
"category": null,
"reviewCount": 1,
"ratingCount": 1,
"averageRating": 2,
"ratingBreakdown": {
"1": 0,
"2": 1,
"3": 0,
"4": 0,
"5": 0
}
}
]
}
],
"offset": 0,
"limit": 50,
"total": 1
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Missing or invalid parameters sku",
"code": 114
}
]
}
Review Detail ¶
Review DetailGET/v1/reviews/{id}
This endpoint will return details of a single review. The required review is identified by its ID.
Any published media content associated with this review will be embedded in the response.
Example URI
- id
number
(required) Example: 12345The ID of the review.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 14,
"rating": 4,
"title": "These are terrific!",
"text": "These are the best widgets ever. Really amazing quality.",
"textLength": 57,
"locale": "en_US",
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": false,
"published": false,
"incentivized": false,
"upVotes": 0,
"downVotes": 0,
"orderId": "NY4003977783",
"catalogItems": [
{
"sku": "700285064826",
"title": "Oakley XX Frame Accessory Kit - Black",
"url": "http://www.testtt.info/tt4_2/responsivesite/qaOverlay-reviewsEmbed.php?sku=700285064826",
"category": null,
"reviewCount": 7,
"averageRating": 4.86,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 6
}
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"value": 1
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Comfort",
"value": 8,
"label": "High"
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Weight",
"label": "Light"
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"label": [
"Stylish"
]
}
],
"media": {
"photo": [
{
"id": 1,
"type": "photo",
"caption": "Desperate product!",
"imageType": "jpeg",
"width": 168,
"height": 168,
"normalUrl": "http://www.turnto.com/imagestore/item/sss-sss/4E21E538722E99F7A34E798084EE4FCC_1454360415690_1.png",
"locale": "en_US",
"published": true,
"dateCreated": "2016-02-01T16:00:16-05:00",
"tags": []
}
],
"video": [
{
"id": 2,
"type": "video",
"caption": "crazy video",
"provider": "youtube",
"providedLink": "https://www.youtube.com/watch?v=jS3ZxOtTD5A",
"thumbnailUrl": "https://i.ytimg.com/vi/jS3ZxOtTD5A/hqdefault.jpg",
"thumbnailWidth": 480,
"thumbnailHeight": 360,
"width": 480,
"height": 270,
"authorName": "HowToBasic",
"authorUrl": "https://www.youtube.com/user/HowToBasic",
"providerId": "jS3ZxOtTD5A",
"html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/jS3ZxOtTD5A?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allowfullscreen></iframe>",
"s88thumbDims": {
"width": 117,
"height": 88,
"scaledTo": "h",
"targetLeft": -15,
"targetTop": 0
},
"s64thumbDims": {
"width": 85,
"height": 64,
"scaledTo": "h",
"targetLeft": -11,
"targetTop": 0
},
"locale": "en_US",
"published": true,
"dateCreated": "2016-02-01T16:00:17-05:00",
"tags": [
"SAF",
"IPR"
]
}
],
"audio": []
},
"responses": [],
"reviewedDate": null,
"purchaseDate": null,
"tags": [
"SOT",
"ALU"
],
"dateCreated": "2015-09-28T15:30:46-04:00",
"user": {
"nickName": "Bart S.",
"firstName": "Bart",
"lastName": "Simpson",
"emailAddress": "bart@simpson.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 1
}
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No review was found for the specified id (949494949949)",
"code": 139
}
]
}
Create Review ¶
Create ReviewPOST/v1/reviews
Creates a new review. Currently a review can only be associated with a single catalog item.
Site settings can be used to configure whether the review title and review text are required properties. For sites that allow Ratings-only Reviews both the review title and review text are configured as optional properties. The review title may not exceed 1000 characters. If the review title is supplied then review text is also required. If review text is supplied it must not be shorter than the site defined minimum (the default is 50 characters) or longer than 5000 characters.
A user credential is required to create a review. For an existing user, the user will be identified either by email address or a unique external ID. If the review is being created by a new user then the user first and last name must be supplied.
Media content can be associated with the review by providing either the IDs of existing media or details of new media content. Up to 5 media items may be supplied. Images are oriented based on their EXIF orientation data.
When using this endpoint to import reviews into TurnTo, an external Id can be supplied to allow the review to be uniquely identified. In the case where a review already exists for the supplied external Id then it will be updated. If an external Id is supplied then the date the review was created may also be supplied.
If the review is created in response to a review solicitation email, the embedded link to initiate the create review flow includes a parameter ‘turntoTrackingToken’ that contains encoded information about the email recipient. The token can be passed to the create review endpoint to allow the review to be associated with the review solicitation email it came from.
Request body JSON object properties
The properties that are passed during Review creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
externalId | No | The Id of the review on an external system. |
dateCreated | No | Date the review was created on an external system. |
title | No | Review title |
text | No | Review text |
locale | No | If omitted use site default. |
rating | Yes | Rating for this product (1,2,3,4, or 5) |
user.firstName | Yes | |
user.lastName | Yes | |
user.nickName | No | |
user.emailAddress | No | Either email address or externalId is required to identify the user |
user.externalId | No | Either email address or externalId is required to identify the user |
user.city | No | |
user.state | No | |
user.country | No | |
user.ageRange | No | |
user.shopperProfiles[].id | No | The Id of the shopper profile to be added |
user.shopperProfiles[].value | No | Value of free-form text for a shopper profile |
userIpAddr | No | The IP address of the UGC author |
catalogItems[].sku | Yes | The SKU of the catalog item that this review is about. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created. |
catalogItems[].title | No | The title of the catalog item for this SKU. This can be omitted if the item already exists in your site’s catalog at TurnTo |
catalogItems[].url | No | The URL of the catalog item for this SKU. This can be omitted if the item already exists in your site’s catalog at TurnTo |
dimensions[].value | No | Predefined dimension value |
media.ids | No | List of existing media Ids to be associated with the review |
media.photo[].caption | No | Caption for new photo associated with the review |
media.photo[].b64data | No | Base64 data for new photo associated with the review |
media.video[].caption | No | Caption for new video associated with the review |
media.video[].url | No | Link URL for new video associated with the review |
turntoTrackingToken | No | The tracking token included in the create review link. |
Example URI
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"externalId": "EXT10008",
"dateCreated": "2015-09-26T10:01:21-04:00",
"title": "These are terrific!",
"text": "These are the best widgets I ever used. Honest swear to god.",
"locale": null,
"rating": 4,
"catalogItems": [
{
"sku": "11112222"
}
],
"dimensions": [
{
"value": 1
},
{
"value": 8
},
{
"value": 10
},
{
"value": 13
}
],
"media": {
"ids": [
1,
2
],
"photo": [],
"video": [
{
"caption": "crazy video",
"url": "https://www.youtube.com/watch?v=jS3ZxOtTD5A"
}
]
},
"user": {
"nickName": "Bart S.",
"firstName": "Bart",
"lastName": "Simpson",
"emailAddress": "bart@simpson.com",
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 1,
"shopperProfiles": [
{
"id": 2
}
]
},
"userIpAddr": "123.456.789.100",
"turntoTrackingToken": "eyJ0cmFuc0lkIjoxLCJ0dXJudG9FbWFpbFR5cGUiOiJyZXZpZXdTb2xpY2l0YXRpb24iLCJ0dXJudG9za3UiOiI1NjY0NTQyNTMzNCJ9"
}
201
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/reviews/{id}
Body
{
"id": 27,
"rating": 4,
"title": "These are terrific!",
"text": "These are the best widgets I ever used. Honest swear to god.",
"textLength": 60,
"locale": "en_US",
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": false,
"published": false,
"incentivized": false,
"upVotes": 0,
"downVotes": 0,
"orderId": null,
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"category": "processors",
"reviewCount": 0,
"averageRating": 0,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
}
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"value": 1
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Comfort",
"value": 8,
"label": "High"
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Weight",
"label": "Light"
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"label": [
"Stylish"
]
}
],
"media": {
"photo": [],
"video": [],
"audio": []
},
"responses": [],
"reviewedDate": null,
"purchaseDate": null,
"dateCreated": "2015-09-26T10:01:21-04:00",
"user": {
"nickName": "Bart S.",
"firstName": "Bart",
"lastName": "Simpson",
"emailAddress": "bart@simpson.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 1,
"shopperProfiles": [
{
"id": 2
}
]
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Review must be at least 50 characters.",
"code": 142
}
]
}
Review Vote Up ¶
Review Vote UpPOST/v1/reviews/{id}/voteup
Registers an up vote for a review.
Example URI
- id
number
(required) Example: 12345The ID of the review.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 27,
"rating": 4,
"title": "These are terrific!",
"text": "These are the best widgets I ever used. Honest swear to god.",
"textLength": 60,
"locale": "en_US",
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": false,
"published": false,
"incentivized": false,
"upVotes": 1,
"downVotes": 0,
"orderId": null,
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"category": "processors",
"reviewCount": 0,
"averageRating": 0,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
}
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"value": 1
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Comfort",
"value": 8,
"label": "High"
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Weight",
"label": "Light"
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"label": [
"Stylish"
]
}
],
"responses": [],
"reviewedDate": null,
"purchaseDate": null,
"dateCreated": "2015-09-26T10:01:21-04:00",
"tags": [],
"user": {
"nickName": "Bart S.",
"firstName": "Bart",
"lastName": "Simpson",
"emailAddress": "bart@simpson.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 1,
"shopperProfiles": [
{
"id": 2
}
]
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No review was found for the specified id (756768685)",
"code": 139
}
]
}
Review Vote Down ¶
Review Vote DownPOST/v1/reviews/{id}/votedown
Registers a down vote for a review.
Example URI
- id
number
(required) Example: 12345The ID of the review.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 27,
"rating": 4,
"title": "These are terrific!",
"text": "These are the best widgets I ever used. Honest swear to god.",
"textLength": 60,
"locale": "en_US",
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": false,
"published": false,
"incentivized": false,
"upVotes": 1,
"downVotes": 1,
"orderId": null,
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"category": "processors",
"reviewCount": 0,
"averageRating": 0,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
}
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"value": 1
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Comfort",
"value": 8,
"label": "High"
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Weight",
"label": "Light"
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"label": [
"Stylish"
]
}
],
"responses": [],
"reviewedDate": null,
"purchaseDate": null,
"dateCreated": "2015-09-26T10:01:21-04:00",
"tags": [],
"user": {
"nickName": "Bart S.",
"firstName": "Bart",
"lastName": "Simpson",
"emailAddress": "bart@simpson.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 1,
"shopperProfiles": [
{
"id": 2
}
]
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No review was found for the specified id (756768685)",
"code": 139
}
]
}
Flag Review ¶
Flag ReviewPOST/v1/reviews/{id}/flag
Flag a review as inappropriate.
Example URI
- id
number
(required) Example: 12345The ID of the review.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 27,
"rating": 4,
"title": "These are terrific!",
"text": "These are the best widgets I ever used. Honest swear to god.",
"textLength": 60,
"locale": "en_US",
"csFlag": false,
"inappropriateFlag": true,
"reviewedFlag": false,
"autoModerated": false,
"published": false,
"incentivized": false,
"upVotes": 1,
"downVotes": 1,
"orderId": null,
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"category": "processors",
"reviewCount": 0,
"averageRating": 0,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
}
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"value": 1
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Comfort",
"value": 8,
"label": "High"
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Weight",
"label": "Light"
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"label": [
"Stylish"
]
}
],
"responses": [],
"reviewedDate": null,
"purchaseDate": null,
"dateCreated": "2015-09-26T10:01:21-04:00",
"tags": [],
"user": {
"nickName": "Bart S.",
"firstName": "Bart",
"lastName": "Simpson",
"emailAddress": "bart@simpson.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 1,
"shopperProfiles": [
{
"id": 2
}
]
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No review was found for the specified id (145454)",
"code": 139
}
]
}
Review Responses ¶
The Review Response endpoints allow authorized users to create responses to reviews.
The user associated with the request must have a moderator, site expert, or brand expert permission.
Resource Properties - Review Response
Property | Type | Description |
---|---|---|
id | number | TurnTo unique ID for this review response |
reviewId | number | TurnTo unique ID of the review |
text | string | Review response text |
locale | string | Locale of review response |
user | resource | The user that posted this review response. Nested user block - see Users section |
dateCreated | date | Date that review response was created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
Create Review Response ¶
Create Review ResponsePOST/v1/reviews/{reviewId}/responses
Creates a new review response. The response text may not exceed 1000 characters.
A user credential is required to create a review response. The user is identified by email address.
Request body JSON object properties
The properties that are passed during Review Response creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
text | Yes | Review response text |
emailToReviewer | No | Boolean. If true, e-mails the original reviewer. Defaults to true. |
publish | No | Boolean. If true, auto-moderates response content. If false, sets response content to hidden status. Defaults to true. |
locale | No | If omitted use site default |
user.emailAddress | Yes | Email address is required to identify the user |
Example URI
- reviewId
number
(required) Example: 12345The ID of the review response.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"text": "Thank you for your review. Glad you enjoyed it!",
"emailToReviewer": true,
"publish": false,
"locale": "en_US",
"user": {
"nickName": null,
"firstName": null,
"lastName": null,
"emailAddress": "aa.89812@mymail.com",
"city": null,
"state": null,
"country": null,
"ageRange": null
}
}
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 4321,
"reviewId": 12345,
"text": "Thank you for your review. Glad you enjoyed it!",
"locale": "en_US",
"dateCreated": "2019-10-16T10:49:08-05:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null,
"shopperProfiles": []
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Response text too long.",
"code": 207
}
]
}
Update Review Response ¶
Update Review ResponsePOST/v1/reviews/{reviewId}/responses/{id}
Updates an existing review response. The response text may not exceed 1000 characters.
A user credential is required to update a review response. The user is identified by email address.
Request body JSON object properties
The properties that are passed during Response Review update are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
text | Yes | Review response text |
emailToReviewer | No | Boolean. If true, e-mails the original reviewer. Defaults to true. |
publish | No | Boolean. If true, auto-moderates response content. If false, sets response content to hidden status. Defaults to true. |
locale | No | If omitted use site default |
user.emailAddress | Yes | Email address is required to identify the user |
Example URI
- reviewId
number
(required) Example: 12345The ID of the review.
- id
number
(required) Example: 4321The ID of the review response.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"text": "Thank you for your review. Glad you enjoyed it!",
"emailToReviewer": true,
"publish": false,
"locale": "en_US",
"user": {
"nickName": null,
"firstName": null,
"lastName": null,
"emailAddress": "aa.89812@mymail.com",
"city": null,
"state": null,
"country": null,
"ageRange": null
}
}
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 4321,
"reviewId": 12345,
"text": "Thank you for your review. Glad you enjoyed it!",
"locale": "en_US",
"dateCreated": "2019-10-16T10:49:08-05:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null,
"shopperProfiles": []
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Response text too long.",
"code": 207
}
]
}
Delete Review Response ¶
Delete Review ResponseDELETE/v1/reviews/{reviewId}/responses/{id}{?email}
Deletes an existing review response.
A user credential is required to delete a review response. The user will be identified by email address.
Example URI
- reviewId
number
(required) Example: 12345The ID of the review.
- id
number
(required) Example: 4321The ID of the review response.
string
(required) Example: andrew@sample.comThe user email address.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "User has no permission to perform this change.",
"code": 129
}
]
}
Seller Ratings ¶
A seller rating is a UGC type representing a user review for your site (rather than a product that your site sells). A seller rating is identified by a unique identifier.
Resource Properties - Seller Ratings
Property | Type | Description |
---|---|---|
id | number | TurnTo unique ID for this seller rating |
text | string | Seller rating text |
rating | number | Seller rating (1, 2, 3, 4, or 5) |
locale | string | Locale of seller rating |
user | resource | The user that posted this seller rating. Nested user block |
userIpAddr | string | The IP address of the UGC author |
userAgent | string | The browser/operating system of the UGC author |
Seller Ratings List ¶
Seller Ratings ListGET/v1/sellerratings{?publishedOnly,locale,rating,suppressUserPII,limit,offset,sort}
This endpoint can be used to return a list of seller ratings associated with your site.
Options are available to filter results by published status, locale, and rating value. Pagination of results is supported via the ‘limit’ and ‘offset’ parameters.
User Properties
Basic information about a user’s age and location appears in the nested ‘user’ block of each seller rating result.
Customer Defined Shopper Profiles
Customer defined shopper profile values captured for a user at the time a review is created appear in the nested ‘shopperProfiles’ block of each seller rating result.
Example URI
- publishedOnly
boolean
(optional) Default: true Example: trueIf true, only return published seller ratings.
Choices:
true
false
- locale
string
(optional) Example: en_USIf specified, only return seller ratings matching this locale.
- rating
number
(optional) Default: 1,2,3,4,5 Example: 4Filter by seller rating value. Enter a single number or a comma-delimited list of numbers.
- suppressUserPII
boolean
(optional) Default: false Example: falseIf true, all user fields are returned null.
Choices:
true
false
- limit
number
(optional) Default: 50 Example: 50Maximum number of seller ratings to show.
- offset
number
(optional) Default: 0 Example: 10Offset into results. Zero-based so first result is offset = 0.
- sort
string
(optional) Default: dateCreated:desc Example: rating:ascField to indicate sort for seller ratings. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
dateCreated:desc
dateCreated:asc
rating:desc
rating:asc
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"sellerratings": [
{
"id": 6,
"locale": "en_US",
"rating": 4,
"text": "This is a great company. Terrific customer service!",
"published": true,
"dateCreated": "2020-02-29T15:21:14-05:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": null,
"externalId": "aa4444",
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"shopperProfiles": []
}
},
{
"id": 7,
"locale": "en_US",
"rating": 2,
"text": "Lost my order and I never heard anything from them! Never again will I shop with this store.",
"published": true,
"dateCreated": "2020-02-29T15:21:14-05:00",
"user": {
"nickName": "WendyW",
"firstName": "Wendy",
"lastName": "Williams",
"emailAddress": null,
"externalId": "aa4445",
"city": "Muncie",
"state": "IN",
"country": "US",
"ageRange": 2,
"shopperProfiles": []
}
}
]
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Missing or invalid parameters user",
"code": 114
}
]
}
Create Seller Rating ¶
Create Seller RatingPOST/v1/sellerratings
Creates a new seller rating. By default, TurnTo accepts only one seller rating per user per order. The seller rating text must not be shorter than the site-defined minimum (default is 50 characters) or longer than 5000 characters.
A user credential is required to create a seller rating. For an existing user, the user will be identified either by email address or a unique external ID. If the seller rating is being created by a new user then the user first name and last name must be supplied.
turntoTrackingToken - if the seller rating is created in response to a solicitation email, the embedded link to initiate the create seller rating flow includes this parameter, which contains encoded information about the email recipient. The token can be passed to the create seller rating endpoint to associate the seller rating with the solicitation email it came from. If you do not include the turntoTrackingToken, you must include an orderExternalId.
The properties that are passed during seller rating creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object.)
Property | Required | Note |
---|---|---|
text | yes | Seller rating text |
locale | no | If omitted use site default. |
rating | yes | Rating for this seller rating (1, 2, 3, 4, or 5) |
orderExternalId | no | String representing the client’s order id. You must include either externalOrderId or turntoTrackingToken |
user.firstName | yes | |
user.lastName | yes | |
user.nickName | no | |
user.emailAddress | no | Either email address or externalId is required to identify the user |
user.externalId | no | Either email address or externalId is required to identify the user |
user.city | no | |
user.state | no | |
user.country | no | |
user.ageRange | no | |
user.shopperProfiles[].id | no | The ID of the shopper profile to be added |
user.shopperProfiles[].value | no | Value of free-form text for a shopper profile |
userIpAddr | no | The IP address of the UGC author |
userAgent | no | The browser/operating system of the UGC author |
turntoTrackingToken | no | The tracking token included in the create seller rating link. You must include either externalOrderId or turntoTrackingToken |
Example URI
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"text": "This is a great company. Terrific customer service!",
"rating": 5,
"locale": "en_US",
"orderExternalId": "M202268013",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": null,
"externalId": "aa4444",
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"shopperProfiles": []
},
"userIpAddr": "555.555.100.001",
"userAgent": "Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.11.10 (KHTML, like Gecko) Mobile/7B405",
"turntoTrackingToken": ""
}
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 12,
"text": "This is a great company. Terrific customer service!",
"rating": 5,
"locale": "en_US",
"published": true,
"dateCreated": "2020-02-29T15:21:14-05:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": null,
"externalId": "aa4444",
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"shopperProfiles": []
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Seller Rating must be at least 50 characters.",
"code": 142
}
]
}
Seller Ratings Summary ¶
The Seller Ratings summary is a collection of data points relating to the seller ratings associated with your site, including the number of seller ratings, the average seller rating, and the breakdown of the number of seller ratings for each rating value.
Resource Properties - Seller Ratings Summary
Property | Type | Description |
---|---|---|
ratingCount | number | Number of seller ratings for your site |
averageRating | number | Average seller rating for your site |
ratingBreakdown | map | Number of seller ratings received for your site broken down by rating value (1-5) |
Seller Ratings SummaryGET/v1.0/sellerratings/summary
This endpoint returns summary details for seller ratings associated with your site.
Example URI
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"ratingCount": 255,
"averageRating": 4.5,
"ratingBreakdown": {
"1": 11,
"2": 5,
"3": 3,
"4": 85,
"5": 153
}
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Seller Ratings not enabled.",
"code": 211
}
]
}
Articles ¶
An Article, also known as a Knowledgebase Article, is a piece of system managed website content. An article can be associated with one or more catalog items, which are identified by a SKU in your catalog. If no catalog item is specified then the article is considered generic.
Resource Properties - Articles
Property | Type | Description |
---|---|---|
id | number | Unique Id for this article |
externalId | string | External Id for this article |
dateCreated | date | Date article created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
title | string | Article title |
text | string | Article text |
locale | string | Locale of article |
published | boolean | Is published? |
expirationDate | date | Date this article expires (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
catalogItems | resource | Product(s) for which this article is applicable. Nested products block - see Products section |
brands | string | List of brands for which this article is related |
categories | string | List of categories for which this article is related |
searchTerms | string | List of search terms for which this article is related |
Article List ¶
Article ListGET/v1/articles{?sku,publishedOnly,locale,limit,offset,sort}
This endpoint is used to retrieve a list of articles. A list of SKUs can be supplied to obtain articles relating to specific products.
Options are available to filter results by published status and locale. Pagination of results is supported via the ‘limit’ and ‘offset’ parameters.
Example URI
- sku
string
(optional) Example: 12345Comma separated list of SKUs to return articles for. Maximum is 20. If omitted all articles are returned.
- publishedOnly
boolean
(optional) Default: true Example: trueIf true, only return published articles.
Choices:
true
false
- locale
string
(optional) Example: en_USOnly return articles for this locale.
- limit
number
(optional) Default: 50 Example: 50Maximum number of articles to show.
- offset
number
(optional) Default: 0 Example: 10Offset into articles results. Zero based so first result is offset = 0.
- sort
string
(optional) Default: dateCreated:desc Example: dateCreated:descField to sort articles by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
dateCreated
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"articles": [
{
"id": 6,
"externalId": "X333",
"title": "Amazing Gadget",
"text": "A new gadget to change your life.",
"locale": "en_US",
"published": true,
"expirationDate": null,
"dateCreated": "2015-08-21T14:26:07-04:00",
"brands": [],
"categories": [],
"searchTerms": [
"one",
"two"
],
"catalogItems": [
{
"sku": "2",
"title": "The Matrix",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
"category": "movies"
}
]
},
{
"id": 9,
"externalId": null,
"title": "Amazing New Toy",
"text": "A new toy to rock your world.",
"locale": "en_US",
"published": true,
"expirationDate": null,
"dateCreated": "2015-08-21T14:26:08-04:00",
"brands": [],
"categories": [],
"searchTerms": [],
"catalogItems": [
{
"sku": "1",
"title": "Die Hard 2",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
"category": "movies"
},
{
"sku": "2",
"title": "The Matrix",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
"category": "movies"
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
"category": "movies"
}
]
},
{
"id": 10,
"externalId": null,
"title": "Amazing New Colors",
"text": "A new color to rock your world.",
"locale": "en_US",
"published": true,
"expirationDate": null,
"dateCreated": "2015-08-21T14:26:08-04:00",
"brands": [],
"categories": [],
"searchTerms": [
"blue",
"green"
],
"catalogItems": [
{
"sku": "1",
"title": "Die Hard 2",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
"category": "movies"
}
]
}
],
"offset": null,
"limit": null,
"total": 3
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Missing or invalid parameters sku",
"code": 114
}
]
}
Article Detail ¶
Article DetailGET/v1/articles/{id}
This endpoint will return a single article identified by its ID.
Example URI
- id
number
(required) Example: 12345The ID of the article.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 5,
"externalId": "X222",
"title": "Amazing Gadget",
"text": "A new gadget to change your life.",
"locale": "en_US",
"published": true,
"expirationDate": null,
"dateCreated": "2015-08-21T14:26:07-04:00",
"brands": [],
"categories": [],
"searchTerms": [],
"catalogItems": [
{
"sku": "2",
"title": "The Matrix",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
"category": "movies"
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
"category": "movies"
},
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"category": "processors"
}
]
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No article was found for the specified id (12292929)",
"code": 154
}
]
}
Article Detail By External Id ¶
Article Detail By External IdGET/v1/articles{?externalId}
This endpoint will return a single article identified by its external ID.
Example URI
- externalId
string
(required) Example: X12345The external Id of the article.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 5,
"externalId": "X222",
"title": "Amazing Gadget",
"text": "A new gadget to change your life.",
"locale": "en_US",
"published": true,
"expirationDate": null,
"dateCreated": "2015-08-21T14:26:07-04:00",
"brands": [],
"categories": [],
"searchTerms": [],
"catalogItems": [
{
"sku": "2",
"title": "The Matrix",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
"category": "movies"
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
"category": "movies"
},
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"category": "processors"
}
]
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No article was found for the specified external Id (X0123)",
"code": 155
}
]
}
Update Article ¶
Update ArticlePOST/v1/articles
An authorization token is required to create or update an article. An article may be updated by including an existing Id or external system Id. The article is created/updated by posting a JSON object in the body of the request. A nested catalogItems block can be used to associate the article with one or more catalog items.
Request body JSON object properties
The properties that are passed to create or update an article are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)
Property | Required | Note |
---|---|---|
id | No | |
externalId | No | |
title | Yes | |
text | Yes | |
locale | No | If omitted use site default. |
published | Yes | True or false |
expirationDate | No | Expiration date |
catalogItems[].sku | No | The SKU of the catalog item(s) that this article is about. |
brands | No | |
categories | No | |
searchTerms | No |
Example URI
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
"id": null,
"externalId": "X0123",
"title": "Amazing Gadget",
"text": "A new gadget to change your life.",
"locale": "en_US",
"published": true,
"expirationDate": "2017-08-21T14:26:04-04:00",
"catalogItems": [
{
"sku": "1"
},
{
"sku": "2"
},
{
"sku": "3"
}
],
"brands": null,
"categories": null,
"searchTerms": null
}
201
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/articles/{id}
Body
{
"id": 36,
"externalId": "X0123",
"title": "Amazing Gadget",
"text": "A new gadget to change your life.",
"locale": "en_US",
"published": true,
"expirationDate": "2017-08-21T14:26:04-04:00",
"dateCreated": "2015-08-20T16:56:35-04:00",
"brands": [],
"categories": [],
"searchTerms": [],
"catalogItems": [
{
"sku": "1",
"title": "Die Hard 2",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
"category": "movies"
},
{
"sku": "2",
"title": "The Matrix",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
"category": "movies"
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
"category": "movies"
}
]
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Missing Required Fields (title)",
"code": 108
}
]
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No article was found for the specified id (398239892)",
"code": 154
}
]
}
Delete Article ¶
Delete ArticleDELETE/v1/articles/{id}
An authorization token is required to delete an article. The article is identified by its unique Id.
Example URI
- id
number
(required) Example: 1234The ID of the article.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 2,
"externalId": "X0123"
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No article was found for the specified id (2)",
"code": 154
}
]
}
Delete Article By External Id ¶
Delete Article By External IdDELETE/v1/articles{?externalId}
An authorization token is required to delete an article. The article is identified by its external ID.
Example URI
- externalId
string
(required) Example: X12345The external ID of the article.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"id": 2,
"externalId": "X0123"
}
404
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "No article was found for the specified external id (X222)",
"code": 154
}
]
}
Users ¶
A user is identified by an email address or in the case of user created from a third party application by user external ID.
User profile information such as location (city, state, and country) and age range may also be collected and stored.
Custom user profile information, referred to as shopper profiles, can be configured for a site. If so this information will also be collected and stored.
Resource Properties - User
Property | Type | Description |
---|---|---|
firstName | string | First name |
lastName | string | Last name |
nickName | string | Nick name |
externalId | string | External ID |
string | Email address | |
city | string | City |
state | string | State |
country | string | Country |
ageRange | number | Age range indicator |
badge.text | string | Badge text |
badge.imageUrl | string | URL of image to use for badge |
shopperProfiles[].id | number | Identifier for a shopper profile |
shopperProfiles[].value | string | Free-form text value |
Forget User ¶
Forget UserPOST/v1/users/forget{?email}
Use this endpoint to submit a request to remove personal data. Submit the shopper’s email address to add to the user data removal queue.
Example URI
string
(required) Example: sample@turnto.comThe email of the shopper.
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Invalid Email Address",
"code": 128
}
]
}
User UGC ¶
User UGCGET/v1/users{?email,userId,ugcType,questionsOnly,questionsAnsweredOnly,answersOnly,commentsOnly,reviewsOnly,includeNested,publishedOnly}
This endpoint can be used to return content created by an individual user. The user is identified using either email address or external ID.
UGC types include questions, questions answered, answers, comments, and reviews. Options are available to return specific UGC types. Populating the ‘ugcType’ parameter is the preferred method for selecting UGC types. The ‘questionsOnly’, ‘questionsAnsweredOnly’, ‘answersOnly’, ‘commentsOnly’, and ‘reviewsOnly’ parameters are deprecated and will be removed in a future release.
Nested content can be included in the returned results by using the ‘includeNested’ option. In the case of questions and questions answered, this means that any nested answers and replies will be included. In the case of answers, this means that any nested replies will be included. In the case of reviews, this means that any nested responses to reviews will be included.
By default only published content is returned. To obtain all content the ‘publishedOnly’ option can be set to false.
Example URI
string
(optional) Example: a@a.comThe user’s email address.
- userId
string
(optional) Example: 7654321The user’s external ID. This parameter is required if email address is blank.
- ugcType
string
(optional) Default: all Example: questionType of content to return. Multiple types can be specified using comma-separated values.
Choices:
question
question-answered
answer
review
comment
all
- questionsOnly
boolean
(optional) Default: false Example: falseIf true only return questions content.
Choices:
true
false
- questionsAnsweredOnly
boolean
(optional) Default: false Example: falseIf questionsAnsweredOnly is true only return questions answered content.
Choices:
true
false
- answersOnly
boolean
(optional) Default: false Example: falseIf true only return answers content.
Choices:
true
false
- commentsOnly
boolean
(optional) Default: false Example: falseIf true only return comments content.
Choices:
true
false
- reviewsOnly
boolean
(optional) Default: false Example: falseIf true only return reviews content.
Choices:
true
false
- includeNested
boolean
(optional) Default: false Example: falseOption to include nested content.
Choices:
true
false
- publishedOnly
boolean
(optional) Default: true Example: trueIf true, only return published content.
Choices:
true
false
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"user": {
"firstName": "Bill",
"lastName": "Mee",
"nickName": "Bill M.",
"externalId": null,
"email": "bm@sample.com",
"city": "Memphis",
"state": "TN",
"country": "US",
"ageRange": 2
},
"questions": [
{
"id": 7,
"dateCreated": "2016-11-15T10:37:48-05:00",
"approvedDate": null,
"text": "How many different attachments come with this food processor?",
"textLength": 61,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 2,
"answers": [
{
"id": 6,
"dateCreated": "2016-11-15T10:37:50-05:00",
"reviewedDate": null,
"text": "There are 5: fine, coarse, slicer, mixer, grater.",
"textLength": 49,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 2,
"replies": [
{
"id": 2,
"text": "Thank you so much!",
"locale": "en_US",
"published": false,
"dateCreated": "2016-11-15T10:37:51-05:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"parentReplyId": null,
"parentAnswerId": 6,
"user": {
"nickName": "Bill M.",
"firstName": "Bill",
"lastName": "Mee",
"emailAddress": "bm@sample.com",
"externalId": null,
"city": "Memphis",
"state": "TN",
"country": "US",
"ageRange": 2
},
"replies": [
{
"id": 3,
"text": "You're welcome.",
"locale": "en_US",
"published": false,
"dateCreated": "2016-11-15T10:37:51-05:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"parentReplyId": 2,
"parentAnswerId": 6,
"user": {
"nickName": "Mable L.",
"firstName": "Mable",
"lastName": "Leaf",
"emailAddress": "ml@sample.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null
},
"replies": [],
"replyCount": 0
}
],
"replyCount": 1
}
],
"user": {
"nickName": "Mable L.",
"firstName": "Mable",
"lastName": "Leaf",
"emailAddress": "ml@sample.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"bestAnswer": true,
"tags": []
},
{
"id": 5,
"dateCreated": "2016-11-15T10:37:49-05:00",
"reviewedDate": null,
"text": "There are no attachments!",
"textLength": 25,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 7,
"catalogItems": [],
"replyCount": 0,
"replies": [],
"user": {
"nickName": "Clint S.",
"firstName": "Clint",
"lastName": "Smith",
"emailAddress": "clint@sample.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null
},
"tags": []
}
],
"user": {
"nickName": "Bill M.",
"firstName": "Bill",
"lastName": "Mee",
"emailAddress": "bm@sample.com",
"externalId": null,
"city": "Memphis",
"state": "TN",
"country": "US",
"ageRange": 2
},
"catalogItems": [
{
"sku": "FP12653",
"title": "Blendomatic 5000",
"url": "http://www.homegadgetsandmore.com/blendomatic",
"category": null
}
],
"tags": []
}
],
"questionsAnswered": [
{
"id": 8,
"dateCreated": "2016-11-15T10:37:51-05:00",
"approvedDate": "2016-11-15T10:37:51-05:00",
"text": "You are you are?",
"textLength": 16,
"locale": "en_US",
"published": true,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": true,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 1,
"answers": [
{
"id": 7,
"dateCreated": "2016-11-15T10:37:52-05:00",
"reviewedDate": null,
"text": "Oh yes, this little guy is amazing!",
"textLength": 35,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 8,
"catalogItems": [],
"replyCount": 1,
"replies": [
{
"id": 4,
"text": "Good to know...",
"locale": "en_US",
"published": false,
"dateCreated": "2016-11-15T10:37:52-05:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"parentReplyId": null,
"parentAnswerId": 7,
"user": {
"nickName": "Sally L.",
"firstName": "Sally",
"lastName": "Lewis",
"emailAddress": "sl@sample.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null
},
"replies": [],
"replyCount": 0
}
],
"user": {
"nickName": "Bill M.",
"firstName": "Bill",
"lastName": "Mee",
"emailAddress": "bm@sample.com",
"externalId": null,
"city": "Memphis",
"state": "TN",
"country": "US",
"ageRange": 2,
"badge": null
},
"bestAnswer": true,
"tags": []
}
],
"user": {
"nickName": "Sally L.",
"firstName": "Sally",
"lastName": "Lewis",
"emailAddress": "sl@sample.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null
},
"catalogItems": [
{
"sku": "FP17268",
"title": "Melon Slicer",
"url": "http://www.homegadgetsandmore.com/melonslicer",
"category": null
}
],
"tags": []
}
],
"answers": [
{
"id": 7,
"dateCreated": "2016-11-15T10:37:52-05:00",
"reviewedDate": null,
"text": "Oh yes, this little guy is amazing!",
"textLength": 35,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 8,
"catalogItems": [],
"replyCount": 1,
"replies": [
{
"id": 4,
"text": "Good to know...",
"locale": "en_US",
"published": false,
"dateCreated": "2016-11-15T10:37:52-05:00",
"reviewedDate": null,
"csFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"isStaff": false,
"parentReplyId": null,
"parentAnswerId": 7,
"user": {
"nickName": "Sally L.",
"firstName": "Sally",
"lastName": "Lewis",
"emailAddress": "sl@sample.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null
},
"replies": [],
"replyCount": 0
}
],
"user": {
"nickName": "Bill M.",
"firstName": "Bill",
"lastName": "Mee",
"emailAddress": "bm@sample.com",
"externalId": null,
"city": "Memphis",
"state": "TN",
"country": "US",
"ageRange": 2,
"badge": null
},
"tags": []
}
],
"comments": [
{
"id": 5,
"text": "This Blendomatic should have all the features I am looking for.",
"textLength": 63,
"locale": "en_US",
"published": false,
"dateCreated": "2016-11-15T10:37:52-05:00",
"orderId": null,
"user": {
"nickName": "Bill M.",
"firstName": "Bill",
"lastName": "Mee",
"emailAddress": null,
"externalId": null,
"city": "Memphis",
"state": "TN",
"country": "US",
"ageRange": 2
},
"catalogItem": {
"sku": "FP12653",
"title": "Blendomatic 5000",
"url": "http://www.homegadgetsandmore.com/blendomatic",
"category": null
},
"tags": []
}
],
"reviews": [
{
"id": 7,
"rating": 4,
"title": "The best melon slicer bar none",
"text": "This melon slicer has changed my life. I never thought I would see the day when slicing a melon could be made so simple. The best ever!",
"textLength": 137,
"locale": "en_US",
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": false,
"published": false,
"incentivized": false,
"upVotes": 0,
"downVotes": 0,
"orderId": null,
"dimensions": [],
"media": {
"photo": [],
"video": [],
"audio": []
},
"responses": [],
"reviewedDate": null,
"purchaseDate": null,
"dateCreated": "2016-11-15T10:37:53-05:00",
"user": {
"nickName": "Bill M.",
"firstName": "Bill",
"lastName": "Mee",
"emailAddress": "bm@sample.com",
"externalId": null,
"city": "Memphis",
"state": "TN",
"country": "US",
"ageRange": 2
},
"catalogItems": [
{
"sku": "FP17268",
"title": "Melon Slicer",
"url": "http://www.homegadgetsandmore.com/melonslicer",
"category": null
}
],
"tags": []
}
]
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Invalid Email Address",
"code": 128
}
]
}
Search ¶
UGC Search ¶
UGC SearchGET/v1/search{?q,sku,ugcType,related,includeRelated,publishedOnly,minRating,maxRating,mostRecent,locale,tags,dateCreatedFrom,dateCreatedTo,limit,offset}
Perform a search for the specified search text across the content of one or more of the available UGC types. A list of SKUs can be supplied to restrict search to specific products. In the case of Articles, generic articles (that apply to all products) are always searched.
Options are available to return direct content, related content, or a combined list containing both. Direct content is content that was created for a catalog item. Related content is content that was related to a catalog item, either as Virtual Parent Siblings, or as bundle parents.
Search will return a JSON object with a nested “results” object that has a list of objects of the UGC types that were used in the “ugcType” parameter and whose content matches the search string “q”. The fields returned in the results for each UGC type are those described in the “Resource properties” section of this doc. (For example, a search result containing a question will have most of the properties described in the Questions section.
Nested UGC types will not be returned for question or answer resources. For example, if your search returns a question, there will not be a collection of nested answers included. Review resources, however, will contain any published media content associated with the review.
There is one additional property added in search results to each object called “ugcType” that will identify it as either a question, answer, comment, review, or article.
A filter is available to constrain by published status.
Filtering by tag codes is supported. Tag codes should be specified as a comma separated list. If tag codes are specified then a UGC result must be associated with at least one of those tag codes.
Results can be selected for a specific time period by supplying one or both of the ‘dateCreatedFrom’ and ‘dateCreatedTo’ parameters.
Pagination of results are supported via the ‘limit’ and ‘offset’ parameters.
Example URI
- q
string
(optional) Example: stewUTF-8, URL-encoded search string of no more than 500 characters.
- sku
string
(optional) Example: 12345,22222,33333Comma separated list of SKUs to return results for. Maximum is 20.
- ugcType
string
(required) Example: question,answerType of content to search for. Multiple types can be searched using comma-separated values.
Choices:
question
answer
review
comment
article
all
- related
boolean
(optional) Default: false Example: falseIf true, the content returned will be related to the SKU, either as Virtual Parent Siblings, or as bundle parents.
Choices:
true
false
- includeRelated
boolean
(optional) Default: false Example: falseIf true, the content returned will be a combined list of direct and related content for the SKU.
Choices:
true
false
- publishedOnly
boolean
(optional) Default: true Example: trueIf true, only return published results.
Choices:
true
false
- minRating
number
(optional) Example: 1Minimum rating of reviews to return.
- maxRating
number
(optional) Example: 4Maximum rating of reviews to return.
- mostRecent
boolean
(optional) Default: false Example: falseOrder results by most recent.
Choices:
true
false
- locale
string
(optional) Example: en_USOnly return results for this locale.
- tags
string
(optional) Example: CSR,DAMComma separated list of tag codes. Only return results associated with at least one tag code.
- dateCreatedFrom
date
(optional) Example: 2016-07-01T10:00:00-04:00Only include results that were created on or after this date (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ).
- dateCreatedTo
date
(optional) Example: 2016-07-02T10:00:00-04:00Only include results that were created on or before this date (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ).
- limit
number
(optional) Default: 20 Example: 20Maximum number of results to return. Maximum value is 100.
- offset
number
(optional) Default: 0 Example: 0Offset into results. Zero based so first result is offset = 0.
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"limit": 10,
"offset": 0,
"total": 45,
"results": [
{
"id": 18,
"dateCreated": "2015-07-20T15:06:46-04:00",
"approvedDate": null,
"text": "How many different attachments come with this food processor?",
"textLength": 61,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": true,
"answerCount": 1,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Rye",
"state": "NY",
"country": "US",
"ageRange": 2,
"shopperProfiles": [
{
"id": 4,
"value": "toast"
},
{
"id": 1
}
]
},
"ugcType": "question",
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef"
}
],
"tags": [
"PRI",
"ALU",
"NEW"
]
},
{
"id": 12,
"dateCreated": "2015-07-20T15:06:46-04:00",
"reviewedDate": null,
"text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
"textLength": 65,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 18,
"catalogItems": [],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Brimmer",
"emailAddress": null,
"externalId": "12345",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 0,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "waffles"
},
{
"id": 1
}
]
},
"ugcType": "answer",
"tags": []
},
{
"id": 11,
"dateCreated": "2015-07-20T15:06:41-04:00",
"reviewedDate": null,
"text": "My D600 with 24-85 mm lens with cap (3 3/4\" long) fits in the case. If the 24-120 is @ same length, t should fit snugly.",
"textLength": 120,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 1,
"thanked": false,
"isStaff": true,
"purchaseDate": null,
"itemQuestionId": 16,
"catalogItems": [],
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "spike@dog.org",
"externalId": null,
"city": "hell",
"state": "NE",
"country": "US",
"ageRange": null,
"badge": {
"text": "Staff",
"imageUrl": ""
}
},
"ugcType": "answer",
"tags": [
"CSR",
"FLF"
]
},
{
"id": 7,
"dateCreated": "2015-07-20T15:06:39-04:00",
"reviewedDate": null,
"text": "My D600 with 24-85 mm lens with cap (3 3/4\" long) fits in the case. If the 24-120 is @ same length, t should fit snugly.",
"textLength": 120,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 16,
"catalogItems": [
{
"sku": "1",
"title": "Die Hard 2",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1"
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3"
},
{
"sku": "5",
"title": "Other6",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=5"
},
{
"sku": "6",
"title": "Other7",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=6"
}
],
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Rye",
"state": "NY",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "toast"
},
{
"id": 1
}
]
},
"ugcType": "answer",
"tags": []
},
{
"id": 6,
"dateCreated": "2015-07-20T15:06:39-04:00",
"reviewedDate": null,
"text": "My D600 with 24-85 mm lens with cap (3 3/4\" long) fits in the case. If the 24-120 is @ same length, t should fit snugly.",
"textLength": 120,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 0,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 16,
"catalogItems": [
{
"sku": "1",
"title": "Die Hard 2",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1"
}
],
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Rye",
"state": "NY",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "toast"
},
{
"id": 1
}
]
},
"ugcType": "answer",
"tags": []
},
{
"id": 5,
"dateCreated": "2015-07-20T15:06:38-04:00",
"reviewedDate": null,
"text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
"textLength": 65,
"locale": "en_US",
"published": false,
"csFlag": false,
"inappropriateFlag": true,
"reviewedFlag": false,
"autoModerated": true,
"upVotes": 1,
"thanked": false,
"isStaff": false,
"purchaseDate": null,
"itemQuestionId": 16,
"catalogItems": [],
"user": {
"nickName": "Bob B.",
"firstName": "Bob",
"lastName": "Brimmer",
"emailAddress": null,
"externalId": "12345",
"city": "Dallas",
"state": "TX",
"country": "US",
"ageRange": 0,
"badge": null,
"shopperProfiles": [
{
"id": 4,
"value": "waffles"
},
{
"id": 1
}
]
},
"ugcType": "answer",
"tags": []
},
{
"id": 16,
"dateCreated": "2015-07-20T15:06:38-04:00",
"approvedDate": null,
"text": "How many different attachments come with this food processor?",
"textLength": 61,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": true,
"answerCount": 6,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Rye",
"state": "NY",
"country": "US",
"ageRange": 2,
"shopperProfiles": [
{
"id": 4,
"value": "toast"
},
{
"id": 1
}
]
},
"ugcType": "question",
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef"
}
],
"tags": []
},
{
"id": 12,
"dateCreated": "2015-07-20T15:06:21-04:00",
"approvedDate": null,
"text": "Can my D600+24-120mm F4 fit into this case? I read the official Nikon document which is saying 24-120mm F4 does not fit with D600, but I'm still thinking it might fit tightly. Anyone has, maybe, an experience?",
"textLength": 209,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": false,
"isCategoryQuestion": false,
"answerCount": 0,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Rye",
"state": "NY",
"country": "US",
"ageRange": 2,
"shopperProfiles": [
{
"id": 4,
"value": "toast"
},
{
"id": 1
}
]
},
"ugcType": "question",
"catalogItems": [
{
"sku": "340824 REG",
"title": "Greenies Smart Biscuit Fresh Chip 16 oz Regular",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=340824 REG"
}
],
"tags": []
},
{
"id": 15,
"dateCreated": "2015-07-20T15:06:22-04:00",
"approvedDate": null,
"text": "Can my D600+24-120mm F4 pics fit into this case? I read the official Nikon document which is saying 24-120mm F4 does not fit with D600, but I'm still thinking it might fit tightly. Anyone has, maybe, an experience?",
"textLength": 214,
"locale": "en_US",
"published": false,
"csFlag": false,
"irrelevantFlag": false,
"unansweredAlert": false,
"reviewedFlag": false,
"autoModerated": false,
"flagForExpert": false,
"upVotes": 0,
"isStaff": true,
"isCategoryQuestion": true,
"answerCount": 0,
"user": {
"nickName": "Andrew A.",
"firstName": "Andrew",
"lastName": "Adamson",
"emailAddress": "spike@dog.org",
"externalId": null,
"city": "hell",
"state": "NE",
"country": "US",
"ageRange": null
},
"ugcType": "question",
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef"
}
],
"tags": []
},
{
"ugcType": "review",
"id": 3,
"rating": 5,
"title": "These are awesome!",
"text": "These are really very good indeed. These are really very good indeed.",
"textLength": 69,
"locale": "en_US",
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": false,
"published": false,
"incentivized": false,
"upVotes": 0,
"downVotes": 0,
"orderId": null,
"dimensions": [],
"media": {
"photo": [],
"video": [],
"audio": []
},
"responses": [],
"reviewedDate": null,
"purchaseDate": null,
"dateCreated": "2016-05-17T12:41:28-04:00",
"user": {
"nickName": "Bart S.",
"firstName": "Bart",
"lastName": "Simpson",
"emailAddress": "bart2@simpson.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 1
},
"catalogItems": [
{
"sku": "REVIEWSKU555",
"title": "Vacuum Cleaner",
"url": "www.vacsrus.com/vac1",
"category": null
}
],
"tags": []
}
]
}
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"errors": [
{
"message": "Bad search filters",
"code": 131
}
]
}
Recent Updates ¶
This section contains details of recent updates to the API.
To receive updates by email, please visit our signup page http://www2.turntonetworks.com/dev-comm.
2/8/24 - Seller Ratings Summary endpoint
A new Seller Ratings Summary endpoint returns summary details for seller ratings associated with your site.
7/28/21 - Forget User endpoint
A new Forget User endpoint submits a request to remove shoppers’ personal data.
10/13/20 - Product List endpoint maximum number of SKUS updated
The Product List endpoint returns product information for up to 25 SKUs from a single request.
10/13/20 - TurnTo does not accept gif images
The image/gif MIME type is not considered valid. TurnTo does no longer accepts Media image submissions in gif format.
08/20/20 - UGC Summary endpoint maximum number of SKUS updated
The UGC Summary endpoint returns the UGC summary for up to 25 SKUs from a single request.
11/12/19 - Review responses endpoints added
New Review Responses endpoints have been added to allow clients to manage review responses.
11/12/19 - Review list rating only review option added
A new option (includeRatingOnlyReviews) has been added to the Review List endpoint to allow rating only reviews to be excluded from results.
01/14/19 - Create Order line item brand property added
The Create Order endpoint has been modified to allow a brand to be specified for each order line.
10/02/18 - UGC Search related content option added
Optional parameters (related) and (includeRelated) have been added to the UGC Search endpoint to allow direct and related content to be returned.
04/18/18 - Review list sort by upVotes
A new sort option (upVotes) has been added to the Review List endpoint to allow reviews to be sorted by number of upVotes.
09/27/17 - List direct and related reviews in single request
An optional parameter (includeRelated) has been added to the Review List endpoint to allow direct and related reviews to be returned in a combined list.
08/16/17 - UGC Summary by locale
An optional parameter (locale) has been added to the UGC Summary endpoint to allow dimensions to be localized to target site locale.
07/05/17 - Create Review title and text validation
The Create Review endpoint has been modified to include additional validation of review title and text properties so that rules regarding minimum and maximum number of characters is enforced.
01/04/17 - User UGC questions answered
The User UGC endpoint has been modified to allow questions answered by the user to be included in returned results.
01/04/17 - Capture email recipient information for answers and reviews
An optional property (turntoTrackingToken) has been added to the Create Answer and Create Review endpoints to allow information about email recipients to be captured.
10/26/16 - Thank Answerer endpoint added
The Thank Answerer endpoint has been added to support sending a thank you email to the user that created an answer.
09/14/16 - User UGC enhancement
The User UGC endpoint has been enhanced to include two new options. The ‘includeNested’ option allows nested content to be included in the returned results. The ‘publishedOnly’ option allows returned results to be limited to published content.
08/03/16 - Answer more questions
The Answer More Questions endpoint has been added to support an API implementation of the TurnTo widget Answer More Questions box.
08/03/16 - Collect IP for UGC authors
An optional property (userIpAddr) has been added to UGC creation endpoints to allow for the capture of the IP address for the UGC author.
The following endpoints have been updated Create Question, Create Answer, Create Reply, Create Comment, and Create Review.
08/03/16 - Search against creation date
The UGC Search endpoint has been enhanced to allow results to be filtered by creation date.
Results can be selected for a specific time period by supplying one or both of the ‘dateCreatedFrom’ and ‘dateCreatedTo’ parameters.
08/03/16 - Article List fix
The Article List endpoint has been modified to correct the behavior when paginating large result sets.
Previously, the use of the offset parameter to paginate large result sets did not return the expect results. This has been fixed.
06/29/16 - UGC flag indicators
The Questions UGC type has been modified to include the csFlag property. Also, the type of irrelevantFlag property has been changed to boolean to maintain consistency with other flag indicators.
The Reviews UGC type has been modified to change the csFlag and inappropriateFlag properties to boolean to maintain consistency with other flag indicators.
06/29/16 - Search by tag codes
The UGC Search endpoint has been enhanced to allow results to be filtered by tag codes.
05/25/16 - List and search publishedOnly option fix
The list and search endpoints have been modified to fix an issue in the behavior of the publishedOnly option. Previously, setting publishedOnly to false resulted in only unpublished content being returned.
This has been fixed so that setting publishedOnly to false results in both published and unpublished content being returned.
05/25/16 - Review catalog items fix
The UGC Search and User UGC endpoints have been modified to fix an inconsistency in the presentation of catalog items associated with reviews.
The catalogItem property is replaced by the catalogItems list property.
The catalogItem property in reviews block has been deprecated and will be removed in a future release.
05/25/16 - Review search results includes media content
The UGC Search endpoint has been modified to include associated published media content in review results.
05/25/16 - Review order Id property added
The orderId property has been added to review block to allow the order associated with a review to be identified.
05/25/16 - Review dimension properties added
The dimensionId property has been added to review dimension block to allow the dimension to be unambiguously identified.
Type 2 (range) dimensions now include the value property to uniquely identify range values.
05/25/16 - Content Tags added
Content Tags have been added to Media, Question, Answer, Comment, and Review UGC Types.
New options to filter content by tag codes added.
03/22/16 - Article List fix
The Article List endpoint has been modified to correct behavior when filtering by SKU.
Previously, the use of * as a wildcard allowed articles for all SKU’s to be returned. This behavior was inconsistent with other endpoints and caused confusion.
The use of * as wildcard has been deprecated and will be removed in a future release.
To obtain articles for all SKU’s the sku parameter should be left blank.
03/22/16 - Improved validation
Additional validation checks have been included to allow more meaningful responses to be returned.
Four new Response Codes 178 - 181 have been added.
02/17/16 - Media UGC type added
The Media UGC type has been added to allow media content to be created and associated with reviews.
Two new endpoints have been added: Save Media allows media content to be created for a user, User Media List allows media content to be retrieved for a user.
The Create Review endpoint has been enhanced to allow new and/or existing media to be included with a review.
Note: audio is not currently supported.
02/17/16 - Best Answer enhancement
The Question List, Question Detail, and Question Answers endpoints have been updated to return answer results sorted by best answer. The best answer for a question now contains a new property bestAnswer set to true.
02/17/16 - Create order documentation
The Create Order documentation has been corrected to indicate that property emailOptOut is not part of the user block.
01/07/16 - Associate order with comment enhancement
The Create Comment endpoint has been enhanced to allow an order to be associated with the comment.
An Order Id field has been added to the comment blocks returned by API endpoints.
11/04/15 - Response to Reviews enhancement
The TurnTo application has been enhanced to allow review moderators to post responses to reviews.
When using the API endpoints to retrieve reviews, any responses to reviews will be embedded in the reviews result set in a new property (responses).
10/07/15 - Review List enhancement
The Review List endpoint used to return reviews for a specified sku has been enhanced.
Two new parameters (dateCreatedFrom and dateCreatedTo) have been added to allow reviews to be constrained by their creation date.
A new sort option (rating) has been added to allow reviews to be sorted by the review product rating.
10/07/15 - Product List and UGC Summary fix
Under certain circumstances the dimensions blocks for the returned products were not fully populated. This has been fixed for the Product List and UGC Summary endpoints.
Additionally, the count field (count) in the dimensions block is now populated for dimension types 3 (Single Select) and 4 (Multi Select).
Comment List ¶
/v1/comments{?sku,publishedOnly,tags,locale,limit,offset,sort}
This endpoint will return a list of Comments for a catalog item.
Options are available to filter results by published status, tag code, and locale.
Pagination and sorting of results is supported.
Example URI
string
(required) Example: 12345The SKU of the topic catalog item that the returned comments are about.
boolean
(optional) Default: true Example: trueIf true, only return published comments.
Choices:
true
false
string
(optional) Example: CSR,DAM,SOTIf specified, only return comments that contain at least 1 of the comma separated tag codes.
string
(optional) Example: en_USOnly return comments for this locale. If omitted use site default.
number
(optional) Default: 50 Example: 50Maximum number of comments to show.
number
(optional) Default: 0 Example: 10Offset into comments results. Zero based so first result is offset = 0.
string
(optional) Default: dateCreated:desc Example: textLength:descField to sort comments by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
dateCreated
text
textLength
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200
Headers
Content-Type: application/json;charset=UTF-8
Body
{ "comments": [ { "id": 8, "text": "This is the best Master Chef ever!", "locale": "en_US", "textLength": 76, "published": true, "dateCreated": "2015-07-01T09:49:43-04:00", "catalogItem": { "sku": "11112222", "title": "MultiChef", "url": "www.topchef.com/food-processors/multichef" }, "orderId": "5555522", "user": { "nickName": "Andy A.", "firstName": "Andy", "lastName": "Adamson", "emailAddress": "andrew@sample.com", "externalId": null, "city": "Miami", "state": "FL", "country": "US", "ageRange": 1 }, "tags": [] }, { "id": 7, "text": "I love all the attachments!", "locale": "fr_CA", "textLength": 160, "published": true, "dateCreated": "2015-06-30T11:43:06-04:00", "catalogItem": { "sku": "11112222", "title": "MultiChef", "url": "www.topchef.com/food-processors/multichef" }, "orderId": null, "user": { "nickName": "Andy A.", "firstName": "Andy", "lastName": "Adamson", "emailAddress": "andrew@sample.com", "externalId": null, "city": "Miami", "state": "FL", "country": "US", "ageRange": 1 }, "tags": [ "CSR" ] }, { "id": 5, "text": "This Master Chef has loads of power and more speeds than you will ever need!", "locale": "en_US", "textLength": 76, "published": true, "dateCreated": "2015-06-30T11:43:05-04:00", "catalogItem": { "sku": "11112222", "title": "MultiChef", "url": "www.topchef.com/food-processors/multichef" }, "orderId": null, "user": { "nickName": "Andy A.", "firstName": "Andy", "lastName": "Adamson", "emailAddress": "andrew@sample.com", "externalId": null, "city": "Miami", "state": "FL", "country": "US", "ageRange": 1 }, "tags": [] } ], "offset": null, "limit": null, "total": 3 }
400
Headers
Content-Type: application/json;charset=UTF-8
Body
{ "errors": [ { "message": "Missing or invalid parameters sku", "code": 114 } ] }