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