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
- The key carries the scope:
marketing:read:campaigns,marketing:write:campaignsormarketing:read:campaign_metrics. - 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
| Endpoint | Scope | Owner needs | Does |
|---|---|---|---|
GET/marketing/campaigns | marketing:read:campaigns | marketing.campaign.view | List. Filters: status (comma separated), search, page, limit |
GET/marketing/campaigns/:id | marketing:read:campaigns | marketing.campaign.view | The plan: dates, budget, goals, brief, messaging, audience, phases |
GET/marketing/campaigns/:id/performance | marketing:read:campaign_metrics | marketing.campaign.view | Posts, ad spend and pacing, link visitors, goals against targets |
GET/marketing/campaigns/:id/attribution | marketing:read:campaign_metrics | marketing.campaign.view | Credited sales and deals. Query: model, window |
POST/marketing/campaigns | marketing:write:campaigns | marketing.campaign.create | Create a draft campaign |
POST/marketing/campaigns/:id/links | marketing:write:campaigns | marketing.links.manage | Make 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.
Tracked links
POST /api/v1/public/marketing/campaigns/:id/links
{
"destination": "https://shop.example.com/back-to-school",
"label": "Instagram bio",
"channel": "organic:instagram"
}The link gets the campaign's UTM tags and a short address on the workspace's link domain. Tracked links count against the plan's monthly allowance, like links made in the app.
Webhook events
marketing.campaign.createdA campaign was created: by hand, from a template, by a repeat or by an AI teammate. Always a draft.marketing.campaign.approvedThe campaign's plan finished its approval laddermarketing.campaign.launchedIt went live, by hand or on its start datemarketing.campaign.pausedA running campaign was pausedmarketing.campaign.completedIt ended, by hand or on its end datemarketing.campaign.budget_thresholdAd spend reached one of the workspace's alert thresholds (50, 80, 100% by default)marketing.campaign.kpi_reachedA goal measured in Marketing (reach, impressions, clicks, link visitors) reached its target. Once per goal.marketing.promo.redeemedA 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.