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 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 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.
• Update a user's virtual coin balance to synchronize it with an external loyalty system.
• Send virtual coin transactions to reward a user for actions taken in an external loyalty system.
• Send virtual coin transactions to provide additional entries in promotions for a user.

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

• Authorization

• Methods

• Models and items

• Collections and pagination

• Dates

• Rate limit

• Errors

• 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:

https://api.easypromosapp.com/v2

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.

Deprecation notice

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. 

Authorization

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 \
'https://api.easypromosapp.com/v2/promotions' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

If you don't include a valid access token you will receive a 401 (Unauthorized) error.

Methods

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 and POST.

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 application/json content-type.

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:

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)
{
  "items": [
     {
       "id": 1,
       "name": "My organizing brand 1"
     }
     ....
     {
       "id": 100,
       "name": "My organizing brand 100"
    }
  ],
  "paging": {
    "next_cursor": 1234,
    "items_page": 100
  }
}

If 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)
{
  "items": [
    {
      "id": 101,
      "name": "My organizing brand 101"
    }
    ....
    {
      "id": 109,
      "name": "My organizing brand 109"
    }
  ],
  "paging": {
    "items_page": 9
  }
}

When there is not next_cursor then it is the final page.

Dates

All timestamps are formatted as ISO-8601 in UTC time. For example, 2022-04-08T12:52:36+00:00. We support timestamps which start from 1970-01-01T00:00:00 (Unix epoch)

Timezone for all timestamps is UTC

Rate limit

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.

Errors

If the Easypromos API responds with a resource (item or collection of items) correctly it will respond with the HTTP Status code 200.

Otherwise it will respond with an HTTP Status Error Code:

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:

{
  "code": 42,
  "message": "Promotion is not open"
}

These are the codes of and a 400 HTTP Status error:

API reference

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 support@easypromosapp.com.