Skip to main content
A campaign is the core unit of advertising in ENS Ads. When you call GET /api/v1/campaigns/fetch, the API returns an array of campaign objects that match the placement and targeting parameters you provide. Your platform is responsible for rendering each campaign in the correct location and reporting impressions and clicks back to the API.

​
Campaign object fields

Each campaign object returned by the API contains the following fields:
​
id
integer
required
Unique numeric identifier for the campaign. Use this value when tracking impressions and clicks.
​
title
string
required
The campaign’s display title, provided by the advertiser.
​
description
string
A short description of the campaign or offer.
​
category
string
The content category the campaign is associated with. See Targeting for the full list of supported categories.
​
destinationUrl
string
required
The URL users are sent to when they click the ad. Always use this value as the click target — do not modify or wrap it without confirming with the advertiser.
​
status
string
required
Current state of the campaign. See campaign statuses below.
​
createdAt
string
required
ISO 8601 timestamp indicating when the campaign was created.

​
Sample campaign object

The following is an example campaign object as returned inside the data array of a successful response: 
{
  "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"
}
The full response envelope wraps this array in a data key and includes a count field: 
{
  "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
}

​
Campaign statuses

The status field indicates whether a campaign is currently active and eligible to be displayed.
The campaign is active and should be displayed. All campaigns returned by the fetch endpoint have running status — the API only returns campaigns that are eligible to be served.
The API filters out inactive campaigns server-side. You do not need to check status yourself before rendering — any campaign in the response is ready to display.

​
How campaigns are matched to your request

When you call GET /api/v1/campaigns/fetch, the API matches campaigns against three dimensions:
  • Placement — the specific slot on your page where the ad will appear (required)
  • Location — the user’s country, supplied as an ISO 3166-1 alpha-2 code (optional but recommended)
  • Device — the user’s device type: mobile, desktop, or tablet (optional but recommended)
Passing all three parameters gives the API the most context to return well-matched campaigns. The limit parameter (default 10, max 100) controls how many campaigns are returned in a single call.

​
Content categories

Campaigns are associated with one of the following content categories. You can use the category field on each campaign object to filter or style ads appropriately for your content:
Category
technology
business
sports
entertainment
health
politics
science
lifestyle
travel
If your platform serves content in a specific category (for example, a sports news site), pass the matching category context when fetching campaigns. This improves ad relevance for your users and increases engagement for advertisers.