Back to top

New Version Released

The TurnTo API v1.1 contains a number of significant updates that are designed to ensure consistent object model representations across all endpoints which in turn allows JSON responses to be parsed and accessed more easily.

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

A summary of updates is listed below:

Product List Response

A successful response to the Product List endpoint (GET /v1.1/products) will always contain an array of product results. Results are only included for matched SKUs.

Previous version would return a single product if retrieving details for a single SKU. Additionally, when retrieving details for multiple SKUs any product not found was reported as an error in the results.

UGC Summary Response

A successful response to the UGC Summary endpoint (GET /v1.1/products/ugc_summary) will always contain an array of UGC Summary results. Results are only included for matched SKUs.

Previous version would return a single UGC summary if retrieving details for a single SKU. Additionally, when retrieving details for multiple SKUs any product not found was reported as an error in the results.

Comment Catalog Items

The catalog item associated with a Comment is contained in array block identified by property 'catalogItems’.

In previous version a single value property ‘catalogItem’ was used which was inconsistent with data model used in other UGC types.

Review Dimensions Label

Nested review dimension blocks are modified such that the ‘label’ property is always presented as an array of values.

In previous version a single value was returned for the review dimension types 2 (Range) and 3 (Single Select).

Invalidate Access Token Response

A successful response to the Invalidate Access Token endpoint (POST /v1.1/oauth2/invalidate_token) has no response body.

Previous version unnecessarily echoed the access token in the response.

Cancel Order Response

A successful response to the Cancel Order endpoint (POST /v1.1/orders/cancel) has no response body.

Previous version unnecessarily echoed the order Id and SKU in the response.

Article List Response

A successful response to the Article List endpoint (GET /v1.1/articles) will always contain a paginated results block containing an array of article results.

Previous version would return a single article if retrieving details by externalId.

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

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.

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

Update (Operation)

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

Example:

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

Next 

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:

CodeMessageDescriptionHTTP Status
101Invalid sort parameter formatThe supplied sort parameter did not have the correct format.400
102Invalid field in sort parameterOne or more fields in the supplied sort parameter were not valid.400
103Invalid limit or offsetThe limit or offset was not numeric.400
104Offset was out of rangeThe offset was less than zero or greater than or equal to the total number of result set rows.400
105Limit was out of rangeThe limit was less than zero.400
106No catalog item found for SKU ()The SKU was not found in the catalog.400
107No question was found for the specified ID ()A question with the specified ID could not be found.404
108Missing Required FieldsFields were missing for a create or update.400
109Catalog item not found for one or more supplied SKUsOne of the supplied SKUs was not found in the catalog.400
110Please do not include links to other sitesA link to another site was included in the supplied text.400
111Failed to save the questionAn unknown error occurred while attempting to save the question.500
112Invalid client_id or client_secretClient ID / Client Secret combination is not valid.403
113Unknown grant_typeInvalid grant_type.400
114Missing or invalid parameters client_secret, grant_typeThe client_secret and/or grant_type was missing or invalid.400
115Unknown access_tokenAccess token missing or incorrect for invalidate_token service.400
116Missing Authorization headerOAuth2 token not present.403
117Invalid access tokenOAuth2 token invalid.403
118Error while generating access_tokenServer error.500
119Error while invalidating access_tokenServer error.400
120$$$$ method not allowed for this request typeThe requested method is not allowed for this request type.405
121Failed to save answerAn unknown error occurred while attempting to save the answer.500
122Too many SKUs requestedThere is a maximum of 20 UGC counts that can be returned in a single request.400
123No comment was found for the specified ID ()A comment with the specified ID could not be found.400
124Failed to save the commentAn unknown error occurred while attempting to save the comment.500
125Too many SKUs attached to questionThe maximum number of SKUs (catalog items) for a question was exceeded. Maximum is 10.400
126Limit too large. Max is 100The maximum limit for pagination was exceeded. Maximum is 100.400
127Failed to save the replyAn unknown error occurred while attempting to save the reply.500
128Invalid email addressThe format of the email address is invalid.400
129Unknown email addressThe email address was not a match for any user.400
130Unknown external IDThe external id was not a match for any user.400
131Bad search filtersAt least one of the search filter parameters has an invalid value, or a required filter parameter is missing400
132No answer was found for the specified ID ()An answer with the specified ID could not be found.404
133No reply was found for the specified ID ()A reply with the specified ID could not be found.404
134No replies found for the specified answer id ()No replies found for the specified answer ID ()400
135Error parsing JSON propertiesError parsing JSON properties.400
136Must specify at least one catalog itemMust specify at least one catalog item.400
137One or more duplicate SKUsAt least one SKU is duplicated in the catalog items section.400
138Too many SKUs attached to answerThe maximum number of SKUs (catalog items) for an answer was exceeded. Maximum is 10.400
139No review was found for the specified ID ()A review with the specified ID could not be found.404
140Failed to save the reviewAn unknown error occurred while attempting to save the review.500
141Review rating must be between 1 and 5The review rating must be between 1 and 5.400
142Review text too shortThe review text length is less than site minimum number of characters.400
143No parent reply was found for the specified id ()No parent reply was found for the specified ID.400
144Must specify email address or external IDUser must be identified by an email address or an external ID.400
145Invalid fieldThe field value was not valid.400
146Invalid delivery date format.The delivery date was not correctly formatted as yyyy-MM-dd400
147Order not createdThe order could not be created.400
148Order not cancelledThe order could not be cancelled.400
149Invalid locale for siteInvalid locale for site.400
150Product update failedThe product update could not be completed.400
151Invalid shopper profileThe shopper profile was invalid.400
152Duplicate shopper profileThe supplied shopper profiles contains duplicates.400
153Failed to save the articleAn unknown error occurred while attempting to save the article.500
154No article was found for the specified ID ()An article with the specified ID could not be found.404
155No article was found for the specified external ID ()An article with the specified external ID could not be found.404
156Must specify ID or external IDArticle to be deleted must be identified by ID or external ID.400
157Invalid expiration date format.The expiration date was not correctly formatted as yyyy-MM-dd400
158Category not found for one or more supplied category namesOne of the supplied category names was not found.400
159One or more duplicate categoriesAt least one category is duplicated.400
160Brand not found for one or more supplied brand namesOne of the supplied brand names was not found.400
161One or more duplicate brandsAt least one brand is duplicated.400
162Too many SKUs requestedThere is a maximum of 20 SKUs that can be matched in a single request.400
163Invalid date specified for dateCreatedFrom parameterThe date created from parameter is invalid.400
164Invalid date specified for dateCreatedTo parameterThe date created to parameter is invalid.400
165Invalid date specified for dateCreated parameterThe date created parameter is invalid.400
166DateCreated parameter not allowed without external IdThe date created parameter is not allowed without external Id.400
167API rate limit exceededThe number of requests has exceeded the API rate limit.429
168Reviews not enabledReviews are not enabled for this site.400
169No order item found for the specified order ID () and SKU ()An order item with the specified ID and SKU could not be found400
170The specified media could not be associated with the reviewThe specified media could not be associated with the review400
171Failed to save the mediaAn unknown error occurred while attempting to save the media.500
172No media itemsThere were no media items to be uploaded.400
173Too many media itemsThere is a maximum of 5 media items that can be uploaded in a single request.400
174Unsupported video serviceUnsupported video service.400
175Video not foundVideo not found.400
176Invalid image typeThe uploaded image type is not valid.400
177Image exceeds maximum sizeImage exceeds maximum size.400
178Invalid SKUSKUs must contain at least 1 alphanumeric character.400
179One or more duplicate dimensionsAt least one dimension is duplicated.400
180Invalid dimension ()The specified dimension could not be found for this product.400
181Invalid ratingThe rating must be between 1 and 5.400
182Tag code not foundOne of the specified tag codes was not found.400
183One or more duplicate tag codesAt least one tag code is duplicated.400
184Too many SKUs attached to reviewOnly 1 SKU can be attached to a review.400
186Invalid boolean parameterThe boolean parameter is not valid.400
187Thanking users is not enabledThanking users is not enabled in site configuration.400
188Answer already thankedThe answerer has already been thanked.400
189Invalid UGC Type ()The ugcType parameter contained an invalid UGC type.400
190Failed to register new userAn unknown error occurred while attempting to register a new user.400
191Site not activeThe request cannot be processed for a site that is not active.403
192Review text too longReview text length exceeds maximum of 5000 characters.400
193Review title mandatoryReview title mandatory for site.400
194Review title too longReview title length exceeds maximum of 1000 characters.400
195Review text mandatory with review titleThe review text is mandatory when review title is provided.400
196User already reviewed this catalog itemThe user has already submitted a review for this catalog item.400
197Invalid date specified for orderDateFrom parameterThe order date from parameter is invalid.400
198Terms and conditions not acceptedThe user has not accepted the terms and conditions.400
199Form submission not foundForm submission not found.400
Next  Previous

OAuth 

TurnTo uses the OAuth 2.0 Bearer token mechanism to secure most API requests. You can use the ‘/v1.1/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

Your site can only have one valid API access token at a time.

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.

Obtain Access Token 

Requests Access Token
/v1.1/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.

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

Resource URL

https://api.turnto.com/v1.1/oauth2/token
  • Parameters
  • 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
  • Headers
    Content-Type: application/x-www-form-urlencoded
    Body
    client_id=[yourSiteKey]&client_secret=[yourAuthKey]&grant_type=client_credentials
    
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"token_type":"bearer","access_token":"R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya"}
    
  • Response  403
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Invalid client_id or client_secret",
       "code": 112
    }]}
    

Invalidate Access Token 

Invalidates Access Token
/v1.1/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 if, for security reasons, you have a policy of renewing the access token periodically.

Resource URL

https://api.turnto.com/v1.1/oauth2/invalidate_token
  • Parameters
  • 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
  • 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
  • Headers
    Content-Type: application/json;charset=UTF-8
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Unknown access_token",
       "code": 115
    }]}
    
Next  Previous

Sites 

A number of site configuration settings may be accessed using the TurnTo API.

This includes user settings that control which additional user information, referred to as shopper profiles, is to be collected and displayed.

Resource Properties - User Settings

PropertyTypeDescription
ageRange.hiddenbooleanInclude age range input on review submission form.
ageRange.requiredbooleanAge range required.
ageRange.collectDuringContentSubmitbooleanAge range to be collected during content submission.
ageRange.displayPublicbooleanDisplay age range with user content.
cityState.hiddenbooleanInclude user location input on review submission form.
cityState.requiredbooleanUser location required.
cityState.collectDuringContentSubmitbooleanUser location to be collected during content submission.
cityState.displayPublicbooleanDisplay user location with user content.
shopperProfilesresourceList of shopper profiles

Resource Properties - Shopper Profile

PropertyTypeDescription
namestringName of profile
labelstringLocalized label
typenumberProfile type: 0 = select, 1 = free-form text
hiddenboolean
requiredboolean
collectDuringContentSubmitboolean
displayPublicboolean
values[].idnumberIdentifier for a profile value
values[].labelstringLocalized label
values[].hiddenboolean
values[].sortOrdernumber

Site Settings 

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

Get site settings
/v1.1/sites {?locale}

This endpoint will return site settings for the site identified in the request.

Labels will be localized according to the specified locale.

Resource URL

https://api.turnto.com/v1.1/sites?locale=en_US
  • Parameters
  • locale
    string (optional) Default: en_US 

    Labels will be returned in target locale.

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

Products 

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

Resource Properties - Product

PropertyTypeDescription
skustringUnique catalog identifier for this product
titlestringName of the product
urlstringWeb page for this product
dimensionsresourceCustom values that can be assigned for this product

Resource Properties - Dimension

PropertyTypeDescription
idnumberIdentifier for the dimension
labelstringLabel to be displayed
typenumberDimension type: 1 = Rating, 2 = Range, 3 = Single Select, 4 = Multi Select
requiredbooleanIs dimension value required when submitting review by widget?
averagenumberThe average value for this dimension
values[].idnumberIdentifier for a dimension value
values[].labelstringDisplay label for a dimension value
values[].sortOrdernumberSort order for a dimension value
values[].countnumberNumber of times dimension selected in a review for this product

Product List 

The product detail information describes the product.

Get product details
/v1.1/products {?sku,locale}

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

Resource URL

https://api.turnto.com/v1.1/products?sku=12345,22222,33333&locale=en_US
  • Parameters
  • sku
    string (required) Example: 12345,22222,33333

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

    locale
    string (optional) 

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

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

PropertyTypeDescription
skustringUnique catalog identifier for this product
questionsnumberNumber of questions for this product
relatedQuestionsnumberNumber of related questions for this product
commentsnumberNumber of comments for this product
answersnumberNumber of answers for this product
relatedAnswersnumberNumber of related answers for this product
reviewsnumberNumber of reviews for this product
averageRatingnumberAverage rating for this product
ratingBreakdownmapNumber of ratings received for this product broken down the rating value (1-5)
dimensionsresourceCustom values that can be assigned for this product
Get UGC summary
/v1.1/products/ugc_summary {?sku,locale}

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

Resource URL

https://api.turnto.com/v1.1/products/ugc_summary?sku=12345,22222,33333&locale=en_US
  • Parameters
  • sku
    string (required) Example: 12345,22222,33333

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

    locale
    string (optional) 

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

  • Request
  • Headers
    Content-Type: application/x-www-form-urlencoded
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    [
          {
          "sku": "700285064826",
          "questions": 1,
          "relatedQuestions": 0,
          "comments": 0,
          "answers": 1,
          "relatedAnswers": 0,
          "reviews": 7,
          "averageRating": 4.86,
          "ratingBreakdown":       {
             "1": 0,
             "2": 0,
             "3": 0,
             "4": 1,
             "5": 6
          },
          "dimensions":       [
                      {
                "id": 1,
                "label": "Overall Quality",
                "type": 1,
                "required": true,
                "average": "1.00",
                "values":             [
                                  {
                      "id": 1,
                      "value": 1
                   },
                                  {
                      "id": 2,
                      "value": 2
                   },
                                  {
                      "id": 3,
                      "value": 3
                   },
                                  {
                      "id": 4,
                      "value": 4
                   },
                                  {
                      "id": 5,
                      "value": 5
                   }
                ]
             },
                      {
                "id": 2,
                "label": "Comfort",
                "type": 2,
                "required": true,
                "average": "2.00",
                "values":             [
                                  {
                      "id": 6,
                      "sortOrder": 0,
                      "label": "Low"
                   },
                                  {
                      "id": 7,
                      "sortOrder": 1,
                      "label": "Medium"
                   },
                                  {
                      "id": 8,
                      "sortOrder": 2,
                      "label": "High"
                   }
                ]
             },
                      {
                "id": 3,
                "label": "Impression",
                "type": 4,
                "required": false,
                "average": null,
                "values":             [
                                  {
                      "id": 9,
                      "sortOrder": 0,
                      "label": "Durable",
                      "count": 0
                   },
                                  {
                      "id": 10,
                      "sortOrder": 1,
                      "label": "Stylish",
                      "count": 1
                   },
                                  {
                      "id": 11,
                      "sortOrder": 2,
                      "label": "Modern",
                      "count": 0
                   },
                                  {
                      "id": 12,
                      "sortOrder": 3,
                      "label": "Youthful",
                      "count": 0
                   }
                ]
             },
                      {
                "id": 4,
                "label": "Weight",
                "type": 3,
                "required": false,
                "average": null,
                "values":             [
                                  {
                      "id": 13,
                      "sortOrder": 0,
                      "label": "Light",
                      "count": 1
                   },
                                  {
                      "id": 14,
                      "sortOrder": 1,
                      "label": "Heavy",
                      "count": 0
                   }
                ]
             }
          ]
       },
          {
          "sku": "088989217022",
          "questions": 0,
          "relatedQuestions": 0,
          "comments": 0,
          "answers": 0,
          "relatedAnswers": 0,
          "reviews": 0,
          "averageRating": 0,
          "ratingBreakdown":       {
             "1": 0,
             "2": 0,
             "3": 0,
             "4": 0,
             "5": 0
          },
          "dimensions":       [
                      {
                "id": 1,
                "label": "Overall Quality",
                "type": 1,
                "required": true,
                "average": null,
                "values":             [
                                  {
                      "id": 1,
                      "value": 1
                   },
                                  {
                      "id": 2,
                      "value": 2
                   },
                                  {
                      "id": 3,
                      "value": 3
                   },
                                  {
                      "id": 4,
                      "value": 4
                   },
                                  {
                      "id": 5,
                      "value": 5
                   }
                ]
             },
                      {
                "id": 2,
                "label": "Comfort",
                "type": 2,
                "required": true,
                "average": null,
                "values":             [
                                  {
                      "id": 6,
                      "sortOrder": 0,
                      "label": "Low"
                   },
                                  {
                      "id": 7,
                      "sortOrder": 1,
                      "label": "Medium"
                   },
                                  {
                      "id": 8,
                      "sortOrder": 2,
                      "label": "High"
                   }
                ]
             },
                      {
                "id": 3,
                "label": "Impression",
                "type": 4,
                "required": false,
                "average": null,
                "values":             [
                                  {
                      "id": 9,
                      "sortOrder": 0,
                      "label": "Durable",
                      "count": 0
                   },
                                  {
                      "id": 10,
                      "sortOrder": 1,
                      "label": "Stylish",
                      "count": 0
                   },
                                  {
                      "id": 11,
                      "sortOrder": 2,
                      "label": "Modern",
                      "count": 0
                   },
                                  {
                      "id": 12,
                      "sortOrder": 3,
                      "label": "Youthful",
                      "count": 0
                   }
                ]
             },
                      {
                "id": 4,
                "label": "Weight",
                "type": 3,
                "required": false,
                "average": null,
                "values":             [
                                  {
                      "id": 13,
                      "sortOrder": 0,
                      "label": "Light",
                      "count": 0
                   },
                                  {
                      "id": 14,
                      "sortOrder": 1,
                      "label": "Heavy",
                      "count": 0
                   }
                ]
             }
          ]
       }
    ]
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Too many SKUs requested. Maximum is 20.",
       "code": 122
    }]}
    

Update Product 

Update product information.

Update a product
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/products

Request body JSON object properties

PropertyRequiredNote
skuYesUnique identifier for the item in your catalog.
imageUrlNoThe URL of the image of your catalog item.
titleYes
priceNoDefaults to 0.00
currencyNoDefaults to USD.
activeNoBoolean - defaults to true.
urlYesThe URL of the item on your site.
categoryNoName of the category this item belongs to.
categoryPathNoIf 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.
keywordsNoComma delimited list of keywords that apply to this item.
inStockNoBoolean - defaults to true.
virtualParentCodeNoAn arbitrary string used to group products.
isCategoryNoIs this a category rather than an orderable item - defaults to false.
membersNoIf product is a bundle of other products, specify comma delimited list of skus.
brandNoThe product’s brand name. If used together with 'MPN’, this field uniquely identifies the product.
mpnNo(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.
isbnNo(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.
upcNo(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.
eanNo(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.
janNo(Japanese Article Number) A unique numerical identifier for commercial products that’s usually associated with a barcode printed on retail merchandise. Used in Japan.
asinNo(Amazon Standard Identification Number) Uniquely identifies each product sold on amazon.com.
mobileItemUrlNoThe URL of the item on your mobile site.
localeDataNoA JSON field that allows the specification of locale specific product titles and urls. If specified, ‘title’ and ‘itemUrl’ are required, ‘mobileItemUrl’ is optional.
  • Request
  • 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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "sku": "11112222"
    }
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Invalid field (price)",
       "code": 145
    }]}
    
Next  Previous

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

PropertyTypeDescription
orderIdstringUnique order Id
deliveryDatedateDate of delivery
postalCodestringOrder postal code
emailOptOutbooleanUser opted out of receiving emails
userresource
itemsresourcelist order items

Resource Properties - Order Item

PropertyTypeDescription
lineItemIdstringIdentifier for the line item
titlestringProduct title
urlstringProduct URL
skustringProduct sku
pricenumberLine item amount
itemImageUrlstringItem image URL

Create Order 

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

Create an order
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/orders/create

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)

PropertyRequiredNote
orderIdYesUnique Id of the order to be created.
deliveryDateNoDate of delivery, format is yyyy-MM-dd
localeNoIf omitted use site default.
postalCodeNo
emailOptOutNoSet to the boolean value ‘true’ if the user is to receive no emails from TurnTo. Defaults to false.
user.firstNameYes
user.lastNameYes
user.nickNameNo
user.emailAddressYesEmail address is required to identify the user
user.externalIdNo
items[].lineItemIdNo
items[].titleYes
items[].urlYes
items[].skuYes
items[].priceNo
items[].itemImageUrlYes
  • Request
  • 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": "1",
           "price": "29.99",
           "itemImageUrl": "www.treadzzzzz.com/img/sneakers.jpg"
        },
        {
           "lineItemId": "2",
           "title": "Cleats",
           "url": "www.treadzzzzz.com/cleats",
           "price": "49.99",
           "itemImageUrl": "www.treadzzzzz.com/img/cleats.jpg"
        }
        ]
    }
    
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "id": 3317217,
       "orderId": "99977"
    }
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Invalid delivery date",
       "code": 146
    }]}
    

Cancel Order 

Cancel an order
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/orders/cancel

Request body JSON object properties

PropertyRequiredNote
orderIdYesId of the order to be cancelled.
skuNoIf provided only the order item with matching sku will be cancelled.
  • Request
  • Headers
    Content-Type: application/json;charset=UTF-8
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
    Body
    {
        "orderId": "99977",
        "sku": ""
    }
    
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Order not cancelled",
       "code": 148
    }]}
    
Next  Previous

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.

Note: audio is not currently supported.

Resource Properties - Media

PropertyTypeDescription
idnumberTurnTo unique ID for this media
captionstringCaption
typestringMedia type (photo,video,audio)
widthnumberImage width
heightnumberImage height
imageTypestringImage type (gif, jpeg, jpg, pjpeg, png, x-png)
normalUrlstringNormal image URL
thumbnailUrlstringThumbnail image/video URL
originalUrlstringOriginal image URL
providerstringVideo service provider
providedLinkstringVideo URL
thumbnailWidthstringVideo thumbnail width
thumbnailHeightstringVideo thumbnail height
authorNamestringVideo author name
authorUrlstringVideo author URL
providerIdstringVideo provider Id
htmlstringVideo html
authorNamestringVideo author name
tagsstringList of tag codes associated with this media
userresourceThe user that created this media content. Nested user block - see Users section
catalogItemsresourceProducts for which this media is associated with. Nested products block - see Products section
dateCreateddateDate 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 it’s Base64 encoded data in the request. For video the URL link must be supplied which is then verified with the video provider. Up to 5 media types may be specified.

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

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

Save media
/v1.1/media

This endpoint

Resource URL

https://api.turnto.com/v1.1/media

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)

PropertyRequiredNote
localeNoIf omitted use site default.
user.firstNameNo
user.lastNameNo
user.nickNameNo
user.emailAddressNoEither email address or externalId is required to identify the user
user.externalIdNoEither email address or externalId is required to identify the user
user.cityNo
user.stateNo
user.countryNo
user.ageRangeNo
user.shopperProfiles[].idNo
user.shopperProfiles[].valueNo
catalogItems[].skuYesThe 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[].titleNoThe 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[].urlNoThe 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[].captionNoThe caption must be provided for each photo b64data supplied
photo[].b64dataNoBase64 encoded image
video[].captionNoThe caption must be provided for each video URL supplied
video[].urlNoVideo URL link
  • Request
  • Headers
    Content-Type: application/json;charset=UTF-8
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
    Body
    {
        "locale": "en_US",
        "user": {
            "nickName": "Andrew A.",
            "firstName": "Andrew",
            "lastName": "Adamson",
            "emailAddress": "andrew@sample.com"
        },
         "catalogItems": [    {
            "sku": "VRSKU12345"
         } ],
         "photo": [
            {
                "caption": "Outstanding product!",
                "b64data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCACoAKgDASIAAhEBAxEB/8QAHQABAAAHAQEAAAAAAAAAAAAAAAIDBAUGBwgBCf/EAEwQAAEDAgQCAwsJBQYEBwAAAAECAxEABAUSITEGQRNR0QcUFSJhcYGRk5SxFjI1VFVzkqHBIzNCU2I2RXJ0gvAXJNLhJjRDRFKDwv/EABoBAQADAQEBAAAAAAAAAAAAAAABAgQDBQb/xAAsEQACAgECBQEIAwEAAAAAAAAAAQIRAwQSEyExQVEGBRQiMmFxgbEzQuHw/9oADAMBAAIRAxEAPwDqmlKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUBZxxNgUkeGsMkGD/zTeh6t6mDiDBlAEYvh5B6rlHbXPOEOZeCXpMaK/Wue8adcbu1FtSklS1EwT10B9DPD+D8sWw/3lHbXvhzCOWKWHvCO2vnKy5dPvNtMqecdcIShCJUVKOwA3J2EVehwvxbywHHPcneygPoCMbwr7TsfeEdte+GcL+0rL26e2vn98mOLvsLHfcneynyY4u+wsd9zd7KUwfQLwxhv2jZ+3T208LYb9oWntk9tfP35M8XfYWO+5u9le/Jri77Cx33N3spTB9AvC2HfaFp7ZPbXvhXD/r9p7ZPbXz8+TfF42wPHfc3eyvRw7xeNRguO+5u9lKYPoD4Vw/6/ae2T2174Uw/69a+2T218/vAHGP2Nj3ubvZTwDxj9j497m72UoH0BGJ2HK+tfbJ7a98JWP1229qntr5/eA+MR/c+Pe5u9lPAvGX2Rj3ubvZSmD6BDEbLleW3tU9tejELPld2/tE9tfPzwNxmP7px73N3sr3wTxpH0Vj3ujvZSgfQLv6z+tMe0Fei9tPrLHtBXz9GF8Z/ZmP+6O9lQnDuMQoJVh2OhREgG2d1jntUNqKthc3SPoJ37a/WWfaCvRd252uGfxivnz4N4xH93Y77s72VaTi+JIUQq8uEkEggqIjyGqxnGXyslpo+jhureQOnak7eONaVwlwJiV1dYfjrd0+t0C3Ck5zOUg8jSrkG0bDxuCnIOhCh+ZrQXEBzXhJOpUo+ma33hpI4DWQf4T+taCxwzc/6lfGgJnCSsvFeCqJAAvWD5ocTXaHhRmP3zf4q4t4Ug8UYPKQod+sjLG/jp0rdiuGeLRiScIRbs97Lt30i46JfRgOOZoKujnMCExuPKNq2aTBDNalNRryVk2uiNzeE2f5zf4v+9e+E2f5yPxDtqBWH4flkWjapP8mNerbeo14XZAaWCMw3HRHf0Csj1GPyKkPCbP8ANR+IVaV3bvymTcdMo2fe6UiHRkCwXCSRn3gp/hVMcoq6Jw2xK47za3gDoo19VQJtcHUSlLVupSRrlRMfl8JqPecfkipXRjSL3Gbe1datHCpSlKyOPupUvdHjKlSht0kRAnXKN6qnr/GUZkN3iFoykpcBb6QnOQNDCT4hCgNJKY0kmr0LHDCSSwwlIk/uZ/TfyVhvdCwa5WrDMU4eYYW5h6nXF23RLBfBCYSMqdTod4HLbSu2nnizZFByq/P/AHcNSXYu2HXuMJxBhd3doFupKFPJTkUCrokhQMkFIzAkZQdZnSDUKl4javjwfeL6Jbzil9I90/iynIPHVKUxnmNQYmdqtnAeCv2tpiV/jdnaIevVJfbt2WSkMQn5kEaHr3BOtXBF5h2G4z0t/hNpcsPto6NKkoEOJk/xDQaiTy032rnqMuLDl4UZbvqPiS3NE/FrvFVsMMWd3mlhxLzmZtMrKCAdIIIURGXT41KfvscS64G73O3BCClLJJGc+MZgZsuXSMpGmh1FfYWtmiwz31jbsvqWtSm0NApTmWuEiNYGUjbQVqxvhviJpxvh25trAtWdwl9WIFC9UlWbo0qKZneRAEeutekxY88XKU1Gq6+P8Ibl4NnYNfYj36XMUeEdAkFIWjowowTlA15GSZ120q+eEmv5qPxCqNqxw91OdNvbADdPRAkeobVErD7DLKbS3zDraGvm0rD7ziXKy+2XgqhiTX8xH4qkJukXGKNhK0qIYWdD/UmqZFlaZ1oVZWuYHSG0iQamW1rbW+KNlhpptSmFTkQE/wASdDXl+2NRCWjyJeDtp4y4itFz51wzif0ldffK+JruauGcT+krr75XxNeF6UfPJ+DXrf6mVdz0xZ4//lP1pXnc/wD/ACXEB6rWfzpX2R55trCl/wDgJW3zT+taDxkzc+lXxreeFLjgZX+E/rWi8X/fz5VfGgKjg/8AtdgkjTv5jT/7E12wvGrdnG7bC1W9yp11sqDgaUUiMoicsR42p2B0MVxPwf8A2twPT/3zHKf/AFE13ehCVLSpSGy8lEEqEEAx6Y200G1UkChOXKZUUkaSCNT6P09NSr66btkJccUc5GiDErPkHV5Yj8hUq9deObvNppahpnWCQB5EnT/e1UVta9C53zfnO4dhlmeXPWOX5DyZZN3SRWTl0RC49e3yClSuhZVoQjmPPz+HV11E1YpQyptolK1JUEkCYURE+WNDVYlcutKDa/2aw5GU6+Kd5O0KnqmDrUtvD7lRKU3l00nUhOcKAjbzmOtUzz3mY411b5iMaIH2nEvBbNyhpsCOiWykx4qRObfcE7cz6JSU3aUAG9QpR2PewyzoI1I0meenwrl2bnRqaU7dhZkhRXkVrl0I3I8U6mTrHlqQtgtqQTfXahIUUBxJCoPXGldG0XPLtLqrS4WRAShYDeQDdUgzvsY59dWprD0rYS8u4SjowgLzJPi59p066udylTNtfFZcUXczkOGQgGTAHpGvk0jWo7FSfB7bam0KQpCZ8UeNAG87gflyrPuSzfgvXwFG0zb5FLVibCUpBP70bDXYGQddtDy8lTi0wlBU5fIWhCggjpAYJJEHfqI5fGq2GFtONqtmSHFZjKE6mOemulei3aUyGWrRgNpGZSUpbjTmRGnVNaLiynMpm12zCoaetEkCRDqdJ1kSZjQ+qqpsJUrK5kEoKh4wBEEjlyzCDpvpUu4sbZ94FNsw44JXmIEzlJM6Qdzrr1716tBK1qBbSVfOiDuZgHkJ1jada5yoFLcyiHUg5kb+VJ37ahSQrE2lJIILCz5/GTVTlCR84GsfxO9Vhd1LAQvKlKQlRnLnebSQY8ijH+5832or0so9ztg/kTMkrhnE/pK6++V8TXXdzxrhzXG1pw2hwm6czBwlslIOXMEhQ0zdfn69K5ExP6SuvvlfE15/pjDPE571VpP9nfWSUkqMo4BnvPHgOdp+tKh4EMWmORztf1pX1xhNlYQ5m4GWP6e2tKYr++H+JXxrcWBLnghYPJNadxT98POr40BUcIhR4swUNqIWb5gAgTrnTrHPXlXcC7XEE3ja271rvUBIU24yVLIA26TNE/6fXvXD/CRy8VYMZiL1k+b9omuxrHGLu6TaqSq0Ut9CSlsF0xKZylWSJ07KpKwV7hzqyjMuNkNg/Hr8semqhTffCEqbShLyUwpsEKlIAEp5TG433I5gW6yu03lhbXC3EIDzaXC0ArxSQD1QTynnVT0zKEtloKW5JnP4uWDoQBud+dZr7Ek5tAdbUpxxQKYhStREfN656t/RvVLcW1o60y0TcpQwlxSVJeyqkkEq2/h5dU61VJvC8tRu0B6AcseKZJGhI0jU8ifNvUD3QPBXSZoU2tkpUkKAQqJAIIgaDlNTGVdGOpAm3aSHMibxaHFIcOYlXjJOYKB33iddedQtWgC2XE3GIkNDKUqWFBRSQfG69BEQNOqpSsPw4KCWks9GAkJzlyYSZjqjTaY+NeKw7Dykp6G3CSCmB0nP/fp5zpXTd9SCK4SyxZ3SWXHICQlaVJSoJISQNBoCQTPM7761Mw8IVbMBtK3VFAgRHLnGp/KrbxJiltg9i46lJL12sNnvdCytwhKjqN4jMf8AtThrG/CWHlbS30dEotLQ6CCIAMZTygjSK4ywZN3Gr4elluJGtl8y9wkHxksz51H8wYqJ4ozKS04hLRIIEK9RMSYPljmIqnD/AFhH4a96b+lHqFTuVURRNZcSysKQ4qR/RoR69t58lR3EIIU245kWM6JSNtRqeuQR+dSA6Z+aj8IqixO+UmEpIU+oQnSAhIJ5DQDq8vpNc8maOKDlIvDG5y2ooeJMYVh1qpbKQ66FJCyVQG0kxmJ5QPPA1NY029cYth5uEW5yqW30YblfSJD7KiuYkjf1E1kFrbi4cKCCWkn9oT/Go6x+cnyQKuaI8JtQAAGFx5PGTXk6rOsujlknDmua+xs2cLIscZfcwy34WvWO6MMTu3emsH3FvIQ2teVKgnxStHzQobBQM6bbxy1if0ldffK+JruauGcT+krr75XxNcvTeolnlNy7JL9ldXBRSoyPghWW0xv/AC360qVwaYtMY/y36ilfVmE2DgKyOC3QeoitSYkf2p/xK+NbTwZZHCzyZ6/1rVeJfvf9RoCo4W/tPhAIJm8Z5/1jnXYuGY7iDFzhaU4j0OFsMW7blt3i8VylMOAnoyDOg0IGx5Qri2xWW763WkkKS4lQPmIM1uG0a7/w5teHY8p3EuidedtVoUjKlAkgK2JieYB2ootkNm8MHbS1hNih22bDiGEJUFFQIISBGh3mriyEuOJbRbMSZJJU5AA1JJzbRqTWO9zJVhd8DYU/f27FxcKS5mcdaStRhxUAk67QPNUrHsZwXDMSvW3bixtENtpWW1YX0kJKdSFBMEaSd41nqrnwHdizK1XFl02XoihkQCtClZvKYJI9G9LoN21+EqCy0hJIhQPSJUPFV1EeTr3kiqHBHcEvLLOm1tX1IWUKcVYhrNrOgI2gjrB9dEXrTNxc2DrDz1q2rpWOhbUVMoXJhJAIjMFDKdIiI0qJYnHmSmetF0ltCbjMuUoSO9kKzSY1MyVdRka6mdRUxBLLy27m5NylCkJKkNhvRCvGggzBiN4gmpriWrdhS7Nbzz6huWFoU2kjYCIzakEzoNBrqLQcQsmxAURlWGvHbdRKoBKfmEZokiOXVua1IWY/3S8zFnhrV7aYtiFu6gPqfwtpCHWVkIKQQNMp8bTfxop3N1g2l2hiwxa0tApKkrxMDpXlmcx05DxE+QCKym+uU3VulHRKUtCUIWG2nl5SkIywQiD1nSOfURCy8lLaW7ZhxWSQ5mYeGUkAwfFkiSqBoYg1aWTI1wklX+kbI3u7lWBrUwcqoW8SZLqmyDKFBC0pQ6pSVGYBGQQfm+jad6hucTW2rKzYX7qpAnvVwD15Z/KKyzThzZeMXJ0iovbkWyBACnV6ITO56/IOs/rANpTnW6G0rCn3NVLMaDYnzbCPR1mp1l+3xVo3rb0auLDrKkpKU6BIzCIkgxzg1db63tnnGlWimbXLIVFslWYEjQzoPz+IrItHPXPdLlFPp5Nqyx0qqPOT7+CBpDbDKWmyAkabzJ8p5ncny1JZdbVjCW0rSVpYVKQrUDMjlvVHgF7aYuwbq0vkOsJdKFA2TaZKd09adxpAPXFXZ1VsrFWjbsttq6FWYpQE6Zk7kVPtbT7NFka7Iz4JN5VZU1wzif0ldffK+JruauGcT+kbr75fxNeL6U65Pwadd0iXzhExaYv5bf8AUUqXwqYtcV+4j86V9meeZ1hCgcAuk80lQ/M1rDFJLhEkSVDzVuR3hLiDh5y+tMXwe+QglWR5tlTrSgTuFpkeWJB6xWu8U4WxV50G1s3lpBVMpy76896AxVpRbcSrfKQfPBmr8xxVfW9k9aMLcbtndXG0OZQqYGsDUaeaofkjjg3w9f4kioDwrjI3slfjT21KbQqzNOHe67e4Jg1thzWFsOoYBAWp0gmVE7DzxUrEe6gnEnbh2+wBh5b6A0vNduxkEaATAEgEgRJ1rDzwxjA3sz+NHbUPyaxbnan0uJ7abmRRsG17s93aJdFtglo2l1xTqwHVnxlHUx+fIVNb7uOKN3IeThVpOUoI6RWskRPq089a4+TuKDe2HtU9tQnh/Evq49ojtpuZNG0v+PmL8sIsvaKq3td0rEcZW41b8Mt3axcd/FDK3VZF/NzQnYSfWeZrXvgHEvq6fao7ar8Ht8awtTht7dpSVlKihxaSMyTKVaGZBnnBBg6Eim5ijJ7Ti3ELm/TcWfCinluNF0Ntl5SVoDoGfSSRnTlJmJ03giNzi+/WXCrhHUtoCjnuZCT80zMychOaZMHeDVpbxTi1pLYaDKOjSEIyJaTCQptUabgllBgzOvWZHEOLTbpYKkqZSkJCStswAABqTO35lRGpNLBe7rul4jaYp4QueGbZi7DiV5nC8kZwnTQkCYIO2xHKq893vHeWGYd619tYRi6OJMXtmmL9KXUNLU43K25TmjSZnLoNJgeTWrYOG8WO1qPap7abmDYLvdwxtx4uHDsPkgJ/j0A9PlNQnu345yw7DvUv/qrAxwtjCtrM/jT21GnhHG1bWKvxpP603MUZfYd1/FLBLotMKw5HTOdKskuqKlQEySVydEpEbACKqWu7djrdyHhh+GFQSUAFKzuQf/l5BWGDgvHTtYr9YqMcD4+drFf4Sa55YRzQePJzTJi9rtGcHu88RcsNwn8Dn/XWpbhxTz7jqwApxRUY6yZ09dZIOBOIVaDD3vZrP6VNT3PeJFbYZdHzMOH/APNcNPosOmvhRqy08kp/Myj4Vks4ikc2wPzFKy7hLuecTl11lOD3ynH1IQJtnEpSJkkqUAAB1zStRQ7lpSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUApSlAKUpQClKUB//9k="
            }
        ],
        "video": [
            {
                "caption": "How to install the game",
                "url": "https://www.youtube.com/watch?v=jS3ZxOtTD5A"
            }
         ]
    
    }
    
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"media": {
       "photo": [   {
          "id": 14,
          "type": "photo",
          "caption": "Outstanding product!",
          "imageType": "jpeg",
          "width": 168,
          "height": 168,
          "locale": "en_US",
          "published": false,
          "dateCreated": null,
          "normalUrl": "http://dev.turntodev.com/devimagestore/item/temp/071FE5C85C1CB762BBCA8098742D946D_1454970511491_1.jpeg"
       }],
       "video": [   {
          "id": 15,
          "type": "video",
          "caption": "How to install the game",
          "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": false,
          "dateCreated": null
       }],
       "audio": []
    }}
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "No catalog item found for sku (5558886554)",
       "code": 106
    }]}
    

User Media List 

Get user media
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/media?email=andrew@sample.com&sku=12345
  • Parameters
  • 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
  • Headers
    Content-Type: application/x-www-form-urlencoded
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"media": {
       "photo": [   {
          "id": 1,
          "type": "photo",
          "caption": "Perfect product!",
          "imageType": "jpeg",
          "width": 168,
          "height": 168,
          "locale": "en_US",
          "published": true,
          "dateCreated": "2016-04-27T16:31:09-04:00",
          "normalUrl": "http://dev.turntodev.com/devimagestore/media/temp/31C24FCD4822D15AE8394919BB35114D_1461789069312_1.jpeg",
          "thumbnailUrl": null,
          "originalUrl": "http://dev.turntodev.com/devimagestore/media/temp/31C24FCD4822D15AE8394919BB35114D_1461789069312_1.jpeg",
          "tags": [
            "CSR"
          ]
       }],
       "video": [   {
          "id": 2,
          "type": "video",
          "caption": "How to install the game",
          "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": false,
          "dateCreated": "2016-02-09T11:40:27-05:00",
          "tags": []
       }],
       "audio": []
    }}
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Unknown Email Address",
       "code": 129
    }]}
    
Next  Previous

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

PropertyTypeDescription
idnumberTurnTo unique ID for this question
dateCreateddateDate question created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
approvedDatedateDate question approved (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
textstringQuestion text
textLengthnumberNumber of characters in question text
localestringLocale of question
publishedbooleanIs published?
csFlagbooleanIs flagged for customer service?
irrelevantFlagbooleanIs irrelevant?
unansweredAlertbooleanUnanswered alert?
reviewedFlagbooleanIs reviewed?
autoModeratedbooleanIs auto moderated?
flagForExpertbooleanFlag for expert?
upVotesnumberNumber of up votes received
isStaffbooleanIs staff?
isCategoryQuestionbooleanIs category question?
tagsstringList of tag codes associated with this question
userresourceThe user that asked this question. Nested user block - see Users section
userIpAddrstringThe IP address of the UGC author
catalogItemsresourceProducts for which this question was asked. Nested products block - see Products section
answerCountnumberNumber of answers posted for this question
answersresourceAnswers posted for this question. Nested answers block - see Answers section

Question List 

Get questions
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/questions?sku=12345&related=false&publishedOnly=true&tags=CSR,DAM,SOT&locale=en_US&limit=10&offset=20
  • Parameters
  • sku
    string (required) Example: 12345

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

    related
    boolean (optional) Default: 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 

    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 

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

Question Detail 

Get question
/v1.1/questions/{id}

This endpoint will return a single question with it’s nested answers and replies. The required question is identified by it’s 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.

Resource URL

https://api.turnto.com/v1.1/questions/12345
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the question.

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

Create Question 

Create a question
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/questions

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)

PropertyRequiredNote
textYes
localeNoIf omitted use site default.
user.firstNameNo
user.lastNameNo
user.nickNameNo
user.emailAddressNoEither email address or externalId is required to identify the user
user.externalIdNoEither email address or externalId is required to identify the user
user.cityNo
user.stateNo
user.countryNo
user.ageRangeNo
user.shopperProfiles[].idNo
user.shopperProfiles[].valueNo
userIpAddrNoThe IP address of the UGC author
catalogItems[].skuYesThe 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[].titleNoThe 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[].urlNoThe 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
  • Request
  • 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": "${#TestCase#sku}",
           "title": "Fruit Samarai",
           "url": "http://dev.turntodev.com/products?sku=${#TestCase#sku}"
            }
        ],
        "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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Location: https://api.turnto.com/v1.1/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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "No catalog item was found for sku (7969494)",
       "code": 106
    }]}
    

Question Vote Up 

Vote up for a question
/v1.1/questions/{id}/voteup

This endpoint registers an up vote for a question.

Resource URL

https://api.turnto.com/v1.1/questions/12345/voteup
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the question.

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

Answer More Questions 

Get AMQ Data
/v1.1/amq {?email, userId, sku, locale, questionsOnly, purchasesOnly, limit, offset}

The Answer More Questions (AMQ) box is displayed after a user has written an answer or a review or clicks on the “Questions that need answers” link in the TurnTo widget.

The AMQ box is used to display questions that the user may be able to answer. Questions shown are for the current item, related items, and items connected to previous purchases.

In addition to questions, the AMQ box is also used to display products purchased by the user so that user may provide a review.

This endpoint supports an API implementation of the AMQ functionality.

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.

Resource URL

https://api.turnto.com/v1.1/amq?email=a@a.com&sku=12345
  • Parameters
  • 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 

    Only return questions.

    Choices: true false

    purchasesOnly
    boolean (optional) Default: false 

    Only return purchases.

    Choices: true false

    limit
    number (optional) Default: 10 

    Maximum number of questions to return.

    offset
    number (optional) Default: 0 

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

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

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

PropertyTypeDescription
idnumberTurnTo unique ID for this answer
dateCreateddateDate answer created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
reviewedDatedateDate answer reviewed (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
textstringAnswer text
textLengthnumberNumber of characters in answer text
localestringLocale of answer
publishedbooleanIs published?
csFlagbooleanIs flagged for customer service?
inappropriateFlagbooleanIs inappropriate?
reviewedFlagbooleanIs reviewed?
autoModeratedbooleanIs auto moderated?
upVotesnumberNumber of up votes received
thankedbooleanIs thanked?
isStaffbooleanIs staff?
purchaseDatedateDate product purchased (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
itemQuestionIdnumberTurnTo unique ID for the question
tagsstringList of tag codes associated with this answer
userresourceThe user that posted this answer. Nested user block - see Users section
userIpAddrstringThe IP address of the UGC author
catalogItemsresourceProducts for which this answer is also applicable. Nested products block - see Products section
replyCountnumberNumber of replies posted for this answer
repliesresourceReplies posted for this answer. Nested replies block - see Replies section

Question Answers 

Get answers for a question
/v1.1/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.

Resource URL

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

    The ID of the question.

    publishedOnly
    boolean (optional) Default: true 

    If true, only return published answers.

    Choices: true false

    locale
    string (optional) Example: en_US

    Only return answers for this locale.

    limit
    number (optional) Default: 50 Example: 10

    Maximum number of answers to show.

    offset
    number (optional) Default: 0 Example: 10

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

    sort
    string (optional) Default: dateCreated:desc 

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

Answer Detail 

Get answer
/v1.1/answers/{id}

This endpoint will return a single answer.

The required answer is identified by it’s ID.

Resource URL

https://api.turnto.com/v1.1/answers/12345
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the answer.

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

Create Answer 

Create an answer
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/questions/12345/answers

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)

PropertyRequiredNote
textYes
localeNoIf omitted use site default.
user.firstNameYes
user.lastNameYes
user.nickNameNo
user.emailAddressNoEither email address or externalId is required to identify the user
user.externalIdNoEither email address or externalId is required to identify the user
user.cityNo
user.stateNo
user.countryNo
user.ageRangeNo
user.shopperProfiles[].idNo
user.shopperProfiles[].valueNo
userIpAddrNoThe IP address of the UGC author
catalogItems[].skuNoThe 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[].titleNoThe 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[].urlNoThe URL of the catalog item for this SKU. This can be omitted if the item already exists in your site’s catalog at TurnTo
turntoTrackingTokenNoThe tracking token included in the create answer link.
  • Request
  • 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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Location: https://api.turnto.com/v1.1/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
  • 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 

Vote up for an answer
/v1.1/answers/{id}/voteup

Registers an up vote for an answer.

Resource URL

https://api.turnto.com/v1.1/answers/12345/voteup
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the answer.

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

Flag Answer 

Flag answer as inappropriate
/v1.1/answers/{id}/flag

Flag an answer as inappropriate.

Resource URL

https://api.turnto.com/v1.1/answers/12345/flag
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the answer.

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

Thank Answerer 

Thank an answerer
/v1.1/answers/{id}/thank

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

Resource URL

https://api.turnto.com/v1.1/answers/12345/thank
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the answer.

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

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

PropertyTypeDescription
idnumberTurnTo unique ID for this reply
dateCreateddateDate reply created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
reviewedDatedateDate reply reviewed (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
textstringReply text
localestringLocale of reply
publishedbooleanIs published?
csFlagbooleanIs flagged for customer service?
reviewedFlagbooleanIs reviewed?
autoModeratedbooleanIs auto moderated?
isStaffbooleanIs staff?
userresourceThe user that posted this reply. Nested user block - see Users section
userIpAddrstringThe IP address of the UGC author

Answer Replies 

Get replies for an answer
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/answers/12345/replies?publishedOnly=true&locale=en_US&sort=textLength:desc&limit=10&offset=20
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the answer.

    publishedOnly
    boolean (optional) Default: true 

    If true, only return published replies.

    Choices: true false

    locale
    string (optional) Example: en_US

    Only return replies for this locale.

    limit
    number (optional) Default: 50 Example: 10

    Maximum number of replies to show.

    offset
    number (optional) Default: 0 Example: 10

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

    sort
    string (optional) Default: dateCreated:desc 

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

Reply Detail 

Get reply
/v1.1/replies/{id}

This endpoint will return a single reply.

The required reply is identified by it’s ID.

Resource URL

https://api.turnto.com/v1.1/replies/12345
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the reply.

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

Create Reply 

Create a reply
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/answers/12345/replies

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)

PropertyRequiredNote
textYes
localeNoIf omitted use site default.
parentReplyIdNoProvide parentReplyId if this reply is to an earlier reply.
user.firstNameYes
user.lastNameYes
user.nickNameNo
user.emailAddressNoEither email address or externalId is required to identify the user
user.externalIdNoEither email address or externalId is required to identify the user
user.cityNo
user.stateNo
user.countryNo
user.ageRangeNo
user.shopperProfiles[].idNo
user.shopperProfiles[].valueNo
userIpAddrNoThe IP address of the UGC author
  • Request
  • 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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Location: https://api.turnto.com/v1.1/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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "No answer was found for the specified id (49439)",
       "code": ???
    }]}
    
Next  Previous

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

PropertyTypeDescription
idnumberTurnTo unique ID for this comment
dateCreateddateDate comment created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
textstringComment text
textLengthnumberNumber of characters in comment text
localestringLocale of comment
publishedbooleanIs published?
tagsstringList of tag codes associated with this comment
userresourceThe user that posted this comment. Nested user block - see Users section
userIpAddrstringThe IP address of the UGC author
orderIdstringUnique Id of order associated with this comment
catalogItemsresourceProduct for which this comment was posted. Nested products block - see Products section

Comment List 

Get comments
/v1.1/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.

Resource URL

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

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

    publishedOnly
    boolean (optional) Default: true 

    If true, only return published comments.

    Choices: true false

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

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

    locale
    string (optional) Example: en_US

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

    limit
    number (optional) Default: 50 Example: 10

    Maximum number of comments to show.

    offset
    number (optional) Default: 0 Example: 10

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

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

Comment Detail 

Get comment
/v1.1/comments/{id}

This endpoint will return a single Comment.

The required comment is identified by it’s ID.

Resource URL

https://api.turnto.com/v1.1/comments/12345
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the Comment.

  • Request
  • Headers
    Content-Type: application/x-www-form-urlencoded
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "id": 8,
       "text": "This Master Chef has loads of power and more speeds than you will ever need!",
       "locale": "en_US",
       "textLength": 76,
       "published": true,
       "dateCreated": "2015-07-01T09:49:43-04:00",
       "catalogItems":    [{
          "sku": "11112222",
          "title": "MultiChef",
          "url": "www.topchef.com/food-processors/multichef"
       }],
       "orderId": "5555522",
       "user":    {
          "nickName": "Andy A.",
          "firstName": "Andy",
          "lastName": "Adamson",
          "emailAddress": "andrew@sample.com",
          "externalId": null,
          "city": "Miami",
          "state": "FL",
          "country": "US",
          "ageRange": 1
       },
       "tags": []
    }
    
  • Response  404
  • 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 a comment
/v1.1/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 it’s order Id.

Resource URL

https://api.turnto.com/v1.1/comments

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)

PropertyRequiredNote
textYes
localeNoIf omitted use site default.
user.firstNameYes
user.lastNameYes
user.nickNameNo
user.emailAddressNoEither email address or externalId is required to identify the user
user.externalIdNoEither email address or externalId is required to identify the user
user.cityNo
user.stateNo
user.countryNo
user.ageRangeNo
user.shopperProfiles[].idNo
user.shopperProfiles[].valueNo
userIpAddrNoThe IP address of the UGC author
orderIdNoThe Id of an order that this comment is associated with. The order must already exist at TurnTo
catalogItems[0].skuYesThe SKU of the catalog item that this comment is about. Typically a catalog item would already exist in your site’s catalog that’s been uploaded to TurnTo. If that is not the case, and you also pass the title and url properties, a new catalog item record will be created.
catalogItems[0].titleNoThe title of the catalog item that this comment is about. This can be omitted if the item already exists in your site’s catalog at TurnTo
catalogItems[0].urlNoThe 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
  • Request
  • Headers
    Content-Type: application/json;charset=UTF-8
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
    Body
    {
        "text": "This Master Chef has loads of power and more speeds than you will ever need!",
        "locale" : "en_US",
        "catalogItems":     [{
           "sku": "11112222"
        }],
        "orderId": "5555522",
        "user":          {
            "nickName": "",
            "firstName": "Andy",
            "lastName": "Adamson",
            "emailAddress": "andrew@sample.com",
            "city": "Miami",
            "state": "FL",
            "country": "US",
            "ageRange": 1
        },
        "userIpAddr": "123.456.789.100"
    }
    
  • Response  201
  • Headers
    Content-Type: application/json;charset=UTF-8
    Location: https://api.turnto.com/v1.1/comments/{id}
    Body
     {
        "id": 8,
        "text": "This Master Chef has loads of power and more speeds than you will ever need!",
        "textLength": 76,
        "locale": "en_US",
        "published": true,
        "dateCreated": "2015-07-01T09:49:43-04:00",
        "catalogItems":    [{
           "sku": "11112222",
           "title": "MultiChef",
           "url": "www.topchef.com/food-processors/multichef"
        }],
        "orderId": "5555522",
        "user":    {
           "nickName": "",
           "firstName": "Andy",
           "lastName": "Adamson",
           "emailAddress": "andrew@sample.com",
           "externalId": null,
           "city": "Miami",
           "state": "FL",
           "country": "US",
           "ageRange": 1
        }
     }
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Missing or invalid parameters sku",
       "code": 114
    }]}
    
Next  Previous

Reviews 

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

Resource Properties - Review

PropertyTypeDescription
idnumberTurnTo unique ID for this review
dateCreateddateDate review created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
reviewedDatedateDate product reviewed (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
titlestringReview title
textstringReview text
textLengthnumberNumber of characters in review text
localestringLocale of review
ratingnumberProduct rating (1,2,3,4, or 5)
publishedbooleanIs published?
csFlagbooleanIs flagged for customer service?
inappropriateFlagbooleanIs inappropriate?
reviewedFlagbooleanIs reviewed?
autoModeratedbooleanIs auto moderated?
incentivizedbooleanDid reviewer receive incentive?
upVotesnumberNumber of up votes received
downVotesnumberNumber of down votes received
orderIdstringThe order Id that is associated with the review
purchaseDatedateDate product purchased (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
tagsstringList of tag codes associated with this review
userresourceThe user that posted this review. Nested user block - see Users section
userIpAddrstringThe IP address of the UGC author
catalogItemsresourceProduct(s) for which this review is applicable. Nested products block - see Products section
dimensionsresourceCustom dimension properties that can be captured for this product. Nested dimensions block - see Products section
mediaresourceMedia associated with this review. Nested media block - see Media section
responses[].textstringResponse text
responses[].localestringLocale of response
responses[].userresourceThe user that posted this response. Nested user block - see Users section
responses[].dateCreateddateDate response created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
syndication.sourceNamestringSyndication source name
syndication.siteUrlstringSyndication source site URL
syndication.logoUrlstringSyndication source logo URL

Review List 

Get reviews
/v1.1/reviews {?sku, related, includeRelated, 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.

Resource URL

https://api.turnto.com/v1.1/reviews?sku=12345&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=10&offset=20&sort=textLength:desc
  • Parameters
  • sku
    string (required) Example: 12345

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

    related
    boolean (optional) Default: 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 

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

    Choices: true false

    publishedOnly
    boolean (optional) Default: 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: 10

    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 

    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 text textLength

  • Request
  • Headers
    Content-Type: application/x-www-form-urlencoded
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "reviews":    [
                {
             "id": 27,
             "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": null,
             "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://dev.turntodev.com/devimagestore/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":          [
                             {
                    "text": "Yes, of course...  they are transparent!!",
                    "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":                   {
                          "text": "Staff",
                          "imageUrl": ""
                       }
                    },
                    "dateCreated": "2015-10-23T10:37:41-04:00"
                 },
                             {
                    "text": "Exactly - well said.",
                    "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":                   {
                          "text": "Staff",
                          "imageUrl": ""
                       }
                    },
                    "dateCreated": "2015-10-23T11:41:10-04:00"
                 }
             ],
             "reviewedDate": null,
             "purchaseDate": null,
             "dateCreated": "2015-09-29T12:43:41-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
             }
          },
                {
             "id": 25,
             "rating": 4,
             "title": "These are terrific!",
             "text": "These are the best widgets I ever used without doubt.",
             "textLength": 53,
             "locale": "en_US",
             "csFlag": false,
             "inappropriateFlag": false,
             "reviewedFlag": false,
             "autoModerated": false,
             "published": false,
             "incentivized": false,
             "upVotes": 0,
             "downVotes": 0,
             "orderId": "NY4003948883",
             "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": 4,
                   "dimensionId": 4,
                   "dimensionLabel": "Impression",
                   "label": ["Stylish"]
                }
             ],
             "media":          {
                 "photo": [],
                 "video": [],
                 "audio": []
             },
             "responses": [],
             "reviewedDate": null,
             "purchaseDate": null,
             "dateCreated": "2015-09-29T12:43:38-04:00",
             "tags": [
                "SOT",
                "ALU"
             ],
             "user":          {
                "nickName": "Bart S.",
                "firstName": "Bart",
                "lastName": "Simpson",
                "emailAddress": "bart@simpson.com",
                "externalId": null,
                "city": "Springfield",
                "state": "OH",
                "country": "US",
                "ageRange": 1
             }
          },
                {
             "id": 24,
             "rating": 4,
             "title": "These are terrific!",
             "text": "These are the best widgets ever.  Really amazing quality.",
             "textLength": 57,
             "locale": "en_US",
             "csFlag": false,
             "inappropriateFlag": true,
             "reviewedFlag": false,
             "autoModerated": false,
             "published": false,
             "incentivized": false,
             "upVotes": 1,
             "downVotes": 1,
             "orderId": null,
             "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"]
                }
             ],
             "media":          {
                 "photo": [],
                 "video": [],
                 "audio": []
             },
             "responses": [],
             "reviewedDate": null,
             "purchaseDate": null,
             "dateCreated": "2015-09-29T12:43:29-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
             }
          },
                {
             "id": 23,
             "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": null,
             "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"]
                }
             ],
             "media":          {
                 "photo": [],
                 "video": [],
                 "audio": []
             },
             "responses": [],
             "reviewedDate": null,
             "purchaseDate": null,
             "dateCreated": "2015-09-29T12:31:22-04:00",
             "syndication":          {
                "sourceName": "Super Shades",
                "siteUrl": "http://www.supershades.com/",
                "logoUrl": "http://www.supershades.com/logo.png"
             },
             "tags": [],
             "user":          {
                "nickName": "Bart S.",
                "firstName": "Bart",
                "lastName": "Simpson",
                "emailAddress": "bart@simpson.com",
                "externalId": null,
                "city": "Springfield",
                "state": "OH",
                "country": "US",
                "ageRange": 1
             }
          },
                {
             "id": 22,
             "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": null,
             "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": [],
                 "video": [],
                 "audio": []
             },
             "responses": [],
             "reviewedDate": null,
             "purchaseDate": null,
             "tags": [],
             "dateCreated": "2015-09-29T09:59:22-04:00"
          }
       ],
       "offset": 0,
       "limit": 5,
       "total": 11
    }
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Missing or invalid parameters sku",
       "code": 114
    }]}
    

Review Detail 

Get review
/v1.1/reviews/{id}

This endpoint will return details of a single review. The required review is identified by it’s ID.

Any published media content associated with this review will be embedded in the response.

Resource URL

https://api.turnto.com/v1.1/reviews/12345
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the review.

  • Request
  • Headers
    Content-Type: application/x-www-form-urlencoded
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "id": 14,
       "rating": 4,
       "title": "These are terrific!",
       "text": "These are the best widgets ever.  Really amazing quality.",
       "textLength": 57,
       "locale": "en_US",
       "csFlag": false,
       "inappropriateFlag": false,
       "reviewedFlag": false,
       "autoModerated": false,
       "published": false,
       "incentivized": false,
       "upVotes": 0,
       "downVotes": 0,
       "orderId": "NY4003977783",
       "catalogItems": [   {
          "sku": "700285064826",
          "title": "Oakley XX Frame Accessory Kit - Black",
          "url": "http://www.testtt.info/tt4_2/responsivesite/qaOverlay-reviewsEmbed.php?sku=700285064826",
          "category": null,
          "reviewCount": 7,
          "averageRating": 4.86,
          "ratingBreakdown":       {
             "1": 0,
             "2": 0,
             "3": 0,
             "4": 1,
             "5": 6
          }
       }],
       "dimensions":    [
                {
             "type": 1,
             "dimensionId": 1,
             "dimensionLabel": "Overall Quality",
             "value": 1
          },
                {
             "type": 2,
             "dimensionId": 2,
             "dimensionLabel": "Comfort",
             "value": 8,
             "label": ["High"]
          },
                {
             "type": 3,
             "dimensionId": 3,
             "dimensionLabel": "Weight",
             "label": ["Light"]
          },
                {
             "type": 4,
             "dimensionId": 4,
             "dimensionLabel": "Impression",
             "label": ["Stylish"]
          }
       ],
       "media":    {
          "photo": [      {
             "id": 1,
             "type": "photo",
             "caption": "Desperate product!",
             "imageType": "jpeg",
             "width": 168,
             "height": 168,
             "normalUrl": "http://dev.turntodev.com/devimagestore/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
  • 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 a review
/v1.1/reviews

Creates a new review. Currently a review can only be associated with a single catalog item. The review title is optional unless defined as mandatory for the site and must not exceed 1000 characters. The review text 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 ID’s of existing media or details of new media content. Up to 5 media items may be supplied.

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.

Resource URL

https://api.turnto.com/v1.1/reviews

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)

PropertyRequiredNote
externalIdNoThe Id of the review on an external system.
dateCreatedNoDate the review was created on an external system.
titleNoReview title
textYesReview text
localeNoIf omitted use site default.
ratingYesRating for this product (1,2,3,4, or 5)
user.firstNameYes
user.lastNameYes
user.nickNameNo
user.emailAddressNoEither email address or externalId is required to identify the user
user.externalIdNoEither email address or externalId is required to identify the user
user.cityNo
user.stateNo
user.countryNo
user.ageRangeNo
user.shopperProfiles[].idNoThe Id of the shopper profile to be added
user.shopperProfiles[].valueNoValue of free-form text for a shopper profile
userIpAddrNoThe IP address of the UGC author
catalogItems[].skuYesThe 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[].titleNoThe 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[].urlNoThe 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[].valueNoPredefined dimension value
media.idsNoList of existing media Ids to be associated with the review
media.photo[].captionNoCaption for new photo associated with the review
media.photo[].b64dataNoBase64 data for new photo associated with the review
media.video[].captionNoCaption for new video associated with the review
media.video[].urlNoLink URL for new video associated with the review
turntoTrackingTokenNoThe tracking token included in the create review link.
  • Request
  • 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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Location: https://api.turnto.com/v1.1/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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Review must be at least 50 characters.",
       "code": 142
    }]}
    

Review Vote Up 

Vote up for a review
/v1.1/reviews/{id}/voteup

Registers an up vote for a review.

Resource URL

https://api.turnto.com/v1.1/reviews/12345/voteup
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the review.

  • Request
  • Headers
    Content-Type: application/json;charset=UTF-8
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "id": 27,
       "rating": 4,
       "title": "These are terrific!",
       "text": "These are the best widgets I ever used. Honest swear to god.",
       "textLength": 60,
       "locale": "en_US",
       "csFlag": false,
       "inappropriateFlag": false,
       "reviewedFlag": false,
       "autoModerated": false,
       "published": false,
       "incentivized": false,
       "upVotes": 1,
       "downVotes": 0,
       "orderId": null,
       "catalogItems": [   {
          "sku": "11112222",
          "title": "MultiChef",
          "url": "www.topchef.com/food-processors/multichef",
          "category": "processors",
          "reviewCount": 0,
          "averageRating": 0,
          "ratingBreakdown":       {
             "1": 0,
             "2": 0,
             "3": 0,
             "4": 0,
             "5": 0
          }
       }],
       "dimensions":    [
                {
             "type": 1,
             "dimensionId": 1,
             "dimensionLabel": "Overall Quality",
             "value": 1
          },
                {
             "type": 2,
             "dimensionId": 2,
             "dimensionLabel": "Comfort",
             "value": 8,
             "label": ["High"]
          },
                {
             "type": 3,
             "dimensionId": 3,
             "dimensionLabel": "Weight",
             "label": ["Light"]
          },
                {
             "type": 4,
             "dimensionId": 4,
             "dimensionLabel": "Impression",
             "label": ["Stylish"]
          }
       ],
       "responses": [],
       "reviewedDate": null,
       "purchaseDate": null,
       "dateCreated": "2015-09-26T10:01:21-04:00",
       "tags": [],
       "user":    {
          "nickName": "Bart S.",
          "firstName": "Bart",
          "lastName": "Simpson",
          "emailAddress": "bart@simpson.com",
          "externalId": null,
          "city": "Springfield",
          "state": "OH",
          "country": "US",
          "ageRange": 1,
          "shopperProfiles": [{"id": 2}]
       }
    }
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "No review was found for the specified id (756768685)",
       "code": 139
    }]}
    

Review Vote Down 

Vote down for a review
/v1.1/reviews/{id}/votedown

Registers a down vote for a review.

Resource URL

https://api.turnto.com/v1.1/reviews/12345/votedown
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the review.

  • Request
  • Headers
    Content-Type: application/json;charset=UTF-8
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "id": 27,
       "rating": 4,
       "title": "These are terrific!",
       "text": "These are the best widgets I ever used. Honest swear to god.",
       "textLength": 60,
       "locale": "en_US",
       "csFlag": false,
       "inappropriateFlag": false,
       "reviewedFlag": false,
       "autoModerated": false,
       "published": false,
       "incentivized": false,
       "upVotes": 1,
       "downVotes": 1,
       "orderId": null,
       "catalogItems": [   {
          "sku": "11112222",
          "title": "MultiChef",
          "url": "www.topchef.com/food-processors/multichef",
          "category": "processors",
          "reviewCount": 0,
          "averageRating": 0,
          "ratingBreakdown":       {
             "1": 0,
             "2": 0,
             "3": 0,
             "4": 0,
             "5": 0
          }
       }],
       "dimensions":    [
                {
             "type": 1,
             "dimensionId": 1,
             "dimensionLabel": "Overall Quality",
             "value": 1
          },
                {
             "type": 2,
             "dimensionId": 2,
             "dimensionLabel": "Comfort",
             "value": 8,
             "label": ["High"]
          },
                {
             "type": 3,
             "dimensionId": 3,
             "dimensionLabel": "Weight",
             "label": ["Light"]
          },
                {
             "type": 4,
             "dimensionId": 4,
             "dimensionLabel": "Impression",
             "label": ["Stylish"]
          }
       ],
       "responses": [],
       "reviewedDate": null,
       "purchaseDate": null,
       "dateCreated": "2015-09-26T10:01:21-04:00",
       "tags": [],
       "user":    {
          "nickName": "Bart S.",
          "firstName": "Bart",
          "lastName": "Simpson",
          "emailAddress": "bart@simpson.com",
          "externalId": null,
          "city": "Springfield",
          "state": "OH",
          "country": "US",
          "ageRange": 1,
          "shopperProfiles": [{"id": 2}]
       }
    }
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "No review was found for the specified id (756768685)",
       "code": 139
    }]}
    

Flag Review 

Flag review as inappropriate
/v1.1/reviews/{id}/flag

Flag a review as inappropriate.

Resource URL

https://api.turnto.com/v1.1/reviews/12345/flag
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the review.

  • Request
  • Headers
    Content-Type: application/json;charset=UTF-8
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "id": 27,
       "rating": 4,
       "title": "These are terrific!",
       "text": "These are the best widgets I ever used. Honest swear to god.",
       "textLength": 60,
       "locale": "en_US",
       "csFlag": false,
       "inappropriateFlag": true,
       "reviewedFlag": false,
       "autoModerated": false,
       "published": false,
       "incentivized": false,
       "upVotes": 1,
       "downVotes": 1,
       "orderId": null,
       "catalogItems": [   {
          "sku": "11112222",
          "title": "MultiChef",
          "url": "www.topchef.com/food-processors/multichef",
          "category": "processors",
          "reviewCount": 0,
          "averageRating": 0,
          "ratingBreakdown":       {
             "1": 0,
             "2": 0,
             "3": 0,
             "4": 0,
             "5": 0
          }
       }],
       "dimensions":    [
                {
             "type": 1,
             "dimensionId": 1,
             "dimensionLabel": "Overall Quality",
             "value": 1
          },
                {
             "type": 2,
             "dimensionId": 2,
             "dimensionLabel": "Comfort",
             "value": 8,
             "label": ["High"]
          },
                {
             "type": 3,
             "dimensionId": 3,
             "dimensionLabel": "Weight",
             "label": ["Light"]
          },
                {
             "type": 4,
             "dimensionId": 4,
             "dimensionLabel": "Impression",
             "label": ["Stylish"]
          }
       ],
       "responses": [],
       "reviewedDate": null,
       "purchaseDate": null,
       "dateCreated": "2015-09-26T10:01:21-04:00",
       "tags": [],
       "user":    {
          "nickName": "Bart S.",
          "firstName": "Bart",
          "lastName": "Simpson",
          "emailAddress": "bart@simpson.com",
          "externalId": null,
          "city": "Springfield",
          "state": "OH",
          "country": "US",
          "ageRange": 1,
          "shopperProfiles": [{"id": 2}]
       }
    }
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "No review was found for the specified id (145454)",
       "code": 139
    }]}
    
Next  Previous

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

PropertyTypeDescription
idnumberUnique Id for this article
externalIdstringExternal Id for this article
dateCreateddateDate article created (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
titlestringArticle title
textstringArticle text
localestringLocale of article
publishedbooleanIs published?
expirationDatedateDate this article expires (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ)
catalogItemsresourceProduct(s) for which this article is applicable. Nested products block - see Products section
brandsstringList of brands for which this article is related
categoriesstringList of categories for which this article is related
searchTermsstringList of search terms for which this article is related

Article List 

Get articles
/v1.1/articles {?externalId, sku, publishedOnly, locale, limit, offset, sort}

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

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

If externalId is supplied, this endpoint will return a single article identified by it’s external Id.

Resource URL

https://api.turnto.com/v1.1/articles?externalId=&sku=12345&publishedOnly=true&locale=en_US&limit=10&offset=20&sort=textLength:desc
  • Parameters
  • externalId
    string (optional) Example: X12345

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

    sku
    string (optional) Example: 12345

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

    publishedOnly
    boolean (optional) Default: true 

    If true, only return published articles.

    Choices: true false

    locale
    string (optional) Example: en_US

    Only return articles for this locale.

    limit
    number (optional) Default: 50 Example: 10

    Maximum number of articles to show.

    offset
    number (optional) Default: 0 Example: 10

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

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

Article Detail 

Get article
/v1.1/articles/{id}

This endpoint will return a single article identified by it’s Id.

Resource URL

https://api.turnto.com/v1.1/articles/12345
  • Parameters
  • id
    number (required) Example: 12345

    The ID of the article.

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

Update Article 

Update an article
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/articles

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)

PropertyRequiredNote
idNo
externalIdNo
titleYes
textYes
localeNoIf omitted use site default.
publishedYesTrue or false
expirationDateNoExpiration date
catalogItems[].skuNoThe SKU of the catalog item(s) that this article is about.
brandsNo
categoriesNo
searchTermsNo
  • Request
  • 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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Location: https://api.turnto.com/v1.1/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
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Missing Required Fields (title)",
       "code": 108
    }]}
    
  • Response  404
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "No article was found for the specified id (398239892)",
       "code": 154
    }]}
    

Delete Article 

Delete an article
/v1.1/articles/{id}

An authorization token is required to delete an article. The article is identified by it’s unique Id.

Resource URL

https://api.turnto.com/v1.1/articles/1234
  • Parameters
  • id
    number (required) Example: 1234

    The ID of the article.

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

Delete Article By External Id 

Delete an article by External Id
/v1.1/articles {?externalId}

An authorization token is required to delete an article. The article is identified by it’s external Id.

Resource URL

https://api.turnto.com/v1.1/articles?externalId=X12345
  • Parameters
  • externalId
    string (required) Example: X12345

    The external ID of the article.

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

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

PropertyTypeDescription
firstNamestringFirst name
lastNamestringLast name
nickNamestringNick name
externalIdstringExternal ID
emailstringEmail address
citystringCity
statestringState
countrystringCountry
ageRangenumberAge range indicator
badge.textstringBadge text
badge.imageUrlstringURL of image to use for badge
shopperProfiles[].idnumberIdentifier for a shopper profile
shopperProfiles[].valuestringFree-form text value

User UGC 

Get user UGC
/v1.1/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.

Resource URL

https://api.turnto.com/v1.1/users?email=a@a.com&ugcType=question,question-answered,review
  • Parameters
  • 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 

    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 

    If true only return questions content.

    Choices: true false

    questionsAnsweredOnly
    boolean (optional) Default: false 

    If true only return questions answered content.

    Choices: true false

    answersOnly
    boolean (optional) Default: false 

    If true only return answers content.

    Choices: true false

    commentsOnly
    boolean (optional) Default: false 

    If true only return comments content.

    Choices: true false

    reviewsOnly
    boolean (optional) Default: false 

    If true only return reviews content.

    Choices: true false

    includeNested
    boolean (optional) Default: false 

    Option to include nested content.

    Choices: true false

    publishedOnly
    boolean (optional) Default: true 

    If true, only return published content.

    Choices: true false

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

Search for UGC content
/v1.1/search {?q, sku, ugcType, publishedOnly, minRating, maxRating, mostRecent, locale, tags, dateCreatedFrom, dateCreatedTo, limit, offset}

Perform a search for the specified search text across the content of one or more of the available UGC types. A list of SKUs can be supplied to restrict search to specific products. In the case of Articles, generic articles (that apply to all products) are always searched.

Search will return a JSON object with a nested “results” object that has a list of objects of the UGC types that were used in the “ugcType” parameter and whose content matches the search string "q". The fields returned in the results for each UGC type are those described in the “Resource properties” section of this doc. (For example, a search result containing a question will have most of the properties described in the Questions section.

Nested UGC types will not be returned for question or answer resources. For example, if your search returns a question, there will not be a collection of nested answers included. Review resources, however, will contain any published media content associated with the review.

There is one additional property added in search results to each object called “ugcType” that will identify it as either a question, answer, comment, review, or article.

A filter is available to constrain by published status.

Filtering by tag codes is supported. Tag codes should be specified as a comma separated list. If tag codes are specified then a UGC result must be associated with at least one of those tag codes.

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

Pagination of results are supported via the ‘limit’ and ‘offset’ parameters.

Resource URL

https://api.turnto.com/v1.1/search?q=stew&sku=311459%20SM&ugcType=question,answer&publishedOnly=true&limit=20&offset=0
  • Parameters
  • q
    string (optional) 

    UTF-8, URL-encoded search string of no more than 500 characters.

    sku
    string (optional) Example: 12345,22222,33333

    Comma separated list of SKUs to return results for. Maximum is 20.

    ugcType
    string (required) 

    Type of content to search for. Multiple types can be searched using comma-separated values.

    Choices: question answer review comment article all

    publishedOnly
    boolean (optional) Default: true 

    If true, only return published results.

    Choices: true false

    minRating
    number (optional) 

    Minimum rating of reviews to return.

    maxRating
    number (optional) 

    Maximum rating of reviews to return.

    mostRecent
    boolean (optional) Default: false 

    Order results by most recent.

    Choices: true false

    locale
    string (optional) Example: en_US

    Only return results for this locale.

    tags
    string (optional) Example: CSR,DAM

    Comma separated list of tag codes. Only return results associated with at least one tag code.

    dateCreatedFrom
    date (optional) Example: 2016-07-01T10:00:00-04:00

    Only include results that were created on or after this date (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ).

    dateCreatedTo
    date (optional) Example: 2016-07-02T10:00:00-04:00

    Only include results that were created on or before this date (ISO 8601 Format: yyyy-MM-ddTHH:mm:ssZZ).

    limit
    number (optional) Default: 20 

    Maximum number of results to return. Maximum value is 100.

    offset
    number (optional) Default: 0 

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

  • Request
  • Headers
    Content-Type: application/x-www-form-urlencoded
    Authorization: Bearer R85lEKIvpTrQaNNBJoUtHRQuuaTjALtXwya
  • Response  200
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {
       "limit": 10,
       "offset": 0,
       "total": 45,
       "results":    [
                {
             "id": 18,
             "dateCreated": "2015-07-20T15:06:46-04:00",
             "approvedDate": null,
             "text": "How many different attachments come with this food processor?",
             "textLength": 61,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "irrelevantFlag": false,
             "unansweredAlert": false,
             "reviewedFlag": false,
             "autoModerated": false,
             "flagForExpert": false,
             "upVotes": 0,
             "isStaff": false,
             "isCategoryQuestion": true,
             "answerCount": 1,
             "user":          {
                "nickName": "Andrew A.",
                "firstName": "Andrew",
                "lastName": "Adamson",
                "emailAddress": "andrew@sample.com",
                "externalId": null,
                "city": "Rye",
                "state": "NY",
                "country": "US",
                "ageRange": 2,
                "shopperProfiles":             [
                                  {
                      "id": 4,
                      "value": "toast"
                   },
                   {"id": 1}
                ]
             },
             "ugcType": "question",
             "catalogItems": [         {
                "sku": "11112222",
                "title": "MultiChef",
                "url": "www.topchef.com/food-processors/multichef"
             }],
             "tags":          [
                "PRI",
                "ALU",
                "NEW"
             ]
          },
                {
             "id": 12,
             "dateCreated": "2015-07-20T15:06:46-04:00",
             "reviewedDate": null,
             "text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
             "textLength": 65,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "inappropriateFlag": false,
             "reviewedFlag": false,
             "autoModerated": true,
             "upVotes": 0,
             "thanked": false,
             "isStaff": false,
             "purchaseDate": null,
             "itemQuestionId": 18,
             "catalogItems": [],
             "user":          {
                "nickName": "Bob B.",
                "firstName": "Bob",
                "lastName": "Brimmer",
                "emailAddress": null,
                "externalId": "12345",
                "city": "Dallas",
                "state": "TX",
                "country": "US",
                "ageRange": 0,
                "badge": null,
                "shopperProfiles":             [
                                  {
                      "id": 4,
                      "value": "waffles"
                   },
                   {"id": 1}
                ]
             },
             "ugcType": "answer",
             "tags": []
          },
                {
             "id": 11,
             "dateCreated": "2015-07-20T15:06:41-04:00",
             "reviewedDate": null,
             "text": "My D600 with 24-85 mm lens with cap (3 3/4\" long) fits in the case. If the 24-120 is @ same length, t should fit snugly.",
             "textLength": 120,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "inappropriateFlag": false,
             "reviewedFlag": false,
             "autoModerated": true,
             "upVotes": 1,
             "thanked": false,
             "isStaff": true,
             "purchaseDate": null,
             "itemQuestionId": 16,
             "catalogItems": [],
             "user":          {
                "nickName": "Andrew A.",
                "firstName": "Andrew",
                "lastName": "Adamson",
                "emailAddress": "spike@dog.org",
                "externalId": null,
                "city": "hell",
                "state": "NE",
                "country": "US",
                "ageRange": null,
                "badge":             {
                   "text": "Staff",
                   "imageUrl": ""
                }
             },
             "ugcType": "answer",
             "tags": [
                 "CSR",
                 "FLF"
             ]
          },
                {
             "id": 7,
             "dateCreated": "2015-07-20T15:06:39-04:00",
             "reviewedDate": null,
             "text": "My D600 with 24-85 mm lens with cap (3 3/4\" long) fits in the case. If the 24-120 is @ same length, t should fit snugly.",
             "textLength": 120,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "inappropriateFlag": false,
             "reviewedFlag": false,
             "autoModerated": true,
             "upVotes": 0,
             "thanked": false,
             "isStaff": false,
             "purchaseDate": null,
             "itemQuestionId": 16,
             "catalogItems":          [
                            {
                   "sku": "1",
                   "title": "Die Hard 2",
                   "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1"
                },
                            {
                   "sku": "3",
                   "title": "Purple Rain",
                   "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=3"
                },
                            {
                   "sku": "5",
                   "title": "Other6",
                   "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=5"
                },
                            {
                   "sku": "6",
                   "title": "Other7",
                   "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=6"
                }
             ],
             "user":          {
                "nickName": "Andrew A.",
                "firstName": "Andrew",
                "lastName": "Adamson",
                "emailAddress": "andrew@sample.com",
                "externalId": null,
                "city": "Rye",
                "state": "NY",
                "country": "US",
                "ageRange": 2,
                "badge": null,
                "shopperProfiles":             [
                                  {
                      "id": 4,
                      "value": "toast"
                   },
                   {"id": 1}
                ]
             },
             "ugcType": "answer",
             "tags": []
          },
                {
             "id": 6,
             "dateCreated": "2015-07-20T15:06:39-04:00",
             "reviewedDate": null,
             "text": "My D600 with 24-85 mm lens with cap (3 3/4\" long) fits in the case. If the 24-120 is @ same length, t should fit snugly.",
             "textLength": 120,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "inappropriateFlag": false,
             "reviewedFlag": false,
             "autoModerated": true,
             "upVotes": 0,
             "thanked": false,
             "isStaff": false,
             "purchaseDate": null,
             "itemQuestionId": 16,
             "catalogItems": [         {
                "sku": "1",
                "title": "Die Hard 2",
                "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=1"
             }],
             "user":          {
                "nickName": "Andrew A.",
                "firstName": "Andrew",
                "lastName": "Adamson",
                "emailAddress": "andrew@sample.com",
                "externalId": null,
                "city": "Rye",
                "state": "NY",
                "country": "US",
                "ageRange": 2,
                "badge": null,
                "shopperProfiles":             [
                                  {
                      "id": 4,
                      "value": "toast"
                   },
                   {"id": 1}
                ]
             },
             "ugcType": "answer",
             "tags": []
          },
                {
             "id": 5,
             "dateCreated": "2015-07-20T15:06:38-04:00",
             "reviewedDate": null,
             "text": "Too many to list but i'll try - chopper, mixer, beater, slicer...",
             "textLength": 65,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "inappropriateFlag": true,
             "reviewedFlag": false,
             "autoModerated": true,
             "upVotes": 1,
             "thanked": false,
             "isStaff": false,
             "purchaseDate": null,
             "itemQuestionId": 16,
             "catalogItems": [],
             "user":          {
                "nickName": "Bob B.",
                "firstName": "Bob",
                "lastName": "Brimmer",
                "emailAddress": null,
                "externalId": "12345",
                "city": "Dallas",
                "state": "TX",
                "country": "US",
                "ageRange": 0,
                "badge": null,
                "shopperProfiles":             [
                                  {
                      "id": 4,
                      "value": "waffles"
                   },
                   {"id": 1}
                ]
             },
             "ugcType": "answer",
             "tags": []
          },
                {
             "id": 16,
             "dateCreated": "2015-07-20T15:06:38-04:00",
             "approvedDate": null,
             "text": "How many different attachments come with this food processor?",
             "textLength": 61,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "irrelevantFlag": false,
             "unansweredAlert": false,
             "reviewedFlag": false,
             "autoModerated": false,
             "flagForExpert": false,
             "upVotes": 0,
             "isStaff": false,
             "isCategoryQuestion": true,
             "answerCount": 6,
             "user":          {
                "nickName": "Andrew A.",
                "firstName": "Andrew",
                "lastName": "Adamson",
                "emailAddress": "andrew@sample.com",
                "externalId": null,
                "city": "Rye",
                "state": "NY",
                "country": "US",
                "ageRange": 2,
                "shopperProfiles":             [
                                  {
                      "id": 4,
                      "value": "toast"
                   },
                   {"id": 1}
                ]
             },
             "ugcType": "question",
             "catalogItems": [         {
                "sku": "11112222",
                "title": "MultiChef",
                "url": "www.topchef.com/food-processors/multichef"
             }],
             "tags": []
          },
                {
             "id": 12,
             "dateCreated": "2015-07-20T15:06:21-04:00",
             "approvedDate": null,
             "text": "Can my D600+24-120mm F4 fit into this case? I read the official Nikon document which is saying 24-120mm F4 does not fit with D600, but I'm still thinking it might fit tightly. Anyone has, maybe, an experience?",
             "textLength": 209,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "irrelevantFlag": false,
             "unansweredAlert": false,
             "reviewedFlag": false,
             "autoModerated": false,
             "flagForExpert": false,
             "upVotes": 0,
             "isStaff": false,
             "isCategoryQuestion": false,
             "answerCount": 0,
             "user":          {
                "nickName": "Andrew A.",
                "firstName": "Andrew",
                "lastName": "Adamson",
                "emailAddress": "andrew@sample.com",
                "externalId": null,
                "city": "Rye",
                "state": "NY",
                "country": "US",
                "ageRange": 2,
                "shopperProfiles":             [
                                  {
                      "id": 4,
                      "value": "toast"
                   },
                   {"id": 1}
                ]
             },
             "ugcType": "question",
             "catalogItems": [         {
                "sku": "340824 REG",
                "title": "Greenies Smart Biscuit Fresh Chip 16 oz Regular",
                "url": "http://www.testtt.info/tt4_1/qaOverlay-reviewsEmbed.php?sku=340824 REG"
             }],
             "tags": []
          },
          {
             "id": 15,
             "dateCreated": "2015-07-20T15:06:22-04:00",
             "approvedDate": null,
             "text": "Can my D600+24-120mm F4 pics fit into this case? I read the official Nikon document which is saying 24-120mm F4 does not fit with D600, but I'm still thinking it might fit tightly. Anyone has, maybe, an experience?",
             "textLength": 214,
             "locale": "en_US",
             "published": false,
             "csFlag": false,
             "irrelevantFlag": false,
             "unansweredAlert": false,
             "reviewedFlag": false,
             "autoModerated": false,
             "flagForExpert": false,
             "upVotes": 0,
             "isStaff": true,
             "isCategoryQuestion": true,
             "answerCount": 0,
             "user":          {
                "nickName": "Andrew A.",
                "firstName": "Andrew",
                "lastName": "Adamson",
                "emailAddress": "spike@dog.org",
                "externalId": null,
                "city": "hell",
                "state": "NE",
                "country": "US",
                "ageRange": null
             },
             "ugcType": "question",
             "catalogItems": [         {
                "sku": "11112222",
                "title": "MultiChef",
                "url": "www.topchef.com/food-processors/multichef"
             }],
             "tags": []
          },
          {
           "ugcType": "review",
           "id": 3,
           "rating": 5,
           "title": "These are awesome!",
           "text": "These are really very good indeed. These are really very good indeed.",
           "textLength": 69,
           "locale": "en_US",
           "csFlag": false,
           "inappropriateFlag": false,
           "reviewedFlag": false,
           "autoModerated": false,
           "published": false,
           "incentivized": false,
           "upVotes": 0,
           "downVotes": 0,
           "orderId": null,
           "dimensions": [],
           "media":          {
              "photo": [],
              "video": [],
              "audio": []
           },
           "responses": [],
           "reviewedDate": null,
           "purchaseDate": null,
           "dateCreated": "2016-05-17T12:41:28-04:00",
           "user":          {
              "nickName": "Bart S.",
              "firstName": "Bart",
              "lastName": "Simpson",
              "emailAddress": "bart2@simpson.com",
              "externalId": null,
              "city": "Springfield",
              "state": "OH",
              "country": "US",
              "ageRange": 1
           },
           "catalogItems": [         {
              "sku": "REVIEWSKU555",
              "title": "Vacuum Cleaner",
              "url": "www.vacsrus.com/vac1",
              "category": null
           }],
           "tags": []
        }
       ]
    }
    
  • Response  400
  • Headers
    Content-Type: application/json;charset=UTF-8
    Body
    {"errors": [{
       "message": "Bad search filters",
       "code": 131
    }]}
    
Next  Previous

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.

09/27/17 - List direct and related reviews in single request

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

08/16/17 - UGC Summary by locale

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

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

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

Next  Previous

Previous Versions 

Previous

Generated by aglio on 12 Sep 2017