Back to top

TurnTo API v1

Overview

Our API is designed for developers who want to programmatically submit and retrieve TurnTo data, apart from the provided TurnTo front-end web widgets.

It provides access to user generated content as well as product catalog, shopper orders, and other statistical data stored in the TurnTo system from within your own applications.

Using the API provides many opportunities to extend the power of the TurnTo platform. Some possible examples:

  • Native mobile applications

  • Custom display applications

  • In-store kiosks

  • Site-wide search integration

  • Shopper profile integration

  • Catalog maintenance

  • Import/export knowledge base articles

  • Multi-language display and translation

Note: To prevent misuse of the access token, consider using a proxy server for external clients (such as Native mobile applications). See the API Implementation overview.

Data Types

  • Questions

  • Answers

  • Replies

  • Checkout Comments

  • Product Ratings & Reviews

  • Knowledgebase Articles

  • User Media

  • Customer Orders

  • Customer Profiles

  • Content Statistics

Mixed Widget and API Installations

Developers can use their custom API-based applications alongside the TurnTo Widgets for the same site ID. This is particularly important for sites that use TurnTo widgets on their website and the API for their native mobile apps.

Localization

TurnTo API supports multi-language sites so that UGC may be created for a specific locale that has been configured for the site. When using an API endpoint to retrieve UGC the locale parameter is used to filter for the required site language.

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

Moderation

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

Emails and Notifications

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

RESTful Services

Read

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

Example:

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

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

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

Create

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

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

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

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

Update (Operation)

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

Example:

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

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

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

API Rate Limiting

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

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

How to Get Started

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

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

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

Response Codes

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

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

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

Code Message Description HTTP Status
101 Invalid sort parameter format The supplied sort parameter did not have the correct format. 400
102 Invalid field in sort parameter One or more fields in the supplied sort parameter were not valid. 400
103 Invalid limit or offset The limit or offset was not numeric. 400
104 Offset was out of range The offset was less than zero or greater than or equal to the total number of result set rows. 400
105 Limit was out of range The limit was less than zero. 400
106 No catalog item found for SKU () The SKU was not found in the catalog. 400
107 No question was found for the specified ID () A question with the specified ID could not be found. 404
108 Missing Required Fields Fields were missing for a create or update. 400
109 Catalog item not found for one or more supplied SKUs One of the supplied SKUs was not found in the catalog. 400
110 Please do not include links to other sites A link to another site was included in the supplied text. 400
111 Failed to save the question An unknown error occurred while attempting to save the question. 500
112 Invalid client_id or client_secret Client ID / Client Secret combination is not valid. 403
113 Unknown grant_type Invalid grant_type. 400
114 Missing or invalid parameters client_secret, grant_type The client_secret and/or grant_type was missing or invalid. 400
115 Unknown access_token Access token missing or incorrect for invalidate_token service. 400
116 Missing Authorization header OAuth2 token not present. 403
117 Invalid access token OAuth2 token invalid. 403
118 Error while generating access_token Server error. 500
119 Error while invalidating access_token Server error. 400
120 $$$$ method not allowed for this request type The requested method is not allowed for this request type. 405
121 Failed to save answer An unknown error occurred while attempting to save the answer. 500
122 Too many SKUs requested There is a maximum of 25 UGC counts that can be returned in a single request. 400
123 No comment was found for the specified ID () A comment with the specified ID could not be found. 400
124 Failed to save the comment An unknown error occurred while attempting to save the comment. 500
125 Too many SKUs attached to question The maximum number of SKUs (catalog items) for a question was exceeded. Maximum is 10. 400
126 Limit too large. Max is 100 The maximum limit for pagination was exceeded. Maximum is 100. 400
127 Failed to save the reply An unknown error occurred while attempting to save the reply. 500
128 Invalid email address The format of the email address is invalid. 400
129 Unknown email address The email address was not a match for any user. 400
130 Unknown external ID The external id was not a match for any user. 400
131 Bad search filters At least one of the search filter parameters has an invalid value, or a required filter parameter is missing 400
132 No answer was found for the specified ID () An answer with the specified ID could not be found. 404
133 No reply was found for the specified ID () A reply with the specified ID could not be found. 404
134 No replies found for the specified answer id () No replies found for the specified answer ID () 400
135 Error parsing JSON properties Error parsing JSON properties. 400
136 Must specify at least one catalog item Must specify at least one catalog item. 400
137 One or more duplicate SKUs At least one SKU is duplicated in the catalog items section. 400
138 Too many SKUs attached to answer The maximum number of SKUs (catalog items) for an answer was exceeded. Maximum is 10. 400
139 No review was found for the specified ID () A review with the specified ID could not be found. 404
140 Failed to save the review An unknown error occurred while attempting to save the review. 500
141 Review rating must be between 1 and 5 The review rating must be between 1 and 5. 400
142 Review text too short The review text length is less than site minimum number of characters. 400
143 No parent reply was found for the specified id () No parent reply was found for the specified ID. 400
144 Must specify email address or external ID User must be identified by an email address or an external ID. 400
145 Invalid field The field value was not valid. 400
146 Invalid delivery date format. The delivery date was not correctly formatted as yyyy-MM-dd 400
147 Order not created The order could not be created. 400
148 Order not cancelled The order could not be cancelled. 400
149 Invalid locale for site Invalid locale for site. 400
150 Product update failed The product update could not be completed. 400
151 Invalid shopper profile The shopper profile was invalid. 400
152 Duplicate shopper profile The supplied shopper profiles contains duplicates. 400
153 Failed to save the article An unknown error occurred while attempting to save the article. 500
154 No article was found for the specified ID () An article with the specified ID could not be found. 404
155 No article was found for the specified external ID () An article with the specified external ID could not be found. 404
156 Must specify ID or external ID Article to be deleted must be identified by ID or external ID. 400
157 Invalid expiration date format. The expiration date was not correctly formatted as yyyy-MM-dd 400
158 Category not found for one or more supplied category names One of the supplied category names was not found. 400
159 One or more duplicate categories At least one category is duplicated. 400
160 Brand not found for one or more supplied brand names One of the supplied brand names was not found. 400
161 One or more duplicate brands At least one brand is duplicated. 400
162 Too many SKUs requested There is a maximum of 25 SKUs that can be matched in a single request. 400
163 Invalid date specified for dateCreatedFrom parameter The date created from parameter is invalid. 400
164 Invalid date specified for dateCreatedTo parameter The date created to parameter is invalid. 400
165 Invalid date specified for dateCreated parameter The date created parameter is invalid. 400
166 DateCreated parameter not allowed without external Id The date created parameter is not allowed without external Id. 400
167 API rate limit exceeded The number of requests has exceeded the API rate limit. 429
168 Reviews not enabled Reviews are not enabled for this site. 400
169 No order item found for the specified order ID () 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. 400
200 Invalid external ID The external id was invalid for specified email address. 400
201 Failed to return reviews An unknown error occurred while attempting to return review results. 500
202 A single SKU must be specified when searching for related content. Must supply a single SKU when searching for related content. 400
203 Shopper profile should be id or code. Cannot specify shopper profile using both id and code. 400
204 Unknown profile code (). Specified shopper profile code was not found. 400
205 Dimension should be value or code. Cannot specify dimension using both id and code… 400
206 Unknown dimension code (). Specified dimension code was not found. 400
207 Response text too long. The review response text length exceeds maximum of 1000 characters. 400
208 No response was found for the specified id (). The review response was not found. 404
209 Failed to save the response. An unknown error occurred while attempting to save the review response. 500
210 Must specify Review Response ID. The review response Id was missing. 400
211 Seller Ratings not enabled. Seller ratings not enabled for this site. 400
212 Invalid orderExternalId or turntoTrackingToken. Specified order was not found. 400
213 User already submitted a seller rating for this transaction. Cannot specify order that already has a seller rating. 400
214 Invalid ratings value specified. Comma separated ratings values expected when filtering seller ratings by rating. 400

OAuth

TurnTo uses the OAuth 2.0 Bearer token mechanism to secure most API requests. You can use the ‘/v1/oauth2/token’ endpoint to obtain the Bearer token using your site’s siteKey and authKey which you can copy from your site’s settings area at www.turnto.com.

The Bearer token that’s returned in the response has to be included with every request to the API as part of the value of an ‘Authorization’ request header:

Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya

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

Your site can only have one valid API access token at a time and once generated an access token does not expire.

NOTE: It is not necessary to obtain the access token before each API call and doing so may harm performance.

Obtain Access Token

Obtain Access Token
POST/v1/oauth2/token

Use your site’s site key and auth key (obtainable from the site settings page on www.turnto.com) to request an access token which can then be used to authorize subsequent requests to the API.

Note: Do not share or expose the access token.

If you call this endpoint multiple times, it will return the same access_token, until the token is invalidated either by using the /v1/oauth2/invalidate_token endpoint, or through your site’s settings page on www.turnto.com. Once generated, an access token does not expire.

Example URI

POST https://api.turnto.com/v1/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/oauth2/invalidate_token

Invalidates the access token passed in the body of the request if this is the currently active token for your site.

Please note that your site can only have one valid access token at a time. Any clients that are making API requests using your token will begin seeing authorization errors once the token is invalidated using this endpoint. Use this endpoint only if your access token has become compromised, or you have a security policy that requires periodically renewing the token.

Example URI

POST https://api.turnto.com/v1/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
Body
{
  "access_token": "R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya"
}
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/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/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

Resource Properties - Dimension

Dimensions are customer defined rating sub-dimension values that may be captured for a review.

Property Type Description
id number Identifier for the dimension
label string Label to be displayed
type number Dimension type: 1 = Rating, 2 = Range, 3 = Single Select, 4 = Multi Select
required boolean Is dimension value required when submitting review by widget?
average number The average value for this dimension
values[].id number Identifier for a dimension value
values[].label string Display label for a dimension value
values[].sortOrder number Sort order for a dimension value
values[].count number Number of times dimension selected in a review for this product

Product List

The product detail information describes the product.

Product List
GET/v1/products{?sku,locale}

This endpoint will return the product information for each SKU identified in the request. Up to 25 SKUs may be specified in a single request.

If an individual SKU is invalid or not found this will be reported in the list of results.

Example URI

GET https://api.turnto.com/v1/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
          }
        ]
      }
    ]
  },
  {
    "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
          }
        ]
      }
    ]
  }
]
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
averageRating number Average rating for this product
ratingBreakdown map Number of ratings received for this product broken down the rating value (1-5)
dimensions resource Custom values that can be assigned for this product

UGC Summary
GET/v1/products/ugc_summary{?sku,locale}

This endpoint will return the UGC summary for each SKU identified in the request. Up to 25 SKUs may be specified in a single request.

If an individual SKU is invalid or not found this will be reported in the list of results.

Example URI

GET https://api.turnto.com/v1/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": "700285064826",
    "questions": 1,
    "relatedQuestions": 0,
    "comments": 0,
    "answers": 1,
    "relatedAnswers": 0,
    "reviews": 7,
    "averageRating": 4.86,
    "ratingBreakdown": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 1,
      "5": 6
    },
    "dimensions": [
      {
        "id": 1,
        "label": "Overall Quality",
        "type": 1,
        "required": true,
        "average": "1.00",
        "values": [
          {
            "id": 1,
            "value": 1
          },
          {
            "id": 2,
            "value": 2
          },
          {
            "id": 3,
            "value": 3
          },
          {
            "id": 4,
            "value": 4
          },
          {
            "id": 5,
            "value": 5
          }
        ]
      },
      {
        "id": 2,
        "label": "Comfort",
        "type": 2,
        "required": true,
        "average": "2.00",
        "values": [
          {
            "id": 6,
            "sortOrder": 0,
            "label": "Low"
          },
          {
            "id": 7,
            "sortOrder": 1,
            "label": "Medium"
          },
          {
            "id": 8,
            "sortOrder": 2,
            "label": "High"
          }
        ]
      },
      {
        "id": 3,
        "label": "Impression",
        "type": 4,
        "required": false,
        "average": null,
        "values": [
          {
            "id": 9,
            "sortOrder": 0,
            "label": "Durable",
            "count": 0
          },
          {
            "id": 10,
            "sortOrder": 1,
            "label": "Stylish",
            "count": 1
          },
          {
            "id": 11,
            "sortOrder": 2,
            "label": "Modern",
            "count": 0
          },
          {
            "id": 12,
            "sortOrder": 3,
            "label": "Youthful",
            "count": 0
          }
        ]
      },
      {
        "id": 4,
        "label": "Weight",
        "type": 3,
        "required": false,
        "average": null,
        "values": [
          {
            "id": 13,
            "sortOrder": 0,
            "label": "Light",
            "count": 1
          },
          {
            "id": 14,
            "sortOrder": 1,
            "label": "Heavy",
            "count": 0
          }
        ]
      }
    ]
  },
  {
    "sku": "088989217022",
    "questions": 0,
    "relatedQuestions": 0,
    "comments": 0,
    "answers": 0,
    "relatedAnswers": 0,
    "reviews": 0,
    "averageRating": 0,
    "ratingBreakdown": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0
    },
    "dimensions": [
      {
        "id": 1,
        "label": "Overall Quality",
        "type": 1,
        "required": true,
        "average": null,
        "values": [
          {
            "id": 1,
            "value": 1
          },
          {
            "id": 2,
            "value": 2
          },
          {
            "id": 3,
            "value": 3
          },
          {
            "id": 4,
            "value": 4
          },
          {
            "id": 5,
            "value": 5
          }
        ]
      },
      {
        "id": 2,
        "label": "Comfort",
        "type": 2,
        "required": true,
        "average": null,
        "values": [
          {
            "id": 6,
            "sortOrder": 0,
            "label": "Low"
          },
          {
            "id": 7,
            "sortOrder": 1,
            "label": "Medium"
          },
          {
            "id": 8,
            "sortOrder": 2,
            "label": "High"
          }
        ]
      },
      {
        "id": 3,
        "label": "Impression",
        "type": 4,
        "required": false,
        "average": null,
        "values": [
          {
            "id": 9,
            "sortOrder": 0,
            "label": "Durable",
            "count": 0
          },
          {
            "id": 10,
            "sortOrder": 1,
            "label": "Stylish",
            "count": 0
          },
          {
            "id": 11,
            "sortOrder": 2,
            "label": "Modern",
            "count": 0
          },
          {
            "id": 12,
            "sortOrder": 3,
            "label": "Youthful",
            "count": 0
          }
        ]
      },
      {
        "id": 4,
        "label": "Weight",
        "type": 3,
        "required": false,
        "average": null,
        "values": [
          {
            "id": 13,
            "sortOrder": 0,
            "label": "Light",
            "count": 0
          },
          {
            "id": 14,
            "sortOrder": 1,
            "label": "Heavy",
            "count": 0
          }
        ]
      }
    ]
  }
]
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/products

This endpoint allows product information to be kept up to date. The product is uniquely identified by sku. If the product for the sku does not exist then it is created.

Request body JSON object properties

Property Required Note
sku Yes Unique identifier for the item in your catalog.
imageUrl No The URL of the image of your catalog item.
title Yes
price No Defaults to 0.00
currency No Defaults to USD.
active No Boolean - defaults to true.
url Yes The URL of the item on your site.
category No Name of the category this item belongs to.
categoryPath No If you’d like to pass TurnTo a category path for this product, you can include a JSON array of category objects, in the order of most general to the most specific. Each object in the array must include an ‘id’ field (which should be unique across categories as well as regular product SKUs, a ‘name’ field, and optionally a ‘url’ if your store has a page for this category.
keywords No Comma delimited list of keywords that apply to this item.
inStock No Boolean - defaults to true.
virtualParentCode No An arbitrary string used to group products.
isCategory No Is this a category rather than an orderable item - defaults to false.
members No If product is a bundle of other products, specify comma delimited list of skus.
brand No The product’s brand name. If used together with ‘MPN’, this field uniquely identifies the product.
mpn No (Manufacturer part number) The number which uniquely identifies the product to its manufacturer. If used together with ‘BRAND’, this field uniquely identifies the product across the entire catalog.
isbn No (International Standard Book Number) A unique numerical identifier for commercial books published since 1970 that can be found on the back of the book along with the barcode.
upc No (Universal Product Code) A unique numerical identifier for commercial products that’s usually associated with a barcode printed on retail merchandise. Used mainly in North America.
ean No (European Article Number) A unique numerical identifier for commercial products that’s usually associated with a barcode printed on retail merchandise. Used mainly outside of North America.
jan No (Japanese Article Number) A unique numerical identifier for commercial products that’s usually associated with a barcode printed on retail merchandise. Used in Japan.
asin No (Amazon Standard Identification Number) Uniquely identifies each product sold on amazon.com.
mobileItemUrl No The URL of the item on your mobile site.
localeData No A JSON field that allows the specification of locale specific product titles and urls. If specified, ‘title’ and ‘itemUrl’ are required, ‘mobileItemUrl’ is optional.

Example URI

POST https://api.turnto.com/v1/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": "",
  "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/orders/create

This endpoint will typically will be called from an order confirmation page. The customer first name, last name, and email address are required. An order item object is populated for each line item.

Request body JSON object properties

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

Property Required Note
orderId Yes Unique Id of the order to be created.
deliveryDate No Date of delivery, format is yyyy-MM-dd
locale No If omitted use site default.
postalCode No
emailOptOut No Set to the boolean value ‘true’ if the user is to receive no emails from TurnTo. Defaults to false.
user.firstName Yes
user.lastName Yes
user.nickName No
user.emailAddress Yes Email address is required to identify the user
user.externalId No
items[].lineItemId No
items[].title Yes
items[].url Yes
items[].sku Yes
items[].brand No
items[].price No
items[].itemImageUrl Yes

Example URI

POST https://api.turnto.com/v1/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/orders/cancel

This endpoint allows an entire order or an order line item to be cancelled. To cancel an entire order only the order Id is supplied. To cancel an order line item the sku matching the line item sku must be supplied.

Request body JSON object properties

Property Required Note
orderId Yes Id of the order to be cancelled.
sku No If provided only the order item with matching sku will be cancelled.

Example URI

POST https://api.turnto.com/v1/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
Body
{
  "orderId": "99977",
  "sku": ""
}
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 for which this media is associated with. Nested products block - see Products section
dateCreated date Date media created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)

Save Media

This endpoint is used to create media content. In the case of photos, the image is uploaded by including its Base64-encoded data in the request. Images are oriented based on their EXIF orientation data. For video, the URL link must be supplied which is then verified with the video provider. Up to 5 media items may be specified.

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

The media content must be associated with at least 1 catalog item and up to 10 SKUs may be specified.

Save Media
POST/v1/media

This endpoint

Request body JSON object properties

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

Property Required Note
locale No If omitted use site default.
user.firstName No
user.lastName No
user.nickName No
user.emailAddress No Either email address or externalId is required to identify the user
user.externalId No Either email address or externalId is required to identify the user
user.city No
user.state No
user.country No
user.ageRange No
user.shopperProfiles[].id No
user.shopperProfiles[].value No
catalogItems[].sku Yes The SKU of the catalog item that this media is associated with. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created.
catalogItems[].title No The title of the catalog item that this media is associated with. This can be omitted if the item already exists in your site’s catalog at TurnTo
catalogItems[].url No The URL of the catalog item that this media is associated with. This can be omitted if the item already exists in your site’s catalog at TurnTo
photo[].caption No The caption must be provided for each photo b64data supplied
photo[].b64data No Base64 encoded image
video[].caption No The caption must be provided for each video URL supplied
video[].url No Video URL link

Example URI

POST https://api.turnto.com/v1/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,/9j/4AAQSkZJRgABAQEAJAAkAAD/4gxYSUNDX1BST0ZJTEUAAQEAAAxITGlubwIQAABtbnRyUkdCIFhZWiAHzgACAAkABgAxAABhY3NwTVNGVAAAAABJRUMgc1JHQgAAAAAAAAAAAAAAAAAA9tYAAQAAAADTLUhQICAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABFjcHJ0AAABUAAAADNkZXNjAAABhAAAAGx3dHB0AAAB8AAAABRia3B0AAACBAAAABRyWFlaAAACGAAAABRnWFlaAAACLAAAABRiWFlaAAACQAAAABRkbW5kAAACVAAAAHBkbWRkAAACxAAAAIh2dWVkAAADTAAAAIZ2aWV3AAAD1AAAACRsdW1pAAAD+AAAABRtZWFzAAAEDAAAACR0ZWNoAAAEMAAAAAxyVFJDAAAEPAAACAxnVFJDAAAEPAAACAxiVFJDAAAEPAAACAx0ZXh0AAAAAENvcHlyaWdodCAoYykgMTk5OCBIZXdsZXR0LVBhY2thcmQgQ29tcGFueQAAZGVzYwAAAAAAAAASc1JHQiBJRUM2MTk2Ni0yLjEAAAAAAAAAAAAAABJzUkdCIElFQzYxOTY2LTIuMQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWFlaIAAAAAAAAPNRAAEAAAABFsxYWVogAAAAAAAAAAAAAAAAAAAAAFhZWiAAAAAAAABvogAAOPUAAAOQWFlaIAAAAAAAAGKZAAC3hQAAGNpYWVogAAAAAAAAJKAAAA+EAAC2z2Rlc2MAAAAAAAAAFklFQyBodHRwOi8vd3d3LmllYy5jaAAAAAAAAAAAAAAAFklFQyBodHRwOi8vd3d3LmllYy5jaAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABkZXNjAAAAAAAAAC5JRUMgNjE5NjYtMi4xIERlZmF1bHQgUkdCIGNvbG91ciBzcGFjZSAtIHNSR0IAAAAAAAAAAAAAAC5JRUMgNjE5NjYtMi4xIERlZmF1bHQgUkdCIGNvbG91ciBzcGFjZSAtIHNSR0IAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZGVzYwAAAAAAAAAsUmVmZXJlbmNlIFZpZXdpbmcgQ29uZGl0aW9uIGluIElFQzYxOTY2LTIuMQAAAAAAAAAAAAAALFJlZmVyZW5jZSBWaWV3aW5nIENvbmRpdGlvbiBpbiBJRUM2MTk2Ni0yLjEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHZpZXcAAAAAABOk/gAUXy4AEM8UAAPtzAAEEwsAA1yeAAAAAVhZWiAAAAAAAEwJVgBQAAAAVx/nbWVhcwAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAo8AAAACc2lnIAAAAABDUlQgY3VydgAAAAAAAAQAAAAABQAKAA8AFAAZAB4AIwAoAC0AMgA3ADsAQABFAEoATwBUAFkAXgBjAGgAbQByAHcAfACBAIYAiwCQAJUAmgCfAKQAqQCuALIAtwC8AMEAxgDLANAA1QDbAOAA5QDrAPAA9gD7AQEBBwENARMBGQEfASUBKwEyATgBPgFFAUwBUgFZAWABZwFuAXUBfAGDAYsBkgGaAaEBqQGxAbkBwQHJAdEB2QHhAekB8gH6AgMCDAIUAh0CJgIvAjgCQQJLAlQCXQJnAnECegKEAo4CmAKiAqwCtgLBAssC1QLgAusC9QMAAwsDFgMhAy0DOANDA08DWgNmA3IDfgOKA5YDogOuA7oDxwPTA+AD7AP5BAYEEwQgBC0EOwRIBFUEYwRxBH4EjASaBKgEtgTEBNME4QTwBP4FDQUcBSsFOgVJBVgFZwV3BYYFlgWmBbUFxQXVBeUF9gYGBhYGJwY3BkgGWQZqBnsGjAadBq8GwAbRBuMG9QcHBxkHKwc9B08HYQd0B4YHmQesB78H0gflB/gICwgfCDIIRghaCG4IggiWCKoIvgjSCOcI+wkQCSUJOglPCWQJeQmPCaQJugnPCeUJ+woRCicKPQpUCmoKgQqYCq4KxQrcCvMLCwsiCzkLUQtpC4ALmAuwC8gL4Qv5DBIMKgxDDFwMdQyODKcMwAzZDPMNDQ0mDUANWg10DY4NqQ3DDd4N+A4TDi4OSQ5kDn8Omw62DtIO7g8JDyUPQQ9eD3oPlg+zD88P7BAJECYQQxBhEH4QmxC5ENcQ9RETETERTxFtEYwRqhHJEegSBxImEkUSZBKEEqMSwxLjEwMTIxNDE2MTgxOkE8UT5RQGFCcUSRRqFIsUrRTOFPAVEhU0FVYVeBWbFb0V4BYDFiYWSRZsFo8WshbWFvoXHRdBF2UXiReuF9IX9xgbGEAYZRiKGK8Y1Rj6GSAZRRlrGZEZtxndGgQaKhpRGncanhrFGuwbFBs7G2MbihuyG9ocAhwqHFIcexyjHMwc9R0eHUcdcB2ZHcMd7B4WHkAeah6UHr4e6R8THz4faR+UH78f6iAVIEEgbCCYIMQg8CEcIUghdSGhIc4h+yInIlUigiKvIt0jCiM4I2YjlCPCI/AkHyRNJHwkqyTaJQklOCVoJZclxyX3JicmVyaHJrcm6CcYJ0kneierJ9woDSg/KHEooijUKQYpOClrKZ0p0CoCKjUqaCqbKs8rAis2K2krnSvRLAUsOSxuLKIs1y0MLUEtdi2rLeEuFi5MLoIuty7uLyQvWi+RL8cv/jA1MGwwpDDbMRIxSjGCMbox8jIqMmMymzLUMw0zRjN/M7gz8TQrNGU0njTYNRM1TTWHNcI1/TY3NnI2rjbpNyQ3YDecN9c4FDhQOIw4yDkFOUI5fzm8Ofk6Njp0OrI67zstO2s7qjvoPCc8ZTykPOM9Ij1hPaE94D4gPmA+oD7gPyE/YT+iP+JAI0BkQKZA50EpQWpBrEHuQjBCckK1QvdDOkN9Q8BEA0RHRIpEzkUSRVVFmkXeRiJGZ0arRvBHNUd7R8BIBUhLSJFI10kdSWNJqUnwSjdKfUrESwxLU0uaS+JMKkxyTLpNAk1KTZNN3E4lTm5Ot08AT0lPk0/dUCdQcVC7UQZRUFGbUeZSMVJ8UsdTE1NfU6pT9lRCVI9U21UoVXVVwlYPVlxWqVb3V0RXklfgWC9YfVjLWRpZaVm4WgdaVlqmWvVbRVuVW+VcNVyGXNZdJ114XcleGl5sXr1fD19hX7NgBWBXYKpg/GFPYaJh9WJJYpxi8GNDY5dj62RAZJRk6WU9ZZJl52Y9ZpJm6Gc9Z5Nn6Wg/aJZo7GlDaZpp8WpIap9q92tPa6dr/2xXbK9tCG1gbbluEm5rbsRvHm94b9FwK3CGcOBxOnGVcfByS3KmcwFzXXO4dBR0cHTMdSh1hXXhdj52m3b4d1Z3s3gReG54zHkqeYl553pGeqV7BHtje8J8IXyBfOF9QX2hfgF+Yn7CfyN/hH/lgEeAqIEKgWuBzYIwgpKC9INXg7qEHYSAhOOFR4Wrhg6GcobXhzuHn4gEiGmIzokziZmJ/opkisqLMIuWi/yMY4zKjTGNmI3/jmaOzo82j56QBpBukNaRP5GokhGSepLjk02TtpQglIqU9JVflcmWNJaflwqXdZfgmEyYuJkkmZCZ/JpomtWbQpuvnByciZz3nWSd0p5Anq6fHZ+Ln/qgaaDYoUehtqImopajBqN2o+akVqTHpTilqaYapoum/adup+CoUqjEqTepqaocqo+rAqt1q+msXKzQrUStuK4trqGvFq+LsACwdbDqsWCx1rJLssKzOLOutCW0nLUTtYq2AbZ5tvC3aLfguFm40blKucK6O7q1uy67p7whvJu9Fb2Pvgq+hL7/v3q/9cBwwOzBZ8Hjwl/C28NYw9TEUcTOxUvFyMZGxsPHQce/yD3IvMk6ybnKOMq3yzbLtsw1zLXNNc21zjbOts83z7jQOdC60TzRvtI/0sHTRNPG1EnUy9VO1dHWVdbY11zX4Nhk2OjZbNnx2nba+9uA3AXcit0Q3ZbeHN6i3ynfr+A24L3hROHM4lPi2+Nj4+vkc+T85YTmDeaW5x/nqegy6LzpRunQ6lvq5etw6/vshu0R7ZzuKO6070DvzPBY8OXxcvH/8ozzGfOn9DT0wvVQ9d72bfb794r4Gfio+Tj5x/pX+uf7d/wH/Jj9Kf26/kv+3P9t////4QCMRXhpZgAATU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAASgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAAAkAAAAAQAAACQAAAABAAOgAQADAAAAAQABAACgAgAEAAAAAQAAAGygAwAEAAAAAQAAAG0AAAAA/9sAQwACAgICAgIDAgIDBAMDAwQGBAQEBAYHBgYGBgYHCQcHBwcHBwkJCQkJCQkJCwsLCwsLDQ0NDQ0ODg4ODg4ODg4O/9sAQwECAgIEAwQGAwMGDwoICg8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8PDw8P/8IAEQgAbQBsAwEiAAIRAQMRAf/EAB0AAAEFAQEBAQAAAAAAAAAAAAYDBAUHCAIBAAn/xAAaAQACAwEBAAAAAAAAAAAAAAADBAACBQEG/9oADAMBAAIQAxAAAAEdkQSaRPJzNiRS5K9CrBrJoUxJDzrtS1dYmWIMIF6UgN0Rp2lIntUOdAegdT4c2RjvDdc3tGCvm4H1z82vka5qWIiCtxkToJXFoyek+zEvqCnpl7h1plU98zqW8VUcfSghHKwTKx1Qt6ZlvXXPzGRQLEybZfnPz/JmLD1INNBLnvGZnSJC9lruxN1NCPXWNdi431kDCx6C0WMxoeQshmk7D7paa2bRbC2YmhDyLhpbB2a4tzwSctQFFdMvR4iRGOOicvjUuAt1ZpCp4mtQEQpK89lXzR5BpteYl0zW1yZb5559An51wrJeOqKl0Bmxs6ArBVi6sNMEqkr4z7G4IawduYIGbNrLSv6dR+yawrKucl5s/8QAJxAAAgICAQQCAQUBAAAAAAAAAwQBAgAFEwYREiEUMRAHFSIjMkH/2gAIAQEAAQUCYLUOIl5ZMq1U6u3MKXh0LPn7j3gbx34pmIFMZxZYNsmls4pxgsGMlIakJ40nbaeT22YA1Bxdsr5Z5Yges0vEkrQF+xR2jLRMRkEr5KurhzW7D5rQK0kDqYzEa6dWPl+lthXGBNKFEbisocTFJXm0eFa5xQSfHwyv3y27dP8AlZhSbGoYQqRFOSflxYuw1ieyUbVKmzom5G2QRJiePxrSeSAmvlZzzmM0f9VU2xDBJzVIMtSj3EtRVR69M2aQdjj4xJbc7X9NL+QpmIPA73yJ9wMtq6OakToxfl1Tw2jgbH33ylvmnPE05rHUM1Sdso4nsw1PnEQFuUd8+p1z1VCdN6qhCB2fxNgu8Vxwd7BhcEGUZ6cVZvvUp1XTgv44kwWMFtD2FrdrWMgRTQ1r3VDCEYttJuRoINaQmzzRdPbbkcpRWFXTXvTaiu116zx9PE70CszZe+sWnY0Dr6nn9kNXH9fwn/a61NdQA3tLQ2pZEasw/BZEktviSigJMf6g7Ln2Fyef4RYGtbV74ZdmFcMDbvykqOsYdbuVlT5A0j0YD5XnA1v36g6kU0YDFK0T8UmIzXU529NMShWnln1l6eJOGO+xQcCZNkT4ysVDTqk12XYn+H/MjNEvZsNNfU0du2epy1eQf+bTEThtcsa7HTZSk2XTawUvr81950MqQavNx4syNnP85S2WjJ955ejE8IYkjebYNQbL8afWFaYRU+MrSveNbQSzH3HftNJm1cv7jtEw5EcfU4aifzVLVO708guKIrHbYdSbErn/xAAjEQACAgIBBAIDAAAAAAAAAAAAAQIRAxIhBBAgMRNRIkFh/9oACAEDAQE/AUzT6Jpi7UUJmONwsdP2SxL9C44fhGlBWfJGfC9macth/wBNSiL1doyvZLQ6fH+SMmCX0ZvZglZJDMMtZJiXNnU9U2tVwiUrEzbvh6jXiRkzRcaXdyJR1deUIbH/xAAiEQACAgICAgIDAAAAAAAAAAAAAQIDERIEISIxEBNCUWH/2gAIAQIBAT8BcOj7E+pFTTRJDljo3NyVOejkeM9URyn0Rvf5FsMrZGTYf9LsytlglXKHbKox0OP5ZG8ezJKKnHDI1uE5facmz2l6IesnAj4dfs5lWvbRjJF4RetoNG5XJ2eJTUoRUSccrBfUovr4yXcZS7RxKnCe8vmxZfRCe62QjUTRW8pFs8E54P/EADgQAAEDAQYEAwUHBAMAAAAAAAEAAgMRBBIhMUFREyIyYRBxgQUjQpGhFCBDUmJywRWiseEz0fD/2gAIAQEABj8Cq7qQvtBcekhOibzOrjRcN5G1TonWqJtI60Hjcfkq18O+y58F28CdjTdMc6TpOVD/AOqmWpzeWXla3L1TZLNFcbTFMbDfwGIdos/DFXT1DLugRyFVIxGSx5lgAuX6LHJVa0vdtl9UJH4hnTt6IXl05ZHdXhVjjsqwPDvNcG2MLSg4ZJr8PRF0dCzuVRpvHbNOpgTpRUc017IosGuaCAWfMq0ojDC3Buchy9N0YpeunK/UFPsU4uvb9e4QszqUl6a7qh9130PouCwC8fiGCIkGXdXqXu9aIrNNedSgxh5t1edQs3K5F/zMssdaX3Y47BozUZdI+ctwbxOVtT+hv8qG02prRNC4XHtw1ydu0p8VmdURTBzaGtMcvTJNMpocm1zV17fPDL1TTeY5tK1V5tMdwfBz2tJa3MjRNdq3+FH9smbY4XnBz+p37W5+qlhYZbRHH8T6Mbn808RktEdG3dMdqbKxW41MUeBb8IO/qjMyO6G0u1880aZmmSmmi6HTO+V5Vj5mtIFNU6MVOmJwV9x5NAFelkId8vAsmF6zTEcQbfq+WakbD0B94Rvzu6GuoKktEzgZZZedz8QB/pTGyScr7rOIzEIRxxvPEkpU58uZp5qk/wBVfY9wutut1aPIK2SCWsrIuRwFKaK9oKpslmfwpAr0wc0j8UYU80TPO66T1OGHrt6oPb9llGjrqkgnicHR9VATRcONhcToE6yWxkxms9TEI2Vw0xyHqh7W9nNMsE3NJCwgPa74gK91WYfYoK3g1px/2Ux8DQXNF3mxTYMzXHVOsTI3GRvUR0j1T49ZpGR/3Yod1eABGxQuXHyFgfwwaUCpM9jZxykDVvdUsz2RN/Kx9BVSySZyOAwyoBgmz8NpLnAP8twpQI7rZ6wn/tFjj7qZ7gW7Ea+DuFQvpy1yRitEjmxfoo36jFUYKKH2azpso4j/AN78B8h/lEeALJJYnOreuYYaYoMtsjpIpMKvwLX6YtzQDJ308x/KkhcKitWrnUzGfisvjzC4kXX1tr+YaIOjz2VFzK8feWh493ENT32CktVodekleXvPc+JvaZeaihaeG+Z91jgBgUxtribHOzlkAxFQsc81imO2NFhrj6r+oezBed+ND+fu39X+UJ4T5jUHYjRUJAKfK49giPueznx8rxapGyup8DBUfWi4rnOBdibtUHrzVNUO6pkuK9t2T87OU+tESLe9rToRU/NPY0vmtHMeM/amAoiPuWgy4e9uN+WKugI3DUUCporqxQ38LzkbouxjMlWiNnTew8eJd5bO5j3bZ1FeyYAKFxMjv3ONSqkLgwto0imew8a+Nw6Km+Cq34m18LK13xSH+1WiQCpc+6fRU7KW5I6JrXFrWsOgX//EACYQAQACAgICAgEFAQEAAAAAAAEAESExQWFRcYGREKGxweHw0fH/2gAIAQEAAT8hwRti9/U4ZEVtXhg9I2f7psWZcbl9y5N0GHRFSZzy1fE/YiPbvxmFh8YclLcSxSPaN39Ss7qBw9RmuywV+ufSKwZm/r9Vxy1LDweO4gYxcxzjxGy8pXgzBEPKXNbh/UOrFyWQG2sv/f2lZYC88fURX/MVaRRXKVYCmcv/ACdcMQ+TwmBtATrXB8dyiuJQEG1EKPlTV+JalODCVQjyYryPMTlayuHqOwtVNqfjxA/T0V6ZdBFnLD1G6FV2/wAqDs9beRE5MTdFfody57O4HHYS3aNQPlkPVtwvjyTKFc/eybBYK0eIXMsSNldfcdALywHvGFRFf1JS9eVjr2w22bh+1X4nA23OC8i9T2xklUeY2follza0RpR24XhkU+LiNP6o0B/ZWLph3LYYtaDetmpeygFmC3MXZwlmDVhq/fGfEEmnKsA8saCGUcf9hOIL/wADKkeSUh/rKezFtlkb8xprRn0+XtRNyHRboIFuWOEly7zQHtccWU7yrf476qGRzmplGn7Sw7wOV3BiFkOEfySyJStDNzL+4tKFPCHfcoKFebXZKIocHDiwdxWyMiIE00xT9A5PWXKBCFVegE4zwxWOBeAso60DRDi0mBZlxRem416A3iDdzWQSs4FU1uzwniVMeSXwFPGohZEyG4JvMGjH0vEuvUXSgp2Rhb7K3HjzAL5AqArnVfRLCyZOHwxkc1ULaVrTw6YJ1uDxHz88W2HiuGwS5lHqB0Ee1mZXAGqKPK1bTysTQcPB5e7iau41LOLquJUHnCbc50vrZPESj2H9EXa1ZbkhHT7jtSiPSM1eHnuVUUI9gYHpazHyh1flUVM42irPKg27f+SjQA1W2EOYP61HyU0e5bMUXaB7NzEGxifcLtd1FattpZ/hzKEU7ry7YL+/jlR9t+kQJoD9Pwt6hjp4O3PiG2zfKoXEemvmFDHi6vkLK8VsfBcv6b8cTmlkfU57xEzpiXyPlqMFQwrCJhHsZ7yBKGptLB9wfDy/zO0lo7K6NHQSqPZ+DlnSzV9B6eYWjBEW03kMcTw+Bsso+Hc5PQy3HRGHDHpb2umV8AqdRgRW9NO7ECdPD45Sso8MToBol5YPpPE+UXFv2/CTJAWBqG4OoPGPlAWqt7oiqmaKYpJwJqVD95zNUv3LEZHEaLcq1X22+YY2NEP86l+kYzIsAwB0e5SlwmGbx+Bavj7m5UyTWD92WyCQqndfZcu/ZiXqqzMdfabnCZ2TMyZ6qaxyuSc1EiEtR4fxuJU2/S7BDsSnxuf6Yuo9EDIbeZhXpWniHPWI88wgglTzALfEwRZiXCYJL+qemvwmGGolmNmPcErbCbBz7VYTxmHxEihyoLWcZXzP/9oADAMBAAIAAwAAABDI7TVfEHLb/Hv7GFMzmmCtBnD8WV1H96PYvarDQ2g3Z+DLHhgb/8QAIBEBAQEAAgMAAgMAAAAAAAAAAQARITEQQVEgYXGBof/aAAgBAwEBPxDR4h5sE9SyDefOpyWEoFw4vQ5bUZZAvRF54QoohhwEUT6t5wT8yh2EG3uevmxiPcRV/b+of5gGLjFstdhQiMLHx7M9/wA/bcv2YdLabvlR3Ey72efGP4QO/C5aOW//xAAfEQEBAQACAgIDAAAAAAAAAAABABEhQTFRsfAQodH/2gAIAQIBAT8Qw2+bZhYDbpnWo5w2KgPD3PGN7kP3MvSHAHYQByLBdUUDys0g8Eyy57m3IMwnBeH3n9uH9laSIB48r4LbyCzyJ8vcxH31LzEs4HL1Gnr6wMogDiXqYz435haePxszwoFzk8onXNorPhP4Gt//xAAiEAEBAAICAwADAQEBAAAAAAABEQAhMUFRYXGBkcGhsdH/2gAIAQEAAT8QhEdAGzLAce3rHUu9VB4gGbN6+4jNDAkl4LI2/MfTnGpwF2wQOvzgSguHJv4K7efGbotXm/zPBZplxpMXJiztB0KucGicYvpuzAec3B5fM/pzlSl8Ns8HD8we5Hmb/RhUKk9r+c2y0YhDtOQvqmCyA7VjrVPQoDDsaqASUSJNe2czGLEqQjvSxa2+7k/mr74eQK8hjyr4Nft/mHSQdH/mbUsOabMg9KWx5ny9jxvESwmm3wqj1MYhEiJW8ppH21gDdRAp7O1nrjEgAXlt9GA0saoXvnZ8wADDfWvva4dz4mSG1Yo7VYHvDQIIECKyaBy3d94ki7ILuJRHH55pA1zL8/GQtpeFHtev1k1XuhfO8Xgq9zwZB847mNtJ9gu12OaAyp8G2te28tt+jrzdgnnCFkR1DkHBfMjmq3QxQNlBAfd4pTRgodRDHtut8/8AMCRAwlNHQjkvJxecprSnaej7mo6h3o0f+YJVpUtf1gA7t+K+fWKqdJ6fBMfLNHbjUcxzU11A8JwmsXjpgRlV+UHXcTnGiO2g3UetE8hicagl5bcoeyXNQ+h0J3OB9d56oYAeTX4N5Qu0NgHFXL33iEDIZEiAeDL6cvj4R0k5c2EfL0B4nF/ObfbU7+UD8ua7vKN34hm7cgFoqQ8EDMEBnQ6qG7sBvTgW8ABKSrwoLVhDgffL3wFOikUN24dfIaI5s2NNs4qAYk31z1LiMUS7I4VBV4A3iixHQX3yA+HGA7J9xWuiyRSBDW/m+MMUDHkap/uSQl0s2uwULCGym8sq1qOugOwUO5vHGNsK00Q4Ds86cDhX4FuXjjTsVsHRFaEoXtVCA2F7csnaKNx4uibfhhPCaBVU63W93vD+awA7j3CJx1gnqYM+LtR1rFgzDtILoKh4chJm0r4BpzhD8s8ic92U5io4RNxgGFh6bCk4RUWFsOhCSsvNIBtBQ2172DArwyUBDAJ6mzkWQmWK1kxad6gVNvtXh/7gBThBEiqCKFFPLgjuTCIPZIoLxbLkAyQE6BMSFE69E6HkG7x2M84QG4kWCHGAGCOWAmiPUfWasGVlHAsWXk04SX/M2gk1I4dG9ZfDNS+TuSd3K6mKI1HyQwdxwFuZG13QqrQrFoDRYy12h0Q1KWp1hTcHV2UtXsvbh07vAWEeB1gpfikFE3o2booXBvRucpIfCuC5p8g3sv7yQHhruTgiJ0+ebjAuyfYxFg6Cxw4QocNBjk/A0d3NqJRkS1VKSlwSKIcBthotrB4bwWkIFxwB2jr7jPTQbKfEKah4x0FwBVDeG3gweeRCQTZkNaNyI0hD/pmkXtHeg8D69ecYBpVsuxHtcPI2pxQOPNYeKmH/AKMPD2MFNH6xJQW7nSKq2pdo4LNaqAFKXsAsjUv2SAqdoQm+1mMCDnrzD5cj0Ugu2xr5m7UElA4HoKmJwRfbR2rwbx1cgADtnQnYBEeEwXIx085tDtCazlM90gcURnL8BQOnxxy+wVQIKsJWZLN5H83EB+5qgOyaUez1eGIwIbzTN9EFOzrDmRvJTT1FBQd7B1mjXVPoj/hMAEjUeBycekbwSPy4sBEvC3MPeGm7cAPlIADhQHKO8M8mtTOBjWkBHNPADbfz0YhR3rOofi4B2kD+4A7rivDiPA5DpG2p47baRqxijoaWBAIDKAfmToTgF1t3hsm5Dr8mDBGh3p/cKQ00E3pveVB0F3lk9ZRmtCTqWYuvQV900CftlzCBhgiiGpRYq7U4tAPSYaeZsxccQVUB5UB/rl++QJfL9x/X3EweXZJynn1lgTpNjofpMeZiijZ+8BvQ0yGtX1grJSUDljjDc/y4qYPZ4+4aCd0rb8yxBU7atZ42EHvNyARCAm/Tc94D5XjLSpDAJwdCpspwHBQT4Oxgbti/AxWhI0VwbFFRUFtNgW9zGs8jv1eMrm683+YgTUu/ORGldznFWuZp5usHOQDd3+ME6h7mk1zrJpc4EB/Ib7y5r1EreXoug89ZyMYo3pDGo13OMpopUXiIT8Yi6qTiVKqFdOZNZ//Z"
    }
  ],
  "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/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/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
    }
  ]
}

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/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/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/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/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/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/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/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/questions/{id}/voteup

This endpoint registers an up vote for a question.

Example URI

POST https://api.turnto.com/v1/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/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/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 the answer was created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
reviewedDate date Date that the answer was reviewed by moderator (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
text string Answer text
textLength number Number of characters in answer text
locale string Locale of answer
published boolean Is published?
csFlag boolean Is flagged for customer service?
inappropriateFlag boolean Is inappropriate?
reviewedFlag boolean Is reviewed?
autoModerated boolean Is auto moderated?
upVotes number Number of up votes received
thanked boolean Is thanked?
isStaff boolean Is staff?
purchaseDate date Date product purchased (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
itemQuestionId number TurnTo unique ID for the question
tags string List of tag codes associated with this answer
user resource The user that posted this answer. Nested user block - see Users section
userIpAddr string The IP address of the UGC author
catalogItems resource Products for which this answer is also applicable. Nested products block - see Products section
replyCount number Number of replies posted for this answer
replies resource Replies posted for this answer. Nested replies block - see Replies section

Question Answers

Question Answers
GET/v1/questions/{id}/answers{?publishedOnly,locale,limit,offset,sort}

This endpoint will return a list of answers for the specified question. By default, the answers will be sorted to return Best Answers first. Additional options to sort using date created, text, text length, and up votes are available. The best answer for a question is indicated by the boolean property bestAnswer being set to true.

Results may be filtered by published status and locale. Pagination of results is supported using limit and offset parameters.

Example URI

GET https://api.turnto.com/v1/questions/12345/answers?publishedOnly=true&locale=en_US&limit=50&offset=10&sort=textLength:desc
URI Parameters
HideShow
id
number (required) Example: 12345

The ID of the question.

publishedOnly
boolean (optional) Default: true Example: 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: 50

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: textLength: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/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/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/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/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/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/answers/{id}/voteup

Registers an up vote for an answer.

Example URI

POST https://api.turnto.com/v1/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/answers/{id}/flag

Flag an answer as inappropriate.

Example URI

POST https://api.turnto.com/v1/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/answers/{id}/thank

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

Example URI

POST https://api.turnto.com/v1/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/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/answers/12345/replies?publishedOnly=true&locale=en_US&limit=50&offset=20&sort=textLength:desc
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: 50

Maximum number of replies to show.

offset
number (optional) Default: 0 Example: 20

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

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

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/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/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/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/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/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
catalogItem resource Product for which this comment was posted. Nested products block - see Products section

Comment List

Comment List
GET/v1/comments{?sku,publishedOnly,tags,locale,limit,offset,sort}

This endpoint will return a list of Comments for a catalog item.

Options are available to filter results by published status, tag code, and locale.

Pagination and sorting of results is supported.

Example URI

GET https://api.turnto.com/v1/comments?sku=12345&publishedOnly=true&tags=CSR,DAM,SOT&locale=en_US&limit=50&offset=10&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: 50

Maximum number of comments to show.

offset
number (optional) Default: 0 Example: 10

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",
      "catalogItem": {
        "sku": "11112222",
        "title": "MultiChef",
        "url": "www.topchef.com/food-processors/multichef"
      },
      "orderId": "5555522",
      "user": {
        "nickName": "Andy A.",
        "firstName": "Andy",
        "lastName": "Adamson",
        "emailAddress": "andrew@sample.com",
        "externalId": null,
        "city": "Miami",
        "state": "FL",
        "country": "US",
        "ageRange": 1
      },
      "tags": []
    },
    {
      "id": 7,
      "text": "I love all the attachments!",
      "locale": "fr_CA",
      "textLength": 160,
      "published": true,
      "dateCreated": "2015-06-30T11:43:06-04:00",
      "catalogItem": {
        "sku": "11112222",
        "title": "MultiChef",
        "url": "www.topchef.com/food-processors/multichef"
      },
      "orderId": null,
      "user": {
        "nickName": "Andy A.",
        "firstName": "Andy",
        "lastName": "Adamson",
        "emailAddress": "andrew@sample.com",
        "externalId": null,
        "city": "Miami",
        "state": "FL",
        "country": "US",
        "ageRange": 1
      },
      "tags": [
        "CSR"
      ]
    },
    {
      "id": 5,
      "text": "This Master Chef has loads of power and more speeds than you will ever need!",
      "locale": "en_US",
      "textLength": 76,
      "published": true,
      "dateCreated": "2015-06-30T11:43:05-04:00",
      "catalogItem": {
        "sku": "11112222",
        "title": "MultiChef",
        "url": "www.topchef.com/food-processors/multichef"
      },
      "orderId": null,
      "user": {
        "nickName": "Andy A.",
        "firstName": "Andy",
        "lastName": "Adamson",
        "emailAddress": "andrew@sample.com",
        "externalId": null,
        "city": "Miami",
        "state": "FL",
        "country": "US",
        "ageRange": 1
      },
      "tags": []
    }
  ],
  "offset": null,
  "limit": null,
  "total": 3
}
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/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/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",
  "catalogItem": {
    "sku": "11112222",
    "title": "MultiChef",
    "url": "www.topchef.com/food-processors/multichef"
  },
  "orderId": "5555522",
  "user": {
    "nickName": "Andy A.",
    "firstName": "Andy",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com",
    "externalId": null,
    "city": "Miami",
    "state": "FL",
    "country": "US",
    "ageRange": 1
  },
  "tags": []
}
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/comments

Creates a new Comment for a catalog item. An authorization token is required to create a Comment. A Comment is created by posting a JSON object in the body of the request.

A nested user object describes the author of the Comment. A user will be identified either by email address or a unique external ID that is maintained in your system. A nested catalogItem object describes the item that is the subject of the Comment.

The comment may optionally be associated with an order previously created on TurnTo system by supplying its order Id.

Request body JSON object properties

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

Property Required Note
text Yes
locale No If omitted use site default.
user.firstName Yes
user.lastName Yes
user.nickName No
user.emailAddress No Either email address or externalId is required to identify the user
user.externalId No Either email address or externalId is required to identify the user
user.city No
user.state No
user.country No
user.ageRange No
user.shopperProfiles[].id No
user.shopperProfiles[].value No
userIpAddr No The IP address of the UGC author
orderId No The Id of an order that this comment is associated with. The order must already exist at TurnTo
catalogItem.sku Yes The SKU of the catalog item that this comment is about. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created.
catalogItem.title No The title of the catalog item that this comment is about. This can be omitted if the item already exists in your site’s catalog at TurnTo
catalogItem.url No The URL of the catalog item that this comment is about. This can be omitted if the item already exists in your site’s catalog at TurnTo

Example URI

POST https://api.turnto.com/v1/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",
  "catalogItem": {
    "sku": "11112222"
  },
  "orderId": "5555522",
  "user": {
    "nickName": "",
    "firstName": "Andy",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com",
    "city": "Miami",
    "state": "FL",
    "country": "US",
    "ageRange": 1
  },
  "userIpAddr": "123.456.789.100"
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/comments/{id}
Body
{
  "id": 8,
  "text": "This Master Chef has loads of power and more speeds than you will ever need!",
  "textLength": 76,
  "locale": "en_US",
  "published": true,
  "dateCreated": "2015-07-01T09:49:43-04:00",
  "catalogItem": {
    "sku": "11112222",
    "title": "MultiChef",
    "url": "www.topchef.com/food-processors/multichef"
  },
  "orderId": "5555522",
  "user": {
    "nickName": "",
    "firstName": "Andy",
    "lastName": "Adamson",
    "emailAddress": "andrew@sample.com",
    "externalId": null,
    "city": "Miami",
    "state": "FL",
    "country": "US",
    "ageRange": 1
  }
}
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
catalogItems resource Product(s) for which this review is applicable. Nested products block - see Products section
dimensions resource Custom dimension properties that can be captured for this product. Nested dimensions block - see Products section
media resource Published media associated with this review. Nested media block - see Media section
responses[].text string Response text
responses[].locale string Locale of response
responses[].user resource The user that posted this response. Nested user block - see Users section
responses[].dateCreated date Date response created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
syndication.sourceName string Syndication source name
syndication.siteUrl string Syndication source site URL
syndication.logoUrl string Syndication source logo URL

Review List

Review List
GET/v1/reviews{?sku,related,includeRelated,includeRatingOnlyReviews,publishedOnly,tags,locale,dateCreatedFrom,dateCreatedTo,limit,offset,sort}

This endpoint can be used to return a list of reviews associated with a catalog item. The catalog item is identified by the ‘sku’ parameter.

Options are available to return direct reviews, related reviews, or a combined list containing both. Direct reviews are reviews that were created for a catalog item. Related reviews are reviews that are related to a catalog item, either as Virtual Parent Siblings, or as bundle parents.

To return reviews created within a specified time period the ‘dateCreatedFrom’ and ‘dateCreatedTo’ parameters should be used.

Any published media content associated with a review will be embedded with the review.

Options are available to filter results by published status, tag code, and locale. Pagination of results is supported via the ‘limit’ and ‘offset’ parameters.

Example URI

GET https://api.turnto.com/v1/reviews?sku=12345&related=false&includeRelated=false&includeRatingOnlyReviews=true&publishedOnly=true&tags=CSR,DAM,SOT&locale=en_US&dateCreatedFrom=2015-09-14T00:00:00-04:00&dateCreatedTo=2015-09-14T23:59:59-04:00&limit=50&offset=10&sort=textLength:desc
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

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

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

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.

limit
number (optional) Default: 50 Example: 50

Maximum number of reviews to show.

offset
number (optional) Default: 0 Example: 10

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

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": 7,
      "locale": "en_US",
      "rating": 2,
      "title": "An awesome jacket!",
      "text": "This dinner jacket fits perfects and looks absolutely amazing.",
      "textLength": 62,
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": true,
      "autoModerated": false,
      "published": true,
      "incentivized": false,
      "upVotes": 0,
      "downVotes": 0,
      "orderId": null,
      "dimensions": [
        {
          "type": 1,
          "dimensionId": 1,
          "dimensionLabel": "Overall Quality",
          "value": 4
        },
        {
          "type": 2,
          "dimensionId": 2,
          "dimensionLabel": "Fit",
          "value": 7,
          "label": [
            "Spot on"
          ]
        },
        {
          "type": 3,
          "dimensionId": 3,
          "dimensionLabel": "Occasion",
          "label": [
            "Formal"
          ]
        },
        {
          "type": 4,
          "dimensionId": 4,
          "dimensionLabel": "Impression",
          "label": [
            "Stylish",
            "Modern"
          ]
        }
      ],
      "responses": [
        {
          "text": "Thank you for your review.",
          "locale": "en_US",
          "user": {
            "nickName": "Andrew A.",
            "firstName": "Andrew",
            "lastName": "Adamson",
            "emailAddress": "spike@dog.org",
            "externalId": null,
            "city": null,
            "state": null,
            "country": null,
            "ageRange": null,
            "badge": null,
            "shopperProfiles": []
          },
          "dateCreated": "2018-08-31T15:33:11-04:00"
        }
      ],
      "tags": [
        "CSR",
        "INA"
      ],
      "media": {
        "photo": [
          {
            "id": 13,
            "type": "photo",
            "caption": "so cool!",
            "imageType": "jpeg",
            "width": 108,
            "height": 109,
            "locale": "en_US",
            "published": true,
            "dateCreated": "2018-08-31T15:27:03-04:00",
            "normalUrl": "http://www.turnto.com/imagestore/media/sss-sss/06BF7F7E4FE46518D9486D6A67B95D76_1535743622388_1_L1000.jpeg",
            "thumbnailUrl": "http://www.turnto.com/imagestore/media/sss-sss/06BF7F7E4FE46518D9486D6A67B95D76_1535743622388_1_PZ320.jpeg",
            "originalUrl": "http://www.turnto.com/imagestore/media/sss-sss/06BF7F7E4FE46518D9486D6A67B95D76_1535743622388_1.jpeg",
            "tags": []
          }
        ],
        "video": [
          {
            "id": 14,
            "type": "video",
            "caption": "build customer community",
            "provider": "youtube",
            "providedLink": "https://www.youtube.com/watch?v=Vr_r2uBg56g",
            "thumbnailUrl": "https://i.ytimg.com/vi/Vr_r2uBg56g/hqdefault.jpg",
            "thumbnailWidth": 480,
            "thumbnailHeight": 360,
            "width": 480,
            "height": 270,
            "authorName": "TurnTo",
            "authorUrl": "https://www.youtube.com/user/TurnToNetworks",
            "providerId": "Vr_r2uBg56g",
            "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/Vr_r2uBg56g?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen></iframe>",
            "s88thumbDims": {
              "width": 117,
              "height": 88,
              "scaledTo": "h",
              "targetLeft": -15,
              "targetTop": 0
            },
            "s64thumbDims": {
              "width": 85,
              "height": 64,
              "scaledTo": "h",
              "targetLeft": -11,
              "targetTop": 0
            },
            "locale": "en_US",
            "published": true,
            "dateCreated": "2018-08-31T15:27:03-04:00",
            "tags": []
          }
        ],
        "audio": []
      },
      "user": {
        "nickName": "Andy",
        "firstName": "Andrew",
        "lastName": "Adams",
        "emailAddress": "aa.90506@mymail.com",
        "externalId": null,
        "city": "Springfield",
        "state": "OH",
        "country": "US",
        "ageRange": 2,
        "badge": null,
        "shopperProfiles": [
          {
            "id": 3
          }
        ]
      },
      "syndication": null,
      "reviewedDate": "2018-08-31T15:32:30-04:00",
      "purchaseDate": null,
      "dateCreated": "2018-08-31T15:27:03-04:00",
      "acceptedTermsAndConditions": true,
      "catalogItems": [
        {
          "sku": "1234567",
          "title": "Dinner Jacket",
          "url": "www.sample.com/products/Dinner Jacket",
          "category": null,
          "reviewCount": 1,
          "ratingCount": 1,
          "averageRating": 2,
          "ratingBreakdown": {
            "1": 0,
            "2": 1,
            "3": 0,
            "4": 0,
            "5": 0
          }
        }
      ]
    }
  ],
  "offset": 0,
  "limit": 50,
  "total": 1
}
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/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/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": 14,
  "rating": 4,
  "title": "These are terrific!",
  "text": "These are the best widgets ever.  Really amazing quality.",
  "textLength": 57,
  "locale": "en_US",
  "csFlag": false,
  "inappropriateFlag": false,
  "reviewedFlag": false,
  "autoModerated": false,
  "published": false,
  "incentivized": false,
  "upVotes": 0,
  "downVotes": 0,
  "orderId": "NY4003977783",
  "catalogItems": [
    {
      "sku": "700285064826",
      "title": "Oakley XX Frame Accessory Kit - Black",
      "url": "http://www.testtt.info/tt4_2/responsivesite/qaOverlay-reviewsEmbed.php?sku=700285064826",
      "category": null,
      "reviewCount": 7,
      "averageRating": 4.86,
      "ratingBreakdown": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 1,
        "5": 6
      }
    }
  ],
  "dimensions": [
    {
      "type": 1,
      "dimensionId": 1,
      "dimensionLabel": "Overall Quality",
      "value": 1
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Comfort",
      "value": 8,
      "label": "High"
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Weight",
      "label": "Light"
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish"
      ]
    }
  ],
  "media": {
    "photo": [
      {
        "id": 1,
        "type": "photo",
        "caption": "Desperate product!",
        "imageType": "jpeg",
        "width": 168,
        "height": 168,
        "normalUrl": "http://www.turnto.com/imagestore/item/sss-sss/4E21E538722E99F7A34E798084EE4FCC_1454360415690_1.png",
        "locale": "en_US",
        "published": true,
        "dateCreated": "2016-02-01T16:00:16-05:00",
        "tags": []
      }
    ],
    "video": [
      {
        "id": 2,
        "type": "video",
        "caption": "crazy video",
        "provider": "youtube",
        "providedLink": "https://www.youtube.com/watch?v=jS3ZxOtTD5A",
        "thumbnailUrl": "https://i.ytimg.com/vi/jS3ZxOtTD5A/hqdefault.jpg",
        "thumbnailWidth": 480,
        "thumbnailHeight": 360,
        "width": 480,
        "height": 270,
        "authorName": "HowToBasic",
        "authorUrl": "https://www.youtube.com/user/HowToBasic",
        "providerId": "jS3ZxOtTD5A",
        "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/jS3ZxOtTD5A?feature=oembed&rel=0&showinfo=0\" frameborder=\"0\" allowfullscreen></iframe>",
        "s88thumbDims": {
          "width": 117,
          "height": 88,
          "scaledTo": "h",
          "targetLeft": -15,
          "targetTop": 0
        },
        "s64thumbDims": {
          "width": 85,
          "height": 64,
          "scaledTo": "h",
          "targetLeft": -11,
          "targetTop": 0
        },
        "locale": "en_US",
        "published": true,
        "dateCreated": "2016-02-01T16:00:17-05:00",
        "tags": [
          "SAF",
          "IPR"
        ]
      }
    ],
    "audio": []
  },
  "responses": [],
  "reviewedDate": null,
  "purchaseDate": null,
  "tags": [
    "SOT",
    "ALU"
  ],
  "dateCreated": "2015-09-28T15:30:46-04:00",
  "user": {
    "nickName": "Bart S.",
    "firstName": "Bart",
    "lastName": "Simpson",
    "emailAddress": "bart@simpson.com",
    "externalId": null,
    "city": "Springfield",
    "state": "OH",
    "country": "US",
    "ageRange": 1
  }
}
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/reviews

Creates a new review. Currently a review can only be associated with a single catalog item.

Site settings can be used to configure whether the review title and review text are required properties. For sites that allow Ratings-only Reviews both the review title and review text are configured as optional properties. The review title may not exceed 1000 characters. If the review title is supplied then review text is also required. If review text is supplied it must not be shorter than the site defined minimum (the default is 50 characters) or longer than 5000 characters.

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

Media content can be associated with the review by providing either the IDs of existing media or details of new media content. Up to 5 media items may be supplied. Images are oriented based on their EXIF orientation data.

When using this endpoint to import reviews into TurnTo, an external Id can be supplied to allow the review to be uniquely identified. In the case where a review already exists for the supplied external Id then it will be updated. If an external Id is supplied then the date the review was created may also be supplied.

If the review is created in response to a review solicitation email, the embedded link to initiate the create review flow includes a parameter ‘turntoTrackingToken’ that contains encoded information about the email recipient. The token can be passed to the create review endpoint to allow the review to be associated with the review solicitation email it came from.

Request body JSON object properties

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

Property Required Note
externalId No The Id of the review on an external system.
dateCreated No Date the review was created on an external system.
title No Review title
text No Review text
locale No If omitted use site default.
rating Yes Rating for this product (1,2,3,4, or 5)
user.firstName Yes
user.lastName Yes
user.nickName No
user.emailAddress No Either email address or externalId is required to identify the user
user.externalId No Either email address or externalId is required to identify the user
user.city No
user.state No
user.country No
user.ageRange No
user.shopperProfiles[].id No The Id of the shopper profile to be added
user.shopperProfiles[].value No Value of free-form text for a shopper profile
userIpAddr No The IP address of the UGC author
catalogItems[].sku Yes The SKU of the catalog item that this review is about. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created.
catalogItems[].title No The title of the catalog item for this SKU. This can be omitted if the item already exists in your site’s catalog at TurnTo
catalogItems[].url No The URL of the catalog item for this SKU. This can be omitted if the item already exists in your site’s catalog at TurnTo
dimensions[].value No Predefined dimension value
media.ids No List of existing media Ids to be associated with the review
media.photo[].caption No Caption for new photo associated with the review
media.photo[].b64data No Base64 data for new photo associated with the review
media.video[].caption No Caption for new video associated with the review
media.video[].url No Link URL for new video associated with the review
turntoTrackingToken No The tracking token included in the create review link.

Example URI

POST https://api.turnto.com/v1/reviews
Request
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
Body
{
  "externalId": "EXT10008",
  "dateCreated": "2015-09-26T10:01:21-04:00",
  "title": "These are terrific!",
  "text": "These are the best widgets I ever used. Honest swear to god.",
  "locale": null,
  "rating": 4,
  "catalogItems": [
    {
      "sku": "11112222"
    }
  ],
  "dimensions": [
    {
      "value": 1
    },
    {
      "value": 8
    },
    {
      "value": 10
    },
    {
      "value": 13
    }
  ],
  "media": {
    "ids": [
      1,
      2
    ],
    "photo": [],
    "video": [
      {
        "caption": "crazy video",
        "url": "https://www.youtube.com/watch?v=jS3ZxOtTD5A"
      }
    ]
  },
  "user": {
    "nickName": "Bart S.",
    "firstName": "Bart",
    "lastName": "Simpson",
    "emailAddress": "bart@simpson.com",
    "city": "Springfield",
    "state": "OH",
    "country": "US",
    "ageRange": 1,
    "shopperProfiles": [
      {
        "id": 2
      }
    ]
  },
  "userIpAddr": "123.456.789.100",
  "turntoTrackingToken": "eyJ0cmFuc0lkIjoxLCJ0dXJudG9FbWFpbFR5cGUiOiJyZXZpZXdTb2xpY2l0YXRpb24iLCJ0dXJudG9za3UiOiI1NjY0NTQyNTMzNCJ9"
}
Response  201
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Location: https://api.turnto.com/v1/reviews/{id}
Body
{
  "id": 27,
  "rating": 4,
  "title": "These are terrific!",
  "text": "These are the best widgets I ever used. Honest swear to god.",
  "textLength": 60,
  "locale": "en_US",
  "csFlag": false,
  "inappropriateFlag": false,
  "reviewedFlag": false,
  "autoModerated": false,
  "published": false,
  "incentivized": false,
  "upVotes": 0,
  "downVotes": 0,
  "orderId": null,
  "catalogItems": [
    {
      "sku": "11112222",
      "title": "MultiChef",
      "url": "www.topchef.com/food-processors/multichef",
      "category": "processors",
      "reviewCount": 0,
      "averageRating": 0,
      "ratingBreakdown": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0
      }
    }
  ],
  "dimensions": [
    {
      "type": 1,
      "dimensionId": 1,
      "dimensionLabel": "Overall Quality",
      "value": 1
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Comfort",
      "value": 8,
      "label": "High"
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Weight",
      "label": "Light"
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish"
      ]
    }
  ],
  "media": {
    "photo": [],
    "video": [],
    "audio": []
  },
  "responses": [],
  "reviewedDate": null,
  "purchaseDate": null,
  "dateCreated": "2015-09-26T10:01:21-04:00",
  "user": {
    "nickName": "Bart S.",
    "firstName": "Bart",
    "lastName": "Simpson",
    "emailAddress": "bart@simpson.com",
    "externalId": null,
    "city": "Springfield",
    "state": "OH",
    "country": "US",
    "ageRange": 1,
    "shopperProfiles": [
      {
        "id": 2
      }
    ]
  }
}
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/reviews/{id}/voteup

Registers an up vote for a review.

Example URI

POST https://api.turnto.com/v1/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": 27,
  "rating": 4,
  "title": "These are terrific!",
  "text": "These are the best widgets I ever used. Honest swear to god.",
  "textLength": 60,
  "locale": "en_US",
  "csFlag": false,
  "inappropriateFlag": false,
  "reviewedFlag": false,
  "autoModerated": false,
  "published": false,
  "incentivized": false,
  "upVotes": 1,
  "downVotes": 0,
  "orderId": null,
  "catalogItems": [
    {
      "sku": "11112222",
      "title": "MultiChef",
      "url": "www.topchef.com/food-processors/multichef",
      "category": "processors",
      "reviewCount": 0,
      "averageRating": 0,
      "ratingBreakdown": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0
      }
    }
  ],
  "dimensions": [
    {
      "type": 1,
      "dimensionId": 1,
      "dimensionLabel": "Overall Quality",
      "value": 1
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Comfort",
      "value": 8,
      "label": "High"
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Weight",
      "label": "Light"
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish"
      ]
    }
  ],
  "responses": [],
  "reviewedDate": null,
  "purchaseDate": null,
  "dateCreated": "2015-09-26T10:01:21-04:00",
  "tags": [],
  "user": {
    "nickName": "Bart S.",
    "firstName": "Bart",
    "lastName": "Simpson",
    "emailAddress": "bart@simpson.com",
    "externalId": null,
    "city": "Springfield",
    "state": "OH",
    "country": "US",
    "ageRange": 1,
    "shopperProfiles": [
      {
        "id": 2
      }
    ]
  }
}
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/reviews/{id}/votedown

Registers a down vote for a review.

Example URI

POST https://api.turnto.com/v1/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": 27,
  "rating": 4,
  "title": "These are terrific!",
  "text": "These are the best widgets I ever used. Honest swear to god.",
  "textLength": 60,
  "locale": "en_US",
  "csFlag": false,
  "inappropriateFlag": false,
  "reviewedFlag": false,
  "autoModerated": false,
  "published": false,
  "incentivized": false,
  "upVotes": 1,
  "downVotes": 1,
  "orderId": null,
  "catalogItems": [
    {
      "sku": "11112222",
      "title": "MultiChef",
      "url": "www.topchef.com/food-processors/multichef",
      "category": "processors",
      "reviewCount": 0,
      "averageRating": 0,
      "ratingBreakdown": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0
      }
    }
  ],
  "dimensions": [
    {
      "type": 1,
      "dimensionId": 1,
      "dimensionLabel": "Overall Quality",
      "value": 1
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Comfort",
      "value": 8,
      "label": "High"
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Weight",
      "label": "Light"
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish"
      ]
    }
  ],
  "responses": [],
  "reviewedDate": null,
  "purchaseDate": null,
  "dateCreated": "2015-09-26T10:01:21-04:00",
  "tags": [],
  "user": {
    "nickName": "Bart S.",
    "firstName": "Bart",
    "lastName": "Simpson",
    "emailAddress": "bart@simpson.com",
    "externalId": null,
    "city": "Springfield",
    "state": "OH",
    "country": "US",
    "ageRange": 1,
    "shopperProfiles": [
      {
        "id": 2
      }
    ]
  }
}
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/reviews/{id}/flag

Flag a review as inappropriate.

Example URI

POST https://api.turnto.com/v1/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": 27,
  "rating": 4,
  "title": "These are terrific!",
  "text": "These are the best widgets I ever used. Honest swear to god.",
  "textLength": 60,
  "locale": "en_US",
  "csFlag": false,
  "inappropriateFlag": true,
  "reviewedFlag": false,
  "autoModerated": false,
  "published": false,
  "incentivized": false,
  "upVotes": 1,
  "downVotes": 1,
  "orderId": null,
  "catalogItems": [
    {
      "sku": "11112222",
      "title": "MultiChef",
      "url": "www.topchef.com/food-processors/multichef",
      "category": "processors",
      "reviewCount": 0,
      "averageRating": 0,
      "ratingBreakdown": {
        "1": 0,
        "2": 0,
        "3": 0,
        "4": 0,
        "5": 0
      }
    }
  ],
  "dimensions": [
    {
      "type": 1,
      "dimensionId": 1,
      "dimensionLabel": "Overall Quality",
      "value": 1
    },
    {
      "type": 2,
      "dimensionId": 2,
      "dimensionLabel": "Comfort",
      "value": 8,
      "label": "High"
    },
    {
      "type": 3,
      "dimensionId": 3,
      "dimensionLabel": "Weight",
      "label": "Light"
    },
    {
      "type": 4,
      "dimensionId": 4,
      "dimensionLabel": "Impression",
      "label": [
        "Stylish"
      ]
    }
  ],
  "responses": [],
  "reviewedDate": null,
  "purchaseDate": null,
  "dateCreated": "2015-09-26T10:01:21-04:00",
  "tags": [],
  "user": {
    "nickName": "Bart S.",
    "firstName": "Bart",
    "lastName": "Simpson",
    "emailAddress": "bart@simpson.com",
    "externalId": null,
    "city": "Springfield",
    "state": "OH",
    "country": "US",
    "ageRange": 1,
    "shopperProfiles": [
      {
        "id": 2
      }
    ]
  }
}
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 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/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/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/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/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/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/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 Ratings List
GET/v1/sellerratings{?publishedOnly,locale,rating,suppressUserPII,limit,offset,sort}

This endpoint can be used to return a list of seller ratings associated with your site.

Options are available to filter results by published status, locale, and rating value. Pagination of results is supported via the ‘limit’ and ‘offset’ parameters.

User Properties

Basic information about a user’s age and location appears in the nested ‘user’ block of each seller rating result.

Customer Defined Shopper Profiles

Customer defined shopper profile values captured for a user at the time a review is created appear in the nested ‘shopperProfiles’ block of each seller rating result.

Example URI

GET https://api.turnto.com/v1/sellerratings?publishedOnly=true&locale=en_US&rating=4&suppressUserPII=false&limit=50&offset=10&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: 50

Maximum number of seller ratings to show.

offset
number (optional) Default: 0 Example: 10

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/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/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.11.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
    }
  ]
}

Seller Ratings Summary

The Seller Ratings summary is a collection of data points relating to the seller ratings associated with your site, including the number of seller ratings, the average seller rating, and the breakdown of the number of seller ratings for each rating value.

Resource Properties - Seller Ratings Summary

Property Type Description
ratingCount number Number of seller ratings for your site
averageRating number Average seller rating for your site
ratingBreakdown map Number of seller ratings received for your site broken down by rating value (1-5)

Seller Ratings Summary
GET/v1.0/sellerratings/summary

This endpoint returns summary details for seller ratings associated with your site.

Example URI

GET https://api.turnto.com/v1.0/sellerratings/summary
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
{
  "ratingCount": 255,
  "averageRating": 4.5,
  "ratingBreakdown": {
    "1": 11,
    "2": 5,
    "3": 3,
    "4": 85,
    "5": 153
  }
}
Response  400
HideShow
Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "errors": [
    {
      "message": "Seller Ratings not enabled.",
      "code": 211
    }
  ]
}

Articles

An Article, also known as a Knowledgebase Article, is a piece of system managed website content. An article can be associated with one or more catalog items, which are identified by a SKU in your catalog. If no catalog item is specified then the article is considered generic.

Resource Properties - Articles

Property Type Description
id number Unique Id for this article
externalId string External Id for this article
dateCreated date Date article created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
title string Article title
text string Article text
locale string Locale of article
published boolean Is published?
expirationDate date Date this article expires (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
catalogItems resource Product(s) for which this article is applicable. Nested products block - see Products section
brands string List of brands for which this article is related
categories string List of categories for which this article is related
searchTerms string List of search terms for which this article is related

Article List

Article List
GET/v1/articles{?sku,publishedOnly,locale,limit,offset,sort}

This endpoint is used to retrieve a list of articles. A list of SKUs can be supplied to obtain articles relating to specific products.

Options are available to filter results by published status and locale. Pagination of results is supported via the ‘limit’ and ‘offset’ parameters.

Example URI

GET https://api.turnto.com/v1/articles?sku=12345&publishedOnly=true&locale=en_US&limit=50&offset=10&sort=dateCreated:desc
URI Parameters
HideShow
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: 50

Maximum number of articles to show.

offset
number (optional) Default: 0 Example: 10

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/articles/{id}

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

Example URI

GET https://api.turnto.com/v1/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
    }
  ]
}

Article Detail By External Id

Article Detail By External Id
GET/v1/articles{?externalId}

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

Example URI

GET https://api.turnto.com/v1/articles?externalId=X12345
URI Parameters
HideShow
externalId
string (required) Example: X12345

The external 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 external Id (X0123)",
      "code": 155
    }
  ]
}

Update Article

Update Article
POST/v1/articles

An authorization token is required to create or update an article. An article may be updated by including an existing Id or external system Id. The article is created/updated by posting a JSON object in the body of the request. A nested catalogItems block can be used to associate the article with one or more catalog items.

Request body JSON object properties

The properties that are passed to create or update an article are a subset of the properties described in the Resource Properties section above. (Please note that the ‘.’ notation is used to describe the property of a nested object)

Property Required Note
id No
externalId No
title Yes
text Yes
locale No If omitted use site default.
published Yes True or false
expirationDate No Expiration date
catalogItems[].sku No The SKU of the catalog item(s) that this article is about.
brands No
categories No
searchTerms No

Example URI

POST https://api.turnto.com/v1/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/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/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/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
Body
{
  "id": 2,
  "externalId": "X0123"
}
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/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/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
Body
{
  "id": 2,
  "externalId": "X0123"
}
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/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/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/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/users?email=a@a.com&userId=7654321&ugcType=question&questionsOnly=false&questionsAnsweredOnly=false&answersOnly=false&commentsOnly=false&reviewsOnly=false&includeNested=false&publishedOnly=true
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.

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

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
      },
      "catalogItem": {
        "sku": "FP12653",
        "title": "Blendomatic 5000",
        "url": "http://www.homegadgetsandmore.com/blendomatic",
        "category": null
      },
      "tags": []
    }
  ],
  "reviews": [
    {
      "id": 7,
      "rating": 4,
      "title": "The best melon slicer bar none",
      "text": "This melon slicer has changed my life.  I never thought I would see the day when slicing a melon could be made so simple.  The best ever!",
      "textLength": 137,
      "locale": "en_US",
      "csFlag": false,
      "inappropriateFlag": false,
      "reviewedFlag": false,
      "autoModerated": false,
      "published": false,
      "incentivized": false,
      "upVotes": 0,
      "downVotes": 0,
      "orderId": null,
      "dimensions": [],
      "media": {
        "photo": [],
        "video": [],
        "audio": []
      },
      "responses": [],
      "reviewedDate": null,
      "purchaseDate": null,
      "dateCreated": "2016-11-15T10:37:53-05:00",
      "user": {
        "nickName": "Bill M.",
        "firstName": "Bill",
        "lastName": "Mee",
        "emailAddress": "bm@sample.com",
        "externalId": null,
        "city": "Memphis",
        "state": "TN",
        "country": "US",
        "ageRange": 2
      },
      "catalogItems": [
        {
          "sku": "FP17268",
          "title": "Melon Slicer",
          "url": "http://www.homegadgetsandmore.com/melonslicer",
          "category": null
        }
      ],
      "tags": []
    }
  ]
}
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 recent updates to the API.

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

2/8/24 - Seller Ratings Summary endpoint

A new Seller Ratings Summary endpoint returns summary details for seller ratings associated with your site.

7/28/21 - Forget User endpoint

A new Forget User endpoint submits a request to remove shoppers’ personal data.

10/13/20 - Product List endpoint maximum number of SKUS updated

The Product List endpoint returns product information for up to 25 SKUs from a single request.

10/13/20 - TurnTo does not accept gif images

The image/gif MIME type is not considered valid. TurnTo does no longer accepts Media image submissions in gif format.

08/20/20 - UGC Summary endpoint maximum number of SKUS updated

The UGC Summary endpoint returns the UGC summary for up to 25 SKUs from a single request.

11/12/19 - Review responses endpoints added

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

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

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

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

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

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

04/18/18 - Review list sort by upVotes

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

An optional parameter (includeRelated) has been added to the Review List endpoint to allow direct and related reviews to be returned in a combined list.

08/16/17 - UGC Summary by locale

An optional parameter (locale) has been added to the UGC Summary endpoint to allow dimensions to be localized to target site locale.

07/05/17 - Create Review title and text validation

The Create Review endpoint has been modified to include additional validation of review title and text properties so that rules regarding minimum and maximum number of characters is enforced.

01/04/17 - User UGC questions answered

The User UGC endpoint has been modified to allow questions answered by the user to be included in returned results.

01/04/17 - Capture email recipient information for answers and reviews

An optional property (turntoTrackingToken) has been added to the Create Answer and Create Review endpoints to allow information about email recipients to be captured.

10/26/16 - Thank Answerer endpoint added

The Thank Answerer endpoint has been added to support sending a thank you email to the user that created an answer.

09/14/16 - User UGC enhancement

The User UGC endpoint has been enhanced to include two new options. The ‘includeNested’ option allows nested content to be included in the returned results. The ‘publishedOnly’ option allows returned results to be limited to published content.

08/03/16 - Answer more questions

The Answer More Questions endpoint has been added to support an API implementation of the TurnTo widget Answer More Questions box.

08/03/16 - Collect IP for UGC authors

An optional property (userIpAddr) has been added to UGC creation endpoints to allow for the capture of the IP address for the UGC author.

The following endpoints have been updated Create Question, Create Answer, Create Reply, Create Comment, and Create Review.

08/03/16 - Search against creation date

The UGC Search endpoint has been enhanced to allow results to be filtered by creation date.

Results can be selected for a specific time period by supplying one or both of the ‘dateCreatedFrom’ and ‘dateCreatedTo’ parameters.

08/03/16 - Article List fix

The Article List endpoint has been modified to correct the behavior when paginating large result sets.

Previously, the use of the offset parameter to paginate large result sets did not return the expect results. This has been fixed.

06/29/16 - UGC flag indicators

The Questions UGC type has been modified to include the csFlag property. Also, the type of irrelevantFlag property has been changed to boolean to maintain consistency with other flag indicators.

The Reviews UGC type has been modified to change the csFlag and inappropriateFlag properties to boolean to maintain consistency with other flag indicators.

06/29/16 - Search by tag codes

The UGC Search endpoint has been enhanced to allow results to be filtered by tag codes.

05/25/16 - List and search publishedOnly option fix

The list and search endpoints have been modified to fix an issue in the behavior of the publishedOnly option. Previously, setting publishedOnly to false resulted in only unpublished content being returned.

This has been fixed so that setting publishedOnly to false results in both published and unpublished content being returned.

05/25/16 - Review catalog items fix

The UGC Search and User UGC endpoints have been modified to fix an inconsistency in the presentation of catalog items associated with reviews.

The catalogItem property is replaced by the catalogItems list property.

The catalogItem property in reviews block has been deprecated and will be removed in a future release.

05/25/16 - Review search results includes media content

The UGC Search endpoint has been modified to include associated published media content in review results.

05/25/16 - Review order Id property added

The orderId property has been added to review block to allow the order associated with a review to be identified.

05/25/16 - Review dimension properties added

The dimensionId property has been added to review dimension block to allow the dimension to be unambiguously identified.

Type 2 (range) dimensions now include the value property to uniquely identify range values.

05/25/16 - Content Tags added

Content Tags have been added to Media, Question, Answer, Comment, and Review UGC Types.

New options to filter content by tag codes added.

03/22/16 - Article List fix

The Article List endpoint has been modified to correct behavior when filtering by SKU.

Previously, the use of * as a wildcard allowed articles for all SKU’s to be returned. This behavior was inconsistent with other endpoints and caused confusion.

The use of * as wildcard has been deprecated and will be removed in a future release.

To obtain articles for all SKU’s the sku parameter should be left blank.

03/22/16 - Improved validation

Additional validation checks have been included to allow more meaningful responses to be returned.

Four new Response Codes 178 - 181 have been added.

02/17/16 - Media UGC type added

The Media UGC type has been added to allow media content to be created and associated with reviews.

Two new endpoints have been added: Save Media allows media content to be created for a user, User Media List allows media content to be retrieved for a user.

The Create Review endpoint has been enhanced to allow new and/or existing media to be included with a review.

Note: audio is not currently supported.

02/17/16 - Best Answer enhancement

The Question List, Question Detail, and Question Answers endpoints have been updated to return answer results sorted by best answer. The best answer for a question now contains a new property bestAnswer set to true.

02/17/16 - Create order documentation

The Create Order documentation has been corrected to indicate that property emailOptOut is not part of the user block.

01/07/16 - Associate order with comment enhancement

The Create Comment endpoint has been enhanced to allow an order to be associated with the comment.

An Order Id field has been added to the comment blocks returned by API endpoints.

11/04/15 - Response to Reviews enhancement

The TurnTo application has been enhanced to allow review moderators to post responses to reviews.

When using the API endpoints to retrieve reviews, any responses to reviews will be embedded in the reviews result set in a new property (responses).

10/07/15 - Review List enhancement

The Review List endpoint used to return reviews for a specified sku has been enhanced.

Two new parameters (dateCreatedFrom and dateCreatedTo) have been added to allow reviews to be constrained by their creation date.

A new sort option (rating) has been added to allow reviews to be sorted by the review product rating.

10/07/15 - Product List and UGC Summary fix

Under certain circumstances the dimensions blocks for the returned products were not fully populated. This has been fixed for the Product List and UGC Summary endpoints.

Additionally, the count field (count) in the dimensions block is now populated for dimension types 3 (Single Select) and 4 (Multi Select).

Generated by aglio on 20 Feb 2024