---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.1
alternate:
  - https://yandex.ru/dev/adfox/doc/en/v.1/format.md
  - https://yandex.ru/dev/adfox/doc/ru/v.1/format.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/adfox/doc/en/llms.txt

# API request structure

## Request structure  {#structure}

An API request consists of blocks passed in the URL:

1. [Accessing the API host and specifying the version](#reguest).
1. Authorization.
1. [Navigation block](#section-action).
1. [Parameters](#params).

Parameters are separated by the `&` (ampersand) symbol.

The parameter and its value are separated by the `=` (equals) symbol.

{% note alert %}

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

{% endnote %}

## Accessing the API host and specifying the version {#reguest}

Host for all API requests:

```no-highlight
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:

```no-highlight
https://adfox.yandex.com/api/v1
```

## Navigation block {#section-action}

One API request lets you perform one action.

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

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`: Edit 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](https://yandex.ru/dev/adfox/doc/en/v.1/account/account-auth.md), [advertiser-modify](https://yandex.ru/dev/adfox/doc/en/v.1/advertiser/advertiser-modify.md), [assistant-modify](https://yandex.ru/dev/adfox/doc/en/v.1/assistant/assistant-modify.md) methods).
    
## Parameters {#params}

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

1. `Required` — for example:

    ![](_images/params.png)
    
2. `Optional` — the parameters are specified in square brackets, for example:

    ![](_images/params_user.png)
    
    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.

{% cut "Add an ad campaign" %}

All new objects are added in the `account` context.

1. Open the [account](https://yandex.ru/dev/adfox/doc/en/v.1/account/account.md) section in the documentation menu.
1. Select the section with the action to perform — for example, “add”.
1. In the list, select the object that you want to add ([campaign](https://yandex.ru/dev/adfox/doc/en/v.1/account/account-add-campaign.md)).

![](_images/account-add-campaign.png)

The navigation block looks like this:

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

{% endcut %}

{% cut "Add a banner" %} 

All new objects are added in the `account` context.

1. Open the [account](https://yandex.ru/dev/adfox/doc/en/v.1/account/account.md) section in the documentation menu.
1. Select the section with the action to perform — for example, “add”.
1. In the list, select the object that you want to add ([banner](https://yandex.ru/dev/adfox/doc/en/v.1/account/account-add-banner.md)).

![](_images/account-add-banner.png)

The navigation block looks like this:

```
object=account&action=add&actionObject=banner
```

{% endcut %}

{% cut "Edit banner parameters" %} 

1. Open the banner section in the documentation menu, because the action is performed on an object that already exists.
1. Select the section with the action to perform — for example, editing (“modify”).
1. In the list, select the object that you want to edit ([banner](https://yandex.ru/dev/adfox/doc/en/v.1/banner/banner-modify-banner.md)).

The navigation block looks like this:

```
object=banner&action=modify&actionObject=banner
```

{% endcut %}

{% cut "Target a banner by frequency" %}

1. Open the [banner](https://yandex.ru/dev/adfox/doc/en/v.1/banner/banner.md) section in the documentation menu, because the action is performed on an object that already exists.
1. Select the section with the action to perform — for example, targeting (“target”).
1. In the list, select the object that you want to edit ([targetingFrequency](https://yandex.ru/dev/adfox/doc/en/v.1/banner/banner-target-targetingFrequency.md)).

The navigation block looks like this:

```
object=banner&action=target&actionObject=targetingFrequency
```

{% endcut %}

## Ways to pass parameters in an API request

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

{% cut "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 `&` (ampersand) symbol, and the “parameter-value” pair is separated by the `=` (equals) symbol.

Steps:

1\. Make an API request that consists of:
  
  - Host requests:
  
    ```
    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
  ```

{% endcut %}

{% cut "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' \
```

{% endcut %}

## The format for passing the “Date and time” values {#date-time}

<!-- source: en/_includes/shorts.md -->
Date format: `YYYY-MM-DD`.
<!-- endsource: en/_includes/shorts.md -->

<!-- source: en/_includes/shorts.md -->
Time format: `HH:mm`.
<!-- endsource: en/_includes/shorts.md -->

<!-- source: en/_includes/shorts.md -->
Time format with seconds: `HH:mm:ss`.
<!-- endsource: en/_includes/shorts.md -->

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

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

{% note info %}

Date and time values are separated by a space.

{% endnote %}

For example:

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

{% note info %}

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

{% endnote %}

## Encoding input parameters {#encoding}

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:

```xml
encoding=UTF-8
```

## Limits on the number of requests {#limits}

The number of requests is limited to:

- 100 requests per minute.
- 3 simultaneous requests from one account owner.