Complete REST API reference for the EventZR Ads Service. Manage campaigns, creatives, audiences, ad serving, conversion tracking, reporting, and billing.
All endpoints require a valid JWT bearer token and the x-tenant-id header. Obtain a JWT token from the Auth API.
Authorization: Bearer <jwt-token>
x-tenant-id: <your-tenant-uuid>
Content-Type: application/json
Idempotency-Key: <unique-key> // Recommended for POST/PATCH/DELETEProduction: https://api.eventzr.com/ads/v1
Staging: https://api.eventzr.com/ads/v1All responses use the standard EventZR envelope format.
{
"data": { ... },
"error": null,
"page": {
"next_cursor": "<opaque-cursor>",
"has_more": true,
"limit": 20
},
"meta": {
"request_id": "<uuid>"
}
}Create, manage, and control the lifecycle of advertising campaigns.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /ads/v1/campaigns | List campaigns with filters and pagination | Yes |
| POST | /ads/v1/campaigns | Create a new ad campaign | Yes |
| GET | /ads/v1/campaigns/:id | Get campaign by ID | Yes |
| PATCH | /ads/v1/campaigns/:id | Update campaign settings | Yes |
| DELETE | /ads/v1/campaigns/:id | Delete a campaign | Yes |
| POST | /ads/v1/campaigns/:id/launch | Launch a campaign (set status to active) | Yes |
| POST | /ads/v1/campaigns/:id/pause | Pause a running campaign | Yes |
| POST | /ads/v1/campaigns/:id/resume | Resume a paused campaign | Yes |
| POST | /ads/v1/campaigns/:id/clone | Clone campaign with all creatives | Yes |
Upload and manage creative assets (images, videos, HTML) attached to campaigns.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /ads/v1/creatives | List creatives with filters | Yes |
| POST | /ads/v1/creatives | Create a new creative asset | Yes |
| GET | /ads/v1/creatives/:id | Get creative by ID | Yes |
| PATCH | /ads/v1/creatives/:id | Update creative content or metadata | Yes |
| DELETE | /ads/v1/creatives/:id | Delete a creative | Yes |
| POST | /ads/v1/creatives/:id/approve | Approve creative for serving | Yes |
| POST | /ads/v1/creatives/:id/reject | Reject creative with reason | Yes |
Request ads for placement slots and track impressions and clicks. See the Ad Serving Integration Guide for full details.
| Method | Path | Description | Auth |
|---|---|---|---|
| POST | /ads/v1/serve | Request an ad for a placement slot | Yes |
| POST | /ads/v1/serve/batch | Request multiple ads in a single call | Yes |
| POST | /ads/v1/impressions | Track ad impression event | Yes |
| POST | /ads/v1/clicks | Track ad click event | Yes |
Track conversion events (purchases, signups, etc.) for campaign attribution and ROAS measurement.
| Method | Path | Description | Auth |
|---|---|---|---|
| POST | /ads/v1/conversions | Track a conversion event | Yes |
| GET | /ads/v1/conversions | List conversion events | Yes |
| POST | /ads/v1/conversions/batch | Track multiple conversions in batch | Yes |
Create and manage targeting audiences based on demographics, interests, behaviors, and retargeting rules. See the Retargeting Guide for pixel-based audiences.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /ads/v1/audiences | List audiences | Yes |
| POST | /ads/v1/audiences | Create a targeting audience | Yes |
| GET | /ads/v1/audiences/:id | Get audience details with size estimate | Yes |
| PATCH | /ads/v1/audiences/:id | Update audience criteria | Yes |
| DELETE | /ads/v1/audiences/:id | Delete an audience | Yes |
Access campaign and creative performance metrics, schedule automated reports, and export data.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /ads/v1/reports/campaigns/:id | Campaign performance report | Yes |
| GET | /ads/v1/reports/creatives/:id | Creative performance report | Yes |
| GET | /ads/v1/reports/overview | Account-level performance overview | Yes |
| POST | /ads/v1/reports/schedule | Schedule recurring report delivery | Yes |
| POST | /ads/v1/reports/export | Export report data as CSV or JSON | Yes |
Manage ad account funding, check balances, and retrieve invoices.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /ads/v1/billing/balance | Get current ad spend balance | Yes |
| POST | /ads/v1/billing/add-funds | Add funds to ad account | Yes |
| GET | /ads/v1/billing/invoices | List billing invoices | Yes |
| GET | /ads/v1/billing/invoices/:id | Get invoice details | Yes |
{
"name": "Summer Event Promo 2026",
"type": "display",
"budgetType": "daily",
"budgetAmount": 5000,
"currency": "USD",
"startDate": "2026-06-01T00:00:00Z",
"endDate": "2026-08-31T23:59:59Z",
"targetingAudienceId": "aud_abc123",
"bidStrategy": "maximize_clicks"
}{
"data": {
"id": "cmp_xyz789",
"name": "Summer Event Promo 2026",
"status": "draft",
"type": "display",
"budgetType": "daily",
"budgetAmount": 5000,
"currency": "USD",
"startDate": "2026-06-01T00:00:00Z",
"endDate": "2026-08-31T23:59:59Z",
"createdAt": "2026-03-09T10:00:00Z"
},
"meta": { "request_id": "req_abc123" }
}