1. API Reference
  • Default module
    • Getting Started
    • Concepts
      • Advertiser
      • Placement
      • Template
      • Ad
      • Creative
    • API Reference
      • API Versioning & Upgrade Policy
      • Changelog
      • Request an Ad
        POST
      • Tracking
        GET
  1. API Reference

Changelog

All notable changes to the Admoai Decision Engine API will be documented in this file.
The format is based on Keep a Changelog.

[2025-11-01]#

Added#

Destination Targeting Support#

Added a Ad new segmentation filter, allowing to filter ads based on the destination of the user.

Video Ad Support#

Three delivery modes for video ads:
json: Full creative content including video URL and tracking beacons (custom players)
vast_tag: Signed URL to fetch VAST 4.2 XML from renderer service (standard players)
vast_xml: Inline base64-encoded VAST 4.2 XML document (offline/air-gapped)
Six video milestone tracking events:
start: Video playback begins
first_quartile: 25% of duration reached
midpoint: 50% of duration reached
third_quartile: 75% of duration reached
complete: Video playback completes
skip: User skips the video
Video metadata in response:
duration: Video duration in seconds
aspect_ratio: Video aspect ratio (e.g., "16:9")
is_skippable: Whether the video can be skipped
skip_offset_seconds: When skip button becomes available
VAST 4.2 compliance:
IAB-compliant VAST XML generation
Support for Linear video ads
VideoClicks with ClickTracking and ClickThrough
Companion ads support
Admoai-specific extensions (metadata, advertiser info)
Skip button configuration:
HH:MM:SS format (e.g., "00:00:05")
Percentage format (e.g., "25%")
VAST tag URL signing:
HMAC-SHA256 signature for security
TTL-based expiration
Tamper-proof payload encoding

New Request Parameters#

placements[].format: Ad format filter ("native", "video")

New Response Fields (Video Ads Only)#

delivery: Video delivery mode ("json", "vast_tag", "vast_xml")
vast: VAST delivery object
vast.tagUrl: VAST tag URL (vast_tag mode)
vast.xmlBase64: Base64-encoded VAST XML (vast_xml mode)
tracking.videoEvents: Array of video milestone tracking URLs
metadata.format: Ad format ("video")
metadata.duration: Video duration (seconds)
metadata.aspect_ratio: Video aspect ratio
metadata.is_skippable: Skip availability
metadata.skip_offset_seconds: Skip offset (seconds)

Open Measurement (OMID) Support#

Third-party Verification: Added support for Open Measurement SDK (OMID) to enable viewability and measurement verification via external providers (e.g., IAS, DoubleVerify, Moat).
Standardized Signal Delivery: Support for OMID verification resources across both Native and Video formats.

New Response Fields#

verificationScriptResources: Array of verification objects including vendorKey, scriptUrl, and verificationParameters. (Included in JSON for Native ads and Video JSON mode; for other video modes, resources are embedded within the VAST XML).

Changed#

Tracking Behavior (Video Ads)#

VAST Tag/XML delivery modes: Tracking beacons (impressions, clicks, videoEvents) are empty arrays in JSON response; tracking lives in VAST XML instead
Player click event: Excluded from JSON tracking.clicks for VAST modes (included in VAST XML <VideoClicks>)

Response Structure#

Video ads always include delivery field
Video ads always include vast field (empty object for JSON delivery)
Native ads omit delivery and vast fields (backward compatible)

Security#

VAST tag URL signing: HMAC-SHA256 signature prevents tampering
Timestamp validation: VAST tag URLs expire after configurable TTL
Tracking token encryption: Prevents tracking URL manipulation

Fixed#

Improved timezone inference from IP geolocation
Enhanced error messages for invalid geo-targeting
Fixed edge case in custom targeting CEL expression evaluation

Performance#

Optimized video metadata extraction
Reduced VAST XML generation overhead with pre-computed templates
Improved tracking URL generation performance (batch processing)

Documentation#

Complete API reference for v2025-11-01
Video ads implementation guide with code examples (JavaScript, Swift, Kotlin)
VAST 4.2 compliance documentation

[2025-01-01]#

Added#

Core Features#

Native ad support: Text, image, and rich media creatives
Template system: Flexible ad template configuration
Content localization: Language-aware content delivery via Accept-Language header
Click and impression tracking: Encrypted tracking tokens with expiration

Targeting Capabilities#

Geo-targeting: Country, city, region targeting using GeoNames database
Location targeting: GPS coordinate-based targeting with radius matching
Custom targeting: CEL expression-based custom attribute targeting
Dayparting: Time-of-day and day-of-week ad scheduling

Ad Selection#

Priority-based selection: Multi-tier ad prioritization by weight
Weighted random selection: Probabilistic ad rotation based on weights
Frequency capping: Per-user impression limits
GDPR compliance: EU user detection and consent-based frequency capping

API Endpoints#

POST /v1/decision: Request ad decision for placements
GET /v1/tracking: Track ad events (impression, click, custom)

Request Parameters#

placements[]: Array of placement requests
key: Placement identifier (required)
count: Number of ads to return (1-10, default: 1)
advertiserId: Filter by advertiser public ID
templateId: Filter by template public ID
targeting: Targeting parameters
geo: GeoName IDs array
location: Latitude/longitude pairs with radius
custom: Custom attribute key-value pairs
user: User context
id: User identifier (for frequency capping)
ip: IP address (for geo-inference)
timezone: IANA timezone
consent.gdpr: GDPR consent status
device: Device context (OS, model, manufacturer, etc.)
app: Application context (name, version, bundle ID)

Response Structure#

success: Boolean success indicator
data: Array of placement decisions
placement: Placement key
creatives: Array of creative objects
contents: Creative content fields
advertiser: Advertiser information
template: Template configuration
tracking: Tracking URLs
metadata: Ad metadata
errors: Array of error objects
warnings: Array of warning objects

Error Handling#

Validation errors: 422 Unprocessable Entity with detailed error codes
Structured error responses: Error code, message, and contextual details
Warning system: Non-fatal warnings for degraded experience (e.g., missing language)

Version System#

Header-based versioning: X-Decision-Version header for API version selection
Default version: Falls back to 2025-01-01 if no version header provided

Security#

Tracking token encryption: AES-256-GCM encryption for tracking payloads
Token expiration: Configurable TTL (default: 3600 seconds)

Version Support Policy#

VersionReleasedStatusSupport End
2025-11-012025-11-01ActiveTBD
2025-01-012025-01-01Active2026-01-01 (minimum)
Notes:
Active versions receive bug fixes, security updates, and new features
Deprecated versions receive security updates only for 6 months
Versions are supported for minimum 12 months after successor release

Upgrade Path#

From 2025-01-01 to 2025-11-01#

Backward Compatible: ✅ Yes
Changes Required:
None for native ads
Optional: Add format: "video" for video ad support
Optional: Implement video milestone tracking (custom players)
Optional: Integrate VAST player (VAST Tag/XML delivery)

Deprecation Notices#

None#

No features have been deprecated in current versions.

Breaking Changes#

None#

Version 2025-11-01 is fully backward compatible with 2025-01-01.

Experimental Features#

None#

All features in versions 2025-01-01 and 2025-11-01 are stable and production-ready.

Known Issues#

Version 2025-11-01#

None reported.#

Version 2025-01-01#

None reported.#

License#

Copyright © 2024 Admoai. All rights reserved.
Last Updated: 2024-01-15
Current Version: 2025-11-01
Modified at 2026-01-23 15:25:00
Previous
API Versioning & Upgrade Policy
Next
Request an Ad