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 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 lists all the data structures that are used in the API responses.
User
Current user
Request information about user preferences.
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 (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
|
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
|
|
archived | int |
Archive
|
|
targetId | int |
Conversion
|
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
|
|
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
|
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
|
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 |
|
|
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
|
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
|
|
targetId | int |
Conversion
|
|
type | int |
Type
|
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, will return the code `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, 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 (penerbit, pengiklan) |
url | string | Company website (advertiser) |
date | date | Date of registration in ISO 8601 format |
maxmoney | float | Daily budget (advertiser) |
string | ||
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.