Create campaign

post

https://api.delivr.ai/api/v1/campaigns

Create a DelivrDSP campaign from what you want it to do: a goal, audiences, budget, flight and bid. Delivr composes the DelivrDSP settings from that (the bid range, contracted terms, end date and pacing) the same way the dashboard's campaign wizard does.

The campaign is always created as a draft. Nothing is sent to DelivrDSP and nothing spends until you call Launch campaign. The worked example is Launch a DelivrDSP Campaign with the API.

Needs the campaigns:write scope. Every campaign write needs this scope on your API key, separately from read access. A key without it is refused with 403 and required_scopes: ["campaigns:write"]. Contact support to enable it for your key.

The project must have a DelivrDSP integration. It is looked up from project_id, so the body does not name one.

Money (budget, daily_budget, the bid fields, contracted and fine_tune.monthly_budget) is in your account's dollars, the same dollars the campaign reads report.

Unknown fields are refused with 400 naming the field, so a misspelled key is never silently dropped. Other refusals also name the field and the problem, in a plain-text body. The missing-scope 403 is the one JSON refusal.

Add ?dry_run=true to compose without storing anything: the answer is 200 with the draft that would be created.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

dry_run

boolean

Defaults to false

true to compose and check the write without storing anything or calling DelivrDSP.

Body Params

What the campaign should do. Delivr composes the DelivrDSP settings from it. On create, project_id, name and goal are required. On update every field is optional: a field left out keeps its value and null clears it.

Money is in your account's dollars.

project_id

uuid

The project the campaign belongs to. Required on create. On update, if sent, it must be the campaign's own.

name

string

length between 3 and 120

goal

string

enum

What the campaign is for. It seeds the pacing, the default bid and the content category, which the fields below override.

Allowed:

campaign_type

string

enum

The format bought. Omit it for an untyped campaign. A typed campaign buys through an Index Exchange deal, and some types cannot carry an audience or run every goal; such a combination is refused naming why.

Allowed:

audience_ids

array of strings

Audiences to reach, at most 25 distinct. Each must have finished building, and be a people audience, by launch.

audience_ids

excluded_audience_ids

array of strings

Audiences not to reach. None may also be in audience_ids.

excluded_audience_ids

targeting_mode

string

enum

Defaults to audience

no_audience serves with no audience list. Naming audiences or exclusions with it is refused.

Allowed:

budget

double

Total budget. Required to launch.

daily_budget

double

Spend cap per day. At most budget.

start_date

date

First day, YYYY-MM-DD.

flight_days

integer

7 to 90

How many days the campaign runs. The end date is derived from it. Defaults from the goal.

bid_cpm

double

The price to bid per thousand impressions. Defaults from the goal.

cpm_min

double

Lowest bid. Defaults to bid_cpm. At most cpm_max.

cpm_max

double

Highest bid. Defaults to bid_cpm.

optimization_type

string

enum

How DelivrDSP adjusts the bid.

bid_targets

object

Targets the optimization type reads, by name. A name it does not read is refused.

content_category_id

string

The IAB content category. Defaults from the goal.

contracted

object

The contracted terms DelivrDSP requires. Derived from the budget and the bid unless you set them.

fine_tune

object

Pacing, frequency caps and performance floors. Each is optional, and the goal seeds the frequency caps.

targeting

object

inventory

object

bidding

object

DelivrDSP bidding switches.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

401

Missing or invalid authentication.

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

text/plain

200With dry_run=true: the draft that would be created. Nothing is stored.

201The draft. status is draft, delivery is not_started, and warnings carries any advice on the bid.

400The body names an unknown field, a value of the wrong type, or a value outside what a campaign accepts; project_id, name or goal is missing; or the project has no DelivrDSP integration. The plain-text body names the problem.

403The key does not hold campaigns:write (JSON, below), or project_id is outside the key's organization or project binding (plain text: project_id does not match API key scope).