DISPL Ads External DSP API - Product Overview

The DISPL Ads External DSP API is a robust programmatic interface designed to facilitate integration of external Demand-Side Platforms (DSPs) into the DOOH advertising ecosystem. This tool helps agencies and advertisers to automate the entire lifecycle of Digital Out-of-Home (DOOH) advertising campaigns, from initial draft creation and targeting to real-time bidding and comprehensive performance reporting.

Integration Architecture

The operational framework of the DISPL Ads API is built for four primary entities: 

• the end-user Device;

• the DI Bidder; 

• the UT Exchange;

• and the External DSP. 

The process begins with the External DSP creating a request and providing ad media to the UT Exchange. When an ad request is triggered by a device, the DI Bidder initiates an internal bid request, which may optionally be extended as an external bid request to the DSP. The DSP responds with campaign data, which undergoes an audit process to ensure compliance before the ad is finally delivered to the device for playback. 

Throughout this cycle, events such as tracking and billing are recorded to provide a transparent audit trail for all participants.

General procedure for connecting an external DSP via API 

Connecting to the DISPL ecosystem follows a structured 17-step general procedure:

1. Gain access to the DSP's personal account and the agency's DSP ID. 

2. Check the agency's balance. If the balance is less than or equal to zero - campaigns are excluded from the auction. 

3. Get a token to access the API. 

4. Programmatically create a draft request for an advertising campaign. 

5. Get a list of ad network devices and add the desired ones to the blacklist or whitelist. 

6. Programmatically get an estimate of the cost of the campaign with specified parameters (audience, duration, territorial restrictions, etc.). 

7. Programmatically set the maximum bid (max_bid) in the draft. 

8. Programmatically add advertising materials to the bid. 

9. Programmatically send the application for approval. 

10. Application must be approved by the advertising surface owner (SSP). 

11. Periodically check the status of the application / promotional materials. If the application / promotional materials are rejected, obtain comments.

12. If the request is approved, an advertising campaign is created based on it (separate entity, campaign property of the approved request) and bidding is started. 

13. (Optional) Retransmission of device requests for auction on the external DSP side. 

14. Programmatically receive bidding progress reports and adjust the maximum bid and other campaign parameters (except for promotional materials). 

15. Programmatically pause/continue playback or end the campaign. 

16. The campaign automatically ends when the goal is reached, either in terms of number of plays/scope/views, budget, or time (end_date). 

17. Get a summary of the playout.

These steps can be summarized like such:

• Access and Compliance: Initial steps require gaining access to a DSP personal account and verifying the agency's DSP ID. A critical requirement is maintaining a positive agency balance; if the balance reaches zero or less, campaigns are automatically excluded from the auction process.

• Campaign Preparation: Users must programmatically create a draft request for an advertising campaign after securing an authorization token. This phase includes managing white-lists or black-lists of specific ad network devices to refine the reach.

• Optimization and Bidding: Before launching, the API allows for a programmatic estimate of campaign costs based on parameters like audience demographics, territorial restrictions, and duration. The DSP then sets the maximum bid ($max\_bid$) and attaches the necessary advertising materials.

• Approval and Execution: All applications must be approved by the advertising surface owner (SSP). Once approved, a separate campaign entity is created, and bidding commences.

• Monitoring and Conclusion: The API supports real-time adjustments to bids and parameters (excluding ad materials) based on bidding progress reports¹⁸. Campaigns conclude automatically once pre-defined goals—such as budget limits, timeframes ($end\_date$), or specific playout scopes—are reached.

   

Security and Authorization Protocols

The DISPL Ads API prioritizes security through a multi-tiered authorization system. Access is managed via two distinct types of tokens: persistent tokens and OAuth-like tokens (access and refresh).

• Token Management: Access tokens have a limited lifetime of 30 minutes, while refresh tokens remain valid for 2 hours²². Permanent tokens are currently issued exclusively through system administrators.

• Header Requirements: All API calls must include the $X-Authorization$ header. Depending on the token type, the format follows either Bearer <access_token> or Token <token>.

• Role-Based Access Control: The system defines specific roles to maintain operational integrity, including dsp (Administrator), ssp_admin, ssp_approve (Moderator), and ssp_viewer (Observer). The active role must be specified in the x-adexchange-role header for every request.

Campaign Targeting and Parameterization

The API provides granular control over campaign settings, allowing advertisers to define their ideal audience with high precision. Campaign requests are submitted as JSON objects to the agency-specific endpoint.

Primary Campaign Parameters

Beyond basic settings, the API supports advanced targeting:

• Geographic Targeting: Through the areas parameter, users can include or exclude specific zones using latitude, longitude, and a defined radius (in kilometers).

  Audience Demographics: Advertisers can filter by age ranges (e.g., 18–65) and gender.

• Scheduling: The time_range (defined in seconds from the start of the day) and a schedule object (allowing for specific day-of-week selections) ensure ads run at the most impactful times.

• Industry Taxonomy: The system supports IAB Content Category Taxonomy versions 1.0 and 2.0 to ensure ads are contextually relevant.

Cost Estimation and Analytics

A vital feature of the DISPL Ads API is the ability to obtain predictive analytics before a campaign goes live. By querying the stats endpoint, DSPs receive a detailed forecast:

• Price Forecasting: Provides a range of rates (minimum, maximum, and average) for the $max\_bid$. If the $max\_bid$ is set below the price.min, the campaign is unlikely to win any auctions.

• Budget and Reach: The API returns the total_max_budget for a goal and forecasts the number of impressions and audience reach based on current rules.

• Inventory Insights: Users can see the number of broadcasting outlets available for their specific parameters and even download an address plan via an excel_url.

Device Network Management

The API offers comprehensive tools for exploring available inventory. DSPs can retrieve a paginated list of devices within an ad network, complete with technical specifications such as screen resolution, orientation (landscape or portrait), and physical location (city, street, and building). Furthermore, an "extended" output format provides localized cost data for different payment models (CPM, CPV, and ad_plays) specific to each device, allowing for highly localized bidding strategies.

This API serves as the technological bridge for external DSPs to engage with DOOH inventory with the same level of sophistication and automation found in traditional digital display advertising.