Data model

Campaigns contain creatives. Every creative has a latestScanStatus.id, a scan ID. Call /scans/{scanId} on any scan ID to get its test results.

Display creatives are always flat: one creative, one scan. Video creatives can have additional layers (media files and variations). The structures below show how they are organized and which endpoints reveal each level.

Creative structures

Display creative

All display types (hosted images, HTML5, tags) follow the same flat structure. One creative, one scan.

GET /campaigns/{campaignId}/creatives

    Creative                         <- has latestScanStatus.id

GET /scans/{scanId}                  <- display tests (dimensions, filesize, load time, etc.)

Display sourceType values include image, html5, tag-html5, tag-beacon, among others. The test set varies by type but the structure is always the same.

Hosted video

Same flat structure as display. One file, one scan.

GET /campaigns/{campaignId}/creatives

    Creative                         <- has latestScanStatus.id

GET /scans/{scanId}                  <- video tests (resolution, duration, codec, etc.)

VAST without variations

The creative holds the VAST XML scan. Its media files each have their own video scan.

GET /campaigns/{campaignId}/creatives

    Creative                         <- has latestScanStatus.id
    |
    |   GET /scans/{scanId}          <- VAST XML tests (version, validation, skip, etc.)
    |
    +-- GET /creatives/{id}/media-files
        |
        +-- Media file               <- has latestScanStatus.id
        |   GET /scans/{scanId}      <- video tests (duration, codec, audio, etc.)
        |
        +-- Media file               <- has latestScanStatus.id
        |   GET /scans/{scanId}      <- video tests
        |
        +-- ...

VAST with variations

Detected by nbVariations being present on the creative. The variations endpoint returns both the variation XML scan AND its child video scans, so there is no need to call /media-files.

GET /campaigns/{campaignId}/creatives

    Creative                         <- has latestScanStatus.id
    (nbVariations present)
    |
    |   GET /scans/{scanId}          <- top-level nbIssues only (no tests array)
    |
    +-- GET /creatives/{id}/variations
        |
        +-- Variation A  (creativeId, nbObservations)
        +-- Variation B
        +-- ...
            |
            +-- GET /creatives/{id}/variations/{variationCreativeId}
                |
                |   Returns ALL items for this variation:
                |
                +-- vast-variation    <- has latestScanStatus.id
                |   GET /scans/{id}  <- VAST XML tests for this variation
                |
                +-- vast-child-video  <- has latestScanStatus.id
                |   GET /scans/{id}  <- video tests
                |
                +-- vast-child-video  <- has latestScanStatus.id
                |   GET /scans/{id}  <- video tests
                |
                +-- ...

Navigating the hierarchy

Starting from /campaigns/{campaignId}/creatives:

For each creative:
|
+-- Has nbVariations?
|   |
|   YES -> VAST with variations
|   |     1. /scans/{latestScanStatus.id}          -> top-level nbIssues (no tests array)
|   |     2. /creatives/{id}/variations             -> list variations
|   |     3. /creatives/{id}/variations/{varId}     -> variation + media files
|   |     4. /scans/{id} for each item              -> XML or video tests
|   |
|   NO -> fetch /creatives/{id}/media-files
|        |
|        +-- Has results -> VAST without variations
|        |         1. /scans/{latestScanStatus.id}  -> VAST XML tests
|        |         2. /scans/{id} for each media file -> video tests
|        |
|        +-- Empty -> flat creative (display or hosted video)
|                  1. /scans/{latestScanStatus.id}  -> all tests in one response

Key rules

• /scans/{scanId} is the only endpoint that returns test results. Everything else is about discovering scan IDs.
• nbVariations on the creative determines the path. Only VAST creatives can have variations.
• The variations detail endpoint includes media files. When using /creatives/{id}/variations/{variationCreativeId}, the response contains both the vast-variation item and all vast-child-video items. No need to call /media-files separately.
• Every node has latestScanStatus.id. Whether it’s a creative, a variation, or a media file: if it has latestScanStatus.id, you can call /scans/{id} on it.
• Display creatives are always flat. No variations, no media files. One scan covers everything.

Scan types

Tests are prefixed Test_Display_* or Test_Video_* depending on the campaign type.

Display tests

Context	Example tests
Hosted image	AdDimensions, AnimationLength, Border, Filesize
Hosted HTML5	AdDimensions, Audio, VisualStart, AnimationLength, Border, MouseClick, Filesize, TagLoadInitial, TagLoadSubload, Cpu, ExternalRequests, Connections, Cookies, Ssl, LocalStorage, CodeRules, FlashLso, AdVerificationTags, HeavyAdInterventions
HTML5 tag	AdDimensions, Audio, VisualStart, AnimationLength, MouseClick, LandingPage, ClickRedirects, TagLoadInitial, TagLoadSubload, Cpu, ExternalRequests, Connections, Cookies, Ssl, LocalStorage, GdprConsent, CodeRules, FlashLso, AdVerificationTags, HeavyAdInterventions
Tracking tag	AdDimensions, Audio, TagLoadInitial, TagLoadSubload, Cpu, ExternalRequests, Connections, Cookies, Ssl, LocalStorage, GdprConsent, FlashLso, AdVerificationTags, HeavyAdInterventions

Video tests

Context	Example tests
Hosted video	Resolution, Duration, TotalBitrate, FPS, Filesize, ContainerFormat, Codec, ScanType, AudioCodec, AudioAverage, AudioPeak, AudioSampleRate, ChromaSubsampling, Boxing
VAST creative	VastDurationDiscrepancy, VastRequiredMediaFiles, VastVersion, VastValidateXml, VastApiProperties, VastSkipDetection, VastCreativeCount, VastVariations, VastConnectionRules, VastNonHttps, AdVerificationTags
VAST variation	Same as VAST creative (per-variation)
VAST child video	Duration, FPS, Filesize, Codec, ScanType, AudioCodec, AudioAverage, AudioPeak, AudioSampleRate, VastPropertyDiscrepancy, ChromaSubsampling, Boxing