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 contact our 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
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

Getting a site

Getting information about the specified site.

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

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

Campaign List

Getting list of campaigns owned by the user.

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

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
scope string
Area for obtaining statistics, for campaigns is `campaigns`
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

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

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)

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`

Ad

Receive ad

Getting information about the specified teaser.

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

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

Delete ad

Delete teaser. If successful, will return the code `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 (publisher, advertiser)
url string Company website
date date Date of registration in ISO 8601 format
maxmoney float Daily budget
name string Personal username
telegram string Telegram
skype string Skype
phone string User Phone
balance float Current account balance
parentId int Model id User, whose referral is the account

Campaign Statistics

Model that represents campaign statistics.

Attribute Type Description
campaignId int Campaign Id
date string Date in ISO 8601 format
views int Number of showings
clicks int Number of transitions
money float Amount of expenses

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

Ad Stats

Model that represents teaser statistics.

Attribute Type Description
offerId int Teaser id
date string Date in ISO 8601 format
views int Number of showings
clicks int Number of transitions
money float Amount of expenses

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
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
clicks int Transitions for the entire period
views int Views for the entire period
money float Costs for the entire period
todayclicks int Conversions for today
todayviews int Showings for today
todaymoney float Expenses for today

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
url string Website address
category_id string Model id Category

Block

Model representing block data.

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

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.