TurnTo API v1.3
New Version Released
All endpoints for API v1.3 are now prefixed by /v1.3 rather than the previous /v1.2 prefix. The URL returned by create endpoints as a Location header likewise has a /v1.3 prefix.
A summary of updates is listed below:
Flag Media
This endpoint is used to flag media content. A reason for flagging the content must be selected. Media can be flagged as Intellectual Property Violation, Inappropriate, Spam, or Off-topic.
Active Product Indicator
Catalog item data now includes a new field ‘active’ that is used to indicate if the product is an active product in the catalog.
User-specified Identifiers for Subdimensions and Shopper Profile Attributes
Subdimensions and shopper profile attributes now include a new user-specified field ‘code’ that is used to identify a subdimension or shopper profile attribute. Codes maybe up to 5 characters, are not case sensitive, and must be unique for a site. Codes are a useful way to create matching identifiers for parallel subdimensions or shopper profile attributes across site instances.
Review Custom Data
Custom data can now be added to reviews through the Create Review endpoint. The customData property passes a JSON object with key-value pairs. All customData object values are treated as strings. All endpoints that return reviews will include customData when it is present.
Review Device Fingerprint
The ‘deviceFingerprint’ property captures a unique ID associated with a device, and can now be included when creating a review. A device fingerprint is required when syndicating reviews to Bazaarvoice.
Review Incentive Type and Campaign
Two optional parameters (incentiveType) and (campaign) have been added to the Create Review endpoint to identify the type of incentive or campaign a review is part of. The incentiveType cannot be identified when the incentivized parameter is false, but campaign can exist independently of incentiveType OR incentivized parameters.
Syndication attribution for Q&A
Questions, Answers, and Replies endpoints now include the optional resource properties to identify the syndication source name (syndication.sourceName) and web address (syndication.siteUrl).
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 primary API 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.
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.3/questions?sku=12345&related=false&publishedOnly=true&limit=10&offset=20A successful response is returned as a UTF-8 JSON representation with an HTTP response code of 200 (OK).
Content-Type: application/json;charset=UTF-8Create
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-8A 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.3/questions/{id}Update (Operation)
The HTTP POST method is used to perform certain operations (such as voteup).
Example:
https://api.turnto.com/v1.3/questions/12345/voteupA 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-8API 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 SKU 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 must be at least 50 characters | The review must be at least 50 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. | 404 |
| 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 |
| 215 | Invalid incentiveType. | Specified incentive was not found | 400 |
| 216 | Cannot specify incentiveType when incentivized is false. | The review is not recorded as incentivized | 400 |
| 217 | Media Content not enabled. | Media is not enabled for this site | 400 |
| 218 | Id parameter should be a number. | The id parameter includes at least one character that is not a number | 400 |
| 219 | Attempting to flag media with invalid reason. | Media can be flagged as Intellectual Property Violation, Inappropriate, Spam, or Off-topic. No other reasons are valid. | 400 |
| 220 | No media content was found for the specified id. | The media content was not found | 400 |
OAuth ¶
TurnTo uses the OAuth 2.0 Bearer token mechanism to secure most API requests. You can use the ‘/v1.3/oauth2/token’ endpoint to obtain the primary API access Bearer token using your site’s siteKey and authKey which you can copy from your site’s settings area at www.turnto.com.
The 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 R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaAs 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 primary API access token at a time and once generated a primary API access token does not expire.
Note: It is not necessary to obtain the token before each API call and doing so may harm performance.
Obtain Access Token ¶
Obtain Access TokenPOST/v1.3/oauth2/token
Use your site’s site key and auth key (obtainable from the site settings page on www.turnto.com) to request a primary API access token which can then be used to authorize subsequent requests to the API.
Note: Do not share or expose the primary API 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.3/oauth2/invalidate_token endpoint, or through your site’s settings page on www.turnto.com. Once generated, a primary API access token does not expire.
Example URI
POST https://api.turnto.com/v1.3/oauth2/token
URI Parameters
- 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’.
Request
Headers
Content-Type: application/x-www-form-urlencodedBody
client_id=[yourSiteKey]&client_secret=[yourAuthKey]&grant_type=client_credentialsResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"token_type": "bearer",
"access_token": "R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya"
}Response
403Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Invalid client_id or client_secret",
"code": 112
}
]
}Invalidate Access Token ¶
Invalidate Access TokenPOST/v1.3/oauth2/invalidate_token
Invalidates the token passed in the body of the request if this is the active primary API access token for your site.
Your site can only have one valid primary API access token at a time. Once the token is invalidated using this endpoint, any clients making API requests using your token will see authorization errors. Use this endpoint only if your primary API access token has been compromised, or you have a security policy that requires periodically renewing the token.
Example URI
POST https://api.turnto.com/v1.3/oauth2/invalidate_token
URI Parameters
- client_id
string(required) Example: aaa-aaaThe site key.
- client_secret
string(required) Example: bbb-bbbThe site secret.
- access_token
string(required)The primary API access token.
Request
Headers
Content-Type: application/x-www-form-urlencodedBody
client_id=[your_site_key]&client_secret=[your_auth_key]&access_token=[your_access_token]Response
200Headers
Content-Type: application/json;charset=UTF-8Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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 |
| values[].code | string | Customer defined code used to identify shopper profile value |
Site Settings ¶
The site settings contains information on how the site is configured.
Site SettingsGET/v1.3/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
GET https://api.turnto.com/v1.3/sites?locale=en_US
URI Parameters
- locale
string(optional) Example: en_USLabels will be returned in target locale. If omitted use site default.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
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,
"code": "LVL1"
},
{
"id": 2,
"label": "Sous Chef",
"hidden": false,
"sortOrder": 1,
"code": "LVL2"
},
{
"id": 3,
"label": "Line Chef",
"hidden": false,
"sortOrder": 2,
"code": "LVL3"
}
]
},
{
"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,
"code": "DISH"
}]
}]
}
}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 |
| active | boolean | Indicates if product is active |
| attributes | resource | Attributes 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[].code | string | Customer defined code used to identify 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 |
Resource Properties - Attributes
Attributes are individual items of information about a product such as size or color.
| Property | Type | Description |
|---|---|---|
| type | string | Attribute type |
| typeLabel | string | Display label for attribute type |
| values[].value | string | Attribute value |
| values[].valueLabel | string | Display label for attribute value |
Note: The use of product attributes is not enabled by default. Please contact TurnTo support to configure this option for your site.
Product List ¶
The product detail information describes the product.
Product ListGET/v1.3/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.
Example URI
GET https://api.turnto.com/v1.3/products?sku=12345,22222,33333&locale=en_US
URI Parameters
- 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.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
[
{
"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,
"code": "Q1",
"value": 1
},
{
"id": 2,
"code": "Q2",
"value": 2
},
{
"id": 3,
"code": "Q3",
"value": 3
},
{
"id": 4,
"code": "Q4",
"value": 4
},
{
"id": 5,
"code": "Q5",
"value": 5
}
]
},
{
"id": 2,
"label": "Comfort",
"type": 2,
"required": true,
"average": 2,
"values": [
{
"id": 6,
"code": "CLOW",
"sortOrder": 0,
"label": "Low"
},
{
"id": 7,
"code": "CMED",
"sortOrder": 1,
"label": "Medium"
},
{
"id": 8,
"code": "CHIGH",
"sortOrder": 2,
"label": "High"
}
]
},
{
"id": 3,
"label": "Impression",
"type": 4,
"required": false,
"average": null,
"values": [
{
"id": 9,
"code": "IMP1",
"sortOrder": 0,
"label": "Durable",
"count": 0
},
{
"id": 10,
"code": "IMP2",
"sortOrder": 1,
"label": "Stylish",
"count": 1
},
{
"id": 11,
"code": "IMP3",
"sortOrder": 2,
"label": "Modern",
"count": 0
},
{
"id": 12,
"code": "IMP4",
"sortOrder": 3,
"label": "Youthful",
"count": 0
}
]
},
{
"id": 4,
"label": "Weight",
"type": 3,
"required": false,
"average": null,
"values": [
{
"id": 13,
"code": "LW",
"sortOrder": 0,
"label": "Light",
"count": 1
},
{
"id": 14,
"code": "HW",
"sortOrder": 1,
"label": "Heavy",
"count": 0
}
]
}
],
"active": true,
"attributes":[
{
"type":"Size",
"typeLabel":"Size",
"values":[
{
"value":"Medium",
"valueLabel":"Medium"
}
]
},
{
"type":"Color",
"typeLabel":"Color",
"values":[
{
"value":"Red",
"valueLabel":"Red"
}
]
}
]
},
{
"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,
"code": "Q1",
"value": 1
},
{
"id": 2,
"code": "Q2",
"value": 2
},
{
"id": 3,
"code": "Q3",
"value": 3
},
{
"id": 4,
"code": "Q4",
"value": 4
},
{
"id": 5,
"code": "Q5",
"value": 5
}
]
},
{
"id": 2,
"label": "Comfort",
"type": 2,
"required": true,
"average": null,
"values": [
{
"id": 6,
"code": "CLOW",
"sortOrder": 0,
"label": "Low"
},
{
"id": 7,
"code": "CMED",
"sortOrder": 1,
"label": "Medium"
},
{
"id": 8,
"code": "CHIGH",
"sortOrder": 2,
"label": "High"
}
]
},
{
"id": 3,
"label": "Impression",
"type": 4,
"required": false,
"average": null,
"values": [
{
"id": 9,
"code": "IMP1",
"sortOrder": 0,
"label": "Durable",
"count": 0
},
{
"id": 10,
"code": "IMP2",
"sortOrder": 1,
"label": "Stylish",
"count": 1
},
{
"id": 11,
"code": "IMP3",
"sortOrder": 2,
"label": "Modern",
"count": 0
},
{
"id": 12,
"code": "IMP4",`
"sortOrder": 3,
"label": "Youthful",
"count": 0
}
]
},
{
"id": 4,
"label": "Weight",
"type": 3,
"required": false,
"average": null,
"values": [
{
"id": 13,
"code": "LW",
"sortOrder": 0,
"label": "Light",
"count": 0
},
{
"id": 14,
"code": "HW",
"sortOrder": 1,
"label": "Heavy",
"count": 0
}
]
}
],
"active": true,
"attributes":[
{
"type":"Size",
"typeLabel":"Size",
"values": [
{
"value":"Medium",
"valueLabel":"Medium"
}
]
},
{
"type":"Color",
"typeLabel":"Color",
"values": [
{
"value":"Blue",
"valueLabel":"Blue"
}
]
}
]
}
]
Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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 |
| ratings | number | Number of ratings 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) |
| attributes | resource | Attributes for this product |
| dimensions | resource | Custom values that can be assigned for this product |
| active | boolean | Indicates if product is active |
| userSettings | resource | User information that can be captured for this product. Nested user settings block - see Sites section |
UGC SummaryGET/v1.3/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.
Example URI
GET https://api.turnto.com/v1.3/products/ugc_summary?sku=12345,22222,33333&locale=en_US
URI Parameters
- 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.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
[
{
"sku": "HM100010",
"questions": 0,
"relatedQuestions": 0,
"comments": 0,
"answers": 0,
"relatedAnswers": 0,
"reviews": 2,
"ratings": 2,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 2,
"5": 0
},
"attributes": [
{
"type": "Size",
"typeLabel": "Size",
"values": [
{
"value": "Medium",
"valueLabel": "Medium"
}
]
},
{
"type": "Color",
"typeLabel": "Color",
"values": [
{
"value": "Red",
"valueLabel": "Red"
}
]
}
],
"dimensions": [
{
"id": 1,
"sortOrder": 1,
"label": "True to size",
"type": 2,
"required": false,
"average": 0,
"values": [
{
"id": 1,
"code": "SIZE1",
"sortOrder": 0,
"label": "Small"
},
{
"id": 2,
"code": "SIZE2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 3,
"code": "SIZE3",
"sortOrder": 2,
"label": "Large"
}
]
},
{
"id": 2,
"sortOrder": 2,
"label": "Fit",
"type": 2,
"required": false,
"average": 2,
"values": [
{
"id": 4,
"code": "FIT1",
"sortOrder": 0,
"label": "Tight"
},
{
"id": 5,
"code": "FIT2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 6,
"code": "FIT3",
"sortOrder": 2,
"label": "Relaxed"
}
]
},
{
"id": 3,
"sortOrder": 3,
"label": "Length",
"type": 2,
"required": false,
"average": 1,
"values": [
{
"id": 7,
"code": "LEN1",
"sortOrder": 0,
"label": "Short"
},
{
"id": 8,
"code": "LEN2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 9,
"code": "LEN3",
"sortOrder": 2,
"label": "Long"
}
]
},
{
"id": 4,
"sortOrder": 4,
"label": "Width",
"type": 2,
"required": false,
"average": 1,
"values": [
{
"id": 10,
"code": "WID1",
"sortOrder": 0,
"label": "Narrow"
},
{
"id": 11,
"code": "WID2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 12,
"code": "WID3",
"sortOrder": 2,
"label": "Wide"
}
]
}
],
"active": true,
"userSettings": {
"ageRange": {
"hidden": false,
"required": true,
"collectDuringContentSubmit": true,
"displayPublic": false
},
"cityState": {
"hidden": false,
"required": true,
"collectDuringContentSubmit": false,
"displayPublic": true
},
"shopperProfiles": [
{
"name": "bodyType",
"label": "Body Type",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 1,
"label": "Slim",
"hidden": false,
"sortOrder": 0,
"code": "BOD1"
},
{
"id": 2,
"label": "Athletic",
"hidden": false,
"sortOrder": 1,
"code": "BOD2"
},
{
"id": 3,
"label": "Average",
"hidden": false,
"sortOrder": 2,
"code": "BOD3"
},
{
"id": 4,
"label": "Broad",
"hidden": false,
"sortOrder": 3,
"code": "BOD4"
},
{
"id": 5,
"label": "Plus Size",
"hidden": false,
"sortOrder": 4,
"code": "BOD5"
}
]
},
{
"name": "skinType",
"label": "Skin Type",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 6,
"label": "Normal",
"hidden": false,
"sortOrder": 0,
"code": "SKIN1"
},
{
"id": 7,
"label": "Oily",
"hidden": false,
"sortOrder": 1,
"code": "SKIN2"
},
{
"id": 8,
"label": "Combination",
"hidden": false,
"sortOrder": 2,
"code": "SKIN3"
},
{
"id": 9,
"label": "Dry",
"hidden": false,
"sortOrder": 3,
"code": "SKIN4"
},
{
"id": 10,
"label": "Teenage",
"hidden": false,
"sortOrder": 4,
"code": "SKIN5"
},
{
"id": 11,
"label": "Sensitive",
"hidden": false,
"sortOrder": 5,
"code": "SKIN6"
}
]
},
{
"name": "skinTone",
"label": "Skin Tone",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 12,
"label": "Fair",
"hidden": false,
"sortOrder": 0,
"code": "TONE1"
},
{
"id": 13,
"label": "Light",
"hidden": false,
"sortOrder": 1,
"code": "TONE2"
},
{
"id": 14,
"label": "Medium",
"hidden": false,
"sortOrder": 2,
"code": "TONE3"
},
{
"id": 15,
"label": "Tanned",
"hidden": false,
"sortOrder": 3,
"code": "TONE4"
},
{
"id": 16,
"label": "Dark",
"hidden": false,
"sortOrder": 4,
"code": "TONE5"
}
]
},
{
"name": "height",
"label": "Height",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 17,
"label": "< 155 cm",
"hidden": false,
"sortOrder": 0,
"code": "H1"
},
{
"id": 18,
"label": "155-160 cm",
"hidden": false,
"sortOrder": 1,
"code": "H2"
},
{
"id": 19,
"label": "165-170 cm",
"hidden": false,
"sortOrder": 2,
"code": "H3"
},
{
"id": 20,
"label": "170-175 cm",
"hidden": false,
"sortOrder": 3,
"code": "H4"
},
{
"id": 21,
"label": "175-180 cm",
"hidden": false,
"sortOrder": 4,
"code": "H5"
},
{
"id": 22,
"label": "180-185 cm",
"hidden": false,
"sortOrder": 5,
"code": "H6"
},
{
"id": 23,
"label": "185-190 cm",
"hidden": false,
"sortOrder": 6,
"code": "H7"
},
{
"id": 24,
"label": "190-195 cm",
"hidden": false,
"sortOrder": 7,
"code": "H8"
}
]
}
]
}
},
{
"sku": "HM100030",
"questions": 0,
"relatedQuestions": 0,
"comments": 0,
"answers": 0,
"relatedAnswers": 0,
"reviews": 1,
"ratings": 1,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 0
},
"attributes": [
{
"type": "Size",
"typeLabel": "Size",
"values": [
{
"value": "Medium",
"valueLabel": "Medium"
}
]
},
{
"type": "Color",
"typeLabel": "Color",
"values": [
{
"value": "Blue",
"valueLabel": "Blue"
}
]
}
],
"dimensions": [
{
"id": 1,
"sortOrder": 1,
"label": "True to size",
"type": 2,
"required": false,
"average": 0,
"values": [
{
"id": 1,
"code": "SIZE1",
"sortOrder": 0,
"label": "Small"
},
{
"id": 2,
"code": "SIZE2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 3,
"code": "SIZE3",
"sortOrder": 2,
"label": "Large"
}
]
},
{
"id": 2,
"sortOrder": 2,
"label": "Fit",
"type": 2,
"required": false,
"average": 2,
"values": [
{
"id": 4,
"code": "FIT1",
"sortOrder": 0,
"label": "Tight"
},
{
"id": 5,
"code": "FIT2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 6,
"code": "FIT3",
"sortOrder": 2,
"label": "Relaxed"
}
]
},
{
"id": 3,
"sortOrder": 3,
"label": "Length",
"type": 2,
"required": false,
"average": 1,
"values": [
{
"id": 7,
"code": "LEN1",
"sortOrder": 0,
"label": "Short"
},
{
"id": 8,
"code": "LEN2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 9,
"code": "LEN3",
"sortOrder": 2,
"label": "Long"
}
]
},
{
"id": 4,
"sortOrder": 4,
"label": "Width",
"type": 2,
"required": false,
"average": 1,
"values": [
{
"id": 10,
"code": "WID1",
"sortOrder": 0,
"label": "Narrow"
},
{
"id": 11,
"code": "WID2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 12,
"code": "WID3",
"sortOrder": 2,
"label": "Wide"
}
]
}
],
"active": true,
"userSettings": {
"ageRange": {
"hidden": false,
"required": true,
"collectDuringContentSubmit": true,
"displayPublic": false
},
"cityState": {
"hidden": false,
"required": true,
"collectDuringContentSubmit": false,
"displayPublic": true
},
"shopperProfiles": [
{
"name": "bodyType",
"label": "Body Type",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 1,
"label": "Slim",
"hidden": false,
"sortOrder": 0,
"code": "BOD1"
},
{
"id": 2,
"label": "Athletic",
"hidden": false,
"sortOrder": 1,
"code": "BOD2"
},
{
"id": 3,
"label": "Average",
"hidden": false,
"sortOrder": 2,
"code": "BOD3"
},
{
"id": 4,
"label": "Broad",
"hidden": false,
"sortOrder": 3,
"code": "BOD4"
},
{
"id": 5,
"label": "Plus Size",
"hidden": false,
"sortOrder": 4,
"code": "BOD5"
}
]
},
{
"name": "skinType",
"label": "Skin Type",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 6,
"label": "Normal",
"hidden": false,
"sortOrder": 0,
"code": "SKIN1"
},
{
"id": 7,
"label": "Oily",
"hidden": false,
"sortOrder": 1,
"code": "SKIN2"
},
{
"id": 8,
"label": "Combination",
"hidden": false,
"sortOrder": 2,
"code": "SKIN3"
},
{
"id": 9,
"label": "Dry",
"hidden": false,
"sortOrder": 3,
"code": "SKIN4"
},
{
"id": 10,
"label": "Teenage",
"hidden": false,
"sortOrder": 4,
"code": "SKIN5"
},
{
"id": 11,
"label": "Sensitive",
"hidden": false,
"sortOrder": 5,
"code": "SKIN6"
}
]
},
{
"name": "skinTone",
"label": "Skin Tone",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 12,
"label": "Fair",
"hidden": false,
"sortOrder": 0,
"code": "TONE1"
},
{
"id": 13,
"label": "Light",
"hidden": false,
"sortOrder": 1,
"code": "TONE2"
},
{
"id": 14,
"label": "Medium",
"hidden": false,
"sortOrder": 2,
"code": "TONE3"
},
{
"id": 15,
"label": "Tanned",
"hidden": false,
"sortOrder": 3,
"code": "TONE4"
},
{
"id": 16,
"label": "Dark",
"hidden": false,
"sortOrder": 4,
"code": "TONE5"
}
]
},
{
"name": "height",
"label": "Height",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 17,
"label": "< 155 cm",
"hidden": false,
"sortOrder": 0,
"code": "H1"
},
{
"id": 18,
"label": "155-160 cm",
"hidden": false,
"sortOrder": 1,
"code": "H2"
},
{
"id": 19,
"label": "165-170 cm",
"hidden": false,
"sortOrder": 2,
"code": "H3"
},
{
"id": 20,
"label": "170-175 cm",
"hidden": false,
"sortOrder": 3,
"code": "H4"
},
{
"id": 21,
"label": "175-180 cm",
"hidden": false,
"sortOrder": 4,
"code": "H5"
},
{
"id": 22,
"label": "180-185 cm",
"hidden": false,
"sortOrder": 5,
"code": "H6"
},
{
"id": 23,
"label": "185-190 cm",
"hidden": false,
"sortOrder": 6,
"code": "H7"
},
{
"id": 24,
"label": "190-195 cm",
"hidden": false,
"sortOrder": 7,
"code": "H8"
}
]
}
]
}
}
]Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Too many SKUs requested. Maximum is 25.",
"code": 122
}
]
}Update Product ¶
Update product information.
Update ProductPOST/v1.3/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. |
| attributes | No | A JSON field that allows the specification of product attributes (if enabled for site). If specified, a type and list of values is required for each attribute. |
| 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
POST https://api.turnto.com/v1.3/products
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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": "",
"attributes": "{\"Color\": [\"Red\"],\"Size\": [\"Medium\"]}",
"localeData": "{\"fr_CA\": {\"title\": \"Bleu Chemise\", \"itemUrl\": \"http://domain.com/pathToFrenchProductPage\"} }"
}Response
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"sku": "11112222"
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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.3/orders/create
This endpoint typically will be called from an order confirmation page. An order ID that uniquely identifies the order is required.
A user credential is required to create an order. The user is identified either by email address or a unique external ID. The user first and last name must be supplied.
An order item object is populated for each line item. Each order item has a catalog item associated with it. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, a new catalog item record will be created.
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 | 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 |
| items[].lineItemId | No | |
| items[].title | Yes | |
| items[].url | Yes | |
| items[].sku | Yes | |
| items[].brand | No | |
| items[].price | No | |
| items[].itemImageUrl | Yes |
Example URI
POST https://api.turnto.com/v1.3/orders/create
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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"
}
]
}Response
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"id": 3317217,
"orderId": "99977"
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Invalid delivery date",
"code": 146
}
]
}Cancel Order ¶
Cancel OrderPOST/v1.3/orders/cancel
This endpoint allows an entire order or an order line item to be cancelled. To cancel an entire order, provide the order ID. To cancel an order line item, provide the line item SKU.
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
POST https://api.turnto.com/v1.3/orders/cancel
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"orderId": "99977",
"sku": ""
}Response
200Headers
Content-Type: application/json;charset=UTF-8Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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 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 ¶
Save MediaPOST/v1.3/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.
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
POST https://api.turnto.com/v1.3/media
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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"
}
]
}Response
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"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,
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"audio": []
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No catalog item found for sku (5558886554)",
"code": 106
}
]
}Flag Media ¶
Flag MediaPOST/v1.3/media/{id}/flag{?reason}
This endpoint is used to flag media content. A reason for flagging the content must be selected. Media can be flagged as Intellectual Property Violation, Inappropriate, Spam, or Off-topic.
Example URI
POST https://api.turnto.com/v1.3/media/12345/flag?reason=spam
URI Parameters
- id
number(required) Example: 12345The ID of the media.
- reason
string(required) Example: spamReason for flagging media.
Choices:
ipviolationinappropriatespamofftopic
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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",
"ipViolationFlag": false,
"inappropriateFlag": true,
"offensiveFlag": false,
"spamFlag": true,
"offTopicFlag": false,
"tags": []
}
],
"video": [],
"audio": []
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Attempting to flag media with invalid reason: UNCOOL",
"code": 219
}
]
}User Media List ¶
User MediaGET/v1.3/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
GET https://api.turnto.com/v1.3/media?userId=EXT12345&email=andrew@sample.com&sku=12345
URI Parameters
- 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.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"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",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"audio": []
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Unknown Email Address",
"code": 129
}
]
}Photos ¶
A photo is a UGC image that can be created by a user. When a photo is created, it must be associated with at least one catalog item. See Media for valid image types and sizes.
Resource Properties - Photos
| Property | Type | Description |
|---|---|---|
| id | number | TurnTo unique ID for this photo |
| caption | string | Caption |
| 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 |
| tags | string | List of tag codes associated with this photo |
| catalogItems | resource | Products this photo is associated with. Nested products block - see Products section |
| dateCreated | date | Date media created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
Photos List ¶
Photos ListGET/v1.3/photos{?sku,publishedOnly,tags,locale,limit,offset,sort}
This endpoint will return a list of photos for an SKU, optionally sorted by date created. Results may be filtered by published status, tag code, locale, and whether or not photos are for a related SKU. Pagination of results is supported using limit and offset parameters.
Example URI
GET https://api.turnto.com/v1.3/photos?sku=12345&publishedOnly=true&tags=CSR,DAM,SOT&locale=en_US&limit=50&offset=10&sort=dateCreated:desc
URI Parameters
- sku
string(required) Example: 12345The SKU of the catalog item that includes the photo.
- includeRelated
boolean(optional) Default: false Example: falseIf true, also return photos for related SKUs.
Choices:
truefalse- publishedOnly
boolean(optional) Default: true Example: trueIf true, only return published photos.
Choices:
truefalse- tags
string(optional) Example: CSR,DAM,SOTOnly return photos that contain at least 1 of the comma separated tag codes.
- locale
string(optional) Example: en_USOnly return photos for this locale.
- limit
number(optional) Default: 50 Example: 50Maximum number of photos to show.
- offset
number(optional) Default: 0 Example: 10Offset into photo results. Zero based, so first result is offset = 0.
- sort
string(optional) Default: dateCreated:desc Example: dateCreated:descField to sort photos by. Valid directions are: asc and desc.
Choices:
dateCreated:descdateCreated:asc
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"photos": [
{
"id": 4,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": true,
"dateCreated": "2021-01-07T17:24:53-05:00",
"normalUrl": "https://dev.turntodev.com/devimagestore/media/temp/56AF992E653A5F3EAEEB890231E63C17_1610058292997_1.jpeg",
"thumbnailUrl": null,
"originalUrl": "https://dev.turntodev.com/devimagestore/media/temp/56AF992E653A5F3EAEEB890231E63C17_1610058292997_1.jpeg",
"tags": [],
"reviewIds": [
235,
307
],
"catalogItems": [
{
"sku": "1234567",
"title": "Dinner Jacket",
"url": "www.sample.com/products/Dinner Jacket",
"category": null,
"reviewCount": 1,
"ratingCount": 1,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 0
},
"attributes": [
{
"type": "Product group",
"typeLabel": "Product group",
"values": [
{
"value": "Jackets",
"valueLabel": "Jackets"
}
]
},
{
"type": "Assortment type",
"typeLabel": "Assortment type",
"values": [
{
"value": "Clothing",
"valueLabel": "Clothing"
}
]
},
{
"type": "Age group",
"typeLabel": "Age group",
"values": [
{
"value": "Adult",
"valueLabel": "Adult"
}
]
}
]
}
]
}
],
"offset": 0,
"limit": 10,
"total": 1
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{"errors": [{
"message": "Invalid limit or offset",
"code": 103
}]}
{"errors": [{
"message": "No catalog item was found for sku 7969494",
"code": 106
}]}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 |
| syndication.sourceName | string | Syndication source name |
| syndication.siteUrl | string | Syndication source site URL |
| syndication.logoUrl | string | Syndication source logo URL |
Question List ¶
Question ListGET/v1.3/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
GET https://api.turnto.com/v1.3/questions?sku=12345&related=false&publishedOnly=true&tags=CSR,DAM,SOT&locale=en_US&limit=10&offset=10&sort=dateCreated:desc
URI Parameters
- 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:
truefalse- publishedOnly
boolean(optional) Default: true Example: trueIf true, only return published questions.
Choices:
truefalse- 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:
answerCountdateCreatedtexttextLengthupVotes
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": [],
"syndication": {
"sourceName": "Acme Widgets Ltd",
"siteUrl": "https://www.amazinggadgets4all.com//home.html",
"logoUrl": null
}
},
{
"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"
],
"syndication": null
},
{
"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,
"active": true
}
],
"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,
"active": true
}
],
"tags": []
}
],
"offset": 0,
"limit": 50,
"total": 2
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{"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.3/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
GET https://api.turnto.com/v1.3/questions/12345
URI Parameters
- id
number(required) Example: 12345The ID of the question.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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,
"syndication": {
"sourceName": "Acme Widgets Ltd",
"siteUrl": "https://www.amazinggadgets4all.com//home.html",
"logoUrl": null
}
}
],
"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,
"active": true
}
],
"tags": [
"SOT",
"FLF",
"DAM",
"BRL"
],
"syndication": {
"sourceName": "Acme Widgets Ltd",
"siteUrl": "https://www.amazinggadgets4all.com//home.html",
"logoUrl": null
}
}Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No question was found for the specified id (949494949949)",
"code": 107
}
]
}Create Question ¶
Create QuestionPOST/v1.3/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
POST https://api.turnto.com/v1.3/questions
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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"
}Response
201Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.3/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,
"active": true
}
]
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No catalog item was found for sku (7969494)",
"code": 106
}
]
}Question Vote Up ¶
Question Vote UpPOST/v1.3/questions/{id}/voteup
This endpoint registers an up vote for a question.
Example URI
POST https://api.turnto.com/v1.3/questions/12345/voteup
URI Parameters
- id
number(required) Example: 12345The ID of the question.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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,
"active": true
}
],
"tags": []
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No question was found for the specified id (145454)",
"code": 107
}
]
}Answer More Questions ¶
Answer More QuestionsGET/v1.3/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 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
GET https://api.turnto.com/v1.3/amq?email=a@a.com&userId=7654321&sku=12345&locale=en_US&questionsOnly=false&purchasesOnly=false&limit=10&offset=0
URI Parameters
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:
truefalse- purchasesOnly
boolean(optional) Default: false Example: falseOnly return purchases.
Choices:
truefalse- 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.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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",
"active": true
}
]
},
{
"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",
"active": true
}
]
},
{
"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",
"active": true
}
]
}
],
"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
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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 answer was created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ) |
| reviewedDate | date | Date that 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 |
| syndication.sourceName | string | Syndication source name |
| syndication.siteUrl | string | Syndication source site URL |
| syndication.logoUrl | string | Syndication source logo URL |
Question Answers ¶
Question AnswersGET/v1.3/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
GET https://api.turnto.com/v1.3/questions/12345/answers?publishedOnly=true&locale=en_US&limit=10&offset=10&sort=dateCreated:desc
URI Parameters
- id
number(required) Example: 12345The ID of the question.
- publishedOnly
boolean(optional) Default: true Example: trueIf true, only return published answers.
Choices:
truefalse- locale
string(optional) Example: en_USOnly return answers for this locale.
- limit
number(optional) Default: 50 Example: 10Maximum 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: dateCreated:descField to sort answers by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
dateCreatedtexttextLengthupVotes
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No question was found for the specified id (49439)",
"code": 107
}
]
}Answer Detail ¶
Answer DetailGET/v1.3/answers/{id}
This endpoint will return a single answer.
The required answer is identified by its ID.
Example URI
GET https://api.turnto.com/v1.3/answers/12345
URI Parameters
- id
number(required) Example: 12345The ID of the answer.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No answer was found for the specified id (949494949949)",
"code": 132
}
]
}Create Answer ¶
Create AnswerPOST/v1.3/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
POST https://api.turnto.com/v1.3/questions/12345/answers
URI Parameters
- id
number(required) Example: 12345The ID of the answer.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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"
}Response
201Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.3/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
}
]
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No question was found for the specified id (49439)",
"code": 107
}
]
}Answer Vote Up ¶
Answer Vote UpPOST/v1.3/answers/{id}/voteup
Registers an up vote for an answer.
Example URI
POST https://api.turnto.com/v1.3/answers/12345/voteup
URI Parameters
- id
number(required) Example: 12345The ID of the answer.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No answer was found for the specified id (145454)",
"code": 131
}
]
}Flag Answer ¶
Flag AnswerPOST/v1.3/answers/{id}/flag
Flag an answer as inappropriate.
Example URI
POST https://api.turnto.com/v1.3/answers/12345/flag
URI Parameters
- id
number(required) Example: 12345The ID of the answer.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No answer was found for the specified id (145454)",
"code": 132
}
]
}Thank Answerer ¶
Thank AnswererPOST/v1.3/answers/{id}/thank
Sends a thank you email to the user who created the answer.
Example URI
POST https://api.turnto.com/v1.3/answers/12345/thank
URI Parameters
- id
number(required) Example: 12345The ID of the answer.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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 |
| syndication.sourceName | string | Syndication source name |
| syndication.siteUrl | string | Syndication source site URL |
| syndication.logoUrl | string | Syndication source logo URL |
Answer Replies ¶
Answer RepliesGET/v1.3/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
GET https://api.turnto.com/v1.3/answers/12345/replies?publishedOnly=true&locale=en_US&limit=10&offset=10&sort=dateCreated:desc
URI Parameters
- id
number(required) Example: 12345The ID of the answer.
- publishedOnly
boolean(optional) Default: true Example: trueIf true, only return published replies.
Choices:
truefalse- locale
string(optional) Example: en_USOnly return replies for this locale.
- limit
number(optional) Default: 50 Example: 10Maximum number of replies to show.
- offset
number(optional) Default: 0 Example: 10Offset into replies results. Zero based so first result is offset = 0.
- sort
string(optional) Default: dateCreated:desc Example: dateCreated:descField to sort replies by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
dateCreatedtexttextLength
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No answer was found for the specified id (49439)",
"code": 132
}
]
}Reply Detail ¶
Reply DetailGET/v1.3/replies/{id}
This endpoint will return a single reply.
The required reply is identified by its ID.
Example URI
GET https://api.turnto.com/v1.3/replies/12345
URI Parameters
- id
number(required) Example: 12345The ID of the reply.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No reply was found for the specified id (949494949949)",
"code": 133
}
]
}Create Reply ¶
Create ReplyPOST/v1.3/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 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. |
| 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
POST https://api.turnto.com/v1.3/answers/12345/replies
URI Parameters
- id
number(required) Example: 12345The ID of the reply.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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"
}Response
201Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.3/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": []
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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 |
| catalogItems | resource | Product for which this comment was posted. Nested products block - see Products section |
Comment Detail ¶
Comment DetailGET/v1.3/comments/{id}
This endpoint will return a single Comment.
The required comment is identified by its ID.
Example URI
GET https://api.turnto.com/v1.3/comments/12345
URI Parameters
- id
number(required) Example: 12345The ID of the Comment.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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",
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"active": true
}
],
"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": []
}Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No comment was found for the specified id (12292929)",
"code": 123
}
]
}Create Comment ¶
Create CommentPOST/v1.3/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 |
| catalogItems[0].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. |
| catalogItems[0].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 |
| catalogItems[0].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
POST https://api.turnto.com/v1.3/comments
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"text": "This Master Chef has loads of power and more speeds than you will ever need!",
"locale": "en_US",
"catalogItems": [
{
"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"
}Response
201Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.3/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",
"catalogItems": [
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"active": true
}
],
"orderId": "5555522",
"user": {
"nickName": "",
"firstName": "Andy",
"lastName": "Adamson",
"emailAddress": "andrew@sample.com",
"externalId": null,
"city": "Miami",
"state": "FL",
"country": "US",
"ageRange": 1
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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? |
| incentiveType | string | Type of incentive |
| campaign | string | Campaign identifier |
| 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 |
| userAgent | string | The browser/operating system of the UGC author |
| source | string | Source of UGC |
| 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 ¶
Reviews ListGET/v1.3/reviews{?sku,related,includeRelated,includeRatingOnlyReviews,publishedOnly,suppressUserPII,tags,locale,dateCreatedFrom,dateCreatedTo,filter,limit,offset,sort,includeFilters}
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.
Advanced filtering
The parameter ‘filter’ provides the ability to further drill down into review results using customer specific properties. Properties are specified using filter keywords that identify the property and required condition or value. Properties can be logically combined to create more complex filters.
User Properties
Basic information about a user’s age and location appears in the nested ‘user’ block of each review result. Results can be filtered using any of the individual properties for ageRange, city, state, and country. A value to match must be supplied.
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 review result. Results can be filtered for shopper profiles using the ‘sp’ keyword and identifying the shopper profile by its id or customer defined code.
Customer Defined Rating Sub-Dimensions
Customer defined rating sub-dimension values captured for a review appear in the nested ‘dimensions’ block of each review result. Results can be filtered for rating sub-dimensions using the ‘dim’ keyword and identifying the rating sub-dimension by its value or customer defined code.
Product Attributes
Product attributes are individual items of information about a product that appear in the nested ‘attributes’ block of each review result. Results can be filtered for product attributes using the ‘pa’ keyword and identifying the product attribute by its type. A value to match must be supplied.
Note: The use of product attributes is not enabled by default. Please contact TurnTo support to configure this option for your site.
Filter keyword summary
| Property | Response Element | Example Expression | Meaning |
|---|---|---|---|
| User Age Range | user.ageRange | age(2,3) | User is in age range 2 or 3 |
| User City | user.city | city(nyc) | City is NYC |
| User State | user.state | state(ny,nj) | State is NY or NJ |
| User Country | user.country | country(us,ca) | Country is US or CA |
| Shopper Profile (present) | user.shopperProfiles[ ].id | sp(1,3) | SPs contain 1 or 3 |
| Review Dimension | dimensions[ ].value | dim(1,4) | Dimensions contain 1 or 4 |
| Product Attribute | catalogItems[0].attributes[ ].type catalogItems[0].attributes[ ].values[ ].value | pa(‘Color:Blue’) | Color is Blue |
| Review Rating | rating | rating(4,5) | Review rating is 4 or 5 |
| Photos | media.photo[ ] | photos(true) | Review includes photos |
| Videos | media.video[ ] | videos(true) | Review includes videos |
The natural logic of filter keywords is OR.
E.g. Shopper profile 1 OR 3 is set
sp(1,3)Multiple filter keywords may be combined as a logical AND.
E.g. Age range is 2 OR 3 AND shopper profile 1 is set
age(2,3) sp(1)Filter keywords can be negated using the ! symbol.
E.g. Age range is 4 AND country is NOT Canada
age(4) !country(ca)Use single quotes for text if phrase contains non-word characters.
pa('Color:Navy Blue')Use single quotes for codes identifying shopper profile and dimension values.
E.g. Shopper profile is ‘TALL’ AND Dimension is ‘MOD’ OR ‘FCY’
sp('TALL') dim('MOD','FCY')Available filters
If the parameter ‘includeFilters’ is set to true then the response will include a nested ‘filters’ block that contains information about available filters for the selected reviews result set.
Filters are calculated for a range of properties related to the reviews:
-
Customer Defined Shopper Profiles
-
Customer Defined Rating Sub-Dimensions
-
Product Attributes
-
Review Rating
-
Photos
-
Videos
Filters are grouped by type and include all available values for that filter. For each filter value the property ‘count’ is used to indicate the number of reviews that contain that value. The property ‘filter’ contains the filter keyword expression that can be used to apply that filter to the reviews result set in a subsequent request.
Example URI
GET https://api.turnto.com/v1.3/reviews?sku=12345&related=false&includeRelated=false&includeRatingOnlyReviews=true&publishedOnly=true&suppressUserPII=false&tags=CSR,DAM,SOT&locale=en_US&dateCreatedFrom=2015-09-14T00:00:00-04:00&dateCreatedTo=2015-09-14T23:59:59-04:00&filter=age(2) sp(1,3)&limit=10&offset=10&sort=textLength:desc&includeFilters=false
URI Parameters
- 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:
truefalse- 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:
truefalse- includeRatingOnlyReviews
boolean(optional) Default: true Example: trueIf includeRatingOnlyReviews is false, rating only reviews (those without title and text) will be excluded from results.
Choices:
truefalse- publishedOnly
boolean(optional) Default: true Example: trueIf true, only return published reviews.
Choices:
truefalse- suppressUserPII
boolean(optional) Default: false Example: falseIf true, all user fields will be returned null. The nested blocks shopperProfiles and badge are not affected.
Choices:
truefalse- 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_USIf specified, only return reviews for this locale.
- 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.
- filter
string(optional) Example: age(2) sp(1,3)If specified, apply advanced filtering to review results.
- limit
number(optional) Default: 50 Example: 10Maximum 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:
dateCreatedratingtextLengthupVotes- includeFilters
boolean(optional) Default: false Example: falseIf true, the response will include nested filters block containing information about available filters for the selected reviews result set.
Choices:
truefalse
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"reviews": [
{
"id": 6,
"locale": "en_US",
"rating": 4,
"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": true,
"incentiveType": "SWEEPSTAKES",
"campaign": "SPRING2021",
"upVotes": 0,
"downVotes": 0,
"orderId": null,
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"id": 4,
"code": "Q4",
"label": null,
"value": 4
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Fit",
"id": 7,
"code": "FIT2",
"label": "perfect",
"value": null
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Occasion",
"id": 2,
"code": "OCC2",
"label": "Formal",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 9,
"code": "IMP1",
"label": "Stylish",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 11,
"code": "IMP3",
"label": "Modern",
"value": null
}
],
"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-30T16:22:34-04:00"
}
],
"tags": [
"CSR",
"INA"
],
"media": {
"photo": [
{
"id": 11,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": true,
"dateCreated": "2018-08-30T16:15:44-04:00",
"normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_L1000.jpeg",
"thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_PZ320.jpeg",
"originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1.jpeg",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"video": [
{
"id": 12,
"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-30T16:15:44-04:00"
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"audio": []
},
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 3,
"code": "TALL"
}
]
},
"syndication": null,
"reviewedDate": "2018-08-30T16:20:32-04:00",
"purchaseDate": null,
"dateCreated": "2018-08-30T16:15:44-04:00",
"acceptedTermsAndConditions": true,
"catalogItems": [
{
"sku": "1234567",
"title": "Dinner Jacket",
"url": "www.sample.com/products/Dinner Jacket",
"category": null,
"reviewCount": 1,
"ratingCount": 1,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 0
},
"active": true,
"attributes": [
{
"type": "Product group",
"typeLabel": "Product group",
"values": [
{
"value": "Jackets",
"valueLabel": "Jackets"
}
]
},
{
"type": "Assortment type",
"typeLabel": "Assortment type",
"values": [
{
"value": "Clothing",
"valueLabel": "Clothing"
}
]
},
{
"type": "Age group",
"typeLabel": "Age group",
"values": [
{
"value": "Adult",
"valueLabel": "Adult"
}
]
}
]
}
]
}
],
"offset": 0,
"limit": 50,
"total": 1,
"filters": {
"attributes": [
{
"type": "Age group",
"typeLabel": "Age group",
"values": [
{
"value": "Adult",
"valueLabel": "Adult",
"count": 1,
"filter": "pa('Age group:Adult')"
}
]
},
{
"type": "Assortment type",
"typeLabel": "Assortment type",
"values": [
{
"value": "Clothing",
"valueLabel": "Clothing",
"count": 1,
"filter": "pa('Assortment type:Clothing')"
}
]
},
{
"type": "Product group",
"typeLabel": "Product group",
"values": [
{
"value": "Jackets",
"valueLabel": "Jackets",
"count": 1,
"filter": "pa('Product group:Jackets')"
}
]
}
],
"dimensions": [
{
"id": 1,
"name": "quality",
"label": "Overall Quality",
"sortOrder": 1,
"required": false,
"type": 1,
"values": [
{
"id": 1,
"code": "Q1",
"label": null,
"sortOrder": null,
"count": 0,
"filter": "dim('Q1')"
},
{
"id": 2,
"code": "Q2",
"label": null,
"sortOrder": null,
"count": 0,
"filter": "dim('Q2')"
},
{
"id": 3,
"code": "Q3",
"label": null,
"sortOrder": null,
"count": 0,
"filter": "dim('Q3')"
},
{
"id": 4,
"code": "Q4",
"label": null,
"sortOrder": null,
"count": 1,
"filter": "dim('Q4')"
},
{
"id": 5,
"code": "Q5",
"label": null,
"sortOrder": null,
"count": 0,
"filter": "dim('Q5')"
}
]
},
{
"id": 2,
"name": "fit",
"label": "Fit",
"sortOrder": 2,
"required": false,
"type": 2,
"values": [
{
"id": 6,
"code": "FIT1",
"label": "Tight",
"sortOrder": 0,
"count": 0,
"filter": "dim('FIT1')"
},
{
"id": 7,
"code": "FIT2",
"label": "Spot on",
"sortOrder": 1,
"count": 1,
"filter": "dim('FIT2')"
},
{
"id": 8,
"code": "FIT3",
"label": "Relaxed",
"sortOrder": 2,
"count": 0,
"filter": "dim('FIT3')"
}
]
},
{
"id": 3,
"name": "occasion",
"label": "Occasion",
"sortOrder": 3,
"required": false,
"type": 3,
"values": [
{
"id": 9,
"code": "OCC1",
"label": "Casual",
"sortOrder": 0,
"count": 0,
"filter": "dim('OCC1')"
},
{
"id": 10,
"code": "OCC2",
"label": "Formal",
"sortOrder": 1,
"count": 1,
"filter": "dim('OCC2')"
}
]
},
{
"id": 4,
"name": "impression",
"label": "Impression",
"sortOrder": 4,
"required": false,
"type": 4,
"values": [
{
"id": 11,
"code": "IMP1",
"label": "Stylish",
"sortOrder": 0,
"count": 1,
"filter": "dim('IMP1')"
},
{
"id": 12,
"code": "IMP2",
"label": "Modern",
"sortOrder": 1,
"count": 1,
"filter": "dim('IMP2')"
},
{
"id": 13,
"code": "IMP3",
"label": "Fancy",
"sortOrder": 2,
"count": 0,
"filter": "dim('IMP3')"
},
{
"id": 14,
"code": "IMP4",
"label": "Spicy",
"sortOrder": 3,
"count": 0,
"filter": "dim('IMP4')"
}
]
}
],
"userSettings": {
"shopperProfiles": [
{
"id": 1,
"name": "height",
"label": "Height",
"required": false,
"type": 0,
"displayPublic": true,
"collectDuringContentSubmit": true,
"values": [
{
"id": 1,
"sortOrder": 0,
"label": "Short",
"count": 0,
"code": "SHORT",
"filter": "sp('SHORT')"
},
{
"id": 2,
"sortOrder": 1,
"label": "Average",
"count": 0,
"code": "AVG",
"filter": "sp('AVG')"
},
{
"id": 3,
"sortOrder": 2,
"label": "Tall",
"count": 0,
"code": "TALL",
"filter": "sp('TALL')"
}
]
}
]
},
"rating": [
{
"value": 1,
"count": 0,
"filter": "rating(1)"
},
{
"value": 2,
"count": 0,
"filter": "rating(2)"
},
{
"value": 3,
"count": 0,
"filter": "rating(3)"
},
{
"value": 4,
"count": 1,
"filter": "rating(4)"
},
{
"value": 5,
"count": 0,
"filter": "rating(5)"
}
],
"photos": [
{
"value": "true",
"count": 1,
"filter": "photos(true)"
},
{
"value": "false",
"count": 9,
"filter": "photos(false)"
}
],
"videos": [
{
"value": "true",
"count": 1,
"filter": "videos(true)"
},
{
"value": "false",
"count": 9,
"filter": "videos(false)"
}
]
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Missing or invalid parameters sku",
"code": 114
}
]
}Review Detail ¶
Review DetailGET/v1.3/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
GET https://api.turnto.com/v1.3/reviews/12345
URI Parameters
- id
number(required) Example: 12345The ID of the review.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"id": 6,
"rating": 4,
"title": "An awesome jacket!",
"text": "This dinner jacket fits perfects and looks absolutely amazing.",
"textLength": 62,
"locale": "en_US",
"acceptedTermsAndConditions": true,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": true,
"autoModerated": false,
"published": true,
"upVotes": 0,
"downVotes": 0,
"incentivized": true,
"incentiveType": "SWEEPSTAKES",
"campaign": "SPRING2021",
"orderId": null,
"catalogItems": [
{
"sku": "1234567",
"title": "Dinner Jacket",
"url": "www.sample.com/products/Dinner Jacket",
"category": null,
"reviewCount": 1,
"ratingCount": 1,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 0
},
"active": true,
"attributes": [
{
"type": "Product group",
"typeLabel": "Product group",
"values": [
{
"value": "Jackets",
"valueLabel": "Jackets"
}
]
},
{
"type": "Assortment type",
"typeLabel": "Assortment type",
"values": [
{
"value": "Clothing",
"valueLabel": "Clothing"
}
]
},
{
"type": "Age group",
"typeLabel": "Age group",
"values": [
{
"value": "Adult",
"valueLabel": "Adult"
}
]
}
]
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"id": 4,
"code": "Q4",
"label": null,
"value": 4
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Fit",
"id": 7,
"code": "FIT2",
"label": "perfect",
"value": null
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Occasion",
"id": 2,
"code": "OCC2",
"label": "Formal",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 9,
"code": "IMP1",
"label": "Stylish",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 11,
"code": "IMP3",
"label": "Modern",
"value": null
}
],
"media": {
"photo": [
{
"id": 11,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": true,
"dateCreated": "2018-08-30T16:15:44-04:00",
"normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_L1000.jpeg",
"thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_PZ320.jpeg",
"originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1.jpeg",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"video": [
{
"id": 12,
"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-30T16:15:44-04:00",
"tags": []
}
],
"audio": []
},
"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-30T16:22:34-04:00"
}
],
"reviewedDate": "2018-08-30T16:20:32-04:00",
"purchaseDate": null,
"dateCreated": "2018-08-30T16:15:44-04:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 3,
"code": "TALL"
}
]
},
"tags": [
"CSR",
"INA"
]
}Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No review was found for the specified id (949494949949)",
"code": 139
}
]
}Create Review ¶
Create ReviewPOST/v1.3/reviews
Creates a new review. Currently a review can only be associated with a single catalog item. By default, TurnTo accepts only one review per SKU per user. If you want to accept multiple reviews from a single shopper for a single product, contact your TurnTo Customer Success Manager. Multiple reviews per user per SKU can be enabled globally for all products, or enabled for specific products based on a product attribute in the product catalog.
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 (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.
A requirement that a user accept terms and conditions when submitting a review is a site configurable option. If option is enabled then the parameter ‘acceptedTermsAndConditions’ must be set to true.
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.
The customData property can be used to add custom data to reviews. It passes a JSON object with key-value pairs. Any customData object values will be treated as strings. Please contact TurnTo support to configure this option for your site.
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) |
| acceptedTermsAndConditions | No | Has user accepted terms and conditions? |
| 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[].code | No | Customer defined code identifying the shopper profile |
| 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 |
| incentivized | No | Did reviewer receive incentive? |
| incentiveType | No | Type of incentive (SWEEPSTAKES, SAMPLE) can only be specified if incentivized is not false |
| campaign | No | Campaign identifier |
| 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 |
| dimensions[].code | No | Customer defined code identifying the dimension value |
| customData | No | Additional key-value pairs associated with the review |
| deviceFingerprint | No | A unique ID associated with a device and used for authentication |
| 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
POST https://api.turnto.com/v1.3/reviews
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"externalId": "ext9485337445",
"title": "An awesome jacket!",
"text": "This dinner jacket fits perfects and looks absolutely amazing.",
"rating": 4,
"locale": "en_US",
"acceptedTermsAndConditions": true,
"catalogItems": [
{
"sku": "1234567"
}
],
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"shopperProfiles": [
{
"id": null,
"code": "TALL"
}
]
},
"dimensions": [
{
"value": null,
"code": "Q4"
},
{
"value": null,
"code": "FIT2"
},
{
"value": null,
"code": "OCC2"
},
{
"value": null,
"code": "IMP1"
},
{
"value": null,
"code": "IMP3"
}
],
"customData": [
{
"name": "storeId",
"value": "123"
}
],
"media": {
"ids": [],
"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"
}
]
},
"userIpAddr": "555.555.100.001",
"userAgent": "Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405",
"incentivized": true,
"incentiveType": "SWEEPSTAKES",
"campaign": "SPRING2021",
"turntoTrackingToken": "eyJ0cmFuc0lkIjoxLCJ0dXJudG9FbWFpbFR5cGUiOiJyZXZpZXdTb2xpY2l0YXRpb24iLCJ0dXJudG9za3UiOiI1NjY0NTQyNTMzNCJ9"
}Response
201Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.3/reviews/{id}Body
{
"id": 6,
"rating": 4,
"title": "An awesome jacket!",
"text": "This dinner jacket fits perfects and looks absolutely amazing.",
"textLength": 62,
"locale": "en_US",
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": false,
"autoModerated": false,
"published": false,
"upVotes": 0,
"downVotes": 0,
"incentivized": true,
"incentiveType": "SWEEPSTAKES",
"campaign": "SPRING2021",
"orderId": null,
"catalogItems": [
{
"sku": "1234567",
"title": "Dinner Jacket",
"url": "www.sample.com/products/Dinner Jacket",
"category": null,
"reviewCount": 0,
"ratingCount": 0,
"averageRating": 0,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
},
"active": true,
"attributes": [
{
"type": "Product group",
"typeLabel": "Product group",
"values": [
{
"value": "Jackets",
"valueLabel": "Jackets"
}
]
},
{
"type": "Assortment type",
"typeLabel": "Assortment type",
"values": [
{
"value": "Clothing",
"valueLabel": "Clothing"
}
]
},
{
"type": "Age group",
"typeLabel": "Age group",
"values": [
{
"value": "Adult",
"valueLabel": "Adult"
}
]
}
]
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"id": 4,
"code": "Q4",
"label": null,
"value": 4
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Fit",
"id": 7,
"code": "FIT2",
"label": "perfect",
"value": null
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Occasion",
"id": 2,
"code": "OCC2",
"label": "Formal",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 9,
"code": "IMP1",
"label": "Stylish",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 11,
"code": "IMP3",
"label": "Modern",
"value": null
}
],
"media": {
"photo": [],
"video": [],
"audio": []
},
"responses": [],
"reviewedDate": null,
"purchaseDate": null,
"dateCreated": "2018-08-30T16:15:44-04:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 3,
"code": "TALL"
}
]
},
"tags": []
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Review must be at least 50 characters.",
"code": 142
}
]
}Review Vote Up ¶
Review Vote UpPOST/v1.3/reviews/{id}/voteup
Registers an up vote for a review.
Example URI
POST https://api.turnto.com/v1.3/reviews/12345/voteup
URI Parameters
- id
number(required) Example: 12345The ID of the review.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"id": 6,
"rating": 4,
"title": "An awesome jacket!",
"text": "This dinner jacket fits perfects and looks absolutely amazing.",
"textLength": 62,
"locale": "en_US",
"acceptedTermsAndConditions": true,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": true,
"autoModerated": false,
"published": true,
"upVotes": 1,
"downVotes": 0,
"incentivized": true,
"incentiveType": "SWEEPSTAKES",
"campaign": "SPRING2021",
"orderId": null,
"catalogItems": [
{
"sku": "1234567",
"title": "Dinner Jacket",
"url": "www.sample.com/products/Dinner Jacket",
"category": null,
"reviewCount": 1,
"ratingCount": 1,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 0
},
"active": true,
"attributes": [
{
"type": "Product group",
"typeLabel": "Product group",
"values": [
{
"value": "Jackets",
"valueLabel": "Jackets"
}
]
},
{
"type": "Assortment type",
"typeLabel": "Assortment type",
"values": [
{
"value": "Clothing",
"valueLabel": "Clothing"
}
]
},
{
"type": "Age group",
"typeLabel": "Age group",
"values": [
{
"value": "Adult",
"valueLabel": "Adult"
}
]
}
]
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"id": 4,
"code": "Q4",
"label": null,
"value": 4
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Fit",
"id": 7,
"code": "FIT2",
"label": "perfect",
"value": null
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Occasion",
"id": 2,
"code": "OCC2",
"label": "Formal",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 9,
"code": "IMP1",
"label": "Stylish",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 11,
"code": "IMP3",
"label": "Modern",
"value": null
}
],
"media": {
"photo": [
{
"id": 11,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": true,
"dateCreated": "2018-08-30T16:15:44-04:00",
"normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_L1000.jpeg",
"thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_PZ320.jpeg",
"originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1.jpeg",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"video": [
{
"id": 12,
"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-30T16:15:44-04:00",
"tags": []
}
],
"audio": []
},
"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-30T16:22:34-04:00"
}
],
"reviewedDate": "2018-08-30T16:20:32-04:00",
"purchaseDate": null,
"dateCreated": "2018-08-30T16:15:44-04:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 3,
"code": "TALL"
}
]
},
"tags": [
"CSR",
"INA"
]
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No review was found for the specified id (756768685)",
"code": 139
}
]
}Review Vote Down ¶
Review Vote DownPOST/v1.3/reviews/{id}/votedown
Registers a down vote for a review.
Example URI
POST https://api.turnto.com/v1.3/reviews/12345/votedown
URI Parameters
- id
number(required) Example: 12345The ID of the review.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"id": 6,
"rating": 4,
"title": "An awesome jacket!",
"text": "This dinner jacket fits perfects and looks absolutely amazing.",
"textLength": 62,
"locale": "en_US",
"acceptedTermsAndConditions": true,
"csFlag": false,
"inappropriateFlag": false,
"reviewedFlag": true,
"autoModerated": false,
"published": true,
"upVotes": 0,
"downVotes": 1,
"incentivized": true,
"incentiveType": "SWEEPSTAKES",
"campaign": "SPRING2021",
"orderId": null,
"catalogItems": [
{
"sku": "1234567",
"title": "Dinner Jacket",
"url": "www.sample.com/products/Dinner Jacket",
"category": null,
"reviewCount": 1,
"ratingCount": 1,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 0
},
"active": true,
"attributes": [
{
"type": "Product group",
"typeLabel": "Product group",
"values": [
{
"value": "Jackets",
"valueLabel": "Jackets"
}
]
},
{
"type": "Assortment type",
"typeLabel": "Assortment type",
"values": [
{
"value": "Clothing",
"valueLabel": "Clothing"
}
]
},
{
"type": "Age group",
"typeLabel": "Age group",
"values": [
{
"value": "Adult",
"valueLabel": "Adult"
}
]
}
]
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"id": 4,
"code": "Q4",
"label": null,
"value": 4
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Fit",
"id": 7,
"code": "FIT2",
"label": "perfect",
"value": null
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Occasion",
"id": 2,
"code": "OCC2",
"label": "Formal",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 9,
"code": "IMP1",
"label": "Stylish",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 11,
"code": "IMP3",
"label": "Modern",
"value": null
}
],
"media": {
"photo": [
{
"id": 11,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": true,
"dateCreated": "2018-08-30T16:15:44-04:00",
"normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_L1000.jpeg",
"thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_PZ320.jpeg",
"originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1.jpeg",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"video": [
{
"id": 12,
"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-30T16:15:44-04:00",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"audio": []
},
"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-30T16:22:34-04:00"
}
],
"reviewedDate": "2018-08-30T16:20:32-04:00",
"purchaseDate": null,
"dateCreated": "2018-08-30T16:15:44-04:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 3,
"code": "TALL"
}
]
},
"tags": [
"CSR",
"INA"
]
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No review was found for the specified id (756768685)",
"code": 139
}
]
}Flag Review ¶
Flag ReviewPOST/v1.3/reviews/{id}/flag
Flag a review as inappropriate.
Example URI
POST https://api.turnto.com/v1.3/reviews/12345/flag
URI Parameters
- id
number(required) Example: 12345The ID of the review.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"id": 6,
"rating": 4,
"title": "An awesome jacket!",
"text": "This dinner jacket fits perfects and looks absolutely amazing.",
"textLength": 62,
"locale": "en_US",
"acceptedTermsAndConditions": true,
"csFlag": false,
"inappropriateFlag": true,
"reviewedFlag": true,
"autoModerated": false,
"published": true,
"upVotes": 0,
"downVotes": 0,
"incentivized": true,
"incentiveType": "SWEEPSTAKES",
"campaign": "SPRING2021",
"orderId": null,
"catalogItems": [
{
"sku": "1234567",
"title": "Dinner Jacket",
"url": "www.sample.com/products/Dinner Jacket",
"category": null,
"reviewCount": 1,
"ratingCount": 1,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 0
},
"active": true,
"attributes": [
{
"type": "Product group",
"typeLabel": "Product group",
"values": [
{
"value": "Jackets",
"valueLabel": "Jackets"
}
]
},
{
"type": "Assortment type",
"typeLabel": "Assortment type",
"values": [
{
"value": "Clothing",
"valueLabel": "Clothing"
}
]
},
{
"type": "Age group",
"typeLabel": "Age group",
"values": [
{
"value": "Adult",
"valueLabel": "Adult"
}
]
}
]
}
],
"dimensions": [
{
"type": 1,
"dimensionId": 1,
"dimensionLabel": "Overall Quality",
"id": 4,
"code": "Q4",
"label": null,
"value": 4
},
{
"type": 2,
"dimensionId": 2,
"dimensionLabel": "Fit",
"id": 7,
"code": "FIT2",
"label": "perfect",
"value": null
},
{
"type": 3,
"dimensionId": 3,
"dimensionLabel": "Occasion",
"id": 2,
"code": "OCC2",
"label": "Formal",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 9,
"code": "IMP1",
"label": "Stylish",
"value": null
},
{
"type": 4,
"dimensionId": 4,
"dimensionLabel": "Impression",
"id": 11,
"code": "IMP3",
"label": "Modern",
"value": null
}
],
"media": {
"photo": [
{
"id": 11,
"type": "photo",
"caption": "so cool!",
"imageType": "jpeg",
"width": 108,
"height": 109,
"locale": "en_US",
"published": true,
"dateCreated": "2018-08-30T16:15:44-04:00",
"normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_L1000.jpeg",
"thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1_PZ320.jpeg",
"originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/C18B4785A9FC03E7C6C35BE946FA7354_1535660143525_1.jpeg",
"ipViolationFlag": false,
"inappropriateFlag": false,
"offensiveFlag": false,
"spamFlag": false,
"offTopicFlag": false,
"tags": []
}
],
"video": [
{
"id": 12,
"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-30T16:15:44-04:00",
"tags": []
}
],
"audio": []
},
"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-30T16:22:34-04:00"
}
],
"reviewedDate": "2018-08-30T16:20:32-04:00",
"purchaseDate": null,
"dateCreated": "2018-08-30T16:15:44-04:00",
"user": {
"nickName": "Andy",
"firstName": "Andrew",
"lastName": "Adams",
"emailAddress": "aa.89812@mymail.com",
"externalId": null,
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 2,
"badge": null,
"shopperProfiles": [
{
"id": 3,
"code": "TALL"
}
]
},
"tags": [
"CSR",
"INA"
]
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No review was found for the specified id (145454)",
"code": 139
}
]
}Review Form Submission ¶
Review Form SubmissionGET/v1.3/reviews/formsubmission/{id}
This endpoint will return details of a review email form submission that failed validation. The required form submission is identified by its ID.
Example URI
GET https://api.turnto.com/v1.3/reviews/formsubmission/12345
URI Parameters
- id
number(required) Example: 12345The unique identifier for the form submission.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"rating": 4,
"title": "These are terrific!",
"text": "These are the best widgets ever. Really amazing quality.",
"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,
}],
"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"]
}
],
"dateCreated": "2015-09-28T15:30:46-04:00",
"user": {
"city": "Springfield",
"state": "OH",
"country": "US",
"ageRange": 1,
"shopperProfiles": [
{
"id": 1,
"value": "Nice style"
}
]
}
}Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Form submission not found",
"code": 199
}
]
}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.3/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
POST https://api.turnto.com/v1.3/reviews/12345/responses
URI Parameters
- reviewId
number(required) Example: 12345The ID of the review response.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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
}
}Response
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Response text too long.",
"code": 207
}
]
}Update Review Response ¶
Update Review ResponsePOST/v1.3/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
POST https://api.turnto.com/v1.3/reviews/12345/responses/4321
URI Parameters
- reviewId
number(required) Example: 12345The ID of the review.
- id
number(required) Example: 4321The ID of the review response.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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
}
}Response
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Response text too long.",
"code": 207
}
]
}Delete Review Response ¶
Delete Review ResponseDELETE/v1.3/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
DELETE https://api.turnto.com/v1.3/reviews/12345/responses/4321?email=andrew@sample.com
URI Parameters
- 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.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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.3/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
GET https://api.turnto.com/v1.3/sellerratings?publishedOnly=true&locale=en_US&rating=4&suppressUserPII=false&limit=10&offset=10&sort=rating:asc
URI Parameters
- publishedOnly
boolean(optional) Default: true Example: trueIf true, only return published seller ratings.
Choices:
truefalse- 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:
truefalse- limit
number(optional) Default: 50 Example: 10Maximum 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:descdateCreated:ascrating:descrating:asc
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}
}
]
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Missing or invalid parameters user",
"code": 114
}
]
}Create Seller Rating ¶
Create Seller RatingPOST/v1.3/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
POST https://api.turnto.com/v1.3/sellerratings
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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.21.10 (KHTML, like Gecko) Mobile/7B405",
"turntoTrackingToken": ""
}Response
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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": []
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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.3/sellerratings/summary
This endpoint returns summary details for seller ratings associated with your site.
Example URI
GET https://api.turnto.com/v1.3/sellerratings/summary
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"ratingCount": 255,
"averageRating": 4.5,
"ratingBreakdown": {
"1": 11,
"2": 5,
"3": 3,
"4": 85,
"5": 153
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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.3/articles{?externalId,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.
If externalId is supplied, this endpoint will return a single article identified by its external ID.
Example URI
GET https://api.turnto.com/v1.3/articles?externalId=X12345&sku=12345&publishedOnly=true&locale=en_US&limit=10&offset=10&sort=dateCreated:desc
URI Parameters
- externalId
string(optional) Example: X12345The external ID of the article. If supplied other parameters are ignored.
- 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:
truefalse- locale
string(optional) Example: en_USOnly return articles for this locale.
- limit
number(optional) Default: 50 Example: 10Maximum 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
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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",
"active": true
}
]
},
{
"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",
"active": true
},
{
"sku": "2",
"title": "The Matrix",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
"category": "movies",
"active": true
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
"category": "movies",
"active": true
}
]
},
{
"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",
"active": true
}
]
}
],
"offset": null,
"limit": null,
"total": 3
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Missing or invalid parameters sku",
"code": 114
}
]
}Article Detail ¶
Article DetailGET/v1.3/articles/{id}
This endpoint will return a single article identified by its ID.
Example URI
GET https://api.turnto.com/v1.3/articles/12345
URI Parameters
- id
number(required) Example: 12345The ID of the article.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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",
"active": true
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
"category": "movies",
"active": true
},
{
"sku": "11112222",
"title": "MultiChef",
"url": "www.topchef.com/food-processors/multichef",
"category": "processors",
"active": true
}
]
}Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No article was found for the specified id (12292929)",
"code": 154
}
]
}Update Article ¶
Update ArticlePOST/v1.3/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
POST https://api.turnto.com/v1.3/articles
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaBody
{
"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
}Response
201Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.3/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",
"active": true
},
{
"sku": "2",
"title": "The Matrix",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
"category": "movies",
"active": true
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
"category": "movies",
"active": true
}
]
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Missing Required Fields (title)",
"code": 108
}
]
}Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No article was found for the specified id (398239892)",
"code": 154
}
]
}Delete Article ¶
Delete ArticleDELETE/v1.3/articles/{id}
An authorization token is required to delete an article. The article is identified by its unique ID.
Example URI
DELETE https://api.turnto.com/v1.3/articles/1234
URI Parameters
- id
number(required) Example: 1234The ID of the article.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "No article was found for the specified id (2)",
"code": 154
}
]
}Delete Article By External ID ¶
Delete Article By External IDDELETE/v1.3/articles{?externalId}
An authorization token is required to delete an article. The article is identified by its external ID.
Example URI
DELETE https://api.turnto.com/v1.3/articles?externalId=X12345
URI Parameters
- externalId
string(required) Example: X12345The external ID of the article.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Response
404Headers
Content-Type: application/json;charset=UTF-8Body
{
"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[].code | string | Customer defined code used to identify a shopper profile |
| shopperProfiles[].value | string | Free-form text value |
Forget User ¶
Forget UserPOST/v1.3/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
POST https://api.turnto.com/v1.3/users/forget?email=sample@turnto.com
URI Parameters
string(required) Example: sample@turnto.comThe email of the shopper.
Request
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Invalid Email Address",
"code": 128
}
]
}User UGC ¶
User UGCGET/v1.3/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
GET https://api.turnto.com/v1.3/users?email=andrew@sample.com&userId=7654321&ugcType=question&questionsOnly=false&questionsAnsweredOnly=false&answersOnly=false&commentsOnly=false&reviewsOnly=false&includeNested=false&publishedOnly=true
URI Parameters
string(optional) Example: andrew@sample.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:
questionquestion-answeredanswerreviewcommentall- questionsOnly
boolean(optional) Default: false Example: falseIf true only return questions content.
Choices:
truefalse- questionsAnsweredOnly
boolean(optional) Default: false Example: falseIf questionsAnsweredOnly istrue only return questions answered content.
Choices:
truefalse- answersOnly
boolean(optional) Default: false Example: falseIf true only return answers content.
Choices:
truefalse- commentsOnly
boolean(optional) Default: false Example: falseIf true only return comments content.
Choices:
truefalse- reviewsOnly
boolean(optional) Default: false Example: falseIf true only return reviews content.
Choices:
truefalse- includeNested
boolean(optional) Default: false Example: falseOption to include nested content.
Choices:
truefalse- publishedOnly
boolean(optional) Default: true Example: trueIf true, only return published content.
Choices:
truefalse
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"user": {
"firstName": "Bill",
"lastName": "Mee",
"nickName": "Bill M.",
"externalId": null,
"email": "bm@sample.com",
"city": "Memphis",
"state": "TN",
"country": "US",
"ageRange": 2,
"shopperProfiles": [
{
"id": 2,
"code": "AVG"
}
]
},
"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,
"active": true
}
],
"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,
"active": true
}
],
"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
},
"catalogItems": [
{
"sku": "FP12653",
"title": "Blendomatic 5000",
"url": "http://www.homegadgetsandmore.com/blendomatic",
"category": null,
"active": true
}
],
"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,
"shopperProfiles": [
{
"id": 2,
"code": "AVG"
}
]
},
"catalogItems": [
{
"sku": "FP17268",
"title": "Melon Slicer",
"url": "http://www.homegadgetsandmore.com/melonslicer",
"category": null,
"active": true
}
],
"tags": []
}
]
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Invalid Email Address",
"code": 128
}
]
}Unreviewed Purchases ¶
Unreviewed PurchasesGET/v1.3/users/unreviewed{?email,userId,orderId,orderDateFrom,suppressUserPII,limit,offset,sort}
This endpoint can be used to return details of user purchases that have not yet been reviewed. The user is identified using either email address or external ID.
Details of user purchases are extracted from user orders previously uploaded to TurnTo. Ordered products for which the user has not provided a review will be included in the returned results. If an unreviewed product was purchased multiple times then only the most recent purchase is included.
Customers may exclude purchases that have ‘aged out’. To return only user purchases ordered after a specific date the ‘orderDateFrom’ parameter should be used.
Options are available to sort results to suit the needs of the customer’s application. Purchased products can be sorted by fields such as orderDate, price, and reviewCount. If no sort fields are specified then by default results will be sorted according to a ‘most in need of review’ algorithm that favors high value items, items with few reviews, and recently purchased items.
Pagination of results is supported via the ‘limit’ and ‘offset’ parameters.
Example URI
GET https://api.turnto.com/v1.3/users/unreviewed?email=a@a.com&userId=7654321&orderId=ORD02949&orderDateFrom=2015-09-14T23:59:59-04:00&suppressUserPII=false&limit=10&offset=10&sort=orderDate:desc
URI Parameters
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.
- orderId
string(optional) Example: ORD02949If supplied only include purchases for this order.
- orderDateFrom
date(optional) Example: 2015-09-14T23:59:59-04:00Only return purchases with an order date on or after this date.
- suppressUserPII
boolean(optional) Default: false Example: falseIf true, all user fields will be returned null. The nested blocks shopperProfiles and badge are not affected.
Choices:
truefalse- limit
number(optional) Default: 50 Example: 10Maximum number of purchased products to return.
- offset
number(optional) Default: 0 Example: 10Offset into purchased products results. Zero based so first result is offset = 0.
- sort
string(optional) Example: orderDate:descField to sort purchased products by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.
Choices:
orderDatepricereviewCount
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"purchasedProducts": [
{
"orderId": "ORD-32333",
"orderDate": "2017-08-30T15:36:19-04:00",
"price": 29.99,
"currency": "US",
"catalogItem": {
"sku": "HM100020",
"title": "Printed porcelain cup",
"url": "www.stuff.com/printed_porcelain_cup",
"imgId": 1,
"imageUrl": "www.stuff.com/img/printed_porcelain_cup",
"category": null,
"reviewCount": 0,
"ratingCount": 0,
"averageRating": null,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 0,
"5": 0
},
"active": true,
"attributes": [
{
"type": "Size",
"typeLabel": "Size",
"values": [
{
"value": "Medium",
"valueLabel": "Medium"
}
]
},
{
"type": "Color",
"typeLabel": "Color",
"values": [
{
"value": "Red",
"valueLabel": "Red"
}
]
}
],
"dimensions": [
{
"id": 1,
"sortOrder": 1,
"label": "True to size",
"type": 2,
"required": false,
"average": null,
"values": [
{
"id": 1,
"code": "TTS1",
"sortOrder": 0,
"label": "Small"
},
{
"id": 2,
"code": "TTS2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 3,
"code": "TTS3",
"sortOrder": 2,
"label": "Large"
}
]
},
{
"id": 2,
"sortOrder": 2,
"label": "Fit",
"type": 2,
"required": false,
"average": null,
"values": [
{
"id": 4,
"code": "FIT1",
"sortOrder": 0,
"label": "Tight"
},
{
"id": 5,
"code": "FIT2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 6,
"code": "FIT3",
"sortOrder": 2,
"label": "Relaxed"
}
]
},
{
"id": 3,
"sortOrder": 3,
"label": "Length",
"type": 2,
"required": false,
"average": null,
"values": [
{
"id": 7,
"code": "LEN1",
"sortOrder": 0,
"label": "Short"
},
{
"id": 8,
"code": "LEN2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 9,
"code": "LEN3",
"sortOrder": 2,
"label": "Long"
}
]
},
{
"id": 4,
"sortOrder": 4,
"label": "Width",
"type": 2,
"required": false,
"average": null,
"values": [
{
"id": 10,
"code": "WID1",
"sortOrder": 0,
"label": "Narrow"
},
{
"id": 11,
"code": "WID2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 12,
"code": "WID3",
"sortOrder": 2,
"label": "Wide"
}
]
}
],
"userSettings": {
"shopperProfiles": [
{
"name": "bodyType",
"label": "Body Type",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 1,
"label": "Slim",
"hidden": false,
"sortOrder": 0,
"code": "BOD1"
},
{
"id": 2,
"label": "Athletic",
"hidden": false,
"sortOrder": 1,
"code": "BOD2"
},
{
"id": 3,
"label": "Average",
"hidden": false,
"sortOrder": 2,
"code": "BOD3"
},
{
"id": 4,
"label": "Broad",
"hidden": false,
"sortOrder": 3,
"code": "BOD4"
},
{
"id": 5,
"label": "Plus Size",
"hidden": false,
"sortOrder": 4,
"code": "BOD5"
}
]
},
{
"name": "skinType",
"label": "Skin Type",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 6,
"label": "Normal",
"hidden": false,
"sortOrder": 0,
"code": "SKN1"
},
{
"id": 7,
"label": "Oily",
"hidden": false,
"sortOrder": 1,
"code": "SKN1"
},
{
"id": 8,
"label": "Combination",
"hidden": false,
"sortOrder": 2,
"code": "SKN2"
},
{
"id": 9,
"label": "Dry",
"hidden": false,
"sortOrder": 3,
"code": "SKN3"
},
{
"id": 10,
"label": "Teenage",
"hidden": false,
"sortOrder": 4,
"code": "SKN4"
},
{
"id": 11,
"label": "Sensitive",
"hidden": false,
"sortOrder": 5,
"code": "SKN5"
}
]
},
{
"name": "skinTone",
"label": "Skin Tone",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 12,
"label": "Fair",
"hidden": false,
"sortOrder": 0,
"code": "TON1"
},
{
"id": 13,
"label": "Light",
"hidden": false,
"sortOrder": 1,
"code": "TON2"
},
{
"id": 14,
"label": "Medium",
"hidden": false,
"sortOrder": 2,
"code": "TON3"
},
{
"id": 15,
"label": "Tanned",
"hidden": false,
"sortOrder": 3,
"code": "TON4"
},
{
"id": 16,
"label": "Dark",
"hidden": false,
"sortOrder": 4,
"code": "TON5"
}
]
},
{
"name": "height",
"label": "Height",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 17,
"label": "< 155 cm",
"hidden": false,
"sortOrder": 0,
"code": "HGT1"
},
{
"id": 18,
"label": "155-160 cm",
"hidden": false,
"sortOrder": 1,
"code": "HGT1"
},
{
"id": 19,
"label": "165-170 cm",
"hidden": false,
"sortOrder": 2,
"code": "HGT2"
},
{
"id": 20,
"label": "170-175 cm",
"hidden": false,
"sortOrder": 3,
"code": "HGT3"
},
{
"id": 21,
"label": "175-180 cm",
"hidden": false,
"sortOrder": 4,
"code": "HGT4"
},
{
"id": 22,
"label": "180-185 cm",
"hidden": false,
"sortOrder": 5,
"code": "HGT5"
},
{
"id": 23,
"label": "185-190 cm",
"hidden": false,
"sortOrder": 6,
"code": "HGT6"
},
{
"id": 24,
"label": "190-195 cm",
"hidden": false,
"sortOrder": 7,
"code": "HGT7"
}
]
}
]
}
}
},
{
"orderId": "ORD-32333",
"orderDate": "2017-08-30T15:36:19-04:00",
"price": 59.99,
"currency": "US",
"catalogItem": {
"sku": "HM100030",
"title": "Sweatshirt with pompoms",
"url": "www.stuff.com/sweatshirt_with_pompoms",
"imgId": 1,
"imageUrl": "www.stuff.com/img/sweatshirt_with_pompoms",
"category": null,
"reviewCount": 1,
"ratingCount": 1,
"averageRating": 4,
"ratingBreakdown": {
"1": 0,
"2": 0,
"3": 0,
"4": 1,
"5": 0
},
"active": true,
"attributes": [
{
"type": "Size",
"typeLabel": "Size",
"values": [
{
"value": "Medium",
"valueLabel": "Medium"
}
]
},
{
"type": "Color",
"typeLabel": "Color",
"values": [
{
"value": "Blue",
"valueLabel": "Blue"
}
]
}
],
"dimensions": [
{
"id": 1,
"sortOrder": 1,
"label": "True to size",
"type": 2,
"required": false,
"average": null,
"values": [
{
"id": 1,
"code": "TTS1",
"sortOrder": 0,
"label": "Small"
},
{
"id": 2,
"code": "TTS2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 3,
"code": "TTS3",
"sortOrder": 2,
"label": "Large"
}
]
},
{
"id": 2,
"sortOrder": 2,
"label": "Fit",
"type": 2,
"required": false,
"average": null,
"values": [
{
"id": 4,
"code": "FIT1",
"sortOrder": 0,
"label": "Tight"
},
{
"id": 5,
"code": "FIT2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 6,
"code": "FIT3",
"sortOrder": 2,
"label": "Relaxed"
}
]
},
{
"id": 3,
"sortOrder": 3,
"label": "Length",
"type": 2,
"required": false,
"average": null,
"values": [
{
"id": 7,
"code": "LEN1",
"sortOrder": 0,
"label": "Short"
},
{
"id": 8,
"code": "LEN2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 9,
"code": "LEN3",
"sortOrder": 2,
"label": "Long"
}
]
},
{
"id": 4,
"sortOrder": 4,
"label": "Width",
"type": 2,
"required": false,
"average": null,
"values": [
{
"id": 10,
"code": "WID1",
"sortOrder": 0,
"label": "Narrow"
},
{
"id": 11,
"code": "WID2",
"sortOrder": 1,
"label": "Spot on"
},
{
"id": 12,
"code": "WID3",
"sortOrder": 2,
"label": "Wide"
}
]
}
],
"userSettings": {
"shopperProfiles": [
{
"name": "bodyType",
"label": "Body Type",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 1,
"label": "Slim",
"hidden": false,
"sortOrder": 0,
"code": "BOD1"
},
{
"id": 2,
"label": "Athletic",
"hidden": false,
"sortOrder": 1,
"code": "BOD2"
},
{
"id": 3,
"label": "Average",
"hidden": false,
"sortOrder": 2,
"code": "BOD3"
},
{
"id": 4,
"label": "Broad",
"hidden": false,
"sortOrder": 3,
"code": "BOD4"
},
{
"id": 5,
"label": "Plus Size",
"hidden": false,
"sortOrder": 4,
"code": "BOD5"
}
]
},
{
"name": "skinType",
"label": "Skin Type",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 6,
"label": "Normal",
"hidden": false,
"sortOrder": 0,
"code": "SKN1"
},
{
"id": 7,
"label": "Oily",
"hidden": false,
"sortOrder": 1,
"code": "SKN1"
},
{
"id": 8,
"label": "Combination",
"hidden": false,
"sortOrder": 2,
"code": "SKN2"
},
{
"id": 9,
"label": "Dry",
"hidden": false,
"sortOrder": 3,
"code": "SKN3"
},
{
"id": 10,
"label": "Teenage",
"hidden": false,
"sortOrder": 4,
"code": "SKN4"
},
{
"id": 11,
"label": "Sensitive",
"hidden": false,
"sortOrder": 5,
"code": "SKN5"
}
]
},
{
"name": "skinTone",
"label": "Skin Tone",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 12,
"label": "Fair",
"hidden": false,
"sortOrder": 0,
"code": "TON1"
},
{
"id": 13,
"label": "Light",
"hidden": false,
"sortOrder": 1,
"code": "TON2"
},
{
"id": 14,
"label": "Medium",
"hidden": false,
"sortOrder": 2,
"code": "TON3"
},
{
"id": 15,
"label": "Tanned",
"hidden": false,
"sortOrder": 3,
"code": "TON4"
},
{
"id": 16,
"label": "Dark",
"hidden": false,
"sortOrder": 4,
"code": "TON5"
}
]
},
{
"name": "height",
"label": "Height",
"type": 0,
"hidden": false,
"required": false,
"collectDuringContentSubmit": true,
"displayPublic": true,
"values": [
{
"id": 17,
"label": "< 155 cm",
"hidden": false,
"sortOrder": 0,
"code": "HGT1"
},
{
"id": 18,
"label": "155-160 cm",
"hidden": false,
"sortOrder": 1,
"code": "HGT1"
},
{
"id": 19,
"label": "165-170 cm",
"hidden": false,
"sortOrder": 2,
"code": "HGT2"
},
{
"id": 20,
"label": "170-175 cm",
"hidden": false,
"sortOrder": 3,
"code": "HGT3"
},
{
"id": 21,
"label": "175-180 cm",
"hidden": false,
"sortOrder": 4,
"code": "HGT4"
},
{
"id": 22,
"label": "180-185 cm",
"hidden": false,
"sortOrder": 5,
"code": "HGT5"
},
{
"id": 23,
"label": "185-190 cm",
"hidden": false,
"sortOrder": 6,
"code": "HGT6"
},
{
"id": 24,
"label": "190-195 cm",
"hidden": false,
"sortOrder": 7,
"code": "HGT7"
}
]
}
]
}
}
}
],
"offset": 0,
"limit": 50,
"total": 2,
"user": {
"nickName": "Bob J.",
"firstName": "Bob",
"lastName": "Jones",
"emailAddress": "bob.47453@mymail.com",
"externalId": null,
"city": null,
"state": null,
"country": null,
"ageRange": null,
"badge": null,
"shopperProfiles": []
}
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"errors": [
{
"message": "Invalid Email Address",
"code": 128
}
]
}Search ¶
UGC Search ¶
UGC SearchGET/v1.3/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
GET https://api.turnto.com/v1.3/search?q=stew&sku=12345,22222,33333&ugcType=question,answer&related=false&includeRelated=false&publishedOnly=true&minRating=1&maxRating=4&mostRecent=false&locale=en_US&tags=CSR,DAM&dateCreatedFrom=2016-07-01T10:00:00-04:00&dateCreatedTo=2016-07-02T10:00:00-04:00&limit=10&offset=0
URI Parameters
- 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:
questionanswerreviewcommentarticleall- 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:
truefalse- 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:
truefalse- publishedOnly
boolean(optional) Default: true Example: trueIf true, only return published results.
Choices:
truefalse- 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:
truefalse- 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: 10Maximum 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.
Request
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwyaResponse
200Headers
Content-Type: application/json;charset=UTF-8Body
{
"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",
"active": true
}
],
"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",
"active": true
},
{
"sku": "3",
"title": "Purple Rain",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
"active": true
},
{
"sku": "5",
"title": "Other6",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=5",
"active": true
},
{
"sku": "6",
"title": "Other7",
"url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=6",
"active": true
}
],
"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",
"active": true
}
],
"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",
"active": true
}
],
"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",
"active": true
}
],
"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",
"active": true
}
],
"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,
"active": true
}
],
"tags": []
}
]
}Response
400Headers
Content-Type: application/json;charset=UTF-8Body
{
"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.
2/15/21 - Photos endpoint
A new Photos endpoint returns a list of photos for an SKU, optionally sorted by date created.
2/15/21 - New Media filter keyword
Media filter keywords for photos and videos have been added to the filter parameter. If the options to include filters are set to true, the Review List response will include filter sections for photos and videos.
10/13/20 - Flag Media
A new Flag Media endpoint is used to flag visual content as inappropriate. The endpoint includes a parameter to indicate a reason for flagging: Spam, Intellectual Property, Violation, or Off-topic.
10/13/20 - Include incentiveType and campaign parameters
Two optional parameters (incentiveType) and (campaign) have been added to the Create Review endpoint to identify the type of incentive or campaign a review is part of. The incentiveType cannot be identified when the incentivized parameter is false, but campaign can exist independently of incentiveType OR incentivized parameters.
10/13/20 - Syndication properties added to Questions, Answers and Replies
Questions, Answers, and Replies endpoints now include the optional resource properties to identify the syndication source name (syndication.sourceName) and web address (syndication.siteUrl).
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 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.
08/20/20 - Create Review device fingerprint and custom data properties added
Properties, (deviceFingerprint) and (customData), were added to the Create Review endpoint. The deviceFingerprint property captures a unique ID associated with a device. The customData property passes a JSON object with key-value pairs.
Comment List ¶
/v1.3/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:
truefalsestring(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: 10Maximum 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:
dateCreatedtexttextLengthHeaders
Content-Type: application/x-www-form-urlencodedAuthorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
200Headers
Content-Type: application/json;charset=UTF-8Body
{ "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", "catalogItems": [ { "sku": "11112222", "title": "MultiChef", "url": "www.topchef.com/food-processors/multichef", "active": true } ], "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", "catalogItems": [ { "sku": "11112222", "title": "MultiChef", "url": "www.topchef.com/food-processors/multichef", "active": true } ], "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", "catalogItems": [ { "sku": "11112222", "title": "MultiChef", "url": "www.topchef.com/food-processors/multichef", "active": true } ], "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 }400Headers
Content-Type: application/json;charset=UTF-8Body
{ "errors": [ { "message": "Missing or invalid parameters sku", "code": 114 } ] }