Easypromos
Powered by Redocly

Easypromos API Reference (2.0.1)

Download OpenAPI specification:Download

Easypromos Support: support@easypromosapp.com URL: https://soporte.easypromosapp.com/hc/en-us License: Easypromos White Label and Corporate Subscription Agreement.

Official API Reference for Easypromos REST API version 2.0. It follows standard openapi 3.1.0

The Easypromos API allows you to perform some of the operations that you do with our web client. The API is built using REST principles which ensures predictable URLs that make writing applications easy. The API follows HTTP rules, enable a wide range of HTTP clients can be used to interact with the API.

(*)API REST is only available with White Label and Corporate plans.

Promotions

Access to the list of the promotions of an Easypromos account.

Get the list of promotions of the account.

get/promotions
SecuritybearerAuth
Request
query Parameters
status
string
Default: "all"

Status of the promotion

Enum Value Description
all

get all promotions

draft

Get draft promotions

active

get active promotions

expired

get expired promotions

order
string
Default: "created_desc"

Order results based on the creation date

Enum Value Description
created_asc

Ascending, From oldest to newest

created_desc

Descending, From newest to oldest

next_cursor
integer or null <int32>
Default: null

Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.

Responses
200

A list of promotions

401

Unauthorized. Authentication token not valid.

403

Forbidden.

404

The specific resource was not found.

429

Rate limit. Too many requests.

default

Unexpected error

Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Get the basic information of a single promotion.
get/promotions/{promotion_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
Responses 
200
A single promotions


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "organizing_brand": {
    },
  • "promotion_type": 0,
  • "title": "string",
  • "internal_ref": "string",
  • "description": "string",
  • "status": "draft",
  • "timezone": "America/Chicago",
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z",
  • "default_language": "amh",
  • "created": "2019-08-24T14:15:22Z",
  • "url": "http://example.com"
}
Organizing Brands
Access to the list of the organizing brands of an Easypromos account. All promotions belong to an Organizing Brand.


Get the list of the organizing brands of the account.
get/organizing_brands
SecuritybearerAuth 
Request 
query Parameters
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
Responses 
200
A list of organizing brands


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Get the basic information of an organizing brand.
get/organizing_brands/{organizing_brand_id}
SecuritybearerAuth 
Request 
path Parameters
organizing_brand_id
required
integer <int32> 
ID of an organizing brand stage


 
Responses 
200
A single Organizing Brand


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "name": "My organizing brand"
}
Get the list of promotions of an organizing brand.
get/organizing_brands/{organizing_brand_id}/promotions
SecuritybearerAuth 
Request 
path Parameters
organizing_brand_id
required
integer <int32> 
ID of an organizing brand stage


 
query Parameters
status
string
 Default:  "all"
Status of the promotion


 Enum Value Description
all
get all promotions


draft
Get draft promotions


active
get active promotions


expired
get expired promotions


 
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
Responses 
200
A list of promotions


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Stages
Access to the list of the stages of participation in a promotion


Get the list of all participation stages in a promotion.
get/stages/{promotion_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
query Parameters
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
segments
string
Returns the stages that require the specified segment. Use the segment reference. You can filter by multiple segments by separating their references with a comma.


 
active
boolean
 Default:  false
Returns stages that are currently active based on their dates.


 
Responses 
200
A list of stages


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [],
  • "paging": {
    }
}
Get all data of a single participation stage in a promotion.
get/stages/{promotion_id}/{stage_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
stage_id
required
integer <int32> 
ID of the stage


 
Responses 
200
A single participation stage in a promotion


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{}
Users
Manage users who register for a promotion to participate.


Get the list of users registered in a promotion.
get/users/{promotion_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
query Parameters
status
string
 Default:  "all"
Filter results based on the status of the user


 Enum Value Description
all
get all users


pending
Get users with the email pending to validate


validated
Get users with the email validated


 
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
Responses 
200
A list of users


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Get all data of a single user registered in a promotion.
get/users/{promotion_id}/{user_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
user_id
required
integer <int32> 
ID of a user


 
Responses 
200
A single registered in a promotion


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "promotion_id": 1,
  • "first_name": "John",
  • "last_name": "Smith",
  • "nickname": "jsmith",
  • "login_type": "email",
  • "social_id": "string",
  • "external_id": "string",
  • "status": 0,
  • "email": "user@example.com",
  • "phone": "string",
  • "birthday": "2019-08-24",
  • "created": "2019-08-24T14:15:22Z",
  • "avatar_img": "http://example.com",
  • "language": "ara",
  • "country": "FR",
  • "custom_properties": [
    ],
  • "meta_data": {}
}
Get the login token of a user registered in a promotion.
get/users/logintoken/{promotion_id}/{user_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
user_id
required
integer <int32> 
ID of a user


 
Responses 
200
A login token of a user registered in a promotion


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB"
}
Assign one or multiple segments to a user.
post/users/segments/{promotion_id}
Use this API call to assign one or multiple segments to a user. 


User segments documentation.


SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
Request Body schema: application/json
required
lt
required
string  <= 255 characters 
The participant's User Login Token that identifies the participant's open session. You can open a participant session and get the User Login Token by sending a request to the /users/autologin endpoint


 
segments
required
Array of strings
List of segments to assign to the user. The segments must be already created in the promotion, organizing brand or the account. Insert the Reference field of the segment. Use them to create participation rules based on user segments. More information about segments.


 
Responses 
200
Valid assignation.


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


415
Unsupported Media Type. Content-type HTTP Header missing or is not application/json.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB",
  • "segments": [
    ]
}
Response samples 
application/json
{
  • "status": 1
}
Remove one or multiple segments to a user.
delete/users/segments/{promotion_id}
Use this API call to remove one or multiple segments from a user. 


User segments documentation.


SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
Request Body schema: application/json
required
lt
required
string  <= 255 characters 
The participant's User Login Token that identifies the participant's open session. You can open a participant session and get the User Login Token by sending a request to the /users/autologin endpoint


 
segments
required
Array of strings
List of segments to remove from the user. The segments must be already created in the promotion, organizing brand or the account. Insert the Reference field of the segment. More information about segments.


 
Responses 
200
Remove action successful.


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


415
Unsupported Media Type. Content-type HTTP Header missing or is not application/json.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB",
  • "segments": [
    ]
}
Response samples 
application/json
{
  • "status": 1
}
Autologin: login or register a user in a promotion.
post/users/autologin/{promotion_id}
The autologin path allows sending and registering users in a promotion directly from an external system like a mobile app or website.
This path describes the autologin api call from the server side. Autologin api calls from client side (browswer) are also supported from an alternative method; refer to to the documentation.
Autologin full documentation.


SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
Request Body schema: application/json
required
external_id
required
string  [ 1 .. 255 ] characters 
The External ID is the unique identifier of a user. The value can be a string or a number. Easypromos always treats it as a string and converts any numeric value into a string. An External ID should be static. If possible, this should be the same value you use to identify the user in your own system.


 
first_name
string  [ 2 .. 255 ] characters 
Optional. User's first name.


 
last_name
string  [ 2 .. 255 ] characters 
Optional. User's last name.


 
nickname
string  [ 2 .. 200 ] characters 
Optional. User's nickname. It is recommended if you don't want to pass the real first and last name. It must be unique among all participants.


 
email
string <email> 
Optional. User's email address. Add the user's email if you want to send automatic emails from the promotion (example - to say thank you, to send a coupon, etc).


 
phone
string  [ 2 .. 30 ] characters 
Optional. User's phone number.


 
country
string  = 2 characters ^[A-Z]{2}$
Optional. User's country code. Format ISO 3166 Alpha-2 (See list of country codes)


 
segments
Array of strings
Optional. List of segments that the user belongs to. It can belong to one or many (Do not send this field, if you don't use segments or the user belongs to none). The segments must be already created in the promotion, organizing brand or the account. Insert the Reference field of the segment. Use them to create participation rules based on user segments. More information about segments.


 
override_segments
boolean
 Default:  false
Optional. When set to true, each time a user is autologged, their existing account-level segments will be replaced with those specified in the segment parameter. Only account-level segments are affected; other segment types remain unchanged.  


 
language
string
Specifies the language of the user. This value must correspond to one of the languages defined in the promotion. If the provided language does not exist within the promotion, the system will automatically set the user's language to the default language of the promotion.


 Enum Value Description
amh
Amharic


ara
Arabic


aze
Azeri


baq
Euskera


bos
Bosnian


cat
Catalan


chi
Chinese (Simplified)


cze
Czech


dan
Danish


deu
Deutch


dut
Dutch


eng
English (generic)


en_gb
English (British)


en_us
English (US)


es_es
Spanish (Spain)


fin
Finnish


fre
French


glg
Galician


gre
Greek


heb
Hebreu


hrv
Croatian


hun
Hungarian


ind
Indonesian


ita
Italian


jpn
Japanese


kor
Korean


nor
Norwegian


pol
Polish


por
Portuguese


pt_br
Portuguese (Brazil)


rum
Romanian


rus
Russian


slo
Slovakian


slv
Slovenian


spa
Spanish (generic)


swe
Swedish


tha
Thai


tur
Turkish


vie
Vietnamese


zho
Chinese (Traditional)


 
Responses 
200
The user logged in to the promotion successfully. It returns a user Login Token


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


415
Unsupported Media Type. Content-type HTTP Header missing or is not application/json.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
application/json
{
  • "external_id": "4ed790c6-17eb-4ec3-a3b9-d8834bc74501",
  • "first_name": "John",
  • "last_name": "Smith",
  • "nickname": "jsmith79",
  • "email": "john.smith@example.com",
  • "phone": "1-345-897-345",
  • "country": "UK",
  • "segments": [
    ],
  • "override_segments": false,
  • "language": "amh"
}
Response samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB",
  • "registered": "true",
  • "user_id": 1
}
Send the user data when a new user registers in a promotion.Webhook 
Webhook triggered when registering a new user: the information of a new user who registers in the promotion will be sent in a HTTP POST Request to the URL of the webhook. In case the user has to confirm the email address to register, the webhook will be sent as soon as the users have validated their email. This webhook is ideal for receiving information from registered users in real time and inserting them into a CRM or user management system.
You can configure the URL of the webhook from the integrations menu of the promotions management page. Tutorial to enable a webhook in a promotion.


Request 
Request Body schema: application/json
required
required
object (UserFull) 
Full entity of the user. It includes all the registration data of the participant of a promotion, including the additional properties and metadata


 
id
required
integer <int32>   >= 1 
User unique identifier


 
promotion_id
required
integer <int32>   >= 1 
Promotion ID in which the user has registered


 
first_name
string  [ 2 .. 255 ] characters 
User first name


 
last_name
string  [ 2 .. 255 ] characters 
User last name


 
nickname
string or null  [ 2 .. 200 ] characters 
User nickname. If it is not requested during the registration process, First Name + Last Name are used by default


 
login_type
string
Method used by the user to log in


 Enum: "email" "facebook" "google" "twitch" "linkedin" "phone" "guest" "external"  
social_id
string or null  <= 30 characters  >= 1 
User identifier of the social network used by the user to log in


 
external_id
string or null  <= 255 characters 
User identifier of an external system. Example - the external_id sent via autologin


 
status
integer
Status of the user


 Enum Value Description
0
User with the email pending to validate


1
Valid user


 
email
string or null <email>   <= 120 characters 
User email


 
phone
string or null <phone>   <= 100 characters 
User phone


 
birthday
string or null <date> 
User birthday. Format: YYYY-MM-DD


 
created
string <date-time> 
User registration date and time. ISO-8601 format in UTC time.


 
avatar_img
string or null <uri> 
Url of the user's profile avatar image if available


 
language
string
Language used by the user when registering in the promotion.


 Enum Value Description
amh
Amharic


ara
Arabic


aze
Azeri


baq
Euskera


bos
Bosnian


cat
Catalan


chi
Chinese (Simplified)


cze
Czech


dan
Danish


deu
Deutch


dut
Dutch


eng
English (generic)


en_gb
English (British)


en_us
English (US)


es_es
Spanish (Spain)


fin
Finnish


fre
French


glg
Galician


gre
Greek


heb
Hebreu


hrv
Croatian


hun
Hungarian


ind
Indonesian


ita
Italian


jpn
Japanese


kor
Korean


nor
Norwegian


pol
Polish


por
Portuguese


pt_br
Portuguese (Brazil)


rum
Romanian


rus
Russian


slo
Slovakian


slv
Slovenian


spa
Spanish (generic)


swe
Swedish


tha
Thai


tur
Turkish


vie
Vietnamese


zho
Chinese (Traditional)


 
country
string  <= 2 characters 
Country from where the user registered (2 characters - ISO 3166 Alpha-2)


 
Array of objects (CustomUserProperty) 
 
 Array 
id
integer <int32>   >= 1 
Unique identifier of the custom field


 
title
string
Label of the field in the registration form


 
ref
string or null
Short reference of the field


 
value
string
Value selected or introduced by the user in the registration form


 
object
It includes the consent of the legal terms and other information of the user.


 
utm_source
string or null  <= 255 characters 
Source origin - Level 1 (utm_source)


 
utm_medium
string or null  <= 255 characters 
Source origin - Level 2 (utm_medium)


 
utm_campaign
string or null  <= 255 characters 
Source origin - Level 3 (utm_campaign)


 
referral_url
string or null <uri>   <= 255 characters 
Source origin - Referral Url


 
ip
string <ipv4> 
IP address from where the user registered


 
user_agent
string
User agent from where the user registered


 
object
List of consents of legal terms


 
webhook_key
string or null
Returns the webhook key that was inserted when creating the webhook. Use it for security to verify that the request comes from Easypromos.


 
Responses 
200
Your server returns this code if it accepts the callback


401
Unauthorized access


404
Resource not found


Request samples 
application/json
{
  • "user": {
    },
  • "webhook_key": "string"
}
Participations
Access to the list of participations in a promotion


Get the list of participations of a promotion.
get/participations/{promotion_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
query Parameters
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
format
string
 Default:  null
Format of the response.


 Value Description
full
Include the information of the User who participated and the Prize (if won)


 
Responses 
200
A list of participations


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Get the list of participations of a single user.
get/participations/{promotion_id}/users/{user_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
user_id
required
integer <int32> 
ID of a user


 
query Parameters
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
Responses 
200
A list of participations


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Get a single participation.
get/participations/{promotion_id}/{participation_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
participation_id
required
integer <int32> 
ID of a participation


 
Responses 
200
A single participation


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "promotion_id": 1,
  • "stage_id": 1,
  • "user_id": 1,
  • "created": "2019-08-24T14:15:22Z",
  • "ip": "192.168.0.1",
  • "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) GSA/201.0.429950705 Mobile/15E148 Safari/604.1",
  • "points": 786.43,
  • "data": [
    ],
  • "user": {
    },
  • "prize": {
    }
}
Check if a user is eligible to meet the stage requirement.
post/participations/{promotion_id}/check_requirement/{stage_id}
Use this API call to verify if a user is eligible to participate in a stage by meeting the stage's requirements. Currently, this call is only applicable to the Virtual Coin requirement: the system will compare the user's current balance with the stage's required balance. If the user has sufficient balance, the API will return a 200 HTTP response along with the URL to participate. If the user does not have enough balance, a 400 error will be returned.


SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
stage_id
required
integer <int32> 
ID of the stage


 
Request Body schema: application/json
required
lt
required
string  <= 255 characters 
The participant's User Login Token that identifies the participant's open session. You can open a participant session and get the User Login Token by sending a request to the /users/autologin endpoint


 
Responses 
200
User meets the stage requirement. The response includes the URL to participate.


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


415
Unsupported Media Type. Content-type HTTP Header missing or is not application/json.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB"
}
Response samples 
Submit a code as a requirement to participate.
post/participations/{promotion_id}/validate_code/{stage_id}
Use this API call to send a code to validate for a chance to enter a participation stage. The participation stage must have the code validation requirement enabled. If the code is valid, you will get a URL to participate. 


SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
stage_id
required
integer <int32> 
ID of the stage


 
Request Body schema: application/json
required
lt
required
string  <= 255 characters 
The participant's User Login Token that identifies the participant's open session. You can open a participant session and get the User Login Token by sending a request to the /users/autologin endpoint


 
code
required
string  [ 1 .. 255 ] 
The code that the participant is submitting to participate


 
Responses 
200
Valid code. The response includes the URL to participate.


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


415
Unsupported Media Type. Content-type HTTP Header missing or is not application/json.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB",
  • "code": "string"
}
Response samples 
Submit a new participation to participate in a stage.
post/participations/{promotion_id}/participate/{stage_id}
Use this API call to create a participation for a registered user in a participation stage. One user's available participation will be used, and the response may include a prize. This call is recommended to participate in promotions based on Instant Win via API. This call is available for the following types of participation stages:


    

  • 1: direct participation
    • 

  • 4: spin the wheel 
    • 

  • 11: scratch & win
    • 

  • 12: reveal & win
    • 



SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
stage_id
required
integer <int32> 
ID of the stage


 
Request Body schema: application/json
required
lt
required
string  <= 255 characters 
The participant's User Login Token that identifies the participant's open session. You can open a participant session and get the User Login Token by sending a request to the /users/autologin endpoint


 
object or null
If the participation stage has a requirement, you must post a requirement object. Currently, only the "validate a code" requirement is supported. Do not include this field if the stage does not have a requirement. 


 
type
required
string
Type of requirement. Must be the same type of the requeriment of the participation stage. Currently, we only support the "validate a code" requeriment.


 Value Description
code
Validate a code


 
data
required
string
Value of the requirement.  Must be valid for the type of requeriment. If the type of requirement is a code, insert the value of the code in this field.


 
Responses 
200
Participation created successfully. The response can include a prize.


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


415
Unsupported Media Type. Content-type HTTP Header missing or is not application/json.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB",
  • "requirement": {
    }
}
Response samples 
application/json
{
  • "participation_id": 0,
  • "available_participations": 0,
  • "prize": {
    }
}
Send the participation data when a new participation is created.Webhook 
Webhook triggered when registering a new participation from a user: the specific information of a user 's participation will be sent in a HTTP POST Request to the URL of the webhook. For example, the information of the prize won by a user when spinning a prize wheel, or discovering a prize in the Reveal and Win, or the points obtained by a user in a game will be sent. 
You can configure the URL of the webhook from the integrations menu of the promotions management page. Tutorial to enable a webhook in a promotion.


Request 
Request Body schema: application/json
required
required
object (Participation) 
 
id
required
integer <int32>   >= 1 
ID of the participation


 
promotion_id
required
integer <int32>   >= 1 
ID of the promotion to which the participation belongs


 
stage_id
required
integer <int32>   >= 1 
ID of the stage to which the participation belongs


 
user_id
required
integer <int32>   >= 1 
Participating User ID


 
created
required
string <date-time> 
Date and time of the participation. ISO-8601 format in UTC time.


 
ip
string <ipv4> 
IP address from where the user participated.


 
user_agent
string
User agent from where the user participated.


 
points
number <float>   >= 0 
 Default:  0
Points obtained in this participation. If the participation stage has no points, it will show 0


 
Array of objects
Includes additional information about the user's participation. This field contains specific details regarding the type of participation. We currently support the following types:


    

  • Type 2: Answers to a questionnaire
    • 

  • Type 18: Form submission
    • 

  • Type 7: Submission of content such as a photo, video, or text in a contest
    • 

  • Type 21: Photofun or scenes submission
    • 



For other stage types, this field will return an empty array. You can find the exact specification and examples for each type of participation at this link: Data Field Specification of the Participations Model.


 
 Array 
ref
string
Internal reference of the key field. In a questionnaire it is the internal reference of the question.


 
title
string
Public label of the key field. In a questionnaire it is the title of the question.


 
values
Array of strings
Values selected or answered by the user for this key field.  In a questionnaire is the answer (or answers) of a question submitted by the user.


 
required
object (UserFull) 
Full entity of the user. It includes all the registration data of the participant of a promotion, including the additional properties and metadata


 
id
required
integer <int32>   >= 1 
User unique identifier


 
promotion_id
required
integer <int32>   >= 1 
Promotion ID in which the user has registered


 
first_name
string  [ 2 .. 255 ] characters 
User first name


 
last_name
string  [ 2 .. 255 ] characters 
User last name


 
nickname
string or null  [ 2 .. 200 ] characters 
User nickname. If it is not requested during the registration process, First Name + Last Name are used by default


 
login_type
string
Method used by the user to log in


 Enum: "email" "facebook" "google" "twitch" "linkedin" "phone" "guest" "external"  
social_id
string or null  <= 30 characters  >= 1 
User identifier of the social network used by the user to log in


 
external_id
string or null  <= 255 characters 
User identifier of an external system. Example - the external_id sent via autologin


 
status
integer
Status of the user


 Enum Value Description
0
User with the email pending to validate


1
Valid user


 
email
string or null <email>   <= 120 characters 
User email


 
phone
string or null <phone>   <= 100 characters 
User phone


 
birthday
string or null <date> 
User birthday. Format: YYYY-MM-DD


 
created
string <date-time> 
User registration date and time. ISO-8601 format in UTC time.


 
avatar_img
string or null <uri> 
Url of the user's profile avatar image if available


 
language
string
Language used by the user when registering in the promotion.


 Enum Value Description
amh
Amharic


ara
Arabic


aze
Azeri


baq
Euskera


bos
Bosnian


cat
Catalan


chi
Chinese (Simplified)


cze
Czech


dan
Danish


deu
Deutch


dut
Dutch


eng
English (generic)


en_gb
English (British)


en_us
English (US)


es_es
Spanish (Spain)


fin
Finnish


fre
French


glg
Galician


gre
Greek


heb
Hebreu


hrv
Croatian


hun
Hungarian


ind
Indonesian


ita
Italian


jpn
Japanese


kor
Korean


nor
Norwegian


pol
Polish


por
Portuguese


pt_br
Portuguese (Brazil)


rum
Romanian


rus
Russian


slo
Slovakian


slv
Slovenian


spa
Spanish (generic)


swe
Swedish


tha
Thai


tur
Turkish


vie
Vietnamese


zho
Chinese (Traditional)


 
country
string  <= 2 characters 
Country from where the user registered (2 characters - ISO 3166 Alpha-2)


 
Array of objects (CustomUserProperty) 
 
 Array 
id
integer <int32>   >= 1 
Unique identifier of the custom field


 
title
string
Label of the field in the registration form


 
ref
string or null
Short reference of the field


 
value
string
Value selected or introduced by the user in the registration form


 
object
It includes the consent of the legal terms and other information of the user.


 
utm_source
string or null  <= 255 characters 
Source origin - Level 1 (utm_source)


 
utm_medium
string or null  <= 255 characters 
Source origin - Level 2 (utm_medium)


 
utm_campaign
string or null  <= 255 characters 
Source origin - Level 3 (utm_campaign)


 
referral_url
string or null <uri>   <= 255 characters 
Source origin - Referral Url


 
ip
string <ipv4> 
IP address from where the user registered


 
user_agent
string
User agent from where the user registered


 
object
List of consents of legal terms


 
object (Prize) 
Prize entity. It represents a unit of a prize assigned to a user.


 
id
required
integer <int32>   >= 1 
Unique identifier for this unit of prize


 
required
object (PrizeType) 
Prize Type entity. It represents a type of a prize created in the promotion.


 
id
required
integer <int32>   >= 1 
Prize type unique identifier


 
name
required
string  [ 2 .. 255 ] characters 
Prize type name


 
ref
string or null  <= 30 characters 
Short internal reference of the prize type


 
description
string or null
Prize type description


 
assignation_type
required
integer
It defines how this type of prize is assigned to users.


 Enum Value Description
1
Manual


2
Random draw


3
On participate


4
By instant win


5
By probability


 
qty
required
integer <int32>   [ 1 .. 5000010 ] 
Total number of units to reward. This is not the remaining units. They are the total that the administrator set when creating the promotion. If the administrators selected unlimited as the number of units, the value will be 5000010.


 
image
string or null <uri> 
Image URL of the prize type


 
instructions
string or null
Prize type instructions to claim or use


 
user_id
required
integer <int32>   >= 1 
User ID who won the prize


 
stage_id
integer or null <int32>   >= 1 
Stage ID that was assigned the prize. Only applies to prizes assigned directly on participating, instant win or by probability


 
participation_id
integer or null <int32>   >= 1 
Participation ID that was assigned the prize. Only applies to prizes assigned directly on participating, instant win or by probability


 
created
required
string <date-time> 
Date and time when the prize was assigned to the user. ISO-8601 format in UTC time.


 
code
string or null
If the prize has a promotional code, it will include the value of the code


 
download_url
string or null <uri> 
If the prize has a downloadable content like a coupon, it will include the absolute url


 
webhook_key
string or null
It returns the webhook key that was inserted when creating the webhook subscription. Use it as a security measure to verify that the request comes from Easypromos. If the user has won a prize in this participation, a Prize object will be included.


 
Responses 
200
Your server returns this code if it accepts the callback


401
Unauthorized access


404
Resource not found


Request samples 
application/json
{
  • "participation": {
    },
  • "user": {
    },
  • "prize": {
    },
  • "webhook_key": "string"
}
Prizes
Access to the list of prizes and their corresponding winners in a promotion


Get the list of all assigned prizes and their winners.
get/prizes/{promotion_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
query Parameters
prize_type_id
integer <int32> 
List of promotion prizes filtered by prize type ID


 
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
Responses 
200
A list of prizes with the information of the user who won


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Get the list of all prizes of a single user.
get/prizes/{promotion_id}/users/{user_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
user_id
required
integer <int32> 
ID of a user


 
query Parameters
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
Responses 
200
A list of prizes


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Send the prize and winner data when a new prize is assigned to a user.Webhook 
Webhook triggered when a user wins a prize: When a user wins a prize, a webhook will be triggered. The prize details and specific winner information will be sent via an HTTP POST request to the webhook URL. This occurs in various scenarios, such as spinning a prize wheel, discovering a prize in Reveal and Win, or redeeming virtual coins for prizes.
You can configure the URL of the webhook from the integrations menu of the promotions management page. Tutorial to enable a webhook in a promotion.


Request 
Request Body schema: application/json
required
required
object (Prize) 
Prize entity. It represents a unit of a prize assigned to a user.


 
id
required
integer <int32>   >= 1 
Unique identifier for this unit of prize


 
required
object (PrizeType) 
Prize Type entity. It represents a type of a prize created in the promotion.


 
id
required
integer <int32>   >= 1 
Prize type unique identifier


 
name
required
string  [ 2 .. 255 ] characters 
Prize type name


 
ref
string or null  <= 30 characters 
Short internal reference of the prize type


 
description
string or null
Prize type description


 
assignation_type
required
integer
It defines how this type of prize is assigned to users.


 Enum Value Description
1
Manual


2
Random draw


3
On participate


4
By instant win


5
By probability


 
qty
required
integer <int32>   [ 1 .. 5000010 ] 
Total number of units to reward. This is not the remaining units. They are the total that the administrator set when creating the promotion. If the administrators selected unlimited as the number of units, the value will be 5000010.


 
image
string or null <uri> 
Image URL of the prize type


 
instructions
string or null
Prize type instructions to claim or use


 
user_id
required
integer <int32>   >= 1 
User ID who won the prize


 
stage_id
integer or null <int32>   >= 1 
Stage ID that was assigned the prize. Only applies to prizes assigned directly on participating, instant win or by probability


 
participation_id
integer or null <int32>   >= 1 
Participation ID that was assigned the prize. Only applies to prizes assigned directly on participating, instant win or by probability


 
created
required
string <date-time> 
Date and time when the prize was assigned to the user. ISO-8601 format in UTC time.


 
code
string or null
If the prize has a promotional code, it will include the value of the code


 
download_url
string or null <uri> 
If the prize has a downloadable content like a coupon, it will include the absolute url


 
required
object (UserFull) 
Full entity of the user. It includes all the registration data of the participant of a promotion, including the additional properties and metadata


 
id
required
integer <int32>   >= 1 
User unique identifier


 
promotion_id
required
integer <int32>   >= 1 
Promotion ID in which the user has registered


 
first_name
string  [ 2 .. 255 ] characters 
User first name


 
last_name
string  [ 2 .. 255 ] characters 
User last name


 
nickname
string or null  [ 2 .. 200 ] characters 
User nickname. If it is not requested during the registration process, First Name + Last Name are used by default


 
login_type
string
Method used by the user to log in


 Enum: "email" "facebook" "google" "twitch" "linkedin" "phone" "guest" "external"  
social_id
string or null  <= 30 characters  >= 1 
User identifier of the social network used by the user to log in


 
external_id
string or null  <= 255 characters 
User identifier of an external system. Example - the external_id sent via autologin


 
status
integer
Status of the user


 Enum Value Description
0
User with the email pending to validate


1
Valid user


 
email
string or null <email>   <= 120 characters 
User email


 
phone
string or null <phone>   <= 100 characters 
User phone


 
birthday
string or null <date> 
User birthday. Format: YYYY-MM-DD


 
created
string <date-time> 
User registration date and time. ISO-8601 format in UTC time.


 
avatar_img
string or null <uri> 
Url of the user's profile avatar image if available


 
language
string
Language used by the user when registering in the promotion.


 Enum Value Description
amh
Amharic


ara
Arabic


aze
Azeri


baq
Euskera


bos
Bosnian


cat
Catalan


chi
Chinese (Simplified)


cze
Czech


dan
Danish


deu
Deutch


dut
Dutch


eng
English (generic)


en_gb
English (British)


en_us
English (US)


es_es
Spanish (Spain)


fin
Finnish


fre
French


glg
Galician


gre
Greek


heb
Hebreu


hrv
Croatian


hun
Hungarian


ind
Indonesian


ita
Italian


jpn
Japanese


kor
Korean


nor
Norwegian


pol
Polish


por
Portuguese


pt_br
Portuguese (Brazil)


rum
Romanian


rus
Russian


slo
Slovakian


slv
Slovenian


spa
Spanish (generic)


swe
Swedish


tha
Thai


tur
Turkish


vie
Vietnamese


zho
Chinese (Traditional)


 
country
string  <= 2 characters 
Country from where the user registered (2 characters - ISO 3166 Alpha-2)


 
Array of objects (CustomUserProperty) 
 
 Array 
id
integer <int32>   >= 1 
Unique identifier of the custom field


 
title
string
Label of the field in the registration form


 
ref
string or null
Short reference of the field


 
value
string
Value selected or introduced by the user in the registration form


 
object
It includes the consent of the legal terms and other information of the user.


 
utm_source
string or null  <= 255 characters 
Source origin - Level 1 (utm_source)


 
utm_medium
string or null  <= 255 characters 
Source origin - Level 2 (utm_medium)


 
utm_campaign
string or null  <= 255 characters 
Source origin - Level 3 (utm_campaign)


 
referral_url
string or null <uri>   <= 255 characters 
Source origin - Referral Url


 
ip
string <ipv4> 
IP address from where the user registered


 
user_agent
string
User agent from where the user registered


 
object
List of consents of legal terms


 
webhook_key
string or null
It returns the webhook key that was inserted when creating the webhook subscription. Use it as a security measure to verify that the request comes from Easypromos. 


 
Responses 
200
Your server returns this code if it accepts the callback


401
Unauthorized access


404
Resource not found


Request samples 
application/json
{
  • "prize": {
    },
  • "user": {
    },
  • "webhook_key": "string"
}
Coins
Access to the transactions and balance of virtual coins in a promotion


Get the balance of virtual coins of a single user.
get/coins/{promotion_id}/users/{user_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
user_id
required
integer <int32> 
ID of a user


 
Responses 
200
It returns the current balances of the user for each coin. It returns an array because promotions can be multicurrency.


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "coins": [
    ]
}
Update the balance of virtual coins of a single user.
put/coins/{promotion_id}
Use this API call to update the virtual coin balance of a user in a promotion. 


SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
Request Body schema: application/json
required
lt
required
string  <= 255 characters 
The participant's User Login Token that identifies the participant's open session. You can open a participant session and get the User Login Token by sending a request to the /users/autologin endpoint


 
balance
required
integer <int32>   [ -99999 .. 99999 ] 
Balance of the virtual coin to be set for the user.


 
reason
required
string or null
The reason or purpose for the coin balance update.


 
Responses 
200
If the transaction is successful, it returns the current balances of the user for each coin. It returns an array because promotions can be multicurrency.


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


415
Unsupported Media Type. Content-type HTTP Header missing or is not application/json.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB",
  • "balance": 5,
  • "reason": "Update balance to sync with loyalty program"
}
Response samples 
application/json
{
  • "coins": [
    ]
}
Get the list of all virtual coin transactions of a single user.
get/coin_transactions/{promotion_id}/users/{user_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
user_id
required
integer <int32> 
ID of a user


 
query Parameters
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
Responses 
200
A list of virtual coin transactions


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Get the list of all virtual coin transactions in a promotion.
get/coin_transactions/{promotion_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
query Parameters
order
string
 Default:  "created_desc"
Order results based on the creation date


 Enum Value Description
created_asc
Ascending, From oldest to newest


created_desc
Descending, From newest to oldest


 
next_cursor
integer or null <int32> 
 Default:  null
Pagination cursor to go to the next page. The Paging object of the response includes the total number of items in the current page, and the next cursor if available.


 
Responses 
200
A list of virtual coin transactions


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}
Post a new coin transaction to add or remove virtual coins to a user.
post/coin_transactions/{promotion_id}
Use this API call to add or remove virtual coins to a user in a promotion. 


SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
Request Body schema: application/json
required
lt
required
string  <= 255 characters 
The participant's User Login Token that identifies the participant's open session. You can open a participant session and get the User Login Token by sending a request to the /users/autologin endpoint


 
amount
required
integer <int32>   [ -99999 .. 99999 ] 
Amount of the transaction: an integer. Positive if the user earns virtual coins, negative if the user spends or uses them.


 
reason
required
string or null
The reason or purpose for the coin transaction.


 
Responses 
200
If transaction is successful, it returns the registered transaction.


400
The operation could not be completed


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


415
Unsupported Media Type. Content-type HTTP Header missing or is not application/json.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB",
  • "amount": 5,
  • "reason": "External event - Purchase"
}
Response samples 
application/json
{
  • "transaction": {
    }
}
Send the transaction data when a user earns or spends virtual coins.Webhook 
Webhook for virtual coin transactions: This webhook triggers whenever a user earns or spends virtual coins. The transaction data, including details of the amount earned or spent and the user's information, will be sent via an HTTP POST request to the specified webhook URL.
You can configure the URL of the webhook from the integrations menu of the promotions management page. Tutorial to enable a webhook in a promotion.


Request 
Request Body schema: application/json
required
required
object (VirtualCoinTransaction) 
Virtual Coin Transaction entity. It represents a transaction with virtual coins in a promotion related to a user


 
id
required
integer <int32>   >= 1 
Unique identifier for this virtual coin transaction


 
user_id
required
integer <int32>   >= 1 
User ID related to this transaction


 
promotion_id
required
integer <int32>   >= 1 
Promotion ID related to this transaction


 
coin_id
required
integer <int32>   >= 1 
Unique identifier of the coin


 
coin_name
required
string
Name of the virtual coin defined by the administrator of the promotion.


 
amount
required
integer <int32>   [ -99999 .. 99999 ] 
Amount of the transaction: an integer. Positive if the user earns virtual coins, negative if the user spends or uses them.


 
balance
required
integer <int32>   [ -99999 .. 99999 ] 
The resultant balance of the user after the coin transaction is completed.


 
created
required
string <date-time> 
Date and time of the transaction. ISO-8601 format in UTC time.


 
transaction_type
required
integer
It defines the type of transaction. Extra information is available in the extra field.


 Enum Value Description
1
STAGE PARTICIPATION - Coins are directly earned by participating in a stage. For instance, coins can be earned by passing a level in a game or by validating a code or ticket receipt.


2
REDEEM PRIZE - Coins spent by the user to redeem a prize.


3
BY ADMIN - Virtual coin transaction manually completed by the administrator from the control panel.


4
PRIZE TYPE COIN - User won a prize that represents virtual coins. For instance, the user spun the wheel and won coins.


5
STAGE REQUIREMENT - User spent coins to enter a participation stage. For instance, the user had to spend coins to scratch a card for a chance to win a prize.


6
VIA API - Virtual coin transaction completed via API.


 
reason
string or null
The reason or purpose for the coin transaction.


 
extra
string or null
It can include extra information of the transaction such as the redeemed prize_id or the participation stage_id.


 
required
object (UserFull) 
Full entity of the user. It includes all the registration data of the participant of a promotion, including the additional properties and metadata


 
id
required
integer <int32>   >= 1 
User unique identifier


 
promotion_id
required
integer <int32>   >= 1 
Promotion ID in which the user has registered


 
first_name
string  [ 2 .. 255 ] characters 
User first name


 
last_name
string  [ 2 .. 255 ] characters 
User last name


 
nickname
string or null  [ 2 .. 200 ] characters 
User nickname. If it is not requested during the registration process, First Name + Last Name are used by default


 
login_type
string
Method used by the user to log in


 Enum: "email" "facebook" "google" "twitch" "linkedin" "phone" "guest" "external"  
social_id
string or null  <= 30 characters  >= 1 
User identifier of the social network used by the user to log in


 
external_id
string or null  <= 255 characters 
User identifier of an external system. Example - the external_id sent via autologin


 
status
integer
Status of the user


 Enum Value Description
0
User with the email pending to validate


1
Valid user


 
email
string or null <email>   <= 120 characters 
User email


 
phone
string or null <phone>   <= 100 characters 
User phone


 
birthday
string or null <date> 
User birthday. Format: YYYY-MM-DD


 
created
string <date-time> 
User registration date and time. ISO-8601 format in UTC time.


 
avatar_img
string or null <uri> 
Url of the user's profile avatar image if available


 
language
string
Language used by the user when registering in the promotion.


 Enum Value Description
amh
Amharic


ara
Arabic


aze
Azeri


baq
Euskera


bos
Bosnian


cat
Catalan


chi
Chinese (Simplified)


cze
Czech


dan
Danish


deu
Deutch


dut
Dutch


eng
English (generic)


en_gb
English (British)


en_us
English (US)


es_es
Spanish (Spain)


fin
Finnish


fre
French


glg
Galician


gre
Greek


heb
Hebreu


hrv
Croatian


hun
Hungarian


ind
Indonesian


ita
Italian


jpn
Japanese


kor
Korean


nor
Norwegian


pol
Polish


por
Portuguese


pt_br
Portuguese (Brazil)


rum
Romanian


rus
Russian


slo
Slovakian


slv
Slovenian


spa
Spanish (generic)


swe
Swedish


tha
Thai


tur
Turkish


vie
Vietnamese


zho
Chinese (Traditional)


 
country
string  <= 2 characters 
Country from where the user registered (2 characters - ISO 3166 Alpha-2)


 
Array of objects (CustomUserProperty) 
 
 Array 
id
integer <int32>   >= 1 
Unique identifier of the custom field


 
title
string
Label of the field in the registration form


 
ref
string or null
Short reference of the field


 
value
string
Value selected or introduced by the user in the registration form


 
object
It includes the consent of the legal terms and other information of the user.


 
utm_source
string or null  <= 255 characters 
Source origin - Level 1 (utm_source)


 
utm_medium
string or null  <= 255 characters 
Source origin - Level 2 (utm_medium)


 
utm_campaign
string or null  <= 255 characters 
Source origin - Level 3 (utm_campaign)


 
referral_url
string or null <uri>   <= 255 characters 
Source origin - Referral Url


 
ip
string <ipv4> 
IP address from where the user registered


 
user_agent
string
User agent from where the user registered


 
object
List of consents of legal terms


 
webhook_key
string or null
It returns the webhook key that was inserted when creating the webhook subscription. Use it as a security measure to verify that the request comes from Easypromos. 


 
Responses 
200
Your server returns this code if it accepts the callback


401
Unauthorized access


404
Resource not found


Request samples 
application/json
{
  • "transaction": {
    },
  • "user": {
    },
  • "webhook_key": "string"
}
Rankings
Get the information of all the leaderboards or rankings of a promotion


Get the ranking of a promotion.
get/ranking/{promotion_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
query Parameters
stage_id
integer <int32> 
Filter to get the specific ranking of a stage. Do not pass this parameter to get the overall ranking of the promotion.


 
top
integer <int32>   [ 1 .. 500 ] 
 Default:  25
The number of users in the ranking to return


 
Responses 
200
It returns an array of users with their points ordered by ranking position.


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
[
  • {
    }
]
Points Of Sale
Access to the list of the points of sale in a promotion


Get the list of all points of sale in a promotion.
get/pos/{promotion_id}
SecuritybearerAuth 
Request 
path Parameters
promotion_id
required
integer <int32> 
ID of the promotion


 
query Parameters
group
string
Returns the points of sale that belongs to a specific group. You can filter by multiple groups by separating their references with a comma.


 
Responses 
200
A list of points of sale ordered by group and alphabetically


401
Unauthorized. Authentication token not valid.


403
Forbidden.


404
The specific resource was not found.


429
Rate limit. Too many requests.


default
Unexpected error


Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "paging": {
    }
}