Welcome to the Easypromos REST API.
If you want to research REST API capabilities you don't need to write any code. Just get an
accessToken and test the API right on the reference page using the
Try It button.
Follow the steps in this guide to get an access token.
Who can use the REST API?:
- The REST API is only available for clients with a
- The REST API does not export data from Premium and Basic promotions.
The habitual uses of the REST API are integrations with external systems to create automatic processes. Examples:
- Import the users from the promotions to the client’s database or to a users' management system.
- Import the list of winners and their prizes to a prize fulfillment system.
- Let users of an external system (mobile app, membership site, loyalty program) participate in a promotion. Read more about the autologin system.
- Connect Messenger Bots (Whatsapp, Facebook Messenger) to a promotion. Example: validate promotional code from Whatsapp Bot to get instant prizes.
- Display data of the promotion on an external site. Example: the ranking of users in a game.
Note: If your objective is to collect the user data or receive the prizes in real-time, you should consider using the Webhooks.
Table of contents:
- Api base url and versions
- Models and items
- Collections and pagination
- Rate limit
- API reference
- Report an error
API base url and versions
The current version of Easypromos REST API is 2.0 (April 2022)
The api base url is always the same for all the endpoints:
The only thing to remember is that the last part of it (v2 in this case) is the version number of our API. If in the future we introduce some backward incompatible changes we will increment our API version to give you time to migrate from v2 to (let's say) v3. But don’t worry, the stable version will be kept for a long time and most future updates will be backward compatible.
We marked all endpoints with base url https://wl.easypromosapp.com/api/ as obsolete. This base url corresponds to the version 1.0 of the Easypromos REST API.
All version 1 API endpoints will come to their end-of-life by 1st April 2023 and will no longer be available.What do I need to do?
You must migrate all endpoints to the new version 2.0.
All the API requests need to be authenticated using an access token. You can obtain the token from your Easypromos account, in the Utilities menu of the account. How to obtain a token for the API.
To authenticate the API call, include the HTTP HEADER
Authorization: Bearer access_token
Example of the an API request with the Authorization HTTP HEADER using CURL:
curl -i -X GET \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
If you don't include a valid access token you will receive a
401 (Unauthorized) error.
This is REST API, all request follows REST rules in terms of resource naming convention, use of HTTP method as action description and use of custom headers to convey additional information.
We accept 2 methods:
GET is to obtain information. Only query string parameters are allowed. Any content included in the body of the request will be ignored. This request will never change anything.
POST is to add new or modify existing information. Every POST request MUST HAVE
Content-Type header. Currently we accept only
Models and items
We present data as JSON strings. That information is named "items" of a "model". Each url in our API represents a "model". Each item has its own unique Identifier (ID). Naming convention is very easy: ID of a promotion is called promotion_id. When you call GET /promotions/1234 we will return json data which it is an item of the model "promotion" where its ID is equal to '1234'.
The current models are:
Organizing Brand: represents an organizing brand of an Easypromos account.
Promotion: represents a promotion in an Easypromos account. A Promotion always belongs to an Organizing Brand
Stage: represents the definition of a participation stage in a promotion. A Participation Stage is a Quiz, a Game, a Wheel, etc... A participation stage always belongs to a Promotion.
User: represents a participant in a promotion. A User always belongs to a Promotion.
Participation: represents a participation of a User in a Participation Stage. Example: the information of a specific game of a participant including the user, points obtained, IP, time stamp, etc. A Participation always belongs to a User and a Stage.
Prize Type: represent a type of prize created in a promotion. It will include the information of the prize: name, description, image, instructions, type of assignation and the quantity of units that are available in the promotion. A Prize Type always belongs to a Promotion.
Prize: represents a specific unit of a prize won by a User in a Promotion. It include the Type of Prize, when the prize was won, and specific information of the prize like a unique code. A Prize always belongs to a User (who won it) and a Prize Type.
Ranking: represents a leaderboard of a Stage based on a game with scored. Includes a collection of Users with their scores in the game.
The representation and specification of the fields of each model is defined in the API reference.
Collections and pagination
When you call GET /promotions we will return a Collection of items. This is simply a list of items presented as a JSON array. In a collection we could commit some of the fields of the model. You should treat collection as a brief information of a model.
A Collection includes a maximum of 100 items per page.
A GET call which returns a Collection will always include the list of
items and the information of
paging to request the next page of items.
Example of getting the list of organizing brands for page 1, and page 2
GET /organizing_brands (page 1)
"name": "My organizing brand 1"
"name": "My organizing brand 100"
next_cursor of the
paging element exists and it is greater than 0, then you can request the next page of items of the Collection calling the GET endpoint passing the
next_cursor value in a parameter.
GET /organizing_brands?next_cursor=1234 (page 2)
"name": "My organizing brand 101"
"name": "My organizing brand 109"
When there is not
next_cursor then it is the final page.
Timezone for all timestamps is UTC
The Easypromos Rate API rate limit is 200 requests per minute per account.
If the rate limit is exceeded, subsequent requests will receive a response code of
429 (Too many requests) until 60 seconds has elapsed since the initial request.
If the Easypromos API responds with a resource (item or collection of items) correctly it will respond with the HTTP Status code
Otherwise it will respond with an HTTP Status Error Code:
|400||The operation could not be completed. See table of sub-errors below|
|401||Unauthorized – Access Token not valid|
|403||Forbidden – This user does not have access to this resource|
|404||Not Found – Could not find method requested or item doesn't exist|
|415||Unsupported content type. The request must include the HTTP Content-Type header and must be application/json.|
|429||Too Many Requests – You’re over the rate limit window. Try your request again later.|
|500||Internal Server Error – There was an issue processing your request. Get in contact with us at firstname.lastname@example.org|
|503||Service Unavailable – Our servers decided to take a rest. We’ll wake it up for you, try your requests later or contact us.|
When the API responds with an HTTP Status error 400, it will include the reason of the error in the body of the response in JSON format. Example:
"message": "Promotion is not open"
These are the codes of and a 400 HTTP Status error:
check error message
User has not more participations
User Login Token missing or not valid
Requirement is missing or not supported by the API
Requirement - The code is not valid
Requirement - The code was already used
External id missing or invalid
Promotion is not active
Promotion is not open
Autologin is not enabled
Promotion version is not White Label
Nickname already exists
Domain is not authorized for the JS Api call
Email is not valid
Promotion not valid
Promotion is expired
Content Type is not a valid JSON
Country code is not valid
No prizes available to spin the wheel.
Segment doesn't exist in the account or is not valid for this promotion
The definition of API follows the standard Openapi 3.1.0.
Go to the API reference docs.
Report API errors
You can report API errors sending an email to email@example.com.