Skip to main content
Integrating ENS Ads into your platform involves five sequential steps: fetching campaigns from the API, validating that the returned campaigns match your user’s context, rendering them in the correct placement, and then reporting impressions and clicks back to the API. Each step is required for accurate delivery and performance tracking.
Impression and click tracking must always be done server-side. Your API key must never appear in client-side or user-facing code. Exposing it in the browser allows anyone to make requests on your behalf.
1

Fetch available campaigns

Call GET /api/v1/campaigns/fetch with a placement value and any optional targeting parameters. The placement parameter is required — the API will return a 400 error without it. Pass location (ISO 3166-1 alpha-2 country code) and device (mobile, desktop, or tablet) to narrow results to campaigns targeted at your user’s context.
curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?placement=header_banner&location=US&device=mobile" \
  -H "Authorization: Bearer YOUR_API_KEY"
A successful response returns a data array of campaign objects, each with an id, title, description, category, destinationUrl, and status.
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "title": "Summer Sale Campaign",
      "description": "Limited time offer",
      "category": "retail",
      "destinationUrl": "https://example.com/summer",
      "status": "running",
      "createdAt": "2026-04-17T00:00:00Z"
    }
  ],
  "count": 1
}
2

Validate campaign targeting

Before rendering, verify that the campaigns returned actually match your user’s current context. Check that the campaign’s status is "running" and that any location, device, or category constraints align with what you passed in the request. Campaigns returned by the API are already filtered server-side, but validating on your side adds a second layer of assurance and protects against misconfiguration.
Always confirm that the campaigns returned match the expected placement. A campaign intended for sidebar_top should never be rendered in header_banner. Mismatched placements violate advertiser targeting rules and can affect billing accuracy.
3

Display in the correct placement

Render each campaign in the placement slot it was fetched for. ENS Ads supports a range of placement identifiers — for example, header_banner for a full-width top-of-page banner, article_inline for content embedded within articles, and feed_sponsored for native ads in content feeds. Use the campaign’s destinationUrl as the link target and its title and description for display content.
4

Track impressions

Call POST /api/v1/campaigns/impression as soon as the campaign is visible to the user. Include the campaignId from the fetched campaign object, the placement slot, and the same location and device values used when fetching.
curl -X POST "https://ads.enslive.live/api/v1/campaigns/impression" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": 1,
    "placement": "header_banner",
    "location": "US",
    "device": "mobile"
  }'
A successful response confirms tracking:
{
  "status": "success",
  "message": "Impression tracked successfully"
}
5

Track clicks

Call POST /api/v1/campaigns/click when the user interacts with the campaign — typically when they click the ad link. Use the same campaignId, placement, location, and device values as the impression call.
curl -X POST "https://ads.enslive.live/api/v1/campaigns/click" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": 1,
    "placement": "header_banner",
    "location": "US",
    "device": "mobile"
  }'
A successful response confirms tracking:
{
  "status": "success",
  "message": "Click tracked successfully"
}