Creatives

Creatives represent the actual ad content served to users. They contain templates, form fields, rendering metadata, and associations with Line Items.

Overview

A Creative defines:

Ad Content - Images, text, video, rich media
Template - Pre-built responsive ad format (AdTemplate system)
Slot Configuration - Where the ad appears and supported sizes
Targeting - Optional creative-level targeting (overrides line item)
Scheduling - Optional creative-level dates (overrides line item)

Creative Hierarchy

graph TD
    Deal[Deal] --> LineItem[Line Item]
    LineItem --> Creative1[Creative 1<br/>Banner 300x250]
    LineItem --> Creative2[Creative 2<br/>Native Ad]
    Creative1 --> Template1[Ad Template<br/>Banner_300x250]
    Creative1 --> Form1[Creative Form<br/>Basic Config]
    Creative1 --> Body1[Creative Body<br/>Field Data]
    
    style LineItem fill:#e8f5e9
    style Creative1 fill:#fff3e0
    style Template1 fill:#e3f2fd

Query Creatives

Basic Query

query GetCreatives {
  dream_adserver {
    creatives(limit: 10) {
      edges {
        creative_id
        creative_name
        creative_status
        lineitem_id
        lineitem_name
        deal_id
        deal_name
      }
      total_count
    }
  }
}

Filtered Query

query GetFilteredCreatives($filter: JSON, $sort: JSON) {
  dream_adserver {
    creatives(
      filter: $filter
      sort: $sort
      limit: 25
      offset: 0
    ) {
      edges {
        creative_id
        creative_name
        creative_description
        creative_status
        creative_template
        creative_slot
        creative_slot_sizes
        lineitem_id
        lineitem_name
        lineitem_type
        deal_id
        deal_name
      }
      total_count
    }
  }
}

Variables:

{
  "filter": {
    "creative_status": {"=": "ACTIVE"},
    "lineitem_type": {"=": "DISPLAY"}
  },
  "sort": {
    "creative_id": "desc"
  }
}

Query by Line Item

query GetCreativesByLineitem($filter: JSON) {
  dream_adserver {
    lineitems(filter: $filter) {
      edges {
        lineitem_id
        lineitem_name
        creatives(limit: 10) {
          edges {
            creative_id
            creative_name
            creative_status
            creative_template
          }
          total_count
        }
      }
    }
  }
}

Variables:

{
  "filter": {
    "lineitem_id": {"=": 12345}
  },
  "sort": {
    "creative_id": "desc"
  }
}

Critical Fields

Identification

Field	Type	Description
`creative_id`	Int	Unique identifier
`creative_name`	String!	Display name
`creative_description`	String	Description
`lineitem_id`	Int!	Parent line item identifier
`deal_id`	Int!	Parent deal identifier

Template System

Field	Type	Description
`creative_template`	String	Ad template name (defines look/feel)
`creative_form`	DASCreativeForm	Basic template configuration
`creative_body`	JSON	Detailed template field data
`creative_template_data`	AdTplTemplateData	Complete template metadata

Placement & Sizing

Field	Type	Description
`creative_slot`	String	Ad slot name for display
`creative_slot_sizes`	[String!]	Supported slot sizes for targeting

Status & Lifecycle

Field	Type	Description
`creative_status`	String	Status (ACTIVE, PAUSED, etc.)
`creative_start_date`	String	Delivery start (overrides line item)
`creative_end_date`	String	Delivery end (overrides line item)
`creative_is_archived`	Boolean	Archive flag

Targeting & Delivery

Field	Type	Description
`creative_target`	DASTarget	Creative-specific targeting
`creative_weight`	Int	Weight for weighted rotation (0-100)
`creative_capping_cnt`	Int	Max events per user (overrides line item)
`creative_capping_ttl`	Int	Capping time window in seconds

Preview & Verification

Field	Type	Description
`creative_preview_url`	String	Preview URL for creative rendering
`verification_url`	String	URL for ad source verification

Template System

The creative template system uses three related fields:

1. creative_form (DASCreativeForm)

Basic configuration object with common settings.

2. creative_body (JSON)

Template-specific field data. Schema varies by template.

TBD

Example

TBD

Mutations

Create/Update Creative

mutation SetCreative($input: DASCreativeInput!) {
  dream_adserver {
    set_creative(creative: $input) {
      hit {
        creative_id
        creative_name
        creative_status
        creative_template
        lineitem_id
      }
    }
  }
}

Variables (create new):

{
  "input": {
    "creative_name": "Holiday Banner 300x250",
    "lineitem_id": 12345,
    "creative_template": "Banner_300x250",
    "creative_slot": "article_top",
    "creative_slot_sizes": ["300x250"]
  }
}

Variables (update existing):

{
  "input": {
    "creative_id": 67890,
    "creative_name": "Updated Creative Name",
    "creative_status": "ACTIVE"
  }
}

Common Filter Patterns

Active Creatives

{
  "filter": {
    "creative_status": {"=": "ACTIVE"}
  }
}

By Line Item

{
  "filter": {
    "lineitem_id": {"=": 12345}
  }
}

By Template

{
  "filter": {
    "creative_template": {"like": "%Banner%"}
  }
}

By Slot Size

{
  "filter": {
    "creative_slot_sizes": {"in": ["300x250", "728x90"]}
  }
}

Search by Name

{
  "filter": {
    "creative_name": {"ilike": "%holiday%"}
  }
}

Sort Examples

Newest First

{
  "sort": {
    "creative_id": "desc"
  }
}

By Name

{
  "sort": {
    "creative_name": "asc"
  }
}

By Status and ID

{
  "sort": {
    "creative_status": "asc",
    "creative_id": "desc"
  }
}

❗️
⚠️ CRITICAL: Sort direction MUST be lowercase ("desc", not "DESC").

Creative Rotation

When multiple creatives belong to one line item, the creative_weight field controls rotation:

Line Item Setting	Behavior	Use Weight Field
Even rotation	All creatives shown equally	No
Weighted rotation	Creatives shown proportionally	Yes (0-100)
CTR optimized	Best-performing shown more	No

Example (weighted rotation):

Creative A: weight = 70  →  70% of impressions
Creative B: weight = 20  →  20% of impressions
Creative C: weight = 10  →  10% of impressions

Slot Targeting

Slot Sizes

Common IAB standard sizes:

Banners: 300x250, 728x90, 160x600, 320x50
Skyscrapers: 120x600, 160x600
Leaderboards: 728x90, 970x90
Mobile: 320x50, 300x50
Responsive: fluid, responsive

Multi-Size Creatives

A creative can target multiple slot sizes:

{
  "creative_slot_sizes": ["300x250", "336x280"]
}

The creative will be delivered to any slot supporting these sizes.

Preview & Testing

Get Preview URL

query GetCreativePreview($creativeId: Int!) {
  dream_adserver {
    creatives(filter: $filter) {
      edges {
        creative_id
        creative_name
        creative_preview_url
      }
    }
  }
}

Preview with Live Context

query GetCreativePreview($creativeId: Int!, $live: Boolean) {
  dream_adserver {
    creatives(filter: $filter) {
      edges {
        creative_id
        creative_preview_url(live: $live)
      }
    }
  }
}

Variables:

{
  "creativeId": 67890,
  "live": true
}

Best Practices

1. Use Specific Templates

Choose templates appropriate for your ad format:

{
  "creative_template": "Banner_300x250"  // Specific
}

Not:

{
  "creative_template": "Generic"  // Too vague
}

2. Validate Template Body

Ensure creative_body matches template schema:

// Validate before sending
const bannerBody = {
  image_url: "https://...",    // Required
  click_url: "https://...",    // Required
  alt_text: "..."              // Recommended
};

3. Set Appropriate Slot Sizes

Match slot sizes to your creative dimensions:

{
  "creative_template": "Banner_300x250",
  "creative_slot_sizes": ["300x250"]  // Matches template
}

4. Use Preview URLs for QA

Always preview before activating:

1. Get creative_preview_url
2. Open in browser
3. Verify rendering
4. Check click tracking
5. Activate creative

Complete Example

query GetCreativesComplete($filter: JSON, $sort: JSON, $limit: Int, $offset: Int) {
  dream_adserver {
    creatives(
      filter: $filter
      sort: $sort
      limit: $limit
      offset: $offset
    ) {
      edges {
        creative_id
        creative_name
        creative_description
        creative_status
        creative_template
        creative_slot
        creative_slot_sizes
        creative_weight
        creative_preview_url
        lineitem_id
        lineitem_name
        lineitem_type
        deal_id
        deal_name
        creative_start_date
        creative_end_date
      }
      total_count
    }
  }
}

Variables:

{
  "filter": {
    "creative_status": {"=": "ACTIVE"},
    "lineitem_type": {"=": "DISPLAY"}
  },
  "sort": {
    "creative_id": "desc"
  },
  "limit": 25,
  "offset": 0
}

Next Steps

Advertisers - Manage advertiser entities
Line Items - Parent campaign configuration
Filtering - Master query filters
Sorting - Learn lowercase requirement

Delivery APIs Overview - Campaign hierarchy
Inventory Management - Ad slots and placements

Creatives

Overview

Creative Hierarchy

Query Creatives

Basic Query

Filtered Query

Query by Line Item

Critical Fields

Identification

Template System

Placement & Sizing

Status & Lifecycle

Targeting & Delivery

Preview & Verification

Template System

1. creative_form (DASCreativeForm)

2. creative_body (JSON)

Mutations

Create/Update Creative

Common Filter Patterns

Active Creatives

By Line Item

By Template

By Slot Size

Search by Name

Sort Examples

Newest First

By Name

By Status and ID

Creative Rotation

Slot Targeting

Slot Sizes

Multi-Size Creatives

Preview & Testing

Get Preview URL

Preview with Live Context

Best Practices

1. Use Specific Templates

2. Validate Template Body

3. Set Appropriate Slot Sizes

4. Use Preview URLs for QA

Complete Example

Next Steps

Related