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

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.ai Content-Type: application/x-www-form-urlencoded
  1. 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.ai
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 

{
    "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

Request example: 

POST advertiserEdit/create
{
    "name":"Test advertiser",
    "defaultPixel":"5e2ad0764d506e62f85ba123",
    "contentCategory":"529c829380fb961b6480f123",
}

Response example: 

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

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 MyTargret is 2-3 hours, 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 from the MyTargret 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

Receiving 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 Sum Double

Request example: 

GET order/getbyid?orderId=1234567

Response example: 

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

Advertisement

Ad folder creating (adlibraryfolder/create)

After creating an advertiser using this method, you can create an ad folder for the advertiser. In the "Name" field, we recommend to enter a name that is identical to the advertiser's name, right up to the symbol. Creating folders is necessary in order to logically separate ads.

In response you get ID = folderId. This ID is used when creating ads.

The order in which the folders are used is usually as follows:

  1. Main folder with the advertiser's name.
  2. Folders within the main one: each folder can be used to advertise separate campaigns or periods of placement.
Example:
Hybrid api
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 example: 

POST adlibraryfolder/create
{
    "name": "Test 1",
    "parentId": "606428ef4d506e32ac581111",
    "ownerId": "5fa95ff24d506e4f14f3571d"
}

Response example: 

{
    "id": "606428ef4d506e32ac581112",
    "name": "Test 1",
    "parentId": "606428ef4d506e32ac581111",
    "ownerId": "5fa95ff24d506e4f14f3571d"
}

Advertisement

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

This method allows you to get information about all folders, including nested ones.

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

GET adlibraryfolder/getfolderstree?ownerId=5fa95ff24d506e4f14f3571d

Response example: 

[
    {
        "id": "606428ef4d506e32ac58d8e0",
        "name": "Archive",
        "adLibraryFolders": [
            {
                "id": "606428ef4d506e32ac58d8e1"
            },
            {
                "name": "Test 1"
            },
            {
                "parentId": "606428ef4d506e32ac58d8e0"
            },
            {
                "adLibraryFolders": []
            }
        ]
    },
    {
        "id": "606428ef4d506e32ac58d8e0",
        "name": "Archive",
        "adLibraryFolders": [
            {
                "id": "60c093794d506eb5e0bbc01c"
            },
            {
                "name": "Native June"
            },
            {
                "parentId": null
            },
            {
                "adLibraryFolders": []
            }
        ]
    }
]

Advertisement

Ad banner creating (adlibrarybanner/create)

This method creates banners (native, HTML5, image) with an array of objects.

Banner sizes (Pictures):

  • 300x250
  • 728x90
  • 320x50
  • 336x280
  • 240x400
  • 320x100
  • 640x480
  • 160x600
  • 970x250
  • 300x50
  • 640x360
  • 300x100
  • 970x90
  • 600x340
  • 120x600
  • 333x250
  • 250x250
  • 468x60
  • 300x168
  • 300x300

Banner sizes (HTML5):

  • 240x400 suitable for MyTarget and Console
  • 300x250
  • 728x90
  • 320x50
  • 336x280
  • 320x100
  • 640x480
  • 160x600
  • 970x250
  • 300x50
  • 640x360
  • 300x100
  • 970x90
  • 600x340
  • 120x600
  • 333x250
  • 250x250
  • 468x60
  • 300x168

Banner must be archived in ZIP format.


Banner sizes (for Native):

  • 256x256 - logo
  • 600x600 - main size
  • 1200x628 - main size
  • 800x600 - additional size
  • 1200x800 - additional size
  • 1280x720 - additional size

Additional (mandatory) fields for a native banner:

  • Company name (Length: up to 30 characters)
  • Button text (Length: up to 15 characters)
  • Ad text (Length: up to 70 characters)
  • Ad title (Length: up to 25 characters)

More information can be found on the page. Ad Requirements

Pay attention to the parameters that are used for the request. Depending on the type of ad, the parameters change.

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

POST adlibrarybanner/create

Image-Banner: 

[
    {
        "$type": "ImageOrFlashBanner",
        "width": 600,
        "height": 600,
        "altText": "alt text",
        "name": "websiteplanet-dummy-600X600",
        "fileContent": {
            "contentType": "image/jpeg",
            "base64Data": "...",
            "fileName": "websiteplanet-dummy-600X600.jpeg"
        }
    }
]

Html5-Banner: 

[
    {
        "$type": "Html5Banner",
        "width": 200,
        "height": 300,
        "name": "lays_ii",
        "altText": "test",
        "archive": {
            "contentType": "application/x-zip-compressed",
            "base64Data": "...",
            "fileName": "lays_ii.zip"
        }
    }
]

Native-Banner: 

[
    {
        "$type": "NativeBanner",
        "clickUrl": "https://hybrid.ai",
        "name": "websiteplanet-dummy-1200X628.jpeg",
        "title": "Title",
        "companyName": "Brand",
        "altImages": [
            {
                "content": {
                    "contentType": "image/jpeg",
                    "base64Data": "...",
                    "fileName": "websiteplanet-dummy-800X600.jpeg"
                },
                "height": 600,
                "width": 800
            },
            {
                "content": {
                    "contentType": "image/jpeg",
                    "base64Data": "...",
                    "fileName": "websiteplanet-dummy-1200X800.jpeg"
                },
                "height": 800,
                "width": 1200
            },
            {
                "content": {
                    "contentType": "image/jpeg",
                    "base64Data": "...",
                    "fileName": "websiteplanet-dummy-1280X720.jpeg"
                },
                "height": 720,
                "width": 1280
            }
        ],

        "buttonText": "detailed",
        "logoContent": {
            "contentType": "image/png",
            "base64Data": "...",
            "fileName": "websiteplanet-dummy-256X256.jpeg"
        },
        "fileContent": {
            "contentType": "image/png",
            "base64Data": "...",
            "fileName": "websiteplanet-dummy-1200X628.jpeg"
        },
        "iconImageContent": {
            "contentType": "image/png",
            "base64Data": "...",
            "fileName": "websiteplanet-dummy-600X600.jpeg"
        }
    }
]

Response example (Image-banner): 

[
    {
        "isValid": true,
        "content": {
            "$type": "ImageOrFlashBanner",
            "folderId": "614285e97bc72f1160ed3468",
            "id": "61428b0f4d506e47c888de5c"
        }
    }
]

Advertisement

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

Using this method, you can get the number of banners, their type and ID within a specific folder.

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

Request example: 

POST adlibraryagency/getpage
{
    "folderId": null,
    "condition": {
        "limit": 50,
        "page": 0
    }
}

Response example: 

{
    "banners": {
        "count": 1,
        "items": [
            {
                "$type": "ImageOrFlashBanner",
                "id": "6141ebc87bc72fff8ce9b454",
                "adLibrary": "6141ebc87bc72fff8ce9b455"
            }
        ]
    }
}

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 5fac17f24d506ef09c000b81 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": "61128dfe4d506efb84ffb4b0",
                    "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.

Note that MyTarget does not transmit some information, including the sites where banners are displayed. Thus, when using macros, UTM tags may not be defined in Google Analytics and Yandex.Metrica from MyTarget traffic.

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 –
OdnoklassnikiCampaign - MyTarget
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.geoTargetMail No Active geos Id 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, only for HybridExtendedCampaign Ssp Id Long
campaign.status Yes Campaign status Long Active = 1,
NotActive = 2,
Archive = 3
campaign.multiPriceLimitations[].priceFormationType Yes Budget type Long Click = 0,
Impression = 1,
View = 2,
Budget = 3
campaign.multiPriceLimitations[].amount Yes Budget per day Double Positive number with 2 digit precision.
Maximum value is 100000
campaign.multiPriceLimitations[].totalAmount No Total budget Double Positive number with 2 digit precision.
Maximum value is 100000
campaign.name Yes Name String а-я,А-Я,a-z, A-Z, ‘ ’, ‘-’
limit length is 30 symbols
campaign.audienceGroup.$type Yes, only for HybridExtendedCampaign Audience container type String GroupElement – group container
campaign.audienceGroup.operatorType Yes, only for HybridExtendedCampaign Operator type Long Or = 0,
And = 1
campaign.audienceGroup.elements[].$type Yes, only for HybridExtendedCampaign Audience type String Audience based on cid - RemarketingElement
campaign.audienceGroup.elements[].isIncluded Yes, only for HybridExtendedCampaign Activate / exclude the audience Bool
campaign.audienceGroup.elements[].audienceId Yes, only for HybridExtendedCampaign Audience Id String
campaign.mtAudiences[].id Yes, only for OdnoklassinikiCampaign Audience Id String
campaign.mtAudiences[].isIncluded Yes, only for OdnoklassinikiCampaign Audience inclusion indicator, always "true" Bool
campaign.bannerType Yes, only for OdnoklassinikiCampaign Banner type in MyTarge Long 7 - archive
8 - native banner
campaign.packageId Yes, only for OdnoklassinikiCampaign Campaign type in MyTarget Long 1479 - CPC Html5
2268 - CPC Native
campaign.bidding Yes, only for OdnoklassinikiCampaign Auction strategy in MyTarget Long 0 - fixed bet
1 - Minimum costs
2 - Maximum number of clicks or impressions
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.altText No Alternative text (required only for Yandex SSP) 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
            }
        ],
        "multiPriceLimitations": [
            {
                "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 necessary to obtain the status of banner moderation, as well as to obtain the reasons for refusal of moderation. The reasons for the failure may be of a technical nature, as well as described by the internal SSP code. To check the moderation of myTarget banners, you need to request the status of only SSP with ID 30.

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

  • Google takes an average of 6 hours, but can last up to a day.
  • Yandex takes 2-4 hours on average, but it can last up to a day.
  • AppNexus takes 2-4 hours on average, but can last up to a day.

We also place ads on the myTarget platform, moderation in it takes 2-4 hours on average, but can last up to a day.

Request:
Url bannerModeration/get?id=bannerId Getting of banner moderation
Method GET
Content-Type application/json
Parameters campaignId 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 –
Odnoklassniki - MyTarget
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.startDate Yes Start date Date
campaign.endDate No End date Date
campaign.excludeGeoIds No Array of excluded Geo IDs String[]
campaign.geoIds No Array of Id enabled geo String[]
campaign.geoTargetMail 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
campaign.multiPriceLimitations[].priceFormationType Yes Budget type Long Click = 0,
Impression = 1,
View = 2,
Budget = 3
campaign.multiPriceLimitations[].amount Yes Budget per day Double Positive number with 2 digit precision.
Maximum value is 100000.
campaign.multiPriceLimitations[].totalAmount Yes Total budget Double Positive number with 2 digit precision. Maximum value is 100000.
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
campaign.mtAudiences[].id Yes, only for OdnoklassinikiCampaign Audience Id String
campaign.mtAudiences[].isIncluded Yes, only for OdnoklassinikiCampaign Audience inclusion indicator, always true Bool
campaign.bannerType Yes, only for OdnoklassinikiCampaign Banner type in MyTarget Long 7 - archive 8 - native banner
campaign.packageId Yes, only for OdnoklassinikiCampaign Campaign type in MyTarget Long 1479 - CPC Html5 2268 - CPC Native
campaign.bidding Yes, only for OdnoklassinikiCampaign Auction strategy in MyTarget Long 0 - fixed bet 1 - Minimum costs 2 - Maximum number of clicks or impressions
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
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,
        "multiPriceLimitations": [
            {
                "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/activate
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/activate
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 and MyTarget. DSP delay under normal conditions does not exceed 20 minutes. MyTarget delay under normal conditions does not exceed 3 hours. That’s why it is desirable to make requests with a delay of 3 hours. Thus, to get statistics for a full day, you need to make a request 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
}

29 June 2pm IST

speakers

Webinar online

Skyrocket your campaign performance with VOX - AI Vision Platform

registration