Creating Campaigns

Use the POST /v1/campaigns endpoint to create campaigns on any connected ad platform. AdRelay translates your request into the platform-specific format and creates the campaign on your behalf.

Required Fields

Field	Type	Description
`name`	string	Campaign name (max 255 characters)
`goal`	string	Campaign objective: `CONVERSIONS`, `AWARENESS`, `TRAFFIC`, `LEADS`, `SALES`
`budget_amount`	number	Budget amount in your account’s currency
`budget_period`	string	`DAILY` or `LIFETIME`
`platform`	string	Target platform: `google_ads`, `meta_ads`, or `tiktok_ads`

Basic Example

curl -X POST "https://api.adrelay.dev/v1/campaigns" \
  -H "X-API-Key: $ADRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale 2026",
    "goal": "CONVERSIONS",
    "budget_amount": 50.00,
    "budget_period": "DAILY",
    "platform": "google_ads"
  }'

const response = await fetch("https://api.adrelay.dev/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ADRELAY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Summer Sale 2026",
    goal: "CONVERSIONS",
    budget_amount: 50.0,
    budget_period: "DAILY",
    platform: "google_ads",
  }),
});

const campaign = await response.json();

import requests

response = requests.post(
    "https://api.adrelay.dev/v1/campaigns",
    headers={
        "X-API-Key": "your-api-key-here",
        "Content-Type": "application/json",
    },
    json={
        "name": "Summer Sale 2026",
        "goal": "CONVERSIONS",
        "budget_amount": 50.00,
        "budget_period": "DAILY",
        "platform": "google_ads",
    },
)

campaign = response.json()

Response

{
  "id": "camp_new789",
  "platform": "google_ads",
  "remote_id": "555666777",
  "name": "Summer Sale 2026",
  "status": "PAUSED",
  "goal": "CONVERSIONS",
  "budget_amount": 50.00,
  "budget_period": "DAILY",
  "currency": "USD",
  "created_at": "2026-03-21T10:00:00Z",
  "updated_at": "2026-03-21T10:00:00Z"
}

Default Status

All campaigns are created with a status of PAUSED by default. This gives you the opportunity to review the campaign before it goes live. To activate a campaign, update its status:

curl -X PATCH "https://api.adrelay.dev/v1/campaigns/camp_new789" \
  -H "X-API-Key: $ADRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "ACTIVE"}'

Budget Handling

Daily Budgets

The budget_amount with budget_period: "DAILY" sets the maximum spend per day. Each platform handles daily budgets slightly differently:

Google Ads — May spend up to 2x the daily budget on high-traffic days, but averages out over the month.
Meta Ads — May spend up to 25% more on high-opportunity days.
TikTok Ads — Strictly enforces the daily budget cap.

Lifetime Budgets

Set budget_period: "LIFETIME" to specify a total budget for the campaign’s duration. Note that lifetime budgets may require additional fields on some platforms.

Platform Differences

While AdRelay normalizes the campaign creation interface, there are platform-specific behaviors to be aware of:

Behavior	Google Ads	Meta Ads	TikTok Ads
Minimum daily budget	$1.00	$1.00	$20.00
Budget currency	Account currency	Account currency	Account currency
Campaign goal mapping	Direct	Mapped to objectives	Mapped to objectives
Creation latency	~1-2s	~2-3s	~1-2s

AdRelay validates your request against platform-specific requirements before submitting. If a platform has a higher minimum budget, you will receive a validation error before the campaign is created.

Error Handling

Common creation errors:

Code	Description
`VALIDATION_ERROR`	Missing or invalid fields. Check the `details` object for specifics.
`FORBIDDEN`	No active connection for the specified platform.
`RATE_LIMITED`	Too many requests. Retry after the `Retry-After` period.

Getting Started

Guides

SDKs

Required Fields

Basic Example

Response

Default Status

Budget Handling

Daily Budgets

Lifetime Budgets

Platform Differences

Error Handling

​Required Fields

​Basic Example

​Response

​Default Status

​Budget Handling

​Daily Budgets

​Lifetime Budgets

​Platform Differences

​Error Handling

Required Fields

Basic Example

Response

Default Status

Budget Handling

Daily Budgets

Lifetime Budgets

Platform Differences

Error Handling