This document is still a work in progress.

Request an Ad

Designing

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

Accept-Language

string

optional

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:

English (en)

Spanish (es)

French (fr)

Portuguese (pt)

German (de)

Italian (it)

Dutch (nl)

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:

Body Params application/json

placements

array[object (Placement) {5}]

required

key

string

Placement key

required

Examples:

homemapmenujourneysearch

count

integer

Number of ads to return

optional

This will force to return a maximum number of ads.

Defaults to 1. Maximum 10.

>= 1<= 10

Default:

format

enum<string>

Ad Format

optional

The expected ad format. Currently only native is supported (default).

Allowed value:

native

Default:

native

advertiserId

string <advertiser_[ulid]>

Advertiser ID

optional

The unique identifier of the advertiser. This field can be used to specifically request ads from a particular advertiser.
If provided, only ads linked to this advertiser will be considered for display. If not provided, ads from any eligible advertiser may be returned based on the placement and targeting criteria.

Match pattern:

advertiser_01[0-9A-HJKMNP-TV-Z]{24}

templateId

string <template_[ulid]>

Template ID

optional

The unique identifier of the ad template. A placement can support multiple templates, and a template can be used across various placements.
By specifying the templateId, you can control which template is used for rendering the ad within the placement. If not provided, a suitable template will be selected based on the placement and other criteria.

Match pattern:

template_01[0-9A-HJKMNP-TV-Z]{24}

targeting

object (Targeting)

optional

Target using location targeting or custom targeting.

geo

array[integer]

optional

Overrides the geo targeting retrieved from the user's IP.

An array of geoname ids in the form:

[ 5819, 11797, 18918, 49518 ]

An ad to be eligible must satisfy ANY of the geonames ids. Ads without geo targeting are always eligibles.

location

array [object {2}]

Location targeting

optional

An array of coordinates in the form:

[
    { "latitude": 3.9207, "longitude": 37.1403 },
    { "latitude": -65.7507, "longitude": 153.5787 }
]

An ad to be eligible must satisfy ANY of the coordinates. Ads without location targeting are always eligibles.

custom

array[object (Custom Targeting) {2}]

Custom Targeting

optional

An array of key-value objects. For example:

[
   { "key": "region", "value": "london" },
   { "key": "age", "value": 28 },
   { "key": "vip", "value": true }
]

An ad to be eligible must satisfy ALL of the key values. Ads without custom targeting are always eligibles.

Note: Keys must exists in your key-value presets and must be in the correct data type (string, integer or number)

user

object (User)

optional

string

End-user ID

optional

The internal user id. This can also be a hashed value if the ID is sensitive.

In order to use the frequency capping functionality, this value must be set.

End-user IP

optional

The end-user’s IP address in IPv4 or IPv6 format. This field is necessary when ads are targeted based on geo-location.
The system uses the IP to determine the user’s geographical location to deliver location-based ads. If the IP is not provided, geo-targeted ads may not be shown.

timezone

string

End-user Time Zone

optional

The time zone of the end-user, crucial for accurately targeting ads with day/hour parting. Ads scheduled for specific times depend on this value to ensure they are displayed at the correct local time.
The provided time zone takes priority over any inferred from the user’s IP address. If neither a time zone nor an IP address is provided, ads configured with parting may not be eligible.

consent

object (Consent)

optional

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://decision-engine.fly.dev/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

Content-Language

string

required

The creative content language

Example:

Body

success

boolean

required

Describes if the request was successfully processed.

data

array[object (Decision) {2}]

required

placement

string

required

Examples:

homemapmenujourneysearch

creatives

array[object (Creative) {5}]

required

>= 1 items

errors

required

Any of

Errors

null

code

integer <int32>

required

message

string

required

warnings

optional

This property won't be returned in your production environment, only in staging.

Any of

Warnings

null

code

integer <int32>

required

message

string

required

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 2024-11-22 22:28:18

Creative