Request an Ad

POST

/v1/decision

Request an advertisement based on the provided parameters. This endpoint returns targeted ads for specific placements, considering factors such as advertiser, template, user information, and targeting criteria like geography, location or custom filters. The ads delivered are optimized for relevance based on these inputs.

The simplest request includes only the placements key with one item:

Request

Header Params

Body Params application/json

Example

{
    "placements": [
        {
            "key": "map",
            "templateId": "template_01J00000000000000000000003"
        }
    ],
    "user": {
        "id": "asdasd",
        "timezone": "Europe/London"
    }
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.demo.admoai.com/v1/decision' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--data-raw '{
    "placements": [
        {
            "key": "map",
            "templateId": "template_01J00000000000000000000003"
        }
    ],
    "user": {
        "id": "asdasd",
        "timezone": "Europe/London"
    }
}'

Responses

🟢200Success

application/json

Successful ad decision response

Headers

Body

Examples

Text-only AdComposite Ad

{
    "success": true,
    "data": [
        {
            "placement": "menu",
            "creatives": [
                {
                    "contents": [
                        {
                            "key": "title",
                            "value": "Managed optimizing project",
                            "type": "text"
                        }
                    ],
                    "advertiser": {
                        "id": "advertiser_01KF0AGKWQWKB3EHD2JWBQ0SQ7",
                        "name": "Pagac, Funk and Blanda",
                        "legalName": "Koepp - Okuneva",
                        "logoUrl": "https://loremflickr.com/813/3918?lock=7943095562559505"
                    },
                    "tracking": {
                        "impressions": [
                            {
                                "key": "default",
                                "value": "https://demo.api.admoai.com/t?e=eyJ..."
                            }
                        ],
                        "clicks": null,
                        "custom": null
                    },
                    "metadata": {
                        "adId": "ad_011WZ70EG0HEFDYFG3E3GSAY2C",
                        "creativeId": "creative_0130XW5P9VV9F5JFMDB4Q9FQV2",
                        "placementId": "placement_01K3B0XTH26FHNAWTEPNFRFM5Y",
                        "templateId": "template_01WYM8DAQ7ZR7KHCETDMAGSGTY",
                        "priority": "standard",
                        "style": "default"
                    }
                }
            ]
        }
    ],
    "errors": null,
    "warnings": null
}

🟠422Failed Validation

Modified at 2025-06-15 17:22:49

Creative