AdPlans

/api/v2/ad_plans.json

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

Used object: AdPlan

GET

Retrieving a list of ad campaigns

Request example

    GET /api/v2/ad_plans.json

Response example

    {
        "count": 3,
        "offset": 0,
        "items": [
            {
                "id": 6617841,
                "name": "New campaign 2022-07-15 17:53"
            },
            {
                "id": 6711647,
                "name": "New campaign 2022-08-16 19:49"
            },
            {
                "id": 6711665,
                "name": "New campaign 2022-08-16 19:51"
            }
        ]
    }

Available fields are described in AdPlan.

The resource supports pagination using the limit and offset parameters.

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

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

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

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

Filters

• _id — campaign ID

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

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

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

Sorting

• id

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

• name

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

• status

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

• by multiple fields

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

POST

Creating an ad campaign

Request example:

    POST /api/v2/ad_plans.json
    {
        "name": "My new campaign",
        "status": "active",
        "date_start": "2022-04-01 00:00:00",
        "date_end": "2022-04-15 00:00:00",
        "autobidding_mode": "max_goals",
        "budget_limit_day": "1000",
        "budget_limit": "5000",
        "enable_utm": "False",
        "enable_offline_goals": "False",
        "objective": "playersengagement",
        "ad_groups": []
    }

Response example:

    HTTP 200
    {
        "id": 9826424
    }

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

A campaign 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 — campaign saved
• 400 — validation error

Possible error codes:

• pricelist_not_found — no pricelist was found for the provided pricelist_id
• permission_required — insufficient permissions to modify the field
• 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"
        }
    }