Introduction to the REST API

This article is an introduction for developers who want to connect with the Easypromos API to export the user data from their promotions.


In this article, we will discover the different methods that Easypromos offers for exporting the participant data from the promotions through API. This API has been implemented following the REST method and the HTTP protocol.


Important points:

  • The REST API is only available for clients with a White Label or Corporate plan.
  • The REST API does not export data from Premium and Basic promotions.

The habitual uses of the REST API are:

  • Import the users from the promotions to the client’s database or user management system.
  • Use it to show the data of the promotion on an external site. It can, for example, be to show an image gallery with the user entries, or show the ranking of a game.

The way to work with the REST API is the following: a developer needs to program a code that sends requests to the API periodically to receive the data it needs.

Note: If your objective is to collect the user data in real-time, you should consider using the webhooks feature instead of the API.

In this article, we explain the methods that are included in the REST API and the access to the technical specifications.

Table of contents:



All calls to the API need to be authenticated. To do this, you need to use an access token that the administrator can get from their Easypromos account. Follow these instructions to get an access token.


API methods

Below we will list and describe the different REST API methods:


1. GET Api/Promotions/List: List of promotions

Allows to obtain a list of all the promotions created in an account. For each promotion, all the information is included.

Recommendation: Ideal for exporting and saving all the promotions created in Easypromos and that way have all previous promotions controlled.


2. GET Api/Promotions/Single: Information single promotion

Returns all information from a single White Label promotion. This call does not include the user data.

Recommendation: Ideal for extracting the organizing brand of a promotion.


3. GET Api/Promotions/Users/List: List of unique users from a promotion

This API method returns the list of all unique users registered in the promotion. In promotions with auto login and multi-participation activated, only the user's registration data will be returned.

Recommendation: Ideal for feeding the CRM system or email marketing tool with the leads captured in the promotions.


4. GET Api/Promotions/Users/Single: Information about a single user

This API method returns the information of a specific user of a promotion.


5. GET Api/Promotions/Participations/List: List of participations in a promotion

This API method can only be applied to promotions with the login system enabled. It returns the list of all the participations of all users. For example, in a puzzle-type promotion with multiple daily entries, the method will return a list with all participations arranged in chronological order.

Recommendation: Ideal for having all the participations of your users controlled and complement it with auto login campaigns.


6. GET Api/Promotions/Leaderboard: Ranking from a promotion

Returns the ranking of the first 100 users in a game-type promotion that has time and ranking. This call returns the list of unique users ordered by best score. Only one hundred users are returned. Basic information is included along with their score.

Recommendation: Ideal for showing the ranking/leaderboard of a promotion in an app or on a website, with your design.


7. GET Api/Accounts/Users: List of users from an account

Allows to export the list of all the unique users registered in any White Label promotion in one account from a specific date. For each user, the data includes their registration data, the information of the promotion they entered, and the organizing brand of the promotion. The list of users is returned in chronological order.

Recommendation: Ideal for Corporate accounts that manage different organizing brands where each one has its own promotions. With one call, you can import the users from different promotions into the same CRM system.


8. POST Api/Promotions/Autologin: Register a new user in the promotion

This call allows you to register a new participant in a promotion with the login system enabled. This is the API method that is used for promotions that are embedded in a mobile app or in a user space for users that are logged in. See how the auto login system works.

Have more questions? Submit a request


Please sign in to leave a comment.