Banner

/api/v2/banners/<banner_id>.json

A resource that allows you to retrieve, update, and delete ads.

Used object: Banner

GET

Retrieving a single ad

Request example

    GET /api/v2/banners/23617841.json

Response example

    {
        "id": 23826937
        "ad_group": 9367343
    }

POST

Editing an ad

Request example

    POST /api/v2/banners/23826937.json
    {
        "status": "blocked"
    }

Response example

    HTTP 204

The contents of the urls, textblocks, and content sections are fully replaced on update. For example, for a banner with content:

    {
        "content": {
            "logo_image": {
                "id": 83465432
            },
            "promo_image": {
                "id": 90465432
            },
            "tpl_background_image": {
                "id": 86342123
            }
        }
    }

the update request:

    {
        "content": {
            "logo_image": {
                "id": 83465432
            },
            "promo_image": {
                "id": 88278634
            },
            "tpl_background_image_300": {
                "id": 72934723
            }
        }
    }

will result in exactly this new content section after the update.

Possible response codes

• 200/204 — ad saved
• 400 — validation error
• 404 — ad not found

Possible error codes

• active_banners_limit — the limit of active banners for the user has been exceeded
• deleted_banner — a deleted banner cannot be modified
• bad_width — invalid content width value
• bad_height — invalid content height value
• bad_size — maximum content size exceeded
• bad_type — invalid content type
• bad_length — content has an invalid playback duration
• bad_bitrate — content has an invalid bitrate
• dynamic_content — dynamic content is used in an invalid role
• custom_params — invalid video parameters
• exclamation_signs_limit — exclamation marks limit exceeded in the banner text block
• invalid_macros — a disallowed macro is used in the banner text block
• persistent_urls — changing URLs is not allowed in the package
• one_url_object_id — URLs leading to different objects are not allowed in the package
• ad_group_one_url — different URLs are not allowed in the package
• url_not_checked — using unchecked URLs is not allowed
• url_not_valid — the URL does not match the specified role
• max_value — value is greater than the maximum
• min_value — value is less than the minimum
• bad_value — invalid value format or type
• required — field is required
• unallowed_value — value is not in the list of allowed values
• bad_items — the list contains invalid values
• unallowed_field — field is not allowed
• read_only_field — updating a non-editable field

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": {
                "call_to_action": {
                    "message": "Unallowed value",
                    "code": "unallowed_value"
                }
            },
            "message": "Validation failed",
            "code": "validation_failed"
        }
    }

DELETE

Deleting an ad

Request example

    DELETE /api/v2/banners/23617841.json

Response example

    HTTP 204

Possible response codes

• 204 — ad deleted
• 404 — ad not found