Programmatically manage advertising campaigns, audiences, and performance metrics for account-based advertising.
openapi: 3.1.0
info:
title: Demandbase Advertising API
description: >-
Programmatically manage advertising campaigns, audiences, and performance
metrics for account-based advertising. Create and manage targeted B2B ad
campaigns, define audience segments, and retrieve campaign analytics.
version: '1.0'
contact:
name: Demandbase Support
url: https://support.demandbase.com/
termsOfService: https://www.demandbase.com/terms-of-service/
externalDocs:
description: Demandbase Advertising API Documentation
url: https://docs.demandbase.com/docs/advertising-api
servers:
- url: https://api.demandbase.com/advertising
description: Demandbase Advertising API Production
tags:
- name: Analytics
description: Retrieve campaign performance metrics
- name: Audiences
description: Create and manage audience segments
- name: Campaigns
description: Manage advertising campaigns
security:
- bearerAuth: []
paths:
/campaigns:
get:
operationId: listCampaigns
summary: Demandbase List campaigns
description: >-
Retrieve a list of advertising campaigns with optional filtering
by status, date range, and other parameters.
tags:
- Campaigns
parameters:
- name: status
in: query
required: false
description: Filter by campaign status
schema:
type: string
enum:
- active
- paused
- completed
- draft
- name: limit
in: query
required: false
description: Maximum number of results
schema:
type: integer
default: 25
maximum: 100
- name: offset
in: query
required: false
description: Pagination offset
schema:
type: integer
default: 0
responses:
'200':
description: List of campaigns
content:
application/json:
schema:
type: object
properties:
campaigns:
type: array
items:
$ref: '#/components/schemas/Campaign'
total:
type: integer
'401':
description: Unauthorized
post:
operationId: createCampaign
summary: Demandbase Create a campaign
description: Create a new advertising campaign with targeting and budget settings.
tags:
- Campaigns
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignRequest'
responses:
'201':
description: Campaign created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
description: Invalid request
'401':
description: Unauthorized
/campaigns/{campaignId}:
get:
operationId: getCampaign
summary: Demandbase Get a campaign
description: Retrieve details of a specific advertising campaign.
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/campaignId'
responses:
'200':
description: Campaign details
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'401':
description: Unauthorized
'404':
description: Campaign not found
put:
operationId: updateCampaign
summary: Demandbase Update a campaign
description: Update an existing advertising campaign.
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/campaignId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignRequest'
responses:
'200':
description: Campaign updated
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
description: Invalid request
'401':
description: Unauthorized
'404':
description: Campaign not found
delete:
operationId: deleteCampaign
summary: Demandbase Delete a campaign
description: Delete an advertising campaign.
tags:
- Campaigns
parameters:
- $ref: '#/components/parameters/campaignId'
responses:
'204':
description: Campaign deleted
'401':
description: Unauthorized
'404':
description: Campaign not found
/campaigns/{campaignId}/analytics:
get:
operationId: getCampaignAnalytics
summary: Demandbase Get campaign analytics
description: >-
Retrieve performance analytics for a specific campaign including
impressions, clicks, spend, and account-level engagement metrics.
tags:
- Analytics
parameters:
- $ref: '#/components/parameters/campaignId'
- name: start_date
in: query
required: false
description: Start date for analytics (YYYY-MM-DD)
schema:
type: string
format: date
- name: end_date
in: query
required: false
description: End date for analytics (YYYY-MM-DD)
schema:
type: string
format: date
responses:
'200':
description: Campaign analytics data
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignAnalytics'
'401':
description: Unauthorized
'404':
description: Campaign not found
/audiences:
get:
operationId: listAudiences
summary: Demandbase List audiences
description: Retrieve a list of audience segments for advertising targeting.
tags:
- Audiences
parameters:
- name: limit
in: query
required: false
schema:
type: integer
default: 25
- name: offset
in: query
required: false
schema:
type: integer
default: 0
responses:
'200':
description: List of audiences
content:
application/json:
schema:
type: object
properties:
audiences:
type: array
items:
$ref: '#/components/schemas/Audience'
total:
type: integer
'401':
description: Unauthorized
post:
operationId: createAudience
summary: Demandbase Create an audience
description: Create a new audience segment for advertising targeting.
tags:
- Audiences
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAudienceRequest'
responses:
'201':
description: Audience created
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
'400':
description: Invalid request
'401':
description: Unauthorized
/audiences/{audienceId}:
get:
operationId: getAudience
summary: Demandbase Get an audience
description: Retrieve details of a specific audience segment.
tags:
- Audiences
parameters:
- $ref: '#/components/parameters/audienceId'
responses:
'200':
description: Audience details
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
'401':
description: Unauthorized
'404':
description: Audience not found
delete:
operationId: deleteAudience
summary: Demandbase Delete an audience
description: Delete an audience segment.
tags:
- Audiences
parameters:
- $ref: '#/components/parameters/audienceId'
responses:
'204':
description: Audience deleted
'401':
description: Unauthorized
'404':
description: Audience not found
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth 2.0 bearer token for API access
parameters:
campaignId:
name: campaignId
in: path
required: true
description: Campaign unique identifier
schema:
type: string
audienceId:
name: audienceId
in: path
required: true
description: Audience unique identifier
schema:
type: string
schemas:
Campaign:
type: object
properties:
id:
type: string
description: Campaign unique identifier
name:
type: string
description: Campaign name
status:
type: string
enum:
- active
- paused
- completed
- draft
description: Campaign status
budget:
type: number
description: Campaign budget in USD
daily_budget:
type: number
description: Daily budget cap in USD
start_date:
type: string
format: date
description: Campaign start date
end_date:
type: string
format: date
description: Campaign end date
audience_id:
type: string
description: Associated audience segment ID
created_at:
type: string
format: date-time
description: Campaign creation timestamp
updated_at:
type: string
format: date-time
description: Last update timestamp
CreateCampaignRequest:
type: object
required:
- name
- budget
- start_date
properties:
name:
type: string
description: Campaign name
budget:
type: number
description: Campaign budget in USD
daily_budget:
type: number
description: Daily budget cap in USD
start_date:
type: string
format: date
description: Campaign start date
end_date:
type: string
format: date
description: Campaign end date
audience_id:
type: string
description: Target audience segment ID
Audience:
type: object
properties:
id:
type: string
description: Audience unique identifier
name:
type: string
description: Audience segment name
description:
type: string
description: Audience description
account_count:
type: integer
description: Number of accounts in the audience
criteria:
type: object
description: Targeting criteria for the audience
properties:
industries:
type: array
items:
type: string
description: Target industries
employee_ranges:
type: array
items:
type: string
description: Target employee count ranges
revenue_ranges:
type: array
items:
type: string
description: Target revenue ranges
countries:
type: array
items:
type: string
description: Target countries
created_at:
type: string
format: date-time
description: Audience creation timestamp
CreateAudienceRequest:
type: object
required:
- name
properties:
name:
type: string
description: Audience segment name
description:
type: string
description: Audience description
criteria:
type: object
properties:
industries:
type: array
items:
type: string
employee_ranges:
type: array
items:
type: string
revenue_ranges:
type: array
items:
type: string
countries:
type: array
items:
type: string
CampaignAnalytics:
type: object
properties:
campaign_id:
type: string
description: Campaign identifier
impressions:
type: integer
description: Total impressions served
clicks:
type: integer
description: Total clicks
ctr:
type: number
description: Click-through rate
spend:
type: number
description: Total spend in USD
accounts_reached:
type: integer
description: Number of unique accounts reached
accounts_engaged:
type: integer
description: Number of accounts showing engagement
cpm:
type: number
description: Cost per thousand impressions
start_date:
type: string
format: date
description: Analytics period start
end_date:
type: string
format: date
description: Analytics period end