Easypromos API Reference (2.0.1)

Download OpenAPI specification:Download

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"
}

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

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
{
  • "id": 1,
  • "name": "string",
  • "type": 1,
  • "start_date": "2019-08-24T14:15:22Z",
  • "end_date": "2019-08-24T14:15:22Z"
}

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.

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": [
    ]
}
Response samples
application/json
{
  • "lt": "$5$dGF3emr9XUTj6FtE$63PmeiKorJpSEGsd5vN2Lrlxguvo1cE7KTXB",
  • "registered": "true"
}

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

Unhautorized 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.

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": {
    }
}

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"
}

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 extra information of the user's participation. Applies only to stage type 2 (answers to a questionnaire). The other stage types will return an empty array.

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

Unhautorized 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": {
    }
}

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
[
  • {
    }
]