Ratings & Reviews (TurnTo) API Implementation
Emplifi Ratings & Reviews (TurnTo) REST API Overview
The REST API for Ratings & Reviews, also known as the TurnTo API, is designed for developers who want to programmatically submit and retrieve Emplifi Ratings & Reviews data.
It provides access to user-generated content as well as product catalog, shopper orders, and other statistical data stored in the Emplifi system from within your own applications.
Our highly flexible API enables our clients to create custom displays and interactions as well as custom experiences for Checkout Comments, Visual Content, Ratings & Reviews, and Q&A.
Why use the API?
Emplifi is constantly improving our JavaScript widgets to boost speed, expand functionality, enhance user experience, and increase flexibility. However, nothing provides you with more development flexibility than building your own user interactions. If you need this level of flexibility, Emplifi provides an API for building your own Checkout Comments, Visual Content, Ratings & Reviews, Q&A, and any other interaction you can dream up.
Using the API provides many opportunities to extend the power of the Emplifi Ratings & Reviews 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
Updating user and product data in the Emplifi Ratings & Reviews platform
Building a front-end entirely powered by the Emplifi API requires significant development time and resources. Please ensure that you have reviewed the TurnTo API for Emplifi Ratings & Reviews reference documentation and discussed using our API with Emplifi Support.
Another option is to deploy a hybrid (widget + API) approach, such as using the API to supplement widget functionality.
What data is available in the API?
Here are the types of data that can be retrieved and submitted via the API:
Data Type | Retrieve | Submit |
|---|---|---|
Questions | Yes | Yes |
Answers | Yes | Yes |
Replies | Yes | Yes |
Checkout Comments | Yes | Yes |
Product Ratings & Reviews | Yes | Yes |
Knowledgebase Articles | Yes | Yes |
Customer Orders | Yes | Yes |
Customer Profiles | Yes | Yes |
Content Statistics | Yes | N/A |
Widget vs. API: Functional Comparison
Although most functionality is available both in widgets and in the API, some functionality is only available in the API.
Functionality | Widget | API | API Documentation |
|---|---|---|---|
Ratings & Reviews | Yes | Yes | |
Q&A | Yes | Yes | |
Checkout Comments | Yes | Yes | |
Visual Content | Yes | Yes | |
Star-Only Reviews | No | Yes | |
Inline Media Collection | No | Yes | |
Multiple reviews per shopper per SKU | No | Yes | Not applicable |
Developers can use their custom API-based applications alongside the Emplifi Ratings & Reviews widgets for the same site ID. This is particularly important for sites that use Emplifi Ratings & Reviews widgets on their website and the API for their native mobile apps.
Getting Started with the API
To begin building your custom API-based displays and user interactions, you need access to the API and must provide your product catalog and create some orders.
Primary access token
Emplifi Ratings & Reviews uses OAuth 2.0 Bearer tokens to control API access. You submit your client_id (Site Key) and client_secret (Auth Key) to authenticate. The API returns a primary API access token when you are authenticated, which authorizes you to send and retrieve your information with the API.
Best practices
Your
client_secret(Auth Key) is equivalent to a password and must be protected, preferably by doing the authentication on the server side.To prevent the possibility of API requests being misused, external clients (such as Native Mobile applications) should take steps to protect and conceal the primary API access token. This could be through the use of a proxy server to make API requests or a trusted server to provide authorization to external clients after deployment.
Steps:
In Emplifi Ratings & Reviews, click Settings → Manage site.
Note your Site Key and Auth Key.
Send a POST request to the
/v1.3/oauth2/tokenAPI endpoint. For details, see Obtaining the primary access token in the API Quick Reference article.The response includes your access token.
Do not request a new primary access token each time you call the API. Emplifi Ratings & Reviews does not automatically invalidate the primary access token. Consider using a persistent cache to limit the number of calls for the token. If your security process requires the token be renewed periodically, you can invalidate the access token and request a new one.
Submitting your product catalog
We recommend using the Catalog Feed for all implementations. However, we also provide API access to your catalog details, as well as the ability to add to and update your catalog items. To submit an item into your product catalog using the API, send a POST request to the /v1.3/products endpoint. For details, see Update Product in the API documentation.
Capturing your orders
To enter your order into Emplifi Ratings & Reviews, send a POST request to the /v1.3/orders/create endpoint as each order occurs. For details, see Create Order in the API documentation.
Next Steps
Now that you have access to the API, have submitted your product catalog, and have set up order logging, you're ready to move on to using the API to build displays and user interactions.
To learn more about using the API in general and for a complete listing of all endpoints, see the Ratings & Reviews API reference documentation. For an explanation of frequently used endpoints, see the API Quick Reference. Or learn about Using the API to Build Emplifi Ratings & Reviews widgets.