Hybrid API

Getting started with the Hybrid API

Authorization

The Bearer token authorization protocol is used for authentication and authorization in the API.

A client is created for the user with the client_id and client_secret parameters, using which he receives an access token for authentication in the API.

You can get clientid and clientSecret by leaving us a request by mail support@hybrid.ru.

When grant_type=client_credentials, the method creates a new access token based on the client_id, client_secret pair.


            
                Request
            
            
                POST /token HTTP/2
            
            
                Host: https://capi.hybrid.ru
            
            
                Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

If grant_type=refresh_token the method creates a new access token instead of the old one, which is identified by the passed refresh_token parameter.

Response example

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
    "access_token": "{access_token}",
    "token_type": "bearer",
    "scope": "{scope}",
    "expires_in": "86400",
    "refresh_token": "{refresh_token}"
}

Access token expiration

Each received access token is valid for 24 hours. This is indicated by the expires_in property in the response to an access token request. Refresh_token is also indicated there - a special token for obtaining a new access token.

Request

POST /token HTTP/2
Host: https://capi.hybrid.ru
Content-Type: application/x-www-form-urlencoded

    grant_type=refresh_token

    &refresh_token={refresh_token}

    &client_id={client_id}

    &client_secret={client_secret}

Response example

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8

{
    "access_token": "{new_access_token}",
    "token_type": "bearer",
    "expires_in": "86400",
    "refresh_token": "{refresh_token}"
}

Getting started with the Hybrid API

HTTP Codes

HTTP code	Meaning
200, 201, 204	ОК.
400	Method not supported.
401	Unauthorized, the user has no rights.
404	The method or entity does not exist.
500	An invalid request was made or invalid data was sent.

ADVERTISER

Creating an advertiser (advertiserEdit/create)

This method is required to create a new advertiser in your agency. In response, you will receive:

"id" — IAdvertiser ID and new data cloud ID. It is generated automatically, and the ID is the same as the advertiser ID.
"name" — the name that you specified when creating .
"contentCategory" — the advertiser's Industry ID that you specified when creating the advertiser.
"defaultPixel" — pixel Id

Request:
Url	advertiserEdit/create	Create an advertiser
Method	POST
Content-Type	application/json

Request and response model:
Field name	Required	Description	Restrictions	Data type
name	Yes	Name	a-z, A-Z, ‘ ’, ‘-’ Length: up to 30 characters	String
defaultPixel	Yes	Pixel ID		String
contentCategory	Yes	Content category ID		String
id	No	Advertiser ID (only when responding)		String
oRDId	No	advertising data aggregator Id		Long
initialContractId	No	initial treaty Id		Long
finalContractId	No	final treaty Id		Long

Request example:

POST advertiserEdit/create
{
    "name": "Test advertiser",
    "defaultPixel": "5e2ad0764d506e62f85ba123",
    "contentCategory": "529c829380fb961b6480f123",
    "oRDId": 1,
    "initialContractId": 5,
    "finalContractId": 6
}

Response example:

{
    "id": "5e2ad0764d506e62f85ba777"
    "name": "Test advertiser",
    "defaultPixel": "5e2ad0764d506e62f85ba123",
    "contentCategory": "529c829380fb961b6480f123",
    "oRDId": 1,
    "initialContractId": 5,
    "finalContractId": 6
}

ADVERTISER

Getting an advertiser (advertiserEdit/getbyid?advertiserId={advertiserId})

This method is required to get advertiser settings and a link to get client statistics:

You'll get:

"id" — ID of the advertiser and the new data cloud. It is generated automatically and the ID is the same as the advertiser ID.
"name" — the name that you specified when creating.
"contentCategory" — ID The industry of the advertiser that you specified when creating the advertiser.
"defaultPixel" — Anchor pixel ID.

Request:
Url	advertiserEdit/getbyid?advertiserId={advertiserId}	Getting an advertiser
Method	GET
Content-Type	application/json
Parameters	advertiserId	advertiser id

Response model:
Field name	Description	Data type
id	Advertiser ID	String
name	Name	String
defaultPixel	Pixel ID	String
contentCategory	Content category ID	String

Request example:

GET advertiserEdit/getbyid?advertiserId=5e2ad0764d506e62f8123456

Response example:

{
    "id": "5e2ad0764d506e62f8123456",
    "name": "Test advertiser",
    "defaultPixel": "5e2ad0764d506e62f85ba123",
    "contentCategory": "529c829380fb961b6480f123"
}

ADVERTISER

Getting an advertiser's balance (advertisers/balance?id={advertiserId})

The method is used to get the remaining balance on the advertiser. With it, you can determine how much money is left for placement. This method can be used to determine how much has been spent so far. The delay in debiting funds from the account, in DSP 10-15 minutes. Use this method, you can also check how much money is left on the advertiser before replenishment, in case of prolongation. There are cases when, after the end of the campaign, funds are debited from the advertiser, the statistics was not uploaded in full, and a negative value may be recorded on the advertiser's balance. In this case, it is necessary to replenish the balance, taking into account the negative value that was previously on the advertiser's balance.

There may also be a reverse case when the required amount has been already realized but it took less money than planned, then the advertiser may have budget surpluses on the balance sheet.

In order to understand how much money was spent, it is necessary to deduct from the total campaign budget the residual budget obtained by this method.

Request:
Url	advertisers/balance?id={advertiserId}	Getting an advertiser's balance
Method	GET
Content-Type	application/json
Parameters	id	Advertiser ID

Response model:
Field name	Required	Description	Data type
balance	Yes	Balance	Double
currency	Yes	Currency in ISO 4217 Numeric Format	Long

Request example:

GET advertisers/balance?id=5e2ad0764d506e62f8123451

Response example:

{
    "balance": 123.12,
    "currency": 643
}

ADVERTISER

Transferring money to an advertiser (advertisers/transfertoadvertiser)

With this method, the advertiser's balance is replenished from the agency's balance. The advertiser's balance is required to start campaigns; if the balance is zero, Banners will not be displayed in the campaign.

Request:
Url	advertisers/transfertoadvertiser	Transferring money to an advertiser
Method	POST
Content-Type	application/json

Request model:
Field name	Required	Description	Data type
advertiserId	Yes	Advertiser ID	String
sum	Yes	Total Sum	Double

Request example:

{
    "advertiserId": "529c829380fb961b6480f123",
    "sum": 100
}

ADVERTISER

Creating/Updating an Advertiser Order (order/(create/update))

The method is required to create or update orders. You can use orders to track the progress of daily limits (planned budgets) for your placement. If necessary, Hybrid support specialists will use orders to determine and perform planned budgets.

Request:
Url	order/(create/update)	Create / update an order
Method	POST
Content-Type	application/json

Request /Response Model:
Field name	Required	Description	Data type	Possible values
id	Yes, when updating	Order Id	Long
amount	Yes	Order Quantity	Long	Positive integer
ownerId	Yes	Advertiser Id	String
campaignIds	Yes	List of campaigns Id in an order	String
name	Yes	Order name	String	а-я,А-Я,a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols.
responsibleUserId	Yes	Id of a user responsible for an order	Long
startDate	Yes	Start Date	Date
endDate	Yes	End date	Date
sumPriceWithoutVAT	Yes	Order price without VAT	Long	Positive number with 2 digit precision.
status	Yes	Order status	Long	Active = 1, NotActive = 2, Archive = 3
unit	Yes	Order Metric	Long	Impressions = 1, Clicks = 2, VideoViews = 3, AppInstalls = 4, Conversions = 6, Views = 7

Request example:

POST order/update
{
    "id": 1234567,
    "amount": 1000,
    "campaignIds": [
        "58a2d2837bc72f0ba03d5103",
        "58a2d2837bc72f0ba03d5104"
    ],
    "endDate": "2021-12-31T23:59:59+03:00",
    "name": "Test",
    "ownerId": "58a2d2837bc72f0ba03d5105",
    "responsibleUserId": 111111,
    "startDate": "2021-12-16T00:00:00+03:00",
    "status": 1,
    "sumPriceWithoutVAT": 100000,
    "unit": 2
}

Response example:

{
    "id": 1234567,
    "amount": 1000,
    "campaignIds": [
        "58a2d2837bc72f0ba03d5103",
        "58a2d2837bc72f0ba03d5104"
    ],
    "endDate": "2021-12-31T23:59:59+03:00",
    "name": "Test",
    "ownerId": "58a2d2837bc72f0ba03d5105",
    "responsibleUserId": 111111,
    "startDate": "2021-12-16T00:00:00+03:00",
    "status": 1,
    "sumPriceWithoutVAT": 100000,
    "unit": 2
}

ADVERTISER

Order activation/suspension/archiving (order/(activate/deactivate/archive))

This method is necessary to quickly change the status of orders.

Request:
Url	order/(activate/deactivate/archive)	Activate / deactivate / archive an order
Method	POST
Content-Type	application/json
Parameters		Orders Id list

Request example:

POST order/activate
Body:
[ 123456, 123457 ]

Response example:

204 No Content

ADVERTISER

Getting an order (order/getbyid?orderId=)

This method is necessary to track the results achieved in an order, which in turn is linked to campaigns.

Request:
Url	order/getbyid?orderId=	Getting an order
Method	GET
Content-Type	application/json
Parameters	orderId	Order Id

Response Model:
Field name	Required	Description	Data type	Possible values
id	Yes, when updating	Order Id	Long
amount	Yes	Value of orders	Long	Positive integer
ownerId	Yes	Advertiser Id	String
campaignIds	Yes	List of campaigns Id in an order	String
name	Yes	Order name	String	а-я,А-Я,a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols.
responsibleUserId	Yes	Id of a user responsible for an order	Long
startDate	Yes	Start Date	Date
endDate	Yes	End date	Date
sumPriceWithoutVAT	Yes	Order price without VAT	Long	Positive number with 2 digit precision.
status	Yes	Order status	Long	Active = 1, NotActive = 2, Archive = 3
unit	Yes	Order unit	Long	Impressions = 1, Clicks = 2, VideoViews = 3, AppInstalls = 4, Conversions = 6, Views = 7

Request example:

GET order/getbyid?orderId=1234567

Response example:

{
    "id": 1234567,
    "amount": 1000,
    "campaignIds": [
        "58a2d2837bc72f0ba03d5103",
        "58a2d2837bc72f0ba03d5104"
    ],
    "endDate": "2021-12-31T23:59:59+03:00",
    "name": "Test",
    "ownerId": "58a2d2837bc72f0ba03d5105",
    "responsibleUserId": 111111,
    "startDate": "2021-12-16T00:00:00+03:00",
    "status": 1,
    "sumPriceWithoutVAT": 100000,
    "unit": 2
}

ADVERTISER

Return of money to the agency (advertisers/transfertoagency)

Using this method, the money is returned from the advertiser's balance to the agency's one.

Upon completion of placement, we recommend to return immediately the remaining funds to the agency. As traffic is purchased not at the actual set price, but under the terms of an open auction, the final CPC may differ from the set bid downwards. However, the total cost of placement may be less than the planned one.

You can also use this method to transfer funds to the agency in case of a decrease in the total budget.

Request:
Url	advertisers/transfertoadvertiser	Money transfer to an advertiser
Method	POST
Content-Type	application/json

Request model:
Field name	Required	Description	Data type
advertiserId	Yes	Advertiser Id	String
sum	Yes	Total Sum	Double

Request example:

GET order/getbyid?orderId=1234567

Response example:

{
    "advertiserId": "529c829380fb961b6480f123",
    "sum": 100
}

Request:
Url	adlibraryfolder/create	Create an ad folder
Method	POST
Content-Type	application/json

Request / response model
Field name	Required	Description	Data type
id	Yes, when responding	Folder Id	String
name	Yes	Name	String
parentId	No	Parent folder id	String
ownerId	Yes	Owner ID	String

Request:
Url	adlibraryfolder/getfolderstree?ownerId=	Getting the ad folder tree
Method	GET
Content-Type	application/json
Parameters	ownerId

Answer (array of objects):
Field name	Description	Data type
id	Folder Id	String
name	Name	String
parentId	Parent folder id	String
adLibraryFolders[]	List of subfolders	Array of similar nested objects

Request:
Url	adlibrarybanner/create	Creating an ad
Method	POST
Content-Type	application/json

Request model (array of objects)
Field name	Required	Description	Data type	Possible values
$type	Yes	Banner type	String	ImageOrFlashBanner – picture Html5Banner - Html5 NativeBanner - native banner
clickUrl	Yes	Url click	String
name	Yes	Name	String	a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols
companyName	Yes, for Native	Company name	String	a-z, A-Z, ‘ ’, ‘-’ limit length is 70 symbols
buttonText	Yes, for Native	Button text	String	a-z, A-Z, ‘ ’, ‘-’ limit length is 15 symbols
text	Yes, for Native	Ad text	String	a-z, A-Z, ‘ ’, ‘-’ Length: up to 30 characters
title	Yes, for Native	Ad headline	String	a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols
folderId	No	Folder id	String
fileContent.base64Data	Yes, for Image, Native	File content in base64 format	String
fileContent.contentType	Yes, for Image, Native	File Content-Type	String
fileContent.fileName	Yes, for Image, Native	File name	String
altImages[].content.base64Data	Yes, for Native	File content in base64 format	String
altImages[].content.contentType	Yes, for Native	File Content-Type	String
altImages[].content.fileName	Yes, for Native	File name	String
height	Yes, for Native	Height	Long
width	Yes, for Native	Width	Long
logoContent.base64Data	Yes, for Native	File content in base64 format	String
logoContent.contentType	Yes, for Native	File Content-Type	String
logoContent.fileName	Yes, for Native	File name	String
iconImageContent.base64Data	Yes, for Native	File content in base64 format	String
iconImageContent.contentType	Yes, for Native	File Content-Type	String
iconImageContent.fileName	Yes, for Native	File name	String
archive.base64Data	Yes, for Html5	File content in base64 format	String
archive.contentType	Yes, for Html5	File Content-Type	String
archive.fileName	Yes, for Html5	File name	String

Response model (array of objects)
Field name	Description	Data type
isValid	Banner Validity Flag	Boolean
content.$type	Banner Type	String
content.name	Name	String
content.folderId	Banner Id	String
content.id	Banner Id	String

Request:
Url	adlibraryagency/getpage	Getting a list of ads by condition
Method	POST
Content-Type	application/json

Request model
Field name	Description	Data type
folderId	Folder id	Long
condition.limit	The number of values to return. Max=100	Long
condition.page	Page (from 0)	Long

Response model
Field name	Description	Data type
banners.count	Total number of banners	Long
banners.items[].$type	Banners type	String
banners.items[].id	Banners Id	String

AUDIENCES

Creating an audience based on the JsActionAudience event (audience/create)

Using this method, you can create an audience of users for both retargeting and conversion counting. Audience updates every time JSAction is trigged. An event audience cannot be created until JS is installed on the site and has not worked at least once. Use the "isConversionsTrack" field to count conversions. After that, the calculation of post-click and post-view conversions in campaigns will start.

To add new audiences for retargeting, you need to install js codes on your site:

Sample code: onclick="_txq.push(['track', 'segment33']);"

Variable values are marked in red.

When an event is executed on the site, it is passed to the console. You can create an audience in the console only if at least one event has already been received.

Thus, if you urgently need to add a new audience, you will first need to use the Test request for JS events method, and only after that Create audience based on the event method.

Request:
Url	audience/create	Create an audience based on an event
Method	POST
Content-Type	application/json

Request model
Field name	Required	Description	Limits	Data type
audience.$type	Yes	Audience type	JsActionAudience	String
audience.actionId	Yes	Action name		String
audience.name	Yes	Name	a-z, A-Z, ‘ ’, ‘-’ Length: up to 30 characters	String
audience.duringPeriod	Yes	Activity period		Long
audience.dataCloudId	Yes	Cloud id		String
audience.pixelId	Yes	Default pixel id		String
audience.advertiserId	Yes	Default advertiser ID		String
isConversionsTrack	Yes	Conversion count flag		Boolean

Response model
Field name	Description	Data type
audience.id	Audience ID	String

Request example:

POST audience/create
{
    "audience": {
        "$type": "JsActionAudience",
        "dataCloudId": "5fac17f24d506ef09c000b81",
        "pixelId": "5fac17f24d506ef09c000b81",
        "name": "test_audience-1",
        "advertiserId": "5fa95ff24d506e4f14f3571d",
        "duringPeriod":120,
        "status":"1",
        "actionId":"metropoliya_call"
    },
    "isConversionsTrack":true
}

Response example:

{
    "audience": {
        "id": "5fbf9c157bc72fe25c7b7772"
    }
}

AUDIENCES

Test request for JS events.

This method is required if the JsAction has already been installed on the site, but the event has not yet occurred. This method allows you to simulate a JS submission. After requesting this method, you can create a JsActionAudience audience

https://dss.hybrid.ai/pixel/trackapi2?pid=PIXEL_ID&txid=VISITOR_ID&evt=EVENT_NAME&cnt=

where:

PIXEL_ID - Pixel ID (5fac17f24d506ef09c000b81)
VISITOR_ID - user id 20 characters (possible characters 0-9a-f)
EVENT_NAME - event name (2120427_contacts)

Note:

All fields are required when creating or updating entities. If one of the fields is missing, then this setting is deleted.

AUDIENCES

Getting a list of audiences in the Console (audience/getbydatacloudid?dataCloudId=)

This method is required to get the entire list of available audiences with ID and size. The list will include all the audiences that have ever been created in the Console. Including the audiences that are required to receive post-click and post-view conversions. As well as JSAction audiences. The audience size is the unique users in the audience.

The size of the audience is the unique users in the audience.

Request:
Url	audience/getbydatacloudid?dataCloudId=	Getting a list of audiences
Method	GET
Content-Type	application/json
Parameters	dataCloudId	Pixel ID

Response model
Field name	Description	Data type
size	Size	Long
audience.id	Audience ID	String
audience.$type	Audience type	String
audience.userListType	List Type	505 – cid
audience.actionId	Action name	String
audience.name	Name	String

Request example:

GET audience/getbydatacloudid?dataCloudId=5fac17f24d506ef09c000b81

Response example:

[
    {
        "size":0,
        "audience": {
            "$type":"ImportAudience",
            "userListType":505,
            "name":"ae_segment_1",
            "id":"5fbf9c157bc72fe25c7b0722"
        }
    }
    ...
]

Campaign

SSP list getting (ssp/getall)

Using this method, you can get a list of active SSPs.

Request:
Url	ssp/getall	Ssp getting
Method	GET
Content-Type	application/json

Answer (array of objects):
Field name	Description	Data type
id	Ssp Id	Long
name	Name	String

Request example:

GET ssp/getall

Response example:

[
    {
        "id": 1,
        "name": "Between"
    }
]

Campaign

Campaign creating (campaign/create)

This method allows you to create campaigns by adding settings and targeting to them.

To add the audience to the campaign, it’s necessary to use the double nesting of the "GroupElement" element. This is a technical feature of the UI Console. Otherwise we will not see the used audiences in the interface. Audience transfer format:

"audienceGroup": {
    "$type": "GroupElement",
    "operatorType": 0,
    "elements": [
        {
            "$type": "GroupElement",
            "operatorType": 0,
            "elements": [
                {
                    "$type": "RemarketingElement",
                    "audienceId": "000000000000000000000000",
                    "isIncluded": true
                }
            ]
        }
    ]
}

When creating a campaign, you also need to specify a click link. Link moderation works in Hybrid Console, so the campaign may not be created due to an incorrect link or if our IP is added to the blacklist for your site.

To get Post-Click statistics in Google Analytics and Yandex.Metrica, we recommend specifying utm tags to separate traffic in the final statistics, as well as to separate directions. You can use our macros to create UTM tags.

You can request a complete list of basic macros by mail: support@hybrid.ai

We recommend setting up periodic unloading of the SSP list and, based on this, setting up campaigns for the current list. Since we regularly update the list of SSPs and you may not use some of the new ones. A list of all sps can be obtained in the SSP list getting (ssp/getall).

The daily budget is a mandatory parameter when creating campaigns. The total budget is the maximum campaign budget for the entire placement period.

Use the method Getting statistics to request statistics for the last 24 hours. Run the request at 03:00 for the previous day from 00:00 to 23:59.

Example:

"startDate":"2021-10-30T00:00:00",
"endDate":"2021-10-30T23:59:59",

Request:
Url	campaign/create	campaign creation
Method	POST
Content-Type	application/json

Request / Response model:
Field name	Required	Description	Data type	Possible values
campaign.$type	Yes	Campaign type	String	HybridExtendedCampaign
campaign.advertiserId	Yes	Advertiser Id	String
campaign.id	No	campaignId (only by receiving)	String
campaign.backtwistType	Yes	Budget allocation type	Long	Maximum = 0, Optimization = 1
campaign.betOptimizationType	Yes	Optimization Type	Long	NoOptimization = -1, CPC = 1, CPM = 2
campaign.bet	Yes	Bet	Double	Positive number with 2 digit precision. Maximum value is 1000
campaign.defaultClickUrl	Yes	Click url by default	String
campaign.startDate	Yes	Start date	Date
campaign.endDate	No	End date	Date
campaign.excludeGeoIds	No	Ids Array of excluded Geo	String[]
campaign.geoIds	No	Ids Array of enabled Geo	String[]
campaign.frequencyCaps[].event	No	Event type	Long	Impression = 1, Complete = 2, Click = 3
campaign.frequencyCaps[].count	No	Quantity	Long
campaign.frequencyCaps[].interval	No	Time interval (in hours)	Long	Maximum value is 2208 hours
campaign.frequencyCaps[].type	No	Restriction type	Long	Globally = 0, Site = 1, Place = 2
campaign.linkedSystems[].systemId	No	Ssp Id	Long
campaign.status	Yes	Campaign status	Long	Active = 1, NotActive = 2, Archive = 3
campaign.dailyMultiPriceLimitations	Yes	Budget per day	Double	Positive number with 2 digit precision. Maximum value is 100000 The priceFormationType parameter must include the budget type: Click = 0, Impression = 1, View = 2, Budget = 3
campaign.totalMultiPriceLimitations	No	Total budget	Double	Positive number with 2 digit precision. Maximum value is 100000 The total limit can be set if there is a Sumultipricelimitations, priceFormationType - must be set accordingly in the Sumultipricelimitations The priceFormationType parameter must include the budget type: Click = 0, Impression = 1, View = 2, Budget = 3
campaign.periodBudgetMultiPriceLimitations	No	Period budg	Double	Positive number with 2 digit precision. Maximum value is 100000 The budget for the period can be selected only if the Multipricelimitations is not selected and the start("StartDate") and end dates of the campaign ("EndDate") are selected The priceFormationType parameter must include the budget type: Click = 0, Impression = 1, View = 2, Budget = 3
campaign.name	Yes	Name	String	а-я,А-Я,a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols
campaign.audienceGroup.$type	Yes	Audience container type	String	GroupElement – group container
campaign.audienceGroup.operatorType	Yes	Operator type	Long	Or = 0, And = 1
campaign.audienceGroup.elements[].$type	Yes	Audience type	String	Audience based on cid - RemarketingElement
campaign.audienceGroup.elements[].isIncluded	Yes	Activate / exclude the audience	Bool
campaign.audienceGroup.elements[].audienceId	Yes	Audience Id	String
banners[].id	Only when responding	Banner Id	String
banners[].clickUrl	Yes	Click Url	String
banners[].name	Yes	Name	String	a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols
banners[].status	Yes	Banner status	Long	1 - active 3 - NotActive 4 - archived
banners[].adLibraryId	Yes, if the creation is through an existing Ad	Ad Id	String
banners[].content.$type	Yes	Banner type	String	ImageOrFlashBanner – picture Html5Banner - Html5
banners[].content.clickUrl	Yes	Click Url	String
banners[].content.name	Yes	Name	String	a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols
banners[].content.width	No	Width	Long
banners[].content.height	No	Height	Long
banners[].content.fileContent.base64Data	Yes, for Image	File content in base64 format	String
banners[].content.fileContent.contentType	Yes, for Image	File Content-Type	String
banners[].content.fileContent.fileName	Yes, for Image	File name	String
banners[].content.archive.base64Data	Yes, for Html5	File content in base64 format	String
banners[].content.archive.contentType	Yes, for Html5	File Content-Type	String
banners[].content.archive.fileName	Yes, for Html5	File name	String

Response model:
Field name	Description	Data type
campaign.id	Campaign Id	String
bannersWithContents[].banner.id	Banner Id	String
bannersWithContents[].banner.adLibraryId	Ad Id	String

Request example:

Example 1

POST campaign/create
{
    "campaign": {
        "advertiserId": "58a2d2837bc72f0ba03d5103",
        "name": "Test 19.07.2021",
        "defaultClickUrl": "http://hybrid.ru/",
        "startDate": "2021-07-19T00:00:00+0300",
        "betOptimizationType": "0",
        "backtwistType": "1",
        "bet": 20,
        "excludeGeoIds": [
            "535d61c00000640002002b74"
        ],
        "geoIds": [
            "535d61c000006400020010d9",
            "535d61c0000064000200301a"
        ],
        "frequencyCaps": [
            {
                "event": 1,
                "count": 5,
                "interval": 24,
                "type": 1
            }
        ],
        "dailyMultiPriceLimitations": [
            {
                "priceFormationType": "3",
                "amount": 1000
            }
        ],
        "status": "2",
        "$type": "HybridExtendedCampaign",
        "audienceGroup": {
            "$type": "GroupElement",
            "operatorType": 0,
            "elements": [
                {
                    "$type": "GroupElement",
                    "operatorType": 0,
                    "elements": [
                        {
                            "$type": "RemarketingElement",
                            "audienceId": "61128dfe4d506efb84ffb4b0",
                            "isIncluded": true
                        }
                    ]
                }
            ]
        },
        "banners": [
            {
                "status": "1",
                "clickUrl": "http://hybrid.ru/",
                "name": "Test",
                "content": {
                    "$type": "ImageOrFlashBanner",
                    "clickUrl": "https://hybrid.ai",
                    "name": "test",
                    "fileContent": {
                        "fileName": "test",
                        "contentType": "image/jpeg",
                        "base64Data": "……"
                    }
                }
            }
        ]
    }
}

Example 2 (ads is created in the library)

POST campaign/create
{
    "campaign": {
        "advertiserId": "58a2d2837bc72f0ba03d5103",
        "name": "Test 19.07.2021",
        "defaultClickUrl": "http://hybrid.ru/",
        "startDate": "2021-07-19T00:00:00+0300",
        "betOptimizationType": "0",
        "backtwistType": "1",
        "bet": 20,
        "multiPriceLimitations": [
            {
                "priceFormationType": "3",
                "amount": 1000
            }
        ],
        "status": "2",
        "$type": "HybridExtendedCampaign",
        "audienceGroup": {
            "$type": "GroupElement",
            "operatorType": 1,
            "elements": [
                {
                    "$type": "RemarketingElement",
                    "audienceId": "5fcf2f5f7bc72fff9c2969db",
                    "isIncluded": true
                }
            ]
        }
    },
    "banners": [
        {
            "status": "1",
            "clickUrl": "http://hybrid.ru/",
            "name": "Test",
            "adLibraryId": "5fcf2f5f7bc72fff9c296910"
        }
    ]
}

Response example:

{
    "campaign": {
        "id": "5fcf2f5f7bc72fff9c2969db",
        ....
    },
    "bannersWithContents": {
        "id": "5fcf2f5f7bc72fff9c296911",
        "adLibraryId": "5fcf2f5f7bc72fff9c296910"
    }
}

Campaign

Campaign getting (campaign/getbyid?campaignId=)

This method is required to get the actual campaign settings and status.

Request:
Url	campaign/getbyid?campaignId=	Campaign getting
Method	GET
Content-Type	application/json
Parameters	campaignId	campaign Id

Request example:

https://capi.hybrid.ai/api/campaign/getbyid?campaignId=123456789123456789123456

Response example:

{
    "campaign": {
        "advertiserId": "58a2d2837bc72f0ba03d5103",
        "name": "Test 19.07.2021",
        "defaultClickUrl": "http://hybrid.ru/",
        "startDate": "2021-07-19T00:00:00+0300",
        "betOptimizationType": "0",
        "backtwistType": "1",
        "bet": 20,
        "multiPriceLimitations": [
            {
                "priceFormationType": "3",
                "amount": 1000
            }
        ],
        "status": "2",
        "$type": "HybridExtendedCampaign",
        "audienceGroup": {
            "$type": "GroupElement",
            "operatorType": 1,
            "elements": [
                {
                    "$type":"RemarketingElement",
                    "audienceId":"5fcf2f5f7bc72fff9c2969db",
                    "isIncluded": true
                }
            ]
        },
        "banners": [
            {
                "id": "123456789123456789123456",
                "status": "1",
                "clickUrl": "http://hybrid.ru/",
                "name": "Test",
                "content": {
                    "$type": "ImageOrFlashBanner",
                    "clickUrl": "https://hybrid.ai",
                    "name": "test"
                }
            }
        ]
    }
}

Campaign

Banner moderation (bannerModeration/get?id=bannerId)

This method is required to get the banner's moderation status, as well as to get the reasons for denial of moderation. The reasons may be of a technical nature. The reasons can be described by the internal SSP code.

Banner moderation in the console for most SSPs takes place within 10-20 minutes, the following SSPs are an exception:

Google takes 6 hours on average, but it can be in process within a day.
Yandex takes 2-4 hours on average, but can be in process within a day.
AppNexus takes 2-4 hours on average, but can be in process within a day.

Request:
Url	bannerModeration/get?id=bannerId	Getting of banner moderation
Method	GET
Content-Type	application/json
Parameters	bannerId – Id banner

Response model:
Field name	Description	Data type
systemId	Id Ssp	Long
status	Status	Long OnModeration = 1, Approved = 2, Disapproved = 3, ConditionallyApproved = 4
reason	Reason (in a case a banner was rejected)	String

Request example:

GET bannerModeration/get?id=5fbf9c157bc72fe25c7b7771

Response example:

[
    {
        "systemId": 1,
        "status": 1
    }
]

Campaign

Campaign updating (campaign/update)

This method is necessary to make changes to already created campaigns. For example:

Changing the budget, banners, period, click link, audience.
To replace banners, in case of a negative result of moderation.

The fields of the method are similar to the campaign creating.

Request:
Url	campaign/update	Campaign updates
Method	POST
Content-Type	application/json

Request / response model:
Field name	Required	Description	Data type	Possible values
campaign.$type	Yes	Campaign type	String	HybridExtendedCampaign HybridMobileCampaign
campaign.onlyForMobileApp	Yes for Hybrid Mobile Campaign	Inventory for Hybrid Mobile Campaign	Bool	To create a Hybrid Extended Campaign is not used To create a Hybrid Mobile Campaign, always true
campaign.deviceTypes	Yes for Hybrid Mobile Campaign	Device types	Long[]	Mobile = 2, Tablet = 3
campaign.operatingSystems[].item.id	No	The ID of the operating system for targeting	Long	Android = 1, IOS = 2
campaign.advertiserId	Yes	Advertiser Id	String
campaign.id	Yes	Campaign Id	String
campaign.backtwistType	Yes	Budget allocation type	Long	Maximum = 0, Optimization = 1
campaign.betOptimizationType	Yes	Optimization type	Long	NoOptimization = -1, CPC = 1, CPM = 2
campaign.bet	Yes	Bet	Double	Positive number with 2 digit precision. Maximum value is 1000.
campaign.defaultClickUrl	Yes	Click url by default	String
campaign.clickUrlOption	No	Type of link setup method	Long	Individual = 1, Automated = 2
campaign.thirdPartyEventUrls[].urls	No, but yes, for Automated (2) campaign.clickUrlOption	Url the total display impression counter of third-party systems	String[]
campaign.thirdPartyEventUrls[].event	No, but yes, for Automated (2) campaign.clickUrlOption	Event type
campaign.startDate	Yes	Start date	Date
campaign.endDate	No	End date	Date
campaign.daysPlanings[].dayType	No	The type of day to show	Long	Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6, Sunday = 7, Monday - Friday = 8, All = 9
campaign.daysPlanings[].startHour	No	Start hour to show	Int
campaign.daysPlanings[].endHour	No	End hour to sho	Int
campaign.excludeGeoIds	No	Array of excluded Geo IDs	String[]
campaign.geoIds	No	Array of Id enabled geo	String[]
campaign.frequencyCaps[].event	No	Event type	Long	Impression = 1, Complete = 2, Click = 3
campaign.frequencyCaps[].count	No	Quantity	Long
campaign.frequencyCaps[].interval	No	Time interval (in hours)	Long	Maximum value is 2208 hours
campaign.frequencyCaps[].type	No	Restriction type	Long	Globally = 0, Site = 1, Place = 2
campaign.linkedSystems[].systemId	No	Ssp Id	Long
campaign.status	Yes	Campaign status	Long	Active = 1, NotActive = 2, Archive = 3
dailyMultiPriceLimitations	Yes	Budget per day	Double	Positive number with 2 digit precision. Maximum value is 100000. The priceFormationType parameter must include the budget type: Click = 0, Impression = 1, View = 2, Budget = 3
totalmultiPriceLimitations	No	Total budget	Double	Positive number with 2 digit precision. Maximum value is 100000. The total limit can be set if there is a Sumultipricelimitations, priceFormationType - must be set accordingly in the Sumultipricelimitations The priceFormationType parameter must include the budget type: Click = 0, Impression = 1, View = 2, Budget = 3
periodBudgetMultiPriceLimitations	No	Period budget	Double	Positive number with 2 digit precision. Maximum value is 100000 The budget for the period can be selected only if the Multipricelimitations is not selected and the start("StartDate") and end dates of the campaign ("EndDate") are selected The priceFormationType parameter must include the budget type: Click = 0, Impression = 1, View = 2, Budget = 3
campaign.name	Yes	Name	String	а-я,А-Я,a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols
campaign.applicationLists	No	IDs array of thematic channels (сhannels consisting of applications)	String[]	а-я,А-Я,a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols
campaign.audienceGroup.$type	Yes	Audience container type	String	GroupElement – group container
campaign.audienceGroup.operatorType	Yes	Operator type	Long	Or = 0, And = 1
campaign.audienceGroup.elements[].$type	Yes	Audience type	String	RemarketingElement
campaign.audienceGroup.elements[].isIncluded	Yes	Activate / exclude the audience	Bool
campaign.audienceGroup.elements[].audienceId	Yes	Audience Id	String
campaign.audienceGroup.elements[].overallId	Yes	Audience Id	Long	Only for campaign.audienceGroup.elements[].$type : AidataElement, AdriverElement, OnAudienceElement
campaign.audienceGroup.elements[].segmentId	Yes	Audience Id	String	Only for campaign.audienceGroup.elements[].$type : HybridSegmentElement
campaign.audienceGroup.elements[].placeId	Yes	Audience Id	Long	Only for campaign.audienceGroup.elements[].$type : PlacesElement
banners[].id	Only when responding	Banner Id	String
newBanners[].clickUrl	Yes	Click Url	String
newBanners[].name	Yes	Name	String	a-z, A-Z, ‘ ’, ‘-’ limit length is 30 symbols
newBanners[].status	Yes	Banner status	Long	1 - Active 3 - NotActive 4 - archive
newBanners[].adLibraryId	Yes, if the creation is through an existing ad	Ad Id	String
banners[].thirdPartyEventUrls[].urls	No, but yes, for Individual (1) campaign.clickUrlOption	Url the total display impression counter of third-party systems	String[]
banners[].thirdPartyEventUrls[].event	No, but yes, for Individual (1) campaign.clickUrlOption	Event type	Long	Impression = 1

Request / response model:
Field name	Description	Data type
campaign.id	campaign Id	String
bannersWithContents[].banner.id	banner Id	String
bannersWithContents[].banner.adLibraryId	Ad Id	String

Request example:

POST campaign/update
{
    "campaign": {
        "id": "58a2d2837bc72f0ba03d5104",
        "advertiserId": "58a2d2837bc72f0ba03d5103",
        "name": "Test 19.07.2021",
        "defaultClickUrl": "http://hybrid.ru/",
        "startDate": "2021-07-19T00:00:00+0300",
        "betOptimizationType": "0",
        "backtwistType": "1",
        "bet": 20,
        "dailyMultiPriceLimitations": [
            {
                "priceFormationType": "3",
                "amount": 1000
            }
        ],
        "status": "2",
        "$type": "HybridExtendedCampaign",
        "audienceGroup": {
            "$type": "GroupElement",
            "operatorType": 1,
            "elements": [
                {
                    "$type":"RemarketingElement",
                    "audienceId":"5fcf2f5f7bc72fff9c2969db",
                    "isIncluded":true
                }
            ]
        },
        "newBanners": [
            {
                "status": "1",
                "clickUrl": "http://hybrid.ru/",
                "name": "Test",
                "adLibraryId": "5fcf2f5f7bc72fff9c296910"
            }
        ]
    }
}

Response example:

{
    "campaign": {
        "id": "5fcf2f5f7bc72fff9c2969db",
        ....
    },
    "bannersWithContents": {
        "id": "5fcf2f5f7bc72fff9c296911",
        "adLibraryId": "5fcf2f5f7bc72fff9c296910",
    }
}

Campaign

Changing the status of a banner (banner/savestatus)

This method is required to change the status of banners already added to a campaign without using the campaign editing methods.

The banner ID is assigned to a banner when creating or editing a campaign.

Possible statuses and usage examples:

1 - active. Used to enable a banner in a campaign that was previously disabled for any reason.

2 - off. This status is used more often to disable banners from a campaign.
The reasons:

Banners have not been moderated
The banners were changed at the request of the client and new banners were uploaded. The old ones need to be stopped.
You need to disable one of the banner sizes.

4 - removed. Delete a banner. Not recommended to use. Due to the fact that the statistics about removed banners goes to a group "not defined".

Request:
Url	banner/savestatus
Method	POST
Content-Type	application/json

Answer (array of objects):
Field name	Description	Data type	Possible values
id	Banner ID	String
status	Status	Long	1 - active 3 - off 4 - removed

Request example:

POST banner/savestatus
[
    {
        "id": "606428ef4d506e32ac581112",
        "status": 2
    }
]

Response example:


            
                HTTP 204 No Content

Campaign

Campaign deactivating (campaign/deactivate)

This method is required to stop showing the campaign, including all banners within it. That is, using this method, all banners within the campaign are also stopped.

You can resume displaying a campaign and all banners within it using the method Campaign activating.

Request:
Url	campaign/deactivate	Campaign deactivation
Method	POST	campaign/deactivate
Content-Type	application/json
Parameters	campaignId	campaign Id

Request example:

POST campaign/deactivate
Body:
"529c829380fb961b6480f123"

Response example:

HTTP 204 No Content

Campaign

Campaign activating (campaign/activate)

This method is required to activate campaigns after they have been stopped.

Request:
Url	campaign/activate	Campaign activation
Method	POST
Content-Type	application/json
Parameters	campaignId	campaign Id

Request example:

POST campaign/activate
Body:
"529c829380fb961b6480f123"

Response example:

HTTP 204 No Content

Campaign

Campaign archiving (campaign/archive)

This method is required to archive campaigns and is typically used for campaigns that were either created by mistake or never planned to run. It is impossible to restore campaigns from the archive using the API.

Request:
Url	campaign/archive	campaign archiving
Method	POST	campaign/archive
Content-Type	application/json
Parameters	campaignId	campaign Id

Request example:

POST campaign/archive
Body:
"529c829380fb961b6480f123"

STATISTICS

Getting statistics (agencyStatistic/getSplit)

This method is required to get statistics on realized traffic.Using this method makes it possible to get statistics in a variety of breakdowns and filters. You can also get statistics for the last day. It is necessary to consider the statistics delay from the Сonsole. DSP delay under normal conditions does not exceed 20 minutes. To get statistics for a full day, we recommend requesting a report at 03:00 am the next day.

To add a filter, you need to use one of the field values "split" and add the value to it. Example:
"filters":{"4":["6131bae17bc72f375ce550f4"]}, where 4 = CampaignId in the field "split".

When getting statistics, it can be used to share with the client. The maximum period for uploading statistics is 2 months.

Request:
Url	agencyStatistic/getSplit	Getting statistics
Method	POST
Content-Type	application/json

Request model:
Field name	Description	Data type / Possible values
endDate	End date	Date
startDate	Start date	Date
fields	Requested fields	Array(long) ImpressionsCount = 2, ClicksCount = 4, PostClickConversionsCount = 6, PostViewConversionsCount = 7, Reach = 43, CTR = 58, CPM = 59, CPC = 60, TotalSum = 77
limit	Number of returned values. Маx =100	Long
page	Page (с 0)	Long
filters	Filter, a dictionary consisting of a split and plenty of possible values	Dictionary<Long, Array(String)>
split	split	Long Day = 0, Hour = 1, BannerId = 3, CampaignId = 4, AdvertiserId = 5, SspId = 17, Month = 30

Response model:
Field name	Description	Data type
items[].cTR	CTR	Double
items[].campaignId	campaign Id	String
items[].advertiserId	advertiser Id	String
items[].hour	hour	Long
items[].bannerId	banner Id	String
items[].sspId	Ssp Id	Long
items[].day	day	Date
items[].month	month	Date
items[].impressionCount	impressions	Long
items[].clickCount	clicks	Long
items[].postViewConversionsCount	Post-view conversions	Long
items[].postClickConversionsCount	Post-click conversions	Long
items[].postClickConversionsCount	Post-click conversions	Long
items[].reachs	reach	Long
items[].eCPM	CPM	Double
items[].CPC	CPC	Double
items[].TotalSum	total cost	Double

Request example:

POST agencyStatistic/getSplit
{
    "startDate": "2021-07-09T00:00:00",
    "endDate":" 2021-07-09T23:59:59",
    "sortField": 2,
    "page": 0,
    "limit": 100,
    "filters": {},
    "fields": [2,4],
    "split": "4"
}

Response example:

{
    "items": [
        {
            "splitName": "test",
            "advertiserId": "5fbf9c157bc72fe25c7b7772",
            "impressionCount": 5793,
            "clickCount": 303
        }
    ],
    "count": 1
}

Hybrid api

Getting started with the Hybrid API

Authorization

Request

Response example

Access token expiration

Request

Response example

Getting started with the Hybrid API

HTTP Codes

ADVERTISER

Creating an advertiser (advertiserEdit/create)

Request example:

Response example:

ADVERTISER

Getting an advertiser (advertiserEdit/getbyid?advertiserId={advertiserId})

Request example:

Response example:

ADVERTISER

Getting an advertiser's balance (advertisers/balance?id={advertiserId})

Request example:

Response example:

ADVERTISER

Transferring money to an advertiser (advertisers/transfertoadvertiser)

Request example:

ADVERTISER

Creating/Updating an Advertiser Order (order/(create/update))

Request example:

Response example:

ADVERTISER

Order activation/suspension/archiving (order/(activate/deactivate/archive))

Request example:

Response example:

ADVERTISER

Getting an order (order/getbyid?orderId=)

Request example:

Response example:

ADVERTISER

Return of money to the agency (advertisers/transfertoagency)

Request example:

Response example:

Advertisement

Ad folder creating (adlibraryfolder/create)

Request example:

Response example:

Advertisement

Getting the ad folder tree (adlibraryfolder/getfolderstree?ownerId=)

Request example:

Response example:

Advertisement

Ad banner creating (adlibrarybanner/create)

Request example:

Image-Banner:

Html5-Banner:

Native-Banner:

Response example (Image-banner):

Advertisement

Getting a list of ads by condition (adlibraryagency/getpage)

Request example:

Response example:

AUDIENCES

Creating an audience based on the JsActionAudience event (audience/create)

Request example:

Response example:

AUDIENCES

Test request for JS events.

AUDIENCES

Getting a list of audiences in the Console (audience/getbydatacloudid?dataCloudId=)

Request example:

Response example:

Campaign

SSP list getting (ssp/getall)

Request example:

Response example:

Campaign

Campaign creating (campaign/create)

Example:

Request example:

Example 1

Example 2 (ads is created in the library)