GraphQL Overview

The ADP API uses a domain-based GraphQL architecture that organizes operations into 8 functional domains. Understanding this structure is essential for successful API integration.

Domain Root Fields

All API operations must be wrapped in one of these 8 domain root fields:

graph TD
    API[ADP API Root] --> dream_adserver[dream_adserver<br/>Core Ad Operations]
    API --> report[report<br/>Reporting & Analytics]
    API --> inventory_manager[inventory_manager<br/>Inventory Management]
    API --> dream_audience[dream_audience<br/>Audience Segments]
    API --> user_manager[user_manager<br/>User Management]
    API --> video[video<br/>Video Ads]
    API --> crm[crm<br/>CRM Integration]
    API --> mia[mia<br/>Media Analytics]
    
    style dream_adserver fill:#e3f2fd
    style report fill:#f3e5f5
    style inventory_manager fill:#e8f5e9
    style dream_audience fill:#fff3e0

Domain Reference

Root Field	Domain	Operations	Description
`dream_adserver`	Core	26 operations	Deals, Line Items, Creatives, Advertisers
`report`	Core	2 operations	Report tasks, report queries
`inventory_manager`	Core	2 operations	Ad units, placements, custom targeting, forecasting
`dream_audience`	Core	2 operations	Audience segments, audience databases
`user_manager`	Core	2 operations	User management operations
`video`	Video	1 operation	Video ad operations
`crm`	CRM	1 operation	Customer relationship management
`mia`	MIA	1 operation	Media inventory and analytics

Query Structure

🚧
All queries MUST be wrapped in the appropriate domain root field.

❌ WRONG: Missing Domain Root Field

query {
  lineitems {
    edges {
      lineitem_id
    }
  }
}

Error: Cannot query field "lineitems" on type "Query"

✅ CORRECT: Wrapped in Domain Root Field

query {
  dream_adserver {
    lineitems {
      edges {
        lineitem_id
        lineitem_name
      }
    }
  }
}

Success: Query executes correctly

Common Operations by Domain

dream_adserver (Core Ad Operations)

Most commonly used domain for campaign management:

query GetCampaignData {
  dream_adserver {
    # Query deals
    deals(limit: 10) {
      edges {
        deal_id
        deal_name
      }
      total_count
    }
    
    # Query line items
    lineitems(limit: 10) {
      edges {
        lineitem_id
        lineitem_name
        lineitem_type
      }
      total_count
    }
    
    # Query creatives
    creatives(limit: 10) {
      edges {
        creative_id
        creative_name
      }
      total_count
    }
  }
}

report (Reporting & Analytics)

query GetReportTask($taskId: Int!) {
  report {
    report_task(task_id: $taskId) {
      task_id
      task_status
      task_download_url
    }
  }
}

inventory_manager (Inventory Management)

query GetInventory {
  inventory_manager {
    im_adunits(limit: 10) {
      edges {
        node_id
        node_code
      }
      total_count
    }
  }
}

dream_audience (Audience Segments)

query GetAudienceSegments {
  dream_audience {
    audience_segments(limit: 10) {
      edges {
        audience_segment_id
        audience_segment_name
      }
      total_count
    }
  }
}

Multi-Domain Queries

You can query multiple domains in a single request:

query GetMultiDomainData {
  # Core ad operations
  dream_adserver {
    lineitems(limit: 5) {
      edges {
        lineitem_id
        lineitem_name
      }
    }
  }
  
  # Reporting
  report {
    report_defs {
      edges {
        report_definition_name
        report_definition_type
      }
    }
  }
  
  # Inventory
  inventory_manager {
    im_adunits(limit: 5) {
      edges {
        node_id
        node_code
      }
    }
  }
}

Connection Types

The ADP API uses a custom Connection structure for paginated results.

❗️
ADP API Connections do NOT use the standard GraphQL node wrapper.

Standard GraphQL Relay Connection (NOT used by ADP API)

Standard Relay-style connections use edges { node { ... } }:

# This is standard Relay (NOT used in ADP API)
query {
  dream_adserver {
    lineitems {
      edges {
        node {          # ← ADP API does NOT use this wrapper
          lineitem_id
          lineitem_name
        }
      }
    }
  }
}

ADP API Connection Structure (actual)

ADP API uses direct field access in edges (no node wrapper):

query {
  dream_adserver {
    lineitems {
      edges {           # ← Direct access, no node wrapper
        lineitem_id
        lineitem_name
      }
      total_count       # ← Count field (not pageInfo.totalCount)
    }
  }
}

See Pagination for detailed information.

Schema Exploration

Using the Playground

The best way to explore the API schema is through the Playground:

Open: https://adp-api.dreamlab.pl/playground
Authenticate: Add headers (see Authentication)
Browse Schema: Click "Docs" to explore types and fields
Auto-complete: Start typing to see available fields

Schema Documentation

In Playground, click on any type to see:

Fields: Available fields and their types
Arguments: Query parameters (filter, sort, limit, offset)
Description: Field documentation
Deprecation: Deprecated fields (avoid these)

Introspection Query

Get schema information programmatically:

{
  __schema {
    queryType {
      fields {
        name
        description
      }
    }
  }
}

Common Query Patterns

All domain operations support these standard parameters:

Filtering

Operator-based filtering (see Filtering :

query GetFilteredLineitems($filter: JSON) {
  dream_adserver {
    lineitems(filter: $filter) {
      edges {
        lineitem_id
        lineitem_name
      }
    }
  }
}

Variables:

{
  "filter": {
    "lineitem_type": {"=": "DISPLAY"},
    "lineitem_is_archived": {"=": false}
  }
}

Sorting

Lowercase sort directions (see Sorting):

query GetSortedLineitems($sort: JSON) {
  dream_adserver {
    lineitems(sort: $sort, limit: 10) {
      edges {
        lineitem_id
        lineitem_name
      }
    }
  }
}

Variables:

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

🚧
Sort direction MUST be lowercase ("desc", not "DESC"). See Common Mistakes.

Pagination

Offset-based pagination (see Pagination):

query GetPaginatedLineitems {
  dream_adserver {
    lineitems(limit: 25, offset: 0) {
      edges {
        lineitem_id
        lineitem_name
      }
      total_count
    }
  }
}

Complete Example

Here's a complete query combining all patterns:

query GetCampaigns($filter: JSON, $sort: JSON, $limit: Int, $offset: Int) {
  dream_adserver {
    lineitems(
      filter: $filter
      sort: $sort
      limit: $limit
      offset: $offset
    ) {
      edges {
        lineitem_id
        lineitem_name
        lineitem_type
        lineitem_status
        deal_id
        deal_name
        lineitem_start_date
        lineitem_end_date
      }
      total_count
    }
  }
}

Variables:

{
  "filter": {
    "lineitem_type": {"=": "DISPLAY"},
    "lineitem_is_archived": {"=": false}
  },
  "sort": {
    "lineitem_start_date": "desc"
  },
  "limit": 10,
  "offset": 0
}

Best Practices

1. Always Use Variables for JSON Parameters

❌ WRONG: Inline JSON

query {
  dream_adserver {
    lineitems(filter: {field: {"=": "value"}}) {
      edges { lineitem_id }
    }
  }
}

✅ CORRECT: GraphQL variables

query GetLineitems($filter: JSON) {
  dream_adserver {
    lineitems(filter: $filter) {
      edges { lineitem_id }
    }
  }
}

2. Request Only Needed Fields

Bad (requesting unnecessary fields):

query {
  dream_adserver {
    lineitems {
      edges {
        lineitem_id
        lineitem_name
        lineitem_description
        lineitem_target
        lineitem_states
        # ... 50 more fields
      }
    }
  }
}

Good (only what you need):

query {
  dream_adserver {
    lineitems {
      edges {
        lineitem_id
        lineitem_name
        lineitem_status
      }
    }
  }
}

3. Use Pagination for Large Result Sets

Always use limit to avoid timeouts:

query {
  dream_adserver {
    lineitems(limit: 100, offset: 0) {
      edges { lineitem_id }
      total_count
    }
  }
}

4. Check total_count Before Pagination

query {
  dream_adserver {
    lineitems(limit: 1) {
      total_count  # Check this first
    }
  }
}

Then calculate pages needed.

Next Steps

Learn Common Mistakes - Avoid the 4 critical errors
Explore Delivery APIs - Manage campaigns and creatives
Master Filtering - Use operator-based filters
Understand Sorting - Learn the lowercase requirement

Need Help?

Playground: Explore schema at https://adp-api.dreamlab.pl/playground
Documentation: Browse API Reference
Support: Email [email protected]