API Documentation

The API will allow you to dynamically load the necessary data using them in your statistics systems

General information

Overview

The Recreativ API provides access to the Recreativ infrastructure through a standardized programming interface. Through the API Recreativ you can do the same thing that is available when using the Recreativ.com account, but using the programming language of your choice.

Recreativ API is a RESTful API based on HTTP requests and responses in XML or JSON (P) format. If you are familiar with the Twitter API, Amazon S3, del.icio.us, or another web service, you can easily get started with our API.

This version of the API uses a token mechanism for authorization. This means that all requests must be encrypted and sent via SSL / TLS to https: //. This also means that each request must be accompanied by a specially formed HTTP header, in which there will be an authorization key. You can find this key in your personal account on the profile page.

Code example


user@localhost:~$ curl 'https://recreativ.com/api/advertiser/campaigns?filter[id]=111,222' \
     -H 'Content-Type: application/json; charset=UTF-8' \
     -H 'Accept: application/json' \
     -H 'Auth-Token: eNldKDZHFuemaotqp6166WhZ0nximcHz'
     -v
> GET /api/advertiser/campaigns?filter[id]=111,222 HTTP/1.1
> User-Agent: curl/7.35.0
> Host: recreativ.com
> Content-Type: application/json; charset=UTF-8
> Accept: application/json
> Auth-Token: eNldKDZHFuemaotqp6166WhZ0nximcHz
> < HTTP/1.1 200 OK< Server: nginx< Date: Wed, 18 Feb 2015 15:34:24 GMT< Content-Type: application/json; charset=UTF-8< Transfer-Encoding: chunked< Connection: keep-alive<
[
   {
      "id":111,
      "title":"Первая кампания",
      "active":1,
      "maxclicks":0,
      "maxmoney":"0.0000",
      "isRetarget":0
   },
   {
      "id":222,
      "title":"Вторая кампания",
      "active":1,
      "maxclicks":1000,
      "maxmoney":"25.0000",
      "isRetarget":0
   }
]

Need help?

If you have any questions, ask our support team by mail, skype or through the form on the site.

Entry points

The API is accessible through HTTP requests to a specific URL, which contains information about exactly what you want to do in the GET and POST variables. All endpoints are accessible only through encrypted HTTPS connection.

API response format

For data transfer XML and JSON are used. The choice of a specific format depends on the Accept header in the server request. To receive a response in JSON, the value of this header must contain the MIME type JSON - application / json, for XML - application / xml. All communication with the server occurs via the HTTPS.

Stable root endpoint of the latest version:

https://recreativ.com/api/

The response can be generated both in JSON format and in XML. This behavior depends on the passed Accept header, which should contain the type of response you want.

Authorization

Authorization takes place using a special key, the so-called access token, which should accompany each request to the server in the Auth-Token request header.

To connect the API, you must support team, after which your personal key for authorization in the API will be available in the settings of your personal account.

Query restriction

The number of API requests per second is limited to 5 requests. If this number is exceeded, you will receive a server response with code 429.

Endpoints

This page describes the addresses of endpoints with the parameters that are used when creating the request.

User

Current user

Request information about the current user.

Method GET
Path https://recreativ.com/api/me
Response Model User

List of clients

Getting a list of referrals of the current account.

Method GET
Path https://recreativ.com/api/advertiser/users
Response Model User

Receiving customer

Getting account information from your referrals.

Method GET
Path https://recreativ.com/api/advertiser/users/{id}
Response Model User

Client Campaign List

Getting a list of campaigns owned by a customer.

Method GET
Path https://recreativ.com/api/advertiser/users/{id}?expand=campaigns
Response Model User, Campaign

Add customer

Create an advertiser account. If successful, returns code 201.

NOTE!
The created user will be automatically designated as the referral of the owner of the API key from which the request for creation came.
Method POST
Path https://recreativ.com/api/advertiser/users
Response Model User

Creating a user will take place in the usual way, so if registration took place through a form on the site, including confirmation of the mailbox. The only difference is the creation of a password on the Recreativ side.

Options

Key Type Required Description
user string
User login
email string
User E-mail
url string
Company website (advertiser)
name string
Personal username
telegram string
Telegram
skype string
Skype
phone string
User Phone

Customer change

Changing user balance {id} by the amount specified in the request parameters. The response to the request will be the user structure in the specified format.

Method PUT
Path https://recreativ.com/api/advertiser/users/{id}
Response Model User

Options

Key Type Required Description
balance float
The amount by which the balance of account will change (may be negative)

Website

Category List

Allows to get a list of site categories.

Method GET
Path https://recreativ.com/api/webmaster/categories
Response Model Category

Sites list

Allows to get a list of user sites.

Method GET
Path https://recreativ.com/api/webmaster/sites
Response Model Website

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format
status int
Status
  • 0 - Moderation
  • 1 - Active
  • 2 - Forbidden
  • 3 - Unconfirmed

Example request URI
`/api/webmaster/sites?dateFrom=2023-01-01&dateTo=2023-01-10&status=1`

Getting a site

Getting information about the specified site.

Method GET
Path https://recreativ.com/api/webmaster/sites/{id}
Response Model Website

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format

Example request URI
`/api/webmaster/sites/1111?dateFrom=2023-03-01&dateTo=2023-03-02`

Statistics

Retrieving statistics on websites and blocks.

Method GET
Path https://recreativ.com/api/webmaster/statistic
Response Model Statistics

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format
siteIds string
Comma-separated numeric site IDs
blockIds string
Comma-separated numeric block IDs

Example request URI
`/api/webmaster/statistic?dateFrom=2023-03-01&dateTo=2023-03-026&siteIds=1111,2222&blockIds=3333,4444,5555`

Payouts

Getting information about payments

Method GET
Path https://recreativ.com/api/webmaster/payment
Response Model Payouts

Block

Receive block

Getting information about the specified block.

Method GET
Path https://recreativ.com/api/webmaster/blocks/{id}
Response Model Block

Block list

Allows to get a list of blocks for the specified site.

Method GET
Path https://recreativ.com/api/webmaster/sites/{id}?expand=blocks
Response Model Block, Website

Campaign

Category List

Allows to get a list of root categories suitable for installation when creating a campaign.

Method GET
Path https://recreativ.com/api/advertiser/categories
Response Model Category

Receive Campaign

Retrieving information about the specified campaign.

Method GET
Path https://recreativ.com/api/advertiser/campaigns/{id}
Response Model Campaign

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format

Example request URI
`/api/advertiser/campaigns/1111?dateFrom=2023-03-01&dateTo=2023-03-02`

Campaign List

Getting list of campaigns owned by the user.

Method GET
Path https://recreativ.com/api/advertiser/campaigns
Response Model Campaign

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format
type int
Type
  • 1 - Retargeting
  • 2 - Standard
archived int
Archive
  • 0 - Yes
  • 1 - No
targetId int
Conversion
  • 0 - All
  • 1 - Purchase
  • 2 - Registration
  • 3 - Intermediate goal

Example request URI
`/api/advertiser/campaigns?dateFrom=2023-03-01&dateTo=2023-03-026&siteIds=1111&targetId=1&archived=0`

Campaign Change

Modification the specified campaign.

Method PUT
Path https://recreativ.com/api/advertiser/campaigns/{id}
Response Model Campaign

Options

Key Type Required Description
active boolean
Campaign Activity Flag

Campaign Statistics

Campaign Statistics

Method GET
Path https://recreativ.com/api/advertiser/statistics
Response Model Campaign Statistics

Options

Key Type Required Description
filter[dateFrom] string
Slice start date in ISO 8601 format
filter[dateTo] string
Slice end date in ISO 8601 format
filter[id] string
Comma-separated numeric campaign IDs
groupDate boolean
Getting advertising campaign statistics

Example request URI
`/api/advertiser/statistics?filter[dateFrom]=2015-05-13&filter[id]=123,456`
`/api/advertiser/statistics?filter[dateFrom]=2015-05-13&filter[id]=123,234,345&groupDate=true`

Ad Stats

Teaser Statistics.

Method GET
Path https://recreativ.com/api/advertiser/statistics
Response Model Ad Stats

Options

Key Type Required Description
scope string
Area for obtaining statistics, for teasers is `offers`
filter[dateFrom] string
Slice start date in ISO 8601 format
filter[dateTo] string
Slice end date in ISO 8601 format
filter[date] string
Exact date in ISO 8601 format
filter[id] int
Numeric teaser id
filter[campaignId] int
Numeric campaign id (when using this filter, the filter `date` is required)
groupDate boolean
Getting advertising ad statistics

Example request URI
`/api/advertiser/statistics?scope=offers&filter[dateFrom]=2015-05-13&filter[id]=123`
`/api/advertiser/statistics?scope=offers&filter[date]=2015-05-13&filter[campaignId]=321&groupDate=true`

Quality Indicator

Obtaining a list of coefficients owned by the company.

Method GET
Path https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}/site/{?id}
Response Model Coefficient

Example request URI

`/api/advertiser/campaigns/multipliers/1111/site

`/api/advertiser/campaigns/multipliers/1111/site/2222s3333

Adjusting the coefficient

Modifying the specified coefficient.

Method PUT
Path https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}/site/{id}
Response Model

Example request URI
`/api/advertiser/campaigns/multipliers/1111/site/2222s3333?coef=1.2

Options

Key Type Required Description
coef float
Number

Minimum value 0.1

Maximum value 10

Adjusting the device coefficient

Modifying the specified device coefficient.

Method PUT
Path https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}/device/{type}
Response Model

Example request URI
`/api/advertiser/campaigns/multipliers/1111/device/{type}?coef=1.2

Options

Key Type Required Description
type string
Device
  • desktop
  • mobile
  • tablet
coef float
Number

Minimum value 0.1

Maximum value 10

Site Statistics

Site Statistics

Method GET
Path https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}
Response Model Site Statistics

Example request URI
`/api/advertiser/campaigns/multipliers/1111?dateFrom=2023-03-01&dateTo=2023-03-02`

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format
targetId int
Conversion
  • 0 - All
  • 1 - Purchase
  • 2 - Registration
  • 3 - Intermediate goal

Device Statistics

Device Statistics

Method GET
Path https://recreativ.com/api/advertiser/campaigns/multipliers/{campaign}/device
Response Model Device Statistics

Example request URI
`/api/advertiser/campaigns/multipliers/1111/device?dateFrom=2023-03-01&dateTo=2023-03-02`

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format
targetId int
Conversion
  • 0 - All
  • 1 - Purchase
  • 2 - Registration
  • 3 - Intermediate goal

Ad

List of subcategories

Allows you to get a list of company subcategories.

Method GET
Path https://recreativ.com/api/advertiser/subCategories
Response Model Category

Options

Key Type Required Description
id int
Campaign Id

Example request URI
`/api/advertiser/subCategories?id=1111`

List of discount types

Allows you to get a list of discount types.

Method GET
Path https://recreativ.com/api/advertiser/discountType/{campaign}
Answer

json

Options

Key Type Required Description
campaign int
Campaign Id

Example request URI
`/api/advertiser/discountType/1111`

Adding an ad

Create an ad. If successful, it will return code 201.

Method POST
Path https://recreativ.com/api/advertiser/offers
Response Model Ad

Options

Key Type Required Description
campaignId int
Campaign Id
description string
Text up to 60 characters. GEO Thailand, 100 characters.
url string
URL
price int
Price
discount int
  • Discount id: 1
  • from id: 2
  • to id: 3
discountType string
Discount type
oldPrice int
Old price
subCategory int
Subcategory ID
clickPrice float
CPC
rectangle string

Rectangular image (Main)

Example format:

data:image/{type};base64,.... where type - png, jpeg
square string

Square image

Example format:

data:image/{type};base64,.... where type - png, jpeg

Receive ad

Getting information about the specified teaser.

Method GET
Path https://recreativ.com/api/advertiser/offers/{id}
Response Model Ad

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format
targetId int
Conversion
  • 0 - All
  • 1 - Purchase
  • 2 - Registration
  • 3 - Intermediate goal

Example request URI
`/api/advertiser/offers/1111?dateFrom=2023-03-01&dateTo=2023-03-02`

Ad List

Getting a list of teasers owned by the campaign.

Method GET
Path https://recreativ.com/api/advertiser/campaigns/{id}?expand=offers
Response Model Ad, Campaign

Options

Key Type Required Description
dateFrom string
Date in ISO 8601 format
dateTo string
Date in ISO 8601 format
archived int
Archive
  • 0 - Yes
  • 1 - No
targetId int
Conversion
  • 0 - All
  • 1 - Purchase
  • 2 - Registration
  • 3 - Intermediate goal
type int
Type
  • 1 - Retargeting
  • 2 - Standard

Example request URI
`/api/advertiser/campaigns/1111?dateFrom=2023-03-01&dateTo=2023-03-02&type=1`

Enable/Disable ad

Enable/Disable ad. If successful, a code will be returned `204`.

Method PUT
Path https://recreativ.com/api/advertiser/offers/{id}
Response Model

Options

Key Type Required Description
active boolean
Teaser Activity Flag

Delete ad

Delete teaser. If successful, a code will be returned `204`.

Method DELETE
Path https://recreativ.com/api/advertiser/offers/{id}
Response Model

Data models

This page lists all the data structures that are used in the API responses.

User

Model representing user data.

Attribute Type Description
id int User ID
username string User login
email string User E-mail
type string Account type (penerbit, pengiklan)
url string Company website (advertiser)
date date Date of registration in ISO 8601 format
maxmoney float Daily budget (advertiser)
whatsapp string WhatsApp
telegram string Telegram
skype string Skype
phone string User Phone
balance float Current account balance
parentId int Model id User, referral, which is an account

Campaign Statistics

Model that represents campaign statistics.

Attribute Type Description
date string Date in ISO 8601 format
views int Number of showings
clicks int Number of transitions
money float Amount of expenses
orders int Conversions
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC

Campaign

Model representing campaign data.

Attribute Type Description
id int Campaign Id
title string Campaign Title
active bool Campaign Activity Flag
maxclicks int Conversion limit
maxmoney float Spending limit
isRetarget bool Is the campaign a retargeting campaign
category_id int Category id
items int Products
status int Status
views int Number of showings
clicks int Number of transitions
money float Amount of expenses
orders int Conversions
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC

Ad Stats

Model that represents teaser statistics.

Attribute Type Description
date string Date in ISO 8601 format
views int Number of showings
clicks int Number of transitions
money float Amount of expenses
orders int Conversions
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC

Ad

Model that represents the teaser data.

Attribute Type Description
id int Teaser id
title string Product title
campaignId int Model id Campaigns
img Image Structure with a list of product images
img_wide Image Structure with a list of product images
isRetarget bool Is the campaign a retargeting campaign
opis string Product description
cost string Product price
url string Referral Address
url_mobile string Referral Address for mobile platforms
stavka float Current conversion price
active bool Teaser Activity Flag
views int Number of showings
clicks int Number of transitions
money float Amount of expenses
orders int Conversions
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC

Category

Model representing these categories.

Attribute Type Description
id int Category id
parent_id int Parent Model ID Category
title string Category Title

Image

Model representing image data.

Attribute Type Description
url string Default image
allowedSizes string Allowed image sizes
pattern string Custom size template

Website

Model representing site data.

Attribute Type Description
id int Site id
status string Status
url string Website address
category_id string Model id Category
monthly_uniq_users string Monthly unique visitors
blocks_count int Units
views int Impressions
clicks int Clicks
ctr float CTR
cpm float CPM
money int Income

Block

Model representing block data.

Attribute Type Description
id int Block id
bn string Block code
title string Block header
siteid string Site id

Statistics

A model representing statistics on websites and blocks.

Attribute Type Description
date string Date in ISO 8601 format
views int Impressions
clicks int Clicks
ctr float CTR
cpm float CPM
money int Income

Payouts

Model representing payout data

Attribute Type Description
date string Date in ISO 8601 format
wallet string Payment method
amount float Income
status string Status

Site Statistics

Model representing statistical data about websites

Attribute Type Description
site_id string Site id
views int Number of showings
clicks int Number of transitions
money float Amount of expenses
orders int Conversions
ctr float CTR
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC
coef float Coefficient

Device Statistics

Model representing statistical data about devices

Attribute Type Description
device string Device
views int Number of showings
clicks int Number of transitions
money float Amount of expenses
orders int Conversions
ctr float CTR
cpm float CPM
cpo float CPO
cr float CR
cpc float CPC
coef float Coefficient

Coefficient

Model representing coefficient data.

Attribute Type Description
coef float Coefficient
campaignId int Campaign Id
siteId int Site id
deviceId int Device ID
informerId int SSP informer ID

Error processing

General information

The status of the request is indicated by the response code of the server with the corresponding status. If the error requires a more detailed description, the response body may contain a list with the `message` parameter. The value of which will be an extended description of the error.

Error example

Attempting to request a resource without the appropriate rights will result in the following error:

XML


<response>
   <name>Unauthorized</name>
   <message>You are requesting with an invalid credential.</message>
   <code>0</code>
   <status>401</status>
</response>

JSON


{
   "name": "Unauthorized",
   "message": "You are requesting with an invalid credential.",
   "code": 0,
   "status": 401
}

Status 200

The request was successfully processed by the server and no errors occurred.

Status 201

The resource was successfully created in response to the `POST` request. The `Location` header contains a URL pointing to the newly created resource.

Status 204

The request was processed successfully, and there is no content in the response (for the `DELETE` request, for example).

Status 304

The resource has not changed. You can use the cached version.

Status 400

Invalid request. It can be connected with various problems on the user side, such as incorrect JSON data in the request body, incorrect action parameters, etc.

Status 401

Authentication failed.

Status 403

An authenticated user is not allowed access to the specified API entry point.

Status 404

The requested resource does not exist.

Status 405

The method is not supported. See the list of supported HTTP methods in the `Allow` header.

Status 415

Unsupported data type. The wrong data type or version number is requested.

Status 422

Data verification failed (in response to a `POST` request, for example). For detailed error messages, see the response body.

Status 429

Too many requests. Request denied due to exceeding request frequency limits.

Status 500

Internal Server Error. A possible cause is errors in the program itself.