Getting started with the EVO API

Definition

API stands for Application Programming Interface. In the context of APIs, the word Application refers to any software with a distinct function. The interface can be thought of as a service contract between two applications. This contract defines how the two communicate using requests and responses. The documentation of their respective APIs contains information on how developers should structure these requests and responses, like this API Reference.

The EVO API is a REST API. REST stands for Representational State Transfer. REST defines a set of functions such as GET, PUT, DELETE, and so on, that can be used to access server data. The requester and servers exchange data using HTTP.

The main characteristic of a REST API is its statelessness. Statelessness means that servers do not save client data between requests. Requests to the server are similar to the URLs you type in the browser to visit a website. The server's response corresponds to simple data, without the typical graphical rendering of a web page.

How to Use the EVO API

To start using the EVO API, you need to:

Obtain an API key to make requests.

Test the API using an HTTP API client, where you can easily structure API requests using the received API keys.

Let's detail each of these points below.

Obtaining EVO API Keys

To obtain the keys necessary to make API requests, you need to create them within EVO itself. It is important to understand that there are two types of API keys that can be created:

Single-branch key: a key created in a branch instance with permissions and access only to that branch's data;

Multi-branch key: a key created in a General Admin instance with access only to calls that have the idbranch parameter.

The path to create the keys in EVO is Settings - Integrations and access the EVO card in the API section:

Clicking on the EVO card presents the screen:

92e576e4fc02a2495bff23c9eacb8687ec2d47b430018d4ab29b9bb410f9ee62-image.png

1- Alphabetical list of all created integration Tokens.

2- Search field to look for the Token name.

3- NEW TOKEN: button to create new Tokens.

4- Actions: edit and delete created Tokens.

5- History of deleted Tokens.

Create a Token

Click on NEW TOKEN.

7cd71a776f3bc29226e1ded9db13e04fd513f16e4c43e8033b0aec0af8d2892e-image.png

A login and password request window for the EVO system appears.

9763b4018a6f60017c3dc737f16bccab9af7e4e46ad7462a3f597f70ca4cfe99-image.png

Click on CONFIRM.

Fill in the Token Name, Requester Name, and WhatsApp.

59bae093b67bf72c44f513954d177c53136f3663260b22c6d9a88c4203debf9f-image.png

Fill in the usage

Purpose of use: specify the purpose of the integration by selecting the existing options.

Internal/Partner Supplier: when selecting the Partner/Supplier option, provide the partner's name, supplier name, email, or phone.

🚧 If the supplier is not on the list, it is necessary to request registration in this form.

e872749cf3abca9f860e40895025e5fd31dba3a751c6e57874f9e8299400d312-image.png

Fill in the permissions

The selected permissions must relate to the data that the key will be able to access.

Each of these permissions is linked to the endpoints, and to check, click the arrow to expand.

3b4b17acffb047191c4ca8d071680c504406dec42288d239da0c28d7faa05e01-image.png

📘 Read this article to understand which endpoint each permission refers to.

After selecting all options, click on CREATE TOKEN.

After creating the token, the keys for authentication will be shown:

Your DNS, which will serve as the username;

And a token, which will serve as the password.

2eb66af3cf47c337a7e4c1f6b94eb26d25bcedf98dd26ca47a688c9a91ba481b-image.png

Edit and Delete Token

After creating the token, you can edit the permissions or delete existing tokens. Just click on the "edit" icon.

0eada00798d2b7a0d8c12f1f0fe3d13091e6860233b69df414f52ffb15cfdf8d-image.png

Testing the EVO API in an HTTP API Client

The authentication method of the EVO API is Basic Authentication, which means that to make API calls, a username and password are required: the DNS as the username, and the randomly generated key created in the last step as the password.

The HTTP API clients available for you to test API calls are this one, the Api Reference, where you can navigate through the different entities and their endpoints, being able to test them. There is also Swagger, where you can do the same in a more streamlined interface.

To perform the test calls, simply provide the username and password and fill in the parameters outlined in each endpoint. Both this channel and Swagger provide this sandbox environment where you will receive the returns of your test calls.

"Try it out"

What are the Entities of the EVO API?

API entities are the various areas of the product to which you can make an API call. Here is a summary of the main entities of the EVO API:

Activities: endpoints to obtain existing classes, enroll members in them, create test classes, view the list of classes;

Configuration: endpoints to obtain branch configurations, gateways, card brands, card translation, occupancy;

Employees: endpoints to obtain, add, update, and delete staff members;

Entries: endpoints to obtain entries;

Invoices: endpoints to obtain invoices by date;

MemberMembership: endpoints to obtain summaries of customer contracts;

Members: endpoints to obtain, update, authenticate customers;

Memberships: endpoints to obtain contracts and their categories;

Prospects: endpoints to obtain, add, and update prospects;

Receivables: endpoints to obtain and mark receivables, obtain cost center;

Sales: endpoints to obtain, create sales and return items by sale;

Service: endpoints to obtain services;

Voucher: endpoints to obtain vouchers;

Webhook: endpoints to create, list, and remove webhooks;

Workout: endpoints to obtain workout lists.

And many more!
Check the complete listing of entities in our API Reference.

Pagination of the EVO API

The pagination standard for the returns of EVO API calls is 50 records. There are some endpoints that exceptionally allow 100 records in the return.

To regulate the pagination of your call returns, use the take and skip parameters.

The total parameter in the header indicates the total number of items available for pagination in the API.

Request Limitations (Rate Limits)

To ensure system performance and stability, the EVO API implements request limits (rate limits). These limits control the number of calls that can be made within specific time intervals, based on the following criteria:

Per Minute (per IP): Limit of 40 requests per minute. Once reached, status 429 (Too Many Requests) will be returned, and you must wait 1 minute for new calls.

Per Hour (per API Key): Limit of 10,000 requests per hour. If exceeded, the key will be blocked for 1 hour.

Per Hour (per DNS): Limit of 20,000 requests per hour for all keys associated with the same DNS. If exceeded, all keys of the gym will be blocked for 1 hour.

Note: During the hours of 12 AM to 5 AM, the limits are not applied, allowing for high-volume executions, such as batch requests.

For more information and best practices on how to avoid blocks, consult the complete section on Request Limits

Best Practices for Using the EVO API

Finally, here are some best practices for the effective use of the EVO API.

First of all, it is important to clarify that the EVO API was designed to be used in the backend, as Basic Authentication requires API keys for requests.

🚧 This means that using it in the frontend can expose methods and data of your gym(s). Always implement it in the backend.

Additionally, it is essential to know that the EVO API consumes production data, which competes with the common processes of using EVO itself. Therefore, it is recommended to pull heavy API requests during the early morning from 1 AM to 6 AM, to avoid slowdowns in the use of EVO by the gym(s).

Getting started with the EVO API

Definition#

How to Use the EVO API#

Obtaining EVO API Keys#

Create a Token#

Edit and Delete Token#

Testing the EVO API in an HTTP API Client#

What are the Entities of the EVO API?#

Pagination of the EVO API#

Request Limitations (Rate Limits)#

Best Practices for Using the EVO API#