campaign

Get a list of campaigns.

Request format

Note

Pagination available.

https://adfox.yandex.com/api/v1
  ? object=account
  & action=list
  & actionObject=campaign
  & [actionObjectID=<integer>]
  & [superCampaignID=<integer>]
  & [dateAddedFrom=<YYYY-MM-DD>]
  & [dateAddedTo=<YYYY-MM-DD>]
  & [show=<string>]
  & [search=<string>]
  & [criteriaID=<integer>]
  & [showMode=<string>]

actionObjectID

To get data for only one campaign, specify its ID.

Default value: 0 (display the list of all campaigns).

superCampaignID

Filter by super campaign ID.

dateAddedFrom

Data filtering: show campaigns created after the specified date.

Date format: YYYY-MM-DD.

dateAddedTo

Data filtering: show campaigns created before the specified date.

Date format: YYYY-MM-DD.

show

This parameter is used to specify the degree of data completeness in the list of campaigns and to display the targeting settings of a certain campaign.

Configuring data completeness in the list of campaigns:

Acceptable values:

  • advanced (full display format).

  • common (brief display format):

    • ID.
    • name.

  • short (limited display format):

    • ID.
    • name.
    • superCampaignID.
    • status.
    • dateStart.
    • dateEnd.
    • dateFinished.

Default value: advanced.

Configuring the display of targeting settings of a certain campaign:

Required parameter: actionObjectID.

Forbidden: dateAddedFrom, dateAddedTo, and search.

Acceptable values:

  • targetingTime: Targeting by time.
  • targetingFrequency: Targeting by frequency.
  • targetingBehavior: Targeting by behavior.
  • targetingGeobase: Targeting by geography.
  • targetingSearch: Targeting by search queries.
  • targetingGender: Targeting by gender.
  • targetingAge: Targeting by age.
  • targetingRevenue: Targeting by income.
  • targetingUser: Additional targeting. Additional parameters: criteriaID and showMode.

search

Filtering by substring in a super campaign name.

An entry can contain Russian and Latin letters, numbers, and any special characters.

criteriaID

Only required for getting data on custom targeting (show=targetingUser).

User characteristic ID.

Acceptable values: from 1 to 63.

showMode

Only used for getting data on custom targeting (show=targetingUser).

You can use it to display the list of allowed and/or prohibited values of a specified user characteristic in the ad campaign.

Acceptable values:

  • denied: Only show prohibited values.

  • allowed: Only show allowed values.

  • all: Show all values with a breakdown into allowed and prohibited ones.

Default value: denied.

* Required

Response format

<response>
<status>
  <code>{integer}</code>
</status>
<result>
<data>
  <row0>
    <ID>{integer}</ID>
    <name>{string}</name>
    <superCampaignID>{integer}</superCampaignID>
    <superCampaignName>{string}</superCampaignName>
    <advertiserID>{integer}</advertiserID>
    <advertiserAccount>{string}</advertiserAccount>
    <assistantID>{integer}</assistantID>
    <assistantAccount>{string}</assistantAccount>
    <additionalAdvertiserIDs>{integer}</additionalAdvertiserIDs>
    <additionalAdvertiserAccounts>{string}</additionalAdvertiserAccounts>
    <additionalAssistantIDs>{integer}</additionalAssistantIDs>
    <additionalAssistantAccounts>{string}</additionalAssistantAccounts>
    <status>{integer}</status>
    <level>{integer}</level>
    <sequence>{integer}</sequence>
    <priority>{integer}</priority>
    <type>{integer}</type>
    <tracingPointsType>{integer}</tracingPointsType>
    <targetingProfileID>{integer}</targetingProfileID>
    <isSession>{integer}</isSession>
    <outerMarkID>{integer}</outerMarkID>
    <bannerSequence>{integer}</bannerSequence>
    <scenarioPeriodID>{integer}</scenarioPeriodID>
    <impressionsMethodID>{integer}</impressionsMethodID>
    <impressionsSmoothTypeID>{integer}</impressionsSmoothTypeID>
    <clicksSmoothTypeID>{integer}</clicksSmoothTypeID>
    <isTrafficSmooth>{integer}</isTrafficSmooth>
    <maxImpressions>{integer}</maxImpressions>
    <maxClicks>{integer}</maxClicks>
    <impressionsAll>{integer}</impressionsAll>
    <clicksAll>{integer}</clicksAll>
    <impressionsToday>{integer}</impressionsToday>
    <clicksToday>{integer}</clicksToday>
    <maxImpressionsPerDay>{integer}</maxImpressionsPerDay>
    <maxClicksPerDay>{integer}</maxClicksPerDay>
    <maxImpressionsPerHour>{integer}</maxImpressionsPerHour>
    <maxClicksPerHour>{integer}</maxClicksPerHour>
    <impressionsPerHour>{integer}</impressionsPerHour>
    <clicksPerHour>{integer}</clicksPerHour>
    <mainPointID>{integer}</mainPointID>
    <dateStart>{date}</dateStart>
    <dateEnd>{date}</dateEnd>
    <dateFinished>{date}</dateFinished>
    <dateAdded>{date}</dateAdded>
    <common_profile_id>{integer}</common_profile_id>
    <costType>{integer}</costType>
    <sendToErir>{integer}</sendToErir>
      <contractID>{integer}</contractID>
      <okveds>
        <row0>{string}</row0>
        <row1>{string}</row1>
      </okveds>
      <markingAdvertiserInfo>{string}</markingAdvertiserInfo>
  </row0>  
</data>
</result>
</response>

Response parameters

code

Request processing status. If the value is 0, the request was completed successfully. For the key, see Error handling.

rows

Number of items in the response tree.

rowN

Item number in the response tree, where N is a number from 0 to rows-1 (where rows is the total number of items in the response).

ID

Unique ID of the campaign.

name

Campaign name.

superCampaignID

ID of the super campaign that the campaign belongs to.

superCampaignName

Name of the super campaign that the campaign belongs to.

advertiserID

Advertiser ID.

advertiserAccount

Advertiser's account.

assistantID

ID of the assistant that the campaign is assigned to.

assistantAccount

Account of the assistant that the campaign is assigned to.

additionalAdvertiserIDs

IDs of additional advertisers.

additionalAdvertiserAccounts

Accounts of additional advertisers.

additionalAssistantIDs

IDs of additional assistants.

additionalAssistantAccounts

Accounts of additional assistants.

level

Campaign level.

priority

Campaign priority.

status

Status.

Acceptable values:

  • 0: Active.
  • 1: Paused.
  • 2: Completed.

sequence

Group.

type

Campaign type. Deprecated parameter.

Acceptable values:

  • 0: Simplified.
  • 1: Standard.

tracingPointsType

Action tracking.

Acceptable values:

  • 0: None.
  • 1: postClick.
  • 2: postView & postClick.
  • 3: postView.

targetingProfileID

Targeting profile ID.

isSession

Session impressions.

Acceptable values:

  • 0: Disabled.
  • 1: Enabled.

outerMarkID

Automatic tag substitution for click links is enabled.

Acceptable values:

  • 0: Disabled.
  • 1: Openstat.ru.
  • 2: Google Analytics.

bannerSequence

Banner impression sequence. Deprecated parameter.

Acceptable values:

  • 0: by priority. Banners are selected based on their priority.
  • 1: Sequential (the “Scenario period” (scenarioPeriodID) parameter is required). A script (scenario) indicates the banner number and how many times it's served to the user.

scenarioPeriodID

The scenario period determines the frequency of repeated banner impressions in this ad campaign for a unique user. Deprecated parameter.

Required if banners are selected sequentially (bannerSequence=1).

Acceptable values:

  • 0: A one-time sequence.
  • 1: One hour.
  • 2: Four hours.
  • 3: Six hours.
  • 4: 12 hours.
  • 5: One day.
  • 6: One week.
  • 7: One month.
  • 11: A looping sequence.

impressionsMethodID

Impression count method.

Acceptable values:

  • 0: Banner ad response. An impression is counted when the banner code is uploaded to the site page.
  • 101≤N≤130, where N is the event sequence number from 1 to 30 (101 corresponds to event 1, 105 corresponds to event 5, and so on). An impression is counted when the event with the specified number is called by the banner on the website page.
  • 1101: Viewable impression, Yandex (IMS). An impression is only counted if at least 50% of the banner area is in the active browser window for at least two seconds.
  • 2101: Impression (IMS). An impression event that occurs when ad rendering begins.
  • 2102: Viewable impression (IMS). Impressions in the viewable area of the window in the active browser tab, counted according to the criteria established by international media industry standards (minimum percentage of pixels in the viewable area and display time in the viewable browser area).

impressionsSmoothTypeID

Impression running speed.

Acceptable values:

  • 0: As fast as possible. Campaign banners are served at the maximum possible speed until the impression limits are reached (if specified). The maximum running speed doesn't require that you specify any limits and start/end dates of the campaign.
  • 1: Spread evenly throughout the day. Impressions are uniformly distributed throughout the day. Make sure to specify the maximum number of impressions per day (maxImpressionsPerDay).
  • 2: Spread evenly throughout the entire period. The campaign impressions are distributed evenly over the entire period based on account statistics. Make sure to specify the maximum number of impressions (maxImpressions) and the campaign end date (dateEnd).
  • 3: Spread evenly throughout the entire period (automatic prolongation). The campaign impressions are distributed evenly over the entire period based on account statistics. If the campaign doesn't reach the impression limit in the allocated time, it's automatically extended for one day and runs at the maximum speed on that day. Make sure to specify the maximum number of impressions (maxImpressions) and the campaign end date (dateEnd).

clicksSmoothTypeID

Click delivery speed.

Acceptable values:

  • 0: As fast as possible. Campaign banners are served at the maximum possible speed until the click limits are reached (if specified). The maximum running speed doesn't require that you specify any limits and start/end dates of the campaign.
  • 1: Spread evenly throughout the day. Clicks are uniformly distributed throughout the day. Make sure to specify the maximum number of clicks per day (maxClicksPerDay).
  • 2: Spread evenly throughout the entire period. The campaign clicks are distributed evenly over the entire period based on account statistics. Make sure to specify the maximum number of clicks (maxClicks) and the campaign end date (dateEnd).
  • 3: Spread evenly throughout the entire period (automatic prolongation). The campaign clicks are distributed evenly over the entire period based on account statistics. If the campaign doesn't reach the click limit in the allocated time, it's automatically extended for one day and runs at the maximum speed on that day. Make sure to specify the maximum number of clicks (maxClicks) and the campaign end date (dateEnd).

maxImpressions

Maximum number of impressions.

impressionsAll

Tag information. Total number of impressions.

maxImpressionsPerDay

Maximum number of impressions per day.

impressionsToday

Tag information. Number of impressions on the current day.

maxImpressionsPerHour

Maximum number of impressions per hour.

impressionsPerHour

Tag information. Number of impressions in the current hour.

maxClicks

Maximum total number of clicks.

clicksAll

Tag information. Total number of clicks.

maxClicksPerDay

Maximum number of clicks per day.

clicksToday

Tag information. Number of clicks on the current day.

maxClicksPerHour

Maximum number of clicks per hour.

clicksPerHour

Tag information. Number of clicks in the current hour.

dateStart

Delivery start date.

dateEnd

Delivery end date.

dateFinished

Delivery completion date.

dateAdded

Add date.

common_profile_id

General profile ID for show=advanced.

costType

Campaign type.

Acceptable values:

  • 0: Other.
  • 1: CPM.
  • 2: CPC.
  • 3: CPA.

sendToErir

Submit data to the Russian state register.

Acceptable values:

  • 0: Don't submit data to the Russian state register.
  • 1: Submit data to the Russian state register (ad register is enabled).

contractID

Contract identifier. This parameter is required if sendToErir=1. Learn more about getting a list of contracts.

okveds

OKVED code of the advertised product.

markingAdvertiserInfo

Information about the advertiser in the banner menu.

Sample request and response

Request:

https://adfox.yandex.com/api/v1?object=account&action=list&actionObject=campaign

Response:

<response>
<status>
  <code>0</code>
</status>
<result>
<data>
  <row0>
    <ID>474205</ID>
    <name>example</name>
    <superCampaignID/>
    <superCampaignName/>
    <advertiserID>226201</advertiserID>
    <advertiserAccount>ivanov</advertiserAccount>
    <assistantID>239097</assistantID>
    <assistantAccount>petrov</assistantAccount>
    <additionalAdvertiserIDs/>
    <additionalAdvertiserAccounts/>
    <additionalAssistantIDs/>
    <additionalAssistantAccounts/>
    <status>0</status>
    <level>1</level>
    <sequence>1</sequence>
    <priority>100</priority>
    <type>1</type>
    <tracingPointsType>0</tracingPointsType>
    <targetingProfileID>0</targetingProfileID>
    <isSession>0</isSession>
    <outerMarkID>0</outerMarkID>
    <bannerSequence>0</bannerSequence>
    <scenarioPeriodID>0</scenarioPeriodID>
    <impressionsMethodID>0</impressionsMethodID>
    <impressionsSmoothTypeID>0</impressionsSmoothTypeID>
    <clicksSmoothTypeID>0</clicksSmoothTypeID>
    <isTrafficSmooth>0</isTrafficSmooth>
    <maxImpressions>0</maxImpressions>
    <maxClicks>0</maxClicks>
    <impressionsAll>0</impressionsAll>
    <clicksAll>0</clicksAll>
    <impressionsToday>0</impressionsToday>
    <clicksToday>0</clicksToday>
    <maxImpressionsPerDay>0</maxImpressionsPerDay>
    <maxClicksPerDay>0</maxClicksPerDay>
    <maxImpressionsPerHour>0</maxImpressionsPerHour>
    <maxClicksPerHour>0</maxClicksPerHour>
    <impressionsPerHour>0</impressionsPerHour>
    <clicksPerHour>0</clicksPerHour>
    <mainPointID>0</mainPointID>
    <dateStart>2021-05-18 13:00:00</dateStart>
    <dateEnd/>
    <dateFinished>0000-00-00 00:00:00</dateFinished>
    <dateAdded>2021-05-18</dateAdded>
    <common_profile_id>525</common_profile_id>
    <costType>1</costType>
    <sendToErir>1</sendToErir>
    <contractID>139</contractID>
    <okveds></okveds>
    <markingAdvertiserInfo>OOO Romashka OGRN 1231231</markingAdvertiserInfo>
  </row0>
</data>
</result>
</response>

Other actions with the object

See more actions with the campaign object:

Previous
bannerType
Next
category
In this article: