Campaigns — API Routes

Related: Data Model | Workflow & Permissions | API structure

All campaign routes are registered under the tenant prefix: /tenant/v1/campaigns.

The existing DM portal routes at /dm/v1/campaigns cover the backlink-outreach campaign read/send flow and should be aligned to the generalised model as part of this work.

Route Index

Flow A — Import Campaigns from Platform

Allows the DM team to discover campaigns already running on a connected ad account (Google Ads, Meta Ads, LinkedIn Ads) and import them into Leadmetrics so their metrics can be tracked.

GET /tenant/v1/campaigns/import

Fetches the list of campaigns currently available on the connected platform. Calls the platform API live — does not read from the DB.

Query params:

Response:

{
  campaigns: {
    externalCampaignId: string;   // platform's own ID
    name: string;
    status: string;               // as reported by the platform (enabled, paused, etc.)
    budget?: number;
    startDate?: string;
    endDate?: string;
    alreadyImported: boolean;     // true if a CampaignExternalMapping already exists
  }[];
}

For Google Ads: calls getCampaignsAsLookup() from packages/providers/google/src/google-ads.ts (already implemented).

For Meta Ads: calls the Meta Ads campaigns endpoint via packages/providers/meta/src/facebook.ts.

POST /tenant/v1/campaigns/import

Imports one or more selected platform campaigns into Leadmetrics. For each selected campaign:

1. Creates a Campaign record (type: paid_ads, source: imported, status: active or paused to mirror platform status)
2. Creates a CampaignExternalMapping record linking the Leadmetrics campaign to the external campaign ID
3. Immediately triggers a metrics sync (enqueues the relevant insights worker)

Body:

{
  connectedChannelId: string;
  platform: "google_ads" | "meta_ads" | "linkedin_ads";
  campaigns: {
    externalCampaignId: string;
    name: string;
    budget?: number;
    startDate?: string;
    endDate?: string;
  }[];
  deliverablePeriodId?: string;   // optional — link all imported campaigns to a period
}

Response: Array of created Campaign records with their CampaignExternalMapping.

POST /tenant/v1/campaigns/:id/link-external

Links an existing Leadmetrics campaign (created via the wizard) to an external platform campaign. Used when a DM creates a campaign in Leadmetrics first and then launches it on the platform.

Body:

{
  connectedChannelId: string;
  platform: "google_ads" | "meta_ads" | "linkedin_ads";
  externalCampaignId: string;
  externalCampaignName: string;
}

Creates a CampaignExternalMapping record. If a mapping already exists for this platform on this campaign, returns a 409.

Flow B — Metrics Sync

Pulls per-campaign metrics from the platform using the externalCampaignId stored in CampaignExternalMapping and writes structured rows to CampaignMetrics.

This is a significant change from the current behaviour where google-ads-insights and meta-ads-insights workers write a single narrative text blob to ChannelInsight for the whole ad account. For campaigns, they are extended to also write structured per-campaign metric rows.

Sync trigger options:

Per-campaign sync flow:

CampaignExternalMapping.externalCampaignId
        │
        ▼
Platform API call scoped to that campaign ID
  └─ Google: GAQL filtered by campaign.id
  └─ Meta:   GET /act_{adAccountId}/insights?filtering=[{field:"campaign.id",operator:"IN",value:[externalId]}]
        │
        ▼
Structured metrics written to CampaignMetrics rows
(one row per day per channel)
        │
        ▼
CampaignExternalMapping.lastSyncedAt updated

The existing ChannelInsight AI narrative (account-level) continues to work unchanged alongside this. They serve different purposes: ChannelInsight is a broad account health summary; CampaignMetrics is granular per-campaign data for the Performance tab.

Campaign CRUD

GET /tenant/v1/campaigns

List all campaigns for the tenant.

Query params:

Response: Paginated list of campaigns with type, channel badges, status, goal, date range, and the primary performance metric for that campaign type (CTR for paid ads, open rate for email, etc.).

POST /tenant/v1/campaigns

Create a new campaign.

Body:

{
  name: string;
  type: CampaignType;
  channel: string[];
  goal: CampaignGoal;
  budget?: number;
  budgetCurrency?: string;
  startDate?: string;
  endDate?: string;
  deliverablePeriodId?: string;  // optional link to DeliverablePeriod
}

Creates the campaign in draft status. Does not trigger any agent automatically.

GET /tenant/v1/campaigns/:id

Get full campaign detail including:

• Campaign fields + brief
• Linked CampaignAudience[]
• CampaignMetrics summary (latest snapshot per channel)
• Linked Activity[] (via Activity.campaignId)
• CampaignSequence[] (email/review campaigns only)

PATCH /tenant/v1/campaigns/:id

Update editable campaign fields: name, budget, budgetCurrency, startDate, endDate, brief, autoPilotEnabled, deliverablePeriodId.

Status transitions use a dedicated route (see below) — cannot be set directly via PATCH.

DELETE /tenant/v1/campaigns/:id

Soft delete — sets status to archived. Does not hard-delete any records.

Campaign Workflow

POST /tenant/v1/campaigns/:id/generate-brief

Enqueues the campaign-brief-writer agent. Transitions campaign to dm_review once brief is ready.

Body:

{
  targetAudienceDescription: string;
}

POST /tenant/v1/campaigns/:id/generate-audience

Enqueues the audience-analyst agent. Results stored as CampaignAudience records.

PATCH /tenant/v1/campaigns/:id/status

Advance or reverse the campaign workflow status. Role-gated — see Workflow & Permissions.

Body:

{
  status: CampaignStatus;
  note?: string;   // optional reason for rejection / change
}

POST /tenant/v1/campaigns/:id/approve

Client-facing approval endpoint. Only callable when status === "client_review" and the caller has reviewer role. Transitions to client_approved.

Body:

{
  approved: boolean;
  note?: string;
}

Campaign Content

GET /tenant/v1/campaigns/:id/content

List all Activity records where Activity.campaignId === id. Returns the activity type, status, output payload summary, and associated content entity (BlogPost, SocialPost, etc.).

POST /tenant/v1/campaigns/:id/content

Create a new Activity linked to this campaign. Triggers the appropriate agent worker based on the activity’s deliverableType.

Body:

{
  deliverableType: string;    // google_ads_copy | meta_ads_copy | email_newsletter | social_post | etc.
  inputPayload: object;       // agent-specific input
}

Campaign Metrics

GET /tenant/v1/campaigns/:id/metrics

Return CampaignMetrics[] for the campaign, optionally filtered by channel and date range.

Query params: channel?, from?, to?, granularity? (day | week | month)

POST /tenant/v1/campaigns/:id/metrics/sync

Trigger a manual pull of metrics from the connected channel APIs for this campaign. Reads CampaignExternalMapping to find the externalCampaignId and enqueues the relevant insights worker scoped to that campaign.

Returns 400 if no CampaignExternalMapping exists for the campaign (i.e. the campaign has not been linked to a platform campaign yet).

GET /tenant/v1/campaigns/:id/metrics/insights

Return the latest AI-generated optimisation recommendations from google-ads-insights / meta-ads-insights / ads-analyst for this campaign.

Keywords (Google Ads — paid_ads type only)

These routes are only applicable to campaigns with platform: google_ads in their CampaignExternalMapping.

POST /tenant/v1/campaigns/:id/keywords/sync

Sync ad groups, keywords, and existing negative keywords from Google Ads into the DB (AdGroup, CampaignKeyword, NegativeKeyword tables). Uses the externalCampaignId from CampaignExternalMapping.

Updates CampaignExternalMapping.lastSyncedAt on completion.

GET /tenant/v1/campaigns/:id/keywords

List all CampaignKeyword records for this campaign.

Query params: adGroupId?, status? (enabled | paused | removed), matchType?, page?, limit?

Response: Keywords with match type, status, bid, quality score, and last-sync metrics (impressions, clicks, CTR, avg CPC, conversions).

PATCH /tenant/v1/campaigns/:id/keywords/:keywordId

Update a keyword’s bid or status. Pushes the change to Google Ads API immediately (no approval workflow — bid adjustments are a DM-only action).

Body:

{
  bidMicros?: number;
  status?: "enabled" | "paused";
}

GET /tenant/v1/campaigns/:id/ad-groups

List all AdGroup records for this campaign with name, status, and default bid.

Search Terms (Google Ads — paid_ads type only)

POST /tenant/v1/campaigns/:id/search-terms/sync

Pull search term data from search_term_view via GAQL for the specified date range and store as SearchTermReport rows. Deduplicates by (campaignId, searchTerm, syncDate).

Body:

{
  from: string;   // ISO date
  to: string;     // ISO date
}

GET /tenant/v1/campaigns/:id/search-terms

List SearchTermReport rows joined with their SearchTermClassification (if classified).

Query params: classified? (boolean — filter to classified or unclassified), classification? (add_as_keyword | add_as_negative | watch | irrelevant), page?, limit?

POST /tenant/v1/campaigns/:id/search-terms/classify

Trigger the search-term-classifier agent on all unclassified SearchTermReport rows for this campaign. Creates SearchTermClassification records with status: pending.

PATCH /tenant/v1/campaigns/:id/search-terms/:reportId/classification

DM reviews and accepts or overrides the AI classification for a single search term.

Body:

{
  dmDecision: "add_as_keyword" | "add_as_negative" | "watch" | "irrelevant";
}

Sets SearchTermClassification.dmDecision and status: dm_reviewed.

POST /tenant/v1/campaigns/:id/search-terms/push-negatives

Push all dm_reviewed search terms classified as add_as_negative to Google Ads as negative keywords. For each:

1. Creates a NegativeKeyword record (source: search_term_classification, status: pending_push)
2. Calls addNegativeKeyword() on the Google Ads provider
3. Stores externalCriterionId returned from the API
4. Updates NegativeKeyword.status → active and SearchTermClassification.status → pushed

Body:

{
  matchType: "broad" | "phrase" | "exact";  // match type to apply to all pushed negatives
}

Negative Keywords (Google Ads — paid_ads type only)

GET /tenant/v1/campaigns/:id/negative-keywords

List all NegativeKeyword records for this campaign, including source (manual or search_term_classification) and status.

Query params: adGroupId? (null = campaign-level), status?

POST /tenant/v1/campaigns/:id/negative-keywords

Manually add a negative keyword to the campaign. Creates a NegativeKeyword record and immediately pushes to Google Ads API.

Body:

{
  keyword: string;
  matchType: "broad" | "phrase" | "exact";
  adGroupId?: string;   // null = campaign-level negative
}

DELETE /tenant/v1/campaigns/:id/negative-keywords/:negativeKeywordId

Remove a negative keyword. Calls removeNegativeKeyword() on the Google Ads provider using externalCriterionId, then sets NegativeKeyword.status → removed.

GET /tenant/v1/campaigns/:id/audience

List all CampaignAudience segments for this campaign.

POST /tenant/v1/campaigns/:id/audience

Add an audience segment manually or confirm an AI-suggested segment.

Body:

{
  name: string;
  segmentType: "crm_segment" | "platform_audience" | "custom_list";
  filters?: object;
  estimatedSize?: number;
  platformAudienceId?: string;
}

PATCH /tenant/v1/campaigns/:id/audience/:segmentId

Update a segment’s filters, name, or platform audience ID.

DELETE /tenant/v1/campaigns/:id/audience/:segmentId

Remove an audience segment from the campaign.

Email Sequences (email_marketing type)

GET /tenant/v1/campaigns/:id/sequences

List all CampaignSequence records for this campaign.

POST /tenant/v1/campaigns/:id/sequences

Create an email drip sequence.

Body:

{
  name: string;
  triggerType: "on_subscribe" | "on_date" | "manual";
}

PATCH /tenant/v1/campaigns/:id/sequences/:seqId/steps/:stepId

Edit the content of a sequence step (subject, body, delay).

POST /tenant/v1/campaigns/:id/sequences/:seqId/activate

Activate a sequence — pushes the first step to Mailchimp / Klaviyo and schedules subsequent steps.

Review Drip (review_generation type)

POST /tenant/v1/campaigns/:id/review-sequence

Trigger the review-campaign-writer agent to generate the drip sequence. Result stored in ReviewCampaign.sequence.

Body:

{
  reviewPlatform: string;
  reviewUrl: string;
  tone: "friendly" | "professional" | "casual";
  stepCount?: number;
  channel: "email" | "sms";
}

POST /tenant/v1/campaigns/:id/review-sequence/send

Dispatch the next pending step of the review drip to the contact list.

Optimization Recommendations

GET /tenant/v1/campaigns/:id/optimizations

List all CampaignOptimizationRecommendation records for the campaign, ordered by priority then createdAt desc. Optionally filter by status or platform.

Query params: ?status=pending&platform=meta_ads

Response: Array of recommendations with title, rationale, suggestedAction, estimatedImpact, priority, status.

POST /tenant/v1/campaigns/:id/optimizations/trigger

Manually trigger an optimization scan for this campaign (instead of waiting for the weekly cron). Enqueues meta-ads-optimizer and/or linkedin-ads-optimizer based on which platforms the campaign is running on.

Only admin and member roles can call this.

PATCH /tenant/v1/campaigns/:id/optimizations/:recommendationId

Update the status of a single recommendation. Role-gated actions:

Optionally include { note: string } to populate dmNote or clientNote.

POST /tenant/v1/campaigns/:id/optimizations/:recommendationId/apply

Push an approved recommendation to the platform. Only callable when status = client_approved (or dm_approved for budget/bid changes under threshold). Executes the suggestedAction payload against the relevant provider (Meta Marketing API or LinkedIn Ads API), then sets status → applied and stamps appliedAt.

Only admin role can call this.

Files

Provider Extensions

New methods needed in the provider packages to support the routes above.

packages/providers/google/src/google-ads.ts

packages/providers/meta/src/facebook.ts

packages/providers/linkedin/src/linkedin-ads.ts (new file)