Product Documentation
  1. Activate

Launch a DelivrDSP Campaign with the API

Use Case

  • Build DelivrDSP 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 DelivrDSP 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:write scope. Campaign writes need this scope separately from read access; contact support to enable it for your key. Without it, every write below answers 403 with "required_scopes": ["campaigns:write"].
  • A project with a DelivrDSP integration. Step 1 of Activate an Audience to DelivrDSP creates one.
  • 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 DelivrDSP 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, create the integration first, or the create in step 3 answers 400 with project has no delivrdsp integration.

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.png

Then 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 and refuses with 400 naming what is wrong: 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 DelivrDSP, 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 DelivrDSP 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: DelivrDSP refused something you can change. decline_reason says 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 DelivrDSP before it is stored. Its audiences cannot be changed after launch.

Updated about 1 hour ago

Did this page help you?