# Advalidation

> Advalidation is an automated ad creative validation platform. Upload ad creatives (display banners, video files, VAST tags) and each creative is evaluated through automated tests that return structured results such as file weight, dimensions, duration, click-through verification, and SSL compliance. Integrate via the TypeScript SDK (recommended) or the REST API.

Questions, need an API key, or want to discuss integration? Email us at hello@advalidation.com

## Docs

- [TypeScript SDK](https://advalidation.com/docs/sdk/): One call to validate a creative, no manual polling, no response parsing
- [SDK on GitHub](https://github.com/advalidation/sdk): Full SDK reference with all options, result shape, verbose output, and error handling
- [REST API Guide](https://advalidation.com/docs/getting-started/): Core API walkthrough - verify key, create campaign, upload creative, poll for results, retrieve scan data
- [Data model](https://advalidation.com/docs/data-model/): Creative structures, hierarchy navigation, and scan types for display and video
- [Creative files upload guide](https://advalidation.com/docs/file-upload/): Four upload methods (JSON, base64, plain text, binary) with examples
- [Retrieving results for a VAST tag](https://advalidation.com/docs/vast-case-study/): Step-by-step guide for VAST creatives with variations and media files
- [The test array](https://advalidation.com/docs/test-array/): Reference for all display and video tests returned in scan results
- [Conventions](https://advalidation.com/docs/conventions/): Response format, error handling, content types
- [Rate limiting](https://advalidation.com/docs/rate-limiting/): IP-based rate limits, response headers, handling 429s
- [API Reference](https://advalidation.com/docs/api/): Full OpenAPI reference for all endpoints
- [OpenAPI Spec](https://advalidation.com/openapi.json): Full machine-readable API specification

## TypeScript SDK (recommended)

```
npm install advalidation
```

Validate a creative in one call:

```ts
import { Advalidation } from "advalidation";

const client = new Advalidation({ apiKey: "your-api-key" });

const result = await client.validate({
  url: "https://rtr.innovid.com/r1.66f3e735e66ba5.38642747;cb=[timestamp]",
  type: "video",
});

console.log(result.passed);    // true or false
console.log(result.issues);    // number of failed tests
console.log(result.reportUrl); // link to the full visual report
```

The SDK handles campaign creation, upload, polling, and result retrieval. Pass `details: true` to get the full test breakdown including VAST media files and variations.

### Creative inputs

Exactly one of `url`, `tag`, or `file` must be provided.

```ts
// URL (hosted creative, VAST endpoint, ad tag URL)
await client.validate({ url: "https://example.com/ad.html", type: "display" });

// Tag (raw HTML/JavaScript or VAST XML)
await client.validate({ tag: "<script src='https://example.com/ad.js'></script>", type: "display" });

// File (local path, max 16 MB)
await client.validate({ file: "/path/to/video.mp4", type: "video" });
```

### Target options

Provide exactly one of `campaign`, `spec`, or `type`:

- `type: "display" | "video"` -- use the default ad specification for that type (creates a new campaign)
- `spec: "123"` -- use a specific ad specification ID (creates a new campaign)
- `campaign: 12345` -- upload into an existing campaign (adspec is inherited)

### Serverless / split workflow

Use `submit()` + `getResults()` to split the workflow across separate requests (useful when `validate()` would timeout):

```ts
const { creativeId } = await client.submit({ url: "https://example.com/vast.xml", type: "video" });
// Later...
const response = await client.getResults(creativeId);
if (response.status === "finished") {
  console.log(response.passed, response.issues);
}
```

`getResults()` returns a discriminated union -- check `response.status` before accessing result fields. Possible statuses: `"finished"`, `"pending"`, `"failed"`, `"cancelled"`.

### Error handling

All errors extend `AdvalidationError`: `AuthenticationError`, `InputError`, `ApiError`, `RateLimitError`, `ScanFailedError`, `ScanCancelledError`, `TimeoutError`, `AbortError`.

## REST API key concepts

All requests use the base URL `https://app.advalidation.io/v2` and require the `X-API-Key` header.

### Core workflow

1. Create a campaign (`POST /campaigns`) with `type` set to `display` or `video`
2. Upload a creative (`POST /campaigns/{campaignId}/creatives`) with a `payload` field (HTML tag, URL, VAST URL, or base64-encoded file)
3. Poll the creative (`GET /creatives/{creativeId}`) until `processingStatus` is `finished`
4. Retrieve scan results (`GET /scans/{scanId}`)

### Data model

`/scans/{scanId}` is the only endpoint that returns test results. Everything else is about discovering scan IDs.

**Display creatives** are always flat: one creative, one scan.

**Hosted video creatives** are also flat: one creative, one scan.

**VAST without variations**: The creative holds the VAST XML scan. Media files each have their own video scan. Fetch media files from `/creatives/{id}/media-files`.

**VAST with variations**: Detected by `nbVariations` being present on the creative. The top-level scan has `nbIssues` but no `tests` array. Use `/creatives/{id}/variations` to list variations, then `/creatives/{id}/variations/{variationCreativeId}` to get both the variation XML scan and all child video scans.

### 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
```

### Test results

Each test returns `name`, `value`, `result` (`pass`, `fail`, or `warn`), and `attributes`.

---

For complete documentation in a single file, see [llms-full.txt](https://advalidation.com/llms-full.txt).