API request structure

Request structure

An API request consists of blocks passed in the URL:

  1. Accessing the API host and specifying the version.

  2. Authorization.

  3. Navigation block.

  4. Parameters.

Parameters are separated by the & symbol.

The parameter and its value are separated by the = symbol.

Alert

The Adfox API is case-sensitive. All object names must be passed using uppercase and lowercase letters, as specified in the document.

Accessing the API host and specifying the version

Host for all API requests:

https://adfox.yandex.com/api/vX

Where X is the version number starting from 1 (the v0 version isn't supported).

For example, this is a request to the API version 1:

https://adfox.yandex.com/api/v1

Navigation block

One API request lets you perform one action.

In the request, you need to pass information about the context and the action that must be performed on the object.

The navigation block with parameters is responsible for this information:

  1. object: The context in which the action is performed.

  2. action: The action that's performed on the object. A set of possible actions is defined for every context. Examples of actions:

    • add: Add an object (available only in the account context).
    • list: Get a list.
    • modify: Modify an object.
    • update: Change object parameters.
    • delete: Delete an object (available only in the account context).

  3. actionObject: The name of the object that the action is performed on. actionObject may be absent in some objects (for example, in the account-auth, advertiser-modify, and assistant-modify methods).

Parameters

The last block in the API request includes the parameters of the method that's called:

  1. Required — for example:

  2. Optional — the parameters are specified in square brackets, for example:

    If a parameter isn't passed in the request, the API uses its default value. For default values, see the page for a specific actionObject.


Search for a method in the documentation

In the document, the API method descriptions are grouped by the contexts in which they're performed and then by action types. To find the necessary method, you need to build a context–action–object chain, analogous to the navigation block of the request. Here are a few examples.

Add a campaign

All new objects are added in the account context.

Open the account section in the documentation menu.

Next, select the section with the action to perform (add).

In the list, select the object that you want to add (campaign).

The navigation block looks like this:

object=account&action=add&actionObject=campaign
Add a banner

All new objects are added in the account context.

Open the account section in the documentation menu.

Next, select the section with the action to perform (add).

In the list, select the object that you want to add (banner).

The navigation block looks like this:

object=account&action=add&actionObject=banner
Modify banner parameters

Open the banner section in the documentation menu (because the action is performed on an object that already exists).

Next, select the section with the action to be performed (modify).

In the list, select the object that you want to modify (banner).

The navigation block looks like this:

object=banner&action=modify&actionObject=banner
Target a banner by frequency

Open the banner section in the documentation menu (because the action is performed on an object that already exists).

Next, select the section with the action to perform (target).

In the list, select the object that you want to modify (targetingFrequency).

The navigation block looks like this:

object=banner&action=target&actionObject=targetingFrequency

Ways to pass parameters in an API request

There are two ways you can pass a navigation block and a request parameters block:

The request parameters are passed in the URL (GET)

In this case, all parameters are passed directly to the URL of the API request. The parameters are separated by the & symbol, and the “parameter-value” pair is separated by the = symbol.

Steps:

1. Make an API request that consists of:

  • A host request.

    https://adfox.yandex.com/api/v1?

  • A navigation block:

    object=account&action=add&actionObject=campaign&

  • Request parameters (the required and, if necessary, optional ones):

    name=Adfox_company&advertiser=427&status=1&level=5

2. Here's the result:

https://adfox.yandex.com/api/v1?object=account&action=add&actionObject=campaign&name=Adfox_company&advertiser=427&status=1&level=5
The request parameters are passed to the body (POST)

In this case, the request is based on the host request:

https://adfox.yandex.com/api/v1

And the request parameters in body:

--form 'object=account' \
--form 'action=list' \
--form 'actionObject=website' \

Sample POST request:

curl -k --location --request POST 'https://adfox.yandex.com/api/v1' \
--header 'Authorization: OAuth 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037' \
--form 'object=account' \
--form 'action=list' \
--form 'actionObject=website' \

The format for passing the “Date and time” values

Date format: YYYY-MM-DD

Time format: HH:mm.

Time format with seconds: HH:mm:ss.

Date and time format: YYYY-MM-DD HH:mm, where:

  • YYYY: Year.
  • MM: Month.
  • DD: Day.
  • HH: Hour.
  • mm: Minute.

Note

Date and time values are separated by a space.

For example:

dateStart=2022-04-25 11:00&action=…

Note

For date/time parameters, time is an optional value. by default, it's set to 00:00.

Encoding input parameters

If Cyrillic characters are passed in the API request, you need to specify the encoding of the input parameters in the encoding parameter.

Acceptable values:

  • UTF-8 (recommended).
  • CP-1251.

For example:

encoding=UTF-8

Limits on the number of requests

The number of requests is limited to:

  • 100 requests per minute.
  • 3 simultaneous requests from one account owner.
Previous
Authorization
Next
Quick start