Default

Request an Ad

post

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:

POST /v0/decision

{
  "placements": [ { "key": "home" } ]
}

Header parameters

Accept-LanguagestringOptional

The Accept-Language header is an optional string that specifies the user's locale, used to determine the language of the ad creative that will be shown. If the locale is not supported or not provided, the ad creative will default to the language of the selected ad.

Supported languages include:

If the locale is provided in a regional format (e.g., en-US, fr-FR, es-ES, pt-PT, de-DE, it-IT, or nl-NL), it will be automatically converted to the ISO 639-1 standard (e.g., en, fr, es, pt, de, it, nl).

Example: en

Body

application/json

Responses

200

Successful ad decision response

application/json

422Error

application/json

post

/v1/decision

HTTPcURLJavaScriptPython

POST /v1/decision HTTP/1.1
Host: api.demo.admoai.com
Content-Type: application/json
Accept: */*
Content-Length: 131

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

{
  "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"
          },
          "template": {
            "key": "banner",
            "style": "default"
          },
          "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"
          },
          "verificationScriptResources": [
            {
              "vendorKey": "doubleverify.com-omid",
              "url": "https://cdn.doubleverify.com/dvtp_src.js",
              "parameters": "partner=dv_partner_abc"
            }
          ]
        }
      ]
    }
  ],
  "errors": null,
  "warnings": null
}

Tracking

get

Records advertising events (impressions, clicks, views, video milestones) via an encrypted token. Validates and processes the event asynchronously, returning 202 Accepted immediately. Events include ad, creative, user, location, and metadata for analytics and reporting.

Query parameters

estringOptionalExample: <encrypted-payload>

Header parameters

X-Tracking-VersionstringOptionalExample: 2025-11-01

Responses

202Success

application/json

302Redirect

application/json

get

/v1/tracking

HTTPcURLJavaScriptPython

GET /v1/tracking HTTP/1.1
Host: api.demo.admoai.com
Accept: */*

{}