Delivery APIs

Manage your advertising campaigns through the dream_adserver domain. This is the core functionality of the ADP API.

Overview

The Delivery APIs allow you to:

• Manage Line Items - Configure campaign targeting, scheduling, and billing
• Manage Creatives - Upload and configure ad content with templates
• Manage Advertisers - Create and update advertiser entities
• Query Deals - Access commercial agreements

Campaign Hierarchy

graph TD
    Network[Network<br/>NT-7012768] --> Deal[Deal<br/>Commercial Agreement]
    Deal --> LineItem1[Line Item<br/>Campaign Configuration]
    Deal --> LineItem2[Line Item<br/>Another Campaign]
    LineItem1 --> Creative1[Creative<br/>Banner 300x250]
    LineItem1 --> Creative2[Creative<br/>Native Ad]
    LineItem1 --> Target[Target<br/>Targeting Rules]
    LineItem1 --> Billing[Billing Models<br/>CPM, CPC, etc.]
    
    style Network fill:#e3f2fd
    style Deal fill:#f3e5f5
    style LineItem1 fill:#e8f5e9
    style Creative1 fill:#fff3e0

Entity Relationships

Line Item Types

The ADP API supports three types of line items:

Quick Start

Query Line Items

query GetLineitems($filter: JSON, $sort: JSON) {
  dream_adserver {
    lineitems(
      filter: $filter
      sort: $sort
      limit: 10
    ) {
      edges {
        lineitem_id
        lineitem_name
        lineitem_type
        lineitem_status
        deal_id
        deal_name
      }
      total_count
    }
  }
}

Variables:

{
  "filter": {
    "lineitem_is_archived": {"=": false}
  },
  "sort": {
    "lineitem_id": "desc"
  }
}

Query Creatives

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

Variables:

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

Available Operations

Line Items

• Query Line Items - List and filter line items
• Create/Update Line Items - Use set_lineitem mutation
• Line Item Fields - Complete field reference

Creatives

• Query Creatives - List and filter creatives
• Create/Update Creatives - Use set_creative mutation
• Template System - Configure ad templates

Advertisers

• Query Advertisers - List advertisers
• Create/Update Advertisers - Use set_advertiser mutation

Common Patterns

Filter by Type

{
  "filter": {
    "lineitem_type": {"=": "DISPLAY"}
  }
}

Filter by Date Range

{
  "filter": {
    "lineitem_start_date": {">=": "2025-01-01 00:00:00"},
    "lineitem_end_date": {"<=": "2025-12-31 23:59:59"}
  }
}

Search by Name

{
  "filter": {
    "lineitem_name": {"like": "%holiday%"}
  }
}

Get Recent Items

{
  "sort": {
    "lineitem_id": "desc"
  }
}

Nested Queries

Query line items with their creatives:

query GetLineitemsWithCreatives {
  dream_adserver {
    lineitems(limit: 5) {
      edges {
        lineitem_id
        lineitem_name
        creatives(limit: 10) {
          edges {
            creative_id
            creative_name
            creative_status
          }
          total_count
        }
      }
    }
  }
}

Best Practices

1. Use Specific Filters

Bad (retrieves too much):

lineitems(limit: 1000) {
  edges { lineitem_id }
}

Good (filters first):

lineitems(
  filter: {
    "lineitem_is_archived": {"=": false},
    "lineitem_type": {"=": "DISPLAY"}
  },
  limit: 100
) {
  edges { lineitem_id }
}

2. Request Only Needed Fields

Bad:

lineitems {
  edges {
    # All 60+ fields
  }
}

Good:

lineitems {
  edges {
    lineitem_id
    lineitem_name
    lineitem_status
  }
}

3. Use Pagination

Always use limit for large datasets:

lineitems(limit: 25, offset: 0) {
  edges { lineitem_id }
  total_count    # Check total before paginating
}

4. Sort Consistently

For pagination, always sort:

lineitems(
  sort: {"lineitem_id": "asc"},
  limit: 25,
  offset: 0
) {
  edges { lineitem_id }
}

Error Handling

Check Response Errors

const response = await fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({ query, variables })
});

const data = await response.json();

if (data.errors) {
  console.error('GraphQL Errors:', data.errors);
  // Handle errors
} else {
  const lineitems = data.data.dream_adserver.lineitems.edges;
  // Process data
}

Common Errors

• Uppercase sort: Use lowercase "desc" not "DESC"
• Missing domain: Wrap in dream_adserver
• Inline JSON: Use GraphQL variables
• Node wrapper: Access fields directly in edges

See Common Mistakes for details.

Next Steps

1. Line Items - Learn about campaign configuration
2. Creatives - Understand ad content management
3. Advertisers - Manage advertiser entities
4. Filtering - Master query filters

Related Documentation

• Field References - Filtering, sorting, pagination
• Reporting APIs - Campaign performance reports
• Inventory Management - Ad units and targeting

Need Help?

• Playground: Test queries at https://adp-api.dreamlab.pl/playground
• Support: Email [email protected]
• Examples: Check Getting Started guide