Launch a Delivr DSP Campaign with the API
Use Case
- Build Delivr DSP campaigns from your own system instead of the dashboard's campaign wizard
- Go from an audience to a live campaign in a handful of calls: create a draft, add a creative, launch, and watch it go live
You describe what the campaign should do: its goal, audiences, budget, flight and bid. Delivr composes the Delivr DSP settings from that, the same way the dashboard's campaign wizard does. A campaign is created as a draft and spends nothing until you launch it.
Prerequisites
- Organization API key + secret pair (Authentication) with the
campaigns:writescope. Campaign writes need this scope separately from read access. To get it, create a key in Settings > API keys with Campaign writes ticked. To add it to an existing key, choose Allow campaign management from the key's menu. The key can then create and launch campaigns that spend your media budget. Without it, every write below answers403with"required_scopes": ["campaigns:write"]. - A project with a Delivr DSP integration. Every new project gets one automatically. Step 1 checks for it.
- An audience in that project that has finished building (Intent Audiences API).
- An image for the creative, and the page a click should land on.
Steps
1. Confirm the Project's Delivr DSP Integration
curl "https://api.delivr.ai/api/v1/integrations?project_id=YOUR_PROJECT_ID&type=delivrdsp" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET"You never pass the integration's id: Delivr finds it from the project. If the list is empty, set up Delivr DSP first, or the create in step 3 answers 400 with project has no delivrdsp integration. Step 1 of Activate an Audience to Delivr DSP says how.
2. Check the Audience
curl "https://api.delivr.ai/api/v1/audiences/4769" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET"{
"id": 4769,
"project_id": "YOUR_PROJECT_ID",
"segmentation_type": "Audience",
"status": "Completed"
}Launch checks four things about each audience: it is in the campaign's project, its status is Completed, it is not paused, and its segmentation_type is not Account. An account audience targets companies, which have no identifiers a campaign can reach.
3. Create the Campaign Draft
curl -X POST "https://api.delivr.ai/api/v1/campaigns" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"project_id": "YOUR_PROJECT_ID",
"name": "Q4 in-market buyers",
"goal": "demand",
"audience_ids": ["4769"],
"budget": 5000,
"daily_budget": 250,
"start_date": "2026-11-10",
"flight_days": 30,
"bid_cpm": 12
}'Audience ids go in audience_ids as strings. goal is one of tagging, awareness, demand or opportunity, and seeds the pacing, default bid and content category. Money is in your account's dollars. Every other setting is optional. See Create campaign for targeting, frequency caps, exchanges and the rest.
The answer is 201 with the draft. Note its id. The budget you sent as budget reads back as total_budget.
{
"id": "c3f1a9d2-7b4e-4c8a-9f2d-1e0b6a5c4d3e",
"project_id": "YOUR_PROJECT_ID",
"name": "Q4 in-market buyers",
"status": "draft",
"delivery": "not_started",
"total_budget": 5000,
"daily_budget": 250,
"start_date": "2026-11-10"
}Add ?dry_run=true to the same request to see the draft without storing it. An unknown or misspelled field is refused with 400 naming it, so nothing you send is silently dropped.
4. Upload the Creative's Image
Ask for an upload URL:
curl -X POST "https://api.delivr.ai/api/v1/campaigns/CAMPAIGN_ID/files/presign" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"filename": "q4-banner-300x250.png",
"content_type": "image/png",
"size_bytes": 48213,
"file_type": "image_creative"
}'{
"upload_url": "https://...",
"method": "POST",
"fields": { "key": "...", "policy": "...", "...": "..." },
"s3_key": "YOUR_S3_KEY",
"expires_at": "2026-11-01T14:15:00Z"
}Upload within 15 minutes. For "method": "POST" (files of 5 MB or less), send every entry of fields as a form field, then the file as file:
curl -X POST "UPLOAD_URL" \
-F "key=..." -F "policy=..." \
-F "[email protected]"For "method": "PUT" (larger files), send the bytes with the same content type:
curl -X PUT "UPLOAD_URL" -H "Content-Type: image/png" --upload-file q4-banner-300x250.pngThen record the upload:
curl -X POST "https://api.delivr.ai/api/v1/campaigns/CAMPAIGN_ID/files/confirm" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"s3_key": "YOUR_S3_KEY",
"file_type": "image_creative",
"width": 300,
"height": 250
}'The answer is 201 with a file_id.
5. Add the Creative
curl -X POST "https://api.delivr.ai/api/v1/campaigns/CAMPAIGN_ID/creatives" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"type": "IMAGE",
"name": "Q4 banner 300x250",
"file_id": "FILE_ID",
"destination_url": "https://www.example.com/q4",
"ad_domains": "example.com"
}'The creative is created as a draft. Launching the campaign activates it, so there is nothing more to do here. To add several at once, use Create campaign creatives in batch.
6. Launch
curl -X POST "https://api.delivr.ai/api/v1/campaigns/CAMPAIGN_ID/launch" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET"Send no body. The answer is 202 with status activating.
Launch checks the campaign first. It refuses with 400 and names what is wrong. The cause is a missing budget, a campaign targeting audiences that names none, or an audience that fails the checks in step 2. Where your account funds campaigns in advance and the project cannot cover the budget, it answers 402 with the shortfall. Only a draft, or a campaign whose launch failed before it reached Delivr DSP, can be launched. Anything else answers 409, so a retried request never creates a second campaign.
7. Poll Until Live
curl "https://api.delivr.ai/api/v1/campaigns/CAMPAIGN_ID" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET"While Delivr sets the campaign up at Delivr DSP and attaches each audience, status reads activating, with nothing for you to do. It becomes active once the campaign can spend. delivery then says whether it is spending right now: scheduled before the start date, live while serving.
If setup stops, status reads blocked with a reason:
action_required: Delivr DSP refused something you can change.decline_reasonsays what.setup_failed: the failure was on Delivr's side.unknown: contact support rather than changing the campaign.
A campaign without a creative it can serve stays activating, so make sure step 5 succeeded.
Changing a Campaign Later
Send only the fields to change to Update campaign. The body is a JSON merge patch: a field you leave out keeps its value and null clears it.
curl -X PUT "https://api.delivr.ai/api/v1/campaigns/CAMPAIGN_ID?dry_run=true" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "X-Api-Secret: YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{ "budget": 8000 }'With ?dry_run=true the answer lists the fields that would move in changes. Drop it to apply. A launched campaign's change goes to Delivr DSP before it is stored. Its audiences cannot be changed after launch.
The rest of the lifecycle has its own calls, all needing campaigns:write:
- Pause campaign and Resume campaign stop and restart serving.
- Archive or delete campaign archives a campaign that ran, keeping its reporting, and deletes one that never did.
- Attach list and Detach list change a draft's lists. Excluded audiences can still change after launch, through
excluded_audience_idson Update campaign. - Set domain list, Set tracking defaults and Set conversion manage where it serves and how it is measured.
- List campaign creatives, Update campaign creative, Pause campaign creative, Resume campaign creative and Archive campaign creative manage its creatives.
Updated 17 days ago
