Docs

Marketing: Campaigns

Campaigns, their results and attribution, at https://api.zyhap.com/api/v1/public/marketing/campaigns. Pull results into your reporting, draft campaigns from another planning tool, and make tracked links.

Two checks on every request

  1. The key carries the scope: marketing:read:campaigns, marketing:write:campaigns or marketing:read:campaign_metrics.
  2. The person who made the key holds the matching campaign permission, such as marketing.campaign.view, in the workspace the request names, today. Company owners pass this check.

Send the workspace in X-Workspace-ID, as for every Marketing endpoint. Campaigns from other workspaces and branches are never visible.

What the API never does: send a plan for review, approve it, launch, pause or end a campaign, or spend money. A campaign created through the API is a draft; a person in the app takes it from there.

curl https://api.zyhap.com/api/v1/public/marketing/campaigns?status=live \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID"

Endpoints

EndpointScopeOwner needsDoes
GET/marketing/campaignsmarketing:read:campaignsmarketing.campaign.viewList. Filters: status (comma separated), search, page, limit
GET/marketing/campaigns/:idmarketing:read:campaignsmarketing.campaign.viewThe plan: dates, budget, goals, brief, messaging, audience, phases
GET/marketing/campaigns/:id/performancemarketing:read:campaign_metricsmarketing.campaign.viewPosts, ad spend and pacing, link visitors, goals against targets
GET/marketing/campaigns/:id/attributionmarketing:read:campaign_metricsmarketing.campaign.viewCredited sales and deals. Query: model, window
POST/marketing/campaignsmarketing:write:campaignsmarketing.campaign.createCreate a draft campaign
POST/marketing/campaigns/:id/linksmarketing:write:campaignsmarketing.links.manageMake a tracked link for the campaign

CRM numbers (leads, deals, revenue) appear in performance and attribution only when the key's owner may see CRM campaigns. Otherwise the response says they are hidden rather than showing a zero.

Create a draft campaign

name and objective are required. Objectives: awareness, engagement, traffic, leads, sales, app_installs, foot_traffic, retention, event. Money is in minor units with its currency. A budget needs the owner to hold marketing.campaign.budget; without it the request is refused with the reason.

POST /api/v1/public/marketing/campaigns

{
  "name": "Back to school 2027",
  "objective": "sales",
  "startAt": "2027-08-30T08:00:00Z",
  "endAt": "2027-09-20T08:00:00Z",
  "channels": ["organic:instagram", "ads:meta", "email"],
  "budget": { "value": 200000000, "currencyCode": "NGN" },
  "kpis": [{ "metric": "revenue", "target": 5000000, "primary": true }]
}

The answer is the campaign with "status": "draft" and its own code, the short id its tracked links and CRM records carry.

Webhook events

  • marketing.campaign.created A campaign was created: by hand, from a template, by a repeat or by an AI teammate. Always a draft.
  • marketing.campaign.approved The campaign's plan finished its approval ladder
  • marketing.campaign.launched It went live, by hand or on its start date
  • marketing.campaign.paused A running campaign was paused
  • marketing.campaign.completed It ended, by hand or on its end date
  • marketing.campaign.budget_threshold Ad spend reached one of the workspace's alert thresholds (50, 80, 100% by default)
  • marketing.campaign.kpi_reached A goal measured in Marketing (reach, impressions, clicks, link visitors) reached its target. Once per goal.
  • marketing.promo.redeemed A promo code was used on a Sales order

Campaign events carry the campaign (id, name, code, objective, status, dates, budget, workspace) and never the people on it. Status events are sent after the change is saved.

{
  "id": "evt_6c1f...",
  "event": "marketing.campaign.launched",
  "module": "marketing",
  "timestamp": "2027-08-30T08:00:02.000Z",
  "workspace": "665f1c2e9b1e8a0012a4b001",
  "data": {
    "campaign": {
      "id": "6670b1f09b1e8a0012a4c901",
      "name": "Back to school 2027",
      "code": "BTS27",
      "objective": "sales",
      "status": "live",
      "startAt": "2027-08-30T08:00:00.000Z",
      "endAt": "2027-09-20T08:00:00.000Z",
      "budget": { "value": 200000000, "currencyCode": "NGN" },
      "workspaceId": "665f1c2e9b1e8a0012a4b001"
    }
  }
}

Subscribe on the Webhooks page.