Back to top

TurnTo API v1.2

New Version Released

All endpoints for API v1.2 are now prefixed by /v1.2 rather than the previous /v1.1 prefix. The URL returned by create endpoints as a Location header likewise has a /v1.2 prefix.

A summary of updates is listed below:

Product Attributes Support

The Update Product endpoint has been enhanced to allow product attributes to be specified for a catalog item.

Product attributes are individual items of information about a product that go beyond a simple product description, such as size, color, or age group.

Each product attribute is defined as having a type and one or more values, such as Age Group: Youth, Adult.

The product attribute types and values are specified for a product using the JSON formatted ‘attributes’ field.

Note: This feature is not enabled by default. Please contact TurnTo support to configure this option for your site.

Review List Advanced Filtering

Advanced filtering has been added to the Review List endpoint that is used to obtain reviews associated with a particular product or a group of related products.

A new filter script language provides the ability to drill down deeper into review results using properties such as rating, dimensions, shopper profiles, and product attributes.

Details of available filters for the review results may now optionally be included in the response. The new ‘filters’ block contains possible filter values and a count of how many reviews the value applies to.

Unreviewed Purchases Endpoint

A new endpoint to obtain Unreviewed Purchases for a user has been added. The response contains a list of user purchases that have not yet been reviewed. Embedded with each purchased product are details of any dimensions and shopper profiles to be captured with a new review.

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.

Note that when using a locale parameter in a request to an endpoint that accepts it, like /products/ugc_summary, only text values that are localizable, like subdimension labels will be returned in the requested language. Values that are decimal numbers are represented with a ‘.’ as decimal point.

Moderation

Content moderation and expert answering is handled through the TurnTo.com Customer Portal.

Emails and Notifications

Emails and notifications are triggered by the TurnTo active outreach engine to either TurnTo’s ESP or a third party.

RESTful Services

Read

The HTTP GET method is used to retrieve resources. Parameters are passed as encoded values in the URL Query String.

Example:

https://api.turnto.com/v1.2/questions?sku=12345&related=false&publishedOnly=true&limit=10&offset=20

A successful response is returned as a UTF-8 JSON representation with an HTTP response code of 200 (OK).

Content-Type: application/json;charset=UTF-8

Create

The HTTP POST method is used to create resources. Parameters are passed as a UTF-8 JSON representation in the request body.

Content-Type: application/json;charset=UTF-8

A successful response is returned as a UTF-8 JSON representation with an HTTP response code of 201 (Created) and the ‘Location’ header containing link to the newly created resource.

Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.2/questions/{id}

Update (Operation)

The HTTP POST method is used to perform certain operations (such as voteup).

Example:

https://api.turnto.com/v1.2/questions/12345/voteup

A successful response to a resource operation request is returned as a UTF-8 JSON representation with an HTTP response code of 200 (OK).

Content-Type: application/json;charset=UTF-8

API Rate Limiting

The purpose of API Rate Limiting is to ensure efficient use of system resources and prevent excessive usage from negatively impacting the overall system performance.

Requests to the API are subject to a default limit of 50 requests per second for each site key. If API rate limit is exceeded then a HTTP response code of 429 (Too Many Requests) is returned.

How to Get Started

Step 1: Establish a test account and API key with TurnTo Customer Support

Step 2: Upload test data feeds for order history, product catalog (or use API)

Step 3: Visit http://developers.turnto.com for API documentation resources

Response Codes

When a request cannot be processed successfully a response is returned as a block of JSON containing the error code and an error message.

{"errors": [{
       "message": "Unknown access_token",
       "code": 115
    }]}

A list of all error codes are shown in the table below:

Code Message Description HTTP Status
101 Invalid sort parameter format The supplied sort parameter did not have the correct format. 400
102 Invalid field in sort parameter One or more fields in the supplied sort parameter were not valid. 400
103 Invalid limit or offset The limit or offset was not numeric. 400
104 Offset was out of range The offset was less than zero or greater than or equal to the total number of result set rows. 400
105 Limit was out of range The limit was less than zero. 400
106 No catalog item found for SKU () The SKU was not found in the catalog. 400
107 No question was found for the specified ID () A question with the specified ID could not be found. 404
108 Missing Required Fields Fields were missing for a create or update. 400
109 Catalog item not found for one or more supplied SKUs One of the supplied SKUs was not found in the catalog. 400
110 Please do not include links to other sites A link to another site was included in the supplied text. 400
111 Failed to save the question An unknown error occurred while attempting to save the question. 500
112 Invalid client_id or client_secret Client ID / Client Secret combination is not valid. 403
113 Unknown grant_type Invalid grant_type. 400
114 Missing or invalid parameters client_secret, grant_type The client_secret and/or grant_type was missing or invalid. 400
115 Unknown access_token Access token missing or incorrect for invalidate_token service. 400
116 Missing Authorization header OAuth2 token not present. 403
117 Invalid access token OAuth2 token invalid. 403
118 Error while generating access_token Server error. 500
119 Error while invalidating access_token Server error. 400
120 $$$$ method not allowed for this request type The requested method is not allowed for this request type. 405
121 Failed to save answer An unknown error occurred while attempting to save the answer. 500
122 Too many SKUs requested There is a maximum of 25 UGC counts that can be returned in a single request. 400
123 No comment was found for the specified ID () A comment with the specified ID could not be found. 400
124 Failed to save the comment An unknown error occurred while attempting to save the comment. 500
125 Too many SKUs attached to question The maximum number of SKUs (catalog items) for a question was exceeded. Maximum is 10. 400
126 Limit too large. Max is 100 The maximum limit for pagination was exceeded. Maximum is 100. 400
127 Failed to save the reply An unknown error occurred while attempting to save the reply. 500
128 Invalid email address The format of the email address is invalid. 400
129 Unknown email address The email address was not a match for any user. 400
130 Unknown external ID The external id was not a match for any user. 400
131 Bad search filters At least one of the search filter parameters has an invalid value, or a required filter parameter is missing 400
132 No answer was found for the specified ID () An answer with the specified ID could not be found. 404
133 No reply was found for the specified ID () A reply with the specified ID could not be found. 404
134 No replies found for the specified answer id () No replies found for the specified answer ID () 400
135 Error parsing JSON properties Error parsing JSON properties. 400
136 Must specify at least one catalog item Must specify at least one catalog item. 400
137 One or more duplicate SKUs At least one SKU is duplicated in the catalog items section. 400
138 Too many SKUs attached to answer The maximum number of SKUs (catalog items) for an answer was exceeded. Maximum is 10. 400
139 No review was found for the specified ID () A review with the specified ID could not be found. 404
140 Failed to save the review An unknown error occurred while attempting to save the review. 500
141 Review rating must be between 1 and 5 The review rating must be between 1 and 5. 400
142 Review 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 () and SKU () 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

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 R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya

As required by OAuth 2.0, every request must be made over SSL (HTTPS). If a request is made over HTTP, the API will return a 403 response error.

Your site can only have one valid 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 access token before each API call and doing so may harm performance.

Obtain Access Token

Obtain Access Token
POST/v1.2/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.2/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.2/oauth2/token
URI Parameters
HideShow
client_id
string (required) Example: aaa-aaa

The site key.

client_secret
string (required) Example: bbb-bbb

The site secret.

grant_type
string (required) 

The type of credentials. Must be ‘client_credentials’.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
client_id=[yourSiteKey]&client_secret=[yourAuthKey]&grant_type=client_credentials
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "token_type": "bearer",
  "access_token": "R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya"
}
Response  403
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Invalid client_id or client_secret",
      "code": 112
    }
  ]
}

Invalidate Access Token

Invalidate Access Token
POST/v1.2/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.2/oauth2/invalidate_token
URI Parameters
HideShow
client_id
string (required) Example: aaa-aaa

The site key.

client_secret
string (required) Example: bbb-bbb

The site secret.

access_token
string (required) 

The access token.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
client_id=[your_site_key]&client_secret=[your_auth_key]&access_token=[your_access_token]
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Unknown access_token",
      "code": 115
    }
  ]
}

Sites

A number of site configuration settings may be accessed using the TurnTo API. This includes user settings that control which additional user information is to be collected and displayed. Site user settings are considered applicable to all products.

Resource Properties - User Settings

User Settings contains definitions of information to be collected for a user when reviewing a product. Settings for the predefined profiles age range and city/state are included if profile is enabled. A list of any active shopper profiles is also included.

Property Type Description
ageRange.hidden boolean Include age range input on review submission form
ageRange.required boolean Age range is required with content submission
ageRange.collectDuringContentSubmit boolean Age range to be collected during content submission.
ageRange.displayPublic boolean Display age range with user content
cityState.hidden boolean Include user location input on review submission form
cityState.required boolean User location is required with content submission
cityState.collectDuringContentSubmit boolean User location to be collected during content submission
cityState.displayPublic boolean Display user location with user content
shopperProfiles resource List of shopper profiles definitions

Resource Properties - Shopper Profile

Shopper Profiles are defined by the site administrator and used to capture additional information relating to a user. E.g. Height, Body Type.

Property Type Description
name string Name of profile
label string Localized label
type number Profile type: 0 = select, 1 = free-form text
hidden boolean
required boolean Profile value is required with content submission
collectDuringContentSubmit boolean Profile value to be collected during content submission
displayPublic boolean Display profile value with user content
values[].id number Identifier for a profile value
values[].label string Localized label
values[].hidden boolean
values[].sortOrder number Sort order of profile values

Site Settings

The site settings contains information on how the site is configured.

Site Settings
GET/v1.2/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.2/sites?locale=en_US
URI Parameters
HideShow
locale
string (optional) Example: en_US

Labels will be returned in target locale. If omitted use site default.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
    userSettings: {
              "ageRange": {
                  "hidden": false,
                  "required": true,
                  "collectDuringContentSubmit": true,
                  "displayPublic": false
              },
              "cityState": {
                  "hidden": false,
                  "required": true,
                  "collectDuringContentSubmit": false,
                  "displayPublic": true
               },
              "shopperProfiles": [
                 {
                    "name": "level",
                    "label": "Level",
                    "type": 0,
                    "hidden": false,
                    "required": true,
                    "collectDuringContentSubmit": true,
                    "displayPublic": true,
                    "values":       [
                                {
                          "id": 1,
                          "label": "Head Chef",
                          "hidden": false,
                          "sortOrder": 0
                       },
                                {
                          "id": 2,
                          "label": "Sous Chef",
                          "hidden": false,
                          "sortOrder": 1
                       },
                                {
                          "id": 3,
                          "label": "Line Chef",
                          "hidden": false,
                          "sortOrder": 2
                       }
                    ]
                 },
                 {
                    "name": "signature",
                    "label": "Signature Dish",
                    "type": 1,
                    "hidden": false,
                    "required": true,
                    "collectDuringContentSubmit": true,
                    "displayPublic": true,
                    "values": [      {
                       "id": 4,
                       "label": "Signature Dish",
                       "hidden": false,
                       "sortOrder": 0
                    }]
                 }]

}
}

Products

A product is a catalog item which is identified by a SKU in your catalog.

Resource Properties - Product

Property Type Description
sku string Unique catalog identifier for this product
title string Name of the product
url string Web page for this product
dimensions resource Rating sub-dimensions associated with this product
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[].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 List
GET/v1.2/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.2/products?sku=12345,22222,33333&locale=en_US
URI Parameters
HideShow
sku
string (required) Example: 12345,22222,33333

Comma separated list of SKUs to return product information for. Maximum is 25.

locale
string (optional) Example: en_US

Return product information for this locale. If omitted use site default.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
[
  {
    "sku": "700285064826",
    "title": "Oakley XX Frame Accessory Kit - Black",
    "url": "http://www.testtt.info/tt4_2/responsivesite/qaOverlay-reviewsEmbed.php?sku=700285064826",
    "dimensions": [
      {
        "id": 1,
        "label": "Overall Quality",
        "type": 1,
        "required": true,
        "average": 1,
        "values": [
          {
            "id": 1,
            "value": 1
          },
          {
            "id": 2,
            "value": 2
          },
          {
            "id": 3,
            "value": 3
          },
          {
            "id": 4,
            "value": 4
          },
          {
            "id": 5,
            "value": 5
          }
        ]
      },
      {
        "id": 2,
        "label": "Comfort",
        "type": 2,
        "required": true,
        "average": 2,
        "values": [
          {
            "id": 6,
            "sortOrder": 0,
            "label": "Low"
          },
          {
            "id": 7,
            "sortOrder": 1,
            "label": "Medium"
          },
          {
            "id": 8,
            "sortOrder": 2,
            "label": "High"
          }
        ]
      },
      {
        "id": 3,
        "label": "Impression",
        "type": 4,
        "required": false,
        "average": null,
        "values": [
          {
            "id": 9,
            "sortOrder": 0,
            "label": "Durable",
            "count": 0
          },
          {
            "id": 10,
            "sortOrder": 1,
            "label": "Stylish",
            "count": 1
          },
          {
            "id": 11,
            "sortOrder": 2,
            "label": "Modern",
            "count": 0
          },
          {
            "id": 12,
            "sortOrder": 3,
            "label": "Youthful",
            "count": 0
          }
        ]
      },
      {
        "id": 4,
        "label": "Weight",
        "type": 3,
        "required": false,
        "average": null,
        "values": [
          {
            "id": 13,
            "sortOrder": 0,
            "label": "Light",
            "count": 1
          },
          {
            "id": 14,
            "sortOrder": 1,
            "label": "Heavy",
            "count": 0
          }
        ]
      }
    ],
    "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,
            "value": 1
          },
          {
            "id": 2,
            "value": 2
          },
          {
            "id": 3,
            "value": 3
          },
          {
            "id": 4,
            "value": 4
          },
          {
            "id": 5,
            "value": 5
          }
        ]
      },
      {
        "id": 2,
        "label": "Comfort",
        "type": 2,
        "required": true,
        "average": null,
        "values": [
          {
            "id": 6,
            "sortOrder": 0,
            "label": "Low"
          },
          {
            "id": 7,
            "sortOrder": 1,
            "label": "Medium"
          },
          {
            "id": 8,
            "sortOrder": 2,
            "label": "High"
          }
        ]
      },
      {
        "id": 3,
        "label": "Impression",
        "type": 4,
        "required": false,
        "average": null,
        "values": [
          {
            "id": 9,
            "sortOrder": 0,
            "label": "Durable",
            "count": 0
          },
          {
            "id": 10,
            "sortOrder": 1,
            "label": "Stylish",
            "count": 0
          },
          {
            "id": 11,
            "sortOrder": 2,
            "label": "Modern",
            "count": 0
          },
          {
            "id": 12,
            "sortOrder": 3,
            "label": "Youthful",
            "count": 0
          }
        ]
      },
      {
        "id": 4,
        "label": "Weight",
        "type": 3,
        "required": false,
        "average": null,
        "values": [
          {
            "id": 13,
            "sortOrder": 0,
            "label": "Light",
            "count": 0
          },
          {
            "id": 14,
            "sortOrder": 1,
            "label": "Heavy",
            "count": 0
          }
        ]
      }
    ],
    "attributes": [
      {
        "type": "Size",
        "typeLabel": "Size",
        "values": [
          {
            "value": "Medium",
            "valueLabel": "Medium"
          }
        ]
      },
      {
        "type": "Color",
        "typeLabel": "Color",
        "values": [
          {
            "value": "Blue",
            "valueLabel": "Blue"
          }
        ]
      }
    ]
  }
]
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Too many SKUs requested. Maximum is 25.",
      "code": 122
    }
  ]
}

UGC Summary

The UGC (User Generated Content) summary is a collection of data points relating to a particular catalog item, such as number of questions, number of reviews, average rating.

Resource Properties - UGC Summary

Property Type Description
sku string Unique catalog identifier for this product
questions number Number of questions for this product
relatedQuestions number Number of related questions for this product
comments number Number of comments for this product
answers number Number of answers for this product
relatedAnswers number Number of related answers for this product
reviews number Number of reviews for this product
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
userSettings resource User information that can be captured for this product. Nested user settings block - see Sites section

UGC Summary
GET/v1.2/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.2/products/ugc_summary?sku=12345,22222,33333&locale=en_US
URI Parameters
HideShow
sku
string (required) Example: 12345,22222,33333

Comma separated list of SKUs to return UGC counts for. Maximum is 25.

locale
string (optional) Example: en_US

Return product information for this locale. If omitted use site default.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"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,
                "sortOrder":0,
                "label":"Small"
            },
            {
                "id":2,
                "sortOrder":1,
                "label":"Spot on"
            },
            {
                "id":3,
                "sortOrder":2,
                "label":"Large"
            }
        ]
    },
    {
        "id":2,
        "sortOrder":2,
        "label":"Fit",
        "type":2,
        "required":false,
        "average":2,
        "values":[
            {
                "id":4,
                "sortOrder":0,
                "label":"Tight"
            },
            {
                "id":5,
                "sortOrder":1,
                "label":"Spot on"
            },
            {
                "id":6,
                "sortOrder":2,
                "label":"Relaxed"
            }
        ]
    },
    {
        "id":3,
        "sortOrder":3,
        "label":"Length",
        "type":2,
        "required":false,
        "average":1,
        "values":[
            {
                "id":7,
                "sortOrder":0,
                "label":"Short"
            },
            {
                "id":8,
                "sortOrder":1,
                "label":"Spot on"
            },
            {
                "id":9,
                "sortOrder":2,
                "label":"Long"
            }
        ]
    },
    {
        "id":4,
        "sortOrder":4,
        "label":"Width",
        "type":2,
        "required":false,
        "average":1,
        "values":[
            {
                "id":10,
                "sortOrder":0,
                "label":"Narrow"
            },
            {
                "id":11,
                "sortOrder":1,
                "label":"Spot on"
            },
            {
                "id":12,
                "sortOrder":2,
                "label":"Wide"
            }
        ]
    }
],
"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
                },
                {
                    "id":2,
                    "label":"Athletic",
                    "hidden":false,
                    "sortOrder":1
                },
                {
                    "id":3,
                    "label":"Average",
                    "hidden":false,
                    "sortOrder":2
                },
                {
                    "id":4,
                    "label":"Broad",
                    "hidden":false,
                    "sortOrder":3
                },
                {
                    "id":5,
                    "label":"Plus Size",
                    "hidden":false,
                    "sortOrder":4
                }
            ]
        },
        {
            "name":"skinType",
            "label":"Skin Type",
            "type":0,
            "hidden":false,
            "required":false,
            "collectDuringContentSubmit":true,
            "displayPublic":true,
            "values":[
                {
                    "id":6,
                    "label":"Normal",
                    "hidden":false,
                    "sortOrder":0
                },
                {
                    "id":7,
                    "label":"Oily",
                    "hidden":false,
                    "sortOrder":1
                },
                {
                    "id":8,
                    "label":"Combination",
                    "hidden":false,
                    "sortOrder":2
                },
                {
                    "id":9,
                    "label":"Dry",
                    "hidden":false,
                    "sortOrder":3
                },
                {
                    "id":10,
                    "label":"Teenage",
                    "hidden":false,
                    "sortOrder":4
                },
                {
                    "id":11,
                    "label":"Sensitive",
                    "hidden":false,
                    "sortOrder":5
                }
            ]
        },
        {
            "name":"skinTone",
            "label":"Skin Tone",
            "type":0,
            "hidden":false,
            "required":false,
            "collectDuringContentSubmit":true,
            "displayPublic":true,
            "values":[
                {
                    "id":12,
                    "label":"Fair",
                    "hidden":false,
                    "sortOrder":0
                },
                {
                    "id":13,
                    "label":"Light",
                    "hidden":false,
                    "sortOrder":1
                },
                {
                    "id":14,
                    "label":"Medium",
                    "hidden":false,
                    "sortOrder":2
                },
                {
                    "id":15,
                    "label":"Tanned",
                    "hidden":false,
                    "sortOrder":3
                },
                {
                    "id":16,
                    "label":"Dark",
                    "hidden":false,
                    "sortOrder":4
                }
            ]
        },
        {
            "name":"height",
            "label":"Height",
            "type":0,
            "hidden":false,
            "required":false,
            "collectDuringContentSubmit":true,
            "displayPublic":true,
            "values":[
                {
                    "id":17,
                    "label":"< 155 cm",
                    "hidden":false,
                    "sortOrder":0
                },
                {
                    "id":18,
                    "label":"155-160 cm",
                    "hidden":false,
                    "sortOrder":1
                },
                {
                    "id":19,
                    "label":"165-170 cm",
                    "hidden":false,
                    "sortOrder":2
                },
                {
                    "id":20,
                    "label":"170-175 cm",
                    "hidden":false,
                    "sortOrder":3
                },
                {
                    "id":21,
                    "label":"175-180 cm",
                    "hidden":false,
                    "sortOrder":4
                },
                {
                    "id":22,
                    "label":"180-185 cm",
                    "hidden":false,
                    "sortOrder":5
                },
                {
                    "id":23,
                    "label":"185-190 cm",
                    "hidden":false,
                    "sortOrder":6
                },
                {
                    "id":24,
                    "label":"190-195 cm",
                    "hidden":false,
                    "sortOrder":7
                }
            ]
        }
    ]
}
},
{
"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":null,
        "values":[
            {
                "id":1,
                "sortOrder":0,
                "label":"Small"
            },
            {
                "id":2,
                "sortOrder":1,
                "label":"Spot on"
            },
            {
                "id":3,
                "sortOrder":2,
                "label":"Large"
            }
        ]
    },
    {
        "id":2,
        "sortOrder":2,
        "label":"Fit",
        "type":2,
        "required":false,
        "average":null,
        "values":[
            {
                "id":4,
                "sortOrder":0,
                "label":"Tight"
            },
            {
                "id":5,
                "sortOrder":1,
                "label":"Spot on"
            },
            {
                "id":6,
                "sortOrder":2,
                "label":"Relaxed"
            }
        ]
    },
    {
        "id":3,
        "sortOrder":3,
        "label":"Length",
        "type":2,
        "required":false,
        "average":null,
        "values":[
            {
                "id":7,
                "sortOrder":0,
                "label":"Short"
            },
            {
                "id":8,
                "sortOrder":1,
                "label":"Spot on"
            },
            {
                "id":9,
                "sortOrder":2,
                "label":"Long"
            }
        ]
    },
    {
        "id":4,
        "sortOrder":4,
        "label":"Width",
        "type":2,
        "required":false,
        "average":null,
        "values":[
            {
                "id":10,
                "sortOrder":0,
                "label":"Narrow"
            },
            {
                "id":11,
                "sortOrder":1,
                "label":"Spot on"
            },
            {
                "id":12,
                "sortOrder":2,
                "label":"Wide"
            }
        ]
    }
],
"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
                },
                {
                    "id":2,
                    "label":"Athletic",
                    "hidden":false,
                    "sortOrder":1
                },
                {
                    "id":3,
                    "label":"Average",
                    "hidden":false,
                    "sortOrder":2
                },
                {
                    "id":4,
                    "label":"Broad",
                    "hidden":false,
                    "sortOrder":3
                },
                {
                    "id":5,
                    "label":"Plus Size",
                    "hidden":false,
                    "sortOrder":4
                }
            ]
        },
        {
            "name":"skinType",
            "label":"Skin Type",
            "type":0,
            "hidden":false,
            "required":false,
            "collectDuringContentSubmit":true,
            "displayPublic":true,
            "values":[
                {
                    "id":6,
                    "label":"Normal",
                    "hidden":false,
                    "sortOrder":0
                },
                {
                    "id":7,
                    "label":"Oily",
                    "hidden":false,
                    "sortOrder":1
                },
                {
                    "id":8,
                    "label":"Combination",
                    "hidden":false,
                    "sortOrder":2
                },
                {
                    "id":9,
                    "label":"Dry",
                    "hidden":false,
                    "sortOrder":3
                },
                {
                    "id":10,
                    "label":"Teenage",
                    "hidden":false,
                    "sortOrder":4
                },
                {
                    "id":11,
                    "label":"Sensitive",
                    "hidden":false,
                    "sortOrder":5
                }
            ]
        },
        {
            "name":"skinTone",
            "label":"Skin Tone",
            "type":0,
            "hidden":false,
            "required":false,
            "collectDuringContentSubmit":true,
            "displayPublic":true,
            "values":[
                {
                    "id":12,
                    "label":"Fair",
                    "hidden":false,
                    "sortOrder":0
                },
                {
                    "id":13,
                    "label":"Light",
                    "hidden":false,
                    "sortOrder":1
                },
                {
                    "id":14,
                    "label":"Medium",
                    "hidden":false,
                    "sortOrder":2
                },
                {
                    "id":15,
                    "label":"Tanned",
                    "hidden":false,
                    "sortOrder":3
                },
                {
                    "id":16,
                    "label":"Dark",
                    "hidden":false,
                    "sortOrder":4
                }
            ]
        },
        {
            "name":"height",
            "label":"Height",
            "type":0,
            "hidden":false,
            "required":false,
            "collectDuringContentSubmit":true,
            "displayPublic":true,
            "values":[
                {
                    "id":17,
                    "label":"< 155 cm",
                    "hidden":false,
                    "sortOrder":0
                },
                {
                    "id":18,
                    "label":"155-160 cm",
                    "hidden":false,
                    "sortOrder":1
                },
                {
                    "id":19,
                    "label":"165-170 cm",
                    "hidden":false,
                    "sortOrder":2
                },
                {
                    "id":20,
                    "label":"170-175 cm",
                    "hidden":false,
                    "sortOrder":3
                },
                {
                    "id":21,
                    "label":"175-180 cm",
                    "hidden":false,
                    "sortOrder":4
                },
                {
                    "id":22,
                    "label":"180-185 cm",
                    "hidden":false,
                    "sortOrder":5
                },
                {
                    "id":23,
                    "label":"185-190 cm",
                    "hidden":false,
                    "sortOrder":6
                },
                {
                    "id":24,
                    "label":"190-195 cm",
                    "hidden":false,
                    "sortOrder":7
                }
            ]
        }
    ]
}
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Too many SKUs requested. Maximum is 25.",
      "code": 122
    }
  ]
}

Update Product

Update product information.

Update Product
POST/v1.2/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.2/products
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "sku": "11112222",
  "title": "Bananas",
  "url": "www.fruit.com/bananas",
  "imageUrl": "www.fruit.com/img/banana.jpg",
  "currency": "USD",
  "price": "109.99",
  "active": true,
  "category": "fruit",
  "categoryPath": "",
  "keywords": "fruit,yellow",
  "inStock": true,
  "virtualParentCode": "BAN",
  "isCategory": false,
  "members": "",
  "brand": "",
  "mpn": "",
  "isbn": "",
  "upc": "",
  "ean": "",
  "jan": "",
  "asin": "",
  "mobileItemUrl": "",
  "attributes": "{\"Color\": [\"Red\"],\"Size\": [\"Medium\"]}",
  "localeData": "{\"fr_CA\": {\"title\": \"Bleu Chemise\", \"itemUrl\": \"http://domain.com/pathToFrenchProductPage\"} }"
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "sku": "11112222"
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Invalid field (price)",
      "code": 145
    }
  ]
}

Orders

An order is a record of a customer purchase on your site. The order consists of order information, customer contact details, and a list of line items for each product purchased.

Resource Properties - Order

Property Type Description
orderId string Unique order ID
deliveryDate date Date of delivery
postalCode string Order postal code
emailOptOut boolean User opted out of receiving emails
user resource
items resource list order items

Resource Properties - Order Item

Property Type Description
lineItemId string Identifier for the line item
title string Product title
url string Product URL
sku string Product sku
brand string Product brand
price number Line item amount
itemImageUrl string Item image URL

Create Order

Creates an order representing a customer purchase. The order may contain multiple order lines.

Create Order
POST/v1.2/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.2/orders/create
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "orderId": "99977",
  "deliveryDate": "2015-05-20",
  "locale": "en_US",
  "postalCode": "10667",
  "emailOptOut": false,
  "user": {
    "firstName": "Andy",
    "lastName": "Adamson",
    "nickName": "",
    "emailAddress": "andrew@sample.com",
    "externalId": null
  },
  "items": [
    {
      "lineItemId": "1",
      "title": "Sneakers",
      "url": "www.treadzzzzz.com/sneakers",
      "sku": "BF0010020",
      "brand": "Sprinter",
      "price": "29.99",
      "itemImageUrl": "www.treadzzzzz.com/img/sneakers.jpg"
    },
    {
      "lineItemId": "2",
      "title": "Cleats",
      "url": "www.treadzzzzz.com/cleats",
      "sku": "BF0020080",
      "brand": "Hoofer",
      "price": "49.99",
      "itemImageUrl": "www.treadzzzzz.com/img/cleats.jpg"
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 3317217,
  "orderId": "99977"
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Invalid delivery date",
      "code": 146
    }
  ]
}

Cancel Order

Cancel Order
POST/v1.2/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.2/orders/cancel
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "orderId": "99977",
  "sku": ""
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Order not cancelled",
      "code": 148
    }
  ]
}

Media

Media is a UGC type that includes photos, videos, and audio that can be created for a user. A media content item must be associated with at least one catalog item when it is created.

Photos

Photo images are sent as Base64 binary encoded data in request body JSON properties. The maximum size of an image is 10MB.

Valid image MIME types are:

  • image/jpeg

  • image/jpg

  • image/pjpeg

  • image/png

  • image/x-png

After photos have been uploaded, the images are resized and transferred to a web accessible location.

The following image sizes will be generated:

Key Description
PZ320 Scales down the lesser of the width and height to be 320 then hides the difference in the other dimension by cropping on each side
L560 Scales down the larger of the width and height to be 560
L1000 Scales down the larger of the width and height to be 1000
L1800 Scales down the larger of the width and height to be 1800
LH720 Scales the height to be 720 up to maximum width of 1280
LW600 Scales the width to be 600 up to maximum height of 10000

The key can be appended to the image name of the ‘originalUrl’ and used to display a resized image with the corresponding format and dimensions. For example, to display the small size image “L560” the image name would be modified as follows: <originalImage>_L560.<imageType>

The resized images are available once processing has completed.

Until processing has completed the ‘normalUrl’ property will return a URL for the raw uploaded image and the ‘thumbnailUrl’ property will return null.

Videos

Videos are specified by using the video URL link. Currently, all videos must be hosted by YouTube and set to Public.

Information allowing the video to be embedded on customer site is retrieved and made available in the Media properties.

Audio

Audio is not currently supported.

Resource Properties - Media

Property Type Description
id number TurnTo unique ID for this media
caption string Caption
type string Media type (photo,video,audio)
width number Image width
height number Image height
imageType string Image type (jpeg, jpg, png)
normalUrl string Normal image URL
thumbnailUrl string Thumbnail image/video URL
originalUrl string Original image URL
provider string Video service provider
providedLink string Video URL
thumbnailWidth string Video thumbnail width
thumbnailHeight string Video thumbnail height
authorName string Video author name
authorUrl string Video author URL
providerId string Video provider ID
html string Video html
authorName string Video author name
tags string List of tag codes associated with this media
user resource The user that created this media content. Nested user block - see Users section
catalogItems resource Products 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 Media
POST/v1.2/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. For video, the URL link must be supplied which is then verified with the video provider. Up to 5 media types 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.2/media
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "locale": "en_US",
  "catalogItems": [
    {
      "sku": "sku0207644428",
      "title": "zzz tablet",
      "url": "www.zzz.com/tablet"
    }
  ],
  "user": {
    "nickName": "Andy",
    "firstName": "Andrew",
    "lastName": "Adams",
    "emailAddress": "andrew@sample.com"
  },
  "photo": [
    {
      "caption": "so cool!",
      "b64data": "data:image/jpeg;base64,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"
    }
  ],
  "video": [
    {
      "caption": "build customer community",
      "url": "https://www.youtube.com/watch?v=Vr_r2uBg56g"
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "media": {
    "photo": [
      {
        "id": 2,
        "type": "photo",
        "caption": "so cool!",
        "imageType": "jpeg",
        "width": 108,
        "height": 109,
        "locale": "en_US",
        "published": false,
        "dateCreated": null,
        "normalUrl": "http://www.turnto.com/imagestore/media/temp/6AACB0D7BB7A1DC9AE8455D6690A86F5_1535487113608_1.jpeg",
        "thumbnailUrl": null,
        "originalUrl": "http://www.turnto.com/imagestore/media/temp/6AACB0D7BB7A1DC9AE8455D6690A86F5_1535487113608_1.jpeg",
        "tags": []
      }
    ],
    "video": [
      {
        "id": 3,
        "type": "video",
        "caption": "build customer community",
        "provider": "youtube",
        "providedLink": "https://www.youtube.com/watch?v=Vr_r2uBg56g",
        "thumbnailUrl": "https://i.ytimg.com/vi/Vr_r2uBg56g/hqdefault.jpg",
        "thumbnailWidth": 480,
        "thumbnailHeight": 360,
        "width": 480,
        "height": 270,
        "authorName": "TurnTo",
        "authorUrl": "https://www.youtube.com/user/TurnToNetworks",
        "providerId": "Vr_r2uBg56g",
        "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/Vr_r2uBg56g?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen></iframe>",
        "s88thumbDims": {
          "width": 117,
          "height": 88,
          "scaledTo": "h",
          "targetLeft": -15,
          "targetTop": 0
        },
        "s64thumbDims": {
          "width": 85,
          "height": 64,
          "scaledTo": "h",
          "targetLeft": -11,
          "targetTop": 0
        },
        "locale": "en_US",
        "published": false,
        "dateCreated": null,
        "tags": []
      }
    ],
    "audio": []
  }
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No catalog item found for sku (5558886554)",
      "code": 106
    }
  ]
}

User Media List

User Media List
GET/v1.2/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.2/media?userId=EXT12345&email=andrew@sample.com&sku=12345
URI Parameters
HideShow
userId
string (optional) Example: EXT12345

External ID of the user.

email
string (optional) Example: andrew@sample.com

The email address of the user.

sku
string (optional) Example: 12345

The SKU to filter media by.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "media": {
    "photo": [
      {
        "id": 1,
        "type": "photo",
        "caption": "so cool!",
        "imageType": "jpeg",
        "width": 108,
        "height": 109,
        "locale": "en_US",
        "published": false,
        "dateCreated": "2018-08-28T16:09:11-04:00",
        "normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/5C11B3371CEACE00A7DBBDEDA9360E17_1535486950501_1_L1000.jpeg",
        "thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/5C11B3371CEACE00A7DBBDEDA9360E17_1535486950501_1_PZ320.jpeg",
        "originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/5C11B3371CEACE00A7DBBDEDA9360E17_1535486950501_1.jpeg",
        "tags": []
      }
    ],
    "video": [
      {
        "id": 2,
        "type": "video",
        "caption": "build customer community",
        "provider": "youtube",
        "providedLink": "https://www.youtube.com/watch?v=Vr_r2uBg56g",
        "thumbnailUrl": "https://i.ytimg.com/vi/Vr_r2uBg56g/hqdefault.jpg",
        "thumbnailWidth": 480,
        "thumbnailHeight": 360,
        "width": 480,
        "height": 270,
        "authorName": "TurnTo",
        "authorUrl": "https://www.youtube.com/user/TurnToNetworks",
        "providerId": "Vr_r2uBg56g",
        "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/Vr_r2uBg56g?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen></iframe>",
        "s88thumbDims": {
          "width": 117,
          "height": 88,
          "scaledTo": "h",
          "targetLeft": -15,
          "targetTop": 0
        },
        "s64thumbDims": {
          "width": 85,
          "height": 64,
          "scaledTo": "h",
          "targetLeft": -11,
          "targetTop": 0
        },
        "locale": "en_US",
        "published": false,
        "dateCreated": "2018-08-28T16:11:54-04:00",
        "tags": []
      }
    ],
    "audio": []
  }
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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 List
GET/v1.2/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.2/photos?sku=12345&publishedOnly=true&tags=CSR,DAM,SOT&locale=en_US&limit=50&offset=10&sort=dateCreated:desc
URI Parameters
HideShow
sku
string (required) Example: 12345

The SKU of the catalog item that includes the photo.

includeRelated
boolean (optional) Default: false Example: false

If true, also return photos for related SKUs.

Choices: true false

publishedOnly
boolean (optional) Default: true Example: true

If true, only return published photos.

Choices: true false

tags
string (optional) Example: CSR,DAM,SOT

Only return photos that contain at least 1 of the comma separated tag codes.

locale
string (optional) Example: en_US

Only return photos for this locale.

limit
number (optional) Default: 50 Example: 50

Maximum number of photos to show.

offset
number (optional) Default: 0 Example: 10

Offset into photo results. Zero based, so first result is offset = 0.

sort
string (optional) Default: dateCreated:desc Example: dateCreated:desc

Field to sort photos by. Valid directions are: asc and desc.

Choices: dateCreated:desc dateCreated:asc

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{"errors": [{
"message": "Invalid limit or offset",
"code": 103
}]}
{"errors": [{
   "message": "No catalog item was found for sku 7969494",
   "code": 106
}]}

Questions

A question is a UGC type that is tied to a catalog item, which is identified by a SKU in your catalog. A question can contain nested answers.

Resource Properties - Question

Property Type Description
id number TurnTo unique ID for this question
dateCreated date Date question created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
approvedDate date Date question approved (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
text string Question text
textLength number Number of characters in question text
locale string Locale of question
published boolean Is published?
csFlag boolean Is flagged for customer service?
irrelevantFlag boolean Is irrelevant?
unansweredAlert boolean Unanswered alert?
reviewedFlag boolean Is reviewed?
autoModerated boolean Is auto moderated?
flagForExpert boolean Flag for expert?
upVotes number Number of up votes received
isStaff boolean Is staff?
isCategoryQuestion boolean Is category question?
tags string List of tag codes associated with this question
user resource The user that asked this question. Nested user block - see Users section
userIpAddr string The IP address of the UGC author
catalogItems resource Products for which this question was asked. Nested products block - see Products section
answerCount number Number of answers posted for this question
answers resource Answers posted for this question. Nested answers block - see Answers section

Question List

Question List
GET/v1.2/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.2/questions?sku=12345&related=false&publishedOnly=true&tags=CSR,DAM,SOT&locale=en_US&limit=10&offset=10&sort=dateCreated:desc
URI Parameters
HideShow
sku
string (required) Example: 12345

The SKU of the topic catalog item that the returned questions are about.

related
boolean (optional) Default: false Example: false

If true, the questions that are returned will be ones that are related to the SKU, either as Virtual Parent Siblings, or group members, or category members.

Choices: true false

publishedOnly
boolean (optional) Default: true Example: true

If true, only return published questions.

Choices: true false

tags
string (optional) Example: CSR,DAM,SOT

If specified, only return questions that contain at least 1 of the comma separated tag codes.

locale
string (optional) Example: en_US

Only return questions for this locale.

limit
number (optional) Default: 50 Example: 10

Maximum number of questions to show.

offset
number (optional) Default: 0 Example: 10

Offset into question results. Zero based so first result is offset = 0.

sort
string (optional) Default: dateCreated:desc Example: dateCreated:desc

Field to sort questions by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.

Choices: answerCount dateCreated text textLength upVotes

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "questions": [
    {
      "id": 7,
      "dateCreated": "2016-02-08T11:17:16-05:00",
      "approvedDate": null,
      "text": "How many different attachments come with this food processor?",
      "textLength": 61,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "irrelevantFlag": false,
      "unansweredAlert": false,
      "reviewedFlag": false,
      "autoModerated": false,
      "flagForExpert": false,
      "upVotes": 1,
      "isStaff": false,
      "isCategoryQuestion": false,
      "answerCount": 3,
      "answers": [
        {
          "id": 6,
          "dateCreated": "2016-02-08T11:17:18-05:00",
          "reviewedDate": null,
          "text": "It came with 5. 3 for slicing, 2 for puree.",
          "textLength": 43,
          "locale": "en_US",
          "published": false,
          "csFlag": false,
          "inappropriateFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "upVotes": 3,
          "thanked": false,
          "isStaff": false,
          "purchaseDate": null,
          "itemQuestionId": 7,
          "catalogItems": [],
          "replyCount": 1,
          "replies": [
            {
              "id": 2,
              "text": "Thank you so much!",
              "locale": "en_US",
              "published": false,
              "dateCreated": "2016-02-08T14:14:42-05:00",
              "reviewedDate": null,
              "csFlag": false,
              "reviewedFlag": false,
              "autoModerated": true,
              "isStaff": false,
              "parentReplyId": null,
              "parentAnswerId": 6,
              "user": {
                "nickName": "Andrew A.",
                "firstName": "Andrew",
                "lastName": "Adamson",
                "emailAddress": "andrew@sample.com",
                "externalId": null,
                "city": "Dallas",
                "state": "TX",
                "country": "US",
                "ageRange": 2
              },
              "replies": [],
              "replyCount": 0
            }
          ],
          "user": {
            "nickName": "Billy B.",
            "firstName": "Bill",
            "lastName": "Brine",
            "emailAddress": null,
            "externalId": "22222",
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null,
            "badge": null
          },
          "bestAnswer": true,
          "tags": []
        },
        {
          "id": 7,
          "dateCreated": "2016-02-08T11:17:18-05:00",
          "reviewedDate": null,
          "text": "There were no attachments with this item.",
          "textLength": 41,
          "locale": "en_US",
          "published": false,
          "csFlag": false,
          "inappropriateFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "upVotes": 1,
          "thanked": false,
          "isStaff": false,
          "purchaseDate": null,
          "itemQuestionId": 7,
          "catalogItems": [],
          "replyCount": 0,
          "replies": [],
          "user": {
            "nickName": "Chuck C.",
            "firstName": "Chuck",
            "lastName": "Chips",
            "emailAddress": null,
            "externalId": "33333",
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null,
            "badge": null
          },
          "tags": [
            "COM",
            "ALU"
          ]
        },
        {
          "id": 5,
          "dateCreated": "2016-02-08T11:17:17-05:00",
          "reviewedDate": null,
          "text": "Can't remember exactly... might have been 3 or 4.",
          "textLength": 49,
          "locale": "en_US",
          "published": false,
          "csFlag": false,
          "inappropriateFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "upVotes": 0,
          "thanked": false,
          "isStaff": false,
          "purchaseDate": null,
          "itemQuestionId": 7,
          "catalogItems": [],
          "replyCount": 0,
          "replies": [],
          "user": {
            "nickName": "Alan A.",
            "firstName": "Alan",
            "lastName": "Armley",
            "emailAddress": null,
            "externalId": "11111",
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null,
            "badge": null
          },
          "tags": []
        }
      ],
      "user": {
        "nickName": "Andrew A.",
        "firstName": "Andrew",
        "lastName": "Adamson",
        "emailAddress": "andrew@sample.com",
        "externalId": null,
        "city": "Dallas",
        "state": "TX",
        "country": "US",
        "ageRange": 2
      },
      "catalogItems": [
        {
          "sku": "FRSM0987742",
          "title": "Fruit Samarai",
          "url": "http://dev.turntodev.com/products?sku=FRSM0987742",
          "category": null
        }
      ],
      "tags": [
        "SOT",
        "FLF",
        "DAM",
        "BRL"
      ]
    },
    {
      "id": 8,
      "dateCreated": "2016-02-08T11:17:23-05:00",
      "approvedDate": null,
      "text": "How long is the warranty for this product?",
      "textLength": 42,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "irrelevantFlag": false,
      "unansweredAlert": false,
      "reviewedFlag": false,
      "autoModerated": false,
      "flagForExpert": false,
      "upVotes": 0,
      "isStaff": false,
      "isCategoryQuestion": false,
      "answerCount": 0,
      "answers": [],
      "user": {
        "nickName": "Dougie D.",
        "firstName": "Douglas",
        "lastName": "Diamond",
        "emailAddress": "dd@example.com",
        "externalId": null,
        "city": "Portland",
        "state": "OR",
        "country": "US",
        "ageRange": 3
      },
      "catalogItems": [
        {
          "sku": "FRSM0987742",
          "title": "Fruit Samarai",
          "url": "http://dev.turntodev.com/products?sku=FRSM0987742",
          "category": null
        }
      ],
      "tags": []
    }
  ],
  "offset": 0,
  "limit": 50,
  "total": 2
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{"errors": [{
   "message": "Invalid limit or offset",
   "code": 103
}]}

{"errors": [{
   "message": "No catalog item was found for sku 7969494",
   "code": 106
}]}

Question Detail

Question Detail
GET/v1.2/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.2/questions/12345
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the question.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 7,
  "dateCreated": "2016-02-08T11:17:16-05:00",
  "approvedDate": null,
  "text": "How many different attachments come with this food processor?",
  "textLength": 61,
  "locale": "en_US",
  "published": false,
  "csFlag": false,
  "irrelevantFlag": false,
  "unansweredAlert": false,
  "reviewedFlag": false,
  "autoModerated": false,
  "flagForExpert": false,
  "upVotes": 1,
  "isStaff": false,
  "isCategoryQuestion": false,
  "answerCount": 3,
  "answers": [
    {
      "id": 6,
      "dateCreated": "2016-02-08T11:17:18-05:00",
      "reviewedDate": null,
      "text": "It came with 5. 3 for slicing, 2 for puree.",
      "textLength": 43,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "upVotes": 3,
      "thanked": false,
      "isStaff": false,
      "purchaseDate": null,
      "itemQuestionId": 7,
      "catalogItems": [],
      "replyCount": 1,
      "replies": [
        {
          "id": 2,
          "text": "Thank you so much!",
          "locale": "en_US",
          "published": false,
          "dateCreated": "2016-02-08T14:14:42-05:00",
          "reviewedDate": null,
          "csFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "isStaff": false,
          "parentReplyId": null,
          "parentAnswerId": 6,
          "user": {
            "nickName": "Andrew A.",
            "firstName": "Andrew",
            "lastName": "Adamson",
            "emailAddress": "andrew@sample.com",
            "externalId": null,
            "city": "Dallas",
            "state": "TX",
            "country": "US",
            "ageRange": 2
          },
          "replies": [],
          "replyCount": 0
        }
      ],
      "user": {
        "nickName": "Billy B.",
        "firstName": "Bill",
        "lastName": "Brine",
        "emailAddress": null,
        "externalId": "22222",
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null,
        "badge": null
      },
      "tags": [],
      "bestAnswer": true
    },
    {
      "id": 7,
      "dateCreated": "2016-02-08T11:17:18-05:00",
      "reviewedDate": null,
      "text": "There were no attachments with this item.",
      "textLength": 41,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "upVotes": 1,
      "thanked": false,
      "isStaff": false,
      "purchaseDate": null,
      "itemQuestionId": 7,
      "catalogItems": [],
      "replyCount": 0,
      "replies": [],
      "user": {
        "nickName": "Chuck C.",
        "firstName": "Chuck",
        "lastName": "Chips",
        "emailAddress": null,
        "externalId": "33333",
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null,
        "badge": null
      },
      "tags": [
        "COM",
        "ALU"
      ]
    },
    {
      "id": 5,
      "dateCreated": "2016-02-08T11:17:17-05:00",
      "reviewedDate": null,
      "text": "Can't remember exactly... might have been 3 or 4.",
      "textLength": 49,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "upVotes": 0,
      "thanked": false,
      "isStaff": false,
      "purchaseDate": null,
      "itemQuestionId": 7,
      "catalogItems": [],
      "replyCount": 0,
      "replies": [],
      "user": {
        "nickName": "Alan A.",
        "firstName": "Alan",
        "lastName": "Armley",
        "emailAddress": null,
        "externalId": "11111",
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null,
        "badge": null
      },
      "tags": []
    }
  ],
  "user": {
    "nickName": "Andrew A.",
    "firstName": "Andrew",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com",
    "externalId": null,
    "city": "Dallas",
    "state": "TX",
    "country": "US",
    "ageRange": 2
  },
  "catalogItems": [
    {
      "sku": "FRSM0987742",
      "title": "Fruit Samarai",
      "url": "http://dev.turntodev.com/products?sku=FRSM0987742",
      "category": null
    }
  ],
  "tags": [
    "SOT",
    "FLF",
    "DAM",
    "BRL"
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No question was found for the specified id (949494949949)",
      "code": 107
    }
  ]
}

Create Question

Create Question
POST/v1.2/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.2/questions
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "text": "How many different attachments come with this food processor?",
  "locale": "en_US",
  "catalogItems": [
    {
      "sku": "FRSM0987742",
      "title": "Fruit Samarai",
      "url": "http://dev.turntodev.com/products?sku=FRSM0987742"
    }
  ],
  "user": {
    "nickName": "Andrew A.",
    "firstName": "Andrew",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com",
    "city": "Dallas",
    "state": "TX",
    "country": "US",
    "ageRange": 2,
    "shopperProfiles": []
  },
  "userIpAddr": "123.456.789.100"
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.2/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
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No catalog item was found for sku (7969494)",
      "code": 106
    }
  ]
}

Question Vote Up

Question Vote Up
POST/v1.2/questions/{id}/voteup

This endpoint registers an up vote for a question.

Example URI

POST https://api.turnto.com/v1.2/questions/12345/voteup
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the question.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 7,
  "dateCreated": "2016-02-08T11:17:16-05:00",
  "approvedDate": null,
  "text": "How many different attachments come with this food processor?",
  "textLength": 61,
  "locale": "en_US",
  "published": false,
  "csFlag": false,
  "irrelevantFlag": false,
  "unansweredAlert": false,
  "reviewedFlag": false,
  "autoModerated": false,
  "flagForExpert": false,
  "upVotes": 1,
  "isStaff": false,
  "isCategoryQuestion": false,
  "answerCount": 0,
  "answers": [],
  "user": {
    "nickName": "Andrew A.",
    "firstName": "Andrew",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com",
    "externalId": null,
    "city": "Dallas",
    "state": "TX",
    "country": "US",
    "ageRange": 2
  },
  "catalogItems": [
    {
      "sku": "FRSM0987742",
      "title": "Fruit Samarai",
      "url": "http://dev.turntodev.com/products?sku=FRSM0987742",
      "category": null
    }
  ],
  "tags": []
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No question was found for the specified id (145454)",
      "code": 107
    }
  ]
}

Answer More Questions

Answer More Questions
GET/v1.2/amq{?email,userId,sku,locale,questionsOnly,purchasesOnly,limit,offset}

This endpoint supports an API implementation of the “Do More” functionality, also known as Answer More Questions (AMQ).

A “Do More” screen or AMQ box displays after a user has written an answer or a review or clicks the “Do More” link in the TurnTo widget.

It displays products that the user is eligible to review or questions the users may be able to answer. Questions shown are for the current item, related items, and items connected to previous purchases.

The user is identified using either email address or external ID. User identifier can be omitted to obtain questions for anonymous users.

Pagination of questions is supported using the ‘limit’ and ‘offset’ parameters. The boolean property ‘moreQuestions’ is used to indicate if more questions are available.

The ‘questionsOnly’ and ‘purchasesOnly’ parameters can be used to return only questions or purchases respectively.

Example URI

GET https://api.turnto.com/v1.2/amq?email=a@a.com&userId=7654321&sku=12345&locale=en_US&questionsOnly=false&purchasesOnly=false&limit=10&offset=0
URI Parameters
HideShow
email
string (optional) Example: a@a.com

The user’s email address.

userId
string (optional) Example: 7654321

The user’s external ID.

sku
string (required) Example: 12345

The SKU of the current item.

locale
string (optional) Example: en_US

Return results for this locale. If omitted use site default.

questionsOnly
boolean (optional) Default: false Example: false

Only return questions.

Choices: true false

purchasesOnly
boolean (optional) Default: false Example: false

Only return purchases.

Choices: true false

limit
number (optional) Default: 10 Example: 10

Maximum number of questions to return.

offset
number (optional) Default: 0 Example: 0

Offset into question results. Zero based so first result is offset = 0.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "questions": [
    {
      "id": 12,
      "dateCreated": "2016-07-21T14:51:18-04:00",
      "approvedDate": "2016-07-21T14:51:43-04:00",
      "text": "Is this a trilogy?",
      "textLength": 18,
      "locale": "en_US",
      "published": true,
      "csFlag": false,
      "irrelevantFlag": false,
      "unansweredAlert": false,
      "reviewedFlag": true,
      "autoModerated": false,
      "flagForExpert": false,
      "upVotes": 0,
      "isStaff": false,
      "isCategoryQuestion": false,
      "answerCount": 0,
      "answers": [],
      "user": {
        "nickName": "bobby",
        "firstName": "Bob",
        "lastName": "Peterson",
        "emailAddress": "bob@peterson.com",
        "externalId": null,
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null
      },
      "catalogItems": [
        {
          "sku": "2",
          "title": "The Matrix",
          "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
          "category": "movies"
        }
      ]
    },
    {
      "id": 11,
      "dateCreated": "2016-07-21T14:51:17-04:00",
      "approvedDate": "2016-07-21T14:51:44-04:00",
      "text": "Are there DVD extras?",
      "textLength": 21,
      "locale": "en_US",
      "published": true,
      "csFlag": false,
      "irrelevantFlag": false,
      "unansweredAlert": false,
      "reviewedFlag": true,
      "autoModerated": false,
      "flagForExpert": false,
      "upVotes": 0,
      "isStaff": false,
      "isCategoryQuestion": false,
      "answerCount": 0,
      "answers": [],
      "user": {
        "nickName": "Paulie",
        "firstName": "Paul",
        "lastName": "Back",
        "emailAddress": "paul@back.com",
        "externalId": null,
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null
      },
      "catalogItems": [
        {
          "sku": "1",
          "title": "Die Hard 2",
          "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
          "category": "movies"
        }
      ]
    },
    {
      "id": 3,
      "dateCreated": "2013-09-19T16:00:58-04:00",
      "approvedDate": null,
      "text": "What happens at the end?",
      "textLength": 24,
      "locale": "en_US",
      "published": true,
      "csFlag": false,
      "irrelevantFlag": false,
      "unansweredAlert": false,
      "reviewedFlag": true,
      "autoModerated": false,
      "flagForExpert": false,
      "upVotes": 0,
      "isStaff": false,
      "isCategoryQuestion": false,
      "answerCount": 1,
      "answers": [
        {
          "id": 16,
          "dateCreated": "2013-09-22T14:24:05-04:00",
          "reviewedDate": null,
          "text": "Our hero survives",
          "textLength": 17,
          "locale": "en_US",
          "published": true,
          "csFlag": false,
          "inappropriateFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "upVotes": 0,
          "thanked": false,
          "isStaff": true,
          "purchaseDate": null,
          "itemQuestionId": 15,
          "catalogItems": [],
          "replyCount": 0,
          "replies": [],
          "user": {
            "nickName": "buzz",
            "firstName": "Buzz",
            "lastName": "Right",
            "emailAddress": "buzz@right.org",
            "externalId": null,
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null,
            "badge": {
              "text": "Staff",
              "imageUrl": ""
            }
          },
          "bestAnswer": true
        }
      ],
      "user": {
        "nickName": "Bob B.",
        "firstName": "Bob",
        "lastName": "Barker",
        "emailAddress": "isharee2@bbbb.com",
        "externalId": null,
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null
      },
      "catalogItems": [
        {
          "sku": "1",
          "title": "Die Hard 2",
          "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
          "category": "movies"
        }
      ]
    }
  ],
  "moreQuestions": false,
  "purchases": [
    {
      "orderId": "W5249315",
      "sku": "030150 SM",
      "title": "Everlasting Fire Plug 2.25 Inch",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=030150 SM",
      "imgId": 22
    },
    {
      "orderId": "W5249331",
      "sku": "311408 4L",
      "title": "Kong Training Dummy Large",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=311408 4L",
      "imgId": 22
    },
    {
      "orderId": "W5249347",
      "sku": "311066",
      "title": "Kong Bone w/Rope",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=311066",
      "imgId": 22
    },
    {
      "orderId": "W5249366",
      "sku": "492059 5 GLW",
      "title": "Orbee-Tuff Cosmos Ball 5 Inch Luna Glow",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=492059 5 GLW",
      "imgId": 22
    }
  ],
  "user": {
    "nickName": "Andrew A.",
    "firstName": "Andrew",
    "lastName": "Adamson",
    "emailAddress": "spike@dog.org",
    "externalId": null,
    "city": null,
    "state": null,
    "country": null,
    "ageRange": null
  }
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Invalid Email Address",
      "code": 128
    }
  ]
}

Answers

An answer is a UGC type that’s tied to a question, which is identified by a unique identifier. An answer can contain nested replies.

Resource Properties - Answer

Property Type Description
id number TurnTo unique ID for this answer
dateCreated date Date that 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

Question Answers

Question Answers
GET/v1.2/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.2/questions/12345/answers?publishedOnly=&locale=en_US&limit=10&offset=10&sort=dateCreated:desc
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the question.

publishedOnly
boolean (optional) Default: true 

If true, only return published answers.

Choices: true false

locale
string (optional) Example: en_US

Only return answers for this locale.

limit
number (optional) Default: 50 Example: 10

Maximum number of answers to show.

offset
number (optional) Default: 0 Example: 10

Offset into answers results. Zero based so first result is offset = 0.

sort
string (optional) Default: dateCreated:desc Example: dateCreated:desc

Field to sort answers by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.

Choices: dateCreated text textLength upVotes

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "answers": [
    {
      "id": 6,
      "dateCreated": "2016-02-08T11:17:18-05:00",
      "reviewedDate": null,
      "text": "It came with 5. 3 for slicing, 2 for puree.",
      "textLength": 43,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "upVotes": 3,
      "thanked": false,
      "isStaff": false,
      "purchaseDate": null,
      "itemQuestionId": 7,
      "catalogItems": [],
      "replyCount": 0,
      "replies": [],
      "user": {
        "nickName": "Billy B.",
        "firstName": "Bill",
        "lastName": "Brine",
        "emailAddress": null,
        "externalId": "22222",
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null,
        "badge": null
      },
      "bestAnswer": true,
      "tags": []
    },
    {
      "id": 7,
      "dateCreated": "2016-02-08T11:17:18-05:00",
      "reviewedDate": null,
      "text": "There were no attachments with this item.",
      "textLength": 41,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "upVotes": 1,
      "thanked": false,
      "isStaff": false,
      "purchaseDate": null,
      "itemQuestionId": 7,
      "catalogItems": [],
      "replyCount": 0,
      "replies": [],
      "user": {
        "nickName": "Chuck C.",
        "firstName": "Chuck",
        "lastName": "Chips",
        "emailAddress": null,
        "externalId": "33333",
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null,
        "badge": null
      },
      "tags": [
        "COM",
        "ALU"
      ]
    },
    {
      "id": 5,
      "dateCreated": "2016-02-08T11:17:17-05:00",
      "reviewedDate": null,
      "text": "Can't remember exactly... might have been 3 or 4.",
      "textLength": 49,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "upVotes": 0,
      "thanked": false,
      "isStaff": false,
      "purchaseDate": null,
      "itemQuestionId": 7,
      "catalogItems": [],
      "replyCount": 0,
      "replies": [],
      "user": {
        "nickName": "Alan A.",
        "firstName": "Alan",
        "lastName": "Armley",
        "emailAddress": null,
        "externalId": "11111",
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null,
        "badge": null
      },
      "tags": []
    }
  ],
  "offset": 0,
  "limit": 50,
  "total": 3
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No question was found for the specified id (49439)",
      "code": 107
    }
  ]
}

Answer Detail

Answer Detail
GET/v1.2/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.2/answers/12345
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the answer.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 12,
  "dateCreated": "2015-06-25T14:28:57-04:00",
  "reviewedDate": null,
  "text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
  "textLength": 65,
  "locale": "en_US",
  "published": false,
  "csFlag": false,
  "inappropriateFlag": false,
  "reviewedFlag": false,
  "autoModerated": true,
  "upVotes": 0,
  "thanked": false,
  "isStaff": false,
  "purchaseDate": null,
  "itemQuestionId": 18,
  "catalogItems": [],
  "replyCount": 0,
  "replies": [],
  "user": {
    "nickName": "Bob B.",
    "firstName": "Bob",
    "lastName": "Brimmer",
    "emailAddress": null,
    "externalId": "12345",
    "city": "Dallas",
    "state": "TX",
    "country": "US",
    "ageRange": 0,
    "badge": null,
    "shopperProfiles": [
      {
        "id": 4,
        "value": "waffles"
      },
      {
        "id": 1
      }
    ]
  },
  "tags": []
}
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No answer was found for the specified id (949494949949)",
      "code": 132
    }
  ]
}

Create Answer

Create Answer
POST/v1.2/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.2/questions/12345/answers
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the answer.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
  "locale": "en_US",
  "catalogItems": [],
  "user": {
    "nickName": "Bob B.",
    "firstName": "Bob",
    "lastName": "Brimmer",
    "emailAddress": "",
    "externalId": "12345",
    "city": "Dallas",
    "state": "TX",
    "country": "US",
    "ageRange": 0,
    "shopperProfiles": [
      {
        "id": 1
      },
      {
        "id": 4,
        "value": "waffles"
      }
    ]
  },
  "userIpAddr": "123.456.789.100",
  "turntoTrackingToken": "eyJpcXJsSWQiOjEyMzQ1LCJ0dXJudG9RdWVzdGlvbklkIjoiNyIsInR1cm50b0VtYWlsVHlwZSI6InF1ZXN0aW9uIn0%3D"
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.2/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  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No question was found for the specified id (49439)",
      "code": 107
    }
  ]
}

Answer Vote Up

Answer Vote Up
POST/v1.2/answers/{id}/voteup

Registers an up vote for an answer.

Example URI

POST https://api.turnto.com/v1.2/answers/12345/voteup
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the answer.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 12,
  "dateCreated": "2015-06-25T14:28:57-04:00",
  "reviewedDate": null,
  "text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
  "textLength": 65,
  "locale": "en_US",
  "published": false,
  "csFlag": false,
  "inappropriateFlag": false,
  "reviewedFlag": false,
  "autoModerated": true,
  "upVotes": 1,
  "thanked": false,
  "isStaff": false,
  "purchaseDate": null,
  "itemQuestionId": 18,
  "catalogItems": [],
  "replyCount": 0,
  "replies": [],
  "user": {
    "nickName": "Bob B.",
    "firstName": "Bob",
    "lastName": "Brimmer",
    "emailAddress": null,
    "externalId": "12345",
    "city": "Dallas",
    "state": "TX",
    "country": "US",
    "ageRange": 0,
    "badge": null,
    "shopperProfiles": [
      {
        "id": 4,
        "value": "waffles"
      },
      {
        "id": 1
      }
    ]
  },
  "tags": []
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No answer was found for the specified id (145454)",
      "code": 132
    }
  ]
}

Flag Answer

Flag Answer
POST/v1.2/answers/{id}/flag

Flag an answer as inappropriate.

Example URI

POST https://api.turnto.com/v1.2/answers/12345/flag
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the answer.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 12,
  "dateCreated": "2015-06-25T14:28:57-04:00",
  "reviewedDate": null,
  "text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
  "textLength": 65,
  "locale": "en_US",
  "published": false,
  "csFlag": false,
  "inappropriateFlag": true,
  "reviewedFlag": false,
  "autoModerated": true,
  "upVotes": 1,
  "thanked": false,
  "isStaff": false,
  "purchaseDate": null,
  "itemQuestionId": 18,
  "catalogItems": [],
  "replyCount": 0,
  "replies": [],
  "user": {
    "nickName": "Bob B.",
    "firstName": "Bob",
    "lastName": "Brimmer",
    "emailAddress": null,
    "externalId": "12345",
    "city": "Dallas",
    "state": "TX",
    "country": "US",
    "ageRange": 0,
    "badge": null,
    "shopperProfiles": [
      {
        "id": 4,
        "value": "waffles"
      },
      {
        "id": 1
      }
    ]
  },
  "tags": []
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No answer was found for the specified id (145454)",
      "code": 132
    }
  ]
}

Thank Answerer

Thank Answerer
POST/v1.2/answers/{id}/thank

Sends a thank you email to the user who created the answer.

Example URI

POST https://api.turnto.com/v1.2/answers/12345/thank
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the answer.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 12,
  "dateCreated": "2015-06-25T14:28:57-04:00",
  "reviewedDate": null,
  "text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
  "textLength": 65,
  "locale": "en_US",
  "published": false,
  "csFlag": false,
  "inappropriateFlag": false,
  "reviewedFlag": false,
  "autoModerated": true,
  "upVotes": 1,
  "thanked": true,
  "isStaff": false,
  "purchaseDate": null,
  "itemQuestionId": 18,
  "catalogItems": [],
  "replyCount": 0,
  "replies": [],
  "user": {
    "nickName": "Bob B.",
    "firstName": "Bob",
    "lastName": "Brimmer",
    "emailAddress": null,
    "externalId": "12345",
    "city": "Dallas",
    "state": "TX",
    "country": "US",
    "ageRange": 0,
    "badge": null,
    "shopperProfiles": [
      {
        "id": 4,
        "value": "waffles"
      },
      {
        "id": 1
      }
    ]
  },
  "tags": []
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No answer was found for the specified id (145454)",
      "code": 132
    }
  ]
}

Replies

A reply is a UGC type that’s tied to an answer or a previous reply to an answer. A reply can contain nested replies.

Resource Properties - Reply

Property Type Description
id number TurnTo unique ID for this reply
dateCreated date Date that reply was created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
reviewedDate date Date that reply was reviewed by moderator (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
text string Reply text
locale string Locale of reply
published boolean Is published?
csFlag boolean Is flagged for customer service?
reviewedFlag boolean Is reviewed?
autoModerated boolean Is auto moderated?
isStaff boolean Is staff?
user resource The user that posted this reply. Nested user block - see Users section
userIpAddr string The IP address of the UGC author

Answer Replies

Answer Replies
GET/v1.2/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.2/answers/12345/replies?publishedOnly=true&locale=en_US&limit=10&offset=10&sort=textLength
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the answer.

publishedOnly
boolean (optional) Default: true Example: true

If true, only return published replies.

Choices: true false

locale
string (optional) Example: en_US

Only return replies for this locale.

limit
number (optional) Default: 50 Example: 10

Maximum number of replies to show.

offset
number (optional) Default: 0 Example: 10

Offset into replies results. Zero based so first result is offset = 0.

sort
string (optional) Default: dateCreated:desc Example: textLength

Field to sort replies by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.

Choices: dateCreated text textLength

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "replies": [
    {
      "id": 2,
      "text": "Thank you for the advise and I will check them out. Thank you again.",
      "locale": "en_US",
      "published": false,
      "dateCreated": "2011-09-23T13:09:26-04:00",
      "reviewedDate": null,
      "csFlag": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "isStaff": false,
      "user": {
        "nickName": "Andrew A.",
        "firstName": "Andrew",
        "lastName": "Adamson",
        "emailAddress": null,
        "externalId": null
      }
    }
  ],
  "offset": null,
  "limit": null,
  "total": 1
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No answer was found for the specified id (49439)",
      "code": 132
    }
  ]
}

Reply Detail

Reply Detail
GET/v1.2/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.2/replies/12345
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the reply.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 12345,
  "text": "Thank you!",
  "locale": "en_US",
  "published": false,
  "dateCreated": "2013-09-20T09:14:29-04:00",
  "reviewedDate": null,
  "csFlag": false,
  "reviewedFlag": false,
  "autoModerated": true,
  "isStaff": false,
  "parentReplyId": null,
  "parentAnswerId": 3,
  "user": {
    "nickName": "Eric E.",
    "firstName": "Eric",
    "lastName": "Ericsson",
    "emailAddress": "e@e.com",
    "externalId": null
  },
  "replies": []
}
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No reply was found for the specified id (949494949949)",
      "code": 133
    }
  ]
}

Create Reply

Create Reply
POST/v1.2/answers/{id}/replies

Creates a new reply for an existing answer or reply.

A user credential is required to create an reply. For an existing user, the user will be identified either by email address or a unique external ID. If the reply is being created by a new user then the user first and last name must be supplied.

Request body JSON object properties

The properties that are passed during Reply creation are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)

Property Required Note
text Yes
locale No If omitted use site default.
parentReplyId No Provide parentReplyId if this reply is to an earlier reply.
user.firstName Yes
user.lastName Yes
user.nickName No
user.emailAddress No Either email address or externalId is required to identify the user
user.externalId No Either email address or externalId is required to identify the user
user.city No
user.state No
user.country No
user.ageRange No
user.shopperProfiles[].id No
user.shopperProfiles[].value No
userIpAddr No The IP address of the UGC author

Example URI

POST https://api.turnto.com/v1.2/answers/12345/replies
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the reply.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "text": "Thank you so much!",
  "locale": "en_US",
  "parentReplyId": null,
  "user": {
    "nickName": "Andrew A.",
    "firstName": "Andrew",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com"
  },
  "userIpAddr": "123.456.789.100"
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.2/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  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No answer was found for the specified id (49439)",
      "code": 132
    }
  ]
}

Comments

A Comment, also known as a Checkout Comment, is a UGC type that’s tied to a catalog item, which is identified by a SKU in your catalog.

Resource Properties - Comments

Property Type Description
id number TurnTo unique ID for this comment
dateCreated date Date comment created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
text string Comment text
textLength number Number of characters in comment text
locale string Locale of comment
published boolean Is published?
tags string List of tag codes associated with this comment
user resource The user that posted this comment. Nested user block - see Users section
userIpAddr string The IP address of the UGC author
orderId string Unique ID of order associated with this comment
catalogItems resource Product for which this comment was posted. Nested products block - see Products section

Comment List

Comment List
GET/v1.2/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

GET https://api.turnto.com/v1.2/comments?sku=12345&publishedOnly=true&tags=CSR,DAM,SOT&locale=en_US&limit=10&offset=20&sort=textLength:desc
URI Parameters
HideShow
sku
string (required) Example: 12345

The SKU of the topic catalog item that the returned comments are about.

publishedOnly
boolean (optional) Default: true Example: true

If true, only return published comments.

Choices: true false

tags
string (optional) Example: CSR,DAM,SOT

If specified, only return comments that contain at least 1 of the comma separated tag codes.

locale
string (optional) Example: en_US

Only return comments for this locale. If omitted use site default.

limit
number (optional) Default: 50 Example: 10

Maximum number of comments to show.

offset
number (optional) Default: 0 Example: 20

Offset into comments results. Zero based so first result is offset = 0.

sort
string (optional) Default: dateCreated:desc Example: textLength:desc

Field to sort comments by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.

Choices: dateCreated text textLength

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "comments": [
    {
      "id": 8,
      "text": "This is the best Master Chef ever!",
      "locale": "en_US",
      "textLength": 76,
      "published": true,
      "dateCreated": "2015-07-01T09:49:43-04:00",
      "catalogItems": [
        {
          "sku": "11112222",
          "title": "MultiChef",
          "url": "www.topchef.com/food-processors/multichef"
        }
      ],
      "orderId": "5555522",
      "user": {
        "nickName": "Andy A.",
        "firstName": "Andy",
        "lastName": "Adamson",
        "emailAddress": "andrew@sample.com",
        "externalId": null,
        "city": "Miami",
        "state": "FL",
        "country": "US",
        "ageRange": 1
      },
      "tags": []
    },
    {
      "id": 7,
      "text": "I love all the attachments!",
      "locale": "fr_CA",
      "textLength": 160,
      "published": true,
      "dateCreated": "2015-06-30T11:43:06-04:00",
      "catalogItems": [
        {
          "sku": "11112222",
          "title": "MultiChef",
          "url": "www.topchef.com/food-processors/multichef"
        }
      ],
      "orderId": null,
      "user": {
        "nickName": "Andy A.",
        "firstName": "Andy",
        "lastName": "Adamson",
        "emailAddress": "andrew@sample.com",
        "externalId": null,
        "city": "Miami",
        "state": "FL",
        "country": "US",
        "ageRange": 1
      },
      "tags": [
        "CSR"
      ]
    },
    {
      "id": 5,
      "text": "This Master Chef has loads of power and more speeds than you will ever need!",
      "locale": "en_US",
      "textLength": 76,
      "published": true,
      "dateCreated": "2015-06-30T11:43:05-04:00",
      "catalogItems": [
        {
          "sku": "11112222",
          "title": "MultiChef",
          "url": "www.topchef.com/food-processors/multichef"
        }
      ],
      "orderId": null,
      "user": {
        "nickName": "Andy A.",
        "firstName": "Andy",
        "lastName": "Adamson",
        "emailAddress": "andrew@sample.com",
        "externalId": null,
        "city": "Miami",
        "state": "FL",
        "country": "US",
        "ageRange": 1
      },
      "tags": []
    }
  ],
  "offset": null,
  "limit": null,
  "total": 3
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Missing or invalid parameters sku",
      "code": 114
    }
  ]
}

Comment Detail

Comment Detail
GET/v1.2/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.2/comments/12345
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the Comment.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 8,
  "text": "This Master Chef has loads of power and more speeds than you will ever need!",
  "locale": "en_US",
  "textLength": 76,
  "published": true,
  "dateCreated": "2015-07-01T09:49:43-04:00",
  "catalogItems": [
    {
      "sku": "11112222",
      "title": "MultiChef",
      "url": "www.topchef.com/food-processors/multichef"
    }
  ],
  "orderId": "5555522",
  "user": {
    "nickName": "Andy A.",
    "firstName": "Andy",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com",
    "externalId": null,
    "city": "Miami",
    "state": "FL",
    "country": "US",
    "ageRange": 1
  },
  "tags": []
}
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No comment was found for the specified id (12292929)",
      "code": 123
    }
  ]
}

Create Comment

Create Comment
POST/v1.2/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.2/comments
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "text": "This Master Chef has loads of power and more speeds than you will ever need!",
  "locale": "en_US",
  "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  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.2/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"
    }
  ],
  "orderId": "5555522",
  "user": {
    "nickName": "",
    "firstName": "Andy",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com",
    "externalId": null,
    "city": "Miami",
    "state": "FL",
    "country": "US",
    "ageRange": 1
  }
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Missing or invalid parameters sku",
      "code": 114
    }
  ]
}

Reviews

A review is a UGC type representing a user review for a product and is identified by a unique identifier.

Resource Properties - Review

Property Type Description
id number TurnTo unique ID for this review
dateCreated date Date that review was created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
reviewedDate date Date that review was reviewed by moderator (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
title string Review title
text string Review text
textLength number Number of characters in review text
locale string Locale of review
rating number Product rating (1,2,3,4, or 5)
published boolean Is published?
csFlag boolean Is flagged for customer service?
inappropriateFlag boolean Is inappropriate?
reviewedFlag boolean Is reviewed?
autoModerated boolean Is auto moderated?
incentivized boolean Did reviewer receive incentive?
upVotes number Number of up votes received
downVotes number Number of down votes received
orderId string The order ID that is associated with the review
purchaseDate date Date product purchased (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
tags string List of tag codes associated with this review
user resource The user that posted this review. Nested user block - see Users section
userIpAddr string The IP address of the UGC author
userAgent string The browser/operating system of the UGC author
catalogItems resource Product(s) for which this review is applicable. Nested products block - see Products section
dimensions resource Custom dimension properties that can be captured for this product. Nested dimensions block - see Products section
media resource Published media associated with this review. Nested media block - see Media section
responses[].text string Response text
responses[].locale string Locale of response
responses[].user resource The user that posted this response. Nested user block - see Users section
responses[].dateCreated date Date response created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
syndication.sourceName string Syndication source name
syndication.siteUrl string Syndication source site URL

Review List

Review List
GET/v1.2/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.

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.

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')

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.2/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=20&sort=textLength:desc&includeFilters=false
URI Parameters
HideShow
sku
string (required) Example: 12345

The SKU of the topic catalog item that the returned reviews are about.

related
boolean (optional) Default: false Example: false

If true, the reviews that are returned will be ones that are related to the SKU, either as Virtual Parent Siblings, or as bundle parents.

Choices: true false

includeRelated
boolean (optional) Default: false Example: false

If true, the reviews returned will be a combined list of direct and related reviews for the SKU.

Choices: true false

includeRatingOnlyReviews
boolean (optional) Default: true Example: true

If includeRatingOnlyReviews is false, rating only reviews (those without title and text) will be excluded from results.

Choices: true false

publishedOnly
boolean (optional) Default: true Example: true

If true, only return published reviews.

Choices: true false

suppressUserPII
boolean (optional) Default: false Example: false

If true, all user fields will be returned null. The nested blocks shopperProfiles and badge are not affected.

Choices: true false

tags
string (optional) Example: CSR,DAM,SOT

If specified, only return reviews that contain at least 1 of the comma separated tag codes.

locale
string (optional) Example: en_US

If specified, only return reviews for this locale.

dateCreatedFrom
date (optional) Example: 2015-09-14T00:00:00-04:00

Only return reviews created on or after this date.

dateCreatedTo
date (optional) Example: 2015-09-14T23:59:59-04:00

Only 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: 10

Maximum number of reviews to show.

offset
number (optional) Default: 0 Example: 20

Offset into reviews results. Zero based so first result is offset = 0.

sort
string (optional) Default: dateCreated:desc Example: textLength:desc

Field to sort reviews by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.

Choices: dateCreated rating textLength upVotes

includeFilters
boolean (optional) Default: false Example: false

If true, the response will include nested filters block containing information about available filters for the selected reviews result set.

Choices: true false

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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,
      "upVotes": 0,
      "downVotes": 0,
      "orderId": null,
      "dimensions": [
        {
          "type": 1,
          "dimensionId": 1,
          "dimensionLabel": "Overall Quality",
          "value": 4
        },
        {
          "type": 2,
          "dimensionId": 2,
          "dimensionLabel": "Fit",
          "value": 7,
          "label": [
            "Spot on"
          ]
        },
        {
          "type": 3,
          "dimensionId": 3,
          "dimensionLabel": "Occasion",
          "label": [
            "Formal"
          ]
        },
        {
          "type": 4,
          "dimensionId": 4,
          "dimensionLabel": "Impression",
          "label": [
            "Stylish",
            "Modern"
          ]
        }
      ],
      "responses": [
        {
          "text": "Thank you for your review.",
          "locale": "en_US",
          "user": {
            "nickName": "Andrew A.",
            "firstName": "Andrew",
            "lastName": "Adamson",
            "emailAddress": "spike@dog.org",
            "externalId": null,
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null,
            "badge": null,
            "shopperProfiles": []
          },
          "dateCreated": "2018-08-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",
            "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": []
      },
      "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
          }
        ]
      },
      "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
          },
          "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,
            "label": null,
            "sortOrder": null,
            "count": 0,
            "filter": "dim(1)"
          },
          {
            "id": 2,
            "label": null,
            "sortOrder": null,
            "count": 0,
            "filter": "dim(2)"
          },
          {
            "id": 3,
            "label": null,
            "sortOrder": null,
            "count": 0,
            "filter": "dim(3)"
          },
          {
            "id": 4,
            "label": null,
            "sortOrder": null,
            "count": 1,
            "filter": "dim(4)"
          },
          {
            "id": 5,
            "label": null,
            "sortOrder": null,
            "count": 0,
            "filter": "dim(5)"
          }
        ]
      },
      {
        "id": 2,
        "name": "fit",
        "label": "Fit",
        "sortOrder": 2,
        "required": false,
        "type": 2,
        "values": [
          {
            "id": 6,
            "label": "Tight",
            "sortOrder": 0,
            "count": 0,
            "filter": "dim(6)"
          },
          {
            "id": 7,
            "label": "Spot on",
            "sortOrder": 1,
            "count": 1,
            "filter": "dim(7)"
          },
          {
            "id": 8,
            "label": "Relaxed",
            "sortOrder": 2,
            "count": 0,
            "filter": "dim(8)"
          }
        ]
      },
      {
        "id": 3,
        "name": "occasion",
        "label": "Occasion",
        "sortOrder": 3,
        "required": false,
        "type": 3,
        "values": [
          {
            "id": 9,
            "label": "Casual",
            "sortOrder": 0,
            "count": 0,
            "filter": "dim(9)"
          },
          {
            "id": 10,
            "label": "Formal",
            "sortOrder": 1,
            "count": 1,
            "filter": "dim(10)"
          }
        ]
      },
      {
        "id": 4,
        "name": "impression",
        "label": "Impression",
        "sortOrder": 4,
        "required": false,
        "type": 4,
        "values": [
          {
            "id": 11,
            "label": "Stylish",
            "sortOrder": 0,
            "count": 1,
            "filter": "dim(11)"
          },
          {
            "id": 12,
            "label": "Modern",
            "sortOrder": 1,
            "count": 1,
            "filter": "dim(12)"
          },
          {
            "id": 13,
            "label": "Fancy",
            "sortOrder": 2,
            "count": 0,
            "filter": "dim(13)"
          },
          {
            "id": 14,
            "label": "Spicy",
            "sortOrder": 3,
            "count": 0,
            "filter": "dim(14)"
          }
        ]
      }
    ],
    "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,
              "filter": "sp(1)"
            },
            {
              "id": 2,
              "sortOrder": 1,
              "label": "Average",
              "count": 0,
              "filter": "sp(2)"
            },
            {
              "id": 3,
              "sortOrder": 2,
              "label": "Tall",
              "count": 0,
              "filter": "sp(3)"
            }
          ]
        }
      ]
    },
    "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  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Missing or invalid parameters sku",
      "code": 114
    }
  ]
}

Review Detail

Review Detail
GET/v1.2/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.2/reviews/12345
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the review.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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,
  "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
      },
      "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",
      "value": 4
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Fit",
      "value": 7,
      "label": [
        "Spot on"
      ]
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Occasion",
      "label": [
        "Formal"
      ]
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish",
        "Modern"
      ]
    }
  ],
  "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",
        "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
      }
    ]
  },
  "tags": [
    "CSR",
    "INA"
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No review was found for the specified id (949494949949)",
      "code": 139
    }
  ]
}

Create Review

Create Review
POST/v1.2/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 ID’s of existing media or details of new media content. Up to 5 media items may be supplied. Images are oriented exactly as they are supplied. Images submitted via the API are not rotated.

A site setting can be used to add custom data to reviews. If the option is enabled, the customData property can pass 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[].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?
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
customData No Additional key-value pairs associated with the review
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.2/reviews
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "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": 3
      }
    ]
  },
  "dimensions": [
    {
      "value": 4
    },
    {
      "value": 7
    },
    {
      "value": 10
    },
    {
      "value": 11
    },
    {
      "value": 12
    }
  ],
  "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,
  "turntoTrackingToken": "eyJ0cmFuc0lkIjoxLCJ0dXJudG9FbWFpbFR5cGUiOiJyZXZpZXdTb2xpY2l0YXRpb24iLCJ0dXJudG9za3UiOiI1NjY0NTQyNTMzNCJ9"
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.2/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,
  "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
      },
      "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",
      "value": 4
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Fit",
      "value": 7,
      "label": [
        "Spot on"
      ]
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Occasion",
      "label": [
        "Formal"
      ]
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish",
        "Modern"
      ]
    }
  ],
  "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
      }
    ]
  },
  "tags": []
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Review must be at least 50 characters.",
      "code": 142
    }
  ]
}

Review Vote Up

Review Vote Up
POST/v1.2/reviews/{id}/voteup

Registers an up vote for a review.

Example URI

POST https://api.turnto.com/v1.2/reviews/12345/voteup
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the review.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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,
  "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
      },
      "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",
      "value": 4
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Fit",
      "value": 7,
      "label": [
        "Spot on"
      ]
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Occasion",
      "label": [
        "Formal"
      ]
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish",
        "Modern"
      ]
    }
  ],
  "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",
        "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
      }
    ]
  },
  "tags": [
    "CSR",
    "INA"
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No review was found for the specified id (756768685)",
      "code": 139
    }
  ]
}

Review Vote Down

Review Vote Down
POST/v1.2/reviews/{id}/votedown

Registers a down vote for a review.

Example URI

POST https://api.turnto.com/v1.2/reviews/12345/votedown
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the review.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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,
  "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
      },
      "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",
      "value": 4
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Fit",
      "value": 7,
      "label": [
        "Spot on"
      ]
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Occasion",
      "label": [
        "Formal"
      ]
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish",
        "Modern"
      ]
    }
  ],
  "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",
        "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
      }
    ]
  },
  "tags": [
    "CSR",
    "INA"
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No review was found for the specified id (756768685)",
      "code": 139
    }
  ]
}

Flag Review

Flag Review
POST/v1.2/reviews/{id}/flag

Flag a review as inappropriate.

Example URI

POST https://api.turnto.com/v1.2/reviews/12345/flag
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the review.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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,
  "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
      },
      "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",
      "value": 4
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Fit",
      "value": 7,
      "label": [
        "Spot on"
      ]
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Occasion",
      "label": [
        "Formal"
      ]
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish",
        "Modern"
      ]
    }
  ],
  "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",
        "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
      }
    ]
  },
  "tags": [
    "CSR",
    "INA"
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No review was found for the specified id (145454)",
      "code": 139
    }
  ]
}

Review Form Submission

Review Form Submission
GET/v1.2/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.2/reviews/formsubmission/12345
URI Parameters
HideShow
id
number (required) Example: 12345

The unique identifier for the form submission.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
   "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  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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 Response
POST/v1.2/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.2/reviews/12345/responses
URI Parameters
HideShow
reviewId
number (required) Example: 12345

The ID of the review response.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "text": "Thank you for your review.  Glad you enjoyed it!",
  "emailToReviewer": true,
  "publish": false,
  "locale": "en_US",
  "user": {
    "nickName": null,
    "firstName": null,
    "lastName": null,
    "emailAddress": "aa.89812@mymail.com",
    "city": null,
    "state": null,
    "country": null,
    "ageRange": null
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 4321,
  "reviewId": 12345,
  "text": "Thank you for your review.  Glad you enjoyed it!",
  "locale": "en_US",
  "dateCreated": "2019-10-16T10:49:08-05:00",
  "user": {
    "nickName": "Andy",
    "firstName": "Andrew",
    "lastName": "Adams",
    "emailAddress": "aa.89812@mymail.com",
    "externalId": null,
    "city": null,
    "state": null,
    "country": null,
    "ageRange": null,
    "badge": null,
    "shopperProfiles": []
  }
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Response text too long.",
      "code": 207
    }
  ]
}

Update Review Response

Update Review Response
POST/v1.2/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.2/reviews/12345/responses/4321
URI Parameters
HideShow
reviewId
number (required) Example: 12345

The ID of the review.

id
number (required) Example: 4321

The ID of the review response.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "text": "Thank you for your review.  Glad you enjoyed it!",
  "emailToReviewer": true,
  "publish": false,
  "locale": "en_US",
  "user": {
    "nickName": null,
    "firstName": null,
    "lastName": null,
    "emailAddress": "aa.89812@mymail.com",
    "city": null,
    "state": null,
    "country": null,
    "ageRange": null
  }
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 4321,
  "reviewId": 12345,
  "text": "Thank you for your review.  Glad you enjoyed it!",
  "locale": "en_US",
  "dateCreated": "2019-10-16T10:49:08-05:00",
  "user": {
    "nickName": "Andy",
    "firstName": "Andrew",
    "lastName": "Adams",
    "emailAddress": "aa.89812@mymail.com",
    "externalId": null,
    "city": null,
    "state": null,
    "country": null,
    "ageRange": null,
    "badge": null,
    "shopperProfiles": []
  }
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Response text too long.",
      "code": 207
    }
  ]
}

Delete Review Response

Delete Review Response
DELETE/v1.2/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.2/reviews/12345/responses/4321?email=andrew@sample.com
URI Parameters
HideShow
reviewId
number (required) Example: 12345

The ID of the review.

id
number (required) Example: 4321

The ID of the review response.

email
string (required) Example: andrew@sample.com

The user email address.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "User has no permission to perform this change.",
      "code": 129
    }
  ]
}

Seller Ratings

A seller rating is a UGC type representing a user review for your site (rather than a product that your site sells). A seller rating is identified by a unique identifier.

Resource Properties - Seller Ratings

Property Type Description
id number TurnTo unique ID for this seller rating
text string Seller rating text
rating number Seller rating (1, 2, 3, 4, or 5)
locale string Locale of seller rating
user resource The user that posted this seller rating. Nested user block
userIpAddr string The IP address of the UGC author
userAgent string The browser/operating system of the UGC author

Seller Ratings List

Seller Rating List
GET/v1.2/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.2/sellerratings?publishedOnly=true&locale=en_US&rating=4&suppressUserPII=false&limit=10&offset=20&sort=rating:asc
URI Parameters
HideShow
publishedOnly
boolean (optional) Default: true Example: true

If true, only return published seller ratings.

Choices: true false

locale
string (optional) Example: en_US

If specified, only return seller ratings matching this locale.

rating
number (optional) Default: 1,2,3,4,5 Example: 4

Filter by seller rating value. Enter a single number or a comma-delimited list of numbers.

suppressUserPII
boolean (optional) Default: false Example: false

If true, all user fields are returned null.

Choices: true false

limit
number (optional) Default: 50 Example: 10

Maximum number of seller ratings to show.

offset
number (optional) Default: 0 Example: 20

Offset into results. Zero-based so first result is offset = 0.

sort
string (optional) Default: dateCreated:desc Example: rating:asc

Field to indicate sort for seller ratings. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.

Choices: dateCreated:desc dateCreated:asc rating:desc rating:asc

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "sellerratings": [
    {
      "id": 6,
      "locale": "en_US",
      "rating": 4,
      "text": "This is a great company.  Terrific customer service!",
      "published": true,
      "dateCreated": "2020-02-29T15:21:14-05:00",
      "user": {
        "nickName": "Andy",
        "firstName": "Andrew",
        "lastName": "Adams",
        "emailAddress": null,
        "externalId": "aa4444",
        "city": "Springfield",
        "state": "OH",
        "country": "US",
        "ageRange": 2,
        "shopperProfiles": []
      }
    },
    {
      "id": 7,
      "locale": "en_US",
      "rating": 2,
      "text": "Lost my order and I never heard anything from them! Never again will I shop with this store.",
      "published": true,
      "dateCreated": "2020-02-29T15:21:14-05:00",
      "user": {
        "nickName": "WendyW",
        "firstName": "Wendy",
        "lastName": "Williams",
        "emailAddress": null,
        "externalId": "aa4445",
        "city": "Muncie",
        "state": "IN",
        "country": "US",
        "ageRange": 2,
        "shopperProfiles": []
      }
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Missing or invalid parameters user",
      "code": 114
    }
  ]
}

Create Seller Rating

Create Seller Rating
POST/v1.2/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.2/sellerratings
Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "text": "This is a great company.  Terrific customer service!",
  "rating": 5,
  "locale": "en_US",
  "orderExternalId": "M202268013",
  "user": {
    "nickName": "Andy",
    "firstName": "Andrew",
    "lastName": "Adams",
    "emailAddress": null,
    "externalId": "aa4444",
    "city": "Springfield",
    "state": "OH",
    "country": "US",
    "ageRange": 2,
    "shopperProfiles": []
  },
  "userIpAddr": "555.555.100.001",
  "userAgent": "Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405",
  "turntoTrackingToken": ""
}
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 12,
  "text": "This is a great company.  Terrific customer service!",
  "rating": 5,
  "locale": "en_US",
  "published": true,
  "dateCreated": "2020-02-29T15:21:14-05:00",
  "user": {
    "nickName": "Andy",
    "firstName": "Andrew",
    "lastName": "Adams",
    "emailAddress": null,
    "externalId": "aa4444",
    "city": "Springfield",
    "state": "OH",
    "country": "US",
    "ageRange": 2,
    "shopperProfiles": []
  }
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Seller Rating must be at least 50 characters.",
      "code": 142
    }
  ]
}

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 List
GET/v1.2/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.2/articles?externalId=X12345&sku=12345&publishedOnly=true&locale=en_US&limit=10&offset=20&sort=dateCreated:desc
URI Parameters
HideShow
externalId
string (optional) Example: X12345

The external ID of the article. If supplied other parameters are ignored.

sku
string (optional) Example: 12345

Comma separated list of SKUs to return articles for. Maximum is 20. If omitted all articles are returned.

publishedOnly
boolean (optional) Default: true Example: true

If true, only return published articles.

Choices: true false

locale
string (optional) Example: en_US

Only return articles for this locale.

limit
number (optional) Default: 50 Example: 10

Maximum number of articles to show.

offset
number (optional) Default: 0 Example: 20

Offset into articles results. Zero based so first result is offset = 0.

sort
string (optional) Default: dateCreated:desc Example: dateCreated:desc

Field to sort articles by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.

Choices: dateCreated

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "articles": [
    {
      "id": 6,
      "externalId": "X333",
      "title": "Amazing Gadget",
      "text": "A new gadget to change your life.",
      "locale": "en_US",
      "published": true,
      "expirationDate": null,
      "dateCreated": "2015-08-21T14:26:07-04:00",
      "brands": [],
      "categories": [],
      "searchTerms": [
        "one",
        "two"
      ],
      "catalogItems": [
        {
          "sku": "2",
          "title": "The Matrix",
          "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
          "category": "movies"
        }
      ]
    },
    {
      "id": 9,
      "externalId": null,
      "title": "Amazing New Toy",
      "text": "A new toy to rock your world.",
      "locale": "en_US",
      "published": true,
      "expirationDate": null,
      "dateCreated": "2015-08-21T14:26:08-04:00",
      "brands": [],
      "categories": [],
      "searchTerms": [],
      "catalogItems": [
        {
          "sku": "1",
          "title": "Die Hard 2",
          "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
          "category": "movies"
        },
        {
          "sku": "2",
          "title": "The Matrix",
          "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
          "category": "movies"
        },
        {
          "sku": "3",
          "title": "Purple Rain",
          "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
          "category": "movies"
        }
      ]
    },
    {
      "id": 10,
      "externalId": null,
      "title": "Amazing New Colors",
      "text": "A new color to rock your world.",
      "locale": "en_US",
      "published": true,
      "expirationDate": null,
      "dateCreated": "2015-08-21T14:26:08-04:00",
      "brands": [],
      "categories": [],
      "searchTerms": [
        "blue",
        "green"
      ],
      "catalogItems": [
        {
          "sku": "1",
          "title": "Die Hard 2",
          "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
          "category": "movies"
        }
      ]
    }
  ],
  "offset": null,
  "limit": null,
  "total": 3
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Missing or invalid parameters sku",
      "code": 114
    }
  ]
}

Article Detail

Article Detail
GET/v1.2/articles/{id}

This endpoint will return a single article identified by its ID.

Example URI

GET https://api.turnto.com/v1.2/articles/12345
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the article.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "id": 5,
  "externalId": "X222",
  "title": "Amazing Gadget",
  "text": "A new gadget to change your life.",
  "locale": "en_US",
  "published": true,
  "expirationDate": null,
  "dateCreated": "2015-08-21T14:26:07-04:00",
  "brands": [],
  "categories": [],
  "searchTerms": [],
  "catalogItems": [
    {
      "sku": "2",
      "title": "The Matrix",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
      "category": "movies"
    },
    {
      "sku": "3",
      "title": "Purple Rain",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
      "category": "movies"
    },
    {
      "sku": "11112222",
      "title": "MultiChef",
      "url": "www.topchef.com/food-processors/multichef",
      "category": "processors"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No article was found for the specified id (12292929)",
      "code": 154
    }
  ]
}

Update Article

Update Article
POST/v1.2/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.2/articles
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "id": null,
  "externalId": "X0123",
  "title": "Amazing Gadget",
  "text": "A new gadget to change your life.",
  "locale": "en_US",
  "published": true,
  "expirationDate": "2017-08-21T14:26:04-04:00",
  "catalogItems": [
    {
      "sku": "1"
    },
    {
      "sku": "2"
    },
    {
      "sku": "3"
    }
  ],
  "brands": null,
  "categories": null,
  "searchTerms": null
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1.2/articles/{id}
Body
{
  "id": 36,
  "externalId": "X0123",
  "title": "Amazing Gadget",
  "text": "A new gadget to change your life.",
  "locale": "en_US",
  "published": true,
  "expirationDate": "2017-08-21T14:26:04-04:00",
  "dateCreated": "2015-08-20T16:56:35-04:00",
  "brands": [],
  "categories": [],
  "searchTerms": [],
  "catalogItems": [
    {
      "sku": "1",
      "title": "Die Hard 2",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1",
      "category": "movies"
    },
    {
      "sku": "2",
      "title": "The Matrix",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=2",
      "category": "movies"
    },
    {
      "sku": "3",
      "title": "Purple Rain",
      "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3",
      "category": "movies"
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Missing Required Fields (title)",
      "code": 108
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No article was found for the specified id (398239892)",
      "code": 154
    }
  ]
}

Delete Article

Delete Article
DELETE/v1.2/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.2/articles/1234
URI Parameters
HideShow
id
number (required) Example: 1234

The ID of the article.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No article was found for the specified id (2)",
      "code": 154
    }
  ]
}

Delete Article By External ID

Delete Article by External ID
DELETE/v1.2/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.2/articles?externalId=X12345
URI Parameters
HideShow
externalId
string (required) Example: X12345

The external ID of the article.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Response  404
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "No article was found for the specified external id (X222)",
      "code": 154
    }
  ]
}

Users

A user is identified by an email address or in the case of user created from a third party application by user external ID.

User profile information such as location (city, state, and country) and age range may also be collected and stored.

Custom user profile information, referred to as shopper profiles, can be configured for a site. If so this information will also be collected and stored.

Resource Properties - User

Property Type Description
firstName string First name
lastName string Last name
nickName string Nick name
externalId string External ID
email string Email address
city string City
state string State
country string Country
ageRange number Age range indicator
badge.text string Badge text
badge.imageUrl string URL of image to use for badge
shopperProfiles[].id number Identifier for a shopper profile
shopperProfiles[].value string Free-form text value

Forget User

Forget User
POST/v1.2/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.2/users/forget?email=sample@turnto.com
URI Parameters
HideShow
email
string (required) Example: sample@turnto.com

The email of the shopper.

Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Invalid Email Address",
      "code": 128
    }
  ]
}

User UGC

User UGC
GET/v1.2/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.2/users?email=andrew@sample.com&userId=7654321&ugcType=question&questionsOnly=false&questionsAnsweredOnly=false&answersOnly=false&commentsOnly=false&reviewsOnly=false&includeNested=false&publishedOnly=false
URI Parameters
HideShow
email
string (optional) Example: andrew@sample.com

The user’s email address.

userId
string (optional) Example: 7654321

The user’s external ID. This parameter is required if email address is blank.

ugcType
string (optional) Default: all Example: question

Type of content to return. Multiple types can be specified using comma-separated values.

Choices: question question-answered answer review comment all

questionsOnly
boolean (optional) Default: false Example: false

If true only return questions content.

Choices: true false

questionsAnsweredOnly
boolean (optional) Default: false Example: false

If questionsAnsweredOnly is true, only return questions answered content.

Choices: true false

answersOnly
boolean (optional) Default: false Example: false

If true only return answers content.

Choices: true false

commentsOnly
boolean (optional) Default: false Example: false

If true only return comments content.

Choices: true false

reviewsOnly
boolean (optional) Default: false Example: false

If true only return reviews content.

Choices: true false

includeNested
boolean (optional) Default: false Example: false

Option to include nested content.

Choices: true false

publishedOnly
boolean (optional) Default: true Example: false

If true, only return published content.

Choices: true false

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "user": {
    "firstName": "Bill",
    "lastName": "Mee",
    "nickName": "Bill M.",
    "externalId": null,
    "email": "bm@sample.com",
    "city": "Memphis",
    "state": "TN",
    "country": "US",
    "ageRange": 2
  },
  "questions": [
    {
      "id": 7,
      "dateCreated": "2016-11-15T10:37:48-05:00",
      "approvedDate": null,
      "text": "How many different attachments come with this food processor?",
      "textLength": 61,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "irrelevantFlag": false,
      "unansweredAlert": false,
      "reviewedFlag": false,
      "autoModerated": false,
      "flagForExpert": false,
      "upVotes": 0,
      "isStaff": false,
      "isCategoryQuestion": false,
      "answerCount": 2,
      "answers": [
        {
          "id": 6,
          "dateCreated": "2016-11-15T10:37:50-05:00",
          "reviewedDate": null,
          "text": "There are 5: fine, coarse, slicer, mixer, grater.",
          "textLength": 49,
          "locale": "en_US",
          "published": false,
          "csFlag": false,
          "inappropriateFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "upVotes": 0,
          "thanked": false,
          "isStaff": false,
          "purchaseDate": null,
          "itemQuestionId": 7,
          "catalogItems": [],
          "replyCount": 2,
          "replies": [
            {
              "id": 2,
              "text": "Thank you so much!",
              "locale": "en_US",
              "published": false,
              "dateCreated": "2016-11-15T10:37:51-05:00",
              "reviewedDate": null,
              "csFlag": false,
              "reviewedFlag": false,
              "autoModerated": true,
              "isStaff": false,
              "parentReplyId": null,
              "parentAnswerId": 6,
              "user": {
                "nickName": "Bill M.",
                "firstName": "Bill",
                "lastName": "Mee",
                "emailAddress": "bm@sample.com",
                "externalId": null,
                "city": "Memphis",
                "state": "TN",
                "country": "US",
                "ageRange": 2
              },
              "replies": [
                {
                  "id": 3,
                  "text": "You're welcome.",
                  "locale": "en_US",
                  "published": false,
                  "dateCreated": "2016-11-15T10:37:51-05:00",
                  "reviewedDate": null,
                  "csFlag": false,
                  "reviewedFlag": false,
                  "autoModerated": true,
                  "isStaff": false,
                  "parentReplyId": 2,
                  "parentAnswerId": 6,
                  "user": {
                    "nickName": "Mable L.",
                    "firstName": "Mable",
                    "lastName": "Leaf",
                    "emailAddress": "ml@sample.com",
                    "externalId": null,
                    "city": null,
                    "state": null,
                    "country": null,
                    "ageRange": null
                  },
                  "replies": [],
                  "replyCount": 0
                }
              ],
              "replyCount": 1
            }
          ],
          "user": {
            "nickName": "Mable L.",
            "firstName": "Mable",
            "lastName": "Leaf",
            "emailAddress": "ml@sample.com",
            "externalId": null,
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null,
            "badge": null
          },
          "bestAnswer": true,
          "tags": []
        },
        {
          "id": 5,
          "dateCreated": "2016-11-15T10:37:49-05:00",
          "reviewedDate": null,
          "text": "There are no attachments!",
          "textLength": 25,
          "locale": "en_US",
          "published": false,
          "csFlag": false,
          "inappropriateFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "upVotes": 0,
          "thanked": false,
          "isStaff": false,
          "purchaseDate": null,
          "itemQuestionId": 7,
          "catalogItems": [],
          "replyCount": 0,
          "replies": [],
          "user": {
            "nickName": "Clint S.",
            "firstName": "Clint",
            "lastName": "Smith",
            "emailAddress": "clint@sample.com",
            "externalId": null,
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null,
            "badge": null
          },
          "tags": []
        }
      ],
      "user": {
        "nickName": "Bill M.",
        "firstName": "Bill",
        "lastName": "Mee",
        "emailAddress": "bm@sample.com",
        "externalId": null,
        "city": "Memphis",
        "state": "TN",
        "country": "US",
        "ageRange": 2
      },
      "catalogItems": [
        {
          "sku": "FP12653",
          "title": "Blendomatic 5000",
          "url": "http://www.homegadgetsandmore.com/blendomatic",
          "category": null
        }
      ],
      "tags": []
    }
  ],
  "questionsAnswered": [
    {
      "id": 8,
      "dateCreated": "2016-11-15T10:37:51-05:00",
      "approvedDate": "2016-11-15T10:37:51-05:00",
      "text": "You are you are?",
      "textLength": 16,
      "locale": "en_US",
      "published": true,
      "csFlag": false,
      "irrelevantFlag": false,
      "unansweredAlert": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "flagForExpert": false,
      "upVotes": 0,
      "isStaff": false,
      "isCategoryQuestion": false,
      "answerCount": 1,
      "answers": [
        {
          "id": 7,
          "dateCreated": "2016-11-15T10:37:52-05:00",
          "reviewedDate": null,
          "text": "Oh yes, this little guy is amazing!",
          "textLength": 35,
          "locale": "en_US",
          "published": false,
          "csFlag": false,
          "inappropriateFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "upVotes": 0,
          "thanked": false,
          "isStaff": false,
          "purchaseDate": null,
          "itemQuestionId": 8,
          "catalogItems": [],
          "replyCount": 1,
          "replies": [
            {
              "id": 4,
              "text": "Good to know...",
              "locale": "en_US",
              "published": false,
              "dateCreated": "2016-11-15T10:37:52-05:00",
              "reviewedDate": null,
              "csFlag": false,
              "reviewedFlag": false,
              "autoModerated": true,
              "isStaff": false,
              "parentReplyId": null,
              "parentAnswerId": 7,
              "user": {
                "nickName": "Sally L.",
                "firstName": "Sally",
                "lastName": "Lewis",
                "emailAddress": "sl@sample.com",
                "externalId": null,
                "city": null,
                "state": null,
                "country": null,
                "ageRange": null
              },
              "replies": [],
              "replyCount": 0
            }
          ],
          "user": {
            "nickName": "Bill M.",
            "firstName": "Bill",
            "lastName": "Mee",
            "emailAddress": "bm@sample.com",
            "externalId": null,
            "city": "Memphis",
            "state": "TN",
            "country": "US",
            "ageRange": 2,
            "badge": null
          },
          "bestAnswer": true,
          "tags": []
        }
      ],
      "user": {
        "nickName": "Sally L.",
        "firstName": "Sally",
        "lastName": "Lewis",
        "emailAddress": "sl@sample.com",
        "externalId": null,
        "city": null,
        "state": null,
        "country": null,
        "ageRange": null
      },
      "catalogItems": [
        {
          "sku": "FP17268",
          "title": "Melon Slicer",
          "url": "http://www.homegadgetsandmore.com/melonslicer",
          "category": null
        }
      ],
      "tags": []
    }
  ],
  "answers": [
    {
      "id": 7,
      "dateCreated": "2016-11-15T10:37:52-05:00",
      "reviewedDate": null,
      "text": "Oh yes, this little guy is amazing!",
      "textLength": 35,
      "locale": "en_US",
      "published": false,
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": true,
      "upVotes": 0,
      "thanked": false,
      "isStaff": false,
      "purchaseDate": null,
      "itemQuestionId": 8,
      "catalogItems": [],
      "replyCount": 1,
      "replies": [
        {
          "id": 4,
          "text": "Good to know...",
          "locale": "en_US",
          "published": false,
          "dateCreated": "2016-11-15T10:37:52-05:00",
          "reviewedDate": null,
          "csFlag": false,
          "reviewedFlag": false,
          "autoModerated": true,
          "isStaff": false,
          "parentReplyId": null,
          "parentAnswerId": 7,
          "user": {
            "nickName": "Sally L.",
            "firstName": "Sally",
            "lastName": "Lewis",
            "emailAddress": "sl@sample.com",
            "externalId": null,
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null
          },
          "replies": [],
          "replyCount": 0
        }
      ],
      "user": {
        "nickName": "Bill M.",
        "firstName": "Bill",
        "lastName": "Mee",
        "emailAddress": "bm@sample.com",
        "externalId": null,
        "city": "Memphis",
        "state": "TN",
        "country": "US",
        "ageRange": 2,
        "badge": null
      },
      "tags": []
    }
  ],
  "comments": [
    {
      "id": 5,
      "text": "This Blendomatic should have all the features I am looking for.",
      "textLength": 63,
      "locale": "en_US",
      "published": false,
      "dateCreated": "2016-11-15T10:37:52-05:00",
      "orderId": null,
      "user": {
        "nickName": "Bill M.",
        "firstName": "Bill",
        "lastName": "Mee",
        "emailAddress": null,
        "externalId": null,
        "city": "Memphis",
        "state": "TN",
        "country": "US",
        "ageRange": 2
      },
      "catalogItems": [
        {
          "sku": "FP12653",
          "title": "Blendomatic 5000",
          "url": "http://www.homegadgetsandmore.com/blendomatic",
          "category": null
        }
      ],
      "tags": []
    }
  ],
  "reviews": [
    {
      "id": 7,
      "rating": 4,
      "title": "The best melon slicer bar none",
      "text": "This melon slicer has changed my life.  I never thought I would see the day when slicing a melon could be made so simple.  The best ever!",
      "textLength": 137,
      "locale": "en_US",
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": false,
      "published": false,
      "incentivized": false,
      "upVotes": 0,
      "downVotes": 0,
      "orderId": null,
      "dimensions": [],
      "media": {
        "photo": [],
        "video": [],
        "audio": []
      },
      "responses": [],
      "reviewedDate": null,
      "purchaseDate": null,
      "dateCreated": "2016-11-15T10:37:53-05:00",
      "user": {
        "nickName": "Bill M.",
        "firstName": "Bill",
        "lastName": "Mee",
        "emailAddress": "bm@sample.com",
        "externalId": null,
        "city": "Memphis",
        "state": "TN",
        "country": "US",
        "ageRange": 2
      },
      "catalogItems": [
        {
          "sku": "FP17268",
          "title": "Melon Slicer",
          "url": "http://www.homegadgetsandmore.com/melonslicer",
          "category": null
        }
      ],
      "tags": []
    }
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Invalid Email Address",
      "code": 128
    }
  ]
}

Unreviewed Purchases

Unreviewed Purchases
GET/v1.2/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.2/users/unreviewed?email=a@a.com&userId=7654321&orderId=ORD02949&orderDateFrom=2015-09-14T23:59:59-04:00&suppressUserPII=false&limit=10&offset=20&sort=orderDate:asc
URI Parameters
HideShow
email
string (optional) Example: a@a.com

The user’s email address.

userId
string (optional) Example: 7654321

The user’s external ID. This parameter is required if email address is blank.

orderId
string (optional) Example: ORD02949

If supplied only include purchases for this order.

orderDateFrom
date (optional) Example: 2015-09-14T23:59:59-04:00

Only return purchases with an order date on or after this date.

suppressUserPII
boolean (optional) Default: false Example: false

If true, all user fields will be returned null. The nested blocks shopperProfiles and badge are not affected.

Choices: true false

limit
number (optional) Default: 50 Example: 10

Maximum number of purchased products to return.

offset
number (optional) Default: 0 Example: 20

Offset into purchased products results. Zero based so first result is offset = 0.

sort
string (optional) Example: orderDate:asc

Field to sort purchased products by. Format field-name-1:direction-1,field-name-2:direction-2. Valid directions are: asc and desc.

Choices: orderDate price reviewCount

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Response  200
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "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
        },
        "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,
                "sortOrder": 0,
                "label": "Small"
              },
              {
                "id": 2,
                "sortOrder": 1,
                "label": "Spot on"
              },
              {
                "id": 3,
                "sortOrder": 2,
                "label": "Large"
              }
            ]
          },
          {
            "id": 2,
            "sortOrder": 2,
            "label": "Fit",
            "type": 2,
            "required": false,
            "average": null,
            "values": [
              {
                "id": 4,
                "sortOrder": 0,
                "label": "Tight"
              },
              {
                "id": 5,
                "sortOrder": 1,
                "label": "Spot on"
              },
              {
                "id": 6,
                "sortOrder": 2,
                "label": "Relaxed"
              }
            ]
          },
          {
            "id": 3,
            "sortOrder": 3,
            "label": "Length",
            "type": 2,
            "required": false,
            "average": null,
            "values": [
              {
                "id": 7,
                "sortOrder": 0,
                "label": "Short"
              },
              {
                "id": 8,
                "sortOrder": 1,
                "label": "Spot on"
              },
              {
                "id": 9,
                "sortOrder": 2,
                "label": "Long"
              }
            ]
          },
          {
            "id": 4,
            "sortOrder": 4,
            "label": "Width",
            "type": 2,
            "required": false,
            "average": null,
            "values": [
              {
                "id": 10,
                "sortOrder": 0,
                "label": "Narrow"
              },
              {
                "id": 11,
                "sortOrder": 1,
                "label": "Spot on"
              },
              {
                "id": 12,
                "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
                },
                {
                  "id": 2,
                  "label": "Athletic",
                  "hidden": false,
                  "sortOrder": 1
                },
                {
                  "id": 3,
                  "label": "Average",
                  "hidden": false,
                  "sortOrder": 2
                },
                {
                  "id": 4,
                  "label": "Broad",
                  "hidden": false,
                  "sortOrder": 3
                },
                {
                  "id": 5,
                  "label": "Plus Size",
                  "hidden": false,
                  "sortOrder": 4
                }
              ]
            },
            {
              "name": "skinType",
              "label": "Skin Type",
              "type": 0,
              "hidden": false,
              "required": false,
              "collectDuringContentSubmit": true,
              "displayPublic": true,
              "values": [
                {
                  "id": 6,
                  "label": "Normal",
                  "hidden": false,
                  "sortOrder": 0
                },
                {
                  "id": 7,
                  "label": "Oily",
                  "hidden": false,
                  "sortOrder": 1
                },
                {
                  "id": 8,
                  "label": "Combination",
                  "hidden": false,
                  "sortOrder": 2
                },
                {
                  "id": 9,
                  "label": "Dry",
                  "hidden": false,
                  "sortOrder": 3
                },
                {
                  "id": 10,
                  "label": "Teenage",
                  "hidden": false,
                  "sortOrder": 4
                },
                {
                  "id": 11,
                  "label": "Sensitive",
                  "hidden": false,
                  "sortOrder": 5
                }
              ]
            },
            {
              "name": "skinTone",
              "label": "Skin Tone",
              "type": 0,
              "hidden": false,
              "required": false,
              "collectDuringContentSubmit": true,
              "displayPublic": true,
              "values": [
                {
                  "id": 12,
                  "label": "Fair",
                  "hidden": false,
                  "sortOrder": 0
                },
                {
                  "id": 13,
                  "label": "Light",
                  "hidden": false,
                  "sortOrder": 1
                },
                {
                  "id": 14,
                  "label": "Medium",
                  "hidden": false,
                  "sortOrder": 2
                },
                {
                  "id": 15,
                  "label": "Tanned",
                  "hidden": false,
                  "sortOrder": 3
                },
                {
                  "id": 16,
                  "label": "Dark",
                  "hidden": false,
                  "sortOrder": 4
                }
              ]
            },
            {
              "name": "height",
              "label": "Height",
              "type": 0,
              "hidden": false,
              "required": false,
              "collectDuringContentSubmit": true,
              "displayPublic": true,
              "values": [
                {
                  "id": 17,
                  "label": "< 155 cm",
                  "hidden": false,
                  "sortOrder": 0
                },
                {
                  "id": 18,
                  "label": "155-160 cm",
                  "hidden": false,
                  "sortOrder": 1
                },
                {
                  "id": 19,
                  "label": "165-170 cm",
                  "hidden": false,
                  "sortOrder": 2
                },
                {
                  "id": 20,
                  "label": "170-175 cm",
                  "hidden": false,
                  "sortOrder": 3
                },
                {
                  "id": 21,
                  "label": "175-180 cm",
                  "hidden": false,
                  "sortOrder": 4
                },
                {
                  "id": 22,
                  "label": "180-185 cm",
                  "hidden": false,
                  "sortOrder": 5
                },
                {
                  "id": 23,
                  "label": "185-190 cm",
                  "hidden": false,
                  "sortOrder": 6
                },
                {
                  "id": 24,
                  "label": "190-195 cm",
                  "hidden": false,
                  "sortOrder": 7
                }
              ]
            }
          ]
        }
      }
    },
    {
      "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
        },
        "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,
                "sortOrder": 0,
                "label": "Small"
              },
              {
                "id": 2,
                "sortOrder": 1,
                "label": "Spot on"
              },
              {
                "id": 3,
                "sortOrder": 2,
                "label": "Large"
              }
            ]
          },
          {
            "id": 2,
            "sortOrder": 2,
            "label": "Fit",
            "type": 2,
            "required": false,
            "average": null,
            "values": [
              {
                "id": 4,
                "sortOrder": 0,
                "label": "Tight"
              },
              {
                "id": 5,
                "sortOrder": 1,
                "label": "Spot on"
              },
              {
                "id": 6,
                "sortOrder": 2,
                "label": "Relaxed"
              }
            ]
          },
          {
            "id": 3,
            "sortOrder": 3,
            "label": "Length",
            "type": 2,
            "required": false,
            "average": null,
            "values": [
              {
                "id": 7,
                "sortOrder": 0,
                "label": "Short"
              },
              {
                "id": 8,
                "sortOrder": 1,
                "label": "Spot on"
              },
              {
                "id": 9,
                "sortOrder": 2,
                "label": "Long"
              }
            ]
          },
          {
            "id": 4,
            "sortOrder": 4,
            "label": "Width",
            "type": 2,
            "required": false,
            "average": null,
            "values": [
              {
                "id": 10,
                "sortOrder": 0,
                "label": "Narrow"
              },
              {
                "id": 11,
                "sortOrder": 1,
                "label": "Spot on"
              },
              {
                "id": 12,
                "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
                },
                {
                  "id": 2,
                  "label": "Athletic",
                  "hidden": false,
                  "sortOrder": 1
                },
                {
                  "id": 3,
                  "label": "Average",
                  "hidden": false,
                  "sortOrder": 2
                },
                {
                  "id": 4,
                  "label": "Broad",
                  "hidden": false,
                  "sortOrder": 3
                },
                {
                  "id": 5,
                  "label": "Plus Size",
                  "hidden": false,
                  "sortOrder": 4
                }
              ]
            },
            {
              "name": "skinType",
              "label": "Skin Type",
              "type": 0,
              "hidden": false,
              "required": false,
              "collectDuringContentSubmit": true,
              "displayPublic": true,
              "values": [
                {
                  "id": 6,
                  "label": "Normal",
                  "hidden": false,
                  "sortOrder": 0
                },
                {
                  "id": 7,
                  "label": "Oily",
                  "hidden": false,
                  "sortOrder": 1
                },
                {
                  "id": 8,
                  "label": "Combination",
                  "hidden": false,
                  "sortOrder": 2
                },
                {
                  "id": 9,
                  "label": "Dry",
                  "hidden": false,
                  "sortOrder": 3
                },
                {
                  "id": 10,
                  "label": "Teenage",
                  "hidden": false,
                  "sortOrder": 4
                },
                {
                  "id": 11,
                  "label": "Sensitive",
                  "hidden": false,
                  "sortOrder": 5
                }
              ]
            },
            {
              "name": "skinTone",
              "label": "Skin Tone",
              "type": 0,
              "hidden": false,
              "required": false,
              "collectDuringContentSubmit": true,
              "displayPublic": true,
              "values": [
                {
                  "id": 12,
                  "label": "Fair",
                  "hidden": false,
                  "sortOrder": 0
                },
                {
                  "id": 13,
                  "label": "Light",
                  "hidden": false,
                  "sortOrder": 1
                },
                {
                  "id": 14,
                  "label": "Medium",
                  "hidden": false,
                  "sortOrder": 2
                },
                {
                  "id": 15,
                  "label": "Tanned",
                  "hidden": false,
                  "sortOrder": 3
                },
                {
                  "id": 16,
                  "label": "Dark",
                  "hidden": false,
                  "sortOrder": 4
                }
              ]
            },
            {
              "name": "height",
              "label": "Height",
              "type": 0,
              "hidden": false,
              "required": false,
              "collectDuringContentSubmit": true,
              "displayPublic": true,
              "values": [
                {
                  "id": 17,
                  "label": "< 155 cm",
                  "hidden": false,
                  "sortOrder": 0
                },
                {
                  "id": 18,
                  "label": "155-160 cm",
                  "hidden": false,
                  "sortOrder": 1
                },
                {
                  "id": 19,
                  "label": "165-170 cm",
                  "hidden": false,
                  "sortOrder": 2
                },
                {
                  "id": 20,
                  "label": "170-175 cm",
                  "hidden": false,
                  "sortOrder": 3
                },
                {
                  "id": 21,
                  "label": "175-180 cm",
                  "hidden": false,
                  "sortOrder": 4
                },
                {
                  "id": 22,
                  "label": "180-185 cm",
                  "hidden": false,
                  "sortOrder": 5
                },
                {
                  "id": 23,
                  "label": "185-190 cm",
                  "hidden": false,
                  "sortOrder": 6
                },
                {
                  "id": 24,
                  "label": "190-195 cm",
                  "hidden": false,
                  "sortOrder": 7
                }
              ]
            }
          ]
        }
      }
    }
  ],
  "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  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Invalid Email Address",
      "code": 128
    }
  ]
}

Recent Updates

This section contains details of updates to the API.

To receive updates by email, please visit our signup page http://www2.turntonetworks.com/dev-comm.

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 - 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 custom data property added

An optional property has been added to the Create Review endpoint to capture customData, which passes a JSON object with key-value pairs.

11/12/19 - Review responses endpoints added

New Review Responses endpoints have been added to allow clients to manage review responses.

11/12/19 - Review list rating only review option added

A new option (includeRatingOnlyReviews) has been added to the Review List endpoint to allow rating only reviews to be excluded from results.

01/14/19 - Create Order line item brand property added

The Create Order endpoint has been modified to allow a brand to be specified for each order line.

01/14/19 - Unreviewed Purchases rating breakdown fix

The Unreviewed Purchases endpoint has been modified such that values of ratingBreakdown property are returned as a Map not as a String.

10/02/18 - UGC Search related content option added

Optional parameters (related) and (includeRelated) have been added to the UGC Search endpoint to allow direct and related content to be returned.

08/23/18 - Create Review incentivized property added

An optional parameter (incentivized) has been added to the Create Review endpoint to allow reviews to be flagged as incentivized.

06/26/18 - Collect User Agent for Review authors

An optional parameter (userAgent) has been added to the Create Review endpoint to allow for the capture of the browser/operating system for the UGC author.

04/18/18 - Unreviewed Purchases orderId option added

An optional parameter (orderId) has been added to the Unreviewed Purchases endpoint to allow purchases to be restricted to a single order.

04/18/18 - Review list sort by upVotes

A new sort option (upVotes) has been added to the Review List endpoint to allow reviews to be sorted by number of upVotes.

Previous Versions

Generated by aglio on 06 Aug 2021