TuriTop API

The purpose of this document is to provide technical details about the Turitop API that enables connectivity between Turitop and it's customers and partners. The document outlines the business processes supported by the API and details the specifications of security, communication, testing and implementation steps. To achieve a complete integration, development effort is required from clients, partners and third party actors who want to use Turitop API.

It is important to highlight this API is under continuous improvement. Therefore, both the API itself and this document might be subject to changes and revisions in the future.

You can download the full API specification (for using with Postman, Insomnia or any other similar software) from this link

This document assumes the reader has a computer technical background and is familiar with JSON, Webservices, API's and similar technologies.

These policies have been created to ensure our services integrity and make the development process easier to our customers and partners. Turitop reserves the right to modify the location and definition of the API at any time.

• Turitop does not guarantee the availability of any data, functionality or feature provided by or through the API.
• Turitop may partially revoke access to the API or completely disable the API access without notice or prior notification.
• API use are restricted by the conditions described in this document.
• Additional requests made by third-party services on customers/partners behalf are strictly prohibited.
• You are not allowed to sell, share, transfer or distribute access codes.
• Turitop reserves the right to revoke full access to the API without prior notification.
• Client applications must not affect the Turitop's services performance based on Turitop criteria.
• Turitop API use does not imply any kind of partnership with Turitop
• Client and third party applications may not use brand names, slogans, logotypes, images, based completely or in part from Turitop trademarks.
• To use the Turitop API have it is necessary the prior explicit authorization of Turitop, any attempt of using the API without authorization from Turitop is strictly prohibited.
• Any violation of the policies described above leads to API access revocation, Turitop could also take any legal actions if necessary.

• It is strictly forbidden use this API for bulk requests, any detected type of bulk use may leads to API access revocation.
• Both the number of simultaneous access to the API and the number of operations and errors generated are properly monitored and limited to avoid a missuse of our systems. Going beyond the established limits may result in a temporal blocking.
• In case of more daily requests are needed you should contact our support team, then we will evaluate the possibility of increasing the daily requests limits for your user account towards Turitop API.
• In order to use the Turitop API first you must request your access credentials to our support team at help@turitop.com

The Turitop API must be used via HTTPS, It is recommended to check the SSL certificate of the server to verify that the connection is being made toward the correct server.

Turitop API is a RESTful web API (also called a RESTful web service) which is a web APIimplemented using HTTPS and REST principles. Representational state transfer (REST) is a style of software architecture for distributed systems such as the World Wide Web. REST has emerged as a predominant web API design model. The REST architectural style was developed by W3C Technical Architecture Group (TAG) in parallel with HTTP/1.1, based on the existing design of HTTP/1.0.

Turitop API implements JSON data format for requests and responses. JSON (JavaScript Object Notation), is a text-based open standard designed for human-readable data interchange. It is derived from the JavaScript scripting language for representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, it is language-independent, with parsers available for many languages. All data in response is in Unicode, specifically, the Unicode (or UCS) Transformation Format, 8-bit encoding form (UTF-8)

Access to the API is done via HTTPS protocol. Parameters must be sent using POST (parameters sent using GET are ignored). It is recommended that you check the SSL certificate from the server to ensure that you are connecting to the correct server.

The Turitop API is always under continuous improvement. Therefore, many changes will be expected, we strongly recommend to keep updated with the online documentation. However, in case of major changes we will notify to all active API users via email.

Turitop API implements Hypertext Transfer Protocol (HTTP) response status codes, these status code is part of the HTTP/1.1 standard (RFC 7231).

The status-code element is a three-digit integer code giving the result of the attempt to understand and satisfy the request. The first digit of the status-code defines the class of response. The last two digits do not have any categorization role. There are five values for the first digit:

• 1xx (Informational): The request was received, continuing process.
• 2xx (Successful): The request was successfully received, understood, and accepted.
• 3xx (Redirection): Further action needs to be taken in order to complete the request.
• 4xx (Client Error): The request contains bad syntax or cannot be fulfilled.
• 5xx (Server Error): The server failed to fulfill an apparently valid request.

Turitop API uses Oauth2 authorization (RFC 6749). The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

Once the user is authorized in, each subsequent request must include the access token, allowing the user to access routes, services, and resources that are permitted with that token. The token expires after 1 hour, after this time you have to refresh the access_token with the refresh_token obtained in the authorization action.

Due to user inactivity it is posible that a request made towards the API will be rejected because the token has expired. For better usability reasons if you receive a 401 error in the response because the token has expired, you must make a refresh access token request to the API first, then repeat the original request once the new token has been refresh.