AdGroups

/api/v2/ad_groups.json

A resource that allows you to create a new ad group or retrieve a list of existing ad groups.

Used object: AdGroup

GET

Retrieving a list of ad groups

Request example

    GET /api/v2/ad_groups.json

Response example

    {
        "count": 3,
        "offset": 0,
        "items": [
            {
                "package_id": 83,
                "last_updated": "2022-07-04 17:36:16",
                "id": 6617841,
                "name": "New ad group 2022-07-15 17:53"
            },
            {
                "package_id": 83,
                "last_updated": "2022-07-04 17:36:16",
                "id": 6711647,
                "name": "New ad group 2022-08-16 19:49"
            },
            {
                "package_id": 83,
                "last_updated": "2022-07-04 17:36:16",
                "id": 6711665,
                "name": "New ad group 2022-08-16 19:51"
            }
        ]
    }

Available fields are described in AdGroup.

The resource supports pagination using the limit and offset parameters.

• limit — number of groups in the response. Default: 20

    /api/v2/ad_groups.json?limit=10

• offset — shift by N groups from the beginning of the current selection

    /api/v2/ad_groups.json?limit=5&offset=15

Filters

• _id — group ID

    /api/v2/ad_groups.json?_id=6617841
    /api/v2/ad_groups.json?_id__in=6617841,6711647

• _status — group status. Available statuses: "active", "blocked", "deleted"

    /api/v2/ad_groups.json?_status=active
    /api/v2/ad_groups.json?_status__ne=active
    /api/v2/ad_groups.json?_status__in=active,blocked

• _last_updated — datetime of the last update of the group together with banners. Available lookups: "lt" (less than), "lte" (less than or equal), "gt" (greater than), "gte" (greater than or equal)

    /api/v2/ad_groups.json?_last_updated__gt=2022-01-01 00:00:00
    /api/v2/ad_groups.json?_last_updated__gte=2022-01-01 00:00:00
    /api/v2/ad_groups.json?_last_updated__lt=2022-01-01 00:00:00
    /api/v2/ad_groups.json?_last_updated__lte=2022-01-01 00:00:00

Sorting

• id

    /api/v2/ad_groups.json?sorting=id - ascending
    /api/v2/ad_groups.json?sorting=-id - descending

• name

    /api/v2/ad_groups.json?sorting=name - ascending
    /api/v2/ad_groups.json?sorting=-name - descending

• status

    /api/v2/ad_groups.json?sorting=status - ascending
    /api/v2/ad_groups.json?sorting=-status - descending

• by multiple fields

    /api/v2/ad_groups.json?sorting=status,name,-id

POST

Creating an ad group

Request example:

    POST /api/v2/ad_groups.json
    {
        "name": "My new group",
        "status": "active",
        "date_start": "2022-04-01 00:00:00",
        "date_end": "2022-04-15 00:00:00",
        "autobidding_mode": "second_price",
        "budget_limit_day": "1000",
        "budget_limit": "5000",
        "mixing": "fastest",
        "price": "642.12",
        "age_restrictions": "18+",
        "banner_uniq_shows_limit": 2130,
        "uniq_shows_period": "week",
        "uniq_shows_limit": 100,
        "audit_viewability": "moat",
        "enable_utm": "False",
        "package_id": 449,
        "objective": "playersengagement",
        "banners": [{
            "content": {
                "primary": {
                    "id": 32433493
                }
            },
            "urls": {
                "primary": {
                    "id": 98574325
                }
            },
            "textblocks": {
                "primary": {
                    "title": "Everyone needs this product!",
                    "text": "All you need for happiness is..."
                }
            }
        }, {
            "content": {
                "primary": {
                    "id": 32433494
                }
            },
            "urls": {
                "primary": {
                    "id": 98574325
                }
            },
            "textblocks": {
                "primary": {
                    "title": "Buy me!",
                    "text": "Buy right now"
                }
            }
        }],
        "targetings": {
            "age": {
                "age_list": [21, 22, 23]
            },
            "birthday": {
                "days_after": 5,
                "days_before": 10
            },
            "fulltime": {
                "mon": [1],
                "tue": [1, 2],
                "wed": [1, 2, 3],
                "thu": [1, 2, 3, 4],
                "fri": [1, 2, 3, 4, 5],
                "sat": [1, 2, 3, 4, 5, 6],
                "sun": [1, 2, 3, 4, 5, 6, 7],
                "flags": [],
            },
            "pads": [5206],
            "sex": ["male"],
            "interests": [9018,7356],
            "interests_soc_dem": [7653,7655]
        }
    }

Response example:

    HTTP 200
    {
        "id": 9826424,
        "banners": [{
            "id": 23826937
        }]
    }

The response always contains the id and banners fields (if the group is created with banners).
Important: banners is not supported in fields and will return an error.

Available fields, targetings, and other ad group settings are described in the Package object within which the group is created.

A group can be created with one of the following statuses: active, blocked, deleted.
If the status is not provided, the active status is set.

Possible response codes

• 200/204 — group saved
• 400 — validation error

Possible error codes:

• invalid_package — the package is not available to this user
• can_not_set — cannot switch to the specified package
• step — invalid step when setting budget_limit. The change must be a multiple of budget_limit_step from the /api/v2/currencies.json API for the user’s currency
• not_allowed_for_package — changes are not available in this package
• pricelist_not_found — no pricelist was found for the provided pricelist_id
• permission_required — insufficient permissions to modify the field
• audit_pixel_invalid_roles — invalid audit pixel roles
• audit_pixel_max_count — audit pixel count limit exceeded
• audit_pixel_must_be_unique — audit pixels must be unique
• audit_pixel_invalid_urls — audit pixel has an invalid URL
• min_translation_hours — minimum broadcast time in fulltime targeting must be at least 8 hours
• required — field is required
• max_value — value is greater than the maximum
• min_value — value is less than the minimum
• bad_value — invalid value format or type
• bad_items — the list contains invalid values
• read_only_field — read-only field
• duplicate_value — duplicate values
• required_value — required values are expected
• required_one_of_value — one of the required values is expected
• unallowed_value — value is not in the list of allowed values
• unallowed_field — field is not allowed

In general, an error message has the following format:

    {
        "error": {
            "fields": {
                "<field_name_1\>": {
                    "message": "<error_message_1\>",
                    "code": "<error_code_1\>"
                },
                "<field_name_2\>": {
                    "message": "<error_message_2\>",
                    "code": "<error_code_2\>"
                }
            },
            "message": "Validation failed",
            "code": "validation_failed"
        }
    }

where field_name_N is the name of the field where the error occurred, error_message_N is the error description, and error_code_N is the error code.

Example:

    {
        "error": {
            "fields": {
                "audit_pixels": {
                    "message": "Error validating audit pixels urls",
                    "code": "audit_pixel_invalid_urls"
                }
            },
            "message": "Validation failed",
            "code": "validation_failed"
        }
    }

Examples of specifying targetings when creating/editing groups

• age:

    {
        "age": {
            "age_list": [0, 12, 13, 14, 22, 23, 24]
        }
    }

• birthday:

    {
        "birthday": {
            "days_after": 5,
            "days_before": 10
        }
    }

• browser:

    {
        "browser": ["edge", "internet_explorer", "opera"]
    }

• fulltime:

    {
        "fulltime": {
            "tue": [2],
            "wed": [2, 3],
            "thu": [2, 3, 4],
            "fri": [2, 3, 4, 5],
            "sat": [2, 3, 4, 5, 6],
            "sun": [2, 3, 4, 5, 6, 7],
            "flags": ["use_holidays_moving", "cross_timezone"],
    }

• geo:

    {
        "geo": {
            "regions": [56, 97, 100]
        }
    }

or

    {
        "geo": {
            "local_geo": {
                "visit_type": "usual",
                "loc_type": ["home", "work"],
                "locations": [{
                    "lat": 55.75583,
                    "lng": 37.6173,
                    "radius": 3000,
                    "label": "Moscow city center",
                    "address": "Exact address"
                }]
            }
        }
    }

You cannot pass local_geo and regions in geo at the same time.

Example of incorrect geo payload:

    {
        "regions": [56, 97, 100],
        "local_geo": {
            "visit_type": "usual",
            "loc_type": ["home", "work"],
            "locations": [{
                "lat": 55.75583,
                "lng": 37.6173,
                "radius": 3000,
                "label": "Moscow city center",
                "address": "Exact address"
            }]
        }
    }

Also, you cannot pass local_geo and/or regions together with geo at the same time.

Example of an incorrect request:

    POST /api/v2/ad_groups/9826424.json
    {
        "targetings": {
            "regions": [56, 97, 100],
            "geo": {
                "regions": [56, 97, 100]
            },
        }
    }

• group_members:

    {
        "group_members": "not_group_member"
    }

• interests:

    {
        "interests": [9413, 9414, 9415]
    }

• interests_soc_dem:

    {
        "interests_soc_dem": [0, 12, 13, 14, 22, 23, 24]
    }

• local_geo:

    {
        "local_geo": {
            "visit_type": "usual",
            "loc_type": ["home", "work"],
            "locations": [{
                "lat": 55.75583,
                "lng": 37.6173,
                "radius": 3000,
                "label": "Moscow city center",
                "address": "Exact address"
            }]
        }
    }

• mobile_apps:

    {
        "mobile_apps": "deleted"
    }

• mobile_operation_systems:

    {
        "mobile_operation_systems": [37, 38, 39]
    }

• mobile_operators:

    {
        "mobile_operators": [3, 5, 6]
    }

• mobile_prefix:

    {
        "mobile_prefix": ["mts", "beeline", "megafon"]
    }

• mobile_types:

    {
        "mobile_types": ["smartphones", "tablets"]
    }

• mobile_vendors:

    {
        "mobile_vendors": [14, 41, 49]
    }

• pad_category:

    {
        "pad_category": {
            "iOS": [12, 13, 41],
            "Android": [7, 9, 83]
        }
    }

• pads:

    {
        "pads": [9863, 9872]
    }

• regions:

    {
        "regions": [56, 97, 100]
    }

• segments:

    {
        "segments": [22679, 22728]
    }

• sex:

    {
        "sex": ["male", "female"]
    }

• geo (regions):

    {
        "geo": {
            "regions": [56, 97, 100, 188, -70]
        }
    }

• geo (local_geo):

    {
        "geo": {
            "local_geo": {
                "visit_type": "usual",
                "loc_type": ["home", "work"],
                "locations": [{
                    "lat": 55.75583,
                    "lng": 37.6173,
                    "radius": 3000,
                    "label": "Moscow city center",
                    "address": "Exact address"
                }]
            }
        }
    }